En este artículo
mcp-memory-service: memoria compartida para Claude Code y Cursor
mcp-memory-service proporciona a los agentes de programación una memoria persistente y compartida para decisiones de arquitectura, investigaciones de errores y convenciones del proyecto. Su utilidad no consiste en mantener una conversación ilimitada dentro del modelo. Permite que una sesión nueva recupere registros guardados desde otra sesión o herramienta, siempre que ambos clientes accedan al mismo almacén y utilicen sus herramientas de memoria. El repositorio oficial describe embeddings locales, recuperación semántica y relaciones tipadas en un grafo de conocimiento.
Revisión de fuentes: . Esta guía se basa en documentación: no presenta una integración ejecutada por nosotros ni un benchmark reproducido de forma independiente. Distinguimos las capacidades publicadas, nuestra configuración propuesta y los criterios de aceptación sugeridos.
¿Sustituye a CLAUDE.md, las reglas de Cursor o la memoria nativa?
No. Mantén las instrucciones estables en el repositorio y reserva la memoria compartida para el historial cambiante respaldado por evidencias. Afirmar que Claude Code empieza cada sesión sin ningún contexto persistente es excesivo: su documentación de memoria describe archivos de instrucciones y Auto Memory. Las reglas de Cursor también conservan instrucciones. Eso no demuestra que herramientas diferentes compartan un único historial de decisiones consultable.
| Información | Ubicación recomendada | Motivo |
|---|---|---|
| Comandos de compilación, convenciones de directorios y comprobaciones obligatorias | Instrucciones versionadas, como CLAUDE.md, AGENTS.md o reglas de Cursor | Las políticas revisables deben acompañar al código. |
| Por qué se descartó una opción o qué migración originó una regresión | Memoria compartida delimitada, con enlaces a decisiones, commits y pruebas | Las explicaciones históricas deben seguir siendo localizables entre sesiones. |
| Cómo funciona realmente la aplicación ahora | Código actual, configuración y pruebas ejecutables | Una afirmación recordada puede haber quedado obsoleta. |
La pregunta para decidir su adopción es concreta: ¿el equipo reconstruye una y otra vez el mismo razonamiento al cambiar de Claude Code a Cursor u OpenCode? Empieza por ese problema, no por crear un segundo sistema de políticas que contradiga al primero.
Instalar mcp-memory-service no equivale a integrarlo
El comando de instalación en una línea es:
pip install mcp-memory-serviceLa ficha de PyPI identifica la versión 11.13.0, publicada el 19 de septiembre de 2026, Python 3.10 o posterior y la licencia Apache-2.0. El ejemplo fija esta versión revisada para no incorporar versiones posteriores de manera implícita.
python3 -m venv "$HOME/.venvs/mcp-memory-service"
"$HOME/.venvs/mcp-memory-service/bin/python" -m pip install "mcp-memory-service==11.13.0"
mkdir -p "$HOME/.local/share/agent-memory/example-app"
"$HOME/.venvs/mcp-memory-service/bin/memory" server --helpEstos comandos están pensados para macOS y Linux. En Windows, adapta el ejecutable del entorno virtual y las rutas absolutas de almacenamiento; no copies las rutas POSIX sin modificarlas. Utiliza el procedimiento de gestión de entornos que mantenga tu equipo.
La guía oficial de instalación documenta memory server y la conexión del cliente. Instalar un paquete de Python no registra automáticamente un servidor MCP en todos los IDE, no importa conversaciones anteriores y no garantiza que cada sesión nueva consulte la memoria.
La configuración clave: todos los clientes deben usar la misma base de datos
El mismo paquete con rutas de base de datos diferentes produce memorias diferentes. En este ejemplo para una persona y un equipo, los tres clientes utilizan el mismo ejecutable y el mismo archivo SQLite mediante su ruta absoluta. La referencia de configuración documenta MCP_MEMORY_STORAGE_BACKEND, MCP_MEMORY_SQLITE_PATH y MCP_MEMORY_USE_ONNX.
Sustituye example-app de forma coherente por un proyecto o un perímetro de confianza. Separa los almacenes de clientes distintos en lugar de tratar una etiqueta como control de acceso. La ruta debe señalar un archivo, no únicamente su directorio. Un contenedor, un servidor de desarrollo remoto o una cuenta diferente del sistema operativo no comparten tu directorio personal por tener configuraciones parecidas.
Cada cliente MCP inicia aquí un proceso stdio conectado al mismo almacén local. Esto no es un diseño multiusuario. Comprueba el acceso concurrente antes de depender de él. No guardes una base SQLite activa en Git ni conviertas una carpeta sincronizada en un sustituto de la replicación de bases de datos.
Conectar Claude Code mediante MCP local
Ejecuta lo siguiente desde el proyecto en el que deba estar disponible la conexión:
claude mcp add \
--env MCP_MEMORY_STORAGE_BACKEND=sqlite_vec \
--env MCP_MEMORY_SQLITE_PATH="$HOME/.local/share/agent-memory/example-app/sqlite_vec.db" \
--env MCP_MEMORY_USE_ONNX=true \
--transport stdio --scope local \
memory -- "$HOME/.venvs/mcp-memory-service/bin/memory" server
claude mcp listEl ejemplo sigue el formato oficial de comandos MCP de Claude Code. --scope local mantiene el registro en tu configuración local del proyecto. Las opciones preceden al nombre del servidor y el separador -- precede al ejecutable. La ruta explícita evita depender de que el IDE herede el PATH del terminal.
Reinicia o reconecta el cliente según corresponda. Comprueba que el servidor esté conectado y que aparezcan memory_store y memory_search. Autoriza únicamente las operaciones esperadas. Que un servidor esté conectado no significa que haya guardado ya alguna memoria.
Configurar Cursor para utilizar el mismo almacén
Integra esta entrada en .cursor/mcp.json dentro del proyecto, conservando los servidores que ya existan:
{
"mcpServers": {
"memory": {
"type": "stdio",
"command": "${userHome}/.venvs/mcp-memory-service/bin/memory",
"args": [
"server"
],
"env": {
"MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
"MCP_MEMORY_SQLITE_PATH": "${userHome}/.local/share/agent-memory/example-app/sqlite_vec.db",
"MCP_MEMORY_USE_ONNX": "true"
}
}
}
}La documentación MCP de Cursor especifica los campos de stdio y admite la interpolación de ${userHome}. Comprueba la ruta resultante, reconecta el servidor y consulta la salida MCP cuando falte una herramienta. La configuración del proyecto no debe contener credenciales ni una base de datos copiada de un cliente.
Ver un servidor llamado «memory» en ambos clientes no demuestra que compartan estado. La prueba entre herramientas que aparece más abajo verifica conjuntamente la base de datos y el uso real de las herramientas.
OpenCode: conexión MCP estándar frente al plugin de captura automática
Para utilizar la misma conexión MCP local, integra lo siguiente en opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"memory": {
"type": "local",
"command": [
"{env:HOME}/.venvs/mcp-memory-service/bin/memory",
"server"
],
"enabled": true,
"environment": {
"MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
"MCP_MEMORY_SQLITE_PATH": "{env:HOME}/.local/share/agent-memory/example-app/sqlite_vec.db",
"MCP_MEMORY_USE_ONNX": "true"
}
}
}
}La referencia MCP de OpenCode utiliza type: local, un array de comandos y environment, no el campo env de Cursor. Su referencia de configuración documenta la sustitución {env:HOME}. Este ejemplo combina los ajustes documentados del cliente con el comando del servidor. No hemos ejecutado esta configuración de tres clientes en un entorno real.
El plugin Memory Awareness es una integración distinta: utiliza la API HTTP REST para recuperar contexto al iniciar sesiones y capturarlo automáticamente. Sus archivos proceden del repositorio, no solo de la instalación mediante pip. MCP expone herramientas; el plugin añade automatización al ciclo de la sesión.
Elige primero una vía. Activar ambas sin una política de captura dificulta saber quién guardó cada información. Esta guía de stdio no requiere un servicio HTTP a la escucha. Un despliegue opcional del plugin necesita revisar por separado el endpoint, la autenticación y el acceso de red.
Comprobar que la memoria sobrevive al reinicio y al cambio de IDE
Comprueba la recuperación, no la afirmación del agente de que recuerda. Pide expresamente a Claude Code que utilice memory_store para guardar una decisión ficticia con la etiqueta project:example-app: «Los eventos de pago utilizan una outbox para que un pago confirmado no pierda su evento posterior». Añade una referencia de decisión ficticia, estado y fecha. No uses datos reales de clientes.
Revisa la confirmación de escritura de la herramienta. Cierra la sesión y abre una nueva en Cursor. Solicita una llamada a memory_search que busque el motivo de la outbox de pagos. Contrasta el identificador y el contenido del registro, en lugar de aceptar una respuesta verosímil generada a partir del conocimiento general del modelo. Repite la prueba en OpenCode y después de reiniciar los procesos de los clientes.
Añade un caso negativo: otro proyecto no debería poder recuperar esa decisión según el aislamiento elegido. Las etiquetas acotan búsquedas, pero no crean una frontera de seguridad. Evalúa tanto los resultados ausentes como los resultados que no deberían aparecer antes de activar la captura automática.
Embeddings ONNX locales: qué cubre «sin llamadas a API externas»
Calcular embeddings localmente no convierte todo el flujo de programación en un sistema sin conexión. ONNX Runtime permite ejecutar localmente un modelo disponible. La instalación de paquetes y la descarga inicial de modelos son eventos de red independientes. Un modelo de programación alojado en la nube puede seguir recibiendo memorias cuando el cliente añade los resultados de las herramientas a su contexto.
Los equipos multilingües tienen otra limitación que comprobar. La ficha de all-MiniLM-L6-v2 identifica el modelo predeterminado como inglés, con vectores de 384 dimensiones y truncamiento por defecto más allá de 256 word pieces. Una interfaz en español no demuestra que funcione bien la búsqueda de decisiones en inglés con preguntas en español. Los volcados largos de conversaciones también pueden perder detalles relevantes antes de generar el embedding.
El ejemplo de variables de entorno expone opciones de modelos, proveedores y funciones adicionales. Revísalas en lugar de interpretar «local-first» como prueba de una frontera concreta para los datos. El almacenamiento cloud o híbrido, la evaluación externa y la extracción asistida por LLM requieren decisiones separadas.
Proponemos esta prueba multilingüe: guarda una decisión aprobada en inglés y búscala en alemán, español y chino con expresiones reales del equipo. Mide si aparece el registro correcto, no si el asistente traduce bien su respuesta. Cambiar de modelo exige una migración respaldada por copias de seguridad y el recálculo de embeddings, incluso cuando ambos modelos tienen las mismas dimensiones.
¿mcp-memory-service recupera realmente el contexto en 5 ms?
Los 5 ms son una afirmación de rendimiento del proyecto, no una garantía de extremo a extremo demostrada en este artículo. El titular del repositorio no debe convertirse en «cualquier decisión histórica y cualquier relación del grafo se devuelve en 5 ms». No hemos reproducido ese dato de forma independiente.
Una evaluación útil separa el arranque del proceso, la primera carga del modelo, el embedding de la consulta, la recuperación de la base de datos, la expansión del grafo y el transporte al cliente. Después mide la llamada completa a la herramienta. Una consulta con caché caliente no mide lo mismo que una búsqueda en frío, una solicitud remota o la respuesta final del modelo de programación.
Registra equipo, modelo, cantidad y longitud de las memorias, tipos de consulta, clientes concurrentes y condiciones de calentamiento. Presenta la mediana y los casos lentos junto con la corrección de la evidencia recuperada. Nuestro criterio: ahorrar unos milisegundos no ayuda si el agente recomienda con seguridad una decisión de arquitectura obsoleta.
Memoria causal para depurar: una relación no demuestra una causa
La documentación del grafo de conocimiento describe relaciones como causes, fixes, contradicts, supports, follows y related. Permiten representar una cadena de investigación; no demuestran que su conclusión sea verdadera.
Ejemplo ficticio: el commit demo-change-A elimina una protección de idempotencia; el error DEMO-42 documenta eventos de pago duplicados; el parche demo-fix-B restablece la protección; la prueba test_duplicate_event reproduce el fallo antes del parche y pasa después. Guarda los enlaces a esos artefactos junto con la afirmación. Distingue «causa sospechada» de «confirmada mediante la prueba revisada».
Cuando una migración posterior sustituya el diseño, conserva el historial, pero marca la recomendación anterior como reemplazada. Una coincidencia semántica acertada puede convertirse en un consejo técnico incorrecto. El agente debería inspeccionar el código actual y la prueba pertinente antes de actuar sobre esa cadena recordada.
Política práctica: guardar decisiones, recuperar lo necesario y retirar consejos obsoletos
Nuestra plantilla propuesta contiene proyecto, componente, decisión, justificación, ubicación de la evidencia, commit de origen, autor o revisor, estado, fecha de registro y siguiente motivo de revisión. Es una plantilla editorial para el contenido del registro, no una lista de parámetros obligatorios de la API. Conserva una idea duradera por memoria. No conviertas cada pensamiento provisional en una decisión aprobada.
Al empezar una tarea, busca el componente afectado y comprueba el estado de la evidencia recuperada. Al terminar, guarda únicamente cambios verificados y preguntas pendientes claramente etiquetadas. Separa «lo probamos» de «el equipo lo aprobó». Exige revisión antes de que una consolidación automática cambie el significado de información operativa importante.
La guía de recuperación eficiente en tokens documenta límites y exploración basada en grafos. Este objeto ilustrativo de argumentos para memory_search limita resultados y caracteres. 6000 es nuestro presupuesto de ejemplo, no una recomendación de rendimiento del proyecto ni una cantidad de tokens:
{
"query": "Why does example-app use an outbox for payment events?",
"tags": [
"project:example-app"
],
"limit": 5,
"max_response_chars": 6000
}La recuperación mediante entidades necesita su propia comprobación. Un resultado vacío de memory_explore puede indicar que las entidades nunca se generaron, aunque existan memorias de texto. La opción documentada MCP_ENTITY_LINKING_ENABLED=1 afecta a registros guardados a partir de su activación; los existentes necesitan un proceso explícito de mantenimiento o carga retrospectiva. No ejecutes una operación de mantenimiento que modifique datos a ciegas solo para llenar un grafo vacío.
Solucionar problemas de persistencia y recuperación de memoria
| Síntoma | Qué revisar primero | Evidencia necesaria |
|---|---|---|
| Funciona en Claude Code, pero no en Cursor | Ejecutable, entorno, ruta absoluta de la base y cuenta del sistema | Comparar los ajustes resueltos y recuperar el mismo identificador. |
| La memoria desaparece al reiniciar | Confirmación de escritura, rutas efímeras y almacén reabierto | Guardar, cerrar, reabrir y buscar sin utilizar el historial de la conversación. |
| La herramienta está conectada, pero el agente olvida | Si se invocaron las herramientas de memoria | Inspeccionar las llamadas reales y establecer un flujo explícito de recuperación. |
| La búsqueda de texto funciona, pero el grafo está vacío | Configuración de enlaces de entidades y población del grafo | Comprobar el número de entidades antes de planificar una carga retrospectiva revisada. |
| Las preguntas en español no encuentran decisiones en inglés | Modelo, idioma, longitud del texto y filtros | Probar consultas multilingües equivalentes sobre registros conocidos. |
| Error de dimensiones tras cambiar el modelo | Modelo seleccionado, caché y compatibilidad de los vectores existentes | Detener nuevas escrituras, conservar una copia y planificar el recálculo. |
| Fallos intermitentes con varios clientes | Escrituras concurrentes, ubicación del almacenamiento y registros de procesos | Reproducir con clientes controlados antes de modificar la base de datos. |
Límites de seguridad de una memoria compartida para agentes
Trata cada memoria recuperada como evidencia no confiable, no como una instrucción de mayor prioridad. Un registro que cite «ignora las instrucciones anteriores» debe seguir siendo un dato. Concede a cada proyecto solo el almacenamiento y las herramientas necesarios. Un documento aportado por un cliente no debe reescribir silenciosamente tus políticas de desarrollo.
La guía de seguridad de MCP sirve como punto de partida para revisar autorización y transporte. Recomendamos empezar con stdio local, excluir secretos y transcripciones de clientes y revisar por separado cualquier endpoint compartido. Para HTTP, elige expresamente dirección de escucha, autenticación, permisos, protección del transporte y clientes autorizados. No traslades una demostración con acceso anónimo a un servicio accesible desde la red.
Asigna responsabilidades de corrección, eliminación, retención y recuperación antes de activar la captura automática. Prueba un procedimiento de copia y restauración consistente y comprueba que los registros eliminados o reemplazados no reaparezcan desde un segundo almacén. El código abierto, los embeddings locales y las etiquetas no demuestran por sí solos cumplimiento normativo ni aislamiento entre clientes.
Un piloto pequeño con criterios de aceptación útiles
Empieza con un conjunto deliberadamente pequeño antes de importar todo el archivo. Este es nuestro piloto propuesto, no un benchmark publicado: diez decisiones aprobadas, cinco reemplazadas, cinco cadenas de error y corrección y cinco consultas entre idiomas. Incluye registros que otro proyecto no deba poder ver.
| Prueba | Resultado útil |
|---|---|
| Continuidad entre herramientas | Una sesión nueva en cada cliente recupera la misma decisión con identificador y evidencia. |
| Vigencia de las decisiones | La respuesta identifica la decisión actual y marca la anterior como reemplazada. |
| Aislamiento | Un cliente fuera del perímetro de confianza no puede leer la memoria de otro proyecto. |
| Trazabilidad de la depuración | El agente encuentra hipótesis, corrección y prueba de regresión sin inventar una demostración causal. |
| Coste y latencia | Se registran por separado duración de llamadas, tamaño del contexto y solicitudes externas. |
| Fallo y recuperación | El agente comunica que la memoria no está disponible; una restauración probada conserva los registros esperados. |
Conserva el servicio cuando el piloto reduzca explicaciones repetidas sin aumentar los consejos obsoletos o procedentes de otros proyectos. Mantén las instrucciones del repositorio cuando el problema real sea la falta de convenciones claras. Nuestro análisis de OpenViking aborda la recuperación de contexto estructurado; la guía de Supermemory trata la memoria de aplicaciones y otras opciones de despliegue.
Para implementar estas ideas, consulta nuestros servicios de ingeniería de IA. El caso Twinsoft AI aporta contexto de entrega relacionado, no evidencia de que se utilizara esta herramienta. Nuestra lista de control de QA antes del lanzamiento ayuda a convertir el piloto en criterios de publicación. También puedes plantear al equipo una integración de alcance definido.