graphrag-local

Parte del ecosistema Myrmion

Myrmion es un ecosistema opensource para adoptar IA corporativa con cultura propia. Myrmion graphRAG es una de sus herramientas: da a Claude Code memoria local sobre tus documentos y tu código sin que nada salga de tu máquina. Se usa por sí sola, sin requerir el resto del ecosistema.

Dos memorias locales, expuestas como dos servidores MCP:

• myrmion-graphrag — grafo de conocimiento sobre tus documentos (notas, manuales, papers, decisiones). Motor: LightRAG + Ollama.

• myrmion-codebase — grafo de tu código: dependencias, "¿a qué afecta esta función?", "¿quién llama a X?", inventario (reutilizable / obligatoria / muerta) e histórico. Parser multi-lenguaje (Python vía ast; JS/TS, Java, C# y VB.NET vía tree-sitter; VB6/VBScript y ASP clásico con parser propio).

Todo corre en tu equipo, sin claves de API para el indexado. Solo sale lo que Claude Code envía a Anthropic al razonar tu pregunta.

Otras piezas del ecosistema: myrmion-blackbar-pii-guard (redacción de PII para Claude) · myrmion-AI-factory (SDLC agéntico gobernado) · myrmion-framework (el paraguas).

Related MCP server: MyAIGist MCP

Índice

• Parte del ecosistema Myrmion

• Arquitectura

• Requisitos

• Instalación y conexionado

• Backends de almacenamiento (filesystem / Neo4j / PostgreSQL / híbrido)

• Consistencia del híbrido (saga + reconciliación)

• Perfiles de modelo (local vs profesional)

• Parametrizar según tu hardware (CPU/RAM/GPU/modelo)

• Herramientas MCP

• Lenguajes y parsers cubiertos

• Mantenimiento automático del codebase_inventory

• Sincronización incremental sin duplicados

• Versionado de documentos

• Tests

• Estructura del repo

• Referencias / créditos

• Licencia

Arquitectura

                         Claude Code (VS Code) ── cliente MCP
                           │ stdio            │ stdio
            ┌──────────────▼───────┐   ┌──────▼────────────────┐
            │  myrmion-graphrag    │   │  myrmion-codebase     │
            │  mcp_server.py       │   │  codebase_server.py   │
            │  (documentos)        │   │  (código)             │
            └──────────┬───────────┘   └──────┬────────────────┘
               HTTP :9621                GraphStore pluggable
            ┌──────────▼───────────┐   ┌──────▼────────────────────────────┐
            │  lightrag-server     │   │ filesystem(def) │ neo4j │ postgres │
            │  storage PLUGGABLE:  │   └────────────────────────────────────┘
            │  filesystem/neo4j/pg │
            │  /híbrido            │
            └──────────────────────┘

def = backend por defecto. Ambos servidores usan el mismo trío filesystem / neo4j / postgres. Para el grafo de código, filesystem persiste el grafo en un JSON en config/ (sin BD externa, como el filesystem de LightRAG); neo4j/postgres son las opciones profesionales.

Requisitos

• Python 3.11+

• Ollama instalado y en ejecución

• VS Code con la extensión de Claude Code

• ~11 GB de RAM libres para indexar documentos con qwen2.5:7b

• (Opcional, para backends profesionales) Docker + Docker Compose

Instalación y conexionado

1. Modelos locales (una vez)

ollama pull qwen2.5:7b
ollama pull nomic-embed-text

2. Setup del proyecto

./setup.sh

setup.sh crea el venv, instala dependencias (requirements.txt + requirements-codebase.txt), crea tu config personal en config/ (desde las plantillas *.example), genera config/mcp.json con los dos servidores y sus rutas absolutas, crea los enlaces .env y .mcp.json en la raíz, copia los scripts locales (db-up.sh, migrate-backend.sh) y activa el git pre-push hook del inventario.

Toda tu configuración personal vive en config/ (gitignored); el repo solo versiona las plantillas. Edita config/lightrag.env (rutas, API key, perfil de storage) y config/codebase.env (raíz del código, backend), y re-ejecuta ./setup.sh.

3. Servidor LightRAG (documentos)

uv tool install "lightrag-hku[api]"   # o: pip install "lightrag-hku[api]"
lightrag-server                        # otra terminal; lee .env -> config/lightrag.env

4. Indexar

# Documentos -> myrmion-graphrag
python ingest.py "$INPUT_DIR" --api-key "$LIGHTRAG_API_KEY" --watch

# Código -> myrmion-codebase  (desde Claude Code: tool  indexar_codebase )

5. Conectar Claude Code

Abre el repo en VS Code con Claude Code. El .mcp.json de la raíz hace que Claude Code descubra ambos servidores. Verifica con /mcp que aparecen conectados: myrmion-graphrag y myrmion-codebase. Llama a estado_rag y a estado_indexado para diagnosticar cada uno.

El servidor myrmion-codebase puede apuntar a cualquier codebase: pon su ruta en CODEBASE_ROOT (en config/codebase.env) y re-ejecuta ./setup.sh.

Backends de almacenamiento

LightRAG usa 4 capas de storage (KV, Vector, Grafo, DocStatus). Eliges un perfil en config/lightrag.env (bloque de almacenamiento). Caveat: el storage debe elegirse antes de indexar el primer documento; cambiarlo obliga a re-indexar (usa ./migrate-backend.sh).

Levanta los backends con Docker (bind a 127.0.0.1, nada sale de tu máquina):

./db-up.sh neo4j start        # Neo4j en :7474 (browser) / :7687 (bolt)
./db-up.sh postgres start     # Postgres en :5432
./db-up.sh pro start          # HÍBRIDO: ambos a la vez

Valida la conexión y qué backend está activo:

python -m backends healthcheck neo4j     # o postgres
# y desde Claude Code:  estado_rag   (reporta el backend activo)

El inventario de código (myrmion-codebase) usa su propio GraphStore pluggable con el mismo trío: filesystem (por defecto, grafo persistido en un JSON en config/, sin BD), neo4j (recomendado para uso pro; puede reutilizar la instancia de LightRAG) o postgres.

Consistencia del híbrido

El perfil híbrido escribe el grafo en Neo4j y los vectores/KV/estado en Postgres: dos bases de datos sin transacción distribuida. Para que nunca queden desalineadas, myrmion-graphrag incluye un supervisor de consistencia (consistency.py):

• Health-gate: no se escribe salvo que Neo4j y Postgres y LightRAG respondan.

• Saga con reintentos automáticos + compensación: cada operación de documento es una saga de pasos idempotentes; si un paso agota reintentos, se compensan los previos.

• Reconciliación: detecta deriva (docs sin grafo/sin vectores, huérfanos) y la repara (reindexar / borrar huérfanos).

Tools MCP (solo aplican al híbrido): verificar_alineacion (dry-run) y reconciliar(aplicar=True) (repara).

Compromiso honesto: es consistencia fuerte auto-reparable (se detecta y repara toda deriva), no un candado 2PC instantáneo. Si necesitas una garantía transaccional dura sin reconciliación, usa el Perfil C (Postgres todo-en-uno: una sola transacción ACID). El inventario de código va en Neo4j (grafo puro, un solo store → sin deriva posible).

Perfiles de modelo

Los backends profesionales suelen correr en hardware potente, donde interesa un Qwen mayor para maximizar la extracción y la fiabilidad. En config/lightrag.env hay presets:

Regla crítica: cambiar LLM_MODEL no obliga a reindexar; cambiar EMBEDDING_MODEL/EMBEDDING_DIM sí (la dimensión del vector cambia). Descarga el modelo con ollama pull qwen2.5:32b.

Parametrizar según tu hardware

Ajusta config/lightrag.env según CPU/RAM/GPU. Referencia (Q4): 7b≈6GB, 14b≈10GB, 32b≈20GB, 72b≈48GB de VRAM/RAM.

Perillas: MAX_ASYNC = llamadas LLM en paralelo (CPU=1; en GPU sube según VRAM). OLLAMA_LLM_NUM_CTX = ventana para extracción (32k+ ideal, pero consume RAM/VRAM; 8k en CPU para evitar swap). OLLAMA_KV_CACHE_TYPE=q8_0 comprime la KV cache. Sube timeouts en CPU. Ollama usa la GPU automáticamente si está disponible (OLLAMA_NUM_PARALLEL, capas descargadas según VRAM). Regla de oro: sube modelo/NUM_CTX/MAX_ASYNC solo si el hardware lo aguanta sin swap; en CPU, prioriza terminar el indexado antes que calidad máxima.

Herramientas MCP

myrmion-graphrag (documentos)

Modos de búsqueda: mix (recomendado), hybrid, local, global, naive.

myrmion-codebase (código)

Cada llamada expone la confianza (exact/heuristic/unresolved) de las aristas para que valores tú la fiabilidad; nunca se adivina en ambigüedad.

Lenguajes y parsers cubiertos

El servidor myrmion-codebase elige el parser por la extensión del fichero. El grafo es el mismo para todos (nodos Module/Class/Function/Method, aristas DEFINES/IMPORTS/INHERITS/ CALLS/IMPLEMENTS); solo cambia el motor de parseo:

La resolución de llamadas es heurística en todos los lenguajes (tree-sitter es sintáctico; no hay análisis de tipos): se expone confidence (exact/heuristic/ unresolved) para que valores la fiabilidad. En VB.NET la herencia (Inherits/Implements) se omite por ser poco fiable en la gramática. Nuevos lenguajes tree-sitter se añaden registrando su gramática y extensión. El markup .aspx de ASP.NET queda para fase posterior.

Mantenimiento automático del codebase_inventory

El inventario durable refleja solo la rama main; editar en ramas de feature no lo muta (si la rama nunca se mergea, no deja símbolos fantasma). Tres capas:

1. Instrucciones en CLAUDE.md: Claude llama a sincronizar_codigo tras editar.

2. Hook PostToolUse (.claude/settings.json → hooks/sync_on_edit.sh): mantiene caliente el overlay de sesión tras cada Edit/Write (nunca el durable).

3. git pre-push hook (hooks/pre-push, activado por setup.sh vía core.hooksPath): al hacer push a main, reconcilia el inventario canónico con el diff y aborta el push si no queda consistente. Lo ejecuta git, no el modelo → no se puede saltar.

Sincronización incremental sin duplicados

sincronizar_codigo(["ruta"]) (y el CLI python -m codebase_mcp.sync) actualizan el grafo tras editar, garantizando:

• Sin duplicados: Node.id estable (kind:qualified_name) + upsert idempotente.

• Sin residuos: borra todos los nodos/aristas del fichero antes de re-parsear (los símbolos renombrados/eliminados desaparecen).

• Consistencia cruzada: re-resuelve todas las llamadas, así ninguna arista de otro fichero queda colgando.

• Barato: no-op si el hash del fichero no cambió.

Versionado de documentos

LightRAG guarda solo la versión actual de cada documento y deduplica por nombre (archiva los duplicados en vez de actualizar): si el contenido cambia pero el nombre no, un re-upload ingenuo pierde el update. Por encima de LightRAG hay un ledger de documentos que reutiliza la misma maquinaria que el inventario de código (snapshots + histórico), con la identidad = basename y el body_hash = hash de contenido/bytes:

• Detección por hash, no por nombre: sincronizar_documento(ruta) / sincronizar_documentos(carpeta) reindexan solo si el hash cambió (no-op si no), y hacen delete + insert/upload cuando cambió → nunca se pierde un update ni se duplica. Funciona con binarios (pdf/docx: se re-sube el fichero por multipart).

• Histórico: cada sync crea un snapshot (etiquetado con el commit git) y registra added/modified/removed → historico_documento(ruta) y estado_documentos(), igual que el codebase.

• Batch seguro: python ingest.py "$INPUT_DIR" --sync usa el ledger para saltar lo no cambiado y actualizar (borrar+subir) lo modificado, en vez de dejar que LightRAG archive el duplicado.

El ledger vive en config/docs.json (var DOCS_LEDGER), gitignored.

Tests

pip install -r requirements-dev.txt      # pytest, pytest-cov, respx, tree-sitter, ...
python -m pytest                         # cobertura mínima exigida: 80%

87 tests, ~87% de cobertura. Todo corre sin servicios externos (HTTP mockeado con respx, grafo en memoria, git real en tmp_path). Los tests que requieren Neo4j/Postgres reales van marcados @pytest.mark.integration y se excluyen por defecto.

Estructura del repo

.
├── mcp_server.py            # servidor MCP de documentos (LightRAGClient)
├── codebase_server.py       # servidor MCP de código
├── codebase_mcp/            # paquete: parsers, GraphStore, resolver, queries, inventory,
│                            #          gitutil, history, indexer, sync
├── backends.py              # perfiles de storage + healthcheck + modelos (testeable)
├── consistency.py           # saga + reconciliación del híbrido (testeable)
├── consistency_readers.py   # cableado a Neo4j/Postgres reales (integración)
├── ingest.py                # ingesta en lote de documentos
├── docker-compose.yml       # Neo4j / Postgres (perfiles)
├── hooks/                   # pre-push (gate del inventario) + sync_on_edit (PostToolUse)
├── tests/                   # suite pytest + fixtures/mini_codebase
├── pyproject.toml           # config de pytest/coverage
├── *.env.example / .mcp.json.example / *.sh.example   # PLANTILLAS públicas
└── CLAUDE.md / README.md / LICENSE

# Generado en local, NUNCA versionado (gitignored):
#   config/            TU config real (lightrag.env, codebase.env, mcp.json, codebase.json)
#   .env  .mcp.json    enlaces a config/
#   db-up.sh  migrate-backend.sh  venv/  rag_storage/

Referencias / créditos

Este proyecto toma como base y se inspira en:

• HKUDS/LightRAG — motor GraphRAG (grafo + vectores + storage pluggable).

• DeusData/codebase-memory-mcp — concepto del servidor de inteligencia de codebase.

• tree-sitter + gramáticas tree-sitter-javascript/typescript/java/c-sharp y tree-sitter-language-pack (grammar vb para VB.NET) — parsing multi-lenguaje.

• Ollama y Qwen — modelos locales (LLM y embeddings).

• Model Context Protocol — el estándar que conecta las herramientas con Claude Code.

• Neo4j y PostgreSQL (pgvector + Apache AGE) — backends profesionales.

Licencia

MIT. Ver LICENSE.