Despliegue y práctica con MemPalace: crea un sistema de memoria de IA que nunca olvida

Dificultad media · ~20 minutos · Aprenderás el flujo completo de despliegue de MemPalace, comprenderás la estructura por capas de Palace y aprenderás a integrar este sistema de memoria en cualquier IA usando MCP.

---

Público objetivo

1-3 años de experiencia como desarrollador, ya has usado herramientas de programación con IA como Claude Code / Cursor / Copilot. Buscas que la IA mantenga memoria de contexto en proyectos a largo plazo, y que no tenga que empezar desde cero cada vez.

---

Dependencias clave y entorno

• Python: 3.9+
• Dependencias principales: chromadb>=0.5.0,<0.7、pyyaml>=6.0
• Modo de instalación: pip install mempalace o uv pip install mempalace
• Sistema operativo: macOS / Linux / Windows (WSL también sirve)
• Almacenamiento: ChromaDB (base vectorial) + SQLite (grafo de conocimiento); todo se guarda localmente, sin necesidad de red

---

Estructura completa del proyecto

mempalace/
├── mempalace/                 # Paquete Python principal
│   ├── cli.py                 # Entrada de CLI, enruta a mine/search/init, etc.
│   ├── mcp_server.py          # Servidor MCP, expone 19 herramientas
│   ├── knowledge_graph.py     # Grafo de conocimiento temporal (SQLite)
│   ├── palace_graph.py        # Mapa de navegación de Palace (BFS, descubrimiento de túneles)
│   ├── convo_miner.py         # Minería de conversaciones, segmenta por Q+A
│   ├── miner.py               # Minería de archivos del proyecto, segmenta por párrafos
│   ├── searcher.py            # Búsqueda semántica (ChromaDB)
│   ├── normalize.py           # Normalización de 5 formatos de conversación
│   ├── dialect.py             # Dialecto AAAK (compresión)
│   ├── layers.py              # Pila de memoria de cuatro capas (L0-L3)
│   ├── onboarding.py          # Inicialización guiada
│   ├── entity_detector.py     # Detección automática de nombres de personas/proyectos
│   └── split_mega_files.py    # Divide y combina archivos de sesión
├── hooks/                     # Hooks para guardado automático en Claude Code
│   ├── mempal_save_hook.sh     # Guarda automáticamente cada 15 mensajes
│   └── mempal_precompact_hook.sh  # Guardado de emergencia antes de comprimir el contexto
├── benchmarks/               # Benchmarks reproducibles (LongMemEval / LoCoMo)
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

Paso a paso

Paso 1: Instalación

pip install mempalace

La versión mínima de Python es 3.9. Tras instalar, verifica que funcione:

mempalace --version

---

Paso 2: Inicializa el palacio de memoria

mempalace init ~/projects/myapp

El comando init inicia el flujo guiado, preguntando en orden:

• Las personas con las que colaboras con frecuencia (añádelas a la configuración wing)
• Los proyectos en los que estás trabajando (un wing por proyecto)
• Tu identidad de IA (se escribe en la capa L0)

Al terminar la guía, se generan dos archivos de configuración:

• ~/.mempalace/config.json — configuración global (ruta del palacio, etc.)
• ~/.mempalace/wing_config.json — mapeo entre wing y palabras clave

El wing_config.json generado se ve aproximadamente así:

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

Cada vez que arranca la IA, solo carga L0 + L1 (≈ 170 tokens) y ya sabe cómo es tu mundo.

---

Paso 3: Minería de datos

MemPalace admite dos modos de minería; elige según tu fuente de datos.

Modo A: Minar archivos del proyecto (código, documentos, notas)

mempalace mine ~/projects/myapp

El miner recorre el directorio de forma recursiva, segmenta por párrafos, guarda en ChromaDB y almacena el contenido original en Drawer.

Modo B: Minar exportaciones de conversaciones (Claude/ChatGPT/Slack)

# Uso básico
mempalace mine ~/chats/ --mode convos

# Indica el wing para filtrar luego por proyecto
mempalace mine ~/chats/ --mode convos --wing myapp

# Activa la clasificación automática (extrae decisiones, preferencias, hitos, problemas y contexto emocional)
mempalace mine ~/chats/ --mode convos --extract general

El convo_miner segmenta la conversación por Q+A, detecta automáticamente a qué room pertenece (coincidencias de 70+ modos mediante room_detector_local.py, sin API).

---

