# The Memory Model

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

## Memory Anatomy

```json
{
  "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.

```python
# 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:

```bash
# 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)"

> [!NOTE]
> 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:

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

> [!NOTE]
> 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:

```json
{
  "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:

```json
{
  "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

- [Memory API](/docs/api/memory)
- [Memory Best Practices](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)