Synap – lokale Gedächtnis-Engine für KI-Agenten

Synap verwenden

Synap ist eine lokale Gedächtnis-Engine für KI-Agenten. Alles befindet sich unter ~/.synap/ auf dem Rechner des Nutzers – keine Cloud, keine Konten, keine API-Schlüssel. Du kommunizierst damit über die mcp__synap__*-Toolfamilie.

Dieses Skill vermittelt dir den Entscheidungsbaum: welches Tool, wann, mit welchen Argumenten. Lies die Tool-Schemas für die genaue Parametersyntax; dieses Dokument hilft dir, das richtige Tool auszuwählen und es gut einzusetzen.

Kernkonzepte

Synap organisiert Daten in Apps. Eine App ist ein Namensraum (tasks, accounting, recipes, …) mit einem Schema. Schemas basieren intern auf EAV, sodass Du später Felder hinzufügen kannst, ohne eine Migration durchführen zu müssen. Jede App enthält Entitäten (Zeilen) mit Attributen (Feldern).

Zwei Apps sind integriert und gehören zu Synap selbst:

• synap.memories – Langzeitgedächtnis über den Nutzer. Schreibzugriffe erfolgen über remember / forget (niemals write). Lesezugriffe über query / search.
• synap.sessions – Gesprächsverlauf (Wendungen, Zusammenfassungen). Für dich schreibgeschützt – nicht daran schreiben.

Vom Nutzer erstellte Apps leben unter anderen Namen (kein synap.-Präfix – dieser Namensraum ist reserviert).

Entscheidungsbaum

"Erinnere dich an X über mich"

Verwende remember gegen synap.memories. Zwei Formen:

• Profilattribut (type: "attr") – eine dauerhafte Tatsache über den Nutzer (preferred_language, city, allergies). Verwende op: "set" zum Überschreiben, op: "append" zum Hinzufügen zu einer Liste.
• Ereignis (type: "event") – eine zeitgestempelte Beobachtung ("Nutzer hat v0.1.0 heute veröffentlicht", "Nutzer erwähnte, überfordert zu sein"). Nur anhängbar, mit description, subject, optionalem when.

Wähle attr, wenn die Tatsache einen dauerhaften Zustand beschreibt. Wähle event, wenn es sich um einen bestimmten Zeitpunkt handelt, der später für den Kontext wichtig ist.

"Was weißt du über mich?"

query auf synap.memories mit filters=[{field:"subject", op:"eq", value:"user"}]. Verwende nicht search, es sei denn, der Nutzer hat etwas Unscharfes gefragt wie "irgendwas zu meinen Reiseplänen" – dann search mit rank: "time_decay" hebt aktuelle relevante Ereignisse hervor.

"Vergiss X"

forget. Präzise, schlüsselbasiert. Nicht "query dann write nulls" – forget erledigt sowohl das Löschen von Attributen als auch das Entfernen von Ereignissen atomar.

"Verfolge Aufgaben / Rezepte / Ausgaben / …" (neue Art von Daten)

1. list_apps – prüfe, ob bereits eine App existiert.
2. Falls nicht: init_app mit einem durchdachten Schema.
3. write zum Hinzufügen von Entitäten. ops ist ein Array: ein op = einzelner Schreibvorgang, N ops = atomarer Batch (alles oder nichts).

Tipps zur Schema-Erstellung:

• Markiere lange Textfelder (Beschreibungen, Notizen) mit vectorized: true, damit die Suche sie semantisch finden kann.
• Verwende entity_type, wenn eine App unterschiedliche Formen enthält ("Aufgabe" + "Notiz" in einer workspace-App).
• Überentwickle die erste Version nicht – EAV ermöglicht das Hinzufügen von Feldern später.

"Zeig mir meine Todos / Notizen von letzter Woche / …"

query mit Filtern und Sortierung. TSV-Ausgabe ist dicht – parsiere sie, gib sie nicht roh an den Nutzer zurück.

"Finde irgendwas zu X"

search. Drei Ranking-Modi:

