{"title":"Memory API","slug":"memory","category":"api","summary":"Complete reference for the 22 memory endpoints: store, recall, search, semantic search, sync, audit, and more.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":516,"read_minutes":3,"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":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Memory API\n\nThe Memory API is the heart of Synapse. It provides 22 endpoints for storing,\nretrieving, searching, and managing structured memories. All endpoints require\na Mind Key for authentication.\n\n> [!CRITICAL]\n> **Always call `GET /memory/recall` at the start of every session.** This is\n> the only way to rebuild context from previous sessions.\n\n## Categories\n\nMemories are organized into 8 categories:\n\n| Category | Use Case |\n|----------|----------|\n| `identity` | User name, role, contact info, preferences about self |\n| `preference` | Likes, dislikes, working style, communication prefs |\n| `fact` | Verifiable facts (project details, dates, URLs) |\n| `project` | Project status, milestones, architecture |\n| `skill` | Things the user is good at |\n| `mistake` | Past errors — avoid repeating |\n| `context` | Session-relevant context |\n| `note` | Misc notes |\n\n## Priorities\n\n- `low` — nice to know\n- `normal` — default\n- `high` — important\n- `critical` — must never forget (user identity, legal info)\n\n## Core Endpoints\n\n### GET /memory/recall\n\nReturns ALL memories as LLM-optimized plain text. Call this at every session start.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\nResponse (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\nStore a new memory or update an existing one (same category + key = update).\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\nResponse: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\nList memories with optional filters.\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\nUpdate a specific memory by ID.\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\nDelete a single memory.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Search Endpoints\n\n### GET /memory/search\n\nFull-text search using FTS5.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nFTS5 syntax:\n\n- Multiple words = AND: `docker swarm`\n- Phrase: `\"docker swarm\"`\n- Prefix: `docker*`\n- Boolean: `docker OR kubernetes`\n- Exclude: `docker -swarm`\n\n### GET /memory/semantic-search\n\nConceptual search using embeddings (slower than FTS5 but understands meaning).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nReturns memories that are semantically similar to the query, even if no keywords\nmatch. Useful for \"find memories about X\" where X is described differently.\n\n### GET /memory/by-tag\n\nList memories by tag.\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\nFind memories related to a specific memory (via shared tags).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## Sync & Diff\n\n### GET /memory/diff\n\nIncremental sync — returns memories changed since a timestamp.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\nResponse: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\nApply a diff from another instance (for self-hosted sync).\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## Bulk Operations\n\n### POST /memory/bulk-delete\n\nDelete multiple memories by ID.\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\nGenerate embeddings for memories that don't have them yet (for semantic search).\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\nCheck embedding generation progress.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Verification\n\nMemories have a `verified` flag. Agent-stored memories default to unverified\n(`source=agent`); human-stored memories are verified (`source=user`).\n\n### POST /memory/verify\n\nMark a memory as verified (requires JWT, not Mind Key).\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\nMark a memory as unverified (requires 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\nList memories awaiting human verification.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## Statistics & Audit\n\n### GET /memory/stats\n\nAggregate statistics for the current mind.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\nReturns: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\nAudit log of all state-changing operations.\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\nDetect potential contradictions in stored memories.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\nList memories with expiry dates approaching.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## Health & Export\n\n### GET /memory/health\n\nQuick health check for memory system.\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\nFull JSON export of all memories (for backup).\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\nCompact similar memories (auto-summarization).\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## Next Steps\n\n- [Quick Start for LLMs](/docs/getting-started/quick-start-llm)\n- [Memory Best Practices](/docs/guides/memory-best-practices)\n- [FTS5 Search](/docs/concepts/fts5-search)\n- [Semantic Search](/docs/concepts/semantic-search)\n","content_html":"

Memory API

\n

The Memory API is the heart of Synapse. It provides 22 endpoints for storing,\nretrieving, searching, and managing structured memories. All endpoints require\na Mind Key for authentication.

\n
**Always call `GET /memory/recall` at the start of every session.** This is\nthe only way to rebuild context from previous sessions.

Categories

\n

Memories are organized into 8 categories:

\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
CategoryUse Case
identityUser name, role, contact info, preferences about self
preferenceLikes, dislikes, working style, communication prefs
factVerifiable facts (project details, dates, URLs)
projectProject status, milestones, architecture
skillThings the user is good at
mistakePast errors — avoid repeating
contextSession-relevant context
noteMisc notes
\n

Priorities

\n\n

Core Endpoints

\n

GET /memory/recall

\n

Returns ALL memories as LLM-optimized plain text. Call this at every session start.

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

Response (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

Store a new memory or update an existing one (same category + key = update).

\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  }'

Response: { "id": "mem_001", "status": "stored" }

\n

GET /memory

\n

List memories with optional filters.

\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

Update a specific memory by 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

Delete a single memory.

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

Search Endpoints

\n

GET /memory/search

\n

Full-text search using FTS5.

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

FTS5 syntax:

\n\n

GET /memory/semantic-search

\n

Conceptual search using embeddings (slower than FTS5 but understands meaning).

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

Returns memories that are semantically similar to the query, even if no keywords\nmatch. Useful for "find memories about X" where X is described differently.

\n

GET /memory/by-tag

\n

List memories by tag.

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

GET /memory/related/:id

\n

Find memories related to a specific memory (via shared tags).

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

Sync & Diff

\n

GET /memory/diff

\n

Incremental sync — returns memories changed since a timestamp.

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

Response: { "added": [...], "updated": [...], "deleted": [...] }

\n

POST /memory/sync

\n

Apply a diff from another instance (for self-hosted sync).

\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": [...]}'

Bulk Operations

\n

POST /memory/bulk-delete

\n

Delete multiple memories by 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

Generate embeddings for memories that don't have them yet (for semantic search).

\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

Check embedding generation progress.

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

Verification

\n

Memories have a verified flag. Agent-stored memories default to unverified\n(source=agent); human-stored memories are verified (source=user).

\n

POST /memory/verify

\n

Mark a memory as verified (requires JWT, not Mind Key).

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

POST /memory/unverify

\n

Mark a memory as unverified (requires JWT).

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

GET /memory/unverified

\n

List memories awaiting human verification.

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

Statistics & Audit

\n

GET /memory/stats

\n

Aggregate statistics for the current mind.

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

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

\n

GET /memory/audit

\n

Audit log of all state-changing operations.

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

GET /memory/contradictions

\n

Detect potential contradictions in stored memories.

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

GET /memory/expiring

\n

List memories with expiry dates approaching.

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

Health & Export

\n

GET /memory/health

\n

Quick health check for memory system.

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

GET /memory/mind-export

\n

Full JSON export of all memories (for backup).

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

POST /memory/compact

\n

Compact similar memories (auto-summarization).

\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}'

Next Steps

\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"]}