memory-mcp-1file

🏠 🍎 🪟 🐧 - Un servidor de memoria autocontenido con arquitectura de un solo binario (BD y modelos integrados, sin dependencias). Proporciona memoria semántica y basada en grafos persistente para agentes de IA.

GitHub

Prueba este MCPPatrocinado

Documentación

🧠 Servidor MCP de Memoria

Un servidor de Protocolo de Contexto de Modelo (MCP) de alto rendimiento, 100% Rust, que proporciona memoria persistente, semántica y basada en grafos para agentes de IA.

Funciona perfectamente con:

Claude Desktop
Claude Code (CLI)
Gemini CLI
OpenAI Codex (CLI / IDE)
Cursor
OpenCode
Cline / Roo Code
Cualquier otro cliente compatible con MCP.

🏆 La Ventaja "Todo-en-Uno"

A diferencia de otras soluciones de memoria que requieren una pila compleja (Python + Base de Datos Vectorial + Base de Datos de Grafos), este proyecto es un único ejecutable autocontenido.

✅ Sin Base de Datos Externa (SurrealDB está integrado)
✅ Sin Claves API, Sin Nube, Sin Python — Todo se ejecuta 100% localmente mediante un runtime ONNX integrado. El modelo de embeddings está incluido en el binario y se ejecuta en CPU. Nada sale de tu máquina.
✅ Configuración Cero (Solo ejecuta un contenedor Docker o binario)

Combina:

Búsqueda Vectorial (FastEmbed) para similitud semántica.
Grafo de Conocimiento (PetGraph) para relaciones entre entidades.
Indexación de Código con grafo de símbolos (llamadas, extensiones, implementaciones) para una comprensión profunda del código base.
Recuperación Híbrida (Fusión de Rango Recíproco) para los mejores resultados.

🏗️ Arquitectura

graph TD
    User[AI Agent / IDE]
    
    subgraph "Memory MCP Server"
        MS[MCP Server]
        
        subgraph "Core Engines"
            ES[Embedding Service]
            GS[Graph Service]
            CS[Codebase Service]
        end
        
        MS -- "Store / Search" --> ES
        MS -- "Relate Entities" --> GS
        MS -- "Index" --> CS
        
        ES -- "Vectorize Text" --> SDB[(SurrealDB Embedded)]
        GS -- "Knowledge Graph" --> SDB
        CS -- "AST Chunks" --> SDB
    end

    User -- "MCP Protocol" --> MS

Haz clic aquí para la Documentación Detallada de Arquitectura

Protocolo MCP y Transportes

El servidor utiliza rmcp 3.2 y soporta ambos ciclos de vida del protocolo:

Solicitudes sin estado MCP 2026-07-28: los clientes pueden comenzar con server/discover; cada solicitud lleva la versión del protocolo y los metadatos del cliente en _meta. El proceso no almacena sesión MCP, Mcp-Session-Id, ni currentProject mutable.
Compatibilidad MCP 2025-11-25: los clientes que utilizan el ciclo de vida heredado initialize/initialized siguen siendo compatibles.

Este binario expone MCP a través de stdio. Ejecuta un proceso por espacio de trabajo local y monta ese espacio de trabajo en /project cuando uses Docker. HTTP Streamable no está habilitado ni anunciado en esta versión, por lo que no introduce gestión de sesiones HTTP ni superficie de autenticación de servidor compartido. La indexación de código recibe una ruta explícita a través de index_project; la búsqueda de código se puede limitar con project_id cuando un proceso contiene múltiples proyectos indexados. La negociación de raíces no se utiliza.

🤖 Integración con Agentes (Prompt del Sistema)

La memoria es inútil si tu agente no la consulta. Para obtener el efecto de "Memoria a Largo Plazo", debes instruir a tu agente para que siga un protocolo estricto.

Proporcionamos un Protocolo de Memoria (AGENTS.md) probado en batalla que puedes adaptar.

🛡️ Flujos de Trabajo Principales (Protección del Contexto)

El protocolo implementa flujos específicos para manejar la Compactación de la Ventana de Contexto y los Reinicios de Sesión:

