LLMGraph

Gestor de contexto para modelos y agentes IA basado en grafos comprimidos.

Principio del sistema:

Markdown humano editable -> grafo comprimido -> Context Pack minimo, vigente y trazable

LLMGraph no reemplaza la documentacion humana. Compila .md a un indice .llgr.zlib para que los agentes consulten solo el contexto relevante de una tarea, con fuentes y metricas.

Instalación

pip install -e ".[mcp]"

Instalación por editor

VS Code / Cursor / Windsurf

LLMGraph incluye una extension VSIX en extension/ que agrega una pestaña en la Activity Bar del editor. El panel invoca el CLI local y puede asegurar la configuracion MCP del workspace.

cd extension
npm install
npm run validate
npm run package
code --install-extension llmgraph-editor-0.4.0.vsix

Cursor y Windsurf pueden instalar el mismo .vsix desde su interfaz de extensiones o desde un CLI compatible.

Claude Code

El plugin vive en .claude-plugin/plugin.json y registra el MCP llmgraph. Tambien se incluye el skill .claude/skills/llmgraph-context/SKILL.md.

Codex

codex mcp add llmgraph -- llmgraph-mcp

La configuracion equivalente esta en .codex/config.toml.

opencode

Copiar opencode.json al workspace o usarlo desde esta raiz. Declara el MCP local llmgraph.

ChatGPT Desktop

Usar el connector MCP local con comando llmgraph-mcp y working directory del proyecto. ChatGPT web no aplica porque LLMGraph no expone una API HTTP.

Uso rápido

Python

from llmgraph import Graph, encode, decode
from llmgraph.md_parser import parse_file

# Crear grafo
g = Graph()
g.metadata["project"] = "mi-proyecto"
g.add_node("file", name="auth.py", lang="python")
g.add_node("file", name="db.py", lang="python")
g.add_edge(0, 1, "imports")

# Codificar a binario
raw = encode(g)  # → bytes, ~10x más pequeño que .md equivalente

# Decodificar
g2 = decode(raw)

CLI

# Convertir .md a .llgr
llmgraph convert README.md -o project.llgr

# Consultar
llmgraph query project.llgr -t section

# Comparar
llmgraph diff graph1.llgr graph2.llgr

Context Manager

# Crear context/context-policy.toml
llmgraph context init .

# Compilar README.md/docs/operations a context/project.llgr.zlib
llmgraph context build .

# Preparar contexto optimizado para una tarea
llmgraph context prepare . "refactorizar autenticacion" --profile coding --max-tokens 3000

# Buscar dentro del grafo de contexto
llmgraph context search . "middleware de autenticacion"

# Auditar fuentes, nodos grandes y referencias rotas
llmgraph context health .

El Context Pack reporta:

• tokens fuente vs tokens usados;
• porcentaje de tokens ahorrados;
• nodos incluidos;
• fuentes usadas;
• porcentaje de trazabilidad;
• nodos obsoletos excluidos.

Plan de continuación:

• docs/plan-contexto.md

MCP Server (para editores agenticos)

# Agregar a opencode.json:
{
  "mcp": {
    "llmgraph": {
      "type": "local",
      "command": ["python", "-m", "llmgraph.mcp_server"],
      "enabled": true
    }
  }
}

Formato binario

Un archivo .llgr contiene:

• Header (16 bytes): magic "LLGR" + versión + conteos
• String dictionary: strings deduplicadas (como side channel en MP3)
• Nodes: tipo + propiedades por nodo
• Edges: src + tgt + tipo + propiedades por edge
• Metadata: key-value pairs a nivel de grafo

Compresión vs .md

Formato	Tamaño (50 nodos)	Ratio
.md	1x (baseline)	1.0x
.llgr	~0.3-0.5x	2-3x
JSON	~2x	0.5x

La compresión mejora con grafos más grandes gracias a la deduplicación de strings.

Licencia

MIT