Chaque session avec un agent de code IA recommence à zéro. L’agent ne sait pas que vous avez passé trois jours à refactoriser l’architecture d’authentification la semaine dernière. Il ne sait pas que UserService a deux interfaces concurrentes que vous résolvez progressivement. Il ne sait pas que vous avez décidé d’éviter telle bibliothèque après un incident de production.
Vous expliquez. L’agent comprend. La session se termine. Le lendemain, vous expliquez à nouveau.
C’est le problème du démarrage à froid, et c’est une friction réelle sur des codebases sérieuses.
agentmemory est une tentative open source d’y répondre directement : de la mémoire persistante pour agents de code IA, délivrée via le Model Context Protocol, sans base de données externe, avec 8 800 étoiles GitHub au compteur.
Le problème du démarrage à froid
Un agent de code sans mémoire est intrinsèquement sans état. Chaque session est une première rencontre. Sur un projet d’une journée, c’est tolérable. Sur un projet de six mois avec plusieurs agents actifs, c’est une source de friction chronique.
Les solutions habituelles ont des limites évidentes :
- Contexte de session brut : vous collez votre
CLAUDE.mdet votre README au début de chaque session. Coût en tokens élevé, couverture partielle, aucune adaptation à ce que l’agent a réellement appris. - Résumés LLM : générer un résumé en fin de session et le recharger au début. Coût : environ 22 000 tokens par session selon les benchmarks d’agentmemory, soit environ 650 000 tokens par an.
- Pas de mémoire du tout : l’agent reconstruit le contexte à partir des fichiers à chaque fois. Lent, incomplet, répétitif.
Ce qu’il faut, c’est un système qui capture ce que l’agent fait, le compresse de manière sélective, et le rappelle avec précision quand c’est pertinent — sans inonder le contexte.
Ce qu’est agentmemory
agentmemory est un serveur MCP (Model Context Protocol) qui agit comme une couche mémoire persistante entre les agents et leurs sessions de travail. Il expose 51 outils MCP que les agents utilisent pour stocker et rappeler des observations. Il s’intègre via 12 hooks automatiques qui se déclenchent sur les événements du cycle de vie de l’agent sans intervention manuelle.
Tout tourne localement. Pas de Redis, pas de Postgres, pas de base vectorielle externe. SQLite + index vectoriel en processus, construit sur le moteur iii.
La compatibilité est large : Claude Code (12 hooks + MCP), Cursor, Codex CLI, Gemini CLI, OpenClaw, Hermes, Cline, Windsurf, Roo Code, Claude Desktop, Aider et plus de 20 autres clients MCP.
Les chiffres clés revendiqués :
| Métrique | Valeur |
|---|---|
| Rappel R@5 (LongMemEval-S, ICLR 2025) | 95,2% |
| Réduction de tokens vs résumé LLM | 92% |
| Outils MCP exposés | 51 |
| Hooks automatiques | 12 |
| Bases de données externes requises | 0 |
| Tests validés | 827 |
Architecture mémoire — le pipeline complet
Le flux de vie d’une mémoire dans agentmemory suit une progression en plusieurs étapes, de la capture à la récupération.
┌─────────────────────────────────────────────────────────────────────┐
│ PIPELINE DE CYCLE DE VIE MÉMOIRE │
└─────────────────────────────────────────────────────────────────────┘
SESSION ACTIVE
─────────────
Action agent ──▶ Hook déclenché ──▶ Filtrage vie privée
(PostToolUse, (automatique, (API keys, secrets
SessionStop, 0 intervention) supprimés)
PreToolUse...)
│
▼
┌──────────────────────────────────────┐
│ STOCKAGE MÉMOIRE │
│ │
│ SQLite ──▶ Index vectoriel │
│ (métadonnées, (all-MiniLM-L6-v2 │
│ relations, en local, gratuit) │
│ horodatage) │
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ SCORING DE CONFIANCE │
│ │
│ Confiance initiale : haute │
│ Déclin selon courbe Ebbinghaus ──▶ │
│ Sans utilisation → déclin auto │
│ Avec réutilisation → renforcement │
└──────────────────┬───────────────────┘
│
SESSION SUIVANTE ▼
─────────────────────────────────────
Requête agent ──▶ RECHERCHE HYBRIDE
│
┌──────────┼──────────┐
▼ ▼ ▼
BM25 Vecteurs Graphe de
(exact) (sémantique) connaissances
│ │ │
└──────────┴──────────┘
│
Reciprocal Rank Fusion (k=60)
│
▼
Top-5 mémoires rappelées ──▶ Contexte agent
(R@5 = 95,2%) (~1 900 tokens)
La consolidation en quatre niveaux — mémoire de travail → épisodique → sémantique → procédurale — suit une logique inspirée de la psychologie cognitive. Ce qui est fréquemment utilisé monte dans la hiérarchie et devient plus stable.
Partage de mémoire multi-agent
Un serveur agentmemory peut servir plusieurs agents simultanément. Claude Code, Cursor et Gemini CLI peuvent tous pointer vers la même instance — et partager le même store mémoire.
┌─────────────────────────────────────────────────────────────────────┐
│ ARCHITECTURE MULTI-AGENT │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Claude Code │ │ Cursor │ │ Gemini CLI │
│ 12 hooks │ │ MCP │ │ MCP │
│ + MCP │ │ │ │ │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ MCP (port 3111) │
└───────────────────┼───────────────────┘
│
▼
┌──────────────────────────┐
│ SERVEUR AGENTMEMORY │
│ │
│ 51 outils MCP exposés │
│ 12 hooks automatiques │
│ REST API (107 endpoints)│
│ Viewer temps réel :3113 │
└──────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ STORE MÉMOIRE │
│ │
│ SQLite ── Index vectoriel │
│ ── Graphe de │
│ connaissances │
│ │
│ Zéro base de données │
│ externe requise │
└──────────────────────────────┘
┌─────────────┐ ┌─────────────┐
│ Codex CLI │ │ Cline / │
│ 6 hooks │ │ Windsurf / │
│ + MCP │ │ + 20 MCP │
└──────┬──────┘ └──────┬──────┘
│ │
└─────────┬─────────┘
│
▼ (même serveur, même store)
En pratique : si vous utilisez Claude Code le matin et Cursor l’après-midi sur le même projet, les deux agents partagent les mêmes mémoires. Ce que l’un a appris est disponible pour l’autre.
Recherche hybride et le R@5 à 95,2%
Le chiffre de 95,2% de rappel R@5 vient du benchmark LongMemEval-S présenté à l’ICLR 2025. R@5 signifie : parmi les 5 mémoires récupérées, la bonne réponse est présente dans 95,2% des cas.
Atteindre ce niveau nécessite la combinaison de trois signaux de recherche.
Pourquoi la recherche sémantique seule ne suffit pas. La recherche vectorielle encode la similarité de sens. Elle est bonne pour retrouver “cette fonctionnalité qui gère l’authentification”. Elle rate les correspondances exactes : noms de fonctions précis, codes d’erreur, numéros de version. ERR_TLS_CERT_EXPIRED est différent d’ERR_TLS_CERT_REVOKED sémantiquement, mais un vecteur peut les rapprocher.
Pourquoi BM25 seul ne suffit pas. BM25 est un algorithme de correspondance lexicale. Il trouve les mémoires qui contiennent exactement les mêmes mots que la requête. Mais si vous demandez “comment fonctionne le module de connexion” et que la mémoire parle du “système d’authentification”, BM25 ne fait pas le lien sémantique.
La fusion par Reciprocal Rank Fusion (k=60). agentmemory combine les classements produits par BM25, les embeddings vectoriels et le graphe de connaissances via RRF. Chaque source vote pour des mémoires candidates, et le classement final reflète le consensus des trois signaux. Le résultat capture à la fois les correspondances exactes et la similarité sémantique.
┌──────────────────────────────────────────────────────────────────────┐
│ BENCHMARK R@5 — COMPARAISON DES APPROCHES │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ Sans mémoire ████░░░░░░░░░░░░░░░░░░░░░░ ~10% │
│ (reconstruction) │
│ │
│ Dump naïf du ████████████████░░░░░░░░░░ ~63% │
│ contexte complet │
│ │
│ Sémantique seule ████████████████████░░░░░░ ~82% │
│ (vecteurs) │
│ │
│ agentmemory █████████████████████████▌ 95,2% │
│ (hybride RRF) │
│ │
│ ────────────────────────────────────────────── │
│ 0% 25% 50% 75% 100% │
└──────────────────────────────────────────────────────────────────────┘
Source : LongMemEval-S, ICLR 2025
La réduction de 92% des tokens — comment ça fonctionne
Le chiffre de 92% mérite une explication concrète, car il ne vient pas de magie de compression.
Sans mémoire persistante, deux approches dominent :
- Contexte complet rechargé : vous donnez à l’agent toute la documentation, les fichiers de configuration, les notes du projet. Coût élevé, information souvent hors sujet.
- Résumé LLM : vous faites résumer la session précédente par le modèle, et rechargez ce résumé. agentmemory mesure cette approche à environ 22 000 tokens par session, soit environ 650 000 tokens sur un an d’utilisation régulière.
agentmemory fait autre chose : il récupère sélectivement les 5 mémoires les plus pertinentes pour la requête en cours, et uniquement celles-là. Coût moyen mesuré : environ 1 900 tokens par session. Sur un an, environ 170 000 tokens — soit une réduction de 92% par rapport à l’approche résumé LLM, et d’environ $10/an avec des embeddings locaux.
La clé est “sélectivement”. R@5 = 5 mémoires rappelées. Pas un dump du contexte complet. Pas un résumé qui recapitule tout. Juste ce qui est pertinent maintenant.
Graphes de connaissances vs mémoire plate
La plupart des systèmes de mémoire stockent des observations sous forme clé-valeur : “l’agent a fait X à l’instant T”. C’est utile mais limité.
agentmemory construit des relations entre entités. Quand l’agent apprend que la fonction authenticate() appelle validateToken() qui dépend de JWTService, cette chaîne est stockée comme des arcs dans un graphe de connaissances — pas comme trois observations isolées.
L’effet concret : quand vous demandez plus tard comment fonctionne l’authentification, le graphe traverse les relations et remonte la chaîne complète, même si vous n’avez jamais mentionné JWTService dans votre requête.
La recherche hybride fusionne ensuite les résultats du graphe avec ceux de BM25 et des vecteurs via RRF, ce qui explique en partie pourquoi le R@5 dépasse la recherche sémantique seule de manière significative.
Installation et intégration — walkthrough Claude Code
L’installation de base est directe :
# Démarrer le serveur agentmemory
npx @agentmemory/agentmemory
Le serveur écoute sur trois ports :
- 3111 : API REST (107 endpoints)
- 3113 : Console de visualisation en temps réel
- 49134 : Bridge iii
Pour Claude Code, l’intégration utilise à la fois MCP et les 12 hooks automatiques. Ajoutez agentmemory à votre configuration MCP :
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
Les 12 hooks de Claude Code se déclenchent sur : SessionStart, SessionStop, PreToolUse, PostToolUse, Stop, et les variantes de notification. Ils capturent automatiquement ce que l’agent fait sans que vous ayez à appeler explicitement les outils mémoire.
Pour les clients MCP standard (Cursor, Gemini CLI, etc.), la configuration MCP ci-dessus suffit. L’agent peut ensuite appeler les 51 outils mémoire exposés directement : store_memory, smart_search, observe, get_context, et les autres.
Les embeddings locaux (all-MiniLM-L6-v2) fonctionnent par défaut sans clé API. OpenAI, Gemini, Voyage AI, Cohere et OpenRouter sont supportés si vous voulez des embeddings cloud.
La Console iii
Le moteur iii inclut une console de visualisation accessible sur le port 3113. C’est un visualiseur en temps réel qui permet d’inspecter :
- Les mémoires actuellement stockées et leurs scores de confiance
- Les hits de rappel — quelles mémoires ont été récupérées pour quelle requête
- La courbe de déclin des mémoires peu utilisées
- Les arcs du graphe de connaissances
C’est utile pendant le débogage du système ou pour comprendre pourquoi certaines mémoires sont rappelées (ou ne le sont pas). En production normale, vous ne l’utilisez probablement pas souvent, mais c’est plus agréable que d’inspecter des tables SQLite brutes.
Évaluation honnête — limites et points à surveiller
agentmemory est un projet sérieux avec de vrais résultats de benchmark. Mais il y a des réserves à formuler avant d’en faire la colonne vertébrale de votre workflow.
C’est jeune. Le projet est à 8 800 étoiles et actif, mais la v1 vient d’être publiée. L’API et le schéma de stockage peuvent évoluer. Si vous construisez des automatisations autour, prévoyez des migrations.
Les benchmarks ont un contexte. LongMemEval-S est un benchmark académique standardisé — c’est bien, c’est reproductible. Mais votre codebase n’est pas un benchmark académique. Le R@5 réel dépend de la qualité de ce que les hooks capturent, de la densité sémantique de vos conversations, et de la façon dont vous avez configuré les embeddings.
La réduction de tokens présuppose une baseline. Le 92% est mesuré contre l’approche “résumé LLM complet par session”. Si votre baseline actuelle est “pas de mémoire du tout, reconstruction depuis les fichiers”, la comparaison est différente.
Le moteur iii est une dépendance opaque. agentmemory est construit sur le moteur iii, décrit comme un système de primitives remplaçant Express, SQLite standalone, Redis, pm2 et Prometheus. C’est 123 fonctions sur ~21 800 lignes de code. Si vous rencontrez un bug dans cette couche, le débogage peut être complexe.
La confidentialité mérite attention. Le filtrage automatique des secrets (clés API, tokens) est une bonne chose. Mais vérifiez ce que les hooks capturent effectivement sur votre projet avant de déployer en environnement sensible. Inspectez la console iii.
Conclusion
agentmemory résout un problème réel avec une architecture technique cohérente. Le choix MCP est bon — si votre agent supporte MCP, l’intégration est directe. Les chiffres de benchmark (95,2% R@5, 92% de réduction de tokens) sont sérieux et sourcés.
Ce qui est intéressant dans l’approche : la combinaison de hooks automatiques et d’outils MCP signifie que les agents n’ont pas besoin d’apprendre de nouveaux comportements. Les hooks capturent passivement, les outils sont disponibles si l’agent veut accéder à la mémoire activement.
Pour un projet en production avec plusieurs agents actifs sur la même codebase, agentmemory mérite une évaluation sérieuse. Pour un usage solo sur des projets courts, le coût opérationnel d’un serveur local persistant peut ne pas valoir les bénéfices.
Le dépôt GitHub est à github.com/rohitg00/agentmemory, sous licence Apache 2.0. La console de visualisation sur le port 3113 est le premier endroit où aller pour comprendre ce que le système fait réellement avec vos mémoires.