How do I install MCP Memory?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does MCP Memory need an API key?

The publisher lists these environment variables: DB_PATH.

What transport does MCP Memory use?

MCP Memory runs locally over stdio.

When was MCP Memory last checked?

Last checked 2026-11-09. Local persistent memory for AI agents: SQLite + FTS5 (BM25) lexical search, zero external infra.

MCP Memory MCP server

English · Español

MCP Memory — Memoria local para agentes IA vía MCP

Lleva la memoria de tu agente IA a cualquier máquina. Servidor MCP open source que da memoria persistente con búsqueda léxica (BM25) a Claude Desktop, Claude Code, OpenCode, Cursor, Continue y cualquier cliente compatible con Model Context Protocol. SQLite + FTS5, cero infra externa, 100% en tu hardware.

Tags: `mcp-server` · `ai-agents` · `sqlite` · `fts5` · `bm25` · `claude-code` · `cursor` · `opencode` · `lexical-search` · `agent-memory` · `local-first` · `self-hosted`

💡 Por qué existe

Los agentes IA olvidan todo entre conversaciones. Las soluciones existentes son cloud-only, multi-tenant pesado, o están atadas a un único cliente. MCP Memory resuelve esto con tres ideas simples:

Tu memoria, tu máquina. Un solo archivo SQLite local. Cero datos en la nube, cero servicios externos que levantar.
Conectas una vez, funciona en todos lados. Es un servidor MCP estándar — cualquier cliente que hable MCP lo usa sin custom code.
Cero overhead. pip install y tienes 9 tools listas para tu agente en segundos — sin Docker, sin modelos que descargar.

⚡ Quickstart

Hay dos formas de correrlo. Elige una:

Modo	Cuándo	Cómo arranca
stdio	Claude Desktop, Claude Code, Cursor… (lo más simple)	El cliente lanza el proceso él solo. No hay server de fondo ni puerto.
HTTP	Varios clientes contra un mismo server, Docker, clientes web	Lo arrancas tú y queda escuchando en `http://localhost:8765/mcp`.

Opción A — stdio (sin dejar nada corriendo)

Con uv 0.13.4 o superior instalado no hace falta clonar (las versiones anteriores confían en una CA comprometida, ver SECURITY.md): el cliente descarga y lanza el server en cada sesión. Para Claude Code:

claude mcp add -s user mcp-memory -- uvx --from "git+https://github.com/GermaniU/mcp-memory#subdirectory=server" mcp-memory --stdio

Para Claude Desktop, Cursor y el resto, la config JSON está en docs/CLIENTS.md. Todos los procesos comparten el mismo archivo SQLite (DB_PATH), así que la memoria es la misma en todos tus clientes.

Opción B — HTTP (server de fondo)

git clone https://github.com/GermaniU/mcp-memory.git
cd mcp-memory/server
pip install -e .
mcp-memory

Alternativa sin instalar en tu entorno global: uvx --from . mcp-memory (corriendo dentro de server/).

No hay pre-requisitos: nada que levantar, nada que descargar. Al arrancar, el server crea el archivo SQLite (DB_PATH, default ~/.agent-memory/memory.db) y su schema (tabla memories + índice FTS5) si no existen.

Endpoint MCP: http://localhost:8765/mcp. Pégalo en la config de tu cliente (ver docs/CLIENTS.md — Claude Code, OpenCode, Cursor, Continue).

mcp-memory --stdio (o MCP_TRANSPORT=stdio) arranca el modo stdio con la instalación local.

🔍 Diagnóstico y Chequeo de Salud

Verifica que tu Python tiene FTS5 compilado y que DB_PATH es accesible al instante:

mcp-memory check

mcp-memory --help lista los comandos y variables de entorno; mcp-memory --version imprime la versión instalada.

🛠 Tools MCP expuestas

