Memory API

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

카테고리

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

우선순위

• low — 알면 좋음
• normal — 기본값
• high — 중요
• critical — 절대 잊으면 안 됨 (사용자 정체성, 법적 정보)

핵심 엔드포인트

GET /memory/recall

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

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

응답 (text/plain):

Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...

POST /memory

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

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

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

GET /memory

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

# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

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

PUT /memory/:id

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

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

DELETE /memory/:id

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

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

검색 엔드포인트

GET /memory/search

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

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

FTS5 구문:

• 여러 단어 = AND: docker swarm
• 구문: "docker swarm"
• 접두사: docker*
• 불린: docker OR kubernetes
• 제외: docker -swarm

GET /memory/semantic-search

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

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

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

GET /memory/by-tag

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

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

GET /memory/related/:id

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

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

동기화 및 Diff

GET /memory/diff

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

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

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

POST /memory/sync

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

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

대량 작업

POST /memory/bulk-delete

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

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

POST /memory/embed-batch

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

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

GET /memory/embed-batch-status

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

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

검증

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

POST /memory/verify

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

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

POST /memory/unverify

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

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

GET /memory/unverified

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

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

통계 및 감사

GET /memory/stats

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

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

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

GET /memory/audit

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

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

GET /memory/contradictions

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

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

GET /memory/expiring

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

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

상태 및 내보내기

GET /memory/health

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

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

GET /memory/mind-export

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

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

POST /memory/compact

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

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

다음 단계

• LLM을 위한 빠른 시작
• 메모리 모범 사례
• FTS5 검색
• 의미론적 검색