agentcairn

Ein dauerhaftes Gedächtnis für unterstützte Coding-Agenten.
Dein Markdown-Vault ist kanonisch. DuckDB ist der ersetzbare Retrieval-Cache.

Website · PyPI · Obsidian-Begleiter · Benchmarks

Ein Steinhaufen (Cairn) markiert einen Weg für alle, die als Nächstes kommen. agentcairn tut das für Coding-Agenten: Es erfasst dauerhaften Kontext aus den Werkzeugen, die du verwendest, speichert ihn als überprüfbares Markdown mit Herkunftsnachweis und ruft nur die relevantesten Teile ab, wenn ein anderer Agent sie benötigt.

Beweis, den du überprüfen kannst

Das Gedächtnis ist nicht hinter einer Admin-Konsole oder einer gehosteten Datenbank verborgen. Der separate agentcairn-obsidian-Begleiter liest dieselben Markdown-Dateien wie die Agenten und zeigt Herkunft, Aktualität, Wichtigkeit, Ersetzung und related:-Links an.

_{Ein echter agentcairn-Vault in Obsidian. Die Liste ist eine Ansicht über die Dateien – kein zweiter Speicher.}

Dogfood-Schnappschuss · 2026-07-15. Bei 417 lokalen Abrufen lieferte der Vault des Maintainers Kontext mit 262× smaller als das Laden des gesamten Vaults jedes Mal – geschätzt 136.6M tokens of full-vault context avoided in der Summe. Token-Zählungen verwenden ungefähr vier Zeichen pro Token. Dies sind keine abgerechneten Token-Ersparnisse, und agentcairn sendet keine Telemetrie.

Installation

Der kürzeste Weg ist ein erstklassiges Plugin. Es bündelt den MCP-Server, die Gedächtnis-Fähigkeit und die hostspezifischen Umgebungs-Hooks – keine separate agentcairn-Paketinstallation. Das Plugin startet über uvx, also installiere zuerst uv, falls uvx --version nicht bereits verfügbar ist.

Claude Code

claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

Claude Code erhält pro Turn projektbezogenen Abruf, Sitzungs-/Kompaktierungserfassung und die /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings und /agentcairn:ingest-Befehle.

Codex

codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Codex erhält die gebündelten MCP-Werkzeuge und die Gedächtnis-Fähigkeit, live verifizierten SessionStart-Abruf und SessionEnd-Erfassung mit cairn sweep als Out-of-Band-Absicherung.

Agentenunterstützte Einrichtung

Verwendest du bereits skills.sh oder einen find-skills-Workflow? Installiere den öffentlichen Einrichtungsassistenten:

npx skills add ccf/agentcairn --skill agentcairn-setup -g

Frage dann deinen Agenten: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Dies installiert nur Einrichtungsanleitungen – nicht die AgentCairn-Laufzeit, den MCP-Server, das Plugin oder die Hooks. Der Assistent delegiert diese Änderungen an den Preview-First-nativen Installer von AgentCairn und verifiziert die resultierende Integration. Die Plugin-Befehle für Claude Code und Codex oben bleiben der kürzeste Weg.

Der Standard-Vault ist ~/agentcairn und wird bei der ersten Verwendung erstellt. Ein neuer leerer Vault hat noch nichts Nützliches abzurufen, also beweise die gesamte Schleife explizit:

You   → Remember this durable fact: staging deploys use blue-green.
Agent → written and indexed
You   → Recall the staging deploy strategy.
Agent → staging deploys use blue-green.  ↳ <memory permalink>

remember schreibt die Markdown-Notiz und den Indexeintrag zusammen, sodass sofortiger Abruf Teil des Vertrags ist. Der erste lokale Lauf kann die konfigurierten Einbettungs-/Reranking-Modelle herunterladen und aufwärmen.

Der Vertrag

So funktioniert es

• Erfassen: Host-Hooks verbessern die Unmittelbarkeit; cairn sweep liest unterstützte Transkript-Speicher Out-of-Band als dauerhafte Absicherung. AgentCairn schwärzt erkannte Anmeldedaten, dedupliziert, wertet nach Wichtigkeit aus und destilliert vor den automatisierten Klartext-Schreibvorgängen.
• Abgleichen: Der erste Lesevorgang bringt den Vault-bezogenen Index transaktional mit Markdown in Sync. Ein fehlgeschlagener Neuaufbau bewahrt den letzten guten Cache, und die dauerhaften Dateien bleiben unberührt.
• Abrufen: BM25- und semantische Vektoren werden mit Reciprocal Rank Fusion fusioniert und dann optional neu gerankt. Modell-/Anbieterfehler fallen sichtbar auf BM25 mit Diagnosen zurück, anstatt inkompatible Vektoren zurückzugeben.
• Merken: Das MCP-Werkzeug schreibt atomar eine Markdown-Notiz und aktualisiert den Index unter einer einzigen Writer-Sperre, wodurch ein erfolgreicher Speichervorgang sofort abrufbar wird.