Tool	Tipo	Para qué
`memory_save`	✏️ escritura	Guardar texto + tags + metadata.
`memory_search`	👁 lectura	Búsqueda léxica (BM25 vía SQLite FTS5) con filtro por namespace.
`memory_update`	⚠️ destructiva	Cambiar contenido/tags/metadata por id. Re-sincroniza el índice FTS5 si cambia el contenido. Rechaza `content` vacío.
`memory_delete`	⚠️ destructiva	Borrar por id.
`memory_list`	👁 lectura	Paginado por namespace.
`memory_recent`	👁 lectura	Las últimas N por `updated_at`.
`memory_stats`	👁 lectura	Conteo, namespaces, oldest/newest.
`memory_export`	👁 lectura	Exporta todas las memorias (o las de un namespace) como JSONL. Devuelve `count` y el string `jsonl`.
`memory_import`	✏️ escritura	Importa un string JSONL producido por `memory_export`. Salta colisiones de id silenciosamente. Acepta `namespace_override` opcional.

El Tipo se publica como anotaciones MCP (readOnlyHint, destructiveHint): los clientes que las soportan pueden auto-aprobar las lecturas y pedir confirmación antes de modificar o borrar. Al conectarse, el server también envía instructions al agente (cuándo buscar, cuándo guardar, cómo formular queries léxicas).

Schemas + ejemplos de invocación en docs/CLIENTS.md.

🎯 Alcance actual

MCP Memory es deliberadamente pequeño. Hace una cosa bien: memoria léxica de texto plano. No es un sistema de RAG completo, no es un knowledge base, no es un grafo.

Lo que SÍ hace

✅ Almacena y recupera texto puro en SQLite.
✅ Búsqueda léxica (BM25/FTS5) con filtro por namespace.
✅ Tags + metadata libres en cada entrada.
✅ 9 tools MCP estándar para cualquier agente compatible.
✅ Persistencia en disco (un único archivo .db), backup = copiar el archivo.

Lo que NO hace (todavía)

❌ No hace búsqueda semántica. Es léxica (BM25): coincide términos, no significado — sinónimos o paráfrasis sin overlap de vocabulario no matchean.
❌ No soporta imágenes ni gráficas. Solo texto.
❌ No soporta PDFs ni archivos binarios — extrae el texto antes de guardarlo.
❌ No es multi-tenant. Una persona, una máquina, una memoria (con namespaces para separar contextos).
❌ No tiene UI propia. Lo administras desde el agente o por curl/MCP.
❌ No sincroniza entre máquinas. Backup manual (copiar el archivo .db) si quieres mover datos.
❌ No tiene auth. En modo HTTP solo escucha en localhost y con CORS cerrado (en stdio no abre ningún puerto). Si lo expones a internet, pon un proxy con auth. Ver SECURITY.md.

Si necesitas algo de la lista NO, abre un issue con caso de uso real (no especulativo) — vamos por demanda, no por especulación.

🧭 ¿Y el `server-memory` oficial?

El MCP oficial incluye server-memory (@modelcontextprotocol/server-memory). No compiten por el mismo trabajo: ese es un grafo de conocimiento; este es memoria léxica de texto. Elige según lo que necesites recordar.

	MCP Memory (este)	`server-memory` (oficial)
Modelo de datos	Entradas de texto planas (`content` + `tags` + `metadata`)	Grafo: entidades + relaciones + observaciones
Almacenamiento	Un archivo SQLite con índice FTS5	Un archivo JSONL con el grafo completo
Búsqueda	BM25 con ranking (FTS5), filtrada por `namespace`	`search_nodes`: match por substring en nombre/tipo/observaciones, sin ranking
Namespaces	✅ un pool por proyecto o agente	❌
Tags / metadata libres	✅ por entrada	❌
Export / import	✅ `memory_export` / `memory_import` (JSONL)	❌ hay que leer y escribir el archivo
Transporte	stdio + Streamable HTTP	stdio
Coste de leer	Ranking en SQLite: traes solo los hits	`read_graph` devuelve el grafo entero

