Claude Engram

Memoria persistente e inteligencia de sesión para asistentes de programación con IA. Se integra en el ciclo de vida de Claude Code para rastrear automáticamente errores, decisiones y contexto, y luego analiza todo el historial de tu sesión para identificar patrones, predecir lo que necesitarás y buscar en todo lo que hayas discutido.

Cero esfuerzo manual. Funciona con cualquier cliente compatible con MCP.

Qué hace

Automático (hooks — cero invocación):

• Rastrea cada edición, error, resultado de prueba y evento de sesión

• Captura automáticamente decisiones de tus prompts ("usemos X", "cambiemos a Y")

• Inyecta las 3 memorias más relevantes antes de cada edición de archivo

• Advierte cuando estás a punto de repetir un error pasado

• Detecta bucles de edición (mismo archivo 3+ veces sin progreso)

• Sobrevive a la compactación de contexto: crea puntos de control antes y los reinyecta después

• Analiza el historial de tu sesión en segundo plano después de cada sesión

Análisis de sesión (automático, en segundo plano):

• Analiza los registros completos de conversación de Claude Code (JSONL) después de cada sesión, incluidas las conversaciones con subagentes (Explore, Plan, code-reviewer, etc.)

• Extrae decisiones, errores, enfoques y correcciones del usuario mediante análisis estructural + puntuación semántica AllMiniLM (tolerante a errores tipográficos)

• Construye un índice de búsqueda en todas las conversaciones pasadas (más de 20k fragmentos con subagentes)

• Detecta dificultades recurrentes, patrones de error y correlaciones de edición de archivos

• Predice qué archivos y contexto necesitarás antes de las ediciones

• Reflexiona sobre los patrones usando un LLM local para sintetizar causas raíz y conocimientos arquitectónicos

• En la primera instalación, analiza retroactivamente todo el historial de tu sesión

Bajo demanda (herramientas MCP):

• memory: almacenar, buscar, archivar y gestionar memorias

• session_mine: buscar conversaciones pasadas, encontrar decisiones, reproducir el historial de archivos, detectar patrones

• work: registrar decisiones y errores con razonamiento

• Además: protección de alcance, puntos de control de contexto, seguimiento de convenciones, análisis de impacto

Related MCP server: Doclea MCP

Cómo funciona

Claude Code
 |
 +-- Hooks (remind.py) <- Intercepts every tool call
 | SessionStart / Edit / Bash / Error / Compact / Stop
 |
 +-- Session Mining (mining/) <- Background intelligence
 | JSONL parser -> Extractors -> Search index -> Pattern detection
 |
 +-- MCP Server (server.py) <- Tools for manual operations
 | memory, session_mine, work, scope, context, ...
 |
 +-- Scorer Server (scorer_server.py) <- Persistent AllMiniLM process
 TCP localhost, ~90MB RAM, batch embeddings

Los hooks se activan en cada llamada a herramienta (presupuesto de 1-2s cada uno). El procesamiento pesado ocurre en un subproceso en segundo plano después de finalizar la sesión. El servidor de puntuación permanece cargado en memoria para una puntuación semántica rápida.

Benchmarks

Benchmarks de integración

Estos prueban lo que el producto hace realmente.

Reproducir: python tests/bench_integration.py, bench_session_mining.py, bench_obsidian_vault.py

Benchmarks de recuperación

Solo recuperación (recall@k): si la memoria correcta se encuentra en los mejores resultados.

Reproducir: python tests/bench_longmemeval.py, bench_locomo.py, bench_convomem.py

Compatibilidad

Instalación

git clone https://github.com/20alexl/claude-engram.git
cd claude-engram
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows

pip install -e . # Core
pip install -e ".[semantic]" # + AllMiniLM for vector search and semantic scoring

python install.py # Configure hooks, MCP server, and /engram skill

Configuración por proyecto

python install.py --setup /path/to/your/project

O copia .mcp.json a la raíz de tu proyecto.

