dat999zx/knowl

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 AI agents, for code, research and everyday life, 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.
Other package managers
The published package is the same one in every case; each of these installs it and puts knowl
on your PATH.
Or run it without installing:
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 only upgrades what is already set up: your repositories, the global store if you have one, and
a global instruction block (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) only where one is already
there. It never creates any of them; knowl init and knowl init --global do that. 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