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

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

npx @dat999zx/knowl init

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

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, 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