{"title":"메모리 모델","slug":"memory-model","category":"concepts","summary":"메모리 구조화 방식 — 카테고리, 키, 태그, 우선순위, 소스, 검증.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":655,"read_minutes":3,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 메모리 모델\n\nSynapse의 메모리 모델은 LLM 에이전트를 위해 설계되었습니다 — 신뢰할 수\n있는 회상을 위해 충분히 구조화되어 있으면서, 모든 도메인에 대해 충분히\n유연합니다.\n\n## 메모리 구조\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## 필드\n\n| 필드 | 타입 | 필수 | 설명 |\n|-------|------|----------|-------------|\n| `id` | string | 자동 | 고유 ID (mem_xxx) |\n| `category` | enum | ✅ | 8개 카테고리 중 하나 |\n| `key` | string | ✅ | 안정적 식별자 (업데이트에 사용) |\n| `content` | string | ✅ | 메모리 콘텐츠 (모든 텍스트) |\n| `tags` | string[] | – | 검색 및 필터링용 |\n| `priority` | enum | – | low, normal, high, critical (기본값: normal) |\n| `source` | enum | 자동 | user, agent (누가 저장했는지) |\n| `verified` | bool | 자동 | 사람이 검증했는지 여부 |\n| `confidence` | float | – | 0.0 ~ 1.0 (기본값: user 1.0, agent 0.7) |\n| `expires_at` | timestamp | – | 이 메모리를 잊을 시점 |\n| `mind_id` | string | 자동 | 이 메모리를 소유한 마인드 |\n| `created_at` | timestamp | 자동 | 최초 저장 시각 |\n| `updated_at` | timestamp | 자동 | 최종 수정 시각 |\n\n## 카테고리\n\n8개 카테고리가 일반적인 LLM 에이전트 사용 사례를 다룹니다:\n\n| 카테고리 | 용도 | 예시 콘텐츠 |\n|----------|---------|-----------------|\n| `identity` | 사용자가 누구인지 | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | 사용자 선호도 | \"Prefers concise technical responses\" |\n| `fact` | 검증 가능한 사실 | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | 프로젝트 상태 | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | 사용자 기술 | \"Advanced Python, 10+ years\" |\n| `mistake` | 과거 오류 | \"Forgot to bump npm version — CI failed\" |\n| `context` | 세션 컨텍스트 | \"Currently reviewing PR #42\" |\n| `note` | 기타 노트 | \"Try Redis for caching next sprint\" |\n\n## 키: 안정적 식별자\n\n`key` 필드는 중요합니다 — 중복을 만들지 않고 메모리를 업데이트하는\n방법입니다.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**키 규칙:**\n\n- (category, mind) 내에서 고유해야 함\n- `snake_case` 사용\n- 명확성을 위해 카테고리로 접두사: `preference_communication`, `mistake_npm_version`\n- 안정적으로 유지 — 생성 후 키를 변경하지 마십시오\n\n## 태그: 검색용\n\n태그를 사용하면 빠른 필터링과 검색이 가능합니다:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**태그 모범 사례:**\n\n- 메모리당 2-5개 태그 (과도한 태깅 금지)\n- 일관성을 위해 소문자 사용\n- 프로젝트 이름, 주제, 기술 사용\n- 태그는 대소문자 구분 안 함\n\n## 우선순위 수준\n\n| 우선순위 | 사용 시기 | 회상 동작 |\n|----------|-------------|-----------------|\n| `critical` | 정체성, 법적, 되돌릴 수 없는 것 | 항상 회상 최상단 |\n| `high` | 활성 프로젝트, 핵심 선호도 | 회상에서 두드러짐 |\n| `normal` | 대부분의 메모리 (기본값) | 표준 회상 순서 |\n| `low` | 일시적, 알면 좋음 | 요약될 수 있음 |\n\n`/memory/recall`은 우선순위 (critical 먼저)로 정렬한 후 최신순으로 정렬합니다.\n\n## 소스: User vs Agent\n\n메모리에는 `source` 태그가 지정됩니다:\n\n- `user` — 사람이 저장 (JWT 또는 human UI를 통해)\n- `agent` — LLM 에이전트가 저장 (Mind Key를 통해)\n\n이는 다음에 영향을 미칩니다:\n\n- **검증**: `user` 메모리는 자동 검증, `agent` 메모리는 검증 안 됨\n- **신뢰도**: `user` 기본값 1.0, `agent` 0.7\n- **회상**: `/memory/recall`은 미검증 메모리에 \"(unverified)\" 표시\n\n> [!NOTE]\n> `agent` 소스 메모리는 적절한 회의적으로 취급하십시오. 사용자가 직접\n> 명시한 것이 아니라 추론되거나 가정된 것일 수 있습니다.\n\n## 검증\n\n`verified` 플래그는 사람이 메모리를 확인했음을 나타냅니다:\n\n- `user` 메모리: 자동 검증 (`true`)\n- `agent` 메모리: 기본 미검증 (`false`)\n\n다음을 통해 메모리 검증:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> 검증에는 Mind Key (에이전트 인증)가 아닌 JWT (사람 인증)가 필요합니다.\n> 이는 사람만 메모리를 검증됨으로 표시할 수 있도록 보장합니다.\n\n## 신뢰도\n\n`confidence` 필드 (0.0 ~ 1.0)는 메모리의 신뢰도를 나타냅니다:\n\n- 1.0 — 사용자가 직접 명시\n- 0.7 — 에이전트가 추론\n- 0.5 — 불확실, 검증 필요\n- 0.0 — 명시적으로 의심됨\n\n저장 시 신뢰도 설정:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## 만료\n\n시간에 민감한 메모리에 `expires_at` 설정:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\n만료된 메모리는 `/memory/recall`에서 반환되지 않습니다 (DB에는 여전히 존재).\n곧 만료되는 메모리를 보려면 `/memory/expiring?within=7d`를 사용하십시오.\n\n## 메모리 라이프사이클\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## 회상 동작\n\n`GET /memory/recall`은 LLM 컨텍스트에 최적화된 일반 텍스트 요약을 반환합니다:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- 우선순위 (critical → low)로 정렬, 그 다음 최신순\n- 미검증 메모리는 `[unverified]`로 표시\n- 컨텍스트를 위해 태그 포함\n- 일반 텍스트 (JSON 파싱 불필요)\n\n## 다음 단계\n\n- [Memory API](/docs/api/memory)\n- [메모리 모범 사례](/docs/guides/memory-best-practices)\n- [FTS5 검색](/docs/concepts/fts5-search)\n","content_html":"

메모리 모델

\n

Synapse의 메모리 모델은 LLM 에이전트를 위해 설계되었습니다 — 신뢰할 수\n있는 회상을 위해 충분히 구조화되어 있으면서, 모든 도메인에 대해 충분히\n유연합니다.

\n

메모리 구조

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

필드

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
필드타입필수설명
idstring자동고유 ID (mem_xxx)
categoryenum✅8개 카테고리 중 하나
keystring✅안정적 식별자 (업데이트에 사용)
contentstring✅메모리 콘텐츠 (모든 텍스트)
tagsstring[]–검색 및 필터링용
priorityenum–low, normal, high, critical (기본값: normal)
sourceenum자동user, agent (누가 저장했는지)
verifiedbool자동사람이 검증했는지 여부
confidencefloat–0.0 ~ 1.0 (기본값: user 1.0, agent 0.7)
expires_attimestamp–이 메모리를 잊을 시점
mind_idstring자동이 메모리를 소유한 마인드
created_attimestamp자동최초 저장 시각
updated_attimestamp자동최종 수정 시각
\n

카테고리

\n

8개 카테고리가 일반적인 LLM 에이전트 사용 사례를 다룹니다:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
카테고리용도예시 콘텐츠
identity사용자가 누구인지"User is Michael Schäfer, software engineer in Berlin"
preference사용자 선호도"Prefers concise technical responses"
fact검증 가능한 사실"Office is in Berlin, timezone Europe/Berlin"
project프로젝트 상태"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skill사용자 기술"Advanced Python, 10+ years"
mistake과거 오류"Forgot to bump npm version — CI failed"
context세션 컨텍스트"Currently reviewing PR #42"
note기타 노트"Try Redis for caching next sprint"
\n

키: 안정적 식별자

\n

key 필드는 중요합니다 — 중복을 만들지 않고 메모리를 업데이트하는\n방법입니다.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

키 규칙:

\n\n

태그: 검색용

\n

태그를 사용하면 빠른 필터링과 검색이 가능합니다:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

태그 모범 사례:

\n\n

우선순위 수준

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
우선순위사용 시기회상 동작
critical정체성, 법적, 되돌릴 수 없는 것항상 회상 최상단
high활성 프로젝트, 핵심 선호도회상에서 두드러짐
normal대부분의 메모리 (기본값)표준 회상 순서
low일시적, 알면 좋음요약될 수 있음
\n

/memory/recall은 우선순위 (critical 먼저)로 정렬한 후 최신순으로 정렬합니다.

\n

소스: User vs Agent

\n

메모리에는 source 태그가 지정됩니다:

\n\n

이는 다음에 영향을 미칩니다:

\n\n
`agent` 소스 메모리는 적절한 회의적으로 취급하십시오. 사용자가 직접\n명시한 것이 아니라 추론되거나 가정된 것일 수 있습니다.

검증

\n

verified 플래그는 사람이 메모리를 확인했음을 나타냅니다:

\n\n

다음을 통해 메모리 검증:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
검증에는 Mind Key (에이전트 인증)가 아닌 JWT (사람 인증)가 필요합니다.\n이는 사람만 메모리를 검증됨으로 표시할 수 있도록 보장합니다.

신뢰도

\n

confidence 필드 (0.0 ~ 1.0)는 메모리의 신뢰도를 나타냅니다:

\n\n

저장 시 신뢰도 설정:

\n
{\n  "category": "preference",\n  "key": "prefers_dark_mode",\n  "content": "User seems to prefer dark mode (based on their IDE screenshots)",\n  "confidence": 0.5,\n  "source": "agent"\n}

만료

\n

시간에 민감한 메모리에 expires_at 설정:

\n
{\n  "category": "context",\n  "key": "current_meeting_topic",\n  "content": "Discussing Q3 roadmap",\n  "expires_at": "2026-06-28T00:00:00Z"\n}

만료된 메모리는 /memory/recall에서 반환되지 않습니다 (DB에는 여전히 존재).\n곧 만료되는 메모리를 보려면 /memory/expiring?within=7d를 사용하십시오.

\n

메모리 라이프사이클

\n
                  ┌─────────────────┐\n                  │     Create      │\n                  │  POST /memory   │\n                  └────────┬────────┘\n                           │\n                           ▼\n                  ┌─────────────────┐\n                  │     Active      │ ◀──── PUT /memory/:id (update)\n                  │  (in recall)    │\n                  └────────┬────────┘\n                           │\n              ┌────────────┼────────────┐\n              │            │            │\n              ▼            ▼            ▼\n        ┌──────────┐ ┌──────────┐ ┌──────────┐\n        │ Expired  │ │ Verified │ │ Deleted  │\n        │ (in DB)  │ │ (flag)   │ │ (gone)   │\n        └──────────┘ └──────────┘ └──────────┘

회상 동작

\n

GET /memory/recall은 LLM 컨텍스트에 최적화된 일반 텍스트 요약을 반환합니다:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

다음 단계

\n\n","urls":{"html":"/docs/concepts/memory-model","text":"/docs/concepts/memory-model?format=text","json":"/docs/concepts/memory-model?format=json","llm":"/docs/concepts/memory-model?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}