MCP Memory-mesh

Un servidor MCP que le da a Claude Code memoria persistente entre sesiones (código abierto, SQLite)

Documentación

MemoryMesh

SQLite para la memoria de IA. Capa de memoria persistente para agentes MCP y copilotos de código: local primero, cero nube, funciona en 5 minutos.

Véalo en acción: Claude Code recordando decisiones de proyecto entre sesiones.

💻 Copilotos de código	🤖 Agentes MCP	📚 Asistentes de investigación
Recuerda decisiones de arquitectura, errores y preferencias entre sesiones	Memoria persistente en cualquier cliente compatible con MCP	Recuperación semántica de notas, artículos y documentos

En funcionamiento en 5 minutos

pip install memorymesh-mcp
cp config.example.yaml ~/.memorymesh/config.yaml
# edit config.yaml — point at your folders
memorymesh index ~/Documents
memorymesh search "how did I configure the debounce"

Conéctelo a Claude Desktop. Encuentre el archivo de configuración en:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memorymesh": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/memory-mesh",
        "memorymesh", "start"
      ]
    }
  }
}

Reinicie Claude Desktop. Las 15 herramientas aparecen automáticamente.

Por qué existe

Cada conversación de IA comienza desde cero. Claude no sabe qué decisión de arquitectura tomó la semana pasada. Cursor no recuerda el error que corrigió ayer. El contexto muere cuando termina la sesión.

Mem0 requiere una cuenta en la nube. Zep necesita un servidor en ejecución y una base de datos. LangMem lo ata al ecosistema LangChain. Ninguno habla MCP de forma nativa.

MemoryMesh se ejecuta completamente en su máquina. Indexa sus archivos en un almacén local SQLite + ChromaDB y los expone a través de 15 herramientas MCP. Nunca toca la red a menos que configure un conector. Cualquier cliente MCP (Claude Desktop, Cursor, su propio agente) obtiene memoria persistente con un cambio de configuración.

Cómo funciona

El indexador observa sus archivos, los divide en fragmentos con analizadores conscientes del formato y almacena las incrustaciones localmente. El motor de búsqueda fusiona resultados densos y dispersos, y luego un reranker de codificador cruzado puntúa los candidatos.

                   ┌──────────────────────────────┐
  MCP clients ───▶ │         MemoryMesh           │
(Claude Desktop,   │  ┌────────────────────────┐  │
 Cursor, agents)   │  │ MCP Tools (FastMCP):   │  │
                   │  │  search_memory         │  │
                   │  │  list_sources          │  │
                   │  │  get_document          │  │
                   │  │  index_now             │  │
                   │  └──────────┬─────────────┘  │
                   │             ▼                 │
                   │     Search Engine             │
                   │   dense + BM25 → RRF          │
                   │             │                 │
                   │   ┌─────────┴──────────┐      │
                   │   ▼                    ▼      │
                   │ ChromaDB            BM25      │
                   │ (embeddings)     (sparse)     │
                   │   ▲                    ▲      │
                   │   └──────── Indexer ───┘      │
                   │                ▲              │
                   │           Watchdog            │
                   └────────────────┬──────────────┘
                                    ▼
                             Your filesystem

Indexación: el observador de archivos detecta cambios → la deduplicación SHA-256 omite archivos sin cambios → el analizador (txt/md/pdf/docx/code/obsidian/email/calendar/browser) → el fragmentador (tree-sitter para código, por encabezado para markdown, recursivo para texto) → incrustaciones sentence-transformers → ChromaDB + BM25.

Búsqueda: consulta → expansión de consulta (variantes léxicas + HyDE) → búsqueda densa y dispersa en paralelo → Fusión de Rango Recíproco (k=60) → reranker bge-reranker-v2-m3 → resultados top-k con ruta, vista previa, puntuación y metadatos.

RAG (opcional): ask_memory → recuperación search_memory → Ollama generate() → respuesta fundamentada con fuentes citadas.

Qué incluye