Für Vertrauen entwickelt

• Standardmäßig lokal. FastEmbed läuft lokal, der MCP-Server verwendet stdio, es gibt keinen erforderlichen Daemon oder externe Datenbank und keine Telemetrie.
• Klare Grenzen. Der synchronisierte Vault enthält Markdown; standardmäßig bleibt der neu aufbaubare .duckdb-Index außerhalb davon. Vault-Symlinks, die aus dem konfigurierten Stammverzeichnis entkommen, werden abgelehnt.
• Zeitbewusste Korrekturen. valid_from, valid_until und superseded_by halten alte Beweise sichtbar, während aktuelle Fakten zuerst eingestuft werden.
• Deterministischer Graph. [[wikilinks]] und optionale cairn link-Nachbarn erstellen einen Obsidian-nativen Graphen, ohne ein LLM zu bitten, Entitäten zu erfinden.
• Projektbewusster Abruf. Das aktuelle Projekt wird standardmäßig hervorgehoben; projektübergreifende Ergebnisse bleiben verfügbar und werden gekennzeichnet. Automatischer Abruf ist projektbezogen, es sei denn, du entscheidest dich explizit für alle Projekte.

Unterstützte Agenten

Jeder Host löst denselben konfigurierten Vault auf. cairn install zeigt erkannte Hosts ohne Schreiben an. MCP-Konfigurationsschreibvorgänge sind Backup-First und bewahren nicht verwandte Server; Plugin-Host-Installationen delegieren an die eigene CLI des Hosts.

Codex SessionStart wurde live Ende-zu-Ende mit agentcairn 0.24.2 / Plugin 0.1.2 verifiziert. Der installierte SessionEnd-Befehlsversand und der getrennte Sweep bestehen exakte Handler-Tests; cairn sweep bleibt die Out-of-Band-Erfassungsabsicherung. Siehe die OpenCode-Integration und Hermes-Integration für deren native Lebenszyklusdetails.

Direkte Verwendung

Das Plugin ist der einfachste Weg, aber agentcairn ist auch ein eigenständiges CLI und ein On-Demand-MCP-Server. Eigenständige Installationen erfordern Python 3.11+.

uv tool install agentcairn

cairn init ~/agentcairn
cairn sweep --vault ~/agentcairn
cairn recall "how did we fix the auth bug?" --vault ~/agentcairn
cairn doctor --vault ~/agentcairn

Claude Codes Gedächtnis mitbringen

Claude Codes Auto-Memory kann den gemeinsamen Vault seeden, ohne seine Quelldateien zu ändern. Der Befehl zeigt standardmäßig nur das aktuelle Repository an; füge --apply hinzu, um die geschwärzten Notizen zu schreiben und den Index zu aktualisieren.

cairn import claude-memory                         # preview; writes nothing
cairn import claude-memory --apply                 # import this repository
cairn import claude-memory --project ../other --apply

Der Einweg-Import liest MEMORY.md und seine Themen-Markdown-Dateien – niemals CLAUDE.md oder .claude/rules/. Importierte Notizen behalten Claude-Code-, Projekt- und Quelldatei-Herkunft. Wenn sich eine Quelle ändert, bleibt die vorherige Version überprüfbar, wird aber ersetzt; wenn eine verschwindet, läuft ihre importierte Version ab. Ein kleines .agentcairn/native-memory/-Register bewahrt diesen Lebenszyklus, ohne Quellinhalt doppelt zu indizieren. Verwende --source <dir> für ein benutzerdefiniertes, verwaltetes oder sitzungsüberschriebenes Claude-Speicherverzeichnis oder --no-reindex beim Stapelimport.

Bevorzugst du einen ephemeren Prozess:

uvx agentcairn                             # MCP server
uvx --from agentcairn cairn recall "..."  # CLI; plain `uvx cairn` is a different package

cairn schedule install --vault ~/agentcairn  # launchd on macOS / user crontab on Linux
cairn schedule status
cairn link --vault ~/agentcairn              # write deterministic related: neighbors
cairn reindex ~/agentcairn                   # rebuild the disposable cache
cairn savings                                # local context-efficiency estimate
cairn index-status --vault ~/agentcairn