En una frase:

Si tu problema son hechos con relaciones («Ana trabaja_en Acme», «padre_de…»), usa el grafo oficial.
Si tu problema es recordar notas y decisiones y encontrarlas por palabra clave, separadas por proyecto y con export/import, usa MCP Memory.

No es «mejor que»: es otra herramienta para otro trabajo — y la que no te obliga a cargar el grafo completo en cada consulta.

🔌 Conectar tu cliente

Configuración lista para copiar en docs/CLIENTS.md (stdio y HTTP):

🟫 Claude Desktop — claude_desktop_config.json con "command": "uvx" (stdio).
🟦 Claude Code — claude mcp add -s user mcp-memory -- uvx --from "git+https://github.com/GermaniU/mcp-memory#subdirectory=server" mcp-memory --stdio, o por HTTP claude mcp add -s user -t http mcp-memory http://localhost:8765/mcp (las tools aparecen en sesiones nuevas).
🟧 Cursor — Settings → MCP Servers → Add new MCP Server.
🟩 Continue (VS Code / JetBrains) — ~/.continue/config.json.
🟪 OpenCode — ~/.config/opencode/config.json.

Snippets JSON listos en examples/.

🧪 Smoke test con curl

Para validar el stack sin necesidad de un cliente MCP:

SESSION=$(curl -sS -D - -o /dev/null -X POST http://localhost:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.1"}}}' \
  | tr -d '\r' | awk '/^mcp-session-id:/{print $2}')

curl -sS -X POST http://localhost:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -sS -X POST http://localhost:8765/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_save","arguments":{"content":"funciona end-to-end","namespace":"smoke","tags":["ok"]}}}'

🧱 Arquitectura (vertical slice)

┌─ tu agente (Claude Code / OpenCode / Cursor / …) ─┐
│           │ MCP streamable HTTP                    │
│           ▼                                        │
│    localhost:8765/mcp                              │
└────────────┬───────────────────────────────────────┘
             │
   ┌─────────▼────────┐
   │   mcp-memory     │
   │   (Python+MCP)   │
   └─────────┬────────┘
             │
             ▼
   ┌──────────────────────────┐
   │  SQLite (archivo local)  │  ← memories + memories_fts (FTS5/BM25)
   └──────────────────────────┘

Cada tool MCP vive en su propia carpeta (server/src/mcp_memory/tools/<tool>/handler.py). Añadir una tool nueva = añadir una carpeta + un decorator en server.py. Cero acoplamiento.

Detalle técnico en docs/ARCHITECTURE.md.

🤝 Contribuye

MCP Memory es un regalo a la comunidad — MIT, sin trampas. PRs, issues y forks bienvenidos.

Reglas (resumen):

Clean Code · SOLID · KISS · YAGNI · Vertical slice · Tests primero. No se aceptan PRs sin tests para la lógica nueva.
Identifiers en inglés, comentarios y commits en español. Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:).
Una tool nueva = una carpeta nueva. No tocar slices existentes salvo bug.
DIP: dependencias externas detrás de un Protocol para que el test no necesite servicios externos.
Sin abstracciones especulativas. Si solo hay 1 implementación, no hay interfaz.
Documenta el WHY, no el WHAT. El nombre de la función ya cuenta el qué.

Detalle completo + workflow paso a paso en CONTRIBUTING.md.

# Setup local de desarrollo
cd server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/unit -q          # 81 unit tests, ~1s
pytest tests/integration -q   # 17 tests E2E reales contra SQLite/FTS5 (incluye stdio), sin servicios externos
ruff check src tests scripts

🩹 Troubleshooting (errores reales que ya pisé)

no such module: fts5 al arrancar

Tu Python no tiene FTS5 compilado en su módulo sqlite3 (típico en algunos builds de Linux). Usa el Python de Homebrew/python.org (macOS/Windows) o instala libsqlite3-dev antes de compilar Python (Linux, pyenv/asdf). Verifica con mcp-memory check.

