Engram

Cada pensamiento deja una huella.

Dale a tu Agente de IA un cerebro que sabe olvidar.

Engram es un servicio de memoria MCP que se ejecuta completamente de forma local. No se trata solo de "almacenar y recuperar"; simula los mecanismos humanos de olvido, refuerzo y asociación, permitiendo que el Agente recuerde lo que realmente importa a través de las sesiones y olvide naturalmente los detalles innecesarios.

Sin dependencia de la nube, tus datos siempre están en tu máquina.

¿Qué problemas resuelve?

Problema 1: Ruptura del estado entre sesiones

Cada conversación con un Agente de IA es una hoja en blanco. Las preferencias que le contaste ayer, las decisiones arquitectónicas tomadas la semana pasada, los errores que cometiste el mes pasado... todo se borra en la siguiente conversación. Limpiar la ventana de contexto es como formatear el cerebro.

Problema 2: Entropía de archivos

Meter todo el contexto en CLAUDE.md o .cursorrules parece resolver el problema, pero en realidad crea uno nuevo: los archivos se vuelven interminables, la información obsoleta se mezcla con la nueva y el costo de mantenimiento manual aumenta constantemente. No estás gestionando la memoria, estás manteniendo un documento cada vez más difícil de leer.

Problema 3: Pérdida del estado de ingeniería

Qué hizo el Agente, dónde se quedó atascado, qué debe hacer a continuación... no hay lugar donde guardar estos estados de ingeniería estructurados. Cada nueva sesión requiere 10 minutos de "re-alineación" antes de poder hacer el trabajo real.

La solución de Engram: No es "guardar todo", sino simular el mecanismo humano de olvido-refuerzo-asociación:

• Las preferencias y decisiones importantes tienen una degradación muy lenta, conservándose casi permanentemente.

• El contexto temporal de depuración se desvanece naturalmente en 11 días.

• El conocimiento que se recuerda repetidamente se vuelve más sólido con cada uso.

• La información contradictoria se sobrescribe automáticamente, evitando conflictos internos.

• Nuevo en v0.2: Traspaso de sesión estructurado (session handoff), permitiendo que la siguiente sesión continúe desde el punto de interrupción en lugar de empezar de cero.

• Nuevo en v0.4: Centro de estado de ingeniería — atribución de fallos estructurada (track_failure) y seguimiento de progreso (track_progress), para que el Agente no solo recuerde información, sino también el estado del proyecto.

Related MCP server: Ori Mnemos

Mecanismos principales

1. Curva del olvido de Ebbinghaus

Cada memoria tiene un valor de fuerza (strength) que decae siguiendo una curva exponencial con el tiempo:

effective_λ = base_λ × (1 - importance × 0.8)
strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)

Tres factores determinan cuánto tiempo sobrevive una memoria:

Cuatro categorías de memoria:

Intención del diseño: Las estrategias exitosas se recuerdan por más tiempo (strategy ~38 días), mientras que las lecciones de los fallos se recuerdan por menos tiempo (failure ~11 días), ya que el entorno cambia y los problemas de ayer pueden estar resueltos mañana.

2. Deduplicación inteligente y resolución de contradicciones

Al almacenar una nueva memoria, el sistema no solo la añade, sino que primero realiza una comparación semántica con las memorias existentes:

相似度 ≥ 0.85 → REINFORCE  只增加回忆次数，不重复存储
相似度 0.65~0.84 → 检测矛盾
  ├── 语义矛盾 → REPLACE   用新内容覆盖旧内容
  └── 语义兼容 → MERGE     合并为一条更完整的记忆
相似度 < 0.65 → NEW        存为新记忆

