agentcairn MCP Server

offiziell

Lokale, agentenbasierte Speicherung: Ein reines Markdown-Obsidian-Vault dient als Quelle der Wahrheit, mit einem wiederaufbaubaren DuckDB-Index für hybriden BM25- + Vektor- + Graph-Abruf.

GitHub
1

Dokumentation

🪨 agentcairn

CI Security PyPI Python License: Apache-2.0

Lokal-first Speicher für KI-Agenten – den Sie tatsächlich lesen, bearbeiten und besitzen können.

cairn  /kɛən/  · Substantiv — ein Steinhaufen, der errichtet wurde, um einen Pfad oder einen erinnerungswürdigen Ort zu markieren, hinterlassen für diejenigen, die nachfolgen.

agentcairn gibt Ihrem Coding-Agenten ein dauerhaftes, hochwertiges Gedächtnis – aber anstatt es in einer undurchsichtigen Datenbank oder einem Cloud-Dienst einzuschließen, leben Ihre Erinnerungen als einfaches Markdown in einem Obsidian-Vault, den Sie besitzen. Ein schneller, wiederherstellbarer DuckDB-Index sitzt zur Abfrage darüber. Öffnen Sie Ihren Vault, lesen Sie, woran sich der Agent erinnert hat, korrigieren Sie eine falsche Tatsache von Hand oder fügen Sie Ihre eigenen Notizen hinzu – und der Agent greift alles auf.

Warum agentcairn anders ist

Die meisten Agent-Memory-Systeme machen eine Datenbank oder einen Cloud-Speicher zur Quelle der Wahrheit und behandeln Dateien (falls vorhanden) als Einweg-Export. agentcairn kehrt das um:

  • 📂 Ihr Vault ist die Quelle der Wahrheit – kein Export. Das Gedächtnis ist menschenlesbares Markdown mit Frontmatter und [[wikilinks]]. Bearbeiten Sie es in Obsidian; der Index respektiert Ihre Änderungen.
  • ♻️ Der Index ist entbehrlich. DuckDB ist ein wiederherstellbarer Cache (cairn reindex). Ihr Gedächtnis übersteht ein Modell-Upgrade, einen beschädigten Index, eine Schemaänderung oder die Deinstallation des Tools – kein Datenverlust, denn die Wahrheit sind nur Dateien auf der Festplatte.
  • 🧠 Konstruktionsbedingt verlustfrei. Die vollständige Notiz bleibt immer erhalten. Die Destillation fügt nur abgeleitete Notizen hinzu, die auf die Quelle zurückverweisen – sie verwirft niemals stillschweigend Fakten, die sie zum Zeitpunkt des Schreibens nicht zu extrahieren gedachte.
  • 🔒 Schwärzung vor jedem Schreibvorgang. Geheimnisse werden bereinigt (Regex + Entropie + URL-Anmeldeinformationserkennung), bevor irgendetwas – Text, Titel oder Tags – den Klartext-Vault erreicht. Wir schreiben Dateien, die Sie lesen können, daher behandeln wir ein durchgesickertes Geheimnis als den schlimmsten Fehlermodus.
  • 🕸️ Ein freier, deterministischer Wissensgraph. Ihre [[wikilinks]] und Frontmatter sind der Graph – keine LLM-Extraktion, keine halluzinierten Entitäten.
  • 🪶 Daemonlos, keine externe DB. Eine eingebettete DuckDB-Datei führt semantische Vektorsuche, BM25-Volltextsuche und Graph-Traversierung durch. Kein ständig laufender Server, kein Neo4j/Postgres/Qdrant, kein erforderlicher Cloud-Schlüssel – nur eine cairn CLI und ein On-Demand-MCP-Server.
  • 🔍 Ehrlich gemessen. Ein reproduzierbarer LongMemEval-S + LoCoMo-Testrahmen wird in benchmarks/ mitgeliefert – mit echten Zahlen, Ablationen und expliziten Vorbehalten anstelle einer einzigen herausgepickten Schlagzeile (siehe unten).

Installation

