knowman1 / 6

Notes pile up and stop being read. An assistant without sources makes things up.

grep finds words, not answers. It cannot tell you what was decided about X, or where that is written.

A chat assistant can invent a source. It answers even when your notes say nothing.

You want the evidence, not a guess. The exact file and the exact lines, or an honest “nothing found”.

Source: core/README.md, introduction.

knowman2 / 6

Ask your Markdown notes. Get the passage, with its lines.

A question the notes cover

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

A question they do not

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

With a language model configured, ask writes prose from those same passages and lists them as sources. Without one, you still get the citations.

It runs on your machine: Postgres with pgvector, Ollama for embeddings, no API key required.

knowman3 / 6

A watcher feeds a queue. A question is matched by distance.

Ingest

Notes.md files

→

Watcherwatcher.py

→

Job queuestore.py

→

Workerworker.py

→

Chunkerchunking.py

→

Postgrespgvector, HNSW

Query

Embed queryretrieval.py

→

Nearest chunksstore.py

→

Distance filterretrieval.py

→

Citationspath:Lstart-Lend

→

LLM answerask.py, llm/OPTIONAL

Each chunk keeps the line range it came from; that is what makes a citation exact. If nothing is within the distance threshold, the result is the explicit negative and the language model is never called.

Full diagram: architecture.html · Source: core/README.md, How it works.

knowman4 / 6

Retrieval is measured. No model judges another model.

100% (25/25)

groundedness on a labeled dataset of 25 questions.

$ knowman eval
groundedness: 100.00% (25/25), delta: +0.00%

A match rate. A question passes when the cited file is the expected one, or when no evidence is returned for a question that has none.

Every run is stored. The next run reports the change since the last, so a regression shows up as a drop.

It already caught a bug. A lone heading became its own chunk and matched unrelated questions; the eval found it.

Sources: core/README.md, core/src/knowman/evaldata/dataset.json, core/CHANGELOG.md. The sample corpus is small; this is a regression check, not a benchmark.

knowman5 / 6

One script. It checks, then installs nothing with elevated privileges.

With Docker

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; no Python on the host.

Without Docker (Arch)

./install.sh --mode native

Uses Postgres, pgvector and Ollama on the host. The script prints the exact pacman and systemctl commands for what is missing and stops; run them and run it again.

Both modes use the same ports, bound to 127.0.0.1.

Source: core/README.md, core/docs/running.md. The installer indexes the sample notes and confirms a real search returns a real citation.

knowman6 / 6

What it is not, and what comes next.

Limits

Markdown only. Not a note editor or a wiki; it reads a folder you already own.
Embeddings need Ollama. Changing the embeddings model means re-indexing everything.
Small local models hedge. The answer is only as good as the model you configure.
Open by default. The API token and rate limit are opt-in; turn them on before exposing it beyond localhost.

A public demo URL on free-tier cloud infrastructure, with retrieval and citations working without any paid key.

core/README.md, Roadmap

Try it: github.com/rdorta27/knowman