• relevance (Standard) – reiner semantischer + Schlüsselwort-Match.
• recency – neueste zuerst, ohne Ähnlichkeitsberücksichtigung. Gut für "aktuellste Notizen".
• time_decay – Mischung aus beidem. Gut für sich entwickelnden Kontext (Ereignisse, Journale), bei dem sowohl Aktualität als auch Relevanz zählen.

Übergib app_id zum Eingrenzen oder lasse es für eine app-übergreifende Suche weg.

"Lies diese Datei"

read_file – verarbeitet file://, synap://-URIs und lokale Pfade. Gibt seitenweise Inhalte zurück (Standard ~4K Zeichen). Verwende den page-Parameter zum Blättern.

"Was hast du mir vorhin erzählt?" (Kontext wurde komprimiert)

Suche in der Unterhaltung nach <compressed_segment turn_ids="...">-Blöcken. expand mit diesen turn_ids bohrt zurück zu den wörtlichen Originalen. <stale_tool_result turn_id="..."> folgt dem gleichen Muster für eingeklappte Tool-Ergebnisse.

Anti-Patterns

• Schreibe nicht in synap.*-Apps. Synap lehnt dies ab. Verwende remember / forget für das Gedächtnis.
• Erfinde kein eigenes Gedächtnis mit einer benutzerdefinierten App. synap.memories bietet Profil- und Ereignis-Semantik, Zeitabkling-Ranking und automatische Vor-Wendungs-Einblendung.
• Chunke nicht manuell zu stark. Langer Text (>1024 Tokens) wird automatisch mit Überlappung gechunkt. Schreibe einfach den gesamten Text.
• Ignoriere das subject-Feld nicht. Das Gedächtnis ist auf subject beschränkt (Standard: "user"). Wenn der Nutzer eine andere Person verfolgt ("erinnere dich, Alice bevorzugt Tee"), übergib subject: "alice".

Häufige Muster

Einrichten eines neuen Bereichs im Leben des Nutzers

Nutzer: "Ich möchte anfangen, mein Lesen zu verfolgen."

1. list_apps – bestätige, dass keine "reading"-App existiert
2. init_app name="reading" mit Feldern:
   - title (Text, erforderlich)
   - author (Text)
   - status (Enum: to_read | reading | done)
   - started_at, finished_at (Datum)
   - notes (Text, vectorized: true)
   - rating (Zahl, 1-5)
3. "Bereit – sag mir, was du liest, und ich füge es hinzu."

Kontext zu Beginn einer Unterhaltung anzeigen

Die Blöcke [memory: profile] und [memory: events] werden automatisch bei jeder Wendung für dich eingefügt. Du musst nicht query aufrufen, um sie zu sehen. Wenn der Nutzer jedoch etwas fragt, das eine breitere Erinnerung erfordert ("Woran habe ich in letzter Zeit gearbeitet?"), ist search auf synap.memories mit rank: "time_decay" die richtige Wahl.

Daten migrieren / umgestalten

Synap hat keine formale Migration. Um ein Feld hinzuzufügen: Schreibe es einfach. Vorhandene Zeilen haben das Attribut dann nicht. Zum Umbenennen: query, um alle entity_ids zu erhalten, dann write einen Batch von Aktualisierungen, die altes Feld → neues Feld → altes Feld löschen. Die EAV-Kosten sind minimal.

Tool-Spickzettel

Ziel	Tool	Hinweise
Nutzerfakt merken	remember type=attr	op: set oder append
Zeitgestempeltes Ereignis protokollieren	remember type=event	Nur anhängbar
Erinnerung löschen	forget	Präziser Schlüssel, nicht raten
Daten-App erstellen	init_app	Idempotent, unterstützt Weiterentwicklung
Apps auflisten	list_apps	include_internal: true um synap.* zu sehen
Entitäten hinzufügen/aktualisieren	write	ops-Array, N = atomarer Batch
Entitäten filtern	query	TSV-Ausgabe, Feldprojektion
Semantische Suche	search	rank: relevance | recency | time_decay
Datei lesen	read_file	Seiten automatisch
Komprimierte Wendungen wiederherstellen	expand	turn_ids aus dem komprimierten Block übergeben
Verknüpfungen zwischen Entitäten erkennen	detect_links	Optional, für Wissensgraphen