agentcairn

Ein dauerhafter Speicher für alle unterstützten Coding-Agenten.
Ihr Markdown-Tresor ist kanonisch. DuckDB ist der austauschbare Abruf-Cache.

Website · PyPI · Obsidian-Begleiter · Benchmarks

Ein Cairn markiert einen Pfad für diejenigen, die nachfolgen. agentcairn tut dies für Coding-Agenten: Es erfasst dauerhaften Kontext aus den von Ihnen verwendeten Werkzeugen, speichert ihn als überprüfbares Markdown mit Herkunftsnachweis und ruft nur die relevantesten Teile ab, wenn ein anderer Agent sie benötigt.

Nachweis, den Sie überprüfen können

Der Speicher ist nicht hinter einer Admin-Konsole oder einer gehosteten Datenbank versteckt. Der separate agentcairn-obsidian-Begleiter liest dieselben Markdown-Dateien wie die Agenten und legt Herkunft, Aktualität, Wichtigkeit, Ablösung und related:-Links offen.

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

Dogfood-Momentaufnahme · 2026-07-15. Bei 417 lokalen Abrufen lieferte der Tresor des Maintainers Kontext über 262× smaller zurück, als jedes Mal den gesamten Tresor zu laden – eine geschätzte 136.6M tokens of full-vault context avoided insgesamt. Token-Zählungen verwenden ungefähr vier Zeichen pro Token. Dies sind keine eingesparten abgerechneten Token, und agentcairn sendet keine Telemetrie.

Installation

Der kürzeste Weg ist ein erstklassiges Plugin. Es bündelt den MCP-Server, die Speicherfähigkeit und die hostspezifischen Umgebungs-Hooks – keine separate agentcairn-Paketinstallation. Das Plugin wird über uvx gestartet, installieren Sie also zuerst uv, falls uvx --version noch nicht verfügbar ist.

Claude Code

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

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

Codex

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

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

Agenten-unterstützte Einrichtung

Verwenden Sie bereits skills.sh oder einen find-skills-Workflow? Installieren Sie den öffentlichen Einrichtungsassistenten:

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

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

Dies installiert nur die Einrichtungsanleitung – nicht die AgentCairn-Laufzeitumgebung, den MCP-Server, das Plugin oder die Hooks. Der Assistent delegiert diese Änderungen an das native Vorschau-zuerst-Installationsprogramm von AgentCairn und verifiziert die resultierende Integration. Die obigen Plugin-Befehle für Claude Code und Codex bleiben der kürzeste Weg.

Der Standard-Tresor ist ~/agentcairn und wird bei der ersten Verwendung erstellt. Ein neuer leerer Tresor hat noch nichts Nützliches zum Abrufen, beweisen Sie also 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 der sofortige Abruf Teil des Vertrags ist. Der erste lokale Lauf kann die konfigurierten Einbettungs-/Neueinstufungsmodelle herunterladen und aufwärmen.

Der Vertrag

Wie es funktioniert

• Erfassung: Host-Hooks verbessern die Unmittelbarkeit; cairn sweep liest unterstützte Transkriptspeicher Out-of-Band als dauerhafte Absicherung. AgentCairn schwärzt erkannte Anmeldeinformationen, dedupliziert, filtert nach Wichtigkeit und destilliert vor seinen automatisierten Klartext-Schreibvorgängen.
• Abgleich: Die erste Lesetransaktion bringt den tresorbezogenen Index transaktional mit Markdown in Einklang. Ein fehlgeschlagener Neuaufbau bewahrt den letzten guten Cache, und die dauerhaften Dateien bleiben unberührt.
• Abruf: BM25 und semantische Vektoren werden mit Reciprocal Rank Fusion fusioniert und dann optional neu eingestuft. Modell-/Anbieterfehler fallen sichtbar auf BM25 mit Diagnoseinformationen zurück, anstatt inkompatible Vektoren zurückzugeben.
• Merken: Das MCP-Tool schreibt atomar eine Markdown-Notiz und aktualisiert den Index unter einer Schreibsperre, wodurch eine erfolgreiche Speicherung sofort abrufbar wird.

Auf Vertrauen ausgelegt

• 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 Tresor enthält Markdown; standardmäßig bleibt der wiederaufbaubare .duckdb-Index außerhalb davon. Tresor-Symlinks, die das konfigurierte Stammverzeichnis verlassen, 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 bevorzugt; projektübergreifende Ergebnisse bleiben verfügbar und werden gekennzeichnet. Der automatische Abruf ist projektbezogen, es sei denn, Sie entscheiden sich explizit für alle Projekte.