🚀 Inicio de Sesión: El agente debe buscar TASK: in_progress inmediatamente. Esto restaura el contexto completo de lo que estaba sucediendo antes de que terminara la última sesión o se compactara el contexto.
⏳ Auto-Continuación: Un mecanismo de seguridad donde el agente presenta la tarea encontrada al usuario y espera (o continúa automáticamente), asegurando que no alucine una nueva tarea.
🔄 Triple Sincronización: Actualiza Memoria, Lista de Tareas y Archivos simultáneamente. Si uno falla (por ejemplo, se pierde el contexto), los otros sirven como respaldo.
🧱 Sistema de Prefijos: Todas las memorias usan prefijos (TASK:, DECISION:, RESEARCH:) para que la búsqueda semántica pueda apuntar con precisión al tipo correcto de información, reduciendo el ruido.

Estos flujos de trabajo transforman al agente de un "chatbot sin estado" a un "trabajador con estado" que sobrevive a reinicios y limpiezas de contexto.

Fragmento de Prompt de Sistema Recomendado

En lugar de dispersar instrucciones en archivos específicos del IDE (como .cursorrules), establece AGENTS.md como la Fuente Única de Verdad.

Instruye a tu agente (en su prompt de sistema base) para que:

Lea AGENTS.md al inicio de cada sesión.
Siga los protocolos definidos en él.

Aquí tienes un prompt de referencia mínimo para iniciar este comportamiento:

# 🧠 Memory & Protocol
You have access to a persistent memory server and a protocol definition file.

1.  **Protocol Adherence**:
    - READ `AGENTS.md` immediately upon starting.
    - Strictly follow the "Session Startup" and "Sync" protocols defined there.

2.  **Context Restoration**:
    - Run `search_text("TASK: in_progress")` to restore context.
    - Do NOT ask the user "what should I do?" if a task is already in progress.

¿Por qué es importante?

Sin este protocolo, el agente pierde el contexto después de la compactación o los reinicios de sesión. Con este protocolo, mantiene el contexto completo de la tarea actual, asegurando que no se pierdan pasos ni detalles, incluso cuando se borra el historial del chat.

🔌 Configuración del Cliente

Configuración Universal con Docker (Cualquier IDE/CLI)

Para usar este servidor MCP con cualquier cliente (Claude Code, OpenCode, Cline, etc.), usa la siguiente estructura de comando Docker.

Requisitos Clave:

Volumen de Memoria: -v mcp-data:/data (Persiste tu grafo, embeddings y pesos del modelo en caché)
Volumen del Proyecto: -v $(pwd):/project:ro (Permite al servidor leer e indexar tu código)
Proceso Init: --init (Asegura que el servidor se apague limpiamente)

[!TIP] Un volumen persiste todo: El único montaje -v mcp-data:/data cubre tanto la base de datos SurrealDB como el modelo de embeddings de ~1.2 GB (almacenado en /data/models/). No hay necesidad de un volumen separado para /data/models — ya es un subdirectorio de /data y se conserva automáticamente. Sin un volumen con nombre, Docker crea un nuevo volumen anónimo en cada docker run, lo que provoca que el modelo se descargue nuevamente (~1.2 GB) cada vez.

Configuración JSON (Claude Desktop, etc.)

