Déploiement et mise en pratique de MemPalace : un système de mémoire IA que vous ne perdrez jamais

Difficulté moyenne · ~20 minutes · Vous maîtriserez le déploiement complet de MemPalace, comprendrez la structure en couches de Palace et apprendrez à brancher ce système de mémoire via MCP sur n’importe quelle IA.

---

Public cible

1-3 ans d’expérience en développement, déjà familiers avec des outils de programmation assistée par IA comme Claude Code / Cursor / Copilot. Le but est de permettre à l’IA de conserver la mémoire du contexte sur des projets au long cours, sans repartir de zéro à chaque fois.

---

Dépendances essentielles et environnement

• Python : 3.9+
• Dépendances principales : chromadb>=0.5.0,<0.7, pyyaml>=6.0
• Installation : pip install mempalace ou uv pip install mempalace
• Système d’exploitation : macOS / Linux / Windows (WSL inclus)
• Stockage : ChromaDB (base vectorielle) + SQLite (graphe de connaissances), stockage entièrement local, sans réseau

---

Structure complète du projet

mempalace/
├── mempalace/                 # Package Python cœur
│   ├── cli.py                 # Entrée CLI, redirige vers mine/search/init, etc.
│   ├── mcp_server.py          # Serveur MCP, expose 19 outils
│   ├── knowledge_graph.py     # Graphe de connaissances temporel (SQLite)
│   ├── palace_graph.py        # Carte de navigation Palace (parcours BFS, détection des tunnels)
│   ├── convo_miner.py         # Extraction de dialogue, découpage par Q/R
│   ├── miner.py               # Extraction de fichiers du projet, découpage par paragraphes
│   ├── searcher.py            # Recherche sémantique (ChromaDB)
│   ├── normalize.py           # Normalisation de 5 formats de dialogue
│   ├── dialect.py             # Dialecte compressé AAAK
│   ├── layers.py              # Pile de mémoire en quatre couches (L0-L3)
│   ├── onboarding.py          # Initialisation guidée
│   ├── entity_detector.py     # Détection automatique des noms de personnes / projets
│   └── split_mega_files.py    # Découpage et fusion des fichiers de session
├── hooks/                     # Crochets pour sauvegarde automatique par Claude Code
│   ├── mempal_save_hook.sh     # Sauvegarde toutes les 15 messages
│   └── mempal_precompact_hook.sh  # Sauvegarde d’urgence avant compression du contexte
├── benchmarks/               # Benchmarks reproductibles (LongMemEval / LoCoMo)
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

Étapes pas à pas

Step 1 : Installation

pip install mempalace

La version minimale de Python est 3.9. Une fois l’installation terminée, vérifiez que c’est utilisable :

mempalace --version

---

Step 2 : Initialiser le palais de la mémoire

mempalace init ~/projects/myapp

La commande init démarre un parcours guidé qui vous pose successivement des questions :

• les personnes avec qui vous collaborez souvent (ajoutées à la configuration wing)
• le(s) projet(s) sur lequel/lesquels vous travaillez (un wing par projet)
• votre identité IA (écrite dans la couche L0)

À la fin du guidage, deux fichiers de configuration sont générés :

• ~/.mempalace/config.json — configuration globale (chemin du palace, etc.)
• ~/.mempalace/wing_config.json — mapping wing ↔ mots-clés

Le wing_config.json généré ressemble globalement à ceci :

{
  "default_wing": "wing_general",
  "wings": {
    "wing_kai": { "type": "person", "keywords": ["kai", "kai's"] },
    "wing_driftwood": { "type": "project", "keywords": ["driftwood", "analytics", "saas"] }
  }
}

À chaque démarrage, il suffit de charger L0 + L1 (environ 170 tokens) pour comprendre comment « est votre monde ».

---

Step 3 : Extraire (miner) les données

MemPalace prend en charge deux modes d’extraction. Choisissez selon votre source de données.

Mode A : extraire les fichiers du projet (code, documents, notes)

mempalace mine ~/projects/myapp

Le miner scanne récursivement le dossier, découpe par paragraphes, puis stocke dans ChromaDB et place le contenu original dans le Drawer.

Mode B : extraire l’export de dialogues (Claude/ChatGPT/Slack)

# Utilisation de base
mempalace mine ~/chats/ --mode convos

# Spécifier un wing, pratique pour filtrer ensuite par projet
mempalace mine ~/chats/ --mode convos --wing myapp

# Activer la catégorisation automatique (extraire décisions, préférences, jalons, questions, contexte émotionnel)
mempalace mine ~/chats/ --mode convos --extract general

Le convo_miner découpe les dialogues par Q/R et détecte automatiquement à quel room ils appartiennent (via la correspondance de plus de 70 modes de room_detector_local.py, sans API).

---

Step 4 : Vérifier avec la recherche sémantique

Une fois l’extraction terminée, faites un test :

