Agent Memory

Memoria del agente del sistema de archivos que funciona con el daemon de consolidación en tu máquina

GitHub
4
Prueba este MCPPatrocinado

Documentación

Un MCP de Sistema de Archivos para Agent Memory

mcp-agent-memory MCP server

Servidor MCP que expone agent-memory-daemon a cualquier cliente compatible con MCP — Kiro (CLI e IDE), Claude Desktop, Cursor, y otros.

El daemon hace el trabajo de pensar (consolidación + extracción); este servidor es un puente ligero de sistema de archivos para que los agentes puedan leer, añadir y buscar memoria a través del Protocolo de Contexto de Modelo.

output

Cómo encaja todo

 ┌──────────────┐     MCP/stdio     ┌────────────────────┐     filesystem      ┌────────────────────────┐
 │ Kiro / Claude│ ◄───────────────► │ mcp-server-memory  │ ◄─────────────────► │ agent-memory-daemon    │
 │   / Cursor   │                   │  (this package)    │   ~/.agent-memory/   │  (runs in background)  │
 └──────────────┘                   └────────────────────┘                     └────────────────────────┘
  • El servidor MCP lee/escribe archivos bajo ~/.agent-memory/
  • El daemon observa el mismo directorio y ejecuta pasadas de consolidación y extracción
  • Nunca se comunican directamente entre sí — el sistema de archivos es el contrato

Herramientas expuestas

memory_read

Lee el índice de memoria del agente (MEMORY.md) y opcionalmente archivos de temas específicos. Llama sin argumentos para cargar solo el índice ligero (económico). Pasa topics solo cuando necesites el contenido completo de un archivo de tema específico.

ParámetroTipoRequeridoDescripción
topicsstring[]NoNombres de archivos de tema a cargar completos (p. ej., ["preferences", "projects"]). Omite para devolver solo el índice.

memory_append_session

Añade un resumen de sesión al directorio de sesiones. El daemon extraerá posteriormente memorias duraderas de él. Llama a esto al final de intercambios significativos. Mantén los resúmenes enfocados en hallazgos y decisiones duraderos (objetivo de 300–800 tokens), no en una narración paso a paso — los resúmenes más largos cuestan más durante la consolidación.

ParámetroTipoRequeridoDescripción
contentstringSíResumen de sesión en formato Markdown. Usa encabezados estructurados y viñetas para una mejor extracción; evita prosa verbosa.
sourcestringNoEtiqueta de origen, p. ej., "kiro", "claude-desktop"

memory_search

Busca una subcadena en los archivos de memoria. Úsalo para recordar hechos específicos sin cargar todo.

ParámetroTipoRequeridoDescripción
querystringSíLa subcadena a buscar en todos los archivos de memoria.

Instalación

npm install -g mcp-agent-memory

Inicio rápido (asistente interactivo)

La forma más rápida de configurar todo — directorio de memoria, daemon, configuraciones de cliente, registros y LaunchAgent — es el asistente de configuración:

mcp-agent-memory --setup

Hace seis preguntas:

  1. Directorio de memoria — donde vive .agent-memory/ (por defecto ~/.agent-memory)
  2. ¿Instalar el daemon de consolidación? — di "no" para modo solo-MCP (los agentes pueden leer/escribir/buscar memoria, pero sin consolidación automática)
  3. Backend de LLM — bedrock, openai, o kiro (se omite si rechazaste el daemon)
  4. Configuración de consolidación — min_hours, min_sessions, intervalo de extracción, máx. caracteres
  5. Modo de ejecución — standalone (inicio manual) o launchagent (inicio automático al iniciar sesión, solo macOS)
  6. Directorio de registros + TTL — dónde poner los registros y cuántos días conservarlos (0 = para siempre)
  7. Registro de cliente — registrar automáticamente el servidor MCP en las configuraciones de Kiro, Claude Desktop y/o Cursor (las entradas MCP existentes se conservan)

Cuando seleccionas el backend kiro, el asistente también copia un agente ligero a ~/.kiro/agents/memconsolidate.json que reduce el uso de tokens en ~7× (ver backend de Kiro).

Cuando seleccionas launchagent, el asistente verifica que agent-memory-daemon esté instalado (y ofrece npm install -g si no lo está), luego registra e inicia el plist.

Referencia de CLI

mcp-agent-memory                       # run as an MCP server (normal mode — clients spawn it)
mcp-agent-memory --setup               # first-time interactive setup
mcp-agent-memory --configure           # re-run most steps; can add/remove the daemon later
mcp-agent-memory --remove              # interactive uninstall (backup memory, clean configs)

# macOS LaunchAgent control:
mcp-agent-memory --daemon status       # is the daemon running?
mcp-agent-memory --daemon start        # load and start
mcp-agent-memory --daemon stop         # unload (keeps the plist)
mcp-agent-memory --daemon restart      # stop + start
mcp-agent-memory --daemon remove       # unload and delete the plist

--remove conserva otras entradas en las configuraciones MCP del cliente — solo se elimina la clave memory. Por defecto hace una copia de seguridad de ~/.agent-memory/ en un directorio .bak-* con marca de tiempo para que puedas restaurar tus memorias consolidadas.

Instalación manual

Si prefieres omitir el asistente, así es como se hace a mano.

Instalar el daemon (opcional)

El servidor MCP funciona de forma independiente — solo lee y escribe archivos bajo ~/.agent-memory/. Las memorias persisten, pero no se consolidarán ni extraerán de las sesiones hasta que añadas el daemon.

npm install -g agent-memory-daemon

# copy the example config
mkdir -p ~/.agent-memory
cp examples/memconsolidate.toml ~/.agent-memory/memconsolidate.toml

