{"title":"Memory API","slug":"memory","category":"api","summary":"22개 메모리 엔드포인트에 대한 완전한 참조: 저장, 회상, 검색, 의미론적 검색, 동기화, 감사 등.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":462,"read_minutes":2,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# Memory API\n\nMemory API는 Synapse의 핵심입니다. 구조화된 메모리를 저장, 검색, 검색 및\n관리하기 위한 22개의 엔드포인트를 제공합니다. 모든 엔드포인트는 인증을 위해\nMind Key가 필요합니다.\n\n> [!CRITICAL]\n> **모든 세션 시작 시 `GET /memory/recall`을 반드시 호출하십시오.** 이것이\n> 이전 세션의 컨텍스트를 재구성하는 유일한 방법입니다.\n\n## 카테고리\n\n메모리는 8개 카테고리로 구성됩니다:\n\n| 카테고리 | 사용 사례 |\n|----------|----------|\n| `identity` | 사용자 이름, 역할, 연락처 정보, 자신에 대한 선호도 |\n| `preference` | 좋아함, 싫어함, 작업 스타일, 커뮤니케이션 선호도 |\n| `fact` | 검증 가능한 사실 (프로젝트 세부 정보, 날짜, URL) |\n| `project` | 프로젝트 상태, 마일스톤, 아키텍처 |\n| `skill` | 사용자가 잘하는 것 |\n| `mistake` | 과거 오류 — 반복 방지 |\n| `context` | 세션 관련 컨텍스트 |\n| `note` | 기타 노트 |\n\n## 우선순위\n\n- `low` — 알면 좋음\n- `normal` — 기본값\n- `high` — 중요\n- `critical` — 절대 잊으면 안 됨 (사용자 정체성, 법적 정보)\n\n## 핵심 엔드포인트\n\n### GET /memory/recall\n\n모든 메모리를 LLM에 최적화된 일반 텍스트로 반환합니다. 모든 세션 시작 시\n호출하십시오.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n응답 (text/plain):\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\n새 메모리를 저장하거나 기존 메모리를 업데이트합니다 (동일한 카테고리 + 키 = 업데이트).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\n응답: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\n선택적 필터로 메모리를 나열합니다.\n\n```bash\n# All memories (JSON)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# Filter by category\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# Filter by tag\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\nID로 특정 메모리를 업데이트합니다.\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\n단일 메모리를 삭제합니다.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## 검색 엔드포인트\n\n### GET /memory/search\n\nFTS5를 사용한 전문 검색입니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nFTS5 구문:\n\n- 여러 단어 = AND: `docker swarm`\n- 구문: `\"docker swarm\"`\n- 접두사: `docker*`\n- 불린: `docker OR kubernetes`\n- 제외: `docker -swarm`\n\n### GET /memory/semantic-search\n\n임베딩을 사용한 개념 검색입니다 (FTS5보다 느리지만 의미를 이해함).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\n키워드가 일치하지 않더라도 쿼리와 의미론적으로 유사한 메모리를\n반환합니다. X가 다르게 설명된 \"X에 대한 메모리 찾기\"에 유용합니다.\n\n### GET /memory/by-tag\n\n태그로 메모리를 나열합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\n특정 메모리와 관련된 메모리를 찾습니다 (공유 태그 기준).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## 동기화 및 Diff\n\n### GET /memory/diff\n\n증분 동기화 — 타임스탬프 이후 변경된 메모리를 반환합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\n응답: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\n다른 인스턴스에서 diff를 적용합니다 (자체 호스팅 동기화용).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## 대량 작업\n\n### POST /memory/bulk-delete\n\nID로 여러 메모리를 삭제합니다.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\n아직 임베딩이 없는 메모리의 임베딩을 생성합니다 (의미론적 검색용).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\n임베딩 생성 진행 상황을 확인합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## 검증\n\n메모리에는 `verified` 플래그가 있습니다. 에이전트가 저장한 메모리는\n기본적으로 미검증(`source=agent`)이며, 사람이 저장한 메모리는\n검증됨(`source=user`)입니다.\n\n### POST /memory/verify\n\n메모리를 검증됨으로 표시합니다 (Mind Key가 아닌 JWT 필요).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\n메모리를 미검증으로 표시합니다 (JWT 필요).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\n사용자 검증 대기 중인 메모리를 나열합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## 통계 및 감사\n\n### GET /memory/stats\n\n현재 마인드에 대한 집계 통계입니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\n반환: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\n상태를 변경하는 모든 작업의 감사 로그입니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\n저장된 메모리의 잠재적 모순을 감지합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\n만료일이 다가오는 메모리를 나열합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## 상태 및 내보내기\n\n### GET /memory/health\n\n메모리 시스템의 빠른 상태 확인입니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\n모든 메모리의 전체 JSON 내보내기입니다 (백업용).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\n유사한 메모리를 압축합니다 (자동 요약).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## 다음 단계\n\n- [LLM을 위한 빠른 시작](/docs/getting-started/quick-start-llm)\n- [메모리 모범 사례](/docs/guides/memory-best-practices)\n- [FTS5 검색](/docs/concepts/fts5-search)\n- [의미론적 검색](/docs/concepts/semantic-search)\n","content_html":"

Memory API

\n

Memory API는 Synapse의 핵심입니다. 구조화된 메모리를 저장, 검색, 검색 및\n관리하기 위한 22개의 엔드포인트를 제공합니다. 모든 엔드포인트는 인증을 위해\nMind Key가 필요합니다.

\n
**모든 세션 시작 시 `GET /memory/recall`을 반드시 호출하십시오.** 이것이\n이전 세션의 컨텍스트를 재구성하는 유일한 방법입니다.

카테고리

\n

메모리는 8개 카테고리로 구성됩니다:

\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사용자 이름, 역할, 연락처 정보, 자신에 대한 선호도
preference좋아함, 싫어함, 작업 스타일, 커뮤니케이션 선호도
fact검증 가능한 사실 (프로젝트 세부 정보, 날짜, URL)
project프로젝트 상태, 마일스톤, 아키텍처
skill사용자가 잘하는 것
mistake과거 오류 — 반복 방지
context세션 관련 컨텍스트
note기타 노트
\n

우선순위

\n\n

핵심 엔드포인트

\n

GET /memory/recall

\n

모든 메모리를 LLM에 최적화된 일반 텍스트로 반환합니다. 모든 세션 시작 시\n호출하십시오.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/recall

응답 (text/plain):

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

새 메모리를 저장하거나 기존 메모리를 업데이트합니다 (동일한 카테고리 + 키 = 업데이트).

\n
curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "category": "fact",\n    "key": "user_name",\n    "content": "The user's name is Michael Schäfer",\n    "tags": ["person", "identity"],\n    "priority": "critical"\n  }'

