agentmem

agentmem

Memoria compartida para Claude Code, Cursor y Codex que sabe lo que sigue siendo cierto. Guarda sesiones, detecta reglas obsoletas y conflictivas, y evita que tu agente repita errores antiguos.

El Problema

Tu asistente de codificación con IA olvida todo entre sesiones. Repite errores antiguos. No puede distinguir reglas actuales de las obsoletas. El contexto se comprime y la recuperación es dolorosa.

La mayoría de las herramientas de memoria resuelven el almacenamiento. agentmem resuelve la confianza.

Comenzar (Claude Code / Cursor / Codex)

pip install quilmem[mcp]
agentmem init --tool claude --project myapp

Eso es todo. Reinicia tu editor. Tu agente ahora tiene 13 herramientas de memoria. Ejecuta memory_health para confirmar.

¿Solo Python? pip install quilmem funciona sin la extensión MCP. Consulta la API de Python a continuación.

Demostración de 60 Segundos

from agentmem import Memory

mem = Memory()

# Store typed memories
mem.add(type="bug", title="loudnorm undoes SFX levels",
        content="Never apply loudnorm to final mix. It re-normalizes everything.",
        status="validated")

mem.add(type="decision", title="Use per-line atempo",
        content="Bake speed into per-line TTS. No global pass.",
        status="active")

# Something you're not sure about yet
hypothesis = mem.add(type="decision", title="Maybe try 2-second gaps before CTA",
        content="Hypothesis from last session. Needs testing.",
        status="hypothesis")

# Search — validated and active memories rank highest.
# Deprecated and superseded memories are excluded automatically.
results = mem.search("audio mixing")

# Context-budgeted recall — fits the best memories into your token limit
context = mem.recall("building a narration track", max_tokens=2000)

# Lifecycle — promote what's proven, deprecate what's not
mem.promote(hypothesis.id)                # hypothesis -> active -> validated
mem.deprecate(hypothesis.id, reason="Disproven by data")

# Supersede: replace an outdated memory with a newer one
replacement = mem.add(type="decision", title="Use 1-second gaps before CTA",
        content="Confirmed by A/B test.", status="active")
mem.supersede(hypothesis.id, replacement.id)  # old points to replacement

# Health check — is your memory system trustworthy?
from agentmem import health_check
report = health_check(mem._conn)
# Health: 85/100 | Conflicts: 0 | Stale: 2 | Validated: 14

Qué Lo Hace Diferente

Otras herramientas de memoria almacenan cosas. agentmem sabe lo que sigue siendo cierto.

	Mem0	Letta	Mengram	agentmem
Almacenamiento de memoria	Sí	Sí	Sí	Sí
Búsqueda de texto completo	Vectorial	Impulsada por agente	Grafo de conocimiento	FTS5
Estados del ciclo de vida de la memoria	No	Parcial	No	hipótesis -> activa -> validada -> obsoleta -> superada
Detección de conflictos	No	No	Parcial	Integrada
Detección de obsolescencia	No	No	No	Integrada
Puntuación de salud	No	No	No	Integrada
Seguimiento de procedencia	No	No	No	source_path + source_hash
Recuperación clasificada por confianza	No	No	No	Validada > activa > hipótesis
Archivos fuente legibles por humanos	No	No	No	Markdown canónico
Local primero, cero infraestructura	No	Opción de autoalojamiento	Opción de autoalojamiento	Sí, siempre
Servidor MCP	Separado	Separado	Sí	Integrado

Gobernanza de la Verdad

La idea central: cada memoria tiene un estado que rastrea cuánto deberías confiar en ella.

hypothesis    New observation. Not yet confirmed. Lowest trust in recall.
    |
  active      Default. Currently believed true. Normal trust.
    |
 validated    Explicitly confirmed. Highest trust in recall.

 deprecated   Was true, no longer. Excluded from recall. Kept for history.
 superseded   Replaced by a newer memory. Points to replacement.

Por qué esto importa: Sin gobernanza, la memoria de tu agente acumula reglas obsoletas, contradicciones y decisiones desactualizadas. No sabe que la configuración de voz de enero fue anulada en marzo. Recupera ambas y el LLM elige al azar. La memoria gobernada resuelve esto.

Detección de Conflictos

from agentmem import detect_conflicts

conflicts = detect_conflicts(mem._conn)
# Found 2 conflict(s):
#   !! [decision] "Always apply loudnorm to voice"
#      vs [decision] "NEVER apply loudnorm to voice"
#      Contradiction on shared topic (voice, loudnorm, audio)

agentmem encuentra memorias que se contradicen entre sí:

• Detecta superposición de temas (similitud de Jaccard)
• Separa duplicados de contradicciones
• Coincidencia de negación a nivel de oración (no solo escaneo de palabras clave)
• Severidad: critical (ambas activas) vs warning (una obsoleta)

Detección de Obsolescencia

from agentmem import detect_stale

stale = detect_stale(mem._conn, stale_days=30)
# [decision] "Use atempo 0.90" — Source changed since import (hash mismatch)
# [bug] "Firewall blocks port" — Not updated in 45 days

Encuentra memorias desactualizadas mediante:

• Edad (no actualizada en N días)
• Archivo fuente faltante (el archivo referenciado fue eliminado)
• Desviación de hash (el contenido del archivo fuente cambió pero la memoria no se actualizó)

Verificación de Salud

from agentmem import health_check

report = health_check(mem._conn)
print(f"Health: {report.health_score}/100")
print(f"Conflicts: {len(report.conflicts)}")
print(f"Stale: {len(report.stale)}")

Puntúa tu sistema de memoria de 0 a 100 según: conflictos, porcentaje de obsolescencia, referencias huérfanas, peso de obsoletas y si tienes memorias validadas.