La detección de contradicciones se logra mediante análisis de polaridad: extrayendo palabras positivas (prefer/love/adopt) y negativas (avoid/hate/reject), junto con negaciones (not/don't/never), para determinar si dos memorias expresan posturas opuestas.

Ejemplo: Si ya existe "El usuario prefiere TypeScript" y se intenta guardar "El usuario decide abandonar TypeScript por Go", el sistema identifica la contradicción y reemplaza automáticamente la memoria antigua por la nueva.

3. Recuperación híbrida (Vector + BM25 + Grafo)

Al recuperar memorias, se utiliza una puntuación híbrida de tres vías:

最终得分 = 0.4 × BM25关键词得分 + 0.6 × (语义相似度 × 衰减强度) + 图谱加成

¿Por qué no usar solo búsqueda vectorial?

Resultado de la fusión: Al buscar "rendimiento de base de datos", no solo se encuentran memorias que mencionan explícitamente el rendimiento, sino que a través del grafo se encuentran estrategias de indexación o decisiones de caché relacionadas.

4. Grafo semántico

Cada memoria establece automáticamente asociaciones semánticas con las existentes al ser almacenada:

• Calcula la similitud de coseno con todas las memorias existentes.

• Si la similitud ≥ 0.40, se crea una arista bidireccional con peso = similitud × 0.5.

• Cada memoria se conecta como máximo a sus 5 vecinos más similares.

Dos funciones clave del grafo:

Descubrimiento asociativo: Al recuperar, se realiza un BFS (profundidad máxima 2) desde la memoria encontrada para hallar memorias asociadas, incluso si no tienen similitud semántica directa con el término de búsqueda. Es como la asociación humana de "ir de un tema a otro".

Protección en cadena: Cuando una memoria cae por debajo del umbral de degradación, si sus vecinos siguen siendo memorias fuertes, se conserva, ya que podría ser el puente que conecta dos puntos de conocimiento importantes.

5. Consolidación y eliminación automática

El sistema ejecuta una tarea de mantenimiento cada 12 horas:

Consolidación (Consolidation):

1. Identifica clústeres de memoria con similitud ≥ 0.70.

2. Conserva la memoria con mayor importancia como memoria principal.

3. Fusiona la información única de las demás memorias.

4. Recalcula los vectores y las relaciones del grafo.

5. Elimina las memorias redundantes fusionadas.

Eliminación (Pruning):

1. Calcula la fuerza actual de cada memoria.

2. Si la fuerza < 0.05 y pasa la comprobación de seguridad en cadena → Eliminar.

3. Si la fuerza < 0.05 pero sus vecinos siguen siendo fuertes → Conservar (protección en cadena).

Esto significa que la base de memoria se mantiene concisa automáticamente, sin necesidad de limpieza manual ni crecimiento infinito.

Centro de estado de ingeniería (v0.4)

Engram no es solo un plugin de memoria para "guardar información", es una capa de estado que entiende los procesos de ingeniería.

Atribución de fallos (track_failure)

Cuando el Agente encuentra un error, fallo en pruebas o problema de despliegue, se registra en un formato estructurado:

# MCP 调用
track_failure(
    error="CSRF token missing on checkout",
    component="payment",
    severity="critical",        # → importance=0.9
    root_cause="middleware not loaded after refactor",
    fix="re-add CsrfMiddleware to pipeline",
    related_test_ids=["test_checkout_01", "test_payment_csrf"]
)

Decisiones de diseño:

• severity se mapea automáticamente a importance (critical=0.9, major=0.7, minor=0.5).

• Se utiliza la categoría failure (degradación más rápida λ=0.35, vida media ~11 días) — el entorno cambia, los registros de fallos antiguos caducan naturalmente.

• El campo component permite estadísticas agregadas por módulo para localizar rápidamente áreas de alto riesgo.

Seguimiento de progreso (track_progress)

Seguimiento del estado de funciones/tareas entre sesiones:

track_progress(
    feature="login-flow-refactor",
    status="in_progress",       # → importance=0.8
    completion=60,
    blockers=["waiting for API design review"],
    quality_score=0.85,
    notes="auth module done, UI pending"
)

Decisiones de diseño:

• status se mapea automáticamente a importance (blocked=0.9 máximo, done=0.5 mínimo).

• Se utiliza la categoría strategy (degradación más lenta λ=0.10, vida media ~38 días) — el estado de progreso debe recordarse por más tiempo.

• Las funciones completadas desaparecen naturalmente por degradación, sin necesidad de limpieza manual.

Métricas de ingeniería (mejora de memory_stats)

memory_stats ahora agrega automáticamente datos de ingeniería:

{
  "total": 42,
  "categories": {"fact": 20, "failure": 8, "strategy": 14},
  "engineering": {
    "failures": {
      "total": 8,
      "by_component": {"auth": 5, "payment": 3},
      "by_severity": {"critical": 2, "major": 6}
    },
    "features": {
      "total_tracked": 4,
      "active": {
        "login-refactor": {"status": "in_progress", "completion": 60},
        "payment-fix": {"status": "blocked", "completion": 30}
      }
    }
  }
}

Arquitectura técnica

┌──────────────────────────────────────────────┐
│              MCP Client                      │
│      (Claude Code / Cursor / ...)            │
└──────────────────┬───────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼───────────────────────────┐
│              server.py                       │
│  8 MCP tools  ·  APScheduler (12h 维护)      │
├──────────────────────────────────────────────┤
│                                              │
│  ┌─ 写入路径 ──────┐  ┌─ 读取路径 ──────┐    │
│  │  resolve.py     │  │  retrieve.py    │    │
│  │  去重/矛盾消解   │  │  混合检索+评分   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
│  ┌─ 维护路径 ──────┐  ┌─ 统计路径 ──────┐    │
│  │  consolidator   │  │  decay.py       │    │
│  │  聚类合并+剪枝   │  │  遗忘曲线+强度   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
├──────────────────────────────────────────────┤
│  embedding.py          │  graph.py           │
│  768d / 1024d 向量编码  │  NetworkX 语义图谱  │
├──────────────────────────────────────────────┤
│              db.py — DuckDB                  │
│  向量存储  ·  BM25 全文索引  ·  CRUD          │
└──────────────────────────────────────────────┘

数据文件（~/.engram/）：
├── memories.duckdb     # 向量数据库（单文件，零运维）
├── graph.json          # 语义图谱（JSON 序列化）
└── model_cache/        # 嵌入模型缓存

Interfaz de herramientas MCP

Referencia de importancia

Beneficios para el usuario

1. El Agente realmente te "conoce"

Ya no tienes que presentar tu stack tecnológico, hábitos de codificación y contexto del proyecto en cada conversación. El Agente recuerda que prefieres Go sobre Java, sabe que el proyecto usa un monorepo y conoce las decisiones arquitectónicas que tomaste la semana pasada.

2. El conocimiento evoluciona naturalmente

La resolución de contradicciones significa que el conocimiento del Agente siempre está actualizado. ¿Cambiaste de React a Vue? Una conversación lo actualiza automáticamente. No necesitas mantener manualmente una lista de "lo que el Agente debería saber".

3. Cero mantenimiento

• No necesitas limpiar memorias antiguas manualmente: la curva de olvido las elimina.

• No necesitas fusionar duplicados manualmente: el consolidador lo hace.

• No te preocupes por la expansión de datos: mantenimiento automático cada 12 horas.

• No necesitas servicios externos: DuckDB en un solo archivo, listo para usar.

4. Privacidad total

Todos los datos se guardan en ~/.engram/, sin conexión a internet, sin subidas, sin depender de servicios en la nube. El modelo de embedding también se ejecuta localmente. Tus recuerdos son tuyos.

5. Descubrimiento asociativo

La expansión del grafo permite que el Agente no solo "busque y devuelva", sino que pueda encontrar conocimientos relacionados pero no coincidentes directamente. Es como preguntarle a un colega veterano: no solo responde, sino que añade: "Por cierto, esto está relacionado con aquello de la otra vez".

6. Más inteligente con el uso

Refuerzo de memoria: las memorias recuperadas repetidamente aumentan su fuerza y disminuyen su tasa de degradación. El Agente aprende automáticamente qué conocimiento es más valioso para ti.

Inicio rápido

# 安装
pip install mcp-engram

# 初始化（下载模型、创建数据库）
engram-setup

# 按照输出提示将配置块添加到 Claude Code 配置中

Configuración de Claude Code

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      }
    }
  }
}

