Primeros Pasos

¿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:

Dimension	JSONL (Anthropic)	mcp-memory
Indexación	Ninguna — escaneo completo en cada consulta	Índices SQLite en nombre, tipo y contenido
Búsqueda semántica	No disponible	KNN con embeddings ONNX (94+ idiomas)
Búsqueda híbrida	No disponible	KNN + FTS5 vía RRF
Query routing	No disponible	Routing dinámico de 3 estrategias (COSINE_HEAVY/LIMBIC_HEAVY/HYBRID_BALANCED)
Scoring límbico	No disponible	Saliencia + decay temporal + co-ocurrencia con decay temporal
Entity splitting	No disponible	Splitting automático basado en TF-IDF con workflow de aprobación
A/B testing	No disponible	Shadow mode con métricas NDCG@K
Auto-tuning	No disponible	Grid search para optimización de GAMMA/BETA_SAL
Concurrencia	Race conditions confirmadas	SQLite WAL con timeout de 5 segundos
Escala	Degrada linealmente con el tamaño del archivo	Consultas indexadas O(log n)
Corrupción de datos	Documentada en issues #1819, #2579 (Mayo 2025, aún abierto)	Transacciones ACID con auto-rollback

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 (313 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 (opcional)

uv run python scripts/download_model.py

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

Archivo	Propósito
model.onnx	Modelo exportado a ONNX para inferencia en CPU
tokenizer.json	Tokenizer rápido de HuggingFace (Rust)
tokenizer_config.json	Configuración del tokenizer
special_tokens_map.json	Mapeo de tokens especiales

Consejo

La descarga del modelo es opcional. El servidor arranca y ejecuta las 19 tools sin él. Solo search_semantic y find_duplicate_observations 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).

Nota

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"]
    }
  }
}

Precaución

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 TF-IDF 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.

Consejo

Para el workflow completo de entity splitting y los detalles de extracción de tópicos con TF-IDF, 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:

Funcionalidad	Sin modelo	Con modelo
create_entities	✅ Funciona	✅ Funciona + genera embedding
create_relations	✅ Funciona	✅ Funciona
add_observations	✅ Funciona	✅ Funciona + regenera embedding
delete_entities	✅ Funciona	✅ Funciona + elimina embedding
delete_observations	✅ Funciona	✅ Funciona + regenera embedding
delete_relations	✅ Funciona	✅ Funciona
search_nodes	✅ Funciona	✅ Funciona
open_nodes	✅ Funciona	✅ Funciona
migrate	✅ Funciona	✅ Funciona + genera embeddings
search_semantic	❌ Error	✅ Funciona
find_duplicate_observations	❌ Error	✅ Funciona
consolidation_report	✅ Funciona	✅ Funciona
end_relation	✅ Funciona	✅ Funciona
add_reflection	✅ Funciona	✅ Funciona + genera embedding
search_reflections	❌ Error	✅ Funciona

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