# Minnesmodellen

Synapses minnesmodell är utformad för LLM-agenter — tillräckligt strukturerad
för pålitlig återkallning, tillräckligt flexibel för alla domäner.

## Minnesanatomi

```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..."
}
```

## Fält

| Fält | Typ | Obligatorisk | Beskrivning |
|-------|------|----------|-------------|
| `id` | sträng | auto | Unikt ID (mem_xxx) |
| `category` | enum | ✅ | En av 8 kategorier |
| `key` | sträng | ✅ | Stabil identifierare (används för uppdateringar) |
| `content` | sträng | ✅ | Minnesinnehållet (valfri text) |
| `tags` | sträng[] | – | För sökning och filtrering |
| `priority` | enum | – | low, normal, high, critical (standard: normal) |
| `source` | enum | auto | user, agent (vem som lagrade det) |
| `verified` | bool | auto | Har en människa verifierat detta? |
| `confidence` | flyttal | – | 0.0 till 1.0 (standard: 1.0 för user, 0.7 för agent) |
| `expires_at` | tidsstämpel | – | När minnet ska glömmas |
| `mind_id` | sträng | auto | Vilken mind som äger detta |
| `created_at` | tidsstämpel | auto | Först lagrad |
| `updated_at` | tidsstämpel | auto | Senast ändrad |

## Kategorier

Åtta kategorier täcker vanliga användningsområden för LLM-agenter:

| Kategori | Syfte | Exempel på innehåll |
|----------|---------|-----------------|
| `identity` | Vem användaren är | "User is Michael Schäfer, software engineer in Berlin" |
| `preference` | Användarinställningar | "Prefers concise technical responses" |
| `fact` | Verifierbara fakta | "Office is in Berlin, timezone Europe/Berlin" |
| `project` | Projektstatus | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| `skill` | Användarens färdigheter | "Advanced Python, 10+ years" |
| `mistake` | Tidigare fel | "Forgot to bump npm version — CI failed" |
| `context` | Sessionskontext | "Currently reviewing PR #42" |
| `note` | Diverse anteckningar | "Try Redis for caching next sprint" |

## Nycklar: stabila identifierare

Fältet `key` är kritiskt — det är så ni uppdaterar minnen utan att skapa
dubbletter.

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

**Nyckelregler:**

- Måste vara unik inom (category, mind)
- Använd `snake_case`
- Prefixa med kategori för tydlighet: `preference_communication`, `mistake_npm_version`
- Håll stabil — ändra inte nycklar efter skapandet

## Taggar: för sökning

Taggar möjliggör snabb filtrering och sökning:

```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
```

**Bästa praxis för taggar:**

- 2–5 taggar per minne (överätta inte)
- Gemener för konsekvens
- Använd projektnamn, ämnen, tekniker
- Taggar är skiftesokänsliga

## Prioriteringsnivåer

| Prioritering | När den ska användas | Återkallningsbeteende |
|----------|-------------|-----------------|
| `critical` | Identitet, juridik, oåterkalleligt | Alltid högst upp i återkallning |
| `high` | Aktiva projekt, nyckelinställningar | Framträdande i återkallning |
| `normal` | De flesta minnen (standard) | Standardordning för återkallning |
| `low` | Efemärt, trevligt att veta | Kan sammanfattas |

`/memory/recall` sorterar efter prioritet (kritisk först), sedan efter aktualitet.

## Källa: användare vs agent

Minnen taggas med `source`:

- `user` — lagrad av en människa (via JWT eller mänskligt gränssnitt)
- `agent` — lagrad av en LLM-agent (via Mind Key)

Detta påverkar:

- **Verifiering**: `user`-minnen verifieras automatiskt, `agent`-minnen inte
- **Konfidens**: `user` standard 1.0, `agent` 0.7
- **Återkallning**: `/memory/recall` markerar overifierade minnen med "(unverified)"

> [!NOTE]
> Behandla `agent`-källade minnen med lämplig skepsis. De kan vara härledda
> eller antagna snarare än direkt angivna av användaren.

## Verifiering

Flaggan `verified` indikerar att en människa har bekräftat minnet:

- `user`-minnen: auto-verifierade (`true`)
- `agent`-minnen: standard overifierade (`false`)

Verifiera minnen via:

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

> [!NOTE]
> Verifiering kräver JWT (mänsklig autentisering), inte Mind Key
> (agent-autentisering). Detta säkerställer att endast människor kan markera
> minnen som verifierade.

## Konfidens

Fältet `confidence` (0.0 till 1.0) indikerar hur pålitligt minnet är:

- 1.0 — direkt angivet av användare
- 0.7 — härlett av agent
- 0.5 — osäkert, behöver verifiering
- 0.0 — uttryckligen tvivelaktigt

Sätt konfidens vid lagring:

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

## Utgång

Sätt `expires_at` för tidskänsliga minnen:

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

Utgångna minnen returneras inte av `/memory/recall` (men finns fortfarande i DB).
Använd `/memory/expiring?within=7d` för att se minnen som löper ut snart.

## Minneslivscykel

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

## Återkallningsbeteende

`GET /memory/recall` returnerar en oformaterad textsammanfattning optimerad
för LLM-kontext:

```
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

...
```

- Sorterat efter prioritet (kritisk → låg), sedan efter aktualitet
- Overifierade minnen markerade med `[unverified]`
- Taggar inkluderade för kontext
- Oformaterad text (ingen JSON-tolkning behövs)

## Nästa steg

- [Memory API](/docs/api/memory)
- [Minnesbästa praxis](/docs/guides/memory-best-practices)
- [FTS5-sökning](/docs/concepts/fts5-search)