kg - grafo de conocimiento local para tus asistentes de IA

Beta - Las APIs pueden cambiar y aún se esperan algunos errores.

kg le da a tu asistente de IA una memoria de proyecto persistente, estructurada y editable, almacenada localmente como un grafo de conocimiento.

En lugar de depender solo de la recuperación de fragmentos de documentos, puedes mantener arquitectura, decisiones, incidentes, reglas, dependencias y flujos de trabajo en un grafo que sea legible, revisable y compatible con Git.

Úsalo cuando quieras que tu asistente entienda un proyecto existente a lo largo de las sesiones, no que empiece desde cero cada vez.

Por qué usarlo

• Memoria persistente — mantén el conocimiento del proyecto entre conversaciones

• Estructurado, no difuso — inspecciona nodos, aristas, hechos y vacíos directamente

• Editable y revisable — almacena grafos como archivos *.kg con diffs legibles

• Local primero — la memoria de tu proyecto permanece en tu máquina en un formato compatible con Git

• Funciona con clientes MCP — conéctalo como un servidor MCP stdio local

Related MCP server: Agentic Memory Server

Por qué no solo RAG

El RAG clásico es bueno para recuperar fragmentos de texto de documentos.

kg-mcp es mejor cuando quieres:

• memoria de proyecto estable en lugar de recuperación repetida

• hechos, relaciones y dependencias explícitos

• actualizaciones del grafo durante el trabajo real con el asistente

• algo que puedas inspeccionar, versionar, comparar y mejorar con el tiempo

Instalación

Desde crates.io

cargo install kg-cli

Desde script

Instalación recomendada:

curl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh

También puedes descargar un binario listo desde GitHub Releases.

Conecta kg-mcp a tu cliente de IA

Añade kg-mcp como un servidor MCP stdio local.

Configuración de ejemplo:

{
  "mcpServers": {
    "kg": {
      "command": "/absolute/path/to/kg-mcp"
    }
  }
}

Después de eso:

1. reinicia tu cliente de IA,

2. confirma que el servidor MCP kg está disponible,

3. empieza a usar los prompts a continuación.

Configuración completa y referencia de MCP: docs/mcp.md

Inicio rápido con SCL

kg entiende comandos cortos en inglés con verbo primero (SCL — Simple Command Language). El grafo activo se resuelve automáticamente desde tu configuración.

find "compressor defrost"
get concept:refrigerator
add concept:smart_fridge --name "Smart Fridge" --description "Connected refrigerator"
modify concept:smart_fridge --importance 0.9
remove concept:old_idea
connect process:compressor_control TRIGGERS process:auto_defrost
disconnect process:compressor_control TRIGGERS process:auto_defrost
list nodes
stats
use fridge
help

Verbos principales

IDs

Formato: <type>:snake_case — por ejemplo, concept:fridge, bug:door_seal, process:compressor_cycle.

Relaciones

HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM

Consejos

• Las banderas van después de los argumentos posicionales. Pon entre comillas los valores de varias palabras.

• Separa comandos con ; o saltos de línea. Las líneas que empiezan con # son comentarios.

• Usa use <graph> para cambiar de grafo dentro de un script.

• Los comandos canónicos kg <graph> node find ... siguen funcionando como respaldo.

• Referencia completa de SCL: docs/scl.md

Generar un grafo

Este es el primer flujo de trabajo para un proyecto nuevo: pide al asistente que cree o amplíe un grafo a partir de tu documentación.

Por defecto, los grafos se almacenan en ~/.kg/graphs como archivos *.kg.

Prompt mínimo:

You are connected to kg-mcp.

Project graph name: payments

Build or extend this graph from the project documentation I provide.
Use `payments` as the graph name for all graph operations.

Only add facts grounded in source material.
If an important fact is missing and can be inferred safely from the provided docs, update the graph.
If something is ambiguous, ask or record it as a note instead of inventing facts.

Ejemplo de prompt con documentos:

Use kg-mcp to build or extend the `payments` graph from these documents:
- docs/payments/overview.md
- docs/payments/retries.md
- docs/payments/providers.md

Only add facts grounded in the documents.
If something is ambiguous, keep it out of the graph or record it as a note.
When you finish, summarize what was added, what remains unclear, and what document should be ingested next.

Prompt más largo para este flujo de trabajo: docs/ai-prompt-graph-from-docs.md

Para un ejemplo de repositorio listo, ejecuta cargo run --bin repo-example para generar repo-example.kg desde este repositorio.

Grafo automático para un directorio

kg puede convertir una carpeta existente en un grafo automáticamente. Escanea el árbol de directorios, reconoce muchos tipos de archivos comunes, extrae símbolos para Rust, Java, JavaScript/TypeScript, Python y C/C++, y mantiene la estructura generada separada del grafo manual.

