YourMemory

+16pp mejor recuperación que Mem0 en LoCoMo. 100% de precisión en memoria obsoleta. Decaimiento de memoria inspirado biológicamente para agentes de IA.

Memoria persistente para Claude y cualquier IA compatible con MCP: funciona como la memoria humana. Las cosas importantes permanecen, las olvidadas se desvanecen, los hechos obsoletos se eliminan automáticamente. Los recuerdos relacionados permanecen vivos más tiempo a través de una capa de grafo que entiende las conexiones entre ellos.

Etapa temprana: comentarios e ideas son bienvenidos.

Benchmarks

Evaluado frente a Mem0 (nivel gratuito) en el dataset público LoCoMo (Snap Research): 10 pares de conversación, 200 pares de QA en total.

Metodología completa y resultados por muestra en BENCHMARKS.md. Lee el artículo: I built memory decay for AI agents using the Ebbinghaus forgetting curve

Cómo funciona

Curva de olvido de Ebbinghaus

base_λ      = DECAY_RATES[category]
effective_λ = base_λ × (1 - importance × 0.8)
strength    = importance × e^(-effective_λ × days) × (1 + recall_count × 0.2)
score       = cosine_similarity × strength

La tasa de decaimiento varía según la categoría: los recuerdos de fallos se desvanecen rápido, las estrategias persisten más tiempo:

La importancia modula adicionalmente la tasa de decaimiento dentro de cada categoría. Los recuerdos recuperados frecuentemente obtienen aumentos de recall_count que contrarrestan el decaimiento. Los recuerdos por debajo de una fuerza de 0.05 se eliminan automáticamente.

Motor híbrido de vectores + grafos (v1.3.0)

La recuperación se ejecuta en dos rondas:

Ronda 1: Búsqueda vectorial: similitud de coseno contra todos los recuerdos. Devuelve los top-k por encima del umbral de similitud.

Ronda 2: Expansión de grafo: recorrido BFS desde las semillas de la Ronda 1. Saca a la luz recuerdos que están relacionados con los mejores resultados pero que puntuaron por debajo del corte de similitud: recuerdos que comparten contexto pero no vocabulario.

recall("Python backend")
  Round 1 → [1] Python/MongoDB (sim=0.61), [2] DuckDB/spaCy (sim=0.19)
  Round 2 → [5] Docker/Kubernetes (sim=0.29, below cut-off but graph neighbour of [1])
            surfaced via graph even though vector search missed it

Eliminación consciente de cadenas: un recuerdo se mantiene vivo si alguno de sus vecinos en el grafo todavía está por encima del umbral de eliminación. Los recuerdos relacionados envejecen juntos: un recuerdo fuerte protege a todo un clúster conectado de ser eliminado.

Propagación de recuperación: recuperar un recuerdo aumenta automáticamente el recall_count de sus vecinos en el grafo. Los recuerdos accedidos frecuentemente mantienen fresco su contexto relacionado.

Aristas semánticas: las aristas del grafo se crean basadas en la similitud de coseno (umbral ≥ 0.4), no en el orden de inserción. Peso de la arista = similitud × peso_verbo del predicado SVO extraído por spaCy.

Configuración

Cero infraestructura requerida: utiliza DuckDB de forma nativa. Dos comandos y listo.

Soporta Python 3.11, 3.12, 3.13 y 3.14.

1. Instalar

pip install yourmemory

Todas las dependencias se instalan automáticamente. Sin clonar, sin Docker, sin configuración de base de datos.

2. Ejecutar configuración (una vez)

yourmemory-setup

Descarga el modelo de lenguaje de spaCy e inicializa la base de datos. Ejecuta esto una vez después de la instalación.

3. Obtén tu configuración

yourmemory-path

Imprime tu ruta ejecutable completa y una configuración lista para pegar para cualquier cliente MCP. Cópiala.

4. Conecta a tu cliente de IA

La base de datos se crea automáticamente en ~/.yourmemory/memories.duckdb en el primer uso.

Claude Code

Añadir a ~/.claude/settings.json:

{
  "mcpServers": {
    "yourmemory": {
      "command": "yourmemory"
    }
  }
}

Recarga Claude Code (Cmd+Shift+P → Developer: Reload Window).

Cline (VS Code)

VS Code no hereda tu PATH de shell. Ejecuta esto en la terminal para obtener la configuración exacta a pegar:

yourmemory-path

Luego en Cline → MCP Servers → Edit MCP Settings, pega la salida. Se ve así:

{
  "mcpServers": {
    "yourmemory": {
      "command": "/full/path/to/yourmemory",
      "args": [],
      "env": {
        "YOURMEMORY_USER": "your_name",
        "DATABASE_URL": ""
      }
    }
  }
}

