Knowl

Seu CLAUDE.md só cresce. Knowl aposenta fatos quando eles mudam.

Início rápido · Por que substituição · O que é armazenado · Recursos · Configuração do agente · Visualizador · Requisitos · Referência completa →

Seu agente começa cada sessão em branco, então você mantém um CLAUDE.md. Ele só cresce. Seis meses depois, ele ainda menciona o banco de dados do qual você migrou na primavera passada, e agora o agente recebe as duas respostas.

Knowl é memória persistente para Claude Code, Cursor e Codex, via MCP ou CLI. Quando um fato é substituído, o antigo é aposentado em vez de competir com o novo. Nenhuma chave de API é necessária. Quando Knowl não tem certeza de que o novo fato substitui o antigo, ele deixa ambos ativos e entrega a você o comando knowl supersede para que você decida.

Desative isso e a recuperação cai de 98% para 47%. De ponta a ponta, de 90 para 73. Como foi medido ↓

Quarenta segundos, uma decisão, três agentes:

Início rápido

Requer Node.js 22 ou posterior. macOS, Linux e Windows.

npm install -g @dat999zx/knowl
cd your-project
knowl init

pnpm add -g @dat999zx/knowl
yarn global add @dat999zx/knowl
bun add -g @dat999zx/knowl

npx @dat999zx/knowl init

knowl init cria .knowl/, instala os arquivos de orientação do projeto, atualiza .gitignore e registra Knowl com quaisquer agentes que detectar. Ele também aquece um modelo de embedding local (~53 MB) em segundo plano — init funciona de qualquer forma, e sem ele você ainda tem busca por palavras-chave.

Essa é toda a configuração. Você não registra memória manualmente: seu agente lê e escreve enquanto trabalha.

Conectando um agente

Claude Code MCP · ciclo de vida · gate	Codex MCP · ciclo de vida · gate	Hermes MCP · ciclo de vida · gate	OpenClaw em processo · plugin · gate	Copilot MCP · ciclo de vida · gate	Cursor MCP · ciclo de vida · gate	OpenHands MCP · ciclo de vida · gate
Antigravity MCP · ciclo de vida · gate	Windsurf MCP · ciclo de vida · gate	Cline MCP · ciclo de vida · plugin	Zed MCP · captura · ACP	JetBrains MCP · captura · ACP	OpenCode MCP · loop manual	Claude Desktop MCP · loop manual

knowl init registra o servidor MCP para cada host que encontrar. Inicie uma nova sessão depois para que o agente capture suas orientações, e ele consultará e gravará memória por conta própria.

gate significa que Knowl pode recusar uma edição que invalide código que outra sessão está mantendo. Neovim e Kiro funcionam da mesma forma que Zed e JetBrains, via knowl acp. Cline precisa de uma linha apontando para o plugin incluído. Hermes Agent recebe um plugin Python, instalado para você, que funciona no terminal e no Hermes Desktop, e pode adicionalmente ser escolhido como provedor de memória do Hermes. OpenClaw roda em processo dentro do seu gateway via um plugin de extensão, avaliando gates de escrita sem overhead de subprocesso — knowl init openclaw o copia e imprime os dois comandos que o registram. Qualquer outro cliente MCP funciona sem integração alguma.

Executando agentes em paralelo? Cada git worktree resolve para o armazenamento do checkout principal — workspaces do Conductor, isolation: "worktree" do Claude Code, ou seus próprios scripts compartilham uma única memória, sem nada para configurar. Como isso funciona, e seu único limite →

→ Cada host, e o que cada um pode fazer · Como os agentes usam · Ferramentas e recursos MCP

A ideia: memória que se aposenta sozinha

A maioria dos sistemas de memória é somente-acréscimo. Armazenar "migramos para SQLite" deixa "usamos PostgreSQL" ativo e recuperável, então o agente recebe ambos e escolhe por classificação. Knowl trata uma escrita sobre o mesmo assunto como uma correção: o predecessor é marcado como superseded, sai da recuperação normal e permanece consultável via knowl timeline.

Esse único comportamento é a maior parte da diferença de precisão. No corpus de Resolução de Conflitos do MemoryAgentBench — 455 fatos, 100 perguntas sobre qual fato é atual, recuperação top-5, sem leitor LLM:

Mesmo corpus, mesmo classificador, mesmo caminho de consulta. A única variável é se o fato desatualizado ainda está ativo. Esta é uma medição em nível de recuperação no próprio harness do Knowl: ele pergunta se o fato atual volta primeiro, sem modelo no loop.

Verificado de ponta a ponta, no harness do próprio benchmark