# start the daemon
agent-memory-daemon start ~/.agent-memory/memconsolidate.toml

Consulta examples/memconsolidate.toml para una configuración lista para usar que coincida con la estructura de directorios que este servidor MCP espera.

Ejecutar el daemon al iniciar sesión (macOS)

En lugar de iniciar el daemon manualmente, regístralo como LaunchAgent:

./scripts/daemon.sh start          # install plist, load it, start at login
./scripts/daemon.sh status         # check if it's running
./scripts/daemon.sh stop           # unload (keeps the plist)
./scripts/daemon.sh remove         # unload and delete the plist

Pasa una ruta de configuración personalizada como segundo argumento: ./scripts/daemon.sh start /path/to/config.toml. Los registros se guardan en ~/.agent-memory/logs/daemon.{out,err}.log. remove deja tu configuración y archivos de memoria intactos.

Usar Kiro como backend de LLM

Si tienes créditos de Kiro, puedes ejecutar el daemon a través de kiro-cli en lugar de pagar por llamadas a la API de Bedrock u OpenAI. Esto requiere agent-memory-daemon ≥ 2.7 (rama feat/kiro-backend) que añade un backend kiro.

[llm_backend]
name = "kiro"
# optional overrides:
# binary = "/custom/path/to/kiro-cli"
# agent = "memconsolidate"          # set to "" to use Kiro's default session context (not recommended)
# model = "claude-sonnet-4-20250514"
# timeoutMs = 300000

Usa un agente ligero para reducir el uso de tokens en ~7×. Por defecto, cada llamada a kiro-cli chat carga el prompt de sistema completo de Kiro más cada esquema de herramienta MCP de tu configuración global — aproximadamente 12–18K tokens de entrada adicionales por llamada. Crea un agente mínimo que omita todo eso:

cp examples/kiro-agent-memconsolidate.json ~/.kiro/agents/memconsolidate.json

El backend de Kiro pasa --agent memconsolidate automáticamente, por lo que no se necesita configuración adicional. Medido en un prompt trivial: 0.01 créditos con el agente ligero vs. 0.07 créditos con el predeterminado (misma calidad de salida).

Consulta examples/kiro-agent-memconsolidate.json — el agente tiene mcpServers: {}, tools: [] y useLegacyMcpJson: false para que no herede nada de tu configuración global de Kiro.

Configurar clientes manualmente

Los asistentes --setup y --configure manejan esto por ti. Esta sección es para usuarios que quieren configurar las cosas a mano.

Kiro (CLI e IDE)

Edita ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "disabled": false,
      "timeout": 30000,
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

¿Por qué autoApprove? Todas las herramientas de memoria son operaciones de sistema de archivos solo locales — leen/escriben archivos Markdown bajo ~/.agent-memory/ y nunca hacen llamadas de red. Añadirlas a autoApprove permite que Kiro las llame sin pedirte confirmación cada vez, lo cual es esencial para la experiencia fluida de "leer memoria al inicio de la sesión".

Luego pregunta a Kiro: "Lee mi índice de memoria." o "Recuerda esto: prefiero pnpm sobre npm."

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-agent-memory"],
      "env": {
        "MEMORY_DIRECTORY": "~/.agent-memory/memory",
        "SESSION_DIRECTORY": "~/.agent-memory/sessions"
      },
      "autoApprove": ["memory_read", "memory_search", "memory_append_session", "memory_daemon_status"]
    }
  }
}

Reinicia Claude Desktop. Las herramientas memory_* aparecerán.

Cursor

Añade a ~/.cursor/mcp.json el mismo bloque de servidor (incluyendo autoApprove).

Variables de entorno

VariablePredeterminadoDescripción
MEMORY_DIRECTORY~/.agent-memory/memoryDónde almacena el daemon los archivos de memoria consolidados
SESSION_DIRECTORY~/.agent-memory/sessionsDónde aterrizan los resúmenes de sesión escritos por el agente

Ambas rutas deben coincidir con lo que usa tu configuración de agent-memory-daemon.

Prompt de agente recomendado

Dile a tu agente que llame a memory_read al inicio de una conversación y a memory_append_session al final. Ejemplo de regla de dirección para Kiro (~/.kiro/steering/memory.md):

At the start of every session, call memory_read (no arguments) to load my memory
index. Only pass `topics` when the task genuinely needs the full content of a
specific topic file.

When you learn something durable about me, my projects, or my preferences, call
memory_append_session with a concise markdown summary. Target 300-800 tokens,
use structured headers and bullets (not prose), and focus on durable findings
and decisions — not play-by-play. Verbose summaries cost more during the
daemon's consolidation pass.

Consejos de uso de tokens

Cada una de las tres herramientas tiene un perfil de costo diferente. Algunas prácticas mantienen bajas las facturas de inferencia + consolidación:

  • memory_read sin argumentos devuelve solo el índice MEMORY.md (típicamente <1 KB). Prefiere esto sobre topics a menos que necesites el contenido completo.
  • memory_search se basa en subcadenas y devuelve ≤3 líneas coincidentes por archivo — más económico que cargar archivos de tema completos.
  • memory_append_session no cuesta nada en el momento de la llamada, pero cada sesión se procesa por el LLM del daemon durante la consolidación. Mantén los resúmenes concisos y estructurados.
  • Consolida o poda archivos de tema antiguos ocasionalmente. Ejecuta mcp-agent-memory --configure — ahora advierte si tu directorio de memoria supera los 25 archivos o 200 KB.
  • La poda de sesiones después de la extracción la maneja el daemon, no el servidor MCP. Consulta la configuración de agent-memory-daemon para opciones que archiven o eliminen sesiones después de procesarlas (evita que el daemon re-escanee sesiones antiguas para siempre).

Licencia

MIT