MemoryMesh incluye búsqueda híbrida (incrustaciones densas + BM25 + RRF + reranker de codificador cruzado), niveles de memoria caliente/tibia/fría con decaimiento de olvido configurable y una línea de tiempo de eventos episódicos. 47 conectores extraen datos de Jira, Notion, GitHub, Slack, correo electrónico, historial del navegador, Spotify y más. 15 herramientas MCP exponen todo a cualquier cliente compatible con MCP. Un observador de archivos en tiempo real reindexa los archivos modificados en segundos, sin activación manual.

Lista completa de funciones

Función	Estado
Indexación de archivos locales (txt, md, code, pdf, docx)	✅
Analizador de bóvedas Obsidian (frontmatter + wikilinks)	✅
Analizador de exportación HTML de Notion	✅
Exportaciones de conversaciones de IA (Claude, ChatGPT JSON)	✅
Indexación de correo electrónico (`.mbox` vía stdlib)	✅
Indexación de calendario (`.ics` / iCalendar)	✅
Historial del navegador (Chrome / Firefox / Brave SQLite)	✅
Búsqueda híbrida: densa + BM25 + RRF	✅
Reranker de codificador cruzado (`bge-reranker-v2-m3`)	✅
Expansión de consulta: variantes léxicas + HyDE	✅
RAG con LLM local vía Ollama (herramienta `ask_memory`)	✅
Indexación de resúmenes multi-vector para recuperación abstracta	✅
Servidor MCP: 15 herramientas, stdio + streamable-http	✅
Indexación incremental en tiempo real (watchdog + debounce)	✅
Fragmentación de código con tree-sitter (Python, JS, TS, Go, Rust…)	✅
Recuperador de documento padre (`extended_preview`)	✅
Multiplataforma: Windows / Linux / macOS	✅
Reconciliación tras fallos	✅
OCR opcional para PDF escaneados (Tesseract / EasyOCR)	✅
Registro de auditoría de privacidad (solo hashes de consulta, sin texto claro)	✅
CI de GitHub Actions (Ubuntu / Windows / macOS)	✅
Docker + docker-compose	✅
Capa de permisos por agente (ACL + límite de velocidad + revocación)	✅
Memoria jerárquica (niveles caliente / tibia / fría + política de olvido)	✅
Línea de tiempo de memoria episódica (herramientas `query_timeline`, `record_event`)	✅
Herramientas de control de memoria (`pin_memory`, `forget_memory`)	✅
Caché LRU de incrustaciones (`CachedEmbeddingProvider`)	✅
Punto final de salud (`GET /health` en :8766)	✅
Incrustaciones de imagen CLIP reales (`memorymesh[multimodal]`)	✅
Transcripción de audio Whisper real (`memorymesh[multimodal]`)	✅
Grafo de conocimiento: co-ocurrencia de entidades (herramienta `/graph`, `graph_memory`)	✅
Cifrado en reposo (Fernet AES-128, `memorymesh keygen`)	✅
API REST (11 puntos finales en `/api`, documentos OpenAPI en `/api/docs`)	✅
Extensión de VS Code (`extensions/vscode/`)	✅
Extensión de navegador: Manifest V3 (`extensions/browser/`)	✅
47 conectores de fuentes de datos (Jira, Notion, GitHub, Slack, Spotify…)	✅
Suite de pruebas unitarias e integración	✅

Herramientas MCP

Una vez en ejecución, estas herramientas están disponibles para cualquier cliente compatible con MCP:

Herramienta	Descripción
`search_memory(query, top_k, mode, source)`	Búsqueda híbrida sobre todo el contenido indexado. Devuelve ruta, vista previa, puntuación, tipo de archivo, fuente y `extended_preview` opcional para contexto más amplio.
`list_sources()`	Lista todas las fuentes configuradas con recuentos de archivos y estado de indexación.
`get_document(path, max_bytes)`	Lee el contenido completo de un archivo indexado (hasta 1 MB por defecto).
`index_now(path)`	Fuerza la reindexación inmediata de un archivo o directorio, omitiendo el observador.
`ask_memory(question, top_k, model)`	RAG: recupera pasajes relevantes y los envía a un modelo Ollama local para una respuesta fundamentada. Requiere Ollama ejecutándose localmente.
`pin_memory(chunk_id)`	Fija un fragmento al nivel caliente: nunca degradado, nunca con decaimiento de puntuación.
`forget_memory(chunk_id)`	Suprime un fragmento de futuros resultados de búsqueda sin eliminar el archivo fuente.
`query_timeline(since_days, event_type, limit)`	Consulta el registro de eventos episódicos: ¿qué se recuperó / indexó en los últimos N días?
`sync_source(source_type, dry_run)`	Extrae e indexa documentos de un conector externo configurado (Jira, Notion, GitHub…).
`get_entity(name, entity_type)`	Busca una entidad nombrada (persona, proyecto, concepto) y sus IDs de fragmento asociados.
`related_documents(path, top_k, exclude_self)`	Encuentra documentos semánticamente similares a la ruta de archivo dada.
`search_by_date(since_days, until_days, source, limit)`	Busca fragmentos indexados por rango de fecha de última modificación.
`forget_source(source, dry_run)`	Elimina todos los datos indexados de una fuente nombrada del índice.
`summarize_source(source, max_chunks)`	Genera un resumen breve del contenido más reciente en una fuente (requiere Ollama).
`graph_memory(min_mentions, entity_type)`	Devuelve el grafo de conocimiento de co-ocurrencia de entidades como nodos y aristas.

Todas las herramientas son retrocompatibles: se añaden nuevos campos sin cambiar las firmas existentes.

Cómo se compara MemoryMesh

Cómo se compara MemoryMesh con proyectos similares:

Función	MemoryMesh	LangChain	LlamaIndex	PrivateGPT	AnythingLLM	MemGPT	Haystack
MCP nativo	✅	❌	❌	❌	❌	❌	❌
Búsqueda híbrida (densa + BM25 + RRF)	✅	Parcial	Parcial	❌	❌	❌	✅
Observador en tiempo real + deduplicación SHA-256	✅	❌	❌	❌	❌	❌	❌
Reconciliación tras fallos	✅	❌	❌	❌	❌	❌	❌
100% local, cero telemetría	✅	✅	✅	✅	✅	✅	✅
Multiplataforma (Win/Linux/Mac)	✅	✅	✅	Parcial	Parcial	✅	✅
Sin dependencia de framework	✅	—	—	❌	❌	❌	—
Permisos por agente	✅	❌	❌	❌	❌	❌	❌

MCP nativo significa que fue construido para MCP desde el primer día, no añadido después. Las 15 herramientas siguen un versionado aditivo: se añaden nuevos campos sin eliminar los existentes.

Permisos por agente significa que la identidad por cliente, ACL por fuente y operación, límite de velocidad con token-bucket y revocación de tokens están integrados en el núcleo, no añadidos como middleware.

Configuración

Todo vive en config.yaml. Consulte config.example.yaml para una referencia completamente comentada. Puntos clave:

sources:
  - name: documents
    path: ~/Documents
    recursive: true
    extensions: [.txt, .md, .pdf, .docx]

  - name: projects
    path: ~/Projects
    recursive: true
    extensions: [.py, .js, .ts, .go, .rs, .md]

  - name: obsidian
    path: ~/obsidian-vault
    source_type: obsidian     # activates wikilink + frontmatter parser

  - name: emails
    path: ~/Mail
    source_type: email        # parses .mbox files

embeddings:
  model: all-MiniLM-L6-v2    # swap to paraphrase-multilingual-MiniLM-L12-v2 for PT/EN

search:
  default_top_k: 10
  hybrid:
    enabled: true
  reranker:
    enabled: true             # cross-encoder reranker (recommended)
    model: BAAI/bge-reranker-v2-m3
  query_expansion:
    enabled: true
    n_lexical_variants: 1

