# Memory API
SUMMARY: 22개 메모리 엔드포인트에 대한 완전한 참조: 저장, 회상, 검색, 의미론적 검색, 동기화, 감사 등.

KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)

Memory API
Memory API는 Synapse의 핵심입니다. 구조화된 메모리를 저장, 검색, 검색 및
관리하기 위한 22개의 엔드포인트를 제공합니다. 모든 엔드포인트는 인증을 위해
Mind Key가 필요합니다.
> [!CRITICAL]
> 모든 세션 시작 시 을 반드시 호출하십시오. 이것이
> 이전 세션의 컨텍스트를 재구성하는 유일한 방법입니다.
카테고리
메모리는 8개 카테고리로 구성됩니다:
| 카테고리 | 사용 사례 |
|----------|----------|
|  | 사용자 이름, 역할, 연락처 정보, 자신에 대한 선호도 |
|  | 좋아함, 싫어함, 작업 스타일, 커뮤니케이션 선호도 |
|  | 검증 가능한 사실 (프로젝트 세부 정보, 날짜, URL) |
|  | 프로젝트 상태, 마일스톤, 아키텍처 |
|  | 사용자가 잘하는 것 |
|  | 과거 오류 — 반복 방지 |
|  | 세션 관련 컨텍스트 |
|  | 기타 노트 |
우선순위
-  — 알면 좋음
-  — 기본값
-  — 중요
-  — 절대 잊으면 안 됨 (사용자 정체성, 법적 정보)
핵심 엔드포인트
GET /memory/recall
모든 메모리를 LLM에 최적화된 일반 텍스트로 반환합니다. 모든 세션 시작 시
호출하십시오.
[CODE BLOCK]
응답 (text/plain):
[CODE BLOCK]
POST /memory
새 메모리를 저장하거나 기존 메모리를 업데이트합니다 (동일한 카테고리 + 키 = 업데이트).
[CODE BLOCK]
응답: 
GET /memory
선택적 필터로 메모리를 나열합니다.
[CODE BLOCK]
PUT /memory/:id
ID로 특정 메모리를 업데이트합니다.
[CODE BLOCK]
DELETE /memory/:id
단일 메모리를 삭제합니다.
[CODE BLOCK]
검색 엔드포인트
GET /memory/search
FTS5를 사용한 전문 검색입니다.
[CODE BLOCK]
FTS5 구문:
- 여러 단어 = AND: 
- 구문: 
- 접두사: 
- 불린: 
- 제외: 
GET /memory/semantic-search
임베딩을 사용한 개념 검색입니다 (FTS5보다 느리지만 의미를 이해함).
[CODE BLOCK]
키워드가 일치하지 않더라도 쿼리와 의미론적으로 유사한 메모리를
반환합니다. X가 다르게 설명된 "X에 대한 메모리 찾기"에 유용합니다.
GET /memory/by-tag
태그로 메모리를 나열합니다.
[CODE BLOCK]
GET /memory/related/:id
특정 메모리와 관련된 메모리를 찾습니다 (공유 태그 기준).
[CODE BLOCK]
동기화 및 Diff
GET /memory/diff
증분 동기화 — 타임스탬프 이후 변경된 메모리를 반환합니다.
[CODE BLOCK]
응답: 
POST /memory/sync
다른 인스턴스에서 diff를 적용합니다 (자체 호스팅 동기화용).
[CODE BLOCK]
대량 작업
POST /memory/bulk-delete
ID로 여러 메모리를 삭제합니다.
[CODE BLOCK]
POST /memory/embed-batch
아직 임베딩이 없는 메모리의 임베딩을 생성합니다 (의미론적 검색용).
[CODE BLOCK]
GET /memory/embed-batch-status
임베딩 생성 진행 상황을 확인합니다.
[CODE BLOCK]
검증
메모리에는  플래그가 있습니다. 에이전트가 저장한 메모리는
기본적으로 미검증()이며, 사람이 저장한 메모리는
검증됨()입니다.
POST /memory/verify
메모리를 검증됨으로 표시합니다 (Mind Key가 아닌 JWT 필요).
[CODE BLOCK]
POST /memory/unverify
메모리를 미검증으로 표시합니다 (JWT 필요).
[CODE BLOCK]
GET /memory/unverified
사용자 검증 대기 중인 메모리를 나열합니다.
[CODE BLOCK]
통계 및 감사
GET /memory/stats
현재 마인드에 대한 집계 통계입니다.
[CODE BLOCK]
반환: 
GET /memory/audit
상태를 변경하는 모든 작업의 감사 로그입니다.
[CODE BLOCK]
GET /memory/contradictions
저장된 메모리의 잠재적 모순을 감지합니다.
[CODE BLOCK]
GET /memory/expiring
만료일이 다가오는 메모리를 나열합니다.
[CODE BLOCK]
상태 및 내보내기
GET /memory/health
메모리 시스템의 빠른 상태 확인입니다.
[CODE BLOCK]
GET /memory/mind-export
모든 메모리의 전체 JSON 내보내기입니다 (백업용).
[CODE BLOCK]
POST /memory/compact
유사한 메모리를 압축합니다 (자동 요약).
[CODE BLOCK]
다음 단계
- LLM을 위한 빠른 시작
- 메모리 모범 사례
- FTS5 검색
- 의미론적 검색