¿Qué es mcp-memory?

mcp-memory es un reemplazo drop-in del servidor MCP Memory de Anthropic. Proporciona un knowledge graph persistente donde los agentes de IA almacenan entidades, observaciones y relaciones — y las recuperan entre sesiones.

Mantiene compatibilidad total con la API de las 8 tools de Anthropic, a la vez que añade búsqueda semántica, recuperación híbrida y un motor de scoring dinámico. Todos los datos se almacenan en SQLite con modo WAL para acceso concurrente seguro. Consulta la página de Arquitectura para profundizar en su funcionamiento.

Por qué existe

El servidor oficial de Anthropic almacena todo el knowledge graph en un único archivo JSONL. Esto funciona para demos, pero falla bajo uso real:

El servidor oficial reescribe el archivo completo en cada operación. Sin locking ni escrituras atómicas, las operaciones concurrentes producen fusión de JSONs y líneas duplicadas. mcp-memory resuelve estos problemas de raíz con un motor de almacenamiento diseñado para datos persistentes.

Requisitos

• Python >= 3.12
• uv (recomendado) o pip para gestión de dependencias
• Git para clonar el repositorio
• ~465 MB de espacio en disco si descargas el modelo de embedding (opcional)
• ~50 MB para la suite de tests (402 tests pasando)

Instalación

1. Clonar el repositorio

git clone https://github.com/Yarlan1503/mcp-memory.git
cd mcp-memory

2. Instalar dependencias

uv sync

uv sync crea un entorno virtual, resuelve todas las dependencias desde pyproject.toml y genera el entry point mcp-memory.

3. Descargar el modelo de embeddings

uv run python scripts/download_model.py

El modelo se descarga automáticamente en el primer uso. El script siguiente se proporciona para configuraciones manuales/offline.

Esto descarga el modelo de oraciones sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 (~465 MB) a ~/.cache/mcp-memory-v2/models/:

:::tip La descarga del modelo es opcional. El servidor arranca y ejecuta las 19 tools sin él. Solo search_semantic, find_duplicate_observations y search_reflections requieren el modelo. Consulta Sin el modelo más abajo. :::

4. Verificar la instalación

uv run mcp-memory

El servidor arranca como un proceso stdio. Se registra como "memory" en el protocolo MCP, escucha JSON-RPC en stdin y envía logs a stderr (sin interferir con la comunicación MCP).

:::note No verás salida en stdout — eso es correcto. El servidor se comunica mediante el protocolo MCP (JSON-RPC sobre stdio). Los logs van a stderr. :::

Configuración

OpenCode

Añade a la sección mcp de tu opencode.json:

{
  "mcp": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory", "run", "mcp-memory"]
    }
  }
}

Reemplaza /path/to/mcp-memory con la ruta absoluta al repositorio clonado.

Claude Desktop

Añade al archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "mcp-memory"],
      "cwd": "/path/to/mcp-memory"
    }
  }
}

Reemplaza /path/to/mcp-memory con la ruta absoluta al repositorio clonado.

uvx (sin clonar el repositorio)

Si prefieres no clonar el repo, ejecuta directamente desde GitHub:

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

:::caution El método uvx no permite descargar el modelo de embeddings. Si necesitas búsqueda semántica, clona el repositorio y sigue los pasos de instalación anteriores. :::

Primeros pasos

Crear entidades

Almacena conocimiento como entidades con nombre, tipo y observaciones:

{
  "entities": [
    {
      "name": "My Project",
      "entityType": "Project",
      "observations": [
        "Built with Astro and Starlight",
        "Deployed on Vercel",
        "Uses Pagefind for search"
      ]
    }
  ]
}

Si una entidad ya existe, create_entities fusiona las observaciones en lugar de sobrescribir. Los duplicados se descartan.

Conectar entidades con relaciones

Vincula entidades con relaciones tipadas:

{
  "relations": [
    {
      "from": "My Project",
      "to": "Astro",
      "relationType": "uses"
    },
    {
      "from": "My Project",
      "to": "Vercel",
      "relationType": "deployed_on"
    }
  ]
}

Ambas entidades deben existir antes de crear una relación entre ellas.

Buscar por substring

Encuentra entidades por palabra clave en nombres, tipos y contenido de observaciones:

{
  "query": "project"
}

search_nodes usa coincidencia de patrones LIKE. No requiere el modelo de embeddings y retorna todas las entidades cuyo nombre, tipo u observaciones contengan la cadena de búsqueda.

Buscar por significado

Encuentra entidades relacionadas semánticamente con tu consulta, incluso sin coincidencia de palabras clave:

{
  "query": "web framework deployment",
  "limit": 5
}

search_semantic codifica la consulta en un vector de 384 dimensiones y encuentra los vecinos más cercanos por similitud coseno. Los resultados se reordenan mediante el motor de Limbic Scoring, que considera frecuencia de acceso, recencia y patrones de co-ocurrencia.

División automática de entidades grandes

Las entidades con muchas observaciones pueden dividirse automáticamente en sub-entidades enfocadas:

{
  "entity_name": "Mi Proyecto"
}

analyze_entity_split evalúa si una entidad excede su umbral por tipo (Sesion=15, Proyecto=25, otras=20) y usa clustering semántico (Agglomerative + c-TF-IDF fallback) para agrupar observaciones en tópicos. Si se recomienda splitting, propose_entity_split retorna los nombres sugeridos de las nuevas entidades y las relaciones a crear.

{
  "entity_name": "Mi Proyecto",
  "approved_splits": [
    {
      "name": "Mi Proyecto - Arquitectura",
      "entity_type": "Proyecto",
      "observations": ["Stack: FastMCP + SQLite", "MCP Memory v2"]
    }
  ]
}

execute_entity_split crea las nuevas entidades, mueve las observaciones, y establece relaciones contiene/parte_de — todo dentro de una transacción atómica.

:::tip Para el workflow completo de entity splitting y los detalles de extracción de tópicos con clustering semántico, consulta la página de Referencia de Tools. :::

Sin el modelo

El servidor funciona sin el modelo de embeddings descargado. Esto es lo que cambia:

Cuando el modelo no está disponible, search_semantic retorna un mensaje de error con instrucciones para ejecutar el script de descarga. Todas las demás tools funcionan con normalidad.

Próximos pasos

• Arquitectura — entiende el motor de almacenamiento, pipeline de embeddings y flujo de datos
• Referencia de Tools — parámetros, respuestas y casos edge para las 19 tools
• Búsqueda Semántica — cómo trabajan juntos búsqueda vectorial, búsqueda híbrida y Limbic Scoring
• Mantenimiento & Operaciones — deduplicación, splitting de entidades, reportes de consolidación y mejores prácticas
• Auto-tuning — optimiza GAMMA y BETA_SAL vía grid search