Paso 4: Verificación con búsqueda semántica

Cuando termines la minería, prueba a buscar:

mempalace search "why did we switch to GraphQL"

Añade filtro por wing para buscar solo en un proyecto específico:

mempalace search "auth decision" --wing driftwood

Si quieres afinar aún más, añade filtro por room:

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

Lo que devuelves es el texto original del Drawer (verbatim): sin resúmenes y sin pérdida de información. ChromaDB hace la búsqueda vectorial; Closet genera un resumen estructurado.

---

Paso 5: Conecta el servicio MCP

MCP (Model Context Protocol) permite exponer MemPalace como herramienta para cualquier IA. Una configuración, efecto permanente.

Conectar Claude Code:

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

Tras configurar, Claude Code obtiene automáticamente 19 herramientas. La IA llamará por su cuenta a mempalace_search cuando haga falta; no tienes que buscar manualmente.

Conectar Gemini CLI:

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

Gemini CLI tiene soporte MCP más completo y los save hooks también pueden configurarse automáticamente.

Listado de herramientas MCP (19):

A partir de la respuesta de mempalace_status, la IA aprende automáticamente la sintaxis AAAK y el protocolo de memoria; no necesitas configurar prompts manualmente.

---

Paso 6: Configura Claude Code Auto-Save Hooks

Los Hooks de Claude Code permiten que MemPalace guarde memoria automáticamente en cada conversación.

Modifica ~/.claude/settings.json (configuración global de Claude Code) y añade:

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

La diferencia entre ambos hooks:

• Stop: se activa cada 15 mensajes; guardado estructurado — registra tema, decisiones, citas y cambios de código, y además reconstruye la capa L1 (capa de hechos clave).
• PreCompact: se activa antes de comprimir el contexto. Activa un guardado de emergencia para rescatar memorias que aún no se hayan guardado, evitando perder contexto importante durante la compresión.

---

Paso 7: Comprender la estructura de Palace

La abstracción principal de MemPalace es el «palacio de memoria»: inspirándose en las técnicas mnemotécnicas de los oradores de la Grecia antigua, usa una estructura espacial en lugar de un índice de búsqueda plano.

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer   │  ← El original está aquí
    └──────────┘      └──────────┘

  TÚNEL (conexión entre wings):
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings: una persona o un proyecto; es la clasificación principal de la memoria. Debajo de cada wing puede haber varias rooms.

Rooms: temas concretos dentro del wing, por ejemplo auth-migration, ci-pipeline, pricing. Cuando una room con el mismo nombre aparece en wings distintos, se genera automáticamente un túnel.

Halls: pasillos de tipos de memoria. Cada wing tiene el mismo conjunto de halls:

• hall_facts — decisiones bloqueadas
• hall_events — sesiones, hitos y procesos de depuración
• hall_discoveries — avances y nuevas ideas
• hall_preferences — hábitos, preferencias y opiniones
• hall_advice — recomendaciones y soluciones

Closets: capa de resumen, apunta a la ubicación del contenido original (Drawer). El texto original no se pierde: solo se añade una capa con estructura navegable.

Drawers: donde se guarda el texto original. El modo raw verbatim de MemPalace lee el contenido original desde aquí para realizar búsqueda vectorial, logrando el 96.6% de R@5.

---

Paso 8: Relaciones temporales con el Knowledge Graph

ChromaDB guarda los vectores del texto original; el Knowledge Graph (SQLite) guarda tríos de hechos estructurados. Ambos se complementan.

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# Añade hechos, con ventana de validez
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")

# Consulta qué está haciendo Kai ahora
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# Consulta el estado el 2026-01-20 (Maya aún no había terminado auth-migration)
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# Mira la línea temporal del proyecto Orion
print(kg.timeline("Orion"))
# → cadena de hechos ordenada por tiempo

# Maya cambia de proyecto: invalida el hecho anterior
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# Ahora query_entity("Maya") ya no devuelve auth-migration

La ventana de vigencia de los Facts (valid_from / ended) es una capacidad esencial de MemPalace: al consultar estados históricos te dice «qué ocurrió entonces», no «qué ocurre ahora».

---

Paso 9: Arquitectura en cuatro capas de la pila de memoria

La estrategia de recuperación de MemPalace se organiza en cuatro capas: cuanto más arriba, más ligera; cuanto más abajo, más precisa.

