Contextual memory server for agent orchestration using Redis
mcp-memory-server
Servidor MCP de memoria contextual y avanzada sobre Redis: listas cronológicas, memoria semántica (Redis Stack), rollup de historial, scratchpad con TTL y Pub/Sub inter-agente. Pensado para orquestación de agentes.
Arquitectura (hexagonal mínima)
- domain/ — Contrato de resultado (
ToolResult,toolErrorResult,errorToToolResult). Sin I/O. - ports/ — Interfaces:
ContextualMemoryPort,SemanticMemoryPort,ScratchpadPort,EventPublisherPort. - application/ — Casos de uso que reciben un puerto y devuelven
ToolResult(formateo y reglas de negocio). - adapters/redis/ — Implementación de los puertos con ioredis (y RediSearch para semántica).
- adapters/mcp/ — Schemas Zod y registro de tools en el servidor MCP; cada tool parsea input y llama al caso de uso con el puerto inyectado.
El entrypoint (index.ts) crea el cliente Redis, instancia los adaptadores y arranca el servidor con startServer(ports).
Herramientas (Tools)
Memoria cronológica (listas)
| Nombre | Parámetros | Descripción |
|---|---|---|
get_recent_context |
agent_key, limit (opcional, default 5) |
Últimas N entradas de la bitácora (hidratación del agente). |
append_contextual_memory |
agent_key, new_entry |
Registra un nuevo hito en la bitácora. |
get_all_context |
agent_key |
Historial completo (para orquestador o resumen). |
Memoria semántica (Redis Stack; búsqueda por similitud)
| Nombre | Parámetros | Descripción |
|---|---|---|
append_semantic_memory |
agent_key, embedding (number[]), content, metadata (opcional) |
Guarda un recuerdo con vector para búsqueda asociativa. |
search_semantic_memory |
agent_key, embedding, top_k (opcional, default 5), score_threshold (opcional) |
"Tráeme recuerdos similares a este contexto". |
Rollup / compresión
| Nombre | Parámetros | Descripción |
|---|---|---|
get_memory_stats |
agent_key |
Cantidad de entradas y primera/última ts; para decidir cuándo hacer rollup. |
rollup_memory_segment |
agent_key, keep_last (default 20), summary_entry |
Reemplaza entradas antiguas por un ítem [RESUMEN HISTÓRICO]; el orquestador genera el resumen y pasa el texto. |
Scratchpad (TTL)
| Nombre | Parámetros | Descripción |
|---|---|---|
set_scratchpad_entry |
agent_key, name, value, ttl_seconds (opcional, default 3600) |
Guarda dato temporal; Redis lo borra al expirar. |
get_scratchpad_entry |
agent_key, name |
Lee un scratchpad. |
clear_scratchpad_entry |
agent_key, name |
Borra antes del TTL. |
Comunicación inter-agente (Pub/Sub)
| Nombre | Parámetros | Descripción |
|---|---|---|
publish_interagent_message |
channel, sender_agent_key, payload |
Publica en un canal; agentes suscritos (fuera del MCP) lo reciben. |
get_channel_log |
channel, limit (opcional, default 20) |
Lee los últimos mensajes del log del canal (para quien no mantiene suscripción). |
Nota: El MCP no mantiene suscripciones; solo publica y escribe en log. La recepción en tiempo real la hace un proceso que ejecute SUBSCRIBE en Redis.
Datos en Redis: listas por agent_key con JSON {ts, entry, type?}; memoria semántica en hashes con RediSearch; scratchpad en claves con EX; canales con prefijo channel:.
Cómo ejecutar
Con Cursor (MCP en host, Redis en Docker)
- Levantar Redis: desde la raíz del repo:
docker compose up -d redis_db - En
mcp-memory-server:cd mcp-memory-server npm install npm run build - En
.cursor/mcp.json(raíz del workspace) añadí el servidor. Reiniciar Cursor tras cambiarmcp.json.
Cursor: uso standalone (repo por separado)
Si este repo se usa solo (sin orquestador), en la raíz del proyecto donde está mcp-memory-server:
npm install && npm run build
En .cursor/mcp.json del workspace que use este MCP:
"mcp-memory-server": {
"command": "node",
"args": ["mcp-memory-server/dist/index.js"],
"env": {
"REDIS_URL": "redis://localhost:6379"
}
}
Si el MCP está en otra ruta, ajustá args (ej. path absoluto o relativo al cwd de Cursor).
Todo en Docker
docker compose up -d
El servicio mcp_memory_server corre dentro de la red; para uso por stdio desde Cursor hay que ejecutar el MCP en el host (ver arriba).
Orquestación y prompts de ejemplo
Prompt para el agente (memoria cronológica)
Eres un arquitecto experto. Para recordar en qué estás trabajando, usa la herramienta de memoria con la clave
agent:arq_1. Al empezar, llama aget_recent_contextcon esa clave; cuando completes un paso, usaappend_contextual_memorycon la misma clave y un resumen breve.
Playbook orquestador (cuándo llamar cada tool)
- Hidratación (agente):
get_recent_context(agent_key, limit)— solo los
Tools (12)
get_recent_contextRetrieves the last N entries of the agent's log.append_contextual_memoryRegisters a new milestone in the agent's log.get_all_contextRetrieves the full history for an agent.append_semantic_memorySaves a memory with a vector for associative search.search_semantic_memoryFinds memories similar to the provided context.get_memory_statsReturns entry count and timestamps to help decide when to perform a rollup.rollup_memory_segmentReplaces old entries with a summary item.set_scratchpad_entrySaves a temporary data entry with a TTL.get_scratchpad_entryReads a scratchpad entry.clear_scratchpad_entryDeletes a scratchpad entry before its TTL expires.publish_interagent_messagePublishes a message to a specific channel for other agents.get_channel_logReads the latest messages from a channel log.Environment Variables
REDIS_URLrequiredConnection string for the Redis instanceConfiguration
{"mcp-memory-server": {"command": "node", "args": ["mcp-memory-server/dist/index.js"], "env": {"REDIS_URL": "redis://localhost:6379"}}}