# Memory API
SUMMARY: Complete reference for the 22 memory endpoints: store, recall, search, semantic search, sync, audit, and more.

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
The Memory API is the heart of Synapse. It provides 22 endpoints for storing,
retrieving, searching, and managing structured memories. All endpoints require
a Mind Key for authentication.
> [!CRITICAL]
> Always call  at the start of every session. This is
> the only way to rebuild context from previous sessions.
Categories
Memories are organized into 8 categories:
| Category | Use Case |
|----------|----------|
|  | User name, role, contact info, preferences about self |
|  | Likes, dislikes, working style, communication prefs |
|  | Verifiable facts (project details, dates, URLs) |
|  | Project status, milestones, architecture |
|  | Things the user is good at |
|  | Past errors — avoid repeating |
|  | Session-relevant context |
|  | Misc notes |
Priorities
-  — nice to know
-  — default
-  — important
-  — must never forget (user identity, legal info)
Core Endpoints
GET /memory/recall
Returns ALL memories as LLM-optimized plain text. Call this at every session start.
[CODE BLOCK]
Response (text/plain):
[CODE BLOCK]
POST /memory
Store a new memory or update an existing one (same category + key = update).
[CODE BLOCK]
Response: 
GET /memory
List memories with optional filters.
[CODE BLOCK]
PUT /memory/:id
Update a specific memory by ID.
[CODE BLOCK]
DELETE /memory/:id
Delete a single memory.
[CODE BLOCK]
Search Endpoints
GET /memory/search
Full-text search using FTS5.
[CODE BLOCK]
FTS5 syntax:
- Multiple words = AND: 
- Phrase: 
- Prefix: 
- Boolean: 
- Exclude: 
GET /memory/semantic-search
Conceptual search using embeddings (slower than FTS5 but understands meaning).
[CODE BLOCK]
Returns memories that are semantically similar to the query, even if no keywords
match. Useful for "find memories about X" where X is described differently.
GET /memory/by-tag
List memories by tag.
[CODE BLOCK]
GET /memory/related/:id
Find memories related to a specific memory (via shared tags).
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Incremental sync — returns memories changed since a timestamp.
[CODE BLOCK]
Response: 
POST /memory/sync
Apply a diff from another instance (for self-hosted sync).
[CODE BLOCK]
Bulk Operations
POST /memory/bulk-delete
Delete multiple memories by ID.
[CODE BLOCK]
POST /memory/embed-batch
Generate embeddings for memories that don't have them yet (for semantic search).
[CODE BLOCK]
GET /memory/embed-batch-status
Check embedding generation progress.
[CODE BLOCK]
Verification
Memories have a  flag. Agent-stored memories default to unverified
(); human-stored memories are verified ().
POST /memory/verify
Mark a memory as verified (requires JWT, not Mind Key).
[CODE BLOCK]
POST /memory/unverify
Mark a memory as unverified (requires JWT).
[CODE BLOCK]
GET /memory/unverified
List memories awaiting human verification.
[CODE BLOCK]
Statistics & Audit
GET /memory/stats
Aggregate statistics for the current mind.
[CODE BLOCK]
Returns: 
GET /memory/audit
Audit log of all state-changing operations.
[CODE BLOCK]
GET /memory/contradictions
Detect potential contradictions in stored memories.
[CODE BLOCK]
GET /memory/expiring
List memories with expiry dates approaching.
[CODE BLOCK]
Health & Export
GET /memory/health
Quick health check for memory system.
[CODE BLOCK]
GET /memory/mind-export
Full JSON export of all memories (for backup).
[CODE BLOCK]
POST /memory/compact
Compact similar memories (auto-summarization).
[CODE BLOCK]
Next Steps
- Quick Start for LLMs
- Memory Best Practices
- FTS5 Search
- Semantic Search