Skip to main content

The Memory Model

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

How memories are structured — categories, keys, tags, priorities, sources, verification.

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Українська

The Memory Model

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

Memory Anatomy

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

Fields

Field Type Required Description
id string auto Unique ID (mem_xxx)
category enum ✅ One of 8 categories
key string ✅ Stable identifier (used for updates)
content string ✅ The memory content (any text)
tags string[] – For search and filtering
priority enum – low, normal, high, critical (default: normal)
source enum auto user, agent (who stored it)
verified bool auto Has a human verified this?
confidence float – 0.0 to 1.0 (default: 1.0 for user, 0.7 for agent)
expires_at timestamp – When to forget this memory
mind_id string auto Which mind owns this
created_at timestamp auto First stored
updated_at timestamp auto Last modified

Categories

Eight categories cover the common LLM agent use cases:

Category Purpose Example Content
identity Who the user is "User is Michael Schäfer, software engineer in Berlin"
preference User preferences "Prefers concise technical responses"
fact Verifiable facts "Office is in Berlin, timezone Europe/Berlin"
project Project status "Synapse v1.5.0 deployed, working on v1.6.0 docs"
skill User's skills "Advanced Python, 10+ years"
mistake Past errors "Forgot to bump npm version — CI failed"
context Session context "Currently reviewing PR #42"
note Misc notes "Try Redis for caching next sprint"

Keys: Stable Identifiers

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

# First store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

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

Key rules:

  • Must be unique within (category, mind)
  • Use snake_case
  • Prefix with category for clarity: preference_communication, mistake_npm_version
  • Keep stable — don't change keys after creation

Tags: For Search

Tags enable fast filtering and search:

# Find all memories with tag "docker"
GET /memory/by-tag?tag=docker

# FTS5 search within tagged subset
GET /memory/search?q=swarm&tag=docker

Tag best practices:

  • 2-5 tags per memory (don't over-tag)
  • Lowercase for consistency
  • Use project names, topics, technologies
  • Tags are case-insensitive

Priority Levels

Priority When to Use Recall Behavior
critical Identity, legal, irreversible Always at top of recall
high Active projects, key preferences Prominent in recall
normal Most memories (default) Standard recall order
low Ephemeral, nice-to-know May be summarized

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

Source: User vs Agent

Memories are tagged with source:

  • user — stored by a human (via JWT or human UI)
  • agent — stored by an LLM agent (via Mind Key)

This affects:

  • Verification: user memories are auto-verified, agent memories are not
  • Confidence: user defaults to 1.0, agent to 0.7
  • Recall: /memory/recall marks unverified memories with "(unverified)"
Treat `agent`-source memories with appropriate skepticism. They may be inferred or assumed rather than directly stated by the user.

Verification

The verified flag indicates a human has confirmed the memory:

  • user memories: auto-verified (true)
  • agent memories: default unverified (false)

Verify memories via:

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

Confidence

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

  • 1.0 — directly stated by user
  • 0.7 — inferred by agent
  • 0.5 — uncertain, needs verification
  • 0.0 — explicitly doubted

Set confidence when storing:

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

Expiration

Set expires_at for time-sensitive memories:

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

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

Memory Lifecycle

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

Recall Behavior

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

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

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

[002] preference (HIGH) [verified]
  communication_style
  Prefers concise technical responses
  Tags: communication

[003] project (HIGH) [unverified]
  synapse_status
  v1.5.0 deployed, working on v1.6.0 docs
  Tags: synapse, deployment

...
  • Sorted by priority (critical → low), then by recency
  • Unverified memories marked with [unverified]
  • Tags included for context
  • Plain text (no JSON parsing needed)

Next Steps

← Back to Concepts