Der einfachste Weg, agentcairn zu nutzen, ist das Plugin für Claude Code oder Codex – eine Installation verbindet den MCP-Server, das Umgebungsgedächtnis (Abruf zu Sitzungsbeginn, Erfassung am Sitzungsende), eine Gedächtnisfähigkeit und Slash-Befehle (Claude Code):

# Claude Code
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

# Codex (from the Codex plugin marketplace)
codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Bei der Installation wählen Sie einen Vault-Pfad (Standard ~/agentcairn); er wird automatisch in der ersten Sitzung erstellt – keine Obsidian-Einrichtung erforderlich. Von da an zeigt agentcairn zu Beginn jeder Sitzung relevante Erinnerungen an, destilliert jede Sitzung in Ihren Vault und gibt Ihnen /agentcairn:recall, /remember, /memory, /savings und /ingest. Nichts muss per pip installiert werden – das Plugin führt das veröffentlichte Paket über uvx aus.

Nicht auf Claude Code oder Codex? agentcairn ist auch ein eigenständiger MCP-Server + CLI für jeden Host – siehe Direkte Nutzung.

Funktionsweise

flowchart LR
    T["Session transcripts<br/>(out-of-band)"]
    H["You · Obsidian<br/>(hand edits)"]
    V["📂 Obsidian vault<br/>Markdown + frontmatter + wikilinks<br/><b>source of truth</b>"]
    I["♻️ DuckDB index<br/>vector + BM25 + graph<br/><b>rebuildable cache</b>"]
    M["MCP tools<br/>remember · recall · search · build_context · recent"]

    T -- "redact → judge → distill → consolidate" --> V
    H -- "edit" --> V
    V -- "parse / reconcile-on-spawn" --> I
    I -- "READ_ONLY hybrid recall" --> M
    M -. "remember (redacted write)" .-> V

    classDef truth fill:#eaf1ff,stroke:#317cff,color:#191919;
    classDef cache fill:#f5f5f3,stroke:#999999,color:#191919;
    class V truth
    class I cache
  • Erfassung liest die Sitzungstranskripte Ihres Agenten-Harness (nur anhängend, bereits auf der Festplatte) out-of-band – robust durch Design, ohne fragile Live-Hooks – dann Schwärzung → Deduplizierung → Beurteilung (semantische Haltbarkeit; optionale LLM-Destillation über CAIRN_JUDGE=anthropic) → Filterung → Destillation in den Vault, verlustfrei. cairn sweep erkennt automatisch jeden vorhandenen Harness (Claude Code, Codex, Antigravity CLI und Cursor werden alle unterstützt, hinter einer HarnessAdapter-Nahtstelle), sodass Sie einheitlichen Speicher über alle vier hinweg ohne zusätzliche Konfiguration erhalten. Auf der LLM-Stufe wird auch konsolidiert: eine neue Erinnerung, die eine bestehende dupliziert, wird übersprungen, und eine neuere Version einer sich entwickelnden Tatsache markiert die ältere Notiz als superseded_by (behalten + im Abruf herabgestuft, niemals gelöscht) – ausfallsicher, sodass ein falscher Aufruf niemals eine eigenständige Erinnerung verwirft (CAIRN_CONSOLIDATE=0 zum Deaktivieren). Plus ein agentengesteuertes remember-Werkzeug für kuratierte, hochwertige Erinnerungen.
  • Abruf fusioniert BM25 + semantische Vektoren mit Reciprocal Rank Fusion, wendet einen optionalen Graph-Boost an und degradiert anmutig auf Nur-Schlüsselwort, wenn kein Einbettungsmodell verfügbar ist – sodass der Abruf niemals stillschweigend ausfällt. Ein optionaler Cross-Encoder Reranker erhöht die Präzision.
  • Hybride Intelligenz: Offline-lokale Einbettungen (standardmäßig FastEmbed / nomic-embed-text-v1.5) sofort einsatzbereit – stark für sich allein und in der hybriden Fusion (mit nomic übertrifft Vektor-only BM25 selbst bei kurzen Turns; siehe Benchmark). Setzen Sie CAIRN_EMBED_MODEL, um ein anderes FastEmbed-Modell auszuwählen, oder führen Sie CAIRN_EMBEDDER=ollama / eine Cloud-Stufe aus, um weiter zu gehen.
  • Zeitliches Gedächtnis: Notizen können valid_from/valid_until/superseded_by-Frontmatter enthalten. Der Abruf ist gültigkeitsbewusst – er stuft abgelöste und abgelaufene Fakten sanft herab (der aktuelle Fakt gewinnt), ohne sie jemals zu verstecken (verlustfrei), und annotiert den Status jedes Ergebnisses (current/superseded/expired/not_yet_valid) plus einen as_of-Anker, sodass der Agent über die Zeit hinweg schlussfolgern kann. Inert für Notizen ohne Gültigkeitsfelder.
  • Herkunftsbewusster Abruf: Notizen tragen project/harness-Herkunft, und der Abruf verstärkt die Erinnerungen Ihres aktuellen Projekts (verlustfrei – projektübergreifende Treffer erscheinen weiterhin, markiert als [from: <project>]). Übergeben Sie --project <repo>, um ein anderes Repository anzuvisieren, oder --scope project, um hart auf nur das aktuelle zu filtern.

