agentcairn

Une mémoire durable pour tous les agents de codage pris en charge.
Votre coffre-fort Markdown fait autorité. DuckDB est le cache de récupération remplaçable.

Site Web · PyPI · Companion Obsidian · Benchmarks

Un cairn marque un sentier pour ceux qui suivent. agentcairn fait cela pour les agents de codage : il capture le contexte durable des outils que vous utilisez, le stocke sous forme de Markdown inspectable avec provenance, et ne rappelle que les éléments les plus pertinents lorsqu'un autre agent en a besoin.

Une preuve que vous pouvez inspecter

La mémoire n'est pas cachée derrière une console d'administration ou une base de données hébergée. Le compagnon séparé agentcairn-obsidian lit les mêmes fichiers Markdown que les agents et expose la provenance, l'actualité, l'importance, la suppression et les liens related:.

_{Un véritable coffre-fort agentcairn dans Obsidian. La liste est une vue sur les fichiers — pas un second stockage mémoire.}

Instantané de l'auto-test · 2026-07-15. Sur 417 rappels locaux, le coffre-fort du mainteneur a retourné un contexte environ 262× smaller que le chargement complet du coffre-fort à chaque fois — une estimation de 136.6M tokens of full-vault context avoided au total. Le nombre de tokens utilise environ quatre caractères par token. Il ne s'agit pas d'économies de tokens facturés, et agentcairn n'envoie aucune télémétrie.

Installation

Le chemin le plus court est un plugin de première classe. Il regroupe le serveur MCP, la compétence mémoire et les hooks ambiants spécifiques à l'hôte — aucune installation séparée du paquet agentcairn. Le plugin se lance via uvx, installez donc uv d'abord si uvx --version n'est pas déjà disponible.

Claude Code

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

Claude Code bénéficie d'un rappel par tour limité au projet, d'une capture de session/compaction, et des commandes /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings et /agentcairn:ingest.

Codex

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

Codex bénéficie des outils MCP groupés et de la compétence mémoire, d'un rappel SessionStart vérifié en direct et d'une capture SessionEnd avec cairn sweep comme filet de sécurité hors bande.

Configuration assistée par agent

Vous utilisez déjà skills.sh ou un flux de travail find-skills ? Installez l'assistant de configuration public :

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

Puis demandez à votre agent : Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Ceci installe uniquement les conseils de configuration — pas l'environnement d'exécution AgentCairn, le serveur MCP, le plugin ou les hooks. L'assistant délègue ces modifications à l'installateur natif d'AgentCairn, qui privilégie l'aperçu, et vérifie l'intégration résultante. Les commandes de plugin Claude Code et Codex ci-dessus restent le chemin le plus court.

Le coffre-fort par défaut est ~/agentcairn et est créé lors de la première utilisation. Un nouveau coffre-fort vide n'a encore rien d'utile à rappeler, alors prouvez la boucle complète explicitement :

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 écrit la note Markdown et l'entrée d'index ensemble, de sorte que le rappel immédiat fait partie du contrat. La première exécution locale peut télécharger et précharger les modèles d'embedding/reclassement configurés.

Le contrat

Comment ça fonctionne

• Capture : les hooks de l'hôte améliorent l'immédiateté ; cairn sweep lit les transcriptions prises en charge hors bande comme filet de sécurité durable. AgentCairn expurge les informations d'identification reconnues, déduplique, filtre par importance et distille avant ses écritures automatiques en texte brut.
• Réconciliation : la première lecture met l'index du coffre-fort en synchronisation transactionnelle avec le Markdown. Un échec de reconstruction préserve le dernier bon cache et les fichiers durables restent intacts.
• Rappel : BM25 et les vecteurs sémantiques sont fusionnés avec Reciprocal Rank Fusion, puis éventuellement reclassés. Les échecs de modèle/fournisseur reviennent visiblement à BM25 avec des diagnostics au lieu de retourner des vecteurs incompatibles.
• Mémorisation : l'outil MCP écrit atomiquement une note Markdown et met à jour l'index sous un verrou d'écriture unique, rendant une sauvegarde réussie immédiatement rappelable.

Conçu pour la confiance

• Local par défaut. FastEmbed s'exécute localement, le serveur MCP utilise stdio, il n'y a pas de démon ou de base de données externe requis, et il n'y a pas de télémétrie.
• Limites claires. Le coffre-fort synchronisé contient du Markdown ; par défaut, l'index .duckdb reconstruisable reste en dehors. Les liens symboliques du coffre-fort qui sortent de la racine configurée sont rejetés.
• Corrections temporelles. valid_from, valid_until et superseded_by gardent les anciennes preuves visibles tout en classant les faits actuels en premier.
• Graphe déterministe. [[wikilinks]] et les voisins optionnels cairn link créent un graphe natif Obsidian sans demander à un LLM d'inventer des entités.
• Rappel sensible au projet. Le projet actuel est boosté par défaut ; les résultats inter-projets restent disponibles et sont étiquetés. Le rappel automatique est limité au projet, sauf si vous optez explicitement pour tous les projets.

