memory-lean

Memoria a largo plazo para agentes de codificación de IA que no consume la ventana de contexto. Un reemplazo directo para el servidor de memoria de referencia con respuestas aproximadamente 40 veces más pequeñas. Un solo archivo, cero dependencias.

GitHub

Documentación

memory-lean

Memoria a largo plazo para agentes de codificación con IA que no quema la ventana de contexto.

Inicio rápido · Lo que ve el agente · Por qué se mantiene ligero · Herramientas · Protocolo del agente · Configuración · Contribuciones

memory-lean es un servidor MCP que le da a Claude Code, Claude Desktop, Cursor y cualquier otro cliente MCP un grafo de conocimiento que persiste entre sesiones. Es un reemplazo directo del servidor de memoria de referencia (@modelcontextprotocol/server-memory): mismo archivo memory.jsonl, mismos nueve nombres de herramientas, más dos extras. Lo que cambia es cuánto devuelven las herramientas.

Llamada, en un grafo real de 237 entidades	Servidor de referencia	memory-lean
`read_graph`	~77,800 tokens	~2,000 tokens	40× más pequeño
`search_nodes` (promedio de 5 palabras comunes)	~31,000 tokens	~770 tokens	40× más pequeño

Un archivo. Sin dependencias. Nada que compilar.

Inicio rápido

Claude Code: instala el plugin. Añade el servidor, una skill con las instrucciones del agente y un recordatorio breve al inicio de cada sesión.

/plugin marketplace add zamansheikh/memory-lean
/plugin install memory-lean@memory-lean

Cualquier otro agente: añade el servidor a la configuración MCP del agente y luego dale las instrucciones.

{
  "mcpServers": {
    "memory": { "command": "npx", "args": ["-y", "memory-lean"] }
  }
}

npx -y memory-lean --protocol >> AGENTS.md   # into the rules file your agent reads

El archivo de configuración y su forma exacta varían según el agente.

La configuración de copiar y pegar para cada agente está en docs/SETUP.md:

Agente	Configuración del servidor	Instrucciones
Claude Code	plugin	incluidas en el plugin
Xiaomi MiMo Code	`mimocode.jsonc`	skill o `AGENTS.md`
opencode	`opencode.json`	`AGENTS.md`
OpenAI Codex CLI	`codex mcp add`	`AGENTS.md`
Cursor	`.cursor/mcp.json`	`AGENTS.md` o una regla
VS Code (Copilot)	`.vscode/mcp.json`	`copilot-instructions.md`
Gemini CLI	`settings.json`	`GEMINI.md`
Windsurf	`mcp_config.json`	una regla
Cline	`cline_mcp_settings.json`	`.clinerules/`
Zed	`settings.json`	`AGENTS.md` o `.rules`
IDE de JetBrains	configuración de AI Assistant	una regla o pautas
Claude Desktop	`claude_desktop_config.json`	instrucciones del proyecto

El grafo se crea en la primera escritura en ~/.claude/memory-graph/memory.jsonl, independientemente de qué agente escriba en él, así que varios agentes pueden compartir una sola memoria. Establece MEMORY_FILE_PATH para guardarlo en otro lugar.

Ejecutar desde un clon en lugar de npm

git clone https://github.com/zamansheikh/memory-lean.git
claude mcp add --scope user memory -- node /absolute/path/to/memory-lean/server/memory-lean.mjs

No se necesita npm install.

Lo que ve el agente

El servidor de referencia responde a una búsqueda con cada entidad coincidente completa, como JSON con formato bonito. memory-lean responde con una lista clasificada de nombres y las líneas que coincidieron:

> search_nodes { "query": "deploy" }

57 match "deploy", top 10 shown (narrow the query or raise limit). open_nodes for full entities.
- shop-backend [service] 12 obs, 6 rel
    › 2026-03-02: deployed 2.4.0 to production
    › deploy with scripts/release.sh, never by hand
- PENDING shop-backend 2.4.0 [pending] 2 obs, 3 rel
    › …mobile apps still call the old endpoint until the deploy of 2.4.0 reaches them

El agente entonces abre solo lo que necesita:

> open_nodes { "names": ["shop-backend"] }

## shop-backend [service]
- NestJS API behind api.example.com
- 2026-03-02: deployed 2.4.0 to production

## relations
shop-app -talks_to-> shop-backend
PENDING shop-backend 2.4.0 -blocks-> shop-app

Ese es el patrón completo: buscar, luego abrir.

Por qué se mantiene ligero

Un grafo de conocimiento solo es útil si el agente puede permitirse mirarlo, y un grafo al que cada sesión añade crece sin límite. memory-lean limita tanto lo que devuelve como lo que almacena.

Límite	Qué significa
Respuestas pequeñas	`search_nodes` devuelve como máximo 10 nombres con fragmentos, `read_graph` devuelve un índice de nombres, y solo `open_nodes` devuelve entidades completas.
Hechos cortos	Una observación de más de 300 caracteres se rechaza, con un mensaje que le dice al agente que la divida o que ponga el detalle en el repositorio.
Un tope por entidad	Una entidad conserva 15 observaciones. Pasado eso, las más antiguas con fecha se mueven a `archive/<entity>.md` junto al grafo. Nada se elimina: el agente puede listarlas y restaurarlas, y las observaciones sin fecha (los hechos de identidad) siempre permanecen.
Búsqueda de varias palabras que funciona	Cada palabra debe coincidir en algún lugar de la entidad, así que añadir una palabra reduce el resultado. El servidor de referencia busca la consulta como una frase exacta.

Y es cuidadoso con el archivo:

Salvaguarda	Qué significa
Seguro para compartir	Los escritores toman un archivo de bloqueo, así que varias sesiones de agentes pueden usar un grafo sin sobrescribirse entre sí. Cada escritura reemplaza el archivo de forma atómica.
Copias de seguridad diarias	Una copia va a `backups/` una vez al día; se conservan las últimas 7.
Las líneas dañadas se conservan	Una línea que no se puede leer se mueve a `memory.jsonl.unreadable` en la siguiente escritura y se informa, nunca se descarta en silencio.
Archivos simples	El grafo es JSON lines, los archivos son Markdown, las copias de seguridad son copias. Puedes leer, grep y editar todo a mano.

Mídelo en tu propio grafo

Desde un clon de este repositorio:

node tools/bench.mjs                  # read_graph + your five most common words
node tools/bench.mjs deploy "api v2"  # your own queries

Es de solo lectura e imprime tamaños, nunca contenido. Los tokens se estiman como caracteres ÷ 4. Una búsqueda estrecha que coincide con una o dos entidades ahorra mucho menos, porque había poco que recortar.

Herramientas

Herramienta	Qué devuelve
`search_nodes`	Lista clasificada de nombres de entidades con conteos y hasta dos fragmentos coincidentes cada una. Cada palabra debe coincidir con el nombre, el tipo, una observación o el tipo de una relación que toque la entidad.
`open_nodes`	Las entidades completas que nombres, como texto compacto, con cada relación que las toque. Los nombres desconocidos vuelven con sugerencias de "quisiste decir".
`read_graph`	Un índice: nombres de entidades agrupados por tipo, con conteos de observaciones. Nunca las observaciones.
`create_entities`	Crea entidades; los nombres existentes se omiten.
`create_relations`	Crea relaciones entre entidades existentes; los duplicados se omiten.
`add_observations`	Añade hechos a una entidad, aplicando el límite de longitud y el tope por entidad.
`rename_entity`	Renombra una entidad, conservando sus observaciones, relaciones y archivo. No está en el servidor de referencia.
`archived_observations`	Lista lo que se archivó para una entidad, opcionalmente filtrado, y puede restaurar observaciones elegidas. No está en el servidor de referencia.
`delete_observations`	Elimina observaciones por texto exacto.
`delete_relations`	Elimina relaciones específicas.
`delete_entities`	Elimina entidades y cada relación que las toque.

Las tres herramientas de lectura están marcadas como de solo lectura, así que los clientes que lo soporten pueden ejecutarlas sin preguntar.

Enséñale a tu agente a usarlo

Un servidor de memoria solo ayuda si el agente lo lee antes de trabajar y escribe en él cuando algo cambia. docs/AGENT-PROTOCOL.md es un conjunto de instrucciones listo para usar: qué buscar al inicio de una tarea, qué registrar, cómo nombrar las cosas y qué nunca almacenar. El plugin de Claude Code lo incluye. Para cualquier otro agente, un comando lo instala:

npx -y memory-lean --protocol >> AGENTS.md     # into a rules file: always on
npx -y memory-lean --skill .agents/skills      # as an Agent Skill: loaded when relevant

Ajusta los tipos de entidad y los nombres en él a tu propio trabajo.

Si vienes del servidor de memoria de referencia

Apunta MEMORY_FILE_PATH a tu memory.jsonl existente y cambia el comando. El formato de archivo es idéntico, así que puedes volver atrás en cualquier momento. Las observaciones existentes de más de 300 caracteres se conservan tal cual; solo se verifican las nuevas escrituras.

Para ver qué en un grafo existente está por encima del presupuesto y, opcionalmente, corregirlo:

npx -y memory-lean --lint      # report only
npx -y memory-lean --compact   # back up, then move overflow to archive/

Configuración

Todo opcional, establecido como variables de entorno en el servidor:

Variable	Predeterminado	Significado
`MEMORY_FILE_PATH`	`~/.claude/memory-graph/memory.jsonl`	Dónde vive el grafo
`MEMORY_OBS_MAX_CHARS`	`300`	Observación más larga aceptada
`MEMORY_OBS_MAX`	`15`	Observaciones por entidad antes de que las más antiguas con fecha se archiven
`MEMORY_SEARCH_LIMIT`	`10`	Número predeterminado de resultados de búsqueda
`MEMORY_BACKUPS_KEPT`	`7`	Copias de seguridad diarias conservadas

Bueno saber

Tu grafo es privado. Contiene lo que tu agente aprendió sobre tus proyectos. Mantenlo fuera de git y nunca almacenes contraseñas, claves o tokens en él: registra dónde vive un secreto, no su valor.
La búsqueda es coincidencia de texto plano, no embeddings. Los buenos nombres de entidades importan más que las consultas ingeniosas.

Hoja de ruta

Un plugin de Claude Code que instala el servidor y el protocolo del agente juntos
Configuración lista para MiMo Code, Codex, Cursor y otros agentes
Guías de configuración para Cline, Zed e IDE de JetBrains
Windows en la matriz de CI
rename_entity, manteniendo las relaciones intactas
Una forma de listar y restaurar observaciones archivadas
Listados en el registro MCP y el directorio de plugins de Claude Code
Búsqueda en observaciones archivadas de cada entidad

Contribuciones

Las ideas, informes de errores y solicitudes de extracción son bienvenidos. Todo el servidor es un archivo sin dependencias, y npm test se ejecuta en aproximadamente un segundo, así que un primer cambio es rápido de hacer. CONTRIBUTING.md tiene el diseño, las reglas básicas y una lista de buenas primeras contribuciones.

Si pruebas memory-lean en tu propio grafo, la salida de tools/bench.mjs es una publicación de issue útil. Y si te ahorra tokens, una ⭐ ayuda a que otras personas lo encuentren.