mempalace search "why did we switch to GraphQL"

Ajoutez un filtre par wing pour ne chercher que dans un projet précis :

mempalace search "auth decision" --wing driftwood

Rendez encore plus précis en ajoutant le filtre room :

mempalace search "auth decision" --wing driftwood --room auth-migration

Le résultat renvoie le texte original dans le Drawer (verbatim), sans résumé et sans perte d’information. ChromaDB effectue la recherche vectorielle, et Closet produit un résumé structuré.

---

Step 5 : Intégrer le service MCP

MCP (Model Context Protocol) permet à MemPalace d’exposer ses outils à n’importe quelle IA. Une configuration une fois, pour toujours.

Intégration à Claude Code :

claude mcp add mempalace -- python -m mempalace.mcp_server

Après configuration, Claude Code obtient automatiquement 19 outils. L’IA appelle mempalace_search quand c’est nécessaire : vous n’avez rien à chercher manuellement.

Intégration à Gemini CLI :

# Voir examples/gemini_cli_setup.md
claude mcp add mempalace -- python -m mempalace.mcp_server

Gemini CLI supporte MCP de façon plus poussée, et les save hooks peuvent également être configurés automatiquement.

Liste des outils MCP (19) :

À partir du retour de mempalace_status, l’IA apprend automatiquement la syntaxe AAAK et le protocole mémoire, sans que vous ayez besoin de configurer quoi que ce soit dans les prompts.

---

Step 6 : Configurer les Auto-Save Hooks de Claude Code

Les Hooks de Claude Code permettent à MemPalace de sauvegarder automatiquement la mémoire à chaque échange.

Modifiez ~/.claude/settings.json (configuration globale de Claude Code) et ajoutez :

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

Différences entre les deux hooks :

• Stop : déclenché toutes les 15 messages, sauvegarde structurée — le thème, les décisions, les citations, et les modifications de code sont tous enregistrés, tout en reconstruisant la couche L1 (couche de faits clés).
• PreCompact : déclenché juste avant la compression du contexte. Il sauvegarde en urgence la mémoire pas encore enregistrée afin d’éviter de perdre un contexte important pendant la compression.

---

Step 7 : Comprendre la structure de Palace

L’abstraction centrale de MemPalace est « le palais de la mémoire » : en s’inspirant de la mnémotechnique des orateurs de la Grèce antique, elle remplace l’index de recherche à plat par une structure spatiale.

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer  │  ← Le texte original y est stocké
    └──────────┘      └──────────┘

  TUNNEL (connexion inter-wings) :
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings : une personne ou un projet, principal classement des mémoires. Sous chaque wing, il peut y avoir plusieurs rooms.

Rooms : thèmes précis au sein d’un wing, comme auth-migration, ci-pipeline, pricing. Si une room du même nom apparaît dans des wings différents, un tunnel est automatiquement généré.

Halls : des couloirs correspondant aux types de mémoire ; chaque wing possède le même ensemble de halls :

• hall_facts — décisions déjà verrouillées
• hall_events — sessions, jalons, processus de débogage
• hall_discoveries — percées et nouvelles intuitions
• hall_preferences — habitudes, préférences, avis
• hall_advice — recommandations et solutions

Closets : couche de résumé, qui pointe vers l’emplacement où le contenu original se trouve (Drawer). Le texte original n’est pas perdu : il est simplement enrichi d’une structure navigable.

Drawers : lieu où le texte original est stocké. Le mode raw verbatim de MemPalace lit précisément ici le contenu original pour effectuer la recherche vectorielle, ce qui permet d’atteindre 96,6 % de reproductibilité R@5.

---

Step 8 : Relations temporelles avec le Knowledge Graph

ChromaDB stocke des vecteurs du texte original. Le Knowledge Graph (SQLite) stocke des triplets de faits structurés. Les deux sont complémentaires.

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# Ajoutez des faits, avec période de validité
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")

# Que fait Kai maintenant
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# Que se passe-t-il le 2026-01-20 (à ce moment-là, Maya n’a pas encore terminé auth-migration)
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# Voir la chronologie du projet Orion
print(kg.timeline("Orion"))
# → chaîne de faits triés dans l’ordre chronologique

# Maya change de projet : l’ancien fait devient invalide
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# Désormais, query_entity("Maya") ne retourne plus auth-migration

Les fenêtres de validité des Facts (valid_from / ended) constituent la capacité clé de MemPalace : quand vous interrogez un état historique, vous savez « ce qui s’est passé à ce moment-là », et non « ce qui se passe maintenant ».

---

Step 9 : Architecture de la pile de mémoire en quatre couches

La stratégie de recherche de MemPalace se fait en quatre couches : plus on monte, plus c’est léger ; plus on descend, plus c’est précis.

