# Memory API

Memory API är hjärtat i Synapse. Det tillhandahåller 22 endpoints för lagring,
hämtning, sökning och hantering av strukturerade minnen. Alla endpoints kräver
en Mind Key för autentisering.

> [!CRITICAL]
> **Anropa alltid `GET /memory/recall` i början av varje session.** Detta är
> det enda sättet att återuppbygga kontext från tidigare sessioner.

## Kategorier

Minnen är organiserade i 8 kategorier:

| Kategori | Användningsområde |
|----------|----------|
| `identity` | Användarnamn, roll, kontaktinfo, inställningar om sig själv |
| `preference` | Tycker om, ogillar, arbetsstil, kommunikationsinställningar |
| `fact` | Verifierbara fakta (projektdetaljer, datum, URL:er) |
| `project` | Projektstatus, milstolpar, arkitektur |
| `skill` | Saker användaren är bra på |
| `mistake` | Tidigare fel — undvik att upprepa |
| `context` | Sessionsrelevant kontext |
| `note` | Diverse anteckningar |

## Prioriteringar

- `low` — bra att veta
- `normal` — standard
- `high` — viktig
- `critical` — får aldrig glömmas (användaridentitet, juridisk info)

## Centrala endpoints

### GET /memory/recall

Returnerar ALLA minnen som LLM-optimerad oformaterad text. Anropa detta vid
varje sessionsstart.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall
```

Svar (text/plain):

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

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

...
```

### POST /memory

Lagra ett nytt minne eller uppdatera ett befintligt (samma kategori + nyckel = uppdatering).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "fact",
    "key": "user_name",
    "content": "The user's name is Michael Schäfer",
    "tags": ["person", "identity"],
    "priority": "critical"
  }'
```

Svar: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

Lista minnen med valfria filter.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Uppdatera ett specifikt minne via ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Ta bort ett enskilt minne.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Sök-endpoints

### GET /memory/search

Fulltextssökning med FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

FTS5-syntax:

- Flera ord = AND: `docker swarm`
- Fras: `"docker swarm"`
- Prefix: `docker*`
- Boolesk: `docker OR kubernetes`
- Uteslut: `docker -swarm`

### GET /memory/semantic-search

Begreppsbaserad sökning med inbäddningar (langsammare än FTS5 men förstår betydelse).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

Returnerar minnen som är semantiskt lika frågan, även om inga nyckelord
matchar. Användbart för "hitta minnen om X" där X beskrivs på annat sätt.

### GET /memory/by-tag

Lista minnen efter tagg.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Hitta minnen relaterade till ett specifikt minne (via gemensamma taggar).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Synkronisering & Diff

### GET /memory/diff

Inkrementell synk — returnerar minnen som ändrats sedan en tidsstämpel.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Svar: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Tillämpa en diff från en annan instans (för självvärd synk).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Massåtgärder

### POST /memory/bulk-delete

Ta bort flera minnen via ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Generera inbäddningar för minnen som saknar dem (för semantisk sökning).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Kontrollera förloppet för inbäddningsgenerering.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Verifiering

Minnen har en `verified`-flagga. Agentlagrade minnen är som standard overifierade
(`source=agent`); människolagrade minnen är verifierade (`source=user`).

### POST /memory/verify

Markera ett minne som verifierat (kräver JWT, inte Mind Key).

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

### POST /memory/unverify

Markera ett minne som overifierat (kräver JWT).

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

### GET /memory/unverified

Lista minnen som väntar på mänsklig verifiering.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Statistik & granskning

### GET /memory/stats

Aggregerad statistik för den aktuella minden.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/stats
```

Returnerar: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Granskningslogg över alla tillståndsändrande åtgärder.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Upptäck potentiella motsägelser i lagrade minnen.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/contradictions
```

### GET /memory/expiring

Lista minnen med utgångsdatum som närmar sig.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Hälsa & export

### GET /memory/health

Snabb hälsokontroll för minnessystemet.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/health
```

### GET /memory/mind-export

Full JSON-export av alla minnen (för säkerhetskopiering).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Komprimera liknande minnen (auto-sammanfattning).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Nästa steg

- [Snabbstart för LLM:er](/docs/getting-started/quick-start-llm)
- [Minnesbästa praxis](/docs/guides/memory-best-practices)
- [FTS5-sökning](/docs/concepts/fts5-search)
- [Semantisk sökning](/docs/concepts/semantic-search)