knowl

Your CLAUDE.md only grows. Knowl retires facts when they change.

Quick start · Why supersession · What gets stored · Features · Agent setup · Viewer · Requirements · Full reference →

---

Your agent starts every session blank, so you keep a CLAUDE.md. It only grows. Six months in it still names the database you migrated off last spring, and now the agent gets both answers.

Knowl is persistent memory for Claude Code, Cursor and Codex, over MCP or the CLI. When a fact is replaced, the old one is retired instead of competing with the new one. No API key needed. When Knowl isn't sure the new fact replaces the old, it leaves both active and hands you the knowl supersede command to say so.

Turn that off and retrieval drops from 98% to 47%. End to end, 90 to 73. How it was measured ↓

Forty seconds, one decision, three agents:

Quick start

Requires Node.js 22 or later. macOS, Linux and Windows.

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

Other package managers

The published package is the same one in every case; each of these installs it and puts knowl on your PATH.

pnpm add -g @dat999zx/knowl
yarn global add @dat999zx/knowl
bun add -g @dat999zx/knowl

Or run it without installing:

npx @dat999zx/knowl init

Knowl runs on Node.js in all of these — Bun installs it, Node executes it. It bundles native addons (SQLite, tree-sitter, the embedding runtime), so running the CLI under the Bun or Deno runtime directly is not supported.

knowl init creates .knowl/, installs the project guidance files, updates .gitignore, and registers Knowl with whichever agents it detects. It also warms a local embedding model (~53 MB) in the background — init succeeds either way, and without it you still get keyword search.

To refresh every repository and every machine-wide host after an update, run knowl init --all once. It replaces knowl upgrade --all, which still works for one release.

That is the whole setup. You do not record memory by hand: your agent reads and writes it as it works.

Connecting an agent

Claude Code MCP · lifecycle · gate

Codex MCP · lifecycle · gate

Hermes MCP · lifecycle · gate

OpenClaw in-process · plugin · gate

Copilot MCP · lifecycle · gate

Cursor MCP · lifecycle · gate

OpenHands MCP · lifecycle · gate

Antigravity MCP · lifecycle · gate

Windsurf MCP · lifecycle · gate

Cline MCP · lifecycle · plugin

Zed MCP · capture · ACP

JetBrains MCP · capture · ACP

OpenCode MCP · manual loop

Claude Desktop MCP · manual loop

knowl init registers the MCP server for every host it finds. Start a new session afterwards so the agent picks up its guidance, and it will query and write memory on its own.

gate means Knowl can refuse an edit that invalidates code another session is holding. Neovim and Kiro work the same way as Zed and JetBrains, through knowl acp. Cline needs one line pointing it at the shipped plugin. Hermes Agent gets a Python plugin, installed for you, that works in the terminal and in Hermes Desktop alike; knowl init also selects it as Hermes' memory provider when none is set, which is what keeps knowl_query out of Hermes' tool search. OpenClaw runs in-process inside its gateway via an extension plugin, evaluating write gates without subprocess overhead — knowl init openclaw copies it and prints the two commands that register it. Any other MCP client works with no integration at all.

Running agents in parallel? Every git worktree resolves to the main checkout's store — Conductor workspaces, Claude Code's isolation: "worktree", or your own scripts all share one memory, with nothing to configure. How that works, and its one limit →

→ Every host, and what each one can do · How agents use it · MCP tools and resources

The idea: memory that retires itself

Most memory systems are append-only. Storing "we moved to SQLite" leaves "we use PostgreSQL" active and retrievable, so the agent gets both and picks by rank. Knowl treats a same-subject write as a correction: the predecessor is marked superseded, drops out of normal retrieval, and stays queryable through knowl timeline.

That single behavior is most of the accuracy difference. On the MemoryAgentBench Conflict Resolution corpus — 455 facts, 100 questions about which fact is current, top-5 retrieval, no LLM reader:

Configuration	Top-1	Stale returns	Active atoms
Supersession ON	98.0%	2 / 100	306
Supersession OFF	47.0%	62 / 100	455

Same corpus, same ranker, same query path. The only variable is whether the outdated fact is still active. This is a retrieval-level measurement in Knowl's own harness: it asks whether the current fact comes back first, with no model in the loop.

Verified end-to-end, in the benchmark's own harness

Because a number you score yourself is worth less than one somebody else scores, the same claim was re-run inside MemoryAgentBench's harness, scored by its own code, with an LLM reading what Knowl returned — the harder, fully end-to-end setup, at the largest context the task offers:

System	FactConsolidation-SH @262K