À chaque démarrage, l’IA charge d’abord L0 + L1 (mempalace wake-up) : 170 tokens suffisent pour établir le contexte complet. La couche L2 n’est chargée que lorsque le sujet déclenche une room spécifique. La couche L3 n’est déclenchée que lorsque vous posez une question explicite, ce qui lance la recherche vectorielle exhaustive dans ChromaDB.

C’est précisément pour cela que MemPalace a un coût très faible : $10/an de coût de recherche contre $507/an pour la solution de résumés.

---

Dépannage des questions fréquentes

Q1 : Les résultats de recherche sont vides, mais vous êtes sûr que le contenu existe

Procédez en trois étapes :

# 1. Vérifiez que les noms de wing et room sont corrects
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. Élargissez la portée, sans spécifier wing/room (recherche globale)
mempalace search "mot-clé"   # sans --wing

# 3. Vérifiez que ChromaDB a bien été alimenté
mempalace status            # regardez si le nombre de drawers vaut 0

Si mempalace status indique 0 drawer, c’est que l’étape d’extraction n’a pas réussi. Cela peut venir du fait que le format du fichier de dialogue n’est pas pris en charge (actuellement : Claude Code JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON, texte brut).

Q2 : Conflit de nom de collection ChromaDB

Le nom de collection par défaut est mempalace_drawers. Si vous faites init plusieurs fois ou si vous lancez depuis des répertoires différents, vous pouvez rencontrer des conflits. Dans ~/.mempalace/config.json, spécifiez explicitement le chemin :

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers"
}

Puis remplacez avec --palace <path> :

mempalace search "query" --palace /custom/path/to/palace

Q3 : Échec de connexion MCP

Commencez par vérifier manuellement que le service MCP démarre bien :

python -m mempalace.mcp_server
# Normalement, aucune sortie n’apparaît : gardez le processus en premier plan
# Ctrl+C pour quitter

Si vous obtenez ModuleNotFoundError, vérifiez l’installation :

pip show mempalace

Si vous utilisez un environnement virtuel, assurez-vous que le chemin Python dans la configuration MCP de Claude Code est correct :

which python   # récupérer le chemin du python correct
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

Q4 : L’appel aux outils MCP fonctionne, mais le résultat n’est pas celui attendu

Quand l’IA appelle mempalace_search, les paramètres wing/room doivent correspondre précisément pour obtenir le meilleur effet de la structure Palace. Guidez l’IA dans le prompt pour utiliser les filtres corrects :

When searching for project-specific memories, always pass --wing <project>.
When searching for a specific topic, always pass --room <room-name>.

Q5 : Les scripts de hook ne se déclenchent pas

# Vérifier si les hooks de Claude Code sont activés
claude doctor

Vérifiez que les chemins des hooks dans settings.json sont des chemins absolus. Les chemins relatifs échouent car Claude Code peut travailler dans un répertoire différent selon le contexte.

Q6 : Résultats inattendus dans les requêtes temporelles du graphe de connaissances

Les requêtes temporelles dépendent du format de l’argument as_of : la date doit être YYYY-MM-DD :

# Format incorrect
kg.query_entity("Kai", as_of="2026/03/01")

# Format correct
kg.query_entity("Kai", as_of="2026-03-01")

Vérifiez aussi que lors de l’ajout de faits via add_triple, le champ valid_from utilise lui aussi le bon format, sinon la fenêtre temporelle ne prendra pas effet.

---

Lecture complémentaire / pistes d’optimisation

Couche expérimentale de compression AAAK

AAAK est un dialecte abrégé avec perte : il compresse les entités répétées en remplaçant via des expressions régulières, en les transformant en code. Sur des scénarios à grande échelle (par exemple, un même projet mentionné des centaines de fois), cela permet d’économiser des coûts de tokens. Mais pour l’instant, le mode raw verbatim (96,6 %) reste supérieur au mode AAAK (84,2 %). Les cas d’usage adaptés sont les projets longs, avec plusieurs sessions et des entités répétées très denses.

Isolation de mémoire multi-agents : Specialist Agents

Chaque agent dispose de son propre wing et de son journal AAAK :

~/.mempalace/agents/
  ├── reviewer.json    # qualité du code, conventions, bugs
  ├── architect.json   # décisions d’architecture, arbitrages
  └── ops.json         # déploiement, incidents, infrastructure

Au runtime, l’IA découvre dynamiquement les agents via palace : vous n’avez rien à écrire dans CLAUDE.md.

Reproduction des benchmarks

Dans le dossier benchmarks/, vous trouverez des scripts complets pour reproduire LongMemEval et LoCoMo :

python benchmarks/longmemeval_bench.py

Aucune clé API n’est nécessaire sur toute la durée. En 5 minutes sur un M2 Ultra, vous pouvez résoudre 500 questions et valider la reproductibilité à 96,6 %.

Comparaison horizontale avec d’autres systèmes

MemPalace est la seule solution à atteindre le meilleur score sans aucun appel API.