MemoryMesh

Hub MCP universal para datos personales. Local-first, privado por defecto, diseñado para ser la capa de memoria de los agentes que construirás a continuación.

MemoryMesh indexa tus archivos locales —y en futuras versiones, tus correos electrónicos, calendario, historial del navegador y registros de chat— y los expone a través del Model Context Protocol. Cualquier cliente compatible con MCP (Claude Desktop, Cursor, Claude Code o tu propio agente) puede realizar preguntas semánticas sobre las cosas que realmente posees, sin enviar ni un solo byte a la nube.

Es un hub, no un RAG de propósito único. El transporte, el modelo de embedding, el analizador y la estrategia de fragmentación son intercambiables detrás de interfaces limpias, por lo que el mismo hub puede crecer desde "buscar en mis notas" hasta "recordar todo para mi SO de Agentes".

Por qué existe esto

Los datos personales están fragmentados en docenas de aplicaciones. Ningún agente de IA puede acceder a todos ellos de una manera unificada y privada. El MCP de Anthropic definió el protocolo; MemoryMesh llena el vacío del hub que conecta todo, localmente, con la privacidad como condición previa en lugar de como una configuración.

Related MCP server: NOUZ MCP Server

Cómo funciona

                   ┌──────────────────────────────┐
  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

Pipeline de indexación: el observador de archivos detecta cambios → la deduplicación SHA-256 omite archivos sin cambios → analizador (txt/md/pdf/docx/código) → fragmentador inteligente (tree-sitter para código, por encabezado para markdown, recursivo para texto) → embeddings mediante sentence-transformers → upsert en ChromaDB + índice BM25.

Pipeline de búsqueda: consulta → búsqueda densa (ChromaDB) + búsqueda dispersa (BM25) sobre-recuperación → Reciprocal Rank Fusion (k=60) → resultados top-k con ruta, vista previa, puntuación y metadatos.

Qué lo hace diferente

La mayoría de las herramientas comparables eligen una dimensión para optimizar. MemoryMesh es la única que las cumple todas simultáneamente:

Nativo MCP significa que fue construido para MCP desde el primer día, no añadido después. Las 4 herramientas (search_memory, list_sources, get_document, index_now) tienen una API estable que no se romperá entre versiones.

Diseñado como infraestructura significa que la arquitectura anticipa el acceso multi-agente, permisos por agente y agentes de hardware (ESP32, Arduino) consultando el mismo hub. Ver Roadmap.

Estado

Inicio rápido

Requisito previo: Python 3.11+ y uv.

# Install from PyPI
pip install memorymesh-mcp

O clona para desarrollo:

# Clone and install
git clone https://github.com/kilhubprojects/memory-mesh.git
cd memory-mesh
uv sync

# Initialize state directory and copy example config
uv run memorymesh init

# Edit config.yaml — point it at the folders you want indexed
# (see Configuration section below)

# Index a folder
uv run memorymesh index ~/Documents

# Test a search
uv run memorymesh search "how did I configure the debounce"

Ejecutar como demonio (indexación en tiempo real)

uv run memorymesh start --transport streamable-http --detach
uv run memorymesh status
# edit a file in one of your sources — it gets indexed within ~2s
uv run memorymesh search "the sentence you just typed"
uv run memorymesh stop

Conéctalo a Claude Desktop

Añade a tu configuración de Claude Desktop:

• 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", "serve", "--stdio"
      ]
    }
  }
}

Reinicia Claude Desktop. Las cuatro herramientas aparecerán automáticamente.

Herramientas MCP

Todas las herramientas son compatibles con versiones anteriores. Las firmas de la v0.1 están congeladas; añadir extended_preview en la v0.2 es aditivo, no disruptivo.

Configuración

Todo reside en config.yaml. Consulta config.example.yaml para obtener una referencia totalmente comentada. Aspectos destacados:

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]

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

search:
  mode: hybrid               # hybrid | dense | sparse
  top_k: 10

server:
  transport: stdio           # stdio | streamable-http

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

Benchmarks

Los benchmarks se publicarán aquí después de que la v0.2 implemente CI en las tres plataformas. El objetivo son números reproducibles, no "rápido en mi máquina".

Los scripts ya están en benchmarks/ y se pueden ejecutar localmente:

• 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 embedding

Privacidad y seguridad

Tres compromisos firmes que no cambian entre versiones:

1. Ningún dato sale de tu máquina. Sin telemetría. Sin llamadas a API externas a menos que lo aceptes explícitamente, e incluso entonces, hay una ADVERTENCIA en el registro.

2. El oyente HTTP se vincula a 127.0.0.1 solo por defecto. Exponerlo a otras interfaces requiere una anulación de configuración explícita.

3. Los registros nunca contienen contenido de documentos o consultas en texto plano. El registro de auditoría guarda hashes de consulta, no las consultas.

El cifrado en reposo está en el roadmap. Si tu disco está cifrado a nivel de SO, estás cubierto para el modelo de amenaza contra el que está diseñado MemoryMesh.

Roadmap

Detalles completos en ROADMAP.md.

Solución de problemas

• UnicodeDecodeError en un archivo de texto — MemoryMesh intenta UTF-8, UTF-8 BOM, cp1252, latin-1 en orden. Si un archivo sigue fallando, se registra y se omite, no se bloquea.

• El observador no se activa en una unidad de red / montaje WSL — establece watcher.use_polling: true en config.yaml.

• Tesseract no encontrado — instálalo en todo el sistema y asegúrate de que esté en PATH. Windows: Instalador UB-Mannheim.

• Desajuste del modelo de embedding después de cambiar la configuración — ejecuta memorymesh reindex --all. La CLI se niega a iniciarse si el ID del modelo almacenado en ChromaDB no coincide con la configuración.

Sobre este proyecto

MemoryMesh es un proyecto en solitario construido usando vibe coding —escribir código en estrecha colaboración con LLMs a alta velocidad— con revisiones arquitectónicas estructuradas en cada fase. El proceso: el LLM propone código, el arquitecto revisa la corrección, las brechas de diseño y las violaciones de especificaciones, y la suite de pruebas confirma. Los errores que se filtraron (orden de inicio en el sistema de reconciliación, violación de encapsulación de BM25, argumentos de constructor incorrectos en la CLI) fueron detectados en la revisión antes de que se ejecutaran en producción.

Esto es lo que parece el vibe coding cuando te tomas en serio el paso de revisión: una suite de 172 pruebas, un pipeline de búsqueda híbrida real, un sistema de reconciliación y una arquitectura diseñada para avanzar hacia un SO de Agentes.

Contribuciones

MemoryMesh aún no acepta contribuciones externas; todavía no hay CI ni guía de contribución. Esto cambiará en la v0.2. Observa el repositorio o vuelve a consultar entonces.

Licencia

MIT. Ver LICENSE.

Agradecimientos

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