Reinicia Cline después de guardar.

Cursor

Añadir a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "yourmemory": {
      "command": "/full/path/to/yourmemory",
      "args": [],
      "env": {
        "YOURMEMORY_USER": "your_name",
        "DATABASE_URL": ""
      }
    }
  }
}

Claude Desktop

Añadir a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "yourmemory": {
      "command": "yourmemory"
    }
  }
}

Reinicia Claude Desktop.

Cualquier cliente compatible con MCP

YourMemory es un servidor MCP estándar de stdio. Funciona con Claude Code, Claude Desktop, Cline, Cursor, Windsurf, Continue y Zed. Usa la ruta completa de yourmemory-path si el cliente no hereda el PATH del shell.

5. Añade instrucciones de memoria a tu proyecto

Copia sample_CLAUDE.md en la raíz de tu proyecto como CLAUDE.md y reemplaza:

• YOUR_NAME: tu nombre (ej. Alice)

• YOUR_USER_ID: usado para el espacio de nombres de los recuerdos (ej. alice)

Claude ahora seguirá el flujo de trabajo de recuperación → almacenamiento → actualización automáticamente en cada tarea.

Memoria compartida y privada multi-agente

Varios agentes de IA pueden compartir la misma instancia de YourMemory, cada uno con su propia identidad, recuerdos privados aislados y acceso controlado al contexto compartido.

Cómo funciona

Cada recuerdo tiene dos campos que controlan la visibilidad:

Los agentes se autentican con una clave API (prefijo ym_). Sin una clave, el llamador es tratado como el usuario y solo puede leer/escribir recuerdos shared.

Registrar un agente

from src.services.api_keys import register_agent

result = register_agent(
    agent_id="coding-agent",
    user_id="sachit",
    description="Handles code review and refactoring tasks",
    can_read=["shared", "private"],   # what this agent can read
    can_write=["shared", "private"],  # what it can write
)

print(result["api_key"])  # ym_xxxx — save this, shown once only

La clave se cifra con SHA-256 antes del almacenamiento. El texto plano nunca se almacena; si se pierde, revócala y vuelve a registrarla.

Usar la clave API en llamadas MCP

Pasa api_key a cualquier llamada de herramienta MCP:

# Store a private memory — only this agent can recall it
store_memory(
    content="The auth service on staging uses a self-signed cert — skip SSL verify",
    importance=0.7,
    category="failure",
    api_key="ym_xxxx",
    visibility="private"
)

# Store shared context — any agent can recall it
store_memory(
    content="Production database is on PostgreSQL 16, us-east-1",
    importance=0.8,
    category="fact",
    api_key="ym_xxxx",
    visibility="shared"
)

# Recall — returns shared memories + this agent's private memories
recall_memory(
    query="database production",
    api_key="ym_xxxx"
)

Sin api_key, la recuperación devuelve solo recuerdos compartidos.

Control de acceso

Al registrar un agente, can_read controla a qué niveles de visibilidad puede acceder el agente:

# Read-only agent — can see shared context but cannot store private memories
register_agent(
    agent_id="readonly-summarizer",
    user_id="sachit",
    can_read=["shared"],
    can_write=["shared"],
)

# Isolated agent — private memory only, cannot read shared context
register_agent(
    agent_id="isolated-agent",
    user_id="sachit",
    can_read=["private"],
    can_write=["private"],
)

Ejemplo: dos agentes compartiendo contexto

coding-agent stores:
  → "Sachit uses pytest for all Python tests"  (shared, importance=0.8)
  → "Staging API key is sk-staging-xxx"         (private, importance=0.9)

review-agent recalls "Python testing":
  ← "Sachit uses pytest for all Python tests"   ✓ (shared — visible)
  ← "Staging API key is sk-staging-xxx"          ✗ (private — hidden)

coding-agent recalls "Python testing":
  ← "Sachit uses pytest for all Python tests"   ✓ (shared)
  ← "Staging API key is sk-staging-xxx"          ✓ (private — owns it)

Revocar un agente

from src.services.api_keys import revoke_agent

revoke_agent(agent_id="coding-agent", user_id="sachit")
# Key is invalidated immediately — all future calls with it return 401

Herramientas MCP

store_memory acepta un parámetro opcional category para controlar la tasa de decaimiento:

# Failure — decays in ~11 days (environment changes fast)
store_memory(
    content="OAuth for client X fails — redirect URI must be app.example.com",
    importance=0.6,
    category="failure"
)

# Strategy — decays in ~38 days (successful patterns stay relevant)
store_memory(
    content="Cursor pagination fixed the 30s timeout on large user queries",
    importance=0.7,
    category="strategy"
)

