Knowl

Local-first. Tipado. E aposentado no momento em que deixar de ser verdade.

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

Agentes de codificação começam cada sessão em branco, então as equipes anotam as coisas — e essas anotações só crescem. Seis meses depois, o armazenamento ainda relata o banco de dados do qual você migrou na primavera passada, porque nada nunca informou a ele que aquela decisão havia terminado.

Knowl é memória persistente entre sessões para Claude Code, Cursor e Codex: um armazenamento local ao repositório de átomos de conhecimento tipados — decisões, restrições, arquitetura, fatos, metas, estado e habilidades — lidos e gravados por meio de um servidor de memória MCP ou pela CLI knowl, onde uma substituição aposenta seu predecessor no momento da gravação em vez de ficar ao lado dele.

Início rápido

Requer Node.js 22 ou posterior.

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

knowl init cria .knowl/, instala os arquivos de orientação do projeto, atualiza .gitignore e oferece configuração de MCP e ciclo de vida para quaisquer agentes que detectar — Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop. Também aquece o modelo de incorporação local, mas nunca depende de que esse download seja bem-sucedido.

Registre algo que vale a pena manter:

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

Leia de volta, pela CLI ou por qualquer agente conectado:

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

Em seguida, inicie uma nova sessão de agente para que o host capture sua orientação e o registro MCP. A CLI e knowl_query leem o mesmo armazenamento sob as mesmas regras de governança.

A ideia: memória que se aposenta sozinha

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

Esse único comportamento é a maior parte da diferença de precisão. No MemoryAgentBench corpus de Resolução de Conflitos — 455 fatos, 100 perguntas sobre qual fato é atual, recuperação top-5, sem leitor de 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: 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 do que um que outra pessoa pontua, a mesma afirmação foi re-executada dentro do harness do MemoryAgentBench, pontuada pelo seu próprio código, 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. O número do Knowl foi medido aqui; todos os outros números são do artigo MemoryAgentBench, Tabela 2. Sistemas que o artigo não avalia nesta tarefa não são listados.

Desativar a substituição nesse mesmo harness reduz o Knowl para 73, e a diferença 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 verificados e o que a tarefa não cobre — incluindo multi-hop, onde Knowl pontua 7 contra um teto de recuperação de 14 pontos.

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

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

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 atualidade, 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 por conta própria quando o código se move, 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 Knowl deliberadamente não armazena são suas conversas. A captura do ciclo de vida registra eventos limitados e resumos — nunca prompts, transcrições, stdout ou variáveis de ambiente. A busca por transcrição bruta existe como um índice opcional, desativado por padrão sobre arquivos que o host já gravou.

→ Referência do modelo de conhecimento

Conectando um agente

Claude Code MCP · ciclo de vida · subagentes

Codex MCP · ciclo de vida · subagentes

Cursor MCP · ciclo de vida

Gemini CLI MCP · loop manual

Claude Desktop MCP · loop manual

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 ausência, 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, isso se parece com isto — 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 pode informar, porque alternativas rejeitadas não deixam rastro em um código-fonte.

Onde hooks estão disponíveis, eles controlam o ciclo de vida da sessão: contexto de inicialização, 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. Codex lê a mesma entrada sob mcp_servers.

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

Para que serve o Knowl

Knowl faz um trabalho: manter a verdade de engenharia de um repositório precisa 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 de um código-fonte, e quais delas ainda são verdadeiras hoje.

Três escolhas decorrem disso:

• Tipado, não texto livre. Uma decisão carrega raciocínio e as alternativas que você rejeitou. Uma restrição é uma regra que deve continuar valendo. Espera-se que um átomo state fique 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 de acréscimo. Status, atualidade, 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 cada vez maior de notas.
• Local ao repositório, não um serviço. O banco de dados fica ao lado do código que descreve. Sem conta, sem egresso, sem fornecedor entre você e seu próprio histórico de projeto.

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 vincula à 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 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 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: o visualizador local

knowl view inicia um inspetor somente leitura em 127.0.0.1 com um token de acesso novo por inicialização — saber a porta não é suficiente para ler qualquer coisa.

knowl view

Pesquise, filtre por categoria, identifique anéis desatualizados, foque uma vizinhança e abra qualquer átomo para ler suas evidências e linha do tempo. O grafo vincula átomos por meio de tags compartilhadas e arestas derivadas de categoria — 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 vínculo de loopback é o limite de privacidade: não o coloque atrás de um proxy público ou túnel.

→ Visualizador local

Todo o resto

27 ferramentas MCP (mais 3 quando a busca de transcrição está ativa, 1 quando conectado a um espaço de trabalho em nuvem, 1 quando vinculado a um espaço de trabalho local e 1 quando o impacto de mudanças está ativo)

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 por conta própria contra a governança verificada 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 o Knowl grava para um projeto fica sob .knowl/, que knowl init adiciona a .gitignore:

Manifestos de espaço de trabalho ficam fora dos repositórios membros, porque seus caminhos de checkout são específicos da 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

Consulte CONTRIBUTING.md para configuração, as verificações a executar antes de um pull request e as convenções que este código-fonte segue. Pede-se que os contribuidores concordem com o Contrato de Licença de Contribuidor uma única vez, no primeiro pull request.

Licença

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