Seahorse

Persistentes, bi-temporales Gedächtnis für LLM-Agenten — Local-First, MCP-nativ, Obsidian-lesbar.

pip install seahorse-memory
seahorse init myvault && seahorse remember "Sergio lives in Madrid"
seahorse recall "where does Sergio live?"

Warum

LLM-Agenten starten jede Sitzung bei null. Das Kontextfenster ist kein Gedächtnis: Es ist ein Notizblock, der zurückgesetzt wird, und es ist zu klein, um zu halten, was ein Agent über Wochen der Arbeit gelernt hat. Die Tools, die das zu beheben versuchen, haben ihre eigenen Probleme:

• Sie vergessen nicht richtig. Die meisten Speichersysteme sammeln Fakten für immer an und lösen Widersprüche nie auf – ein Agent „erinnert“ sich, dass ein Benutzer gleichzeitig in Madrid und in Barcelona wohnt, ohne herauszufinden zu können, welche Angabe aktuell ist.

• Sie sind intransparent. Das Gedächtnis lebt in einer proprietären Datenbank, die der Mensch nicht lesen, bearbeiten oder prüfen kann. Liegt der Agent falsch, gibt es keine Möglichkeit, das zu korrigieren.

• Ihre Fütterung ist teuer. Jede Episode läuft durch ein LLM, daher kostet das Schreiben Tausender kleiner Fakten echtes Geld.

• Sie binden dich an sich. Ein Speichersystem einzusetzen bedeutet oft, auch dessen Laufzeit, Provider und Ökosystem zu übernehmen.

• Ihre Benchmarks sind nicht vertrauenswürdig. Die eigenen Zahlen des Feldes sind schwer zu reproduzieren: Der LOCOMO-Benchmark enthält 6,4 % falsche Goldantworten, die Reproduktion von Mem0 ist defekt (Issue #2800), und MTEB-Embedding-Scores sagen die Memory-Retrieval-Leistung nicht voraus (LMEB, arXiv 2603.12572).

Seahorse ist ein anderer Ansatz: ein offener, portabler, bi-temporaler Speicherstandard, den ein Agent schreibt und aus dem er liest, den ein Mensch lesen und korrigieren kann und der dich an keine Laufzeit oder kein Produkt bindet.

Related MCP server: agentcairn

Für wen es gedacht ist

• Entwickler, die Agenten bauen (Claude Code, Cursor, Codex oder eigene) und wollen, dass der Agent Entscheidungen und Kontext über Sitzungen hinweg im Gedächtnis behält.

• Obsidian-Power-User, die ihre Notizen als mehr sehen wollen als ein statisches Archiv – als eine Wissensbasis, die ein Agent abfragen und pflegen kann.

• Teams, die portablen Speicher wollen — ein Format, das sie zwischen Anbietern migrieren können, ohne die Historie erneut abspielen zu müssen.

Anwendungsfall: Claude Code mit dauerhaftem Gedächtnis

Der schnellste Weg, Seahorse zu sehen, ist, Claude Code einen Speicher zu geben, der zwischen Sitzungen überlebt. Drei Schritte:

1. Sitzungen erfassen. seahorse setup installiert die Observer-Hooks in ~/.claude/settings.json, und seahorse observe start startet den Capture-Worker. Jede Sitzung wird als Episoden aufgezeichnet – skip-first (nahezu kostenlos), geschwärzt, und deterministisch zusammengefasst.

seahorse setup
seahorse observe start

2. Sitzungsübergreifend abrufen. Der SessionStart-Hook injiziert seahorse context in die nächste Sitzung, sodass der Agent mit dem beginnt, was er früher gelernt hat. Frag direkt mit seahorse recall:

seahorse context
seahorse recall "what did we decide about the API design?"

3. Bring' dein vorhandenes Gedächtnis mit. Wenn du bereits claude-mem verwendest, migriert seahorse import dessen Beobachtungen in kanonische Episoden – kein Abspielen, kein Lock-in:

seahorse import --mode commit

Der wesentliche Unterschied: Der Agent schreibt in denselben Vault, in dem du in Obsidian editierst – language marking... Jede Episode ist eine Markdown-Datei with YAML-Frontmatter – lesbar, editierbar, in Git diffbar und von einem Menschen prüfbar. Das Gedächtnis das Agent ist keine Black Box; es sind deine Notizen.

Von einem Agenten aus verwenden (MCP)

Seahorse ist für Agenten gebaut: Die Speicher-Oberfläche ist ein stdio-MCP-Server (io.seahorse.memory/v1), mit dem sich jeder MCP-fähige Agent verbinden kann. Die CLI ist für Menschen und Skripte gedacht; Agenten sprechen direkt mit seahorse-mcp.

Server in Claude Code registrieren (lokaler Scope, Standard):

claude mcp add seahorse-mcp -- uvx --from seahorse-memory seahorse-mcp --vault "${HOME}/myvault"

Das -- ist erforderlich – es trennt Cliques eigene Flags von dem Serverbefehl. Verwende --scope project, um den Server über .mcp.json (in git eingecheckt) mit einem Team zu teilen. Prüfe mit claude mcp list (sollte ✔ Connected stehen) und claude mcp get seahorse-mcp.

Oder konfiguriere es in .mcp.json im Projektstamm (funktioniert mit jedem MCP-Client):

{
  "mcpServers": {
    "seahorse-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "seahorse-memory", "seahorse-mcp", "--vault", "${HOME}/myvault"]
    }
  }
}