Connection reset by peer al hacer curl http://localhost:8765/mcp

Falta el header Accept: application/json, text/event-stream. Sin él, FastMCP cierra la conexión.

memory_search devuelve vacío

¿Mismo namespace? Si guardaste sin namespace, busca con default. Recordá que la búsqueda es léxica (BM25): la query necesita compartir términos con el contenido guardado, no solo el significado.

mcp-memory no arranca / error de permisos en DB_PATH

El directorio padre de DB_PATH no es escribible. mcp-memory check valida esto explícitamente antes de fallar en caliente.

Quiero mover mi memoria a otra máquina

Copia el archivo de DB_PATH (default ~/.agent-memory/memory.db) — es autocontenido, no hay estado adicional que migrar.

📚 Documentación

docs/INSTALL.md — instalación detallada, variables, troubleshooting extendido.
docs/CLIENTS.md — config para Claude Code, OpenCode, Cursor, Continue.
docs/ARCHITECTURE.md — decisiones técnicas y por qué.
SECURITY.md — modelo de amenazas y cómo reportar vulnerabilidades.
CONTRIBUTING.md — disciplinas, workflow, cómo añadir una tool.
CHANGELOG.md — historial de cambios.

📄 Licencia

MIT — úsalo, fórkalo, regálale a otra gente más memoria local.

Hecho por @GermaniU con disciplinas de software profesional. Si te ha servido, una ⭐ ayuda a que más gente lo encuentre. Si te ha roto algo, abre un issue y lo arreglamos.

MCP Memory

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install MCP Memory?

Does MCP Memory need an API key?

What transport does MCP Memory use?

When was MCP Memory last checked?

Documentation

MCP Memory — Memoria local para agentes IA vía MCP

Tags: `mcp-server` · `ai-agents` · `sqlite` · `fts5` · `bm25` · `claude-code` · `cursor` · `opencode` · `lexical-search` · `agent-memory` · `local-first` · `self-hosted`

💡 Por qué existe

⚡ Quickstart

Opción A — stdio (sin dejar nada corriendo)

Opción B — HTTP (server de fondo)

🔍 Diagnóstico y Chequeo de Salud

🛠 Tools MCP expuestas

🎯 Alcance actual

Lo que SÍ hace

Lo que NO hace (todavía)

🧭 ¿Y el `server-memory` oficial?

🔌 Conectar tu cliente

🧪 Smoke test con curl

🧱 Arquitectura (vertical slice)

🤝 Contribuye

🩹 Troubleshooting (errores reales que ya pisé)

📚 Documentación

📄 Licencia

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install MCP Memory?

Does MCP Memory need an API key?

What transport does MCP Memory use?

When was MCP Memory last checked?

Documentation

MCP Memory — Memoria local para agentes IA vía MCP

Tags: mcp-server · ai-agents · sqlite · fts5 · bm25 · claude-code · cursor · opencode · lexical-search · agent-memory · local-first · self-hosted

💡 Por qué existe

⚡ Quickstart

Opción A — stdio (sin dejar nada corriendo)

Opción B — HTTP (server de fondo)

🔍 Diagnóstico y Chequeo de Salud

🛠 Tools MCP expuestas

🎯 Alcance actual

Lo que SÍ hace

Lo que NO hace (todavía)

🧭 ¿Y el server-memory oficial?

🔌 Conectar tu cliente

🧪 Smoke test con curl

🧱 Arquitectura (vertical slice)

🤝 Contribuye

🩹 Troubleshooting (errores reales que ya pisé)

📚 Documentación

📄 Licencia

Tags: `mcp-server` · `ai-agents` · `sqlite` · `fts5` · `bm25` · `claude-code` · `cursor` · `opencode` · `lexical-search` · `agent-memory` · `local-first` · `self-hosted`

🧭 ¿Y el `server-memory` oficial?