Agents pris en charge

Chaque hôte résout le même coffre-fort configuré. cairn install prévisualise les hôtes détectés sans écrire. Les écritures de configuration MCP sauvegardent d'abord et préservent les serveurs non liés ; les installations de plugin-hôte délèguent à la CLI propre de l'hôte.

La SessionStart de Codex a été vérifiée en direct de bout en bout avec agentcairn 0.24.2 / plugin 0.1.2. La commande SessionEnd installée et le balayage détaché passent les sondes de gestionnaire exactes ; cairn sweep reste le filet de sécurité de capture hors bande. Voir l'intégration OpenCode et l'intégration Hermes pour les détails de leur cycle de vie natif.

Utilisation directe

Le plugin est la voie la plus facile, mais agentcairn est aussi une CLI autonome et un serveur MCP à la demande. Les installations autonomes nécessitent 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

Emportez la mémoire de Claude Code avec vous

La mémoire automatique de Claude Code peut alimenter le coffre-fort partagé sans modifier ses fichiers source. La commande prévisualise uniquement le dépôt actuel par défaut ; ajoutez --apply pour écrire les notes expurgées et rafraîchir l'index.

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

L'importation unidirectionnelle lit MEMORY.md et ses fichiers Markdown de sujet — jamais CLAUDE.md ou .claude/rules/. Les notes importées conservent la provenance de Claude Code, du projet et du fichier source. Lorsqu'une source change, la version précédente reste inspectable mais est remplacée ; lorsqu'elle disparaît, sa version importée expire. Un petit registre .agentcairn/native-memory/ préserve ce cycle de vie sans indexer le contenu source deux fois. Utilisez --source <dir> pour un répertoire de mémoire Claude personnalisé, géré ou surchargé par session, ou --no-reindex lors de l'importation par lots.

Préférez un processus éphémère :

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

Benchmarks mesurés

Le dépôt fournit un harnais LongMemEval-S + LoCoMo révisionné et reproductible. La valeur par défaut est nomic-embed-text-v1.5 local plus le re-classeur cross-encodeur.

Le contexte retourné au k=10 par défaut est bien plus petit que l'historique indexé complet :

Lisez les chiffres honnêtement :

• Le rappel de récupération n'est pas la précision QA. Ces tableaux comparent des bras de récupération contrôlés, pas la qualité des réponses de l'utilisateur final ou le score de classement d'un autre produit.
• Le nombre de tokens utilise une heuristique d'environ quatre caractères par token. La réduction compare la botte de foin indexée avec les fragments retournés ; il ne s'agit pas d'économies de coûts facturés.
• Le boost de graphe est inerte sur ces corpus de chat car ils ne contiennent pas de graphe [[wikilink]] natif. Il est conçu pour de vrais coffres-forts interconnectés.
• Le juge QA optionnel utilise Anthropic plutôt que la configuration GPT-4o des articles, de sorte que ces résultats QA sont utiles pour des ablations relatives — pas pour des comparaisons avec les classements publiés.

Les métriques complètes, les balayages d'embedding, les mesures de latence, les licences, les commandes et les mises en garde se trouvent dans benchmarks/README.md.

Confidentialité et limites

• Le coffre-fort est en texte brut par conception, pas un stockage chiffré. AgentCairn expurge les motifs d'identifiants reconnus avant ses écritures automatisées de corps/titre/étiquette ; les motifs inconnus et les modifications manuelles restent sous votre responsabilité.
• Les fonctionnalités cloud sont des sorties explicites. Le comportement par défaut reste local. Opter pour un intégrateur cloud ou un juge LLM envoie le texte expurgé restant à ce fournisseur.
• Le projet est en version bêta. Une utilisation autonome nécessite Python 3.11+, et le premier chargement du modèle local peut prendre du temps. Les preuves de récupération publiées sont les plus solides pour la mémoire conversationnelle, pas pour une revendication universelle de recherche de code.
• Le comportement ambiant varie selon l'hôte. La matrice ci-dessus est intentionnelle : Cursor et Antigravity reposent sur la capture par balayage ; les hôtes MCP génériques peuvent exposer des outils sans crochets de cycle de vie.
• L'automatisation est spécifique à la plateforme. La planification gérée cible launchd sur macOS et la crontab utilisateur sur Linux ; utilisez votre propre planificateur ailleurs.

Développement

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

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

Exécutez la régression de référence hors ligne sans clés API :

uv run pytest benchmarks/tests/

Licence

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