Hinweis: ~ wird in .mcp.json nicht expandiert – verwenden trage ${HOME} oder einen absoluten Pfad ein. (mcpServers in settings.json wird stillschweigend ignoriert; MCP-Server leben für den User-/Local-Scope in ~/.claude.json und für den Projekt-Scope in .mcp.json.)

Sobald verbunden, sieht der Agent die 14 Memory-Tools – remember, recall, recall_timeline, recall_full, improve, forget, build_pit, skill_add, skill_show, skill_list, skill_search, freshness_view, audit_log, follow_supersedes_chain (siehe The agent surface).

Der Observer (seahorse setup) ist ein separater Bestandteil: Er erfasst Claude-Code-Sitzungen als Episoden. Der MCP-Server ist die Art, wie der Agent Gedächtnis liest und schreibt. Beides prátiert zusammen – erfasse Sitzungen, dann ruf über Sitzungen hinweg ab.

Wie es funktioniert

graph LR
    A[Claude Code / any MCP agent] -- stdio MCP io.seahorse.memory/v1 --> S[seahorse-mcp]
    S --> E[Bi-temporal engine]
    E --> DB[(sqlite3 + sqlite-vec + FTS5)]
    E --> V[Obsidian vault: markdown + F3.1 frontmatter]
    H[Human in Obsidian] --> V

Ein Agent spricht über stdio-MCP mit seahorse-mcp. Die Engine speichert jede Episode zweimal: in einmal in einer Single-File-SQLite-Datenbank (sqlite-vec für Vektorsuche, FTS5 für Volltext) und einmal als Markdown-Datei mit F3.1-Frontmatter im Vault. Der Mensch bearbeitet diese (d) denselben Markdown. Das Format ist versioniert und in docs/f3.1-format.md beschrieben.

Schnellstart

# Install (PyPI):
pip install seahorse-memory
# …or with uv:
uv tool install seahorse-memory
# For hybrid semantic retrieval (FastEmbed ONNX, downloads mE5-small on first
# embed): pip install "seahorse-memory[embeddings]"
# For the multi-LLM extraction path (LiteLLM): pip install "seahorse-memory[llm]"

# Create a vault and write your first episode:
seahorse init myvault
seahorse remember "Sergio lives in Madrid" --title home
seahorse recall "madrid"

# Improve and forget (append-only; history is preserved):
seahorse improve <ep_id> "Sergio lives in Barcelona" --reason correction
seahorse forget <ep_id> --reason done