Direkte Nutzung

Das Plugin ist der einfachste Weg, aber agentcairn ist nur ein Paket – nutzen Sie es ohne Claude Code über den On-Demand-MCP-Server (für jeden MCP-Host) oder die cairn CLI:

uvx agentcairn                                       # on-demand MCP server for any MCP host
cairn ingest --vault ~/vault                         # distill recent agent sessions into the vault
cairn sweep  --vault ~/vault                          # ingest + reindex in one pass (cron-friendly)
cairn schedule install --vault ~/vault                # run sweep automatically every 30 min (launchd on macOS, crontab on Linux)
cairn recall "how did we fix the auth bug?"          # hybrid recall from the CLI
cairn savings                                        # how much context recall has saved you
cairn reindex ~/vault                                # rebuild the index from Markdown (always safe)
cairn doctor                                         # health-check the index

Konfiguration

Alle Einstellungen befinden sich in einer Datei – ~/.agentcairn/config.toml – mit Umgebungsvariablen als Überschreibungen (Rangfolge: CLI-Flag > Umgebungsvariable > Konfigurationsdatei > Standard):

cairn config --init   # scaffold a fully-commented template (chmod 600)
cairn config          # show every setting's effective value and where it came from

Um beispielsweise den LLM-Speicherrichter zu aktivieren, genügen zwei unkommentierte Zeilen – keine Shell-Exporte erforderlich (der Hintergrunddurchlauf des Plugins liest die Datei direkt):

judge = "anthropic"
anthropic_api_key = "sk-ant-..."

Unterstützte Agenten

agentcairn arbeitet auf zwei Ebenen. Plugin-Hosts (Claude Code, Codex und Antigravity) erhalten ein erstklassiges Plugin – einen gebündelten MCP-Server (Abruf/Suche/remember), eine Gedächtnisfähigkeit und (auf Claude Code und Codex) Umgebungs-Sitzungs-Hooks; cairn install <host> installiert das Plugin durch Aufruf der eigenen CLI des Hosts. MCP-Hosts (alles andere) erhalten dieselben Abruf-/Suche-/remember-Werkzeuge über den portablen MCP-Server; cairn install <host> schreibt die MCP-Server-Konfiguration zerstörungsfrei (Ihre anderen Server bleiben erhalten, das Original wird unter <config>.bak gesichert). Der Vault bleibt ein einziger globaler ~/agentcairn, sodass der Speicher über jeden Host hinweg geteilt wird.

