{"title":"The Memory Model","slug":"memory-model","category":"concepts","summary":"How memories are structured — categories, keys, tags, priorities, sources, verification.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":692,"read_minutes":3,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# The Memory Model\n\nSynapse's memory model is designed for LLM agents — structured enough for\nreliable recall, flexible enough for any domain.\n\n## Memory Anatomy\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | string | auto | Unique ID (mem_xxx) |\n| `category` | enum | ✅ | One of 8 categories |\n| `key` | string | ✅ | Stable identifier (used for updates) |\n| `content` | string | ✅ | The memory content (any text) |\n| `tags` | string[] | – | For search and filtering |\n| `priority` | enum | – | low, normal, high, critical (default: normal) |\n| `source` | enum | auto | user, agent (who stored it) |\n| `verified` | bool | auto | Has a human verified this? |\n| `confidence` | float | – | 0.0 to 1.0 (default: 1.0 for user, 0.7 for agent) |\n| `expires_at` | timestamp | – | When to forget this memory |\n| `mind_id` | string | auto | Which mind owns this |\n| `created_at` | timestamp | auto | First stored |\n| `updated_at` | timestamp | auto | Last modified |\n\n## Categories\n\nEight categories cover the common LLM agent use cases:\n\n| Category | Purpose | Example Content |\n|----------|---------|-----------------|\n| `identity` | Who the user is | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | User preferences | \"Prefers concise technical responses\" |\n| `fact` | Verifiable facts | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | Project status | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | User's skills | \"Advanced Python, 10+ years\" |\n| `mistake` | Past errors | \"Forgot to bump npm version — CI failed\" |\n| `context` | Session context | \"Currently reviewing PR #42\" |\n| `note` | Misc notes | \"Try Redis for caching next sprint\" |\n\n## Keys: Stable Identifiers\n\nThe `key` field is critical — it's how you update memories without creating\nduplicates.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Key rules:**\n\n- Must be unique within (category, mind)\n- Use `snake_case`\n- Prefix with category for clarity: `preference_communication`, `mistake_npm_version`\n- Keep stable — don't change keys after creation\n\n## Tags: For Search\n\nTags enable fast filtering and search:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**Tag best practices:**\n\n- 2-5 tags per memory (don't over-tag)\n- Lowercase for consistency\n- Use project names, topics, technologies\n- Tags are case-insensitive\n\n## Priority Levels\n\n| Priority | When to Use | Recall Behavior |\n|----------|-------------|-----------------|\n| `critical` | Identity, legal, irreversible | Always at top of recall |\n| `high` | Active projects, key preferences | Prominent in recall |\n| `normal` | Most memories (default) | Standard recall order |\n| `low` | Ephemeral, nice-to-know | May be summarized |\n\n`/memory/recall` sorts by priority (critical first), then by recency.\n\n## Source: User vs Agent\n\nMemories are tagged with `source`:\n\n- `user` — stored by a human (via JWT or human UI)\n- `agent` — stored by an LLM agent (via Mind Key)\n\nThis affects:\n\n- **Verification**: `user` memories are auto-verified, `agent` memories are not\n- **Confidence**: `user` defaults to 1.0, `agent` to 0.7\n- **Recall**: `/memory/recall` marks unverified memories with \"(unverified)\"\n\n> [!NOTE]\n> Treat `agent`-source memories with appropriate skepticism. They may be\n> inferred or assumed rather than directly stated by the user.\n\n## Verification\n\nThe `verified` flag indicates a human has confirmed the memory:\n\n- `user` memories: auto-verified (`true`)\n- `agent` memories: default unverified (`false`)\n\nVerify memories via:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> Verification requires JWT (human auth), not Mind Key (agent auth). This\n> ensures only humans can mark memories as verified.\n\n## Confidence\n\nThe `confidence` field (0.0 to 1.0) indicates how reliable the memory is:\n\n- 1.0 — directly stated by user\n- 0.7 — inferred by agent\n- 0.5 — uncertain, needs verification\n- 0.0 — explicitly doubted\n\nSet confidence when storing:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## Expiration\n\nSet `expires_at` for time-sensitive memories:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\nExpired memories are not returned by `/memory/recall` (but still exist in DB).\nUse `/memory/expiring?within=7d` to see memories expiring soon.\n\n## Memory Lifecycle\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## Recall Behavior\n\n`GET /memory/recall` returns a plain-text summary optimized for LLM context:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- Sorted by priority (critical → low), then by recency\n- Unverified memories marked with `[unverified]`\n- Tags included for context\n- Plain text (no JSON parsing needed)\n\n## Next Steps\n\n- [Memory API](/docs/api/memory)\n- [Memory Best Practices](/docs/guides/memory-best-practices)\n- [FTS5 Search](/docs/concepts/fts5-search)\n","content_html":"

The Memory Model

\n

Synapse's memory model is designed for LLM agents — structured enough for\nreliable recall, flexible enough for any domain.

\n

Memory Anatomy

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

Fields

\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\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\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
idstringautoUnique ID (mem_xxx)
categoryenum✅One of 8 categories
keystring✅Stable identifier (used for updates)
contentstring✅The memory content (any text)
tagsstring[]–For search and filtering
priorityenum–low, normal, high, critical (default: normal)
sourceenumautouser, agent (who stored it)
verifiedboolautoHas a human verified this?
confidencefloat–0.0 to 1.0 (default: 1.0 for user, 0.7 for agent)
expires_attimestamp–When to forget this memory
mind_idstringautoWhich mind owns this
created_attimestampautoFirst stored
updated_attimestampautoLast modified
\n

Categories

\n

Eight categories cover the common LLM agent use cases:

\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\n\n\n\n\n\n\n\n\n
CategoryPurposeExample Content
identityWho the user is"User is Michael Schäfer, software engineer in Berlin"
preferenceUser preferences"Prefers concise technical responses"
factVerifiable facts"Office is in Berlin, timezone Europe/Berlin"
projectProject status"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skillUser's skills"Advanced Python, 10+ years"
mistakePast errors"Forgot to bump npm version — CI failed"
contextSession context"Currently reviewing PR #42"
noteMisc notes"Try Redis for caching next sprint"
\n

Keys: Stable Identifiers

\n

The key field is critical — it's how you update memories without creating\nduplicates.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Key rules:

\n\n

Tags: For Search

\n

Tags enable fast filtering and search:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

Tag best practices:

\n\n

Priority Levels

\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
PriorityWhen to UseRecall Behavior
criticalIdentity, legal, irreversibleAlways at top of recall
highActive projects, key preferencesProminent in recall
normalMost memories (default)Standard recall order
lowEphemeral, nice-to-knowMay be summarized
\n

/memory/recall sorts by priority (critical first), then by recency.

\n

Source: User vs Agent

\n

Memories are tagged with source:

\n\n

This affects:

\n\n
Treat `agent`-source memories with appropriate skepticism. They may be\ninferred or assumed rather than directly stated by the user.

Verification

\n

The verified flag indicates a human has confirmed the memory:

\n\n

Verify memories via:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
Verification requires JWT (human auth), not Mind Key (agent auth). This\nensures only humans can mark memories as verified.

Confidence

\n

The confidence field (0.0 to 1.0) indicates how reliable the memory is:

\n\n

Set confidence when storing:

\n
{\n  "category": "preference",\n  "key": "prefers_dark_mode",\n  "content": "User seems to prefer dark mode (based on their IDE screenshots)",\n  "confidence": 0.5,\n  "source": "agent"\n}

Expiration

\n

Set expires_at for time-sensitive memories:

\n
{\n  "category": "context",\n  "key": "current_meeting_topic",\n  "content": "Discussing Q3 roadmap",\n  "expires_at": "2026-06-28T00:00:00Z"\n}

Expired memories are not returned by /memory/recall (but still exist in DB).\nUse /memory/expiring?within=7d to see memories expiring soon.

\n

Memory Lifecycle

\n
                  ┌─────────────────┐\n                  │     Create      │\n                  │  POST /memory   │\n                  └────────┬────────┘\n                           │\n                           ▼\n                  ┌─────────────────┐\n                  │     Active      │ ◀──── PUT /memory/:id (update)\n                  │  (in recall)    │\n                  └────────┬────────┘\n                           │\n              ┌────────────┼────────────┐\n              │            │            │\n              ▼            ▼            ▼\n        ┌──────────┐ ┌──────────┐ ┌──────────┐\n        │ Expired  │ │ Verified │ │ Deleted  │\n        │ (in DB)  │ │ (flag)   │ │ (gone)   │\n        └──────────┘ └──────────┘ └──────────┘

Recall Behavior

\n

GET /memory/recall returns a plain-text summary optimized for LLM context:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

Next Steps

\n\n","urls":{"html":"/docs/concepts/memory-model","text":"/docs/concepts/memory-model?format=text","json":"/docs/concepts/memory-model?format=json","llm":"/docs/concepts/memory-model?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}