# The Memory Model
SUMMARY: How memories are structured — categories, keys, tags, priorities, sources, verification.

The Memory Model
Synapse's memory model is designed for LLM agents — structured enough for
reliable recall, flexible enough for any domain.
Memory Anatomy
[CODE BLOCK]
Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
|  | string | auto | Unique ID (memxxx) |
|  | enum | ✅ | One of 8 categories |
|  | string | ✅ | Stable identifier (used for updates) |
|  | string | ✅ | The memory content (any text) |
|  | string[] | – | For search and filtering |
|  | enum | – | low, normal, high, critical (default: normal) |
|  | enum | auto | user, agent (who stored it) |
|  | bool | auto | Has a human verified this? |
|  | float | – | 0.0 to 1.0 (default: 1.0 for user, 0.7 for agent) |
|  | timestamp | – | When to forget this memory |
|  | string | auto | Which mind owns this |
|  | timestamp | auto | First stored |
|  | timestamp | auto | Last modified |
Categories
Eight categories cover the common LLM agent use cases:
| Category | Purpose | Example Content |
|----------|---------|-----------------|
|  | Who the user is | "User is Michael Schäfer, software engineer in Berlin" |
|  | User preferences | "Prefers concise technical responses" |
|  | Verifiable facts | "Office is in Berlin, timezone Europe/Berlin" |
|  | Project status | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
|  | User's skills | "Advanced Python, 10+ years" |
|  | Past errors | "Forgot to bump npm version — CI failed" |
|  | Session context | "Currently reviewing PR #42" |
|  | Misc notes | "Try Redis for caching next sprint" |
Keys: Stable Identifiers
The  field is critical — it's how you update memories without creating
duplicates.
[CODE BLOCK]
Key rules:
- Must be unique within (category, mind)
- Use 
- Prefix with category for clarity: , 
- Keep stable — don't change keys after creation
Tags: For Search
Tags enable fast filtering and search:
[CODE BLOCK]
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 |
|----------|-------------|-----------------|
|  | Identity, legal, irreversible | Always at top of recall |
|  | Active projects, key preferences | Prominent in recall |
|  | Most memories (default) | Standard recall order |
|  | Ephemeral, nice-to-know | May be summarized |
 sorts by priority (critical first), then by recency.
Source: User vs Agent
Memories are tagged with :
-  — stored by a human (via JWT or human UI)
-  — stored by an LLM agent (via Mind Key)
This affects:
- Verification:  memories are auto-verified,  memories are not
- Confidence:  defaults to 1.0,  to 0.7
- Recall:  marks unverified memories with "(unverified)"
> [!NOTE]
> Treat -source memories with appropriate skepticism. They may be
> inferred or assumed rather than directly stated by the user.
Verification
The  flag indicates a human has confirmed the memory:
-  memories: auto-verified ()
-  memories: default unverified ()
Verify memories via:
[CODE BLOCK]
> [!NOTE]
> Verification requires JWT (human auth), not Mind Key (agent auth). This
> ensures only humans can mark memories as verified.
Confidence
The  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:
[CODE BLOCK]
Expiration
Set  for time-sensitive memories:
[CODE BLOCK]
Expired memories are not returned by  (but still exist in DB).
Use  to see memories expiring soon.
Memory Lifecycle
[CODE BLOCK]
Recall Behavior
 returns a plain-text summary optimized for LLM context:
[CODE BLOCK]
- Sorted by priority (critical → low), then by recency
- Unverified memories marked with 
- Tags included for context
- Plain text (no JSON parsing needed)
Next Steps
- Memory API
- Memory Best Practices
- FTS5 Search