HostUnterstützungEinrichtung mitUmgebungserfassung
Claude Code🟢 Plugincairn install claude-code✅ Abruf-zu-Beginn + Erfassung-am-Ende
Codex🟢 Plugincairn install codex◐ Abruf/remember live; Umgebungs-Hooks gebündelt (Überprüfung) 1
Cursor🔌 MCP-Server + Fähigkeit + Aufnahmecairn install cursor◐ cairn sweep erkennt Transkripte automatisch 2
Claude Desktop🔌 MCP-Servercairn install claude-desktop—
VS Code (Copilot)🔌 MCP-Servercairn install vscode—
Gemini CLI 3🔌 MCP-Servercairn install gemini—
Antigravity🟢 Plugin + Aufnahmecairn install antigravity◐ cairn sweep erkennt Transkripte automatisch 4
Jeder andere MCP-Host🔌 MCP-Serveruvx agentcairn (fügen Sie das cairn install … --print-Snippet ein)—

cairn install leitet automatisch nach Host-Typ weiter:

cairn install                 # detect installed hosts + preview (writes nothing)
cairn install codex           # install the Codex plugin (shells to `codex plugin …`; strips any stale MCP block from ~/.codex/config.toml)
cairn install antigravity --source ./plugin  # install the Antigravity plugin from a local checkout (see note)
cairn install cursor          # write MCP config + install the memory skill for Cursor
cairn install --all           # configure every detected host
cairn install codex --source /path/to/agentcairn  # use a local checkout instead of the marketplace

MCP-Hosts erhalten einen JSON mcpServers-Eintrag (VS Code verwendet seinen servers-Schlüssel). Plugin-Hosts (Claude Code, Codex, Antigravity) installieren das Plugin über die Host-CLI – der MCP-Server ist im Plugin gebündelt und benötigt keinen separaten Konfigurationseintrag. Wenn Sie zuvor cairn install antigravity verwendet haben, um einen MCP-Eintrag in ~/.gemini/config/mcp_config.json zu schreiben, entfernt ein erneutes Ausführen von cairn install antigravity diesen veralteten Eintrag automatisch.

Benchmarks gemessen

Wir benchmarken agentcairn so, wie wir ein Speichersystem gemessen haben möchten – reproduzierbar, mit Ablationen und ohne eine einzige herausgepickte Schlagzeilenzahl. Der Testrahmen (benchmarks/) führt LongMemEval-S und LoCoMo durch einen versionsfixierten Downloader aus (Datensätze werden niemals mitgeliefert), bewertet den Abruf deterministisch (Recall/nDCG@k, MRR – kein API-Schlüssel erforderlich, läuft in CI auf einer synthetischen Vorrichtung) und bietet eine optionale LLM-beurteilte QA-Schicht.

Abruf — LoCoMo

Vollständiger LoCoMo-Satz, Turn-Ebene, Makro-Durchschnitt, FastEmbed nomic-embed-text-v1.5 (der Standard-Embedder):

ArmRecall@5Recall@10MRR
Nur BM250.5270.6040.459
Nur Vektor0.5360.6370.433
Hybrid (RRF)0.5620.6480.477
Hybrid + Graph-Boost0.5620.6480.477
Hybrid + Reranker0.6620.7350.608

Was wir daraus lesen – und offen aussprechen:

  • Hybrid schlägt jeden einzelnen Arm – RRF-Fusion lohnt sich.
  • Der Cross-Encoder Reranker ist der größte Hebel (+0.10 Recall@5 gegenüber Hybrid); die Sorge "ms-marco Domain-Shift könnte schaden" hat sich bei Konversationsdaten nicht bewahrheitet.
  • Der Embedder-Standard zieht jetzt sein Gewicht – mit nomic übertrifft Vektor-only BM25 (0.536 vs. 0.527); der Wechsel vom alten bge-small-Standard (der bei 0.483 zurücklag) schloss die Lücke. Ein 5-Modell-FastEmbed-Durchlauf bestimmte die Wahl – nomic (768-d) gewinnt bei Qualität pro Dimension; größere 1024-d-Modelle schlagen es nicht. Vollständige Tabelle: benchmarks/README.md.
  • Graph-Boost ist auf diesen Korpora inert – LoCoMo/LongMemEval haben keinen nativen [[wikilink]]-Graphen, sodass der Boost nichts zum Auslösen hat. Er ist für echte, verlinkte Vaults, nicht für Chat-Protokolle, und wir geben nicht vor, dass es anders ist.

