# 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:

```bash
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:

```bash
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](docs/adr/ADR-006-approval-happens-in-the-client.md)).

## 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/`](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:

```markdown
---
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.

```bash
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/`.

```bash
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:

```json
{
  "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:

```bash
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

```bash
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.