응답: { "id": "mem_001", "status": "stored" }

\n

GET /memory

\n

선택적 필터로 메모리를 나열합니다.

\n
# All memories (JSON)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# Filter by category\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# Filter by tag\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

ID로 특정 메모리를 업데이트합니다.

\n
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Updated content", "priority": "high"}'

DELETE /memory/:id

\n

단일 메모리를 삭제합니다.

\n
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/mem_001

검색 엔드포인트

\n

GET /memory/search

\n

FTS5를 사용한 전문 검색입니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"

FTS5 구문:

\n\n

GET /memory/semantic-search

\n

임베딩을 사용한 개념 검색입니다 (FTS5보다 느리지만 의미를 이해함).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

키워드가 일치하지 않더라도 쿼리와 의미론적으로 유사한 메모리를\n반환합니다. X가 다르게 설명된 "X에 대한 메모리 찾기"에 유용합니다.

\n

GET /memory/by-tag

\n

태그로 메모리를 나열합니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"

GET /memory/related/:id

\n

특정 메모리와 관련된 메모리를 찾습니다 (공유 태그 기준).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/related/mem_001

동기화 및 Diff

\n

GET /memory/diff

\n

증분 동기화 — 타임스탬프 이후 변경된 메모리를 반환합니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/diff?since=1700000000"

응답: { "added": [...], "updated": [...], "deleted": [...] }

\n

POST /memory/sync

\n

다른 인스턴스에서 diff를 적용합니다 (자체 호스팅 동기화용).

\n
curl -X POST https://synapse.schaefer.zone/memory/sync \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"added": [...], "updated": [...], "deleted": [...]}'

대량 작업

\n

POST /memory/bulk-delete

\n

ID로 여러 메모리를 삭제합니다.

\n
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

POST /memory/embed-batch

\n

아직 임베딩이 없는 메모리의 임베딩을 생성합니다 (의미론적 검색용).

\n
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'

GET /memory/embed-batch-status

\n

임베딩 생성 진행 상황을 확인합니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

검증

\n

메모리에는 verified 플래그가 있습니다. 에이전트가 저장한 메모리는\n기본적으로 미검증(source=agent)이며, 사람이 저장한 메모리는\n검증됨(source=user)입니다.

\n

POST /memory/verify

\n

메모리를 검증됨으로 표시합니다 (Mind Key가 아닌 JWT 필요).

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"

POST /memory/unverify

\n

메모리를 미검증으로 표시합니다 (JWT 필요).

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n  -H "Authorization: Bearer YOUR_JWT"

GET /memory/unverified

\n

사용자 검증 대기 중인 메모리를 나열합니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/unverified?limit=100"

통계 및 감사

\n

GET /memory/stats

\n

현재 마인드에 대한 집계 통계입니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/stats

반환: { "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }

\n

GET /memory/audit

\n

상태를 변경하는 모든 작업의 감사 로그입니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"

GET /memory/contradictions

\n

저장된 메모리의 잠재적 모순을 감지합니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/contradictions

GET /memory/expiring

\n

만료일이 다가오는 메모리를 나열합니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/expiring?within=7d"

상태 및 내보내기

\n

GET /memory/health

\n

메모리 시스템의 빠른 상태 확인입니다.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/health

GET /memory/mind-export

\n

모든 메모리의 전체 JSON 내보내기입니다 (백업용).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/mind-export > backup.json

POST /memory/compact

\n

유사한 메모리를 압축합니다 (자동 요약).

\n
curl -X POST https://synapse.schaefer.zone/memory/compact \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"dry_run": true}'

다음 단계

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