Abruf — LongMemEval-S

Voller 500-Instanzen-Satz — eine einfachere Aufgabe mit klar getrennten Evidenz-Sitzungen. Die Sitzungsebene ist die Granularität, die frühere Arbeiten berichten; die Turn-Ebene ist die feinere, korpusoffenbarende Scheibe:

armsession r@5session MRRturn r@5turn r@10turn MRR
Nur BM250.9200.9180.6800.7910.638
Nur Vektor0.9360.9160.5070.6920.454
Hybrid (RRF)0.9540.9380.6400.7980.544
Hybrid + Reranker0.9690.9630.7880.8910.716

Ehrlich gelesen:

  • Unser session recall@5 von 0.969 liegt direkt neben dem ≈0.95 früherer Arbeiten über denselben vollen 500-Fragen-Satz — und im vollen Maßstab diskriminiert er (0.920 BM25 → 0.969 Reranker), anstatt zu sättigen, wie es eine kleine Stichprobe tut.
  • Der Reranker ist erneut der größte Hebel — turn r@5 0.640 → 0.788, session r@5 0.954 → 0.969.
  • Die Turn-Ebene ist korpusoffenbarend: hier schlägt Nur-BM25 (0.680) den RRF-Hybrid (0.640), weil Nur-Vektor bei diesen Single-Turn-Evidenzspannen schwach ist (0.507); der Reranker zieht den Standard nach vorne. (Im Gegensatz zu LoCoMo, wo Nur-Vektor BM25 knapp übertrifft.)

Kontexteffizienz

Wie viel kleiner ist der Kontext, den agentcairn erinnert, als die vollständige Historie, die man sonst in das Modell tragen würde? Standardkonfiguration (Hybrid + Reranker, k=10):

DatensatzAbfragenmittlerer Heuhaufenmittlerer erinnerter (k=10)Kontextreduktion
LoCoMo (3 Gespräche)49725.646 Tok529 Tok51,1× Mittel / 50,3× Median
LongMemEval-S (voll 500)470136.552 Tok2.207 Tok64,7× Mittel / 61,6× Median

Schätzung (~4 Zeichen/Token), keine abgerechneten Kosten; „Heuhaufen“ = die vollständige indexierte Historie, „erinnert“ = die zurückgegebenen Top-k-Chunks. Es misst die Kontextgröße, unabhängig von der Retrieval-Qualität.

QA-Genauigkeit

QA-Genauigkeitszahlen (LLM-beurteilt) sind ebenfalls verfügbar, verwenden jedoch einen Anthropic-Richter anstelle des GPT-4o der Papers, daher sind sie nicht mit veröffentlichten Bestenlisten vergleichbar — nur gültig für relatives Ablationssignal. Siehe benchmarks/README.md für die Ausführung und das Lesen der Zahlen.

Roadmap

  • v1 — fertig. Der Kernkreislauf: Transkriptaufnahme → Schwärzung → Markdown → wiederaufbaubarer DuckDB-Index → hybrider Recall; MCP-Server + CLI; geheime Schwärzung; lokale Embeddings; reproduzierbarer Benchmark-Harnisch.
  • v1.1 — als nächstes, priorisiert durch den obigen Benchmark:
    • ✅ Reranker standardmäßig an — der größte gemessene Retrieval-Hebel; CAIRN_RERANK=0 zum Deaktivieren. (ausgeliefert)
    • Ollama-Embedding-Stufe — ✅ lokale Modelle über CAIRN_EMBEDDER=ollama (CAIRN_EMBED_MODEL/OLLAMA_HOST); Cloud (OpenAI/Voyage) noch ausstehend.
    • ✅ Bitemporale Gültigkeit — Frontmatter valid_from/valid_until/superseded_by; Recall stuft überholte/abgelaufene Fakten weich herab (verlustfrei — niemals versteckt) und annotiert die Aktualität jedes Ergebnisses + einen as_of-Anker, sodass die aktuelle Tatsache gewinnt und der Agent über die Zeit hinweg schlussfolgern kann. (ausgeliefert)
    • In-Memory-HNSW für Retrieval-Latenz bei großen Vaults.
  • v2 — ◐ Obsidian-Plugin (agentcairn-obsidian) — eine Vault-native Memory-Ansicht (Liste + Herkunft + Aktualität + Graph) zum Lesen/Navigieren Ihres Gedächtnisses in Obsidian; (MVP ausgeliefert; semantischer Recall verbleibt in CLI/MCP). MotherDuck-Cloud-Sync, optionale LLM-Entitätsextraktion noch ausstehend.

