Knowledge MCP

Um Knowledge Engine para projetos de software: entrega contexto relevante no início de uma tarefa e acumula conhecimento ao final dela. Não é uma memória — a inteligência de decidir o que é relevante e o que merece ser lembrado fica dentro do MCP, não no cliente.

Estado atual

Fase	Escopo	Status
0	Spike técnico das dependências	✅ concluída
1	Núcleo de arquivos (.knowledge/)	✅ concluída
2	KnowledgeStore, IndexBackend, KnowledgeIndexer + contrato	✅ concluída
3	As 5 tools + extractor, sobre backend em memória	✅ concluída
4	Backend Graphiti (recuperação semântica)	✅ concluída
5	Empacotamento e integração	✅ concluída

O MVP é utilizável de ponta a ponta, validado por E2E real através do protocolo MCP.

Os dois backends de índice

O padrão é graphiti: recuperação semântica é o desenho pretendido do produto. Se o Neo4j não estiver no ar, o sistema degrada sozinho para a fonte de verdade — sem erro e sem lentidão (um disjuntor evita repetir o timeout de conexão).

	graphiti (padrão)	memory
Recuperação	semântica (resolve sinônimos)	lexical, com casamento por prefixo
Infraestrutura	Neo4j local (sem Docker)	nenhuma
LLM por gravação	2 chamadas, em background	nenhum
Relacionamentos entre registros	sim (grafo de entidades e fatos)	não

Para subir o Neo4j:

scripts\start-neo4j.cmd

Ele não inicia sozinho com o Windows. Com ele parado, remember, search e context continuam funcionando pela fonte de verdade — só a recuperação semântica fica indisponível, e as tools avisam.

Com assinatura Pro/Max, as chamadas de LLM não são cobradas por token — consomem as janelas de limite do plano. O valor em dólar que o SDK reporta é estimado a preços de tabela da API e serve como proxy de consumo, não como fatura.

Quanto você espera (medido, backend graphiti)

Operação	Tempo
remember	17–27 ms
search, context, start_task	20–50 ms
primeira busca da sessão	~3 s (carrega o modelo na memória)
indexação no grafo	16 s por registro, em background

Você nunca espera pela indexação: remember grava o arquivo e devolve. O grafo alcança depois, e enquanto isso a busca funciona pela fonte de verdade (ADR-004).

O modelo de embedding (~1 GB) é baixado uma vez por máquina, em %LOCALAPPDATA%\knowledge-mcp\models, e compartilhado por todos os projetos.

Com memory, buscar "login" não encontra um registro sobre "autenticação". Com graphiti, encontra — é o que tests/test_semantic_recall.py verifica.

Para ligar o backend semântico:

set KNOWLEDGE_MCP_INDEX=graphiti
set KNOWLEDGE_MCP_NEO4J_PASSWORD=sua-senha

Se o Neo4j estiver fora do ar, o sistema continua lendo, escrevendo e buscando pela fonte de verdade — só perde a recuperação semântica.

As cinco tools

Tool	O quê	Escreve?
start_task	Contexto relevante antes de começar uma tarefa	não
context	Consulta livre ao conhecimento do projeto	não
finish_task	Sugere o que merece virar conhecimento permanente	não
remember	Grava o conhecimento aprovado	sim
search	Procura no conhecimento registrado	não

O fluxo de escrita é sempre finish_task → o usuário aprova → remember. O MCP não guarda estado de aprovação: ela vive na conversa (ADR-006).

Arquitetura em uma tela

KnowledgeRepository     único autorizado a escrever em .knowledge — fonte de verdade
        │
        ▼
KnowledgeIndexer        sincroniza .knowledge com o índice; fila, hashes, rebuild
        │
        ▼
KnowledgeStore          apenas consulta: busca, relacionamentos, contexto
        │
        ▼
Graphiti                detalhe de implementação, substituível

As decisões estruturais estão em docs/adr/ e são verificadas mecanicamente por testes em tests/test_architecture_rules.py — uma violação quebra o build, não só a convenção.

Princípios

1. É melhor deixar de registrar um conhecimento do que registrar um conhecimento incorreto. Precisão importa mais que cobertura.
2. A fonte de verdade é o .knowledge/. O índice é reconstruível.
3. Evitar modelagem prematura. Campo, estado ou operação só entra quando houver caso real.
4. O índice é uma aceleração, não uma dependência funcional. Sem o backend de índice, o sistema continua lendo, escrevendo e buscando — só perde qualidade de recuperação.

O formato .knowledge/

.knowledge/
  manifest.yaml       versão do schema, projeto, configuração do índice
  decisions/          um diretório por tipo de registro
  entities/
  preferences/
  conventions/
  technologies/
  summaries/
  cache/              descartável e não versionado (índice, grafo, embeddings)

Cada registro é Markdown com frontmatter de exatamente quatro campos:

---
id: dec-20260731-adiar-a-escolha-do-backend-de-grafo
type: decision
title: Adiar a escolha do backend de grafo
created_at: 2026-07-31
---
**Contexto:** ...
**Decisão:** ...
**Consequências:** ...

O id é a identidade do registro; o caminho do arquivo é detalhe de armazenamento. Renomear ou mover o arquivo à mão não cria um registro novo.

O formato é deliberadamente aberto: qualquer ferramenta deve conseguir produzi-lo ou consumi-lo — scripts, outros MCPs, outras IDEs, ou o próprio desenvolvedor editando à mão.

Instalação

Requer Python 3.13 (o 3.14 ainda não tem wheels para parte das dependências de grafo) e o Claude Code autenticado — o MCP usa a sessão existente, sem chave de API separada.

py -3.13 -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"

Registrar no Claude Code

O servidor descobre a raiz do projeto pelo diretório de trabalho, então um registro global serve todos os seus projetos — cada um ganha seu próprio .knowledge/.

claude mcp add knowledge --scope user -- C:\Users\guilh\.virtualenvs\knowledge-mcp\Scripts\knowledge-mcp.exe

Para registrar só num projeto, crie um .mcp.json na raiz dele:

{
  "mcpServers": {
    "knowledge": {
      "command": "C:\\Users\\guilh\\.virtualenvs\\knowledge-mcp\\Scripts\\knowledge-mcp.exe"
    }
  }
}

Para apontar para um projeto fixo, independentemente do diretório de trabalho, defina a variável de ambiente KNOWLEDGE_MCP_PROJECT.

Verifique a conexão com:

claude -p "/mcp" --mcp-config .mcp.json

Como usar

O fluxo natural é conversacional — você não gerencia conhecimento:

1. Ao começar algo, o agente chama start_task e recebe as decisões, regras e convenções que importam para aquela tarefa.
2. Ao terminar, ele chama finish_task com um resumo. O MCP responde com uma sugestão do que merece ser lembrado — sem gravar nada.
3. Você aprova (ou não) na conversa. Só então o agente chama remember.

search e context ficam disponíveis para consulta a qualquer momento.

Desenvolvimento

python -m pytest

Os testes em tests/test_architecture_rules.py verificam as decisões dos ADRs mecanicamente: escrever em .knowledge/ fora do repositório, ou importar graphiti_core fora de store/graphiti/, quebra o build.