Como um número que você mesmo pontua vale menos que um que outra pessoa pontua, a mesma afirmação foi re-executada dentro do harness do MemoryAgentBench, pontuada pelo próprio código dele, com um LLM lendo o que Knowl retornou — a configuração mais difícil, totalmente de ponta a ponta, no maior contexto que a tarefa oferece:

18.332 fatos, 100 perguntas, correspondência exata de substring. Cada linha usa gpt-4o-mini como leitor, incluindo o Knowl — o artigo declara isso para todos os agentes RAG e de memória, então estas são comparações justas. Knowl e agentmemory foram medidos aqui; todos os outros números são do artigo do MemoryAgentBench, arXiv 2507.05257v4, Tabela 3. agentmemory não é avaliado nesse artigo — seus números publicados são recall de recuperação do LongMemEval-S, uma tarefa diferente — então ele foi executado no mesmo harness com a mesma configuração, e ambos os adaptadores compartilham um caminho de código de leitor para que nenhum possa se desviar do manipulador RAG do próprio artigo. Método, mecanismo e etapas de reprodução: FINDINGS.md.

Caso contrário, são mostrados todos os sistemas de memória comerciais que o artigo avalia, além do maior pontuador de cada família de linha de base. A tabela do artigo mudou entre versões — BM25 marcou 56 na v1 e marca 48 na v4 — então a versão é citada, não apenas a tabela.

O 90 do Knowl foi medido em 2026-08-08 e reproduzido de forma independente em 89,0 em 2026-08-19 com o adaptador incluído; o 79 do agentmemory é uma única execução. Cada número aqui é uma execução em temperature: 0.7, e a lacuna de ablação moveu 4 pontos entre duas execuções da mesma célula de 6k, então leia-os pelo ponto principal, não pela casa decimal.

Desligar a substituição nesse mesmo harness derruba Knowl para 73, e a lacuna se mantém em uma mudança de 40× no tamanho do corpus:

As duas seções medem coisas diferentes e não são comparáveis entre si: 98% é recuperação top-1 em 6K sem leitor, 90 é precisão de ponta a ponta em 262K com um. Apenas a segunda é comparável aos sistemas publicados acima. Veja benchmarks para o protocolo, os resultados incluídos e o que a tarefa não cobre — incluindo multi-hop, onde Knowl marca 7 contra um teto de recuperação de 14 pontos.

Substituição é uma correção, não uma exclusão: o item, suas afirmações e seu histórico sobrevivem.

Não é uma simulação — a mesma sequência contra a CLI publicada, gravada a partir de demo.tape:

Compartilhando memória em uma equipe: knowl.cloud

Tudo acima é local e não requer conta. knowl.cloud é a camada opcional hospedada para quando uma máquina não é suficiente:

• Espaços de trabalho compartilhados. O conhecimento escrito em um checkout chega aos agentes dos colegas, com cada repositório ainda sendo dono do que publica.
• Agentes de navegador. claude.ai e chatgpt.com não conseguem executar um processo local, então eles se conectam por um endpoint MCP remoto com um token com escopo para um espaço de trabalho.

Somente local continua sendo uma forma de primeira classe de executar o Knowl. Nada aqui é necessário para usar qualquer coisa acima.

O que é armazenado

Cada átomo tem exatamente uma de sete categorias:

Junto ao conteúdo, cada átomo mantém um status (active, deprecated, rejected, archived, superseded), um sinalizador de atualização, confiança, tags, commit de origem, caminhos afetados e evidências opcionais apontando para arquivos, commits, testes, comandos, URLs ou símbolos de código indexados. Evidências de arquivo e símbolo ficam desatualizadas sozinhas quando o código muda, que é como um átomo admite que pode estar desatualizado em vez de afirmar uma versão do repositório que não existe mais.

O que o Knowl deliberadamente não armazena são suas conversas. A captura do ciclo de vida registra eventos limitados e resumos — nunca prompts, transcrições, saída padrão ou variáveis de ambiente. A busca por transcrições brutas existe como um índice que você pode desativar sobre arquivos que o host já gravou.

→ Referência do modelo de conhecimento

Como os agentes usam

knowl serve expõe o armazenamento via MCP stdio; knowl init o registra para você. O fluxo de trabalho que a orientação instalada pede que os agentes sigam é curto:

1. Consulte a memória com as palavras que nomeiam o assunto antes de ler arquivos do repositório.
2. Use um resultado ativo diretamente; inspecione arquivos apenas em caso de erro, conflito ou resultado desatualizado.
3. Armazene descobertas duráveis, metas declaradas e diagnósticos recorrentes conforme avança, e corrija memória contradita em vez de duplicá-la.

Na prática, é assim que parece — uma nova sessão, sem contexto, nada colado:

You     why did we pick SQLite over Postgres?

