Guide MemPalace - Utilisation et Configuration

Ce guide explique comment installer, configurer et utiliser MemPalace de manière pratique, en local.

1) Vue d'ensemble

MemPalace est un systeme de memoire local-first pour IA :

• stockage verbatime des conversations et contenus (sans resume obligatoire)
• recherche semantique
• organisation en wings/rooms/halls
• backend local (ChromaDB par defaut)
• usage via CLI et serveur MCP

Objectif : retrouver rapidement decisions, contexte technique et historique de travail.

2) Prerequis

• Python 3.9+
• Environnement local (macOS/Linux/Windows)
• Espace disque libre (modele d'embeddings + base locale)

3) Installation

Installation standard :

pip install mempalace

Verifier l'installation :

mempalace --help

4) Initialisation

Initialiser un espace de travail memoire (palace) :

mempalace init ~/projects/myapp

Cela prepare notamment la structure de configuration de base.

5) Commandes essentielles

5.1 Miner des donnees

Projet/fichiers :

mempalace mine ~/projects/myapp

Conversations/export chats :

mempalace mine ~/chats --mode convos

Conversations avec extraction generale :

mempalace mine ~/chats --mode convos --extract general

Associer explicitement a un wing :

mempalace mine ~/chats --mode convos --wing myapp

5.2 Recherche

Recherche globale :

mempalace search "pourquoi on a choisi GraphQL"

Recherche filtree par wing :

mempalace search "decision auth" --wing myapp

Recherche filtree par room :

mempalace search "migration" --room auth-migration

5.3 Etat et contexte

Etat du palace :

mempalace status

Charger un contexte court de session :

mempalace wake-up

Version wing specifique :

mempalace wake-up --wing myapp

6) Configuration

6.1 Configuration globale

Fichier : ~/.mempalace/config.json

Exemple :

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers",
  "people_map": {
    "Kai": "KAI",
    "Priya": "PRI"
  }
}

Points importants :

• palace_path : emplacement des donnees memoire
• collection_name : nom de collection vectorielle
• people_map : normalisation de noms/personnes

6.2 Configuration des wings

Fichier : ~/.mempalace/wing_config.json

Genere a l'init, puis personnalisable.

Exemple :

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

6.3 Identite

Fichier : ~/.mempalace/identity.txt

Ce contenu sert de couche identite (contexte de base charge en debut de session).

6.4 Changer l'emplacement du palace a la commande

La plupart des commandes acceptent :

--palace <path>

Utile pour separer plusieurs environnements (perso, client, labo, etc.).

7) MCP et integration assistant

MemPalace expose des outils MCP pour que l'assistant interroge la memoire directement.

7.1 Via plugin Claude (recommande dans la doc MemPalace)

claude plugin marketplace add MemPalace/mempalace
claude plugin install --scope user mempalace

7.2 Connexion MCP manuelle

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

Ensuite, l'assistant peut appeler les outils mempalace automatiquement (recherche, graph, drawers, etc.).

8) Hooks d'auto-save

MemPalace fournit des hooks pour sauvegarder regulierement la memoire et avant compactage de contexte.

Exemple de declaration (principe) :

{
  "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"
          }
        ]
      }
    ]
  }
}

Option auto-ingest : definir la variable d'environnement MEMPAL_DIR pour lancer un mine automatique sur ce dossier pendant les saves.

9) Workflow recommande

1. Installer puis initialiser.
2. Miner projet + conversations.
3. Verifier avec status.
4. Rechercher en global puis restreindre par wing/room.
5. Connecter MCP pour que l'assistant fasse les appels automatiquement.
6. Activer les hooks pour eviter la perte de contexte.

10) Depannage rapide

• Commande introuvable : verifier l'environnement Python actif.
• Resultats faibles : remine les sources et precise wing/room.
• Mauvaise classification de sujets : enrichir wing_config.json (keywords).
• MCP non detecte : verifier la commande d'ajout MCP et redemarrer l'outil client.

11) Bonnes pratiques

• Garder les donnees sensibles en local (mode local-first).
• Segmenter les wings par projet/personne pour une recherche plus nette.
• Utiliser des noms de rooms coherents (auth-migration, billing-refactor, etc.).
• Faire des re-indexations periodiques quand les sources evoluent fortement.

12) Securite des sources

Pour installer et verifier les informations, prioriser les sources officielles indiquees dans le depot GitHub MemPalace (README, releases, fichiers docs du repo).