Compilar Conhecimento

Visão Geral

Conhecimento durável vale a pena ser mantido em muitos arquivos pequenos e interligados de markdown compilados ao longo do tempo e apresentados através de um índice — não como um documento gigante, um histórico de chat ou um item notes.md que se deteriora. Essa habilidade torna a compilação consistente, de modo que o que um agente aprende em uma sessão é recuperável na próxima, em vez de ser recalculado do zero.

O formato é deliberadamente simples: um fato por arquivo, uma linha description para que a recuperação combine, links [[slug]] entre arquivos relacionados e uma única linha de índice por entrada. A parte difícil não é o formato — é a disciplina de escrever apenas o que é durável e de atualizar um arquivo existente em vez de criar um quase duplicado.

Quando Usar Esta Habilidade

• Use quando você acabou de produzir pesquisa, inteligência competitiva, um resumo ou um resultado de investigação, e está prestes a fechar a tarefa — compile antes de fechar.
• Use quando você aprende um fato não óbvio de forma difícil (uma ferramenta que falha silenciosamente, uma medição que contradiz a documentação, uma restrição que ninguém escreveu).
• Use quando o usuário diz "salve isso", "escreva isso na wiki", "atualize a memória", "registre esta descoberta", "estruture este conhecimento" ou "siga o método karpathy".
• Não use para trabalho rotineiro. Um deploy, um reinício ou uma correção de uma linha geralmente não produzem nada durável, e o preenchimento polui a recuperação.

Como Funciona

Passo 1: Escolha o repositório

• Memória do Agente — a pasta por agente que seu harness já carrega (memory/ com um arquivo de índice como MEMORY.md). Este é o padrão e, para um agente solo, geralmente o único repositório que você precisa.
• Wiki Compartilhada — uma pasta wiki/ com wiki/index.md, para conhecimento que toda a equipe, de outra forma, recalcularia. Pule completamente se você trabalha sozinho; não fabrique cerimônia de equipe.

Regra geral: "apenas eu ajo sobre isso" vai para a memória, "qualquer pessoa da minha equipe pode precisar disso" vai para a wiki. Interligue os dois com [[slug]] em vez de copiar o fato para ambos.

Passo 2: Passe pelo portão de higiene

Compile apenas um fato que seja durável e não óbvio. Pule se for derivável do repositório, do histórico do git ou da documentação existente; se for verdadeiro apenas para esta conversa; ou se um arquivo existente já o cobrir — neste último caso, atualize esse arquivo.

Passo 3: Pesquise antes de escrever

Use grep no repositório e examine o índice para o tópico. Um quase duplicado é pior do que nenhuma entrada, porque a recuperação então tem duas respostas e nenhuma maneira de escolher entre elas.

Passo 4: Escreva um arquivo atômico

Um fato por arquivo. Dois fatos não relacionados são dois arquivos. Nomeie-o como um slug em kebab-case — o slug é o alvo do link, então ele precisa ser adivinhável pelo próximo leitor. O frontmatter carrega name (igual ao slug), uma linha description específica o suficiente para ser correspondida durante a recuperação, e um tipo ou categoria. No corpo, declare o fato claramente e vincule entradas relacionadas com [[slug]] liberalmente; um link para um arquivo que ainda não existe é um bom marcador TODO, não um erro.

Passo 5: Adicione exatamente uma linha de índice

Use uma linha no formato - Title → slug.md — hook, com cerca de 200 caracteres. Os detalhes vivem no arquivo; uma linha de índice que reafirma o arquivo anula o propósito de ter um índice. Crie o índice se ele estiver faltando, ou o repositório for indescobrível.

Passo 6: Envelheça o fato em vez de deixá-lo apodrecer

Fatos expiram. Quando um é sensível ao tempo ou substitui um mais antigo, diga isso no frontmatter para que a recuperação possa rebaixá-lo em vez de servir uma verdade desatualizada:

• valid_to: YYYY-MM-DD — a data em que o fato precisa de uma nova verificação.
• supersedes: <slug> — o fato mais antigo que este substitui. Prefira isso em vez de editar no local quando o valor antigo ainda vale a pena ver; edite no local quando não vale.
• confidence: high|medium|low — para que uma intuição nunca tenha precedência sobre uma medição.
• provenance: "<source>" — de onde o fato veio, distinto de quem escreveu a nota.

Todos os quatro são opcionais e portáteis; omiti-los não muda nada.

Exemplos

Exemplo 1: Um fato medido e não óbvio vai para a memória

---
name: reference_search_api_counts_prs_as_issues
description: "O endpoint /search/issues do GitHub conta pull requests em total_count, então um zero lá prova que nem issues nem PRs existem — mas um valor não zero não diz qual."
confidence: high
provenance: "medido em 2026-08-16 enquanto verificava duplicatas de quatro repositórios upstream"
---

`total_count` de `/search/issues?q=<term>+repo:<owner>/<name>` é a soma de issues e

…