Sesión de ejemplo

User: "I prefer tabs over spaces in all my Python projects"

Claude:
  → recall_memory("tabs spaces Python preferences")   # nothing found
  → store_memory("Sachit prefers tabs over spaces in Python", importance=0.9, category="fact")

Next session:
  → recall_memory("Python formatting")
  ← {"content": "Sachit prefers tabs over spaces in Python", "strength": 0.87}
  → Claude now knows without being told again

Trabajo de decaimiento

Se ejecuta automáticamente cada 24 horas al inicio: no se necesita cron. Los recuerdos por debajo de una fuerza de 0.05 se eliminan.

Eliminación consciente de cadenas (v1.3.0): antes de eliminar un recuerdo decaído, el trabajo de decaimiento verifica sus vecinos en el grafo. Si algún vecino todavía está por encima del umbral de eliminación, el recuerdo se mantiene vivo. Esto evita la eliminación aislada de hechos que son parte de un clúster relacionado.

Stack

• DuckDB: backend predeterminado, configuración cero, similitud vectorial nativa (misma calidad que pgvector)

• NetworkX: backend de grafo predeterminado, configuración cero, persiste en ~/.yourmemory/graph.pkl

• Neo4j: backend de grafo opcional para escalabilidad: pip install 'yourmemory[neo4j]', establece GRAPH_BACKEND=neo4j

• sentence-transformers: embeddings locales (all-mpnet-base-v2, 768 dims, no se necesita servicio externo)

• spaCy 3.8.13+: NLP local para deduplicación, categorización y extracción de triples SVO (compatible con Python 3.11–3.14)

• APScheduler: trabajo de decaimiento automático de 24h

• MCP: integración con Claude a través del Protocolo de Contexto de Modelo

• PostgreSQL + pgvector: opcional, para equipos / grandes datasets

Arquitectura

Claude / Cline / Cursor / Any MCP client
    │
    ├── recall_memory(query, api_key?)
    │       └── embed → cosine similarity (Round 1)
    │           → graph BFS expansion (Round 2)
    │           → score = sim × strength → top-k
    │           → recall propagation → boost graph neighbours
    │
    ├── store_memory(content, importance, category?, api_key?, visibility?)
    │       └── is_question? → reject
    │           contradiction check → update existing if conflict
    │           embed() → INSERT memories
    │           → index_memory() → upsert graph node + semantic edges
    │
    └── update_memory(id, new_content, importance)
            └── embed(new_content) → UPDATE memories
                → update graph node strength

Vector DB (Round 1)          Graph DB (Round 2)
DuckDB (default)             NetworkX (default)
  memories.duckdb              graph.pkl
  ├── embedding FLOAT[768]     ├── nodes: memory_id, strength
  ├── importance FLOAT         └── edges: sim × verb_weight ≥ 0.4
  ├── recall_count INTEGER
  ├── visibility VARCHAR     Neo4j (opt-in, GRAPH_BACKEND=neo4j)
  └── agent_id VARCHAR         └── bolt://localhost:7687

Agent Registry
  agent_registrations
  ├── agent_id VARCHAR
  ├── api_key_hash VARCHAR   ← SHA-256, plaintext never stored
  ├── can_read  []           ← ["shared"] | ["private"] | both
  ├── can_write []
  └── revoked_at TIMESTAMP

PostgreSQL (opcional: para equipos o grandes datasets)

Instalar con soporte para Postgres:

pip install yourmemory[postgres]

Luego crea un archivo .env:

DATABASE_URL=postgresql://YOUR_USER@localhost:5432/yourmemory

El backend se selecciona automáticamente: postgresql:// en DATABASE_URL → Postgres + pgvector, cualquier otra cosa → DuckDB.

macOS

brew install postgresql@16 pgvector && brew services start postgresql@16
createdb yourmemory

Ubuntu / Debian

sudo apt install postgresql postgresql-contrib postgresql-16-pgvector
createdb yourmemory

Referencia del dataset

Los benchmarks utilizan el dataset LoCoMo de Snap Research: un benchmark público de memoria de contexto largo para diálogos de múltiples sesiones.

Maharana et al. (2024). LoCoMo: Long Context Multimodal Benchmark for Dialogue. Snap Research.

Licencia

Copyright 2026 Sachit Misra

Licenciado bajo CC-BY-NC-4.0 (Creative Commons Attribution-NonCommercial 4.0).

Gratis para: uso personal, educación, investigación académica, proyectos de código abierto.

No permitido: uso comercial de cualquier tipo, incluyendo SaaS, herramientas internas en empresas con fines de lucro o servicios pagados, sin un acuerdo escrito por separado.

Para licencias comerciales: mishrasachit1@gmail.com