Kg

Grafo de conhecimento leve

GitHub
9
Experimente este MCPPatrocinado

Documentação

kg - grafo de conhecimento local para seus assistentes de IA

image

CI Release License

Beta - As APIs ainda podem mudar e alguns bugs ainda são esperados.

kg dá ao seu assistente de IA memória de projeto persistente, estruturada e editável, armazenada localmente como um grafo de conhecimento.

Em vez de depender apenas da recuperação de trechos de documentos, você pode manter arquitetura, decisões, incidentes, regras, dependências e fluxos de trabalho em um grafo que é legível, revisável e amigável ao Git.

Use-o quando quiser que seu assistente entenda um projeto existente entre sessões — não comece do zero toda vez.

Por que usar

  • Memória persistente — mantenha o conhecimento do projeto entre conversas
  • Estruturado, não vago — inspecione nós, arestas, fatos e lacunas diretamente
  • Editável e revisável — armazene grafos como arquivos *.kg com diffs legíveis
  • Local-first — a memória do seu projeto permanece na sua máquina em formato amigável ao Git
  • Funciona com clientes MCP — conecte-o como um servidor MCP stdio local

Por que não apenas RAG

RAG clássico é bom para recuperar trechos de texto de documentos.

kg-mcp é melhor quando você quer:

  • memória de projeto estável em vez de recuperação repetida
  • fatos, relações e dependências explícitos
  • atualizações do grafo durante o trabalho real com o assistente
  • algo que você possa inspecionar, versionar, comparar e melhorar ao longo do tempo

Instalação

A partir do crates.io

cargo install kg-cli

A partir do script

Instalação recomendada:

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

Você também pode baixar um binário pronto das Releases do GitHub.

Conecte kg-mcp ao Seu Cliente de IA

Adicione kg-mcp como um servidor MCP stdio local.

Exemplo de configuração:

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

Depois disso:

  1. reinicie seu cliente de IA,
  2. confirme que o servidor MCP kg está disponível,
  3. comece a usar os prompts abaixo.

Configuração completa e referência MCP: docs/mcp.md

Início rápido com SCL

kg entende comandos curtos em inglês com verbo primeiro (SCL — Simple Command Language). O grafo ativo é resolvido automaticamente a partir da sua configuração.

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 principais

VerboO que faz
find <query>busca nós por texto
get <id>busca um nó por id
add <id> --name "Name"cria um nó (tipo inferido do prefixo do id)
modify <id> --field valueatualiza campos do nó
remove <id>exclui um nó
connect <src> <REL> <dst>cria uma aresta (alias: add edge)
disconnect <src> <REL> <dst>exclui uma aresta (alias: remove edge)
list nodes|edges|types|relations|graphslista o conteúdo do grafo
statsmostra estatísticas do grafo
use <graph>alterna o grafo ativo
help [verb]obtém ajuda para um verbo ou todos
feedback <uid> yes|no|nil|pick <n>dá feedback sobre resultados de busca
strictdesativa padrões para as linhas seguintes

IDs

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

Relações

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

Dicas

  • As flags vêm depois dos argumentos posicionais. Coloque valores com várias palavras entre aspas.
  • Separe comandos com ; ou novas linhas. Linhas que começam com # são comentários.
  • Use use <graph> para alternar grafos dentro de um script.
  • Comandos canônicos kg <graph> node find ... ainda funcionam como fallback.
  • Referência completa do SCL: docs/scl.md

Gerar um Grafo

Este é o primeiro fluxo de trabalho para um novo projeto: peça ao assistente para criar ou estender um grafo a partir da sua documentação.

Por padrão, os grafos são armazenados em ~/.kg/graphs como arquivos *.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.

Exemplo de prompt com 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 mais longo para este fluxo de trabalho: docs/ai-prompt-graph-from-docs.md

Para um exemplo de repositório pronto, execute cargo run --bin repo-example para gerar repo-example.kg a partir deste repositório.

Grafo automático para um diretório

kg pode transformar uma pasta existente em um grafo automaticamente. Ele escaneia a árvore de diretórios, reconhece muitos tipos de arquivo comuns, extrai símbolos para Rust, Java, JavaScript/TypeScript, Python e C/C++, e mantém a estrutura gerada separada do grafo manual.

Para documentos semelhantes a markdown, ele também cria nós de documento (GDOC) e capítulo (GSEC) com o conteúdo das seções.

É uma maneira rápida de obter um mapa útil de um codebase ou workspace sem modelar tudo manualmente. O índice gerado é local, atualizável e seguro para ignorar no git.

Exemplo:

cargo run --bin repo-example

Isso gera repo-example.kg a partir deste repositório como uma demonstração local.

Pergunte ao Assistente Sobre Fatos no Grafo

Uma vez que o grafo existe, o fluxo de trabalho normal é pedir ao assistente para inspecioná-lo e responder perguntas a partir dele.

Exemplo 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.

Outras perguntas úteis:

  • "Quais regras controlam tentativas no grafo payments?"
  • "Quais sistemas escrevem no armazenamento de dados de pedidos?"
  • "O que está faltando ou fraco neste grafo?"
  • "Quais nós e arestas explicam o fluxo de autorização?"

Adicionar ou Atualizar Fatos Através do Assistente

Você também pode pedir ao assistente para melhorar o grafo enquanto trabalha.

Exemplo 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.

Isso funciona melhor quando o prompt principal do sistema ou o prompt do projeto já informa ao assistente qual grafo pertence ao projeto.

Prompt mínimo no nível do projeto:

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.

Dicas

Configuração do projeto (.kg.toml)

kg procura por .kg.toml no diretório atual e em seus diretórios pais.

Exemplo:

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" é o padrão e prefere grafos de texto .kg.
  • backend = "redb" armazena grafos em arquivos .db.
  • graph_dir define um diretório principal de grafos.
  • graph_dirs adiciona diretórios extras escaneados por kg list e resolução de grafos.

Mantenha Grafos no Git

O diretório padrão de grafos é ~/.kg/graphs.

Você pode colocar esse diretório sob o git.

Abordagem recomendada:

  • mantenha os arquivos de grafo principais *.kg no git,
  • ignore sidecars gerados e arquivos operacionais locais,
  • trate snapshots de backup e logs de eventos como histórico local da máquina, a menos que você queira versioná-los explicitamente.

Sugestão de .gitignore:

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

Na prática:

  • *.kg é o arquivo de grafo principal que você geralmente quer revisar e commitar,
  • *.kglog é um log local de acesso/feedback,
  • *.kgindex é um índice local gerado,
  • *.event.log é uma linha do tempo local de alterações somente anexação,
  • *.bak é a versão anterior em disco da última gravação,
  • *.bck.*.gz são snapshots de backup compactados periódicos,
  • *.migration.log é um relatório de migração quando grafos mais antigos são convertidos.

*.kg é amigável ao Git e intencionalmente estruturado para tornar os diffs legíveis e os merges mais fáceis quando várias pessoas trabalham no mesmo grafo.

Exportar um Grafo para HTML

Para gerar uma visualização HTML interativa de um grafo:

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

Você pode manter o HTML gerado como um snapshot visual compartilhável do grafo atual.

Documentação

Contato

Para perguntas ou feedback: nnar10@proton.me