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
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.
That is the whole setup. You do not record memory by hand: your agent reads and writes it as it works.
Connecting an agent
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, and can additionally be picked as
Hermes' memory provider. 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 Postg