Agent   → knowl_query "sqlite postgres database choice"
        ← decision · Use SQLite · active · fresh
          "Keeps storage repository-local and simple to operate."
          alternatives: PostgreSQL, MongoDB
          tags: database, local-first

        SQLite keeps the store repository-local and simple to operate.
        Postgres and MongoDB were both considered and rejected on that
        basis.

O agente respondeu antes de abrir um único arquivo, e sabia as opções que você rejeitou — o que o código não consegue dizer, porque alternativas rejeitadas não deixam rastro em um codebase.

Detalhes completos, e por que cada lacuna existe, em docs/hosts.md.

Onde hooks estão disponíveis, eles controlam o ciclo de vida da sessão: bootstrap de contexto, captura, checkpoints e finalização acontecem sem que o agente seja solicitado. Onde não estão, knowl task run, task start, task checkpoint e task finish cobrem o mesmo terreno manualmente.

knowl init grava o registro MCP para cada host que detecta. Para conectar um manualmente, a entrada é a mesma em todos os lugares:

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

Use knowl.cmd como comando no Windows. O Codex lê a mesma entrada sob mcp_servers.

→ Ferramentas e recursos MCP · Referência do ciclo de vida

Para que serve o Knowl

O Knowl faz um trabalho: manter o conhecimento consolidado de um projeto preciso para os agentes que trabalham nele. Não preferências de usuário, não histórico de chat — as decisões, restrições e arquitetura em que um projeto se apoia, e quais delas ainda são verdadeiras hoje. A maioria dos armazenamentos fica em um codebase, e as ferramentas de deriva e evidência são voltadas para isso, mas nada no modelo de conhecimento exige um.

Três escolhas decorrem disso:

• Tipado, não texto livre. Uma decisão carrega justificativa e as alternativas que você rejeitou. Uma restrição é uma regra que deve continuar valendo. Um átomo state deve ficar desatualizado. A recuperação pode classificar com base nessas diferenças; não pode classificar com base em parágrafos em um arquivo de notas.
• Governado, não somente anexação. Status, atualização, proveniência, identidade de conflito e substituição permitem que o armazenamento diga que algo deixou de ser verdade. Essa é toda a diferença entre memória e uma pilha crescente de notas.
• Local ao repositório, não um serviço. O banco de dados fica ao lado do projeto que descreve. Sem conta, sem egresso, sem fornecedor entre você e seu próprio histórico de projeto.

O Knowl deliberadamente não é uma camada de personalização. Não tem opinião sobre seus usuários e não mantém transcrições próprias.

Recursos

Tudo abaixo funciona pela CLI e por qualquer agente conectado via MCP, contra o mesmo banco de dados local. Sem conta, sem servidor, sem chave de API. Cada item linka para a referência completa para o detalhe — e para os limites.

Os comandos que valem a pena conhecer no primeiro dia:

knowl query "auth design"              # search project memory
knowl list --unread                    # browse it — and see what nothing ever reads
knowl edit <item-id>                   # open one memory in the viewer to fix it
knowl state                            # the active memory, as a hierarchy
knowl conflicts                        # items that contradict each other
knowl timeline <item-id>               # every version an atom ever had
knowl context --token-budget 1500      # a fixed-size briefing for an agent
knowl pr --since origin/main           # knowledge your diff may invalidate
knowl fleet                            # every agent session live on this machine, and what it is on
knowl config list                      # every setting, its value, and how to change it
knowl doctor                           # setup, retrieval, and registration

knowl workspace init product      # create the workspace
knowl workspace add product       # run inside each repo that joins it
                                  # ...or --default-visibility repo to keep its writes private

knowl workspace promote                               # pick what to share from a list
knowl workspace promote --category decision --apply   # or name it outright

Veja na prática: o visualizador local

knowl view inicia um editor em 127.0.0.1 com um token de acesso novo a cada execução — saber a porta não é suficiente para ler qualquer coisa, e escritas adicionalmente exigem que a requisição nomeie este visualizador como sua origem, então outra página que você por acaso tenha aberta não pode escrever aqui.

knowl view

Deixe-o aberto enquanto trabalha e ele mostra o agente pensando. Uma recuperação acende os átomos com os quais respondeu, em ordem de classificação, e remove o resto do grafo. Uma escrita chega em um palco limpo. Uma aposentadoria fica escura e permanece escura. Cada átomo alterado tem uma legenda com o que aconteceu com ele — NEW, UPDATED, SUPERSEDED.

Ele observa o banco de dados em vez do agente, então não faz diferença qual ferramenta está trabalhando: Claude Code, Codex, Cursor, ou você executando knowl query em outro terminal — todos acendem o mesmo grafo. Nada foi adicionado a nenhum caminho de escrita para fazer isso funcionar, então quando nenhum visualizador está aberto, nada disso roda.

