agentcairn MCP Server

officiel

Mémoire agent locale d'abord : un coffre Obsidian en Markdown simple sert de source de vérité, avec un index DuckDB reconstruisible pour la récupération hybride BM25 + vectorielle + par graphe.

GitHub
1

Documentation

🪨 agentcairn

CI Security PyPI Python License: Apache-2.0

Mémoire locale d’abord pour agents IA — que vous pouvez réellement lire, modifier et posséder.

cairn  /kɛən/  · nom — un empilement de pierres élevé pour marquer un sentier ou un lieu digne de mémoire, laissé pour celui qui viendra ensuite.

agentcairn donne à votre agent de codage une mémoire durable et de haute qualité — mais au lieu de l’enfermer dans une base de données opaque ou un service cloud, vos souvenirs vivent sous forme de Markdown brut dans un coffre Obsidian que vous possédez. Un index DuckDB rapide et reconstruisible se superpose pour la récupération. Ouvrez votre coffre, lisez ce que l’agent a retenu, corrigez un fait erroné à la main, ou ajoutez vos propres notes — et l’agent assimile tout cela.

Pourquoi agentcairn est différent

La plupart des systèmes de mémoire d’agent font d’une base de données ou d’un stockage cloud la source de vérité et traitent les fichiers (s’il y en a) comme une exportation à sens unique. agentcairn inverse cela :

  • 📂 Votre coffre est la source de vérité — pas une exportation. La mémoire est du Markdown lisible par l’humain avec frontmatter et [[wikilinks]]. Modifiez-la dans Obsidian ; l’index respecte vos modifications.
  • ♻️ L’index est jetable. DuckDB est un cache reconstruisible (cairn reindex). Votre mémoire survit à une mise à niveau de modèle, un index corrompu, un changement de schéma, ou la désinstallation de l’outil — zéro perte de données, car la vérité n’est que des fichiers sur le disque.
  • 🧠 Sans perte par construction. La note complète est toujours conservée. La distillation ne fait qu’ajouter des notes dérivées qui renvoient à la source — elle ne supprime jamais silencieusement des faits qu’elle n’a pas pensé à extraire au moment de l’écriture.
  • 🔒 Caviardage avant chaque écriture. Les secrets sont nettoyés (regex + entropie + détection d’identifiants dans les URL) avant que quoi que ce soit — corps, titre ou étiquettes — n’atteigne le coffre en texte brut. Nous écrivons des fichiers que vous pouvez lire, donc nous traitons une fuite d’identifiant comme le pire mode de défaillance.
  • 🕸️ Un graphe de connaissances gratuit et déterministe. Vos [[wikilinks]] et frontmatter sont le graphe — pas d’extraction par LLM, pas d’entités hallucinées.
  • 🪶 Sans démon, zéro base de données externe. Un seul fichier DuckDB embarqué fait la recherche vectorielle sémantique, le texte intégral BM25 et le parcours de graphe. Pas de serveur toujours actif, pas de Neo4j/Postgres/Qdrant, pas de clé cloud requise — juste une CLI cairn et un serveur MCP à la demande.
  • 🔍 Mesuré honnêtement. Un banc d’essai reproductible LongMemEval-S + LoCoMo est livré dans benchmarks/ — avec des chiffres réels, des ablations et des mises en garde explicites au lieu d’un seul titre choisi avec soin (voir ci-dessous).

Installation

