Notas Markdown, locais, citadas

Pergunte às suas notas. Receba o arquivo e as linhas.

O knowman responde só com as suas notas Markdown e mostra o arquivo e as linhas de cada resposta. Se as notas não contêm a resposta, ele avisa.

Ver a arquiteturaVer os slidesGitHub
git clone https://github.com/rdorta27/knowman
cd knowman
./install.sh

Precisa de Docker. Detalhes abaixo.

O que ele resolve

  • Encontre o que você decidiu e onde escreveu.
  • Responda a uma pergunta com notas de reunião, runbooks ou documentação interna.
  • Dê a um assistente de IA uma fonte que ele deve citar.

No que ele difere

grep

O grep busca os caracteres que você digita. O knowman busca o significado da sua pergunta.

Um chat com arquivos colados

Um chat responde mesmo quando as notas não dizem nada. O knowman imprime No evidence found for that query. e não chama nenhum modelo de linguagem.

A busca de um wiki

A busca de um wiki lista páginas. O knowman devolve o trecho e o seu intervalo de linhas.

A ideia em três partes

Conceito central

O knowman é um programa que lê uma pasta de notas Markdown. Ele responde à sua pergunta com trechos dessas notas. Cada trecho mostra o arquivo e o intervalo de linhas.

Analogia física

Imagine um bibliotecário que atende uma única estante. Você faz uma pergunta. Ele entrega as páginas que correspondem, com o livro e o número da linha. Se nenhuma página corresponde, ele avisa e não entrega nada.

Mecânica técnica

  • Observador detecta cada arquivo .md adicionado, editado ou apagado e cria uma tarefa.
  • Processador pega uma tarefa por vez e a executa.
  • Fragmentador divide cada nota nas linhas em branco e registra o intervalo de linhas.
  • Ollama converte cada trecho em um vetor.
  • Postgres com pgvector guarda os trechos e os vetores.
  • Busca converte a sua pergunta em um vetor e devolve os trechos mais próximos.
  • Filtro de distância descarta os trechos a mais de 0,5. Se nenhum sobra, imprime No evidence found for that query.

Como fica

$ knowman search "why Postgres"
decision-log.md:L5-L5
  We chose Postgres with the pgvector extension for the vector store.
architecture-notes.md:L5-L6
  The store module is the only part of the codebase that speaks SQL.
Every other module calls its functions instead of touching Postgres directly.
decision-log.md:L1-L3
  # Decision log

## Database engine

$ knowman search "capital of mongolia"
No evidence found for that query.

Cada resultado é um trecho com o seu intervalo de linhas, do mais próximo ao mais distante. Com um modelo de linguagem configurado, knowman ask escreve prosa a partir desses mesmos trechos. A recuperação não precisa de modelo de linguagem. O programa imprime suas mensagens em inglês em todos os idiomas do site. Fonte: core/README.md.

O que tem dentro

Recuperação com citações

Os trechos mantêm o intervalo de linhas, então uma citação aponta para as linhas exatas. Se nada estiver dentro do limite de distância, é o negativo explícito.

Índice atualizado

Um observador transforma notas adicionadas, editadas e apagadas em tarefas, e um processador as indexa.

Quatro pontos de entrada

Uma CLI, uma API HTTP, um servidor MCP com search e ask, e um painel de monitoramento.

Roda localmente

Postgres com pgvector e Ollama para os embeddings. Nenhuma chave de API é necessária; Claude, OpenAI ou Grok podem ser configurados para as respostas.

Recuperação medida

knowman eval pontua 25 perguntas rotuladas: 100% (25/25). O conjunto é pequeno. Ele detecta regressões; não é um benchmark.

Veja cada parte e o arquivo por trás dela na página de arquitetura.

Limites

  • Só Markdown. O knowman não é um editor de notas nem um wiki. Ele lê uma pasta que já é sua.
  • Os embeddings precisam do Ollama. Um novo modelo de embeddings exige reindexar tudo.
  • Modelos locais pequenos hesitam. A resposta escrita vale o que vale o modelo que você configurar.
  • A API é aberta por padrão. Ative API_TOKEN e o limite de taxa antes de expô-la além do localhost.

Perguntas frequentes

Minhas notas saem da minha máquina?

Não, por padrão. O Postgres e o Ollama escutam em 127.0.0.1. Se você configurar Claude, OpenAI ou Grok para as respostas, o knowman envia a sua pergunta e os trechos citados a esse provedor.

Precisa de uma chave de API?

Não. A recuperação, as citações e a avaliação funcionam sem chave. Só as respostas de Claude, OpenAI e Grok precisam de uma.

Precisa de GPU?

Não. Se a máquina tiver /dev/dri, o Ollama usa Vulkan. Caso contrário, tudo roda na CPU.

E se eu trocar o modelo de embeddings?

Execute db-init e reindexe todas as notas. Um modelo diferente produz um espaço vetorial diferente.

Instalar

git clone https://github.com/rdorta27/knowman
cd knowman
./install.sh
docker compose exec api knowman search "why Postgres"

Precisa de Docker e do plugin do Compose. No Arch, ./install.sh --mode native roda sem Docker. O script imprime os comandos do que falta e para em vez de instalá-lo.

Use as suas notas

cp .env.example .env
# no .env: CORPUS_PATH=/notes
# no docker-compose.yml, em api > volumes: /home/you/notes:/notes
docker compose up -d
docker compose exec api knowman ingest

Depois deste primeiro índice, o observador atualiza o índice quando você adiciona, edita ou apaga um arquivo .md. Abra http://localhost:8000/dashboard para ver o índice, a fila de tarefas e a última avaliação. Fonte: core/README.md.