Kg

Grafo de conocimiento ligero

GitHub
9
Prueba este MCPPatrocinado

Documentación

kg - grafo de conocimiento local para tus asistentes de IA

image

CI Release License

Beta - Las APIs pueden cambiar y todavía 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 entre 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 formato compatible con Git
  • Funciona con clientes MCP — conéctalo como un servidor MCP local stdio

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ícitas
  • 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

Agrega kg-mcp como un servidor MCP local stdio.

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. comienza a usar los prompts a continuación.

Configuración completa de MCP y referencia: 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

VerboQué hace
find <query>busca nodos por texto
get <id>obtiene un nodo por id
add <id> --name "Name"crea un nodo (el tipo se infiere del prefijo del id)
modify <id> --field valueactualiza campos de un nodo
remove <id>elimina un nodo
connect <src> <REL> <dst>crea una arista (alias: add edge)
disconnect <src> <REL> <dst>elimina una arista (alias: remove edge)
list nodes|edges|types|relations|graphslista el contenido del grafo
statsmuestra estadísticas del grafo
use <graph>cambia el grafo activo
help [verb]obtén ayuda para un verbo o para todos
feedback <uid> yes|no|nil|pick <n>da retroalimentación sobre resultados de búsqueda
strictdesactiva los valores predeterminados para las líneas siguientes

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 con varias palabras.
  • Separa comandos con ; o saltos de línea. Las líneas que comienzan 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: pídele 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.

Prompt de ejemplo 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 demostración local.

Pregúntale al asistente sobre hechos en el grafo

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

Prompt de ejemplo:

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?"

Agregar o actualizar hechos a través del asistente

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

Prompt de ejemplo:

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 indica 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 agrega 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 copias de seguridad 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 querrás 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 agregar,
  • *.bak es la versión anterior en disco de la última escritura,
  • *.bck.*.gz son copias de seguridad 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

Contacto

Para preguntas o retroalimentación: nnar10@proton.me