Unterstützte Agenten

Jeder Host löst denselben konfigurierten Tresor auf. cairn install zeigt erkannte Hosts in der Vorschau an, ohne zu schreiben. MCP-Konfigurationsschreibvorgänge sind Backup-zuerst 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-Prüfungen; 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 eine eigenständige 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

Nehmen Sie Claude Codes Speicher mit

Der Auto-Speicher von Claude Code kann den gemeinsamen Tresor befüllen, ohne seine Quelldateien zu ändern. Der Befehl zeigt standardmäßig nur das aktuelle Repository in der Vorschau an; fügen Sie --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 die Herkunft von Claude Code, Projekt und Quelldatei. Wenn sich eine Quelle ändert, bleibt die vorherige Version überprüfbar, wird aber abgelöst; wenn eine verschwindet, läuft ihre importierte Version ab. Eine kleine .agentcairn/native-memory/-Registrierung bewahrt diesen Lebenszyklus, ohne den Quellinhalt doppelt zu indizieren. Verwenden Sie --source <dir> für ein benutzerdefiniertes, verwaltetes oder sitzungsüberschriebenes Claude-Speicherverzeichnis oder --no-reindex bei Stapelimporten.

Bevorzugen Sie einen kurzlebigen 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 ein versionsgenaues, reproduzierbares LongMemEval-S + LoCoMo-Testgeschirr. Der Standard ist lokales nomic-embed-text-v1.5 plus den Cross-Encoder-Neueinstufer.

Der zurückgegebene Kontext bei der Standardeinstellung k=10 ist viel kleiner als der vollständige indizierte Verlauf:

Lesen Sie die Zahlen ehrlich:

• Abruf-Recall ist keine QA-Genauigkeit. Diese Tabellen vergleichen kontrollierte Abrufarme, nicht die Antwortqualität des Endbenutzers oder die Bestenliste 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 Blöcken; es handelt sich nicht um eingesparte abgerechnete Kosten.
• Die Graph-Verstärkung ist bei diesen Chat-Korpora inaktiv, da sie keinen nativen [[wikilink]]-Graphen enthalten. Sie ist für echte, verlinkte Tresore konzipiert.
• Der optionale QA-Prüfer verwendet Anthropic anstelle des GPT-4o-Setups der Veröffentlichungen, sodass diese QA-Ergebnisse für relative Ablationen nützlich sind – nicht für Vergleiche mit veröffentlichten Bestenlisten.

Vollständige Metriken, Einbettungsdurchläufe, Latenzmessungen, Lizenzen, Befehle und Vorbehalte finden Sie in benchmarks/README.md.

Datenschutz und Grenzen

• Der Tresor ist absichtlich als Klartext konzipiert, kein verschlüsselter Speicher. AgentCairn schwärzt erkannte Anmeldeinformationsmuster vor seinen automatisierten Schreibvorgängen für Textkörper/Titel/Tags; unbekannte Muster und manuelle Bearbeitungen bleiben in Ihrer Verantwortung.
• Cloud-Funktionen sind expliziter Datenabfluss. Der Standard bleibt lokal. Die Entscheidung für einen Cloud-Einbetter oder LLM-Richter sendet den verbleibenden geschwärzten Text an diesen Anbieter.
• Das Projekt befindet sich in der Beta-Phase. Die eigenständige Nutzung erfordert Python 3.11+, und das erste Laden eines lokalen Modells kann Zeit in Anspruch nehmen. Die veröffentlichte Abrufevidenz ist am stärksten für das Konversationsgedächtnis, nicht als universeller Code-Such-Anspruch.
• Das Umgebungsverhalten variiert je nach Host. Die obige Matrix ist beabsichtigt: Cursor und Antigravity setzen auf Sweep-Erfassung; generische MCP-Hosts können Werkzeuge ohne Lebenszyklus-Hooks bereitstellen.
• Automatisierung ist plattformspezifisch. Verwaltete Planung zielt auf macOS launchd und Linux-Benutzer-Crontab; verwenden Sie andernorts Ihren eigenen Scheduler.

Entwicklung

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

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 die Offline-Benchmark-Regression ohne API-Schlüssel aus:

uv run pytest benchmarks/tests/

Lizenz

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