Para documentos similares a Markdown, también crea nodos de documento (GDOC) y capítulo (GSEC) con el contenido de las secciones.

Es una forma rápida de obtener un mapa útil de un código base o espacio de trabajo sin modelar todo a mano. El índice generado es local, actualizable y seguro de ignorar en Git.

Ejemplo:

cargo run --bin repo-example

Esto genera repo-example.kg desde este repositorio como una demo local.

Pregunta al asistente sobre hechos en el grafo

Una vez que el grafo existe, el flujo de trabajo normal es pedir al asistente que lo inspeccione y responda preguntas a partir de él.

Ejemplo de prompt:

Use kg-mcp to inspect my existing `payments` graph.

I want to understand:
- how payment authorization works,
- what triggers retries,
- which external providers are involved,
- which datastore reads and writes are part of the flow.

If the graph is missing critical information, say exactly what is missing.

Otras preguntas útiles:

• ¿Qué reglas controlan los reintentos en el grafo payments?

• ¿Qué sistemas escriben en el almacén de datos de pedidos?

• ¿Qué falta o es débil en este grafo?

• ¿Qué nodos y aristas explican el flujo de autorización?

Añade o actualiza hechos a través del asistente

También puedes pedir al asistente que mejore el grafo mientras trabajas.

Ejemplo de prompt:

Use kg-mcp to review my existing `payments` graph.

Find:
- missing important nodes,
- weak descriptions,
- missing facts,
- suspicious or low-value edges.

Apply safe improvements where possible.
Only add facts grounded in the graph, the provided docs, or the current discussion.
If something is ambiguous, leave it out or add a note.

When you finish, summarize:
- what was wrong,
- what you changed,
- what still needs manual review.

Esto funciona mejor cuando tu prompt principal del sistema o del proyecto ya le dice al asistente qué grafo pertenece al proyecto.

Prompt mínimo a nivel de proyecto:

You are connected to kg-mcp.
Project graph name: payments.
Use this graph for relevant reads and updates in this project.
If you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.
If uncertain, ask or add a note instead of inventing facts.

Consejos

Configuración del proyecto (.kg.toml)

kg busca .kg.toml en el directorio actual y en sus directorios padre.

Ejemplo:

backend = "json" # json backend writes native .kg files by default
graph_dir = ".kg/graphs"
graph_dirs = ["../shared-graphs", "../team-graphs"]
nudge = 20
user_short_uid = "dev_01"

[graphs]
payments = "graphs/payments.kg"

Notas:

• backend = "json" es el valor predeterminado y prefiere grafos de texto .kg.

• backend = "redb" almacena grafos en archivos .db.

• graph_dir establece un directorio de grafos principal.

• graph_dirs añade directorios adicionales escaneados por kg list y la resolución de grafos.

Mantén los grafos en Git

El directorio de grafos predeterminado es ~/.kg/graphs.

Puedes poner ese directorio bajo Git.

Enfoque recomendado:

• mantén los archivos de grafo principales *.kg en Git,

• ignora los archivos secundarios generados y los archivos operativos locales,

• trata las instantáneas de respaldo y los registros de eventos como historial local de la máquina, a menos que quieras versionarlos explícitamente.

.gitignore sugerido:

*.kglog
*.kgindex
*.event.log
*.migration.log
*.bak
*.bck.*.gz

En la práctica:

• *.kg es el archivo de grafo principal que normalmente quieres revisar y confirmar,

• *.kglog es un registro local de acceso/retroalimentación,

• *.kgindex es un índice local generado,

• *.event.log es una línea de tiempo local de cambios de solo añadir,

• *.bak es la versión anterior en disco de la última escritura,

• *.bck.*.gz son instantáneas de respaldo comprimidas periódicas,

• *.migration.log es un informe de migración cuando se convierten grafos antiguos.

*.kg es compatible con Git y está estructurado intencionalmente para que los diffs sean legibles y las fusiones sean más fáciles cuando varias personas trabajan en el mismo grafo.

Exportar un grafo a HTML

Para generar una vista HTML interactiva de un grafo:

kg graph payments export-html --output payments.html

Puedes conservar el HTML generado como una instantánea visual compartible del grafo actual.

Documentación

• docs/mcp.md - Configuración de MCP y referencia de herramientas

• docs/ai-prompt-graph-from-docs.md - prompt más largo para la ingesta de documentos

• docs/build-graph-from-docs.md - flujo de trabajo de construcción de grafos a partir de documentos

• docs/troubleshooting.md - problemas comunes

Contacto

Para preguntas o comentarios: nnar10@proton.me