Integración con CLAUDE.md

Añade esto a tu CLAUDE.md:

## Memory Rules

### Step 1 — 先回忆再行动
每次任务开始时，用请求中的关键词调用 `recall_memory`。

### Step 2 — 学到新东西就存
| 情况 | 操作 |
|------|------|
| 全新知识 | `store_memory(content, importance)` |
| 补充已有 | `update_memory(memory_id, merged_content)` |
| 推翻已有 | `update_memory(memory_id, new_content)` |

Variables de entorno

Consulta rápida de umbrales clave

Evaluación de referencia LoCoMo

Evaluación de calidad de recuperación basada en LoCoMo (referencia de memoria de conversación a largo plazo de Snap Research). LoCoMo es el estándar de evaluación utilizado por productos como Mem0/Zep/Memobase/MemMachine.

Configuración de evaluación

• Dataset: locomo10.json (2/10 conversaciones, 233 QA, excluyendo adversarial)

• Recuperación: recall() top-k=5

• LLM: DeepSeek-V3.2 / GLM-5.1 (Nota: los productos base usan GPT-4o-mini)

• Métricas: Token-level F1 (métrica oficial de LoCoMo) + Hit@5 (tasa de acierto de recuperación independiente del LLM)

Turn Mode — Mejor configuración (bge-m3 + bge-reranker-v2-m3, DeepSeek-V3.2)

Recuperación en dos etapas: recall top-50 → CrossEncoder rerank to top-5, corrección de peso importance=1.0

Turn Mode — Ruta de optimización (DeepSeek-V3.2)

Cuatro rondas de optimización acumulan F1 +50.3% (0.29 → 0.44), Hit@5 +26.2pp (51.5% → 77.7%).

Turn Mode — Comparativa de LLM (all-mpnet-base-v2)

Observation Mode (hechos abstractos asertivos)

Comparativa con la industria

Conclusión: Cuatro rondas de optimización mpnet(0.29) → bge-m3(0.35) → +reranker(0.39) → +weight fix+r50(0.44). Hit@5: 51.5% → 77.7%. La brecha con Mem0(0.67) se redujo del 56% al 35%.

Consulta rápida de mejor configuración

Configuración recomendada: bge-m3 (1024d) + bge-reranker-v2-m3 recuperación en dos etapas

Métrica	Valor	Descripción
F1 General	0.4383	Token-level, DeepSeek-V3.2
Hit@5 General	77.7%	Tasa de acierto de recuperación pura, independiente del LLM
Hit@5 Temporal	95.2%	Rendimiento destacado en preguntas temporales
Magnitud de optimización	F1 +50.3%, Hit +26.2pp	Acumulado en 4 rondas (respecto al mpnet inicial)

Parámetros clave: recall top-50 → rerank to top-5, importance=1.0 corrección de peso. Despliegue local sin dependencia de la nube, brecha con Mem0 (usando GPT-4o-mini) reducida al 35%.

Desarrollo

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v

Licencia

MIT