É aqui também que você corrige o que seus agentes erraram. Abra qualquer átomo para ler suas evidências e linha do tempo, depois edite-o, arquive-o ou escreva um novo manualmente. Arquivar é reversível — Restaurar está no mesmo painel. Átomos aposentados permanecem no grafo como pontos escuros: eles são a história, e não afirmam mais ser atuais.

Ao lado do grafo há uma lista, com uma lente para o que nada jamais leu. Essa lente merece seu lugar: a busca só alcança memória que você já suspeita existir, e um átomo sem informação é exatamente aquele que ninguém pensa em procurar. Ordenada do mais antigo para o mais novo, ela aparece por conta própria. knowl list --unread faz a mesma pergunta a partir do terminal.

O grafo liga átomos apenas por tags que poucos átomos compartilham — uma tag em dezenas deles é uma categoria, e a barra lateral já filtra por essas. Um átomo sobre o qual nada mais trata permanece sem ligação em vez de ser amarrado a um vizinho arbitrário. É um auxílio de navegação, não um grafo causal ou de evidências. Ele mostra conteúdo local completo em todos os status, então o binding de loopback é o limite de privacidade: não o coloque atrás de um proxy público ou túnel.

→ Visualizador local

Memória que é verdadeira sobre você, não sobre um repositório

Algumas coisas não pertencem a nenhum repositório: que você prefere pnpm, que o driver desta máquina quebra no CUDA 12, que todo projeto aqui usa commits convencionais. Knowl mantém essas coisas em um armazenamento de toda a máquina em ~/.knowl/global.db, separado da memória de qualquer projeto.

knowl link global        # this project may read and write it; reversible with --off
knowl store "I prefer pnpm over npm" --title "Package manager" --category constraint --namespace global

Seu projeto sempre responde primeiro. A vinculação nunca muda o que um repositório diz sobre si mesmo — entradas globais ficam atrás das do próprio projeto e nunca podem sufocá-las. E uma sessão sem repositório algum, como uma janela do Hermes Desktop sem pasta aberta, lê o armazenamento global sozinho em vez de não ter memória. Um projeto que existe mas falha ao abrir permanece um erro: global são padrões pessoais, nunca um fallback para um armazenamento quebrado.

Ele segue você para outra máquina. O armazenamento da máquina sincroniza com um workspace na nuvem da mesma forma que um projeto faz — não é um projeto, mas é endereçado como um:

knowl cloud connect --global   # then push and pull with --global

Execute qualquer comando knowl cloud fora de um repositório e ele usa o armazenamento da máquina por conta própria, dizendo isso. Essa inferência é estreita de propósito: somente quando não há projeto acima do diretório de forma alguma. Um projeto cuja config não faz parsing é um erro sobre esse projeto, nunca respondido silenciosamente a partir dos seus padrões pessoais.

→ Namespaces de memória e a camada global

Todo o resto

28 ferramentas MCP (mais 3 quando a busca de transcrições está ativa, 1 quando conectado a um workspace na nuvem, 2 quando vinculado a um workspace local, 1 quando o impacto de mudanças está ativo, 1 para consciência de frota a menos que esteja desligado, e 1 quando hooks rodam via MCP)

e dois URIs de recurso · a CLI completa, de knowl status a knowl audit · uma auditoria de integridade somente leitura · avaliação de recuperação que você pode executar sozinho contra a governança versionada e as suítes de regressão de 500 casos com knowl eval.

→ Referência da CLI · Ferramentas MCP · Benchmarks

Requisitos e dados locais

Node.js 22 ou posterior. Tudo o que Knowl grava para um projeto vive sob .knowl/, que knowl init adiciona a .gitignore:

Um pouco vive ao lado do seu diretório inicial, sob ~/.knowl/, porque é verdadeiro sobre a máquina em vez de sobre qualquer repositório: o armazenamento de padrões pessoais de toda a máquina (~/.knowl/global.db), chaves de retomada, o registro da frota das sessões rodando agora, sua credencial na nuvem e o espelho local de um workspace na nuvem. Manifestos de workspace vivem fora dos repositórios membros pelo mesmo motivo — seus caminhos de checkout são locais à máquina. Exportações e snapshots são gravados somente quando você os solicita.

Documentação

Tudo acima é o resumo. A referência completa é um documento que cobre cada subsistema em profundidade — incluindo as partes que são deliberadamente limitadas, que é geralmente o que você realmente precisa saber.

Contribuindo

Veja CONTRIBUTING.md para configuração, as verificações a executar antes de um pull request e as convenções que este código segue. Os contribuidores são solicitados a concordar com o Contrato de Licença de Contribuidor uma vez, no primeiro pull request.

Licença

Knowl é licenciado sob a Apache License 2.0. Apache-2.0 não concede direitos de marca registrada.