Les agents autonomes de génération de code oublient tout dès qu’une session se termine. Quitter Claude Code au milieu d’un refactoring complexe pour ouvrir OpenAI Codex ou Command Code dans le même répertoire force l’opérateur à réexpliquer l’architecture, les pistes abandonnées et les bugs rencontrés.
L’outil open-source ai-memory élimine cette friction en compilant un wiki persistant et partagé au format Markdown, synchronisé via Git et piloté par le protocole MCP (Model Context Protocol).
Architecture et principes de fonctionnement
Le système repose sur un binaire unique écrit en Rust qui expose un serveur HTTP/MCP et centralise toutes les données dans une structure dédiée :
<data_dir>/
├── wiki/ # Source de vérité en Markdown, versionnée avec Git
├── raw/ # Segments bruts et assainis des flux de travail gérés
├── db/ # Index SQLite (FTS5, entités, embeddings vectoriels)
├── models/ # Espace réservé aux modèles d'embedding locaux
└── logs/ # Traces applicatives rotativesLe serveur sérialise les écritures via un unique gestionnaire d’écriture SQLite. Les hooks de cycle de vie transmettent les observations du terminal (prompts, cycle d’exécution des outils, compactages et fermetures de session). Un moteur compile ces observations sous la forme de pages structurées en Markdown, sans obliger l’utilisateur à créer manuellement des notes.
La recherche combine les résultats via l’algorithme RRF (Reciprocal Rank Fusion) sur quatre flux : la recherche plein texte SQLite FTS5, l’extraction lexicale d’entités, l’exploration des voisins dans le graphe de connaissances, et des vecteurs d’embeddings optionnels.
| Composant | Rôle technique | Impact sur l’agent |
|---|---|---|
| Wiki Git | Stockage durable des décisions, règles et procédures en Markdown brut. | Lisible par l’humain via Obsidian ou un simple terminal grep. |
| Base SQLite | Indexation rapide FTS5, métadonnées, sessions ouvertes et entités. | Recherche hybride instantanée sans latence LLM systématique. |
| Handoffs | Passages de relais injectés automatiquement au démarrage d’une session. | Reprise immédiate du contexte de travail entre outils hétérogènes. |
| Ledger d’événements | Journal visible et portable des interactions lors des lancements managés. | Continuité cross-harness transparente sans perte de fil d’exécution. |
Matrice de compatibilité et intégration des clients
L’outil s’interface avec un écosystème étendu de terminaux et d’environnements de développement :
- Linux : Plateforme cible principale, images Docker multi-architectures (linux/amd64 et linux/arm64), paquets natifs Arch Linux (AUR) avec unités systemd système et utilisateur.
- macOS : Binaires natifs
ai-memory-macos-aarch64.tar.gzetai-memory-macos-x86_64.tar.gzpour Apple Silicon et Intel. - Windows via WSL2 : Environnement Linux recommandé pour faire tourner l’agent.
- Windows Natif : Support expérimental avec binaire
ai-memory.exe, profil de commandes directes sans shell ou wrappers Docker Desktop. - Claude Code : Configuration MCP complète et hooks de cycle de vie. Le drapeau
--session-awareactive l’isolation par session via un pont stdio local. Capture optionnelle du tour final de l’assistant (double opt-in). - OpenAI Codex : MCP et hooks de cycle de vie natifs. Clôture manuelle possible avec
ai-memory finalize-sessionfaute d’événement natif de fin de session. - Command Code : Support MCP (
~/.commandcode/mcp.json) et 4 événements de cycle de vie (~/.commandcode/settings.json). Import d’événements visibles et reprise native v3 viaai-memory run command-code. - Devin CLI : Événement PostCompaction et injection de contexte via
hookSpecificOutput.additionalContext. - OpenCode : Configuration MCP distante et plugin TypeScript généré garantissant les règles d’exclusion de capture.
- Cursor, Gemini CLI, OpenClaw : Prise en charge standard MCP et hooks de cycle de vie.
- Oh My Pi (OMP) & Pi : Extension TypeScript générée injectant la capture de cycle de vie et pont MCP HTTP (
~/.pi/agent/extensions/ai-memory.ts). - Crush : Mode managé uniquement via
ai-memory run crushavec injection de contexte global temporaire. - Grok Build CLI : Configuration MCP (
~/.grok/config.toml) et hooks (~/.grok/hooks/ai-memory.json). Récupération des handoffs via l’outil MCPmemory_handoff_acceptcar le stdout au SessionStart est ignoré. Support managé via--rules. - Kimi Code : Support de 10 événements de cycle de vie (dont
PostToolUseFailure) configurés dans~/.kimi-code/config.toml. Handoff injecté via le stdout deUserPromptSubmit. - Kiro CLI : Prise en charge des moteurs v2 et v3 incompatible. Détection explicite via
ai-memory run kiro --v3ouinstall-hooks --agent kiro-cli-v3. - Zero : MCP HTTP natif (
~/.config/zero/config.json) et hooks via JSON sur stdin sans shell. Handoff récupéré via l’appel MCPmemory_handoff_accept. - Antigravity CLI : Alias
agy. Seul l’événement PreInvocation numéro 0 mappe vers SessionStart. Reprise managée supportée via--conversation. - Clients MCP purs (sans hooks de cycle de vie) : Claude Desktop (via
mcp-remote), VS Code GitHub Copilot agent mode (.vscode/mcp.json), Swival CLI, et Zed (context_serversdanssettings.json). - Hermes Agent : Ingestion communautaire reconnaissant la structure de payload shell-hook pour l’attribution de session.
Découverte et installation pas à pas
Je présente ici le déploiement local via Docker et le wrapper hôte, idéal pour préserver un poste de développement sans encombrer l’environnement système.
1. Installation du wrapper CLI
Nous téléchargeons le script léger qui redirige les commandes vers le conteneur Docker :
mkdir -p ~/.local/bin
wrapper_tmp="$(mktemp -d)"
trap 'rm -rf "$wrapper_tmp"' EXIT
wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper
curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper"
curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256"
expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")"
actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
[ "$actual" = "$expected" ] || { echo "Erreur d'empreinte SHA256" >&2; exit 1; }
install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory
rm -rf "$wrapper_tmp"
trap - EXIT2. Démarrage du serveur conteneurisé
Le conteneur se lie par défaut sur l’interface de bouclage locale 127.0.0.1:49374, interdisant tout accès externe sans configuration explicite :
docker run -d --name ai-memory \
--restart unless-stopped \
-p 127.0.0.1:49374:49374 \
-v ai-memory-data:/data \
-e AI_MEMORY_LLM_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY=sk-ant-api03-... \
-e AI_MEMORY_EMBEDDING_PROVIDER=openai \
-e OPENAI_API_KEY=sk-proj-... \
akitaonrails/ai-memory:latest3. Liaison de l’agent de codage
J’applique les configurations MCP et les hooks d’interception sur mon terminal de travail en deux commandes idempotentes :
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
ai-memory install-instructionsL’option
install-instructionsmet en place le marqueur compact<!-- ai-memory:start -->et installe les Agent Skills guidant l’IA vers les bons outils MCP.
Configuration des moteurs LLM et d’Embeddings
Le serveur fonctionne parfaitement en mode “Zero-LLM” : les hooks capturent les sessions, les recherches utilisent SQLite FTS5 couplé aux entités, et la consolidation génère des synthèses déterministes à base de règles. L’ajout d’un fournisseur d’inférence active la consolidation avancée, la détection de contradictions lors du linting et l’analyse continue des apprentissages.
| Fournisseur | Modèle par défaut | Cas d’usage recommandé |
|---|---|---|
anthropic | claude-haiku-4-5 | Qualité optimale de consolidation et extraction rigoureuse de règles. |
anthropic-oauth | claude-sonnet-4-6 | Abonnement Claude Pro/Max via claude setup-token sans clé API standard. |
openai | gpt-5.4-mini | Solution hébergée rapide et économique. |
openai-oauth | gpt-5.5 | Abonnement ChatGPT Pro/Plus via ai-memory auth login openai-oauth. |
copilot | gpt-5.5 | Authentification GitHub Copilot Chat via jeton OAuth. |
gemini | gemini-2.5-flash | Inférence Google rapide avec un quota gratuit généreux. |
openai-compat | Manuel | Moteurs locaux ou tiers : Ollama, vLLM, LM Studio, OpenRouter. |
Pour les petits modèles locaux hébergés sur Ollama ou vLLM, je recommande d’ajuster les fenêtres de contexte dans le fichier de configuration :
[consolidation]
max_input_tokens = 6500
max_output_tokens = 1000Gestion des espaces de travail et isolation par projet
L’isolation multi-projets est garantie par conception. Chaque projet réside sous l’arborescence <wiki_root>/<workspace_id>/<project_id>/ indexée par des UUIDs stables. Le chemin du projet dérive du répertoire de travail ($cwd). Les sous-commandes de l’outil remontent jusqu’à la racine du dépôt Git principal, permettant aux branches de travail (git worktrees) de partager la même mémoire.
Pour isoler explicitement un mono-repo ou scinder des contextes clients, déposez un fichier .ai-memory.toml dans un répertoire parent :
workspace = "client-acme"
project = "backend-api"
[capture]
ignore_paths = ["secrets/*", "**/*.env", "vendor/**"]La portée réservée _global (écrite via memory_write_page avec scope: "global") stocke vos préférences universelles, règles de style et choix technologiques transversaux. Toute interrogation standard memory_query fusionne ces règles dans les résultats sans pollution croisée des historiques de session.
Exemples d’utilisation et cas concrets
1. Continuité transparente entre plusieurs agents (Workstreams Managés)
J’amorce une tâche complexe avec Claude Code, je bascule sur Codex avec exécution automatique des commandes, puis je finalise sur Command Code dans le même répertoire :
# Démarrage d'une session de travail sur Claude Code
ai-memory run claude
# Interruption du travail, puis bascule immédiate sur OpenAI Codex
ai-memory run codex --yolo
# Poursuite des tests sous Command Code avec préservation du ledger
ai-memory run command-code
# Reprise ultérieure automatique du dernier harnais actif
ai-memory run
# Lancement d'une session neuve tout en conservant l'historique partagé
ai-memory run --fresh codexPour reprendre le travail depuis n’importe quel dossier sans spécifier de nom :
ai-memory continue2. Initialisation d’un projet historique (Bootstrap)
Pour amorcer la mémoire d’un dépôt contenant des mois de commits sans historique ai-memory :
cd /chemin/vers/mon-projet
ai-memory bootstrapLa commande analyse le journal Git, le README, les documentations sous docs/ et les en-têtes de modules pour synthétiser un premier jeu de pages de référence.
3. Enregistrement d’une décision architecturale durable
L’enregistrement d’une note pérenne s’effectue directement depuis le terminal ou via l’agent par l’outil MCP memory_write_page :
ai-memory write-page \
--path decisions/0004-nats-jetstream.md \
--body $'# Choix de NATS JetStream pour la file d\'attente\n\nNous standardisons nos échanges asynchrones sur NATS JetStream afin de garantir la livraison At-Least-Once sans la complexité opérationnelle de Kafka.' \
--pinnedL’indicateur --pinned immunise la page contre les purges automatiques d’obsolescence (decay sweep). Vous pouvez également définir une date d’expiration temporaire avec expires_at (format RFC3339 ou YYYY-MM-DD).
4. Rétroaction sur la fraîcheur des données
Lorsqu’une décision devient obsolète, l’agent utilise l’outil MCP memory_feedback :
// Appel tool MCP exécuté par l'agent
memory_feedback({
"path": "decisions/0001-legacy-auth.md",
"signal": "stale",
"reason": "Remplacé par l'implémentation OIDC documentée dans decisions/0003-oidc.md"
});Le signal stale ou wrong abaisse la saillance de la note et l’affiche comme anomalie dans le rapport memory_lint sans supprimer le fichier brutalement.
Interface Web, API REST et Administration
L’option --enable-web active sur le même port réseau l’interface de navigation graphique (accessible via http://127.0.0.1:49374/web) ainsi qu’une API REST JSON préfixée par /api/v1 :
# Consultation de l'état global du serveur et des modèles
ai-memory status
# Inspection de l'activité des clients MCP sur les 7 derniers jours
curl -s http://127.0.0.1:49374/admin/activity/by-client?since_days=7
# Récupération de la vue synthétique d'un projet via l'API REST
curl -s http://127.0.0.1:49374/api/v1/workspaces/default/projects/mon-projet/overview
# Restauration ciblée d'une page corrompue depuis un commit Git spécifique
ai-memory checkpoints
ai-memory restore-page --path decisions/0004-nats-jetstream.md --from a1b2c3d
# Purge complète et atomique d'un environnement de test
ai-memory purge-project --project prototype-client --confirmLe serveur agit comme source unique de vérité. La commande finalize-session permet de fermer proprement les sessions orphelines en générant les synthèses nécessaires sans jamais manipuler manuellement la base SQLite sous-jacente.