Skip to main content

Memory API

intermediate 🤖 LLM-friendly 3 min · 516 words Updated: 2026-06-27 English

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

Read this article as: 📄 Plain Text ⚡ JSON 🤖 LLM Format
Language: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

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.

**Always call `GET /memory/recall` 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
identity User name, role, contact info, preferences about self
preference Likes, dislikes, working style, communication prefs
fact Verifiable facts (project details, dates, URLs)
project Project status, milestones, architecture
skill Things the user is good at
mistake Past errors — avoid repeating
context Session-relevant context
note Misc notes

Priorities

  • low — nice to know
  • normal — default
  • high — important
  • critical — 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.

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

Response (text/plain):

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

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

...

POST /memory

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

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

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

GET /memory

List memories with optional filters.

# 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

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

Delete a single memory.

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

Search Endpoints

GET /memory/search

Full-text search using FTS5.

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

FTS5 syntax:

  • Multiple words = AND: docker swarm
  • Phrase: "docker swarm"
  • Prefix: docker*
  • Boolean: docker OR kubernetes
  • Exclude: docker -swarm

GET /memory/semantic-search

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

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

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.

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

GET /memory/related/:id

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

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

Sync & Diff

GET /memory/diff

Incremental sync — returns memories changed since a timestamp.

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

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

POST /memory/sync

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

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

Bulk Operations

POST /memory/bulk-delete

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

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

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

Check embedding generation progress.

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

Verification

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

POST /memory/verify

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

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

POST /memory/unverify

Mark a memory as unverified (requires JWT).

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

GET /memory/unverified

List memories awaiting human verification.

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

Statistics & Audit

GET /memory/stats

Aggregate statistics for the current mind.

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

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

GET /memory/audit

Audit log of all state-changing operations.

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

GET /memory/contradictions

Detect potential contradictions in stored memories.

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

GET /memory/expiring

List memories with expiry dates approaching.

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

Health & Export

GET /memory/health

Quick health check for memory system.

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

GET /memory/mind-export

Full JSON export of all memories (for backup).

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

POST /memory/compact

Compact similar memories (auto-summarization).

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

Next Steps

← Back to API Reference