cairn config --init
cairn config

auto_recall = true
auto_recall_k = 3
auto_recall_scope = "project"  # use "all" only as an explicit cross-project opt-in

Gemessene Benchmarks

Das Repository enthält einen revisionspinnbaren, reproduzierbaren LongMemEval-S + LoCoMo-Harness. Der Standard ist lokales nomic-embed-text-v1.5 plus der Cross-Encoder-Reranker.

Der beim Standard-k=10 zurückgegebene Kontext ist viel kleiner als die vollständige indizierte Historie:

Lies die Zahlen ehrlich:

• Retrieval-Recall ist keine QA-Genauigkeit. Diese Tabellen vergleichen kontrollierte Retrieval-Arme, nicht die Antwortqualität für Endnutzer oder die Leaderboard-Punktzahl eines anderen Produkts.
• Token-Zählungen verwenden eine Heuristik von ungefähr vier Zeichen pro Token. Die Reduktion vergleicht den indizierten Heuhaufen mit zurückgegebenen Chunks; es sind keine abgerechneten Kosteneinsparungen.
• Der Graph-Boost ist bei diesen Chat-Korpora wirkungslos, da sie keinen nativen [[wikilink]]-Graphen enthalten. Er ist für echte, verlinkte Vaults entwickelt.
• Der optionale QA-Richter verwendet Anthropic statt des GPT-4o-Setups der Papiere, daher sind diese QA-Ergebnisse für relative Ablationen nützlich – nicht für Vergleiche mit veröffentlichten Leaderboards.

Vollständige Metriken, Einbettungs-Sweeps, Latenzmessungen, Lizenzen, Befehle und Einschränkungen finden sich in benchmarks/README.md.

Datenschutz und Grenzen

• Der Tresor ist bewusst als Klartext konzipiert, nicht als verschlüsselter Speicher. AgentCairn schwärzt erkannte Anmeldedaten-Muster vor seinen automatisierten Body-/Titel-/Tag-Schreibvorgängen; unbekannte Muster und manuelle Bearbeitungen bleiben in Ihrer Verantwortung.
• Tresor-Dateien sind nur für den Eigentümer zugänglich (0600/0700). Da der Tresor Klartext ist und die Schwärzung nur nach bestem Bemühen erfolgt, ist der Dateimodus praktisch die einzige Zugriffskontrolle. Shared-GID-Setups (z. B. zwei Docker-Container in derselben Gruppe, aber mit unterschiedlichen UIDs) benötigen Gruppen-Zugriff, daher erweitert vault_group_writable = true neue Tresor-Notizen und -Verzeichnisse auf 0660/0770. Dies ist bewusst opt-in: Auf macOS ist die primäre Gruppe jedes lokalen Benutzers staff, sodass ein gruppenlesbarer Standard Ihre Erinnerungen anderen Konten auf dem Rechner zugänglich machen würde. Der Schalter erweitert niemals etwas außerhalb des Tresors – der Index, Hauptbücher, Sperrdateien und ~/.agentcairn/config.toml bleiben privat.
• Cloud-Funktionen sind expliziter Datenabfluss. Der Standard bleibt lokal. Die Opt-in-Nutzung eines Cloud-Embedders oder LLM-Richters sendet den verbleibenden geschwärzten Text an diesen Anbieter.
• Das Projekt ist Beta. Die eigenständige Nutzung erfordert Python 3.11+, und das erste lokale Modell-Laden kann Zeit in Anspruch nehmen. Die veröffentlichten Retrieval-Belege sind am stärksten für konversationelles Gedächtnis, nicht für einen universellen Code-Such-Anspruch.
• Das Umgebungsverhalten variiert je nach Host. Die obige Matrix ist beabsichtigt: Cursor und Antigravity verlassen sich auf Sweep-Erfassung; generische MCP-Hosts können Tools ohne Lifecycle-Hooks bereitstellen.
• Automatisierung ist plattformspezifisch. Verwaltete Zeitplanung zielt auf macOS launchd und Linux-Benutzer-crontab; verwenden Sie andernfalls Ihren eigenen Scheduler.

Entwicklung

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

uv sync
uv run pre-commit install

uv run pytest
uv run ruff format .
uv run ruff check --fix .
uv run pre-commit run --all-files

Führen Sie den Offline-Benchmark-Regressionstest ohne API-Schlüssel aus:

uv run pytest benchmarks/tests/

Lizenz

Apache License 2.0 – permissiv, mit ausdrücklicher Patentgewährung. Copyright © 2026 Charles C. Figueiredo.