Nota: El archivo CLAUDE.md en este repositorio es documentación específica de engram; no es necesario para que engram funcione. Los hooks se activan automáticamente y la habilidad /engram proporciona una referencia rápida bajo demanda. Si ya tienes un CLAUDE.md para tu proyecto, mantenlo tal cual y no copies el nuestro encima. Si deseas tener la documentación de engram junto a las reglas de tu proyecto, cámbiale el nombre a CLAUDE-ENGRAM.md (o similar) para que no sobrescriba tu archivo existente; Claude lo verá cuando sea relevante.

Actualización

cd claude-engram
git pull
pip install -e ".[semantic]" # Reinstall if dependencies changed
python install.py # Re-run to update hooks and /engram skill

Los hooks y las herramientas MCP recogen los cambios de código inmediatamente (instalación editable). Reconecta el servidor MCP en Claude Code (/mcp) para recargar el proceso del servidor.

Adopción a mitad de proyecto

¿Ya estás inmerso en un proyecto? Instálalo normalmente. En la primera sesión, engram detecta automáticamente el historial de sesiones de Claude Code existente y lo analiza en segundo plano, extrayendo decisiones, errores y patrones de todas las conversaciones pasadas. Sin esfuerzo manual.

Características clave

Sistema de memoria

• Búsqueda híbrida: palabra clave + vector AllMiniLM + reranking. Sin ChromaDB.

• Inyección puntuada: las 3 mejores memorias por coincidencia de archivo, etiquetas, recencia e importancia antes de cada edición.

• Almacenamiento por niveles: activo (rápido) + archivo (frío, buscable, restaurable). Las reglas y los errores nunca se archivan.

• Multiproyecto: memorias con alcance por subproyecto. Las reglas del espacio de trabajo se propagan hacia abajo.

Análisis de sesión

• Extracción estructural: analiza el flujo de la conversación (confirmaciones, redirecciones, secuencias de error->corrección, cambios de enfoque) en lugar de coincidencia de plantillas.

• Indexación de contenido de herramientas: los comandos bash + salida, diferencias de edición y seguimientos de errores son buscables junto con el texto de la conversación.

• Embeddings por lotes: 22 veces más rápido que las llamadas individuales mediante protocolo TCP por lotes.

• Búsqueda entre sesiones: más de 44k fragmentos de conversación indexados, búsqueda semántica + palabra clave + híbrida.

• Detección de patrones: dificultades recurrentes, patrones de error, correlaciones de edición entre sesiones.

• Contexto predictivo: antes de las ediciones, muestra archivos relacionados y posibles errores del historial.

• Aprendizaje entre proyectos: agrega patrones en todos tus proyectos.

• Bootstrap retroactivo: analiza todo el historial de sesiones existente en la primera instalación.

• Inicio automático del puntuador: el servidor AllMiniLM se inicia bajo demanda si no se está ejecutando. Sin degradación silenciosa.

Ciclo de vida

• Captura automática de decisiones: patrones estructurales (confirmaciones, redirecciones, elecciones explícitas) + puntuación semántica como bono.

• Rastreo automático de errores de cualquier herramienta fallida. Solo registra errores en archivos del proyecto (filtra ruido transitorio). Advierte antes de ediciones repetidas.

• Sobrevive a la compactación: puntos de control con decisiones/errores de sesión, reinyecta después.

• Detección de bucles de edición: marca cuando el mismo archivo se edita 3+ veces sin progreso.

Configuración

Reindexación

Si la calidad de la búsqueda es deficiente o deseas reconstruir después de una actualización:

python scripts/reindex.py "E:\workspace" --force # rebuild search index
python scripts/reindex.py "E:\workspace" --force --extract # also re-extract decisions/mistakes

O mediante MCP: session_mine(operation="reindex", mode="bootstrap")

Documentación

Libro de la biblioteca: filosofía de diseño, aspectos internos, guía de uso completa, referencia de API, advertencias y registro de cambios.

/engram: comando de barra diagonal con referencia rápida de herramientas (instalado por install.py).

Licencia

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• audit_batchC
• claude_engram_statusB
• code_pattern_checkC
• code_quality_checkC
• contextA
• conventionB
• deps_mapC
• file_summarizeC