Añade esto a tu archivo de configuración (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "-i",
        "--rm",
        "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "/absolute/path/to/your/project:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

Nota: Reemplaza /absolute/path/to/your/project con la ruta real que deseas indexar. En algunos entornos (como extensiones de Cursor o VSCode), podrías usar variables como ${workspaceFolder}, pero las rutas absolutas son las más fiables para Docker.

Cursor (Instrucciones Específicas)

Ve a Configuración de Cursor > Funciones > Servidores MCP.
Haz clic en + Añadir Nuevo Servidor MCP.
Tipo: stdio
Nombre: memory

Comando:

docker run --init -i --rm --memory=3g -v mcp-data:/data -v "/Users/yourname/projects/current:/project:ro" ghcr.io/pomazanbohdan/memory-mcp-1file:latest

(Recuerda actualizar la ruta del proyecto al cambiar de espacio de trabajo si necesitas indexación de código)

OpenCode / CLI

docker run --init -i --rm --memory=3g \
  -v mcp-data:/data \
  -v $(pwd):/project:ro \
  ghcr.io/pomazanbohdan/memory-mcp-1file:latest

NPX / Bunx (Sin Docker requerido)

Puedes ejecutar el servidor directamente a través de npx o bunx. El paquete npm descarga automáticamente el binario precompilado correcto para tu plataforma.

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Claude Code (CLI)

claude mcp add memory -- npx -y memory-mcp-1file

Cursor

Ve a Configuración de Cursor > Funciones > Servidores MCP.
Haz clic en + Añadir Nuevo Servidor MCP.
Tipo: command
Nombre: memory
Comando: npx -y memory-mcp-1file

O añade a .cursor/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Windsurf / VS Code

Añade a tu configuración MCP:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Bun

{
  "mcpServers": {
    "memory": {
      "command": "bunx",
      "args": ["memory-mcp-1file"]
    }
  }
}

OpenAI Codex CLI (a nivel de proyecto)

Este repositorio incluye un .codex/config.toml de proyecto de confianza que inicia memory-mcp-1file@0.9.2 sobre STDIO local, almacena datos en .codex/data, y expone una lista de permitidos de 16 herramientas del proyecto. Las herramientas destructivas delete_memory, delete_project y reset_all_memory están intencionalmente excluidas de la configuración del proyecto. La indexación nativa de Codex está limitada al repositorio actual mediante MEMORY_MCP_ALLOWED_INDEX_ROOT.

La configuración de Codex a nivel de proyecto se carga solo después de que confíes explícitamente en el repositorio. En Windows, verifica el paquete de forma independiente primero:

npx -y memory-mcp-1file@0.9.2 -- --help

Luego ejecuta codex desde el repositorio y verifica el servidor con:

/mcp

codex mcp list
codex mcp get memory

La configuración required = true hace visible un fallo de inicio de Memory MCP en lugar de ejecutar silenciosamente el proyecto sin su flujo de trabajo de memoria. La lista de permitidos de herramientas controla qué herramientas MCP carga Codex; no es un sandbox de procesos. Confía en el repositorio y en el paquete npm antes de habilitar esta configuración.

Nota: A diferencia de Docker, npx/bunx ejecuta el binario localmente — ya tiene acceso a tu sistema de archivos, por lo que no se necesita montaje de directorios. Para personalizar la ruta de almacenamiento de datos, pasa --data-dir a través de args:
"args": ["-y", "memory-mcp-1file", "--", "--data-dir", "/path/to/data"]

Gemini CLI

Añade a tu ~/.gemini/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

O con Docker:

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "--init", "-i", "--rm", "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "${workspaceFolder}:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

✨ Características Clave

Memoria Semántica: Almacena texto con embeddings vectoriales (granite por defecto) para recuperación basada en "vibraciones".
Memoria de Grafo: Rastrea entidades (User, Project, Tech) y sus relaciones (uses, likes). Soporta recorrido basado en PageRank.
Inteligencia de Código: Indexa directorios de proyectos locales (fragmentación basada en AST) para Rust, Python, TypeScript, JavaScript, Go, Java y Dart/Flutter. Rastrea relaciones de llamadas, importaciones, extensiones, implementaciones y mixins entre símbolos.
Validez Temporal: Las memorias pueden tener fechas de valid_from y valid_until.
Backend SurrealDB: Base de datos integrada, rápida y de archivo único.

🛠️ Herramientas Disponibles

El servidor expone 19 herramientas al modelo de IA, organizadas en categorías lógicas.

🧠 Gestión Principal de Memoria

Herramienta	Descripción
`store_memory`	Almacena una nueva memoria con contenido y metadatos opcionales.
`update_memory`	Actualiza campos de memoria.
`delete_memory`	Elimina memoria por ID.
`list_memories`	Lista memorias (más recientes primero).
`get_memory`	Obtiene memoria completa por ID.
`invalidate`	Eliminación suave de memoria, vinculando opcionalmente un reemplazo.
`get_valid`	Obtiene memorias válidas. `timestamp` opcional (ISO 8601) para consulta en un punto específico en el tiempo.

🔎 Búsqueda y Recuperación

Herramienta	Descripción
`recall`	Búsqueda híbrida (Vectorial + Palabras clave + Grafo mediante RRF). Predeterminada para memorias.
`search_memory`	Busca memorias. `mode`: `vector` (predeterminado) o `bm25`.

🕸️ Grafo de Conocimiento

Herramienta	Descripción
`knowledge_graph`	Operaciones KG unificadas. `action`: `create_entity` \| `create_relation` \| `get_related` \| `detect_communities`.

💻 Inteligencia de Código Base

Herramienta	Descripción
`index_project`	Indexa el directorio del código base para búsqueda de código.
`delete_project`	Elimina el proyecto indexado.
`recall_code`	Recuperación de código. `mode`: `vector` o `hybrid` (predeterminado). Híbrido usa fusión vectorial+BM25+grafo.
`search_symbols`	Busca símbolos de código por nombre.
`symbol_graph`	Navega por el grafo de símbolos. `action`: `callers` \| `callees` \| `related`.
`project_info`	Información del proyecto. `action`: `list` \| `status` \| `stats`.

⚙️ Sistema y Mantenimiento

Herramienta	Descripción
`get_status`	Obtiene el estado del sistema y el progreso de inicio.
`reset_all_memory`	PELIGRO: Restablece todos los datos de la base de datos (requiere `confirm=true`).
`how_to_use`	Muestra ejemplos de uso de herramientas y combinaciones de parámetros.

⚙️ Configuración

Variables de entorno o argumentos CLI:

Arg	Env	Default	Description
`--data-dir`	`DATA_DIR`	`./data`	Ubicación de la base de datos
`--model`	`EMBEDDING_MODEL`	`granite`	Modelo de embeddings (`granite`, `e5_multi`, `qwen3`, `gemma`, `bge_m3`, `nomic`, `e5_small`)
`--mrl-dim`	`MRL_DIM`	(nativo)	Dimensión de salida para modelos compatibles con MRL (p. ej., 64, 128, 256, 512, 1024 para Qwen3). El valor predeterminado es la dimensión máxima nativa del modelo (384 para Granite, 1024 para Qwen3).
`--batch-size`	`BATCH_SIZE`	`8`	Tamaño máximo de lote para la inferencia de embeddings
`--cache-size`	`CACHE_SIZE`	`1000`	Capacidad de caché LRU para embeddings
`--timeout`	`TIMEOUT_MS`	`30000`	Tiempo de espera en milisegundos
`--idle-timeout`	`IDLE_TIMEOUT`	`0`	Tiempo de inactividad en minutos. 0 = deshabilitado
`--log-level`	`LOG_LEVEL`	`info`	Verbosidad
(Ninguno)	`HF_TOKEN`	(Ninguno)	Token de HuggingFace (SOLO requerido para modelos restringidos como `gemma`)
(Ninguno)	`EMBEDDING_QUEUE_CAPACITY`	`256`	Tamaño máximo de la cola de embeddings en segundo plano
(Ninguno)	`EMBEDDING_BATCH_SIZE`	`8`	Cuántos archivos procesar en un lote de embeddings
(Ninguno)	`INDEX_BATCH_SIZE`	`20`	Cuántos archivos procesar en un lote incremental
(Ninguno)	`INDEX_DEBOUNCE_MS`	`2000`	Milisegundos de espera antes de vaciar eventos de índice (debounce)
(Ninguno)	`MANIFEST_DIFF_INTERVAL_MINS`	`10`	Minutos entre verificaciones periódicas de archivos faltantes

🧠 Modelos Disponibles

Puedes cambiar el modelo de embeddings usando el argumento --model o la variable de entorno EMBEDDING_MODEL.

Cuando no se proporciona ninguna opción, el binario usa Granite. La precedencia de configuración es: argumento explícito --model, luego EMBEDDING_MODEL, luego el valor predeterminado integrado de Granite.

Valor del Argumento	Repositorio HuggingFace	Dimensiones	Tamaño	Caso de Uso
`granite`	`ibm-granite/granite-embedding-97m-multilingual-r2`	384	~195 MB	Predeterminado. Recuperación multilingüe y de código con ModernBERT y agrupación CLS.
`e5_multi`	`intfloat/multilingual-e5-base`	768	1.1 GB	Modelo multilingüe heredado, buen equilibrio entre calidad y rendimiento.
`qwen3`	`Qwen/Qwen3-Embedding-0.6B`	1024 (MRL)	1.2 GB	Mejor modelo de código abierto de 2026, contexto de 32K, soporte MRL.
`gemma`	`onnx-community/embeddinggemma-300m-ONNX`	768 (MRL)	~195 MB	Alternativa más ligera con soporte MRL. (Requiere acuerdo de licencia propietaria)
`bge_m3`	`BAAI/bge-m3`	1024	2.3 GB	Recuperación híbrida multilingüe de última generación. Pesado.
`nomic`	`nomic-ai/nomic-embed-text-v1.5`	768	1.9 GB	Alta calidad, contexto largo, compatible con BERT.
`e5_small`	`intfloat/multilingual-e5-small`	384	134 MB	Más rápido, RAM mínima. Bueno para desarrollo/pruebas.

granite produce embeddings CLS nativos de 384 dimensiones, normalizados con L2. La ruta actual de CPU de Candle limita las entradas a 512 tokens para acotar el costo de memoria de la atención cuadrática; el modelo en sí admite hasta 32K tokens.

📉 Aprendizaje de Representación Matryoshka (MRL)

Los modelos marcados con (MRL) admiten truncar dinámicamente el vector de embedding de salida a una dimensión más pequeña (p. ej., 512, 256, 128) con una pérdida mínima de precisión. Esto ahorra almacenamiento en la base de datos y acelera la búsqueda vectorial.

Usa el argumento --mrl-dim para especificar el tamaño deseado. Si se omite, el valor predeterminado es la dimensión base nativa del modelo (p. ej., 1024 para Qwen3).

Advertencia: Una vez que tu base de datos se crea con una dimensión específica, no puedes cambiarla sin borrar el directorio de datos.

🔒 Modelos Restringidos y Autenticación (Gemma)

Por defecto, el servidor usa Granite, un modelo Apache 2.0 que se descarga automáticamente sin autenticación.

Sin embargo, si eliges usar Gemma (--model gemma), debes autenticarte porque es un "Modelo Restringido" con licencia propietaria.

Para usar Gemma:

Ve a google/embeddinggemma-300m en Hugging Face.
Inicia sesión y haz clic en "Agree to access repository".
Genera un Token de Acceso en HF Tokens (el acceso de lectura es suficiente).
Inicia el servidor con el token:

# Using environment variable
HF_TOKEN="hf_your_token_here" memory-mcp --model gemma

# Or via .env file (see .env.example)

[!WARNING] Cambio de Modelos y Compatibilidad de Datos

Las instalaciones nuevas usan granite (384 dimensiones) por defecto. Los directorios de datos existentes creados con e5_multi (768 dimensiones) siguen siendo utilizables solo si se inician explícitamente con --model e5_multi.

Cambiar a un modelo con dimensiones diferentes requiere un nuevo directorio de datos (o un volumen borrado) y un reindexado completo.

Incluso cambiar entre modelos con las mismas dimensiones (p. ej., e5_multi <-> nomic) no se recomienda porque sus espacios semánticos difieren.

🔮 Hoja de Ruta Futura (Investigación e Ideas)

Basado en el análisis de sistemas de memoria avanzados como Hindsight (consulta su documentación para detalles sobre estos mecanismos), estamos explorando estas características de "Arquitectura Cognitiva" para futuras versiones:

1. Reflexión Meta-Cognitiva (Consolidación)

Problema: Los recuerdos crudos acumulan ruido con el tiempo (p. ej., 10 recuerdos separados sobre corregir el mismo error).
Solución: Implementar un proceso en segundo plano reflect (o herramienta) que escanee periódicamente los recuerdos recientes para:
- Eliminar duplicados de entradas redundantes.
- Resolver conflictos (si dos recuerdos se contradicen, conservar el más reciente o marcarlo para revisión).
- Sintetizar hechos de bajo nivel en "Perspectivas" de alto nivel (p. ej., "El usuario prefiere Rust sobre Python" derivado de 5 elecciones de código).

2. Decaimiento Temporal y "Presencia"

Problema: Los recuerdos antiguos a veces pueden ahogar el contexto actual en la búsqueda semántica.
Solución: Integrar Decaimiento Temporal en el algoritmo de Fusión de Rango Recíproco (RRF).
- Dar un impulso calculado a los recuerdos recientes para consultas que implican "estado actual".
- Permitir que el agente priorice la "memoria de trabajo" sobre los "archivos históricos" dinámicamente.

3. Bancos de Memoria con Espacios de Nombres

Límite actual: Los índices de código ya admiten filtrado explícito con project_id, mientras que los registros de memoria permanecen a nivel de proceso.
Trabajo futuro: Extender el alcance de espacios de nombres/proyectos a las operaciones de memoria y gráficos para que un servidor compartido pueda aislar múltiples espacios de trabajo de agentes.

4. Puntuación de Confianza Epistémica

Problema: El agente trata una suposición igual que un hecho verificado.
Solución: Agregar una puntuación de confidence (0.0 - 1.0) a los esquemas de memoria.
- Permite almacenar hipótesis ("Creo que el error está en auth.rs", confianza: 0.3).
- Las herramientas de recuperación pueden filtrar recuerdos de baja confianza al responder preguntas factuales.

Licencia

MIT