Markdown notes, local, cited

Ask your notes. Get the file and the lines.

knowman answers from your Markdown notes only, and shows the file and the lines behind every answer. When the notes hold no answer, it says so.

See the architectureView the slidesGitHub
git clone https://github.com/rdorta27/knowman
cd knowman
./install.sh

Needs Docker. Details below.

What it solves

  • Find what you decided and where you wrote it.
  • Answer a question from meeting notes, runbooks or internal docs.
  • Give an AI assistant a source it must cite.

How it differs

grep

grep matches the characters you type. knowman matches the meaning of your question.

A chat with pasted files

A chat answers even when the notes say nothing. knowman prints No evidence found for that query. and calls no language model.

Wiki search

Wiki search lists pages. knowman returns the passage and its line range.

The idea in three parts

Core concept

knowman is a program that reads a folder of Markdown notes. It answers your question with passages from those notes. Each passage shows its file and line range.

Physical analogy

Picture a librarian who serves one shelf only. You ask a question. The librarian hands you the matching pages, with the book and the line number. If no page matches, the librarian says so and hands you nothing.

Technical mechanics

  • Watcher detects each added, edited or deleted .md file and creates a job.
  • Worker claims one job at a time and runs it.
  • Chunker splits each note at blank lines and records the line range.
  • Ollama converts each chunk into a vector.
  • Postgres with pgvector stores the chunks and the vectors.
  • Search converts your question into a vector and returns the nearest chunks.
  • Distance filter drops chunks farther than 0.5. If none remain, it prints No evidence found for that query.

What it looks like

$ 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.

Each result is a passage with its line range, listed from the closest match to the farthest. With a language model configured, knowman ask writes prose from those same passages. Retrieval needs no language model. The program prints its messages in English in every site language. Source: core/README.md.

What is inside

Cited retrieval

Chunks keep their line ranges, so a citation points at the exact lines. Nothing within the distance threshold means an explicit negative.

Live index

A watcher turns added, edited and deleted notes into jobs, and a worker indexes them.

Four entry points

A CLI, an HTTP API, an MCP server with search and ask, and a monitoring panel.

Runs locally

Postgres with pgvector and Ollama for embeddings. No API key is needed; Claude, OpenAI or Grok can be set for answers.

Measured retrieval

knowman eval scores 25 labeled questions: 100% (25/25). The set is small. It checks for regressions; it is not a benchmark.

See each part and the file behind it on the architecture page.

Limits

  • Markdown only. knowman is not a note editor or a wiki. It reads a folder you already own.
  • Embeddings need Ollama. A new embeddings model needs a full re-index.
  • Small local models hedge. The written answer is only as good as the model you set.
  • The API is open by default. Turn on API_TOKEN and the rate limit before you expose it beyond localhost.

Frequently asked questions

Do my notes leave my machine?

No, by default. Postgres and Ollama listen on 127.0.0.1. If you set Claude, OpenAI or Grok for answers, knowman sends your question and the cited passages to that provider.

Does it need an API key?

No. Retrieval, citations and eval run with no key. Only the Claude, OpenAI and Grok answers need one.

Does it need a GPU?

No. If the machine has /dev/dri, Ollama uses Vulkan. Otherwise everything runs on the CPU.

What happens if I change the embeddings model?

Run db-init and re-index every note. A different model produces a different vector space.

Install

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

Needs Docker and the Compose plugin. On Arch, ./install.sh --mode native runs without Docker. The script prints the commands for anything missing and stops instead of installing it.

Use your own notes

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

After this first index, the watcher updates the index when you add, edit or delete a .md file. Open http://localhost:8000/dashboard to see the index, the job queue and the last eval. Source: core/README.md.