anneal-memory

Memoria viva para agentes de IA. Los episodios se comprimen en identidad.

El único servidor de memoria MCP con sistema inmunológico. Los patrones ganan permanencia a través de evidencia, el conocimiento falso es detectado y degradado, y la información obsoleta se desvanece; así, la memoria de tu agente se vuelve más inteligente con el tiempo, no solo más grande.

Cuatro capas cognitivas: almacenamiento episódico, continuidad comprimida, asociaciones hebbianas y seguimiento del estado afectivo. Cero dependencias. 5 herramientas. Funciona con cualquier cliente MCP.

Inicio rápido

1. Ejecuta el servidor (no requiere instalación):

{
  "mcpServers": {
    "anneal-memory": {
      "command": "uvx",
      "args": ["anneal-memory", "--project-name", "MyProject"]
    }
  }
}

Añade esto a .mcp.json en la raíz de tu proyecto (Claude Code) o en la configuración MCP de tu editor.

La base de datos se guarda por defecto en ~/.anneal-memory/memory.db (creada automáticamente). Puedes sobrescribirla con --db /ruta/a/memory.db para almacenamiento por proyecto.

Alternativa: pip install anneal-memory si prefieres una instalación fija, luego usa "command": "anneal-memory" directamente.

2. Añade el fragmento de orquestación al archivo CLAUDE.md de tu proyecto:

Copia el contenido de examples/CLAUDE.md.example en el CLAUDE.md de tu proyecto. Esto enseña al agente cuándo y cómo usar las herramientas de memoria durante una sesión: registrando episodios durante el trabajo, verificando el contexto previo antes de tomar decisiones y ejecutando la secuencia completa de compresión al finalizar la sesión.

Sin este fragmento, las herramientas están disponibles pero el agente no conocerá el flujo de trabajo. Este es el paso de configuración más importante.

3. Reinicia tu editor. Eso es todo. El agente ahora registra, recuerda y comprime la memoria entre sesiones.

Por qué existe esto

Todos los servidores de memoria MCP que probamos tienen el mismo problema: la memoria crece para siempre y nada valida lo que sabe.

El servidor oficial de Anthropic almacena todo en un archivo JSONL que crece sin poda. Mem0 requiere Docker y la nube para sus mejores funciones. Otros exponen 15-33 herramientas que consumen tu ventana de contexto. Y ninguno de ellos puede decirte si lo que "recuerdan" sigue siendo cierto.

anneal-memory adopta un enfoque diferente: la memoria como un sistema vivo, no como un archivador.

• Los episodios se acumulan rápidamente (SQLite de solo adición, clasificados por tipo)

• En los límites de la sesión, el agente comprime los episodios en un archivo de continuidad, y el paso de compresión ES el pensamiento, donde emergen los patrones

• Los patrones validados se fortalecen. Los patrones obsoletos se desvanecen. Los patrones falsos son detectados.

• Los episodios que se citan juntos forman asociaciones laterales: una red cognitiva que se desarrolla mediante el uso

• El archivo de continuidad se mantiene acotado y siempre cargado, sin crecer linealmente

Qué lo hace diferente

El sistema inmunológico (nadie más tiene esto)

Graduación validada por citas. Los patrones comienzan en 1x. Para graduarse a 2x o 3x, deben citar IDs de episodios específicos como evidencia. El servidor verifica que esos IDs existan y que la explicación se conecte con el episodio citado. Sin evidencia, no hay promoción.

Defensa contra la endogamia. La verificación de superposición de explicaciones evita que el agente confirme sus propios patrones alucinados: el episodio citado debe contener contenido significativamente diferente de la propia afirmación de graduación.

Degradación de principios. El conocimiento graduado que deja de ser reforzado por nuevos episodios se marca como obsoleto y puede ser degradado. La memoria olvida activamente lo que ya no es relevante.

Asociaciones mediante consolidación (no recuperación)

Durante la compresión, cuando un agente cita múltiples episodios para respaldar un patrón, esos episodios forman asociaciones laterales: enlaces de estilo hebbiano que se fortalecen mediante la co-citación repetida a través de los cierres de sesión.

Esto es fundamentalmente diferente de cómo otros sistemas forman asociaciones:

La red de asociaciones hereda la integridad del sistema inmunológico: solo las citas validadas forman enlaces. Las citas degradadas no. Toda la topología cognitiva se construye sobre evidencia, no sobre frecuencia.

Modelo de fuerza: La co-citación directa añade 1.0, la co-citación de sesión añade 0.3. Los enlaces decaen 0.9x por cierre (las conexiones no utilizadas se desvanecen). La fuerza tiene un tope de 10.0 para evitar la calcificación. Limpieza en el umbral de 0.1.

Seguimiento del estado afectivo

Durante la compresión, el agente puede autoinformar su estado funcional: qué encontró interesante, incierto o sorprendente sobre el material que acaba de procesar. Esto se registra en las asociaciones formadas durante ese cierre.

