Das Memory-Modell

Synapses Memory-Modell ist für LLM-Agenten gestaltet — strukturiert genug für zuverlässiges Abrufen, flexibel genug für jede Domäne.

Anatomie eines Memories

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

Felder

Kategorien

Acht Kategorien decken die gängigen LLM-Agent-Anwendungsfälle ab:

Keys: Stabile Bezeichner

Das Feld key ist entscheidend — so aktualisierst du Memories, ohne Duplikate zu erzeugen.

# 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-Regeln:

• Muss innerhalb (Kategorie, Mind) eindeutig sein
• Verwende snake_case
• Präfix mit Kategorie für Klarheit: preference_communication, mistake_npm_version
• Stabil halten — Keys nach Anlage nicht ändern

Tags: Für die Suche

Tags ermöglichen schnelle Filterung und Suche:

# 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 pro Memory (nicht übertrieben)
• Kleinschreibung für Konsistenz
• Projektnamen, Themen, Technologien verwenden
• Tags sind Case-insensitive

Prioritätsstufen

/memory/recall sortiert nach Priorität (critical zuerst), dann nach Aktualität.

Quelle: User vs Agent

Memories werden mit source markiert:

• user — von einem Menschen gespeichert (via JWT oder Human-UI)
• agent — von einem LLM-Agenten gespeichert (via Mind Key)

Das beeinflusst:

• Verifikation: user-Memories sind auto-verifiziert, agent-Memories nicht
• Confidence: user defaults auf 1.0, agent auf 0.7
• Recall: /memory/recall markiert unverified Memories mit „(unverified)"

Verifikation

Das Flag verified zeigt an, dass ein Mensch den Memory bestätigt hat:

• user-Memories: auto-verifiziert (true)
• agent-Memories: standardmäßig unverified (false)

Memories verifizieren via:

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

Confidence

Das Feld confidence (0.0 bis 1.0) zeigt, wie zuverlässig der Memory ist:

• 1.0 — direkt vom Nutzer geäußert
• 0.7 — vom Agenten gefolgert
• 0.5 — unsicher, needs Verifikation
• 0.0 — explizit angezweifelt

Beim Speichern Confidence setzen:

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

Ablauf

Für zeitkritische Memories expires_at setzen:

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

Abgelaufene Memories werden von /memory/recall nicht zurückgegeben (bleiben aber in der DB). Verwende /memory/expiring?within=7d, um bald ablaufende Memories zu sehen.

Memory-Lebenszyklus

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

Recall-Verhalten

GET /memory/recall liefert eine Klartext-Zusammenfassung, optimiert 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

...

• Sortiert nach Priorität (critical → low), dann nach Aktualität
• Unverified Memories markiert mit [unverified]
• Tags für Kontext enthalten
• Klartext (kein JSON-Parsing nötig)

Nächste Schritte

• Memory-API
• Memory-Best-Practices
• FTS5-Suche