agentcairn

Une mémoire durable pour les agents de codage pris en charge.
Votre coffre Markdown est la référence. DuckDB est le cache de récupération remplaçable.

Site web · PyPI · Compagnon Obsidian · Benchmarks

Un cairn balise le sentier pour ceux qui suivent. agentcairn fait de même 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 supplantation et les liens related:.

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

Instantané dogfood · 2026-07-15. Sur 417 rappels locaux, le coffre du mainteneur a renvoyé un contexte environ 262× smaller que de charger l'intégralité du coffre à chaque fois—soit une estimation de 136.6M tokens of full-vault context avoided au total. Les comptages de jetons utilisent environ quatre caractères par jeton. Il ne s'agit pas d'économies de jetons 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—sans installation séparée du paquet agentcairn. Le plugin se lance via uvx, donc installez 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, de la 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 workflow 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.

Cela installe uniquement des conseils de configuration—pas le runtime AgentCairn, le serveur MCP, le plugin ou les hooks. L'assistant délègue ces modifications à l'installateur natif prévisualisation-d'abord d'AgentCairn 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 par défaut est ~/agentcairn et est créé lors de la première utilisation. Un nouveau coffre vide n'a encore rien d'utile à rappeler, donc prouvez explicitement toute la boucle :

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, donc le rappel immédiat fait partie du contrat. La première exécution locale peut télécharger et préchauffer les modèles d'intégration/reranking configurés.

Le contrat

Comment cela fonctionne

• Capture : les hooks hôtes améliorent l'immédiateté ; cairn sweep lit les magasins de transcriptions pris en charge hors bande comme filet de sécurité durable. AgentCairn masque les identifiants reconnus, déduplique, filtre par importance et distille avant ses écritures automatisées en texte clair.
• Réconciliation : la première transaction de lecture synchronise l'index du coffre avec le Markdown. Une reconstruction échouée préserve le dernier bon cache et les fichiers durables restent intacts.
• Rappel : les vecteurs BM25 et sémantiques sont fusionnés avec Reciprocal Rank Fusion, puis éventuellement rerankés. Les échecs de modèle/fournisseur retombent visiblement sur BM25 avec des diagnostics au lieu de renvoyer des vecteurs incompatibles.
• Mémorisation : l'outil MCP écrit atomiquement une note Markdown et met à jour l'index sous un seul verrou d'écriture, rendant un enregistrement réussi immédiatement rappelable.

Conçu pour la confiance

• Local par défaut. FastEmbed s'exécute localement, le serveur MCP utilise stdio, aucun démon ou base de données externe n'est requis, et il n'y a pas de télémétrie.
• Frontières claires. Le coffre synchronisé contient du Markdown ; par défaut, l'index .duckdb reconstruisible reste en dehors. Les liens symboliques du coffre qui s'échappent de la racine configurée sont rejetés.
• Corrections sensibles au temps. valid_from, valid_until et superseded_by gardent les anciennes preuves visibles tout en faisant passer 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 conscient du 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 configuré. cairn install prévisualise les hôtes détectés sans écrire. Les écritures de configuration MCP sont sauvegarde-d'abord et préservent les serveurs non liés ; les installations de plugin-hôte délèguent au CLI propre de l'hôte.

Le SessionStart de Codex a été vérifié en direct de bout en bout avec agentcairn 0.24.2 / plugin 0.1.2. La distribution de commande SessionEnd installée et le balayage détaché passent des 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 leurs détails de cycle de vie natifs.

Utilisation directe

Le plugin est la voie la plus simple, mais agentcairn est aussi un 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

L'auto-mémoire de Claude Code peut alimenter le coffre partagé sans modifier ses fichiers sources. La commande prévisualise uniquement le dépôt actuel par défaut ; ajoutez --apply pour écrire les notes masquées et actualiser 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'import unidirectionnel lit MEMORY.md et ses fichiers Markdown de sujets—jamais CLAUDE.md ou .claude/rules/. Les notes importées conservent la provenance Claude Code, projet et fichier source. Lorsqu'une source change, la version précédente reste inspectable mais est supplantée ; lorsqu'elle disparaît, sa version importée expire. Un petit registre .agentcairn/native-memory/ préserve ce cycle de vie sans indexer deux fois le contenu source. Utilisez --source <dir> pour un répertoire mémoire Claude personnalisé, géré ou remplacé par session, ou --no-reindex pour des importations 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 reproductible et épinglé à une révision. La valeur par défaut est nomic-embed-text-v1.5 local plus le reranker cross-encoder.

Le contexte renvoyé 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 de QA. Ces tableaux comparent des bras de récupération contrôlés, pas la qualité de réponse de l'utilisateur final ni le score d'un classement d'un autre produit.
• Les comptages de jetons utilisent une heuristique d'environ quatre caractères par jeton. La réduction compare la botte de foin indexée avec les morceaux renvoyés ; ce n'est pas une économie de coût facturé.
• 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 véritables coffres interconnectés.
• Le juge QA optionnel utilise Anthropic plutôt que la configuration GPT-4o des articles, donc ces résultats QA sont utiles pour des ablations relatives—pas des comparaisons de classements publiés.

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

Confidentialité et limites

• Le coffre est en texte clair par conception, pas un stockage chiffré. AgentCairn masque les modèles d'identifiants reconnus avant ses écritures automatisées de corps/titre/balises ; les modèles inconnus et les modifications manuelles restent de votre responsabilité.
• Les fichiers du coffre sont réservés au propriétaire (0600/0700). Comme le coffre est en texte clair et que le masquage est au mieux, le mode de fichier est en pratique son seul contrôle d'accès. Les configurations avec GID partagé (par ex. deux conteneurs Docker sur le même groupe mais avec des UID différents) nécessitent un accès de groupe, donc vault_group_writable = true élargit les nouvelles notes et répertoires du coffre à 0660/0770. C'est volontairement opt-in : sur macOS, le groupe principal de chaque utilisateur local est staff, donc un défaut lisible par le groupe exposerait vos mémoires aux autres comptes de la machine. Le réglage n'élargit jamais rien en dehors du coffre — l'index, les registres, les fichiers de verrouillage et ~/.agentcairn/config.toml restent privés.
• Les fonctionnalités cloud sont des sorties explicites. Le défaut reste local. Opter pour un embedder cloud ou un juge LLM envoie le texte masqué restant à ce fournisseur.
• Le projet est en version bêta. L'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 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 hooks de cycle de vie.
• L'automatisation est spécifique à la plateforme. La planification gérée cible launchd de macOS et crontab utilisateur de Linux ; utilisez votre propre planificateur ailleurs.

Développement

agentcairn utilise uv exclusivement pour la gestion des dépendances et les outils.

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 de brevet explicite. Copyright © 2026 Charles C. Figueiredo.