Entwicklung

agentcairn verwendet uv ausschließlich für Abhängigkeitsverwaltung und Tooling.

Verwenden Sie nicht pip, poetry oder globale virtuelle Umgebungen.

# First-time setup
uv sync                         # create .venv and install all deps (including dev)
uv run pre-commit install       # install git hooks (ruff + pytest run on every commit)

# Daily use
uv run pytest                   # run the test suite
uv run cairn --help             # run the CLI
uvx agentcairn                  # run the installed tool ephemerally (as the MCP server does)

# Formatting and linting
uv run ruff format .            # format all Python files
uv run ruff check --fix .       # lint with auto-fix
uv run pre-commit run --all-files

# Benchmarks (offline retrieval metrics need no API key)
uv run pytest benchmarks/tests/                                      # offline synthetic-fixture suite
PYTHONPATH=benchmarks uv run --group bench python -m cairn_bench.run --dataset locomo

Der MCP-Server wird über uvx agentcairn gestartet — keine globale Installation erforderlich.

Lizenz

Apache License 2.0 — freizügig, mit ausdrücklicher Patentgewährung. Copyright © 2026 Charles C. Figueiredo.

Footnotes

  1. The Die Codex-Plugin-Installation und sein gebündelter MCP-Server (Abruf/Suche/remember) werden live in Codex verifiziert. Die Umgebungs-Sitzungs-Hooks (Abruf-zu-Beginn, Erfassung-am-Ende) werden im Plugin ausgeliefert und verwenden das dokumentierte Hook-Schema von Codex, aber ihr Verhalten auf Codex ist noch nicht Ende-zu-Ende bestätigt; die Erfassung erfolgt unabhängig davon auch out-of-band über cairn sweep. ↩

  2. Cursor hat keine Plugin-Hooks, daher erfolgt die Umgebungserfassung out-of-band über cairn sweep (Quelle: Cursors globale globalStorage/state.vscdb SQLite-Datenbank, Tabelle cursorDiskKV, Benutzer "bubbles"). Cursor bleibt ein MCP-Host für die Ausgabe (cairn install cursor → ~/.cursor/mcp.json); es gibt kein Cursor-Plugin. cairn install cursor installiert auch die using-agentcairn-memory-Fähigkeit (Abruf-/Erinnerungsanleitung) nach ~/.cursor/skills/using-agentcairn-memory/SKILL.md. ↩

  3. Gemini CLI (Consumer) Transkript-Aufnahme wird nicht unterstützt – Google stellt die Gemini CLI ein (Consumer-Einstellung 2026-06-18) zugunsten der Antigravity CLI, die agentcairn stattdessen aufnimmt. cairn install gemini (MCP-Server-Verdrahtung) bleibt für jeden Gemini-basierten Host gültig, der MCP spricht. ↩

  4. The Das Antigravity-Plugin bündelt den MCP-Server + Gedächtnisfähigkeit; cairn install antigravity --source <dir> installiert es über agy plugin install und entfernt jeden veralteten mcpServers.agentcairn-Eintrag aus ~/.gemini/config/mcp_config.json. Hinweis: agy plugin install benötigt ein lokales Verzeichnis oder einen registrierten Marktplatz (kein Git-Repo), richten Sie --source daher vorerst auf das plugin/-Verzeichnis eines geklonten Checkouts. Antigravity hat keine anerkannten Plugin-Hooks, daher erfolgt die Umgebungserfassung out-of-band über cairn sweep (Pfad: ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript.jsonl). ↩