Knowledge Graph
Una capa de memoria persistente impulsada por grafos de conocimiento para agentes de codificación y flujos de trabajo de LLM.
Documentación
Knowledge Graph para Claude Code y Codex
Memoria persistente y nativa de git que hace que tu agente de codificación con IA realmente recuerde. Cero bases de datos, cero servicios — solo bash, jq y tus propios commits.
Claude Code y otros agentes de codificación con IA olvidan todo entre sesiones — terminas reexplicando el mismo contexto del proyecto cada vez. Knowledge Graph soluciona eso convirtiendo tus operaciones de archivos y tu historial de git en una capa de memoria ligera y basada en evidencia que vive dentro de tu repositorio.
Soporte de primera clase para:
- Claude Code — rastrea automáticamente lecturas y escrituras mediante hooks, inyecta una instantánea de trabajo en cada inicio de sesión, reconstruye el contexto después de
/cleary/compact - Codex / Cursor / Windsurf / cualquier cliente MCP — 7 herramientas y más de 20 recursos expuestos por el servidor MCP stdio incluido (
kg_read_node,kg_query,kg_recent_work,kg_blind_spots, …)
Sin embeddings. Sin almacenes vectoriales. Sin servicios externos. Funciona en macOS, Linux y Windows.
Para quién es esto
- Vibecoders — describes la intención, el agente escribe el código. Knowledge Graph le da al agente el contexto del proyecto que nunca tuviste que aprender, para que las solicitudes de una línea se conviertan en cambios funcionales en lugar de reescrituras destructivas. Del mantenedor (un vibecoder él mismo): la finalización de objetivos y la tasa de "lo que realmente quería" saltaron al menos 10× después de instalarlo — "10× es el mínimo."
- Desarrolladores senior — quieres un contexto estructurado y auditable que tu agente de IA respete. Cada regla se remonta a un hash de commit o a un evento de error registrado. Sin convenciones alucinadas.
- Equipos — las reglas viven en nodos canónicos
CLAUDE.mdjusto al lado del código que gobiernan. Codex lee los mismos nodos a través de MCP, por lo que los equipos evitan el conocimiento dividido. Comparte víagit push.
Inicio rápido
macOS / Linux / WSL
bash <(curl -fsSL https://raw.githubusercontent.com/hilyfux/knowledge-graph/main/standalone/install.sh) /path/to/your-project
Windows (PowerShell + Git Bash)
git clone https://github.com/hilyfux/knowledge-graph.git
cd knowledge-graph
.\standalone\install.ps1 C:\path\to\your-project
Luego:
- Reinicia Claude Code para que los hooks se activen, o conecta tu agente compatible con MCP.
- Para Codex, lee las notas
AGENTS.mdinstaladas y usa el servidor MCPknowledge-graphdesde.mcp.json. - Ejecuta
/knowledge-graph initen Claude Code, o usa herramientas MCP comokg_status,kg_queryykg_read_nodedesde Codex.
A partir de ese momento: seguimiento silencioso en Claude Code, nodos de conocimiento distribuidos por módulo y memoria entre sesiones legible por Codex o cualquier agente compatible con MCP.
vs Alternativas
| Knowledge Graph | mcp-knowledge-graph | Memento | Caveman | |
|---|---|---|---|---|
| Almacenamiento | Archivos simples en tu repositorio | Base de datos Neo4j | Base de datos vectorial | N/D (sin estado) |
| Dependencias | Solo jq | Neo4j + Node.js + Docker | Python + ChromaDB | Python (opcional) |
| Aprende con el tiempo | ✅ Motor de inferencia | ❌ | ❌ | ❌ |
| Predice contexto | ✅ Análisis de co-cambio | ❌ | ❌ | ❌ |
Sobrevive a clear / compact | ✅ Instantánea + @include | N/D | N/D | N/D |
| Costo de LLM | Casi cero (bash calcula) | Cada consulta | Costos de embedding | Cero |
| Compartir en equipo | git push | Exportación manual de BD | Exportación manual de BD | N/D |
| Multi-agente (Codex / MCP) | ✅ 7 herramientas + recursos | Parcial | Parcial | ❌ |
| Windows (instalador PowerShell) | ✅ | ❌ | ❌ | ❌ |
Lo que obtienes
- Memoria entre agentes — funciona de forma nativa en Claude Code (hooks); funciona en Codex / Cursor / Windsurf / cualquier cliente MCP a través del servidor incluido (7 herramientas + 22 recursos autoexpuestos)
- Continuidad de sesión a sesión — la instantánea sobrevive a
clearycompact; incluye cambios sin commiteargit statuspara que el agente sepa qué sigue en progreso, no solo lo que se commiteó - Predice errores antes de que ocurran — la predicción de co-cambio precarga prohibiciones de módulos relacionados en el primer acceso; Guarda de tamaño de lectura advierte antes de que una lectura de 25K tokens alcance su límite, para que el agente sepa hacer Grep + lectura parcial en lugar de quemar un viaje de ida y vuelta
- Dependencias autodescubiertas a partir de patrones reales de co-cambio — observa el trabajo, infiere patrones, promueve solo reglas respaldadas por evidencia
- Flujo de trabajo sin interrupciones — el análisis pesado se ejecuta principalmente en los límites de sesión; las sesiones largas reciben una actualización de fondo limitada para que
graph-analysis.jsonno quede obsoleto - Canales de eventos con nombre + esquema — flujos paralelos para rastreadores específicos de dominio (
{channel}-events.jsonl) con forma de evento formal y tolerancia a líneas corruptas. Ver events-schema.md. - Cero dependencias más allá de
jq— sin Docker, sin Neo4j, sin Python, sin servicios, sin demonios. Inspeccionable. Versionable. Sin bloqueo.
Presupuesto de tokens
| Componente | Tokens | Cuándo se carga |
|---|---|---|
| Índice de conocimiento (etiquetas de puntero) | ~300-500 | Siempre (@include) |
| Instantánea de trabajo | ~200-400 | SessionStart / PostCompact |
| Prohibiciones predichas | ~100/módulo | Primer acceso a módulo nuevo |
CLAUDE.md de módulo | ~200/módulo | En acceso a archivo (perezoso) |
| Línea base total | ~500-900 | <0.5% del contexto de 200K |
Cómo funciona (brevemente)
Los hooks se disparan silenciosamente durante tu flujo de trabajo normal de Claude Code:
- Read / Write → eventos registrados en ~3ms; el primer acceso a un módulo dispara una predicción de co-cambio que precarga prohibiciones de módulos relacionados; las sesiones largas con muchas escrituras también disparan una actualización de fondo limitada de
graph-analysis.json - SessionStart / PostCompact → inyecta la última instantánea de trabajo para que el agente retome donde lo dejó
- Stop → guarda la instantánea, rota el registro de eventos, ejecuta análisis de fondo
Bash puro + jq extrae patrones del registro de eventos y del historial de git; el LLM solo participa cuando un nodo de conocimiento realmente necesita ser (re)escrito. Todo lo demás es de cero tokens.
Inmersión profunda con tabla completa de hooks, diagrama de pipeline y matriz de supervivencia de contexto: docs/architecture-notes.md.
Para agentes que no son de Claude: los mismos nodos canónicos CLAUDE.md, la instantánea de trabajo y los pares de co-cambio son accesibles a través del servidor MCP.
Comandos
| Comando | Propósito |
|---|---|
/knowledge-graph init | Escaneo completo del proyecto. Genera CLAUDE.md canónicos para cada módulo. |
/knowledge-graph update | Actualización incremental + motor de inferencia. |
/knowledge-graph status | Cobertura, salud, puntos ciegos, mapa de calor de actividad. |
/knowledge-graph query <question> | Busca en el grafo; obtén respuestas con fuentes. |
Qué se genera
Cada directorio de módulo recibe un nodo canónico compacto CLAUDE.md (≤20 líneas, máxima densidad de información). Codex consume el mismo nodo a través de MCP en lugar de mantener un AGENTS.md duplicado.
# auth
## Prohibitions
- Raw token in localStorage → XSS (a3f21b)
- Skip refresh in test mock → flaky CI (8c4e01)
## When Changing
- Token flow → @middleware/CLAUDE.md
- User model → @api/users/CLAUDE.md
## Conventions
- Auth errors: 401 + {code, message}
- Refresh tokens: httpOnly cookies only
Las referencias @ forman el grafo de dependencias. El motor de inferencia las descubre y las añade automáticamente a partir de patrones de co-cambio.
Servidor MCP
7 herramientas y un canal de recursos expuestos vía MCP, utilizables desde cualquier agente compatible con MCP (Codex, Cursor, Windsurf, Claude Desktop, clientes personalizados):
| Herramienta | Descripción |
|---|---|
kg_status | Cobertura, eventos pendientes, recuento de puntos ciegos, zonas calientes, fallos recientes |
kg_query | Búsqueda de texto completo en todos los cuerpos canónicos CLAUDE.md / SKILL.md — devuelve path:line:excerpt |
kg_read_node | Obtiene el nodo de conocimiento completo para un módulo específico |
kg_recent_work | Instantánea de trabajo actual — módulos activos, cambios sin commitear, commits recientes |
kg_predict | Predice módulos relacionados para una ruta de archivo (historial de co-cambio) |
kg_cochange | Pares de directorios con mayor co-cambio — dependencias implícitas |
kg_blind_spots | Módulos con actividad pero sin nodo de conocimiento |
Además, Recursos: cada CLAUDE.md / SKILL.md canónico se expone a través de kg://node/<path>, kg://claude/<path> o kg://skill/<path>. El índice de conocimiento está en kg://index; la instantánea de trabajo en kg://snapshot.
Auto-registrado en .mcp.json durante la instalación.
Principios de diseño
- Cero interrupciones. Nunca bloquea tu codificación. El análisis se ejecuta en los límites de sesión.
- Bash calcula, LLM decide. La minería de patrones es bash puro (~3ms/evento); el LLM solo escribe prosa.
- Solo basado en evidencia. Cada regla se remonta a un commit, error o análisis. Sin evidencia, sin regla.
- Predice, no reacciones. Precarga conocimiento relacionado antes de los errores, basado en el historial de co-cambio.
- Sobrevive a todo.
clear,compact, sesiones largas — el estado de trabajo persiste a través de instantáneas. - Huella de tokens mínima. Nodos de conocimiento de ≤20 líneas, índice tipo puntero, carga perezosa.
- Salidas independientes del agente. Los hooks son específicos de Claude Code; los nodos canónicos
CLAUDE.md, las herramientas MCP y los recursos son consumibles por Codex y otros agentes.
Requisitos
bash— macOS / Linux: nativo. Windows: Git Bash (winget install Git.Git) o WSL.jq—brew install jq/apt install jq/winget install jqlang.jqgit(opcional, recomendado) — mejora el análisis de dependencias y el rastreo de evidencia- Un agente de IA compatible con MCP: Claude Code de forma nativa, o Codex / Cursor / Windsurf / Claude Desktop a través del servidor MCP incluido
Aprende más
- Instalación — configuración específica por plataforma (macOS / Linux / Windows / WSL)
- Configuración — variables de entorno y ajustes
- Arquitectura — flujo de hooks, motor de predicción, diagrama de pipeline, diseño instalado
- Esquema de eventos — concepto de canal + forma de evento + garantías de tolerancia
- FAQ — preguntas frecuentes
- Changelog — historial de versiones
Contribuciones
Las contribuciones son bienvenidas. Ver CONTRIBUTING.md.
Áreas de alto impacto:
- Nuevos tipos de patrones en
infer.sh - Rendimiento en monorepos grandes (1000+ módulos)
- Medición de precisión de predicción y bucles de retroalimentación
- Pruebas de integración para clientes MCP que no son de Claude
- Integraciones adicionales de agentes más allá de MCP