Los Transformers no mantienen de forma nativa un estado persistente entre sesiones. Esta capa proporciona la infraestructura para ello: un registro de cómo fue el procesamiento del agente, no solo qué procesó. Con el tiempo, la topología afectiva puede divergir de la topología semántica: un agente podría conocer dos cosas igual de bien pero preocuparse por ellas de manera diferente.

Pasa el estado afectivo durante un cierre:

# Via MCP tool
save_continuity(text="...", affective_state={"tag": "curious", "intensity": 0.8})

# Via Engine (automated characterization)
engine = Engine(store, api_key="...", characterize_affect=True)
result = engine.wrap()  # LLM self-reports affect post-compression

Esta es una infraestructura experimental. Las asociaciones y el modelo de fuerza funcionan sin ella. El etiquetado afectivo añade una capa de señal para agentes e investigadores que exploran el estado persistente.

Arquitectura

  Episodes (fast)              Continuity (compressed)
  ┌─────────────┐             ┌──────────────────────┐
  │ observation  │             │ ## State             │
  │ decision     │── wrap ───→│ ## Patterns (1x→3x)  │
  │ tension      │  compress  │ ## Decisions          │
  │ question     │             │ ## Context            │
  │ outcome      │             └──────────────────────┘
  │ context      │               always loaded, bounded
  └─────────────┘               human-readable markdown
   SQLite, indexed
         │                     Associations (lateral)
         │                    ┌──────────────────────┐
         └── co-citation ───→│ episode ↔ episode     │
              during wrap     │ strength + decay      │
                              │ affective state       │
                              └──────────────────────┘
                               Hebbian, evidence-based

Cuatro capas cognitivas, modeladas según cómo funciona realmente la memoria:

1. Almacenamiento episódico (SQLite): episodios con marca de tiempo y tipo. Escrituras rápidas, consultas indexadas. Barato de acumular. El hipocampo.

2. Archivo de continuidad (Markdown): memoria de sesión comprimida. 4 secciones. Siempre cargado al inicio de la sesión. Reescrito (no añadido) en cada límite de sesión. El neocórtex.

3. Asociaciones hebbianas (SQLite): enlaces laterales entre episodios, formados mediante co-citación durante la compresión. Se fortalecen con el uso, decaen sin él. La corteza de asociación.

4. Capa afectiva (en las asociaciones): etiquetas de estado funcional registradas durante la compresión. La intensidad modula la fuerza de la asociación. Infraestructura de estado persistente.

Seis tipos de episodios dan al sistema inmunológico una señal más rica:

Comparación

Higiene de sesión

Los cierres de sesión son lo más importante que hace tu agente con este sistema. Piénsalos como dormir.

La neurociencia lo llama consolidación de la memoria: durante el sueño de ondas lentas, el hipocampo reproduce las experiencias del día mientras el neocórtex las integra en el conocimiento a largo plazo. Si te saltas el sueño, los recuerdos se degradan: las experiencias se acumulan sin ser procesadas, los patrones no se reconocen y el conocimiento antiguo no se refuerza ni se poda.

anneal-memory funciona de la misma manera. Durante una sesión, los episodios se acumulan en el almacenamiento episódico. Al final de la sesión, el cierre comprime esos episodios en el archivo de continuidad. Aquí es donde ocurre el pensamiento real: el agente reconoce patrones, promueve el conocimiento validado, deja que la información obsoleta se desvanezca y forma asociaciones entre episodios relacionados. Sin cierres, solo tienes una pila creciente de episodios crudos y ninguna inteligencia.

La secuencia de cierre:

1. prepare_wrap: reúne episodios recientes, continuidad actual, advertencias de patrones obsoletos, contexto de asociación e instrucciones de compresión

2. El agente comprime: esto ES la cognición. Durante la compresión emergen patrones que no eran visibles en los episodios crudos

3. save_continuity: el servidor valida la estructura, verifica la evidencia de las citas, registra asociaciones entre episodios co-citados, aplica decaimiento a las asociaciones no utilizadas y guarda el resultado

Reglas generales:

• Cierra siempre antes de terminar una sesión. Una sesión sin cerrar es como una noche sin dormir: las experiencias ocurrieron pero no se consolidaron

• El fragmento de CLAUDE.md maneja esto automáticamente: enseña al agente a detectar señales de fin de sesión ("vamos a terminar", "hemos terminado") y ejecutar la secuencia completa

• Las sesiones cortas (3-5 episodios) también se benefician de los cierres. Incluso una pequeña cantidad de compresión construye el archivo de continuidad

• Si prepare_wrap dice "no hay episodios", no hay nada que comprimir. Está bien, sáltalo

El sistema de graduación y la red de asociaciones dependen de los cierres para funcionar. Los patrones solo pueden promoverse (1x -> 2x -> 3x) durante la compresión, las citas solo pueden validarse durante los cierres, las asociaciones solo se forman mediante co-citación durante los cierres y los patrones obsoletos solo pueden detectarse cuando el agente revisa lo que sabe frente a lo que experimentó recientemente. Sin cierres = sin sistema inmunológico, sin asociaciones, sin desarrollo cognitivo.

Cumplimiento y auditoría