# Session capture, context, and consolidation:
# Install the observer (writes [observe] + merges the Claude Code hooks into
# ~/.claude/settings.json):
seahorse setup
# Start the observer (unix socket + worker), then the next session is captured
# automatically (skip-first, redacted, deterministic summary):
seahorse observe start
seahorse observe status
# Bootstrap context by recency (the SessionStart hook injects this):
seahorse context
# Distill recurrent episodes into semantic knowledge notes (N≥3, idempotent):
seahorse consolidate
# Remove the observer:
seahorse setup --uninstall

# Serve an agent over stdio MCP (io.seahorse.memory/v1):
seahorse-mcp --vault myvault
# …equivalently:
seahorse mcp --vault myvault

Das seahorse-Konsolenskript ist für den Menschen und Shell-Skripte gedacht; seahorse-mcp ist für Agenten. Der seahorse mcp-Unterbefehl startet denselben STDIO- Server wie seahorse-mcp, beide Einstiegspunkte sind also äquivalent. Um einen Agenten anzubinden, siehe Von einem Agenten aus verwenden.

Voraussetzungen

• Python ≥ 3.11 (jede aktuelle 3.11/3.12/3.13 funktioniert). Die sqlite3-Bibliothek des Interpreters muss enable_load_extension unterstützen (sqlite-vec (wertbewachs es); die meisten Standard-Builds tun das – seahorse doctor meldet das sonst als FAIL.

• Obsidian ist optional. Seahorse läuft auf jedem Markdown-Ordner – seahorse init erstellt ein .seahorse/-Verzeichnis in einem normalen Ordner. Obsidian ist eine menschenlesbare Oberfläche für denselben Ordner; sein .obsidian/-Verzeichnis wird von Seahorse ignoriert und niemals benötigt.

Migration eines bestehenden Obsidian-Vaults

Ein Vault mit bereits bestehenden Obsidian-Notizen (kein Frontmatter oder Legacy tags/created-Frontmatter) ist noch nicht im kanonischen Format – seahorse index rebuild schlägt an diesen Notizen regener. verschlagen. seahorse frontmatter migrate konvertiert sie:

# Preview: classify every note, write nothing (always exit 0):
seahorse frontmatter migrate --vault myvault --dry-run
# Apply: convert legacy notes, leave canonical notes untouched, refuse
# incompatible notes:
seahorse frontmatter migrate --vault myvault
# Rebuild the sidecar index from the converted notes:
seahorse index rebuild --vault myvault

apply beendet sich mit Exitcode 97, wenn inkompatible Notizen eine vollständige Migration blockieren – die Manifest-Zusammenfassung wird zuerst ausgegeben, damit die Betreiber sieht, welche Notizen eine manuelle Auflösung benötigen. --resume überspringt Notizen, die seit dem letzten Manifest unverändert sind; --batch-size legt den Takt der Manifest-Checkpoints fest. Migration funktioniert vor seahorse init (sie berührt nur .md-Dateien + das Manifest).

Erster Lauf**: Das semantische Embedding-Modell (mE5-small, ~235MB) wird faul beim ersten remember/recall geladen – die CLI kündigt das an, damit der erste Aufruf nicht wie ein Hänger aussieht. seahorse status zeigt das aktive Retrieval-Regime (hybrid RRF (model cached) vs. current-state listing — install seahorse-memory[embeddings] for semantic recall).

Im Vergleich zu anderen Memory-Tools

Ein Vergleich verifizierter Fakten, keine Rangliste. Quellen: Die State-of-the-Art-Analyse des Projekts (siehe Forschungsnotizen und die unten zitierten Angaben).

Legende: ✓ ja · ~ teilweise · ✗ nein · — nicht verifiziert.

Die zwei Fakten, die am meisten zählen sind: mem0 hinterlegt Paywallern die Funktionen, die seine Benchmark-Zahlen erzeugen, und Zep hat Self-Hosting zugunsten von Cloud-only aufgegeben. Seahorse ist standardmäßig Local-First, veröffentlicht seine Benchmark-Harness im Repo und hält das Speicherformat portabel – damit du nie gebunden bist.

Benchmark

Seahorse bringt einen reproduzierbaren Benchmark-Harness mit (LMEB-S, ein Untertheil des LongMemEval-Benchmarks) und veröffentlicht eigene Zahlen – mit Einschränkungen. Es geht nicht um eine Rangliste, sondern um eine ehrliche, reproduzierbare Messung.

Einschränkungen: Die Ausführung verwendet ein Subsample (n≈470–500 Fragen, nicht den gesamten Datensatz); die Relevanz wurde von einem kleinen LLM ohne menschliche Validierung bewertet; gemessen wird nur Retrieval, nicht die endgültige Antwort des Agenten. Ein Cross-Encoder-Rerank wurde evaluiert und abgeworfen – er verschlechterte den recall@10 auf 0,11 bei 1,2s Latenz. Genauer sitzt das Vorgehen und Reproduktionsbefehle in docs/benchmark.md.

Diese Zahlen messen nur die Retrieval-Relevanz an einem Subsample mit einem kleinen Bewerter – sie sind nicht vergleichbar mit den End-to-End-Genauigkeits-Scores anderer Memory-Systeme (z.B. Graphiti 63,8 %, Mem0 94.8, Hindsight 91,4%). Wie man sie nicht vergleichen sollte, steht in docs/benchmark.md.

FAQ

Was ist eine Episode? Ein einzelner Speicherdatensatz: eine Markdown-Datei mit YAML-Frontmatter, die zwei Zeitachsen enthält (valid_at – wann es wahr wurde, und created_at – wann es aufgezeichnet wurde), dazu Quellen-Angabe und einen kognitiven Typ. Das Format ist versioniert und in docs/f3.1-format.md dokumentiert.

Warum Obsidian? Weil der Mensch Teil des Memory-Systems ist. Der Agent schreibt in denselben Vault, an dem du arbeitest – Markdown ist lesbar, in Git diffbar und überprüfbar. Wenn der Agent falsch liegt, bist du es nicht ein Panel: du korrigierst die Notiz, nicht eine Datenbank.

Wie unterscheidet sich das von claude-mem? Zep... claude-mem speichert Beobachtungen in einem eigenen Schema. Seahorse ist ein offener, bi-temporaler Standard mit einem portablen Format und einer menschenlesbaren Ebene – und seahorse import migrationsit claude-mem-Beobachtungen in normalisierte Episoden. Es ist also eine Brücke, kein Konkurrent.

Brauche ich ein LLM? Nein. Der deterministische Skip-Pfad ist die Standardeinstellung für den Großteil der Schreibvorgänge (beinahe ohne Kosten). Die LLM-Extraktion ist optional (seahorse-memory[llm]) und bleibt den wenigen Episoden vorbehalten, die das rechtfertigen.

Ist es kostenlos? Ja. Apache-2.0, local-first, null zusätzliche Infrastruktur. Ein verwaltetes SaaS und eine Enterprise-Stufe sind für die Zukunft geplant (siehe die Strategiehinweise des Projekts).

Wie kann ich beitragen? Siehe CONTRIBUTING.md für das Entwicklungssetup, Test-/Lint-Befehle und den Pull-Request-Workflow.

Roadmap

Unter ROADMAP.md erfährst du, was bereits gebaut ist, was als Nächstes kommt und wohin sich das Projekt entwickelt. Die Versionshistorie findest du in CHANGELOG.md.

Die Agent-Oberfläche — 7 Memory-native Primitive + 7 prozedurale/schreibgeschützte Tools

Verfügbar über stdio MCP (io.seahorse.memory/v1, Protokoll fixiert auf 2025-11-25) und gespiegelt in der CLI. Das sind Speicher-Primitive, kein generisches CRUD: Ein Agent ruft remember / recall / improve / forget so auf, wie ein Mensch über Gedächtnis spricht.

Die 7 Primitive (Schreiben + Abrufen):

Plus 7 prozedurale / schreibgeschützte Werkzeuge (Skills + Fassaden-Inspektion):

Drei Abrufebenen ermöglichen progressive Offenlegung: Zuerst eine günstige Auflistung (INDEX), bei Bedarf die Kette (TIMELINE) und den vollständigen Datensatz nur, wenn er tatsächlich gebraucht wird (FULL). Das hält den häufigsten Pfad günstig.

Was funktioniert

• Bitemporaler, Append-only-Episodenspeicher auf der Standardbibliothek sqlite3 + sqlite-vec (FTS5

  • vec3). Automatisch migrierendes Schema.

• Die 7 Memory-native Primitive plus 7 prozedurale / schreibgeschützte Tools, sowohl in der CLI als auch über stdio MCP (insgesamt 14 Tools).

• Progressive Offenlegung (INDEX / TIMELINE / FULL) und Point-in-Time-Projektion.

• Hybrides semantisches Retrieval: recall ordnet nach Relevanz — sqlite-vec kNN + FTS5 BM25 fusioniert mit Reciprocal Rank Fusion, mit Point-in-Time-Routing (state_at / known_at), sobald ein echtes Embedder-Modell angebunden ist. Der Schreibpfad und seahorse index rebuild befüllen vec0/FTS (Best-Effort — ein Ausfall des Embedders lässt einen Episoden-Schreibvorgang nie fehlschlagen).

• Ehrliches Degradieren: Ohne das Extra embeddings (oder ohne befüllte Vektoren) fällt recall auf die Auflistung des aktuellen Zustands zurück (score 0.0, keine Reihung), und Point-in-Time-Abruf wird verweigert — die Engine arbeitet weiter, nur ohne Rangfolge.

• Optionales Decay-Ranking (standardmäßig aus): Eine FAMA-artige Ebbinghaus-Vergessenskurve gewichtet veraltetes Wissen nach Alter geringer (score’ = score · 2^(-age/half_life)), mit je Typ spezifischen Priors für die Halbwertszeit. Standardmäßig deaktiviert: Der reine RRF-Fingerabdruck bleibt bit-vergleichbar.

• LLM-Extraktion: Ein echter Multi-LLM-Pfad (ollama / gemini / groq / openrouter / openai / anthropic / deepseek / vllm, local-first) mit einem strikten Schema-Validator und Reparaturschleife, Wiederholungs-/Fallback-Kette und einer operationellen Kostenobergrenze (lokale und Free-Tier-Modelle kosten 0 $0). seahorse init --llm richtet den Pfad ein; der Skip-Pfad bleibt die nahezu kostenlose Standardeinstellung für den Großteil der Schreibvorgänge.

• Local-first CI-Gate: Der echte Extraktionspfad läuft in CI gegen das schwächste Modell der Familie (ollama/qwen3:0.6b), sodass Schema-Validator und Reparaturschleife die Last tragen müssen — der Pfad hängt nicht stillschweigend von nativeren strukturierten Ausgaben oder einem starken Modell ab.

• Ersetzung (Supersession) (improve) und Soft-Delete (forget) — vollständige Historie bleibt erhalten.

• Batch-Destillation (seahorse consolidate): Viele Episoden werden zu einer einzelnen konsolidierten Note destilliert — standardmäßig deterministisch, optional mit LLM-Synthese (--synthesis llm) und Supersession (--supersede), sodass die konsolidierte Notiz ihre Quellen ersetzt.

• Frontmatter-Import/-Export für die Obsidian-Vault-Ebene (Markdown als der menschenlesbare, portabler Vertrag auf der Platte).

• Legacy-Vault-Migration: seahorse frontmatter migrate konvertiert alte Obsidian-Notizen mit einer --dry-run-Vorschau, --resume und ehrlichem Exit 97, wenn ungeeignete Notizen eine vollständige Migration blockieren.

• Ehrliche Exit-Codes und eine strukturierte {"error": {...}}-Hülle auf stderr, damit Agenten beziehungsweise Skripte deterministisch auf seahorse_code / cli_code verzweigen können.

Einige CLI-Befehle sind verdrahtet, geben aber absichtlich Exit 75 mit einer Begründung zurück (expire, revalidate, index verify). So ist die Oberfläche ehrlich darüber, was noch nicht implementiert ist, statt stillschweigend nichts zu tun. llm_partial bleibt vollständig reserviert.

Stack

• Python ≥ 3.11. Standardbibliothek sqlite3 + sqlite-vec für die Speicherung (eine einzige Datei ohne Infrastruktur; virtuelle vec0-Tabelle + S5).

• numpy für die Form der Embedding-Blobs.

• Pydantic v2 für den kanonischen Episode-Vertrag (zentrales Typsystem).

• Typer für die CLI-Oberfläche (Menschen und Skripte). Beschränkt auf seahorse.cli.

• stdio JSON-RPC 2.0 für die MCP-Agent-Oberfläche (von Hand gesetzte Framing, nur Stdlib; seahorse .mcp-Paket — import seahorse.mcp lädt Typer nicht).

• ruamel.yaml + python-frontmatter, beschränkt auf den Frontmatter-Adapter.

• FastEmbed ONNX + onnxruntime (embeddings-Extra, NICHT in der Standardinstallation): Das mE5-small-Bundle verwendet standardmäßig model_O4.onnx (fp32, ~235MB) — kein int8/fp16-Artefakt ist auf Apple Silicon portabel, und ein offener Standard muss auf Windows/Linux/macOS laufen. Ein portables int8-Bundle ist ein vermessener Folgebeitrag.

• LiteLLM (llm-Extra, NICHT in der Standardinstallation): Vereinheitlicht die 100+-Provider-Oberfläche für den LLM-Extraktionspfad. Ohne das Extra importiert seahorse.llm weiterhin (Vertrag + StubLLMClient) und der echte Pfad degradiert von llm → skip mit einem Einrichtungshinweis.

Der FastAPI / SQLAlchemy / Postgres-Stack ist für eine spätere Multi-Agent-Stufe geplant (Postgres + pgvector). Die README beschreibt, was gerade mitgeliefert wird, nicht die Zielarchitektur.

Tests

• Unit + Integration: uv run pytest (Coverage ≥ 80 % als Gate).

• Fresh-User-E2E: scripts/e2e-fresh-user.sh — den vollständigen Ablauf Installation → Init → Core-CLI → Embeddings → LLM → Import → MCP in einem sauberen, isolierten HOME (der nie das echte ~/.claude / ~/.claude-mem anfasst).

• Umgebungsmatrix: scripts/e2e-matrix.sh — der Fresh-User-Ablauf über Umgebungskombinationen (Installationsmethode × Extras × Obsidian × Ollama × online/offline × Vault-Zustand × Konkurrenz). --ci-subset führt die CI-sichere Kombinationen aus (core_min + uv_sync_dev); --list zeigt alle Kombinationen.

• Core-Stress: scripts/stress-core.sh — Erfassung von 1000+ Episoden, recall --top-k 100 p95 ≤ 250 ms (In-Process-INDEX-Budget), konkurrierender Single-Writer, Reindex, idempotenter Import, Improve/Forget-Kette.

Mitwirken

Beiträge sind gerne gesehen. Siehe CONTRIBUTING.md für Entwicklungssetup, Test/Lint-Befehle und Pull-Request-Workflow. Die Versionshistorie liegt in CHANGELOG.md.

Lizenz

Apache-2.0. Siehe LICENSE.

Aktueller Status

v0.10.0. Die Gedächtnis-Engine funktioniert von einer sauberen Installation bis zum Ende durch: Episoden schreiben, sie mit hybridem semantischem Retrieval abrufen, mit echtem Multi-LLM-Pfad extrahieren (local-first, CI-gestützt), verbessern und löschen — und einen Agenton über stdio MCP bedienen. recall sortiert nach Relevanz, wenn Vektoren befüllt sind und das benutzte Modell angebunden ist, und degradiert andernfalls ehrlich zu einer Auflistung des aktuellen Zustands. Ein optionales Decay-Ranking (standardmäßig aus) gewichtet veraltetes Wissen nach Alter. seahorse import migriert claude-mem-Beobachtungen zu Episoden, und die Batch-Destillation (seahorse consolidate) macht aus vielen Episoden eine konsolidierte Note, optional mit LLM-Synthese und Supersession. Der Benchmark-Harness wird im Repository zusammen mit Hinweisen und Reproduktionsbefehlen in docs/benchmark.md ausgeliefert. Siehe Was funktioniert und ROADMAP.md für das, was als Nächstes ansteht.