Cada vez que arranca la IA, primero carga L0 + L1 (mempalace wake-up), con 170 tokens es suficiente para construir un contexto completo. Solo cuando el tema dispara una room específica se carga L2; y solo cuando haces una pregunta explícita se activa la búsqueda completa de ChromaDB de L3.

Esta es la razón por la que MemPalace es tan barato — el coste de búsqueda es de $10/año, frente a $507/año del enfoque de resúmenes.

---

Resolución de problemas frecuentes

P1: Los resultados de búsqueda están vacíos, pero estás seguro de que el contenido existe

Verifica en tres pasos:

# 1. Confirma que los nombres de wing y room son correctos
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. Amplía el alcance; busca sin especificar wing/room
mempalace search "palabra clave"   # Sin --wing

# 3. Comprueba si ChromaDB realmente se escribió
mempalace status            # Mira si el total de drawers es 0

Si mempalace status muestra 0 drawer, significa que el paso de minería no funcionó; puede ser porque el formato del archivo de conversación no se admite (por ahora se admiten Claude Code JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON y texto plano).

P2: Conflicto de nombre de colección en ChromaDB

El nombre de la colección por defecto es mempalace_drawers. Si haces init varias veces o ejecutas en distintos directorios, podrías encontrar conflictos. Especifica la ruta explícitamente en ~/.mempalace/config.json:

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

Luego sobrescribe con --palace <path>:

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

P3: Fallo de conexión con MCP

Primero valida manualmente que el servicio MCP se puede iniciar correctamente:

python -m mempalace.mcp_server
# En condiciones normales no debería imprimir nada; mantén la ejecución en primer plano
# Ctrl+C para salir

Si aparece ModuleNotFoundError, revisa si está instalado correctamente:

pip show mempalace

Si usas un entorno virtual, confirma que la configuración MCP de Claude Code indique la ruta Python correcta:

which python   # Obtén la ruta correcta de python
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

P4: La llamada a herramientas MCP funciona, pero el resultado no coincide con lo esperado

Cuando la IA llama a mempalace_search, los parámetros wing/room deben coincidir con precisión para que Palace muestre su máximo rendimiento. Guía a la IA en el prompt para que use filtros correctos:

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

P5: No se activó el hook del script

# Revisa si los hooks de Claude Code están habilitados
claude doctor

Verifica que en settings.json las rutas de hooks estén como rutas absolutas. Las rutas relativas pueden fallar porque Claude Code se ejecuta desde distintos directorios de trabajo.

P6: La consulta temporal del grafo de conocimiento devuelve resultados inesperados

Las consultas temporales dependen del formato del parámetro as_of: la fecha debe ser YYYY-MM-DD:

# Formato incorrecto
kg.query_entity("Kai", as_of="2026/03/01")

# Formato correcto
kg.query_entity("Kai", as_of="2026-03-01")

Además, confirma que al añadir hechos con add_triple, el parámetro valid_from también esté en el formato correcto; de lo contrario, la ventana temporal no se aplicará.

---

Lecturas ampliadas / Direcciones avanzadas

Capa experimental de compresión AAAK

AAAK es un dialecto abreviado con pérdida, que comprime entidades repetidas convirtiéndolas mediante sustituciones con expresiones regulares. En escenarios a gran escala (cuando un mismo proyecto se menciona cientos de veces) puede ahorrar costes de tokens. Sin embargo, en la actualidad el modo raw verbatim (96.6%) sigue siendo mejor que el modo AAAK (84.2%). Los casos ideales son proyectos largos, con múltiples conversaciones y con muchas entidades repetidas.

Aislamiento de memoria entre Specialist Agents (multi-agent)

Cada Agent tiene un wing independiente y un diario AAAK:

~/.mempalace/agents/
  ├── reviewer.json    # calidad del código, patrones, bugs
  ├── architect.json   # decisiones de arquitectura, compromisos
  └── ops.json         # despliegue, fallos, infraestructura

La IA descubre dinámicamente los agents durante la ejecución desde palace, sin necesidad de escribir ninguna configuración en CLAUDE.md.

Reproducción de benchmarks

En el directorio benchmarks/ encontrarás scripts completos para reproducir LongMemEval y LoCoMo:

python benchmarks/longmemeval_bench.py

En todo el proceso no se necesita API key. En un M2 Ultra, se completan las 500 preguntas en menos de 5 minutos, validando la reproducibilidad del 96.6%.

Comparación horizontal con otros sistemas

MemPalace es la única opción que alcanza la puntuación más alta sin llamadas a API.