Sincronización Consciente de Procedencia

Sincroniza archivos markdown canónicos en la base de datos con seguimiento de fuente:

# Each memory tracks where it came from
mem.add(type="bug", title="loudnorm lifts noise",
        content="...",
        source_path="/docs/errors.md",
        source_section="Audio Bugs",
        source_hash="a1b2c3d4e5f6")

El motor de sincronización:

• Mismo hash = omitir (idempotente, re-ejecutar no cambia nada)
• Hash diferente = actualizar (el archivo fuente cambió)
• Sección eliminada = marcar obsoleta (con motivo)
• Sección restaurada = resucitar (reactiva memoria obsoleta)

Tres Interfaces

API de Python

from agentmem import Memory

mem = Memory("./my-agent.db", project="frontend")

# CRUD
record = mem.add(type="decision", title="Use TypeScript", content="...")
mem.get(record.id)
mem.update(record.id, content="Updated reasoning.")
mem.delete(record.id)
mem.list(type="bug", limit=20)

# Search + recall
results = mem.search("typescript migration", type="decision")
context = mem.recall("setting up the build", max_tokens=3000)

# Governance
mem.promote(record.id)              # hypothesis -> active -> validated
mem.deprecate(record.id, reason="No longer relevant")
replacement = mem.add(type="decision", title="Use v2 approach", content="...")
mem.supersede(record.id, replacement.id)  # links old to replacement

# Session persistence
mem.save_session("Working on auth refactor. Blocked on token refresh.")
mem.load_session()                  # picks up where last instance left off

# Health
mem.stats()

CLI

# Get started in 30 seconds
agentmem init --tool claude --project myapp

# Check if everything's working
agentmem doctor

# Core
agentmem add --type bug --title "CSS grid issue" "Flexbox fallback needed"
agentmem search "grid layout"
agentmem recall "frontend styling" --tokens 2000

# Governance
agentmem promote <id>
agentmem deprecate <id> --reason "Fixed in v2.3"
agentmem health
agentmem conflicts
agentmem stale --days 14

# Import + sessions
agentmem import ./errors.md --type bug
agentmem save-session "Finished auth module, starting tests"
agentmem load-session

# MCP server
agentmem serve

Servidor MCP

Servidor Model Context Protocol integrado para Claude Code, Cursor y cualquier cliente MCP.

pip install quilmem[mcp]

Configuración de Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "agentmem": {
      "command": "agentmem",
      "args": ["--db", "./memory.db", "--project", "myproject", "serve"],
      "type": "stdio"
    }
  }
}

Herramientas MCP: add_memory, search_memory, recall_memory, update_memory, delete_memory, list_memories, save_session, load_session, promote_memory, deprecate_memory, supersede_memory, memory_health, memory_conflicts

Enséñale a tu agente cómo usar la memoria: Copia las instrucciones del agente en tu CLAUDE.md, .cursorrules o AGENTS.md. Esto enseña a tu agente el protocolo de sesión, la jerarquía de confianza y cuándo buscar vs. añadir.

Memoria Tipada

Siete tipos que cubren flujos de trabajo reales de agentes:

Tipo	Qué almacena	Ejemplo
setting	Configuración, parámetros	"Velocidad de voz: atempo 1.08"
bug	Errores y sus soluciones	"loudnorm eleva el piso de ruido"
decision	Reglas, políticas, elecciones	"Narración en tercera persona prohibida"
procedure	Flujos de trabajo, pipelines	"TTS -> velocidad -> 48kHz -> mezcla"
context	Conocimiento de fondo	"El proyecto usa FFmpeg + Python 3.11"
feedback	Correcciones del usuario	"Siempre elige, no preguntes"
session	Estado de trabajo actual	"Trabajando en autenticación. Bloqueado por tokens."

Recuperación Clasificada por Confianza

recall() no solo encuentra memorias relevantes. Encuentra las memorias relevantes más confiables:

1. La búsqueda FTS5 devuelve candidatos
2. Cada uno puntuado: relevance (25%) + trust status (20%) + provenance (20%) + recency (15%) + frequency (10%) + confidence (10%)
3. Las memorias canónicas validadas se clasifican por encima de las memorias de hipótesis sin procedencia
4. Las memorias obsoletas y superadas se excluyen por completo
5. Empaquetadas de forma codiciosa en tu presupuesto de tokens

Alcance del Proyecto

frontend = Memory("./shared.db", project="frontend")
backend = Memory("./shared.db", project="backend")

frontend.search("bug")  # Only frontend bugs
backend.search("bug")   # Only backend bugs

Probado en Batalla

Esto no es teórico. agentmem se construyó bajo presión de producción durante más de 2 meses de uso diario:

• Más de 65 Shorts de YouTube producidos con cero errores de producción repetidos
• Más de 330 memorias que gobiernan generación de voz, ensamblaje de FFmpeg, generación de imágenes, flujos de trabajo de subida
• Cada error detectado una vez, corregido una vez, nunca repetido
• El motor de gobernanza redujo los conflictos de 1,848 falsos positivos a 11 hallazgos reales

Cómo Funciona

• Almacenamiento: SQLite con modo WAL (lecturas concurrentes, seguro para hilos)
• Búsqueda: FTS5 con stemming de porter y tokenizador unicode61
• Clasificación: Puntuación compuesta: relevancia de texto + estado de confianza + procedencia + actualidad + frecuencia + confianza
• Gobernanza: Ciclo de vida de estado, detección de conflictos, detección de obsolescencia, puntuación de salud
• Sincronización: Consciente de procedencia con hash de fuente y resurrección
• Cero infraestructura: Sin claves API, sin nube, sin base de datos vectorial. Solo un archivo .db.

Licencia

MIT