# Optional: local LLM for ask_memory tool + HyDE query expansion
ollama:
  enabled: false              # set true after: ollama pull llama3
  model: llama3

server:
  transport: stdio            # stdio | streamable-http

Lista de ignorados global protege rutas sensibles por defecto: .env, *.key, id_rsa*, secrets/, .ssh/, .aws/, .git/, node_modules/.

Puntos de referencia

Los resultados de los puntos de referencia se publicarán aquí. Los scripts ya están en benchmarks/ y se pueden ejecutar localmente: se aceptan contribuciones con números reproducibles.

bench_indexing.py — rendimiento de indexación (fragmentos/s, MB/s) en un corpus sintético
bench_search_latency.py — latencia de búsqueda p50/p95/p99 en modos híbrido/denso/disperso
bench_embedding_models.py — comparación de velocidad vs. calidad entre tres modelos de incrustación

Privacidad y seguridad

Tres compromisos que no cambian entre versiones:

Ningún dato sale de su máquina. Sin telemetría. Sin llamadas API externas a menos que opte explícitamente, e incluso entonces, hay un WARNING en el registro.
El listener HTTP se vincula solo a 127.0.0.1 por defecto. Exponerlo a otras interfaces requiere una anulación explícita de configuración.
Los registros nunca contienen contenido de documentos ni consultas en texto claro. El registro de auditoría registra hashes de consultas, no consultas.

El cifrado en reposo está disponible desde v0.8.0. Ejecute memorymesh keygen para generar una clave, luego habilite encryption.enabled: true en config.yaml. El almacén de metadatos SQLite se puede exportar como copia de seguridad cifrada con memorymesh backup.

Hoja de ruta

Versión	Enfoque	Estado
v0.1	Núcleo: búsqueda híbrida, 4 herramientas MCP, transporte stdio, indexador	✅ enviado
v0.2	CI/CD, Recuperador de documento padre, Docker, endurecimiento de seguridad	✅ enviado
v0.3	Reranker, expansión de consulta + HyDE, RAG (Ollama), 6 nuevos analizadores, marco de evaluación	✅ enviado
v0.5	Permisos por agente (ACL/límite de velocidad/revocación), niveles caliente/tibia/fría, línea de tiempo episódica, herramientas de control de memoria, caché de incrustaciones, punto final de salud, stubs CLIP/Whisper	✅ enviado
v0.8	CLIP+Whisper reales, Grafo de conocimiento, Cifrado en reposo, API REST (11 puntos finales), extensiones VS Code + navegador, 47 conectores, 15 herramientas MCP	✅ enviado
v1.0	Integración con Agent OS: capa de memoria para sistemas multi-agente	~6 meses
v2.0	Agentes de hardware: ESP32/Arduino consultando el hub por BLE/WiFi	~12 meses

Detalles completos en ROADMAP.md.

Solución de problemas

UnicodeDecodeError en un archivo de texto — MemoryMesh prueba UTF-8, UTF-8 BOM, cp1252, latin-1 en orden. Si un archivo aún falla, se registra y se omite.
El observador no se activa en una unidad de red / montaje WSL — establezca watcher.use_polling: true en config.yaml.
Tesseract no encontrado — instálelo a nivel de sistema y asegúrese de que esté en PATH. Windows: instalador UB-Mannheim.
Desajuste del modelo de incrustación tras cambiar la configuración — ejecute memorymesh reindex --all. La CLI se niega a iniciar si el ID del modelo almacenado en ChromaDB no coincide con la configuración.

Contribuciones

Las contribuciones son bienvenidas: informes de errores, nuevos conectores, ejemplos de integración y mejoras de documentación ayudan. Abra un issue para discutir antes de enviar un PR grande.

Agradecimientos

Arquitectura informada por el estudio de LlamaIndex, LangChain, PrivateGPT, AnythingLLM, MemGPT y Haystack: entender qué hace bien cada uno y qué no. Y a chroma-mcp y el SDK MCP de Python por mostrar cómo se ve MCP-nativo en la práctica.

MIT. Consulte LICENSE.