El almacenamiento episódico es una pista de auditoría natural. Cada decisión, tensión y resultado tiene marca de tiempo, tipo y es de solo adición: exactamente lo que los reguladores quieren ver cuando preguntan "¿por qué hizo eso la IA?"

Pista de auditoría JSONL encadenada por hash (incluida, activada por defecto):

Cada operación de memoria (episodio registrado, episodio eliminado, cierre iniciado, cierre completado, asociaciones actualizadas) se registra en un archivo JSONL de solo adición donde el hash SHA-256 de cada entrada incluye el hash de la entrada anterior. Modifica o elimina una entrada y la cadena se rompe. Verifica la integridad mediante programación o con jq.

• Identidad del actor en cada entrada (quién hizo esto: agente, sistema, administrador)

• Modo solo hash de contenido por defecto: la pista de auditoría demuestra qué sucedió sin almacenar el contenido en sí (compatible con GDPR: elimina el episodio, la cadena de auditoría sigue verificando)

• Rotación semanal con gzip: los archivos de auditoría antiguos se comprimen automáticamente, el índice de manifiesto permite la verificación de la cadena entre archivos

• Callback on_event: envía eventos de auditoría a tus propios sistemas (registro en la nube, SIEM, observabilidad)

• Recuperación de fallos: entradas incompletas detectadas y manejadas al reiniciar

from anneal_memory import Store

# Audit trail is on by default
store = Store("./memory.db", project_name="MyAgent")

# Verify chain integrity
from anneal_memory import AuditTrail
result = AuditTrail.verify("./memory.db")
print(f"Valid: {result.valid}, Entries: {result.total_entries}")

# Stream events to external system
store = Store("./memory.db", on_audit_event=lambda entry: send_to_siem(entry))

Relevancia de la Ley de IA de la UE: El Artículo 12 de la Ley requiere el "registro automático de eventos" para sistemas de IA de alto riesgo, con disposiciones para la trazabilidad, la identificación del actor y la evidencia de manipulación. La infraestructura de auditoría de anneal-memory cubre los Artículos 12(2)(b,c) desde el primer momento. Esta es una infraestructura de auditoría que ayuda a los sistemas a cumplir, no una certificación de cumplimiento.

Qué sigue:

• Proxy de cumplimiento (Capa 2): interceptación de la capa de transporte MCP que captura todas las acciones del agente (cada llamada a herramienta, cada respuesta), no solo las operaciones de memoria. Mismo almacenamiento, el campo source distingue el registro intencional de la captura automática. Auditoría de memoria = "esto es lo que aprendió el agente". Proxy de cumplimiento = "esto es todo lo que sucedió".

• Memoria compartida multi-agente: pool episódico compartido con continuidad por agente y topología de asociación por agente. Pista de auditoría completa entre agentes.

Herramientas MCP

Recurso: anneal://continuity: el archivo de continuidad actual, cargado automáticamente al inicio de la sesión.

Marcadores de continuidad

El archivo de continuidad utiliza un conjunto de marcadores simplificado para la densidad:

? question needing resolution
thought: insight worth preserving
✓ completed item

A -> B                          causation
A ><[axis] B                    tension on an axis

[decided(rationale, on)]        committed decision
[blocked(reason, since)]        external dependency

| 1x (2026-04-01)              first observation
| 2x (2026-04-01) [evidence: abc123 "explanation"]   validated pattern

API de Python

from anneal_memory import Store, EpisodeType

with Store("./memory.db", project_name="MyAgent") as store:
    store.record("User prefers PostgreSQL for ACID", EpisodeType.OBSERVATION)
    store.record("Chose pooling over caching", EpisodeType.DECISION)

    result = store.recall(episode_type=EpisodeType.DECISION, keyword="pooling")

    episodes = store.episodes_since_wrap()
    from anneal_memory import prepare_wrap_package
    package = prepare_wrap_package(episodes, store.load_continuity(), "MyAgent")
    # -> episodes, continuity, stale_patterns, instructions, today

    # Associations
    stats = store.association_stats()
    print(f"Links: {stats.total_links}, Avg strength: {stats.avg_strength}")

    assocs = store.get_associations(episode_ids=["abc123"], min_strength=0.5)
    for a in assocs:
        print(f"{a.id_a} <-> {a.id_b} strength={a.strength}")

Motor (Compresión automatizada)

Para pipelines, trabajos cron o uso programático sin un agente interactivo:

pip install anneal-memory[engine]

from anneal_memory import Engine, Store

with Store("./memory.db", project_name="MyAgent") as store:
    store.record("Observed pattern in data", "observation")
    store.record("Chose approach X over Y", "decision")

    engine = Engine(store, api_key="sk-ant-...")  # or llm=my_callable
    result = engine.wrap()

    print(f"Compressed {result.episodes_compressed} episodes")
    print(f"Continuity: {result.chars} chars, {result.patterns_extracted} patterns")
    print(f"Associations: {result.associations_formed} formed, {result.associations_strengthened} strengthened")

El motor reúne episodios, construye el prompt de compresión, llama al LLM, valida la estructura y las citas, registra asociaciones entre episodios co-citados, aplica decaimiento, trunca si supera el presupuesto y