La façon la plus simple d’utiliser agentcairn est le plugin pour Claude Code ou Codex — une seule installation connecte le serveur MCP, la mémoire ambiante (rappel au début de session, capture à la fin de session), une compétence mémoire et des commandes slash (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

Lors de l’installation, vous choisissez un chemin de coffre (par défaut ~/agentcairn) ; il est créé automatiquement à la première session — aucune configuration Obsidian requise. Dès lors, agentcairn fait remonter la mémoire pertinente au début de chaque session, distille chaque session dans votre coffre, et vous donne /agentcairn:recall, /remember, /memory, /savings et /ingest. Rien à installer avec pip — le plugin exécute le paquet publié via uvx.

Vous n’êtes pas sur Claude Code ou Codex ? agentcairn est aussi un serveur MCP autonome + CLI pour tout hôte — voir Utilisation directe.

Comment ça fonctionne

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
  • Capture lit les transcriptions de session de votre harnais d’agent (ajout seul, déjà sur le disque) hors bande — robuste par conception, sans crochets en direct fragiles — puis caviarde → dédoublonne → juge (durabilité sémantique ; distillation LLM optionnelle via CAIRN_JUDGE=anthropic) → filtre → distille dans le coffre, sans perte. cairn sweep détecte automatiquement chaque harnais présent (Claude Code, Codex, Antigravity CLI et Cursor sont tous pris en charge, derrière une couture HarnessAdapter) pour que vous obteniez une mémoire unifiée sur les quatre sans aucune configuration supplémentaire. Au niveau LLM, il consolide également : un nouveau souvenir qui duplique un existant est ignoré, et une version plus récente d’un fait évolutif marque la note plus ancienne superseded_by (conservée + rétrogradée au rappel, jamais supprimée) — à sécurité intégrée, pour qu’un appel erroné ne supprime jamais un souvenir distinct (CAIRN_CONSOLIDATE=0 pour désactiver). Plus un outil remember piloté par l’agent pour des souvenirs organisés et de grande valeur.
  • Récupération fusionne BM25 + vecteurs sémantiques avec Reciprocal Rank Fusion, applique un boost de graphe optionnel, et se dégrade gracieusement jusqu’au mode mots-clés seuls quand aucun modèle d’embedding n’est disponible — ainsi le rappel n’est jamais silencieusement mort. Un re-classeur cross-encodeur optionnel ajoute de la précision.
  • Intelligence hybride : embeddings locaux hors ligne (FastEmbed / nomic-embed-text-v1.5 par défaut) prêts à l’emploi — performants seuls et dans la fusion hybride (avec nomic, le vecteur seul surpasse BM25 même sur des tours courts ; voir le benchmark). Définissez CAIRN_EMBED_MODEL pour choisir un autre modèle FastEmbed, ou exécutez CAIRN_EMBEDDER=ollama / un niveau cloud pour aller plus loin.
  • Mémoire temporelle : les notes peuvent porter un frontmatter valid_from/valid_until/superseded_by. Le rappel est sensible à la validité — il rétrograde doucement les faits remplacés et expirés (le fait actuel l’emporte) sans jamais les cacher (sans perte), et annote le statut de chaque résultat (current/superseded/expired/not_yet_valid) plus une ancre as_of pour que l’agent puisse raisonner dans le temps. Inerte pour les notes sans champs de validité.
  • Rappel sensible à la provenance : les notes portent une provenance project/harness, et le rappel favorise les souvenirs de votre projet actuel (sans perte — les résultats inter-projets remontent toujours, marqués [from: <project>]). Passez --project <repo> pour cibler un autre dépôt, ou --scope project pour filtrer strictement sur le projet actuel uniquement.

Utilisation directe

Le plugin est le chemin le plus simple, mais agentcairn n’est qu’un paquet — utilisez-le sans Claude Code via le serveur MCP à la demande (pour tout hôte MCP) ou la CLI cairn :

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

Configuration

Tous les paramètres résident dans un seul fichier — ~/.agentcairn/config.toml — avec des variables d’env comme surcharges (priorité : drapeau CLI > var env > fichier config > défaut) :

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

Par exemple, activer le juge de mémoire LLM se fait en deux lignes décommentées — pas besoin d’exports shell (le balayage de fond du plugin lit le fichier directement) :

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

Agents pris en charge

agentcairn fonctionne à deux niveaux. Les hôtes de plugin (Claude Code, Codex et Antigravity) bénéficient d’un plugin de première classe — un serveur MCP intégré (rappel/recherche/remember), une compétence mémoire et (sur Claude Code et Codex) des crochets de session ambiants ; cairn install <host> installe le plugin en appelant la CLI propre de l’hôte. Les hôtes MCP (tout le reste) obtiennent les mêmes outils de rappel/recherche/remember via le serveur MCP portable ; cairn install <host> écrit la configuration du serveur MCP de manière non destructive (vos autres serveurs sont préservés, l’original est sauvegardé dans <config>.bak). Le coffre reste un ~/agentcairn global unique, donc la mémoire est partagée entre tous les hôtes.

HôtePrise en chargeConfigurer avecCapture ambiante
Claude Code🟢 Plugincairn install claude-code✅ rappel-au-début + capture-à-la-fin
Codex🟢 Plugincairn install codex◐ rappel/remember en direct ; crochets ambiants intégrés (vérification) 1
Cursor🔌 Serveur MCP + compétence + ingestioncairn install cursor◐ cairn sweep détecte automatiquement les transcriptions 2
Claude Desktop🔌 Serveur MCPcairn install claude-desktop—
VS Code (Copilot)🔌 Serveur MCPcairn install vscode—
Gemini CLI 3🔌 Serveur MCPcairn install gemini—
Antigravity🟢 Plugin + ingestioncairn install antigravity◐ cairn sweep détecte automatiquement les transcriptions 4
Tout autre hôte MCP🔌 Serveur MCPuvx agentcairn (collez l’extrait cairn install … --print)—

cairn install route par type d’hôte automatiquement :

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

Les hôtes MCP prennent une entrée JSON mcpServers (VS Code utilise sa clé servers). Les hôtes de plugin (Claude Code, Codex, Antigravity) installent le plugin via la CLI de l’hôte — le serveur MCP est intégré au plugin et n’a pas besoin d’une entrée de configuration séparée. Si vous avez précédemment utilisé cairn install antigravity pour écrire une entrée MCP dans ~/.gemini/config/mcp_config.json, ré-exécuter cairn install antigravity supprime automatiquement cette entrée obsolète.

Benchmarks mesurés

Nous benchmarkons agentcairn comme nous voudrions qu’un système de mémoire soit mesuré — de manière reproductible, avec des ablations, et sans un seul chiffre titre choisi avec soin. Le banc d’essai (benchmarks/) exécute LongMemEval-S et LoCoMo via un téléchargeur à version épinglée (les jeux de données ne sont jamais vendus), évalue la récupération de manière déterministe (rappel/nDCG@k, MRR — pas de clé API nécessaire, s’exécute en CI sur un dispositif synthétique), et offre une couche optionnelle d’évaluation QA par LLM.

Récupération — LoCoMo

Ensemble LoCoMo complet, niveau tour, macro-moyenne, FastEmbed nomic-embed-text-v1.5 (l’embedder par défaut) :

brasrappel@5rappel@10MRR
BM25 seul0.5270.6040.459
vecteur seul0.5360.6370.433
hybride (RRF)0.5620.6480.477
hybride + boost-graphe0.5620.6480.477
hybride + re-classeur0.6620.7350.608

Ce que nous lisons de cela — et disons à voix haute :

  • L’hybride bat chaque bras seul — la fusion RRF en vaut la peine.
  • Le re-classeur cross-encodeur est le plus grand levier (+0.10 rappel@5 sur l’hybride) ; l’inquiétude que "le décalage de domaine ms-marco pourrait nuire" ne s’est pas matérialisée sur les données conversationnelles.
  • Le défaut de l’embedder fait maintenant ses preuves — avec nomic, le vecteur seul surpasse BM25 (0.536 vs 0.527) ; le passage de l’ancien défaut bge-small (qui traînait à 0.483) a comblé l’écart. Un balayage de 5 modèles FastEmbed a fixé le choix — nomic (768-d) l’emporte en qualité par dimension ; les modèles plus grands 1024-d ne le battent pas. Tableau complet : benchmarks/README.md.
  • Le boost-graphe est inerte sur ces corpus — LoCoMo/LongMemEval n’ont pas de graphe [[wikilink]] natif, donc le boost n’a rien sur quoi s’activer. C’est pour les vrais coffres interconnectés, pas les journaux de chat, et nous ne prétendons pas le contraire.

Récupération — LongMemEval-S

Ensemble complet de 500 instances — une tâche plus facile avec des sessions de preuves bien séparées. Le niveau de session est la granularité rapportée par les travaux antérieurs ; le niveau de tour est la tranche plus fine, révélatrice du corpus :

brassession r@5session MRRtour r@5tour r@10tour MRR
BM25 seul0.9200.9180.6800.7910.638
vectoriel seul0.9360.9160.5070.6920.454
hybride (RRF)0.9540.9380.6400.7980.544
hybride + reranker0.9690.9630.7880.8910.716

À lire honnêtement :

  • Notre rappel@5 de session de 0.969 se situe juste à côté du ≈0.95 des travaux antérieurs sur le même ensemble complet de 500 questions — et à pleine échelle, il discrimine (0.920 BM25 → 0.969 reranker) plutôt que de saturer comme le ferait un petit échantillon.
  • Le reranker est de nouveau le levier le plus important — tour r@5 0.640 → 0.788, session r@5 0.954 → 0.969.
  • Le niveau de tour est révélateur du corpus : ici BM25 seul (0.680) bat l'hybride RRF (0.640) parce que le vectoriel seul est faible sur ces segments de preuve à tour unique (0.507) ; c'est le reranker qui fait passer l'approche par défaut en tête. (Contraste avec LoCoMo, où le vectoriel seul devance légèrement BM25.)

Efficacité contextuelle

De combien le contexte rappelé par agentcairn est-il plus petit que l'historique complet que vous transporteriez autrement dans le modèle ? Configuration par défaut (hybride + reranker, k=10) :

jeu de donnéesrequêtesbotte de foin moyennerappelé moyen (k=10)réduction de contexte
LoCoMo (3 convos)49725 646 tok529 tok51.1× moyenne / 50.3× médiane
LongMemEval-S (complet 500)470136 552 tok2 207 tok64.7× moyenne / 61.6× médiane

Estimation (~4 caractères/token), pas un coût facturé ; « botte de foin » = l'historique indexé complet, « rappelé » = les k meilleurs fragments retournés. Cela mesure la taille du contexte, indépendamment de la qualité de la recherche.

Précision QA

Les chiffres de précision QA (jugés par LLM) sont également disponibles, mais utilisent un juge Anthropic plutôt que le GPT-4o des articles, ils ne sont donc pas comparables aux classements publiés — valides uniquement pour le signal d'ablation relatif. Voir benchmarks/README.md pour savoir comment l'exécuter et comment lire les chiffres.

Feuille de route

  • v1 — terminée. La boucle centrale : ingestion de transcriptions → rédaction → Markdown → index DuckDB reconstituable → rappel hybride ; serveur MCP + CLI ; rédaction secrète ; embeddings locaux ; banc d'essai reproductible.
  • v1.1 — prochaine, priorisée par le benchmark ci-dessus :
    • ✅ Reranker activé par défaut — le plus grand levier de recherche mesuré ; CAIRN_RERANK=0 pour désactiver. (livré)
    • Niveau d'embedding Ollama — ✅ modèles locaux via CAIRN_EMBEDDER=ollama (CAIRN_EMBED_MODEL/OLLAMA_HOST) ; cloud (OpenAI/Voyage) encore en attente.
    • ✅ Validité bi-temporelle — frontmatter valid_from/valid_until/superseded_by ; le rappel rétrograde doucement les faits remplacés/expirés (non destructif — jamais masqués) et annote la devise de chaque résultat + une ancre as_of, afin que le fait actuel l'emporte et que l'agent puisse raisonner dans le temps. (livré)
    • HNSW en mémoire pour la latence de recherche sur de grands coffres.
  • v2 — ◐ Plugin Obsidian (agentcairn-obsidian) — une vue Mémoire native du coffre (liste + provenance + devise + graphe) pour lire/naviguer dans votre mémoire dans Obsidian ; (MVP livré ; le rappel sémantique reste dans le CLI/MCP). Synchronisation cloud MotherDuck, extraction optionnelle d'entités par LLM encore en attente.

Développement

agentcairn utilise uv exclusivement pour la gestion des dépendances et l'outillage.

N'utilisez pas pip, poetry, ou des environnements virtuels globaux.

# 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

Le serveur MCP est lancé via uvx agentcairn — aucune installation globale requise.

Licence

Licence Apache 2.0 — permissive, avec une concession explicite de brevet. Copyright © 2026 Charles C. Figueiredo.

Footnotes

  1. The L’installation du plugin Codex et son serveur MCP intégré (rappel/recherche/remember) sont vérifiés en direct dans Codex. Les crochets de session ambiants (rappel-au-début, capture-à-la-fin) sont livrés dans le plugin et utilisent le schéma de crochets documenté de Codex, mais leur comportement sur Codex n’est pas encore confirmé de bout en bout ; la capture a également lieu hors bande via cairn sweep quoi qu’il en soit. ↩

  2. Cursor n’a pas de crochets de plugin, donc la capture ambiante est hors bande via cairn sweep (source : la base de données SQLite globale globalStorage/state.vscdb de Cursor, table cursorDiskKV, utilisateur "bubbles"). Cursor reste un hôte MCP pour la sortie (cairn install cursor → ~/.cursor/mcp.json) ; il n’y a pas de plugin Cursor. cairn install cursor installe également la compétence using-agentcairn-memory (guide de rappel/souvenir) dans ~/.cursor/skills/using-agentcairn-memory/SKILL.md. ↩

  3. Gemini L’ingestion de transcriptions CLI (consommateur) n’est pas prise en charge — Google arrête la CLI Gemini (arrêt consommateur le 18/06/2026) au profit d’Antigravity CLI, qu’agentcairn ingère à la place. cairn install gemini (câblage du serveur MCP) reste valide pour tout hôte basé sur Gemini qui parle MCP. ↩

  4. The Le plugin Antigravity intègre le serveur MCP + la compétence mémoire ; cairn install antigravity --source <dir> l’installe via agy plugin install et supprime toute entrée mcpServers.agentcairn obsolète de ~/.gemini/config/mcp_config.json. Note : agy plugin install prend un répertoire local ou un marketplace enregistré (pas un dépôt git), donc pointez --source vers le répertoire plugin/ d’une extraction clonée pour l’instant. Antigravity n’a pas de crochets de plugin reconnus, donc la capture ambiante est hors bande via cairn sweep (chemin : ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript.jsonl). ↩