Knowledge Graph
Uma camada de memória persistente orientada por grafo de conhecimento para agentes de codificação e fluxos de trabalho de LLM.
Documentação
Knowledge Graph para Claude Code e Codex
Memória persistente e nativa do git que faz seu agente de codificação com IA realmente lembrar. Zero bancos de dados, zero serviços — apenas bash, jq e seus próprios commits.
Claude Code e outros agentes de codificação com IA esquecem tudo entre sessões — você acaba reexplicando o mesmo contexto do projeto toda vez. O Knowledge Graph resolve isso transformando suas operações de arquivo e o histórico do git em uma camada de memória leve e baseada em evidências que vive dentro do seu repositório.
Suporte de primeira classe para:
- Claude Code — rastreia automaticamente leituras e escritas via hooks, injeta um snapshot de trabalho a cada início de sessão, reconstrói o contexto após
/cleare/compact - Codex / Cursor / Windsurf / qualquer cliente MCP — 7 ferramentas e mais de 20 recursos expostos pelo servidor MCP stdio incluído (
kg_read_node,kg_query,kg_recent_work,kg_blind_spots, …)
Sem embeddings. Sem bancos vetoriais. Sem serviços externos. Funciona em macOS, Linux e Windows.
Para quem é
- Vibecoders — você descreve a intenção, o agente escreve o código. O Knowledge Graph dá ao agente o contexto do projeto que você nunca precisou aprender, então solicitações de uma linha se transformam em mudanças funcionais em vez de reescritas destrutivas. Do mantenedor (ele próprio um vibecoder): a taxa de conclusão de objetivos e de "era isso que eu queria" saltou pelo menos 10× após a instalação — "10× é o piso."
- Desenvolvedores seniores — você quer contexto estruturado e auditável que seu agente de IA respeite. Cada regra remonta a um hash de commit ou a um evento de erro registrado. Sem convenções alucinadas.
- Equipes — as regras vivem em nós canônicos
CLAUDE.mdao lado do código que governam. O Codex lê os mesmos nós via MCP, então as equipes evitam conhecimento dividido. Compartilhe viagit push.
Início 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
Em seguida:
- Reinicie o Claude Code para que os hooks sejam ativados, ou conecte seu agente compatível com MCP.
- Para Codex, leia as notas
AGENTS.mdinstaladas e use o servidor MCPknowledge-graphde.mcp.json. - Execute
/knowledge-graph initno Claude Code, ou use ferramentas MCP comokg_status,kg_queryekg_read_nodea partir do Codex.
A partir daí: rastreamento silencioso no Claude Code, nós de conhecimento distribuídos por módulo e memória entre sessões legível pelo Codex ou por qualquer agente compatível com MCP.
vs Alternativas
| Knowledge Graph | mcp-knowledge-graph | Memento | Caveman | |
|---|---|---|---|---|
| Armazenamento | Arquivos simples no seu repositório | Banco de dados Neo4j | Banco de dados vetorial | N/A (sem estado) |
| Dependências | Apenas jq | Neo4j + Node.js + Docker | Python + ChromaDB | Python (opcional) |
| Aprende com o tempo | ✅ Mecanismo de inferência | ❌ | ❌ | ❌ |
| Prevê contexto | ✅ Análise de co-mudança | ❌ | ❌ | ❌ |
Sobrevive a clear / compact | ✅ Snapshot + @include | N/A | N/A | N/A |
| Custo de LLM | Quase zero (bash calcula) | A cada consulta | Custos de embedding | Zero |
| Compartilhamento em equipe | git push | Exportação manual do banco de dados | Exportação manual do banco de dados | N/A |
| Multi-agente (Codex / MCP) | ✅ 7 ferramentas + recursos | Parcial | Parcial | ❌ |
| Windows (instalador PowerShell) | ✅ | ❌ | ❌ | ❌ |
O Que Você Obtém
- Memória entre agentes — funciona nativamente no Claude Code (hooks); funciona no Codex / Cursor / Windsurf / qualquer cliente MCP através do servidor incluído (7 ferramentas + 22 recursos expostos automaticamente)
- Continuidade entre sessões — o snapshot sobrevive a
clearecompact; inclui alterações não commitadasgit statuspara que o agente saiba o que ainda está em andamento, não apenas o que foi commitado - Preveja erros antes que aconteçam — a previsão de co-mudança pré-carrega proibições de módulos relacionados no primeiro acesso; proteção de tamanho de leitura avisa antes que uma leitura de 25K tokens atinja seu limite, para que o agente saiba usar Grep + leitura parcial em vez de queimar uma ida e volta
- Dependências descobertas automaticamente a partir de padrões reais de co-mudança — observe o trabalho, infira padrões, promova apenas regras baseadas em evidências
- Fluxo de trabalho sem interrupções — a análise pesada roda principalmente nos limites de sessão; sessões longas recebem uma atualização em segundo plano limitada para que
graph-analysis.jsonnão fique desatualizado - Canais de eventos nomeados + schema — fluxos paralelos para rastreadores específicos de domínio (
{channel}-events.jsonl) com formato formal de eventos e tolerância a linhas corrompidas. Veja events-schema.md. - Zero dependências além de
jq— sem Docker, sem Neo4j, sem Python, sem serviços, sem daemon. Inspecionável. Versionável. Sem aprisionamento.
Orçamento de Tokens
| Componente | Tokens | Quando carregado |
|---|---|---|
| Índice de conhecimento (tags de ponteiro) | ~300-500 | Sempre (@include) |
| Snapshot de trabalho | ~200-400 | SessionStart / PostCompact |
| Proibições previstas | ~100/módulo | Primeiro acesso a novo módulo |
CLAUDE.md de módulo | ~200/módulo | No acesso a arquivos (preguiçoso) |
| Total base | ~500-900 | <0,5% do contexto de 200K |
Como Funciona (resumidamente)
Os hooks disparam silenciosamente durante seu fluxo de trabalho normal no Claude Code:
- Read / Write → eventos registrados em ~3ms; o primeiro acesso a um módulo dispara uma previsão de co-mudança que pré-carrega proibições de módulos relacionados; sessões longas com muitas escritas também disparam uma atualização em segundo plano limitada de
graph-analysis.json - SessionStart / PostCompact → injeta o último snapshot de trabalho para que o agente continue de onde parou
- Stop → salva o snapshot, rotaciona o log de eventos, executa análise em segundo plano
Bash puro + jq extrai padrões do log de eventos e do histórico do git; o LLM só é envolvido quando um nó de conhecimento realmente precisa ser (re)escrito. Todo o resto é zero-token.
Mergulho profundo com tabela completa de hooks, diagrama de pipeline e matriz de sobrevivência de contexto: docs/architecture-notes.md.
Para agentes que não são Claude: os mesmos nós canônicos CLAUDE.md, snapshot de trabalho e pares de co-mudança são acessíveis via servidor MCP.
Comandos
| Comando | Finalidade |
|---|---|
/knowledge-graph init | Varredura completa do projeto. Gera CLAUDE.md canônicos para cada módulo. |
/knowledge-graph update | Atualização incremental + mecanismo de inferência. |
/knowledge-graph status | Cobertura, saúde, pontos cegos, mapa de calor de atividade. |
/knowledge-graph query <question> | Pesquise no grafo; obtenha respostas com fontes. |
O Que É Gerado
Cada diretório de módulo recebe um nó canônico compacto CLAUDE.md (≤20 linhas, densidade máxima de informação). O Codex consome o mesmo nó via MCP em vez de manter um 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
Referências @ formam o grafo de dependências. O mecanismo de inferência as descobre e adiciona automaticamente a partir de padrões de co-mudança.
Servidor MCP
7 ferramentas e um canal de recursos expostos via MCP, utilizáveis por qualquer agente compatível com MCP (Codex, Cursor, Windsurf, Claude Desktop, clientes personalizados):
| Ferramenta | Descrição |
|---|---|
kg_status | Cobertura, eventos pendentes, contagem de pontos cegos, zonas quentes, falhas recentes |
kg_query | Pesquisa de texto completo em todos os corpos canônicos CLAUDE.md / SKILL.md — retorna path:line:excerpt |
kg_read_node | Busca o nó de conhecimento completo de um módulo específico |
kg_recent_work | Snapshot de trabalho atual — módulos ativos, alterações não commitadas, commits recentes |
kg_predict | Prevê módulos relacionados para um caminho de arquivo (histórico de co-mudança) |
kg_cochange | Principais pares de diretórios com co-mudança — dependências implícitas |
kg_blind_spots | Módulos com atividade, mas sem nó de conhecimento |
Além de Recursos: cada CLAUDE.md / SKILL.md canônico é exposto através de kg://node/<path>, kg://claude/<path> ou kg://skill/<path>. O índice de conhecimento está em kg://index; o snapshot de trabalho em kg://snapshot.
Registrado automaticamente em .mcp.json durante a instalação.
Princípios de Design
- Zero interrupções. Nunca bloqueia sua codificação. A análise roda nos limites de sessão.
- Bash calcula, LLM decide. A mineração de padrões é bash puro (~3ms/evento); o LLM só escreve prosa.
- Somente baseado em evidências. Cada regra remonta a um commit, erro ou análise. Sem evidência, sem regra.
- Preveja, não reaja. Pré-carregue conhecimento relacionado antes de erros, com base no histórico de co-mudança.
- Sobreviva a tudo.
clear,compact, sessões longas — o estado de trabalho persiste através de snapshots. - Pegada mínima de tokens. Nós de conhecimento de ≤20 linhas, índice estilo ponteiro, carregamento preguiçoso.
- Saídas agnósticas de agente. Os hooks são específicos do Claude Code; nós canônicos
CLAUDE.md, ferramentas MCP e recursos são consumíveis pelo Codex e outros agentes.
Requisitos
bash— macOS / Linux: nativo. Windows: Git Bash (winget install Git.Git) ou WSL.jq—brew install jq/apt install jq/winget install jqlang.jqgit(opcional, recomendado) — aprimora a análise de dependências e o rastreamento de evidências- Um agente de IA compatível com MCP: Claude Code nativamente, ou Codex / Cursor / Windsurf / Claude Desktop via o servidor MCP incluído
Saiba Mais
- Instalação — configuração específica por plataforma (macOS / Linux / Windows / WSL)
- Configuração — variáveis de ambiente e ajustes
- Arquitetura — fluxo de hooks, mecanismo de previsão, diagrama de pipeline, layout instalado
- Schema de Eventos — conceito de canal + formato de evento + garantias de tolerância
- FAQ — perguntas frequentes
- Changelog — histórico de versões
Contribuindo
Contribuições são bem-vindas. Veja CONTRIBUTING.md.
Áreas de alto impacto:
- Novos tipos de padrão em
infer.sh - Desempenho em monorepos grandes (1000+ módulos)
- Medição de precisão de previsão e ciclos de feedback
- Testes de integração para clientes MCP que não são Claude
- Integrações adicionais de agentes além do MCP