Docs
Everything runs from one binary
Install it, point it at a repository, and tell it which agent you use. Your agents read and write memory through MCP from then on.
Install
One Node binary, nothing else. Node 22 or newer.
Everything below is a subcommand of knowl. There are no aliases — one name per
operation, on purpose.
Connect a repository
Sign in once per machine, then connect the repo you are standing in.
Wire up an agent
One command sets the project up: it creates .knowl/, initialises the database, writes
the guidance files your agent reads, updates .gitignore, and offers MCP and lifecycle
setup for the clients it detects. Run it bare and it asks, or name the integrations outright.
Claude Code, Cursor and Codex also take lifecycle hooks, which is what lets an agent capture what it worked out without being asked. Gemini CLI and Claude Desktop keep MCP access but need the manual work loop for lifecycle capture. Anything else that speaks MCP works with no adapter to write.
knowl init still completes and lexical retrieval keeps working —
knowl reindex --vectors is the explicit backfill once a model is present.The browser is the one place none of that reaches: claude.ai and chatgpt.com run no process of yours. For those, Knowl Cloud answers as a remote MCP server and a workspace connects by pasting one URL — see connecting Knowl to Claude and ChatGPT, which is experimental.
What a fact is made of
A stored fact — an atom — is a claim plus the things that let somebody check it later: a category, where the belief came from, the reasoning behind it, and the alternatives that were rejected on the way.
| Field | What it holds |
|---|---|
| category | fact · decision · goal · constraint · architecture · state · skill |
| provenance | observed from a run, user_stated from a person,
or inferred — and claiming one of the first two ranks the atom above one that claims nothing |
| reasoning | Why this was believed, in the author's words |
| alternatives | What was considered and rejected, so nobody re-proposes it |
| affectedPaths | The files the claim depends on — how the next reader reaches the evidence |
| supersedes | The atom this one replaces, if any |
Local by default, published on purpose
Everything an agent stores lands in a local ledger first. Nothing reaches the shared workspace until it is staged and pushed — and the model is deliberately the one you already know.
Writes a fact to the local ledger. Always free, never leaves the machine.
Marks a fact to travel. Auto-staging is on by default for verified writes.
Sends the staged set. Secret-scanned server-side, every time.
The engine — the CLI, the local store, the embeddings and the MCP server — is Apache-2.0 and needs no account. You can run it on its own forever; Knowl Cloud is the layer that lets a second person read what your agents worked out.
Supersession, not deletion
When a claim stops being true, the new one records what it replaced. The old one is retired: still queryable as history, but no longer returned as the answer.
Correcting a claim never deletes one. Keeping every replaced fact beside the current one is what costs accuracy — the old answers come back next to the new one and the model has to guess.
Destruction does exist, but it is maintenance rather than correction. Garbage collection runs on an explicit policy, previews before it applies, and writes every destroyed item to an append-only forget log — the policy that fired, its reason, and the retrieval evidence it decided against — so a collection threshold stays checkable long after the fact.
The reference
That is the whole model. Everything past it — every command and its flags, every MCP tool and what gates it, every limit and the things Knowl deliberately does not do — lives in the reference.