knowl

Coding agents start every session blank, so teams write things down — and those notes only evergrow. Six months in, the store still reports the database you migrated off last spring,because nothing ever told it that decision was over.

Knowl is persistent memory across sessions for Claude Code, Cursor and Codex: arepository-local store of typed knowledge atoms — decisions, constraints, architecture, facts,goals, state, and skills — read and written over an MCP memoryserver or the knowl CLI, where a replacement retires its predecessor at write time instead ofsitting beside it.

Quick start

Requires Node.js 22 or later.

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

knowl init creates .knowl/, installs the project guidance files, updates .gitignore, andoffers MCP and lifecycle setup for whichever agents it detects — Claude Code, Codex, Cursor,Gemini CLI, Claude Desktop. It also warms the local embedding model, but never depends on thatdownload succeeding.

Record something worth keeping:

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

Read it back, from the CLI or from any connected agent:

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

Then start a new agent session so the host picks up its guidance and MCP registration. The CLI andknowl_query read the same store under the same governance rules.

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 writeas a correction: the predecessor is marked superseded, drops out of normal retrieval, and staysqueryable through knowl timeline.

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

Same corpus, same ranker, same query path. The only variable is whether the outdated fact is stillactive. This is a retrieval-level measurement in Knowl's own harness: it asks whether thecurrent 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 wasre-run inside MemoryAgentBench's harness, scored by its own code, with an LLM reading whatKnowl returned — the harder, fully end-to-end setup, at the largest context the task offers:

18,332 facts, 100 questions, substring exact match. Every row uses gpt-4o-mini as the reader,Knowl's included — the paper states it for all RAG and memory agents, so these are like-for-like.Knowl's figure was measured here; every other figure is from the MemoryAgentBench paper, Table 2.Systems the paper does not evaluate on this task are not listed.

Switching supersession off in that same harness drops Knowl to 73, and the gap holds across a40× change in corpus size:

The two sections measure different things and are not comparable to each other: 98% is retrievaltop-1 at 6K with no reader, 90 is end-to-end accuracy at 262K with one. Only the second iscomparable to the published systems above. See benchmarks for theprotocol, the checked-in results, and what the task does not cover — including multi-hop, whereKnowl scores 7 against a 14-point retrieval ceiling.

Supersession is a correction, not a delete: the item, its assertions, and its history all survive.

Not a mock-up — the same sequence against the published CLI, recorded fromdemo.tape:

What gets stored

Every atom has exactly one of seven categories:

Alongside the content, each atom keeps a status (active, deprecated, rejected, archived,superseded), a freshness flag, confidence, tags, source commit, affected paths, and optionalevidence pointing at files, commits, tests, commands, URLs, or indexed code symbols. File andsymbol evidence go stale on their own when the code moves, which is how an atom admits it may beout of date instead of asserting a version of the repository that no longer exists.

What Knowl deliberately does not store is your conversations. Lifecycle capture records boundedevents and summaries — never prompts, transcripts, stdout, or environment variables. Raw transcriptsearch exists as an opt-in, off-by-default indexover files the host already wrote.

→ Knowledge model reference

Connecting an agent

knowl serve exposes the store over stdio MCP; knowl init registers it for you. The workflow theinstalled guidance asks agents to follow is short:

1. Query memory with the words that name the subject before reading repository files.
2. Use an active hit directly; inspect files only on a miss, conflict, or stale result.
3. Store durable findings, stated goals, and recurring diagnoses as you go, and correctcontradicted memory rather than duplicating it.

In practice that looks like this — a new session, no context, nothing pasted in:

You     why did we pick SQLite over Postgres?

Agent   → knowl_query "sqlite postgres database choice"
        ← decision · Use SQLite · active · fresh
          "Keeps storage repository-local and simple to operate."
          alternatives: PostgreSQL, MongoDB
          tags: database, local-first

        SQLite keeps the store repository-local and simple to operate.
        Postgres and MongoDB were both considered and rejected on that
        basis.

The agent answered before opening a single file, and it knew the options you rejected —which the code cannot tell it, because rejected alternatives leave no trace in a codebase.

Where hooks are available, they own the session lifecycle: bootstrap context, capture, checkpoints,and finalization happen without the agent being asked. Where they are not, knowl task run,task start, task checkpoint, and task finish cover the same ground manually.

knowl init writes the MCP registration for every host it detects. To wire one by hand, theentry is the same everywhere:

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

Use knowl.cmd as the command on Windows. Codex reads the same entry under mcp_servers.

→ MCP tools and resources · Lifecycle reference

What Knowl is for

Knowl does one job: keep a repository's engineering truth accurate for the agents working on it.Not user preferences, not chat history — the decisions, constraints, and architecture of acodebase, and which of them are still true today.

Three choices follow from that:

• Typed, not free text. A decision carries reasoning and the alternatives you rejected. Aconstraint is a rule that must keep holding. A state atom is expected to go out of date.Retrieval can rank on those differences; it cannot rank on paragraphs in a notes file.
• Governed, not append-only. Status, freshness, provenance, conflict identity, and supersessionlet the store tell you that something stopped being true. That is the whole difference betweenmemory and an ever-growing pile of notes.
• Repository-local, not a service. The database sits beside the code it describes. No account,no egress, no vendor between you and your own project history.

Knowl is deliberately not a personalization layer. It has no opinion about your users, and it keepsno transcripts of its own.

Features

Everything below works from the CLI and from any MCP-connected agent, against the same localdatabase. No account, no server, no API key. Each item links into thefull reference for the detail — and for the limits.

The commands worth knowing on day one:

knowl query "auth design"              # search project memory
knowl state                            # the active memory, as a hierarchy
knowl conflicts                        # items that contradict each other
knowl timeline <item-id>               # every version an atom ever had
knowl context --token-budget 1500      # a fixed-size briefing for an agent
knowl pr --since origin/main           # knowledge your diff may invalidate
knowl doctor                           # setup, retrieval, and registration

• Seven atom types — listed above. Structure instead of one growingnotes file.
• Automatic supersession — a same-subject write retires its predecessor. This is the90-vs-73 difference above.
• Conflict identity — mark an atom exclusive and Knowl refuses a second active answer to thesame question, instead of quietly holding both. knowl conflicts
• Full history — every version an atom ever had survives as an immutable assertion.knowl timeline <item-id>
• Time travel — ask what the project believed on a past date:knowl query "auth design" --as-of 2026-01-01T00:00:00Z
• Evidence — attach files, symbols, commits, tests, commands, or URLs to an atom. File andsymbol evidence go stale by themselves when the code moves.
• Drift detection — knowl pr --since origin/main flags knowledge your diff may haveinvalidated, before you merge it.
• Code intelligence — incremental Tree-sitter index over .ts / .tsx / .js / .jsx, soevidence can point at symbol:// locators, not just line numbers. knowl index-code
• Secret-safe writes — every write is screened for detected secrets, sensitive paths, andoversized content before it lands. Long-lived memory is the last place a credential should end up.

→ Knowledge model ·Evidence and drift

• Vector-primary ranking with a bounded BM25 fallback, reranked by freshness, status,confidence, and recency — so the current answer wins, not merely the similar one. (This is theagent/MCP path; a single-repo knowl query from the CLI is lexical.)
• Runs offline. The embedding model is local and optional; without it you still get keywordretrieval. Retrieval never sends your query anywhere.
• Five bundled embedding presets, including a multilingual one covering 200+ languages, pluscustom for your own ONNX model. knowl config set-model <model>
• Exact-identifier support — filenames, item IDs, and symbol:// locators still hit even whensemantic similarity is weak.
• Token-budgeted context packs — hand an agent a fixed-size briefing with constraints pinnedfirst, so non-negotiable rules never get truncated away:knowl context --query "auth rollout" --token-budget 1500
• Usage feedback — agents report whether a result helped, and knowl access shows whatis heavily used, what is stale, and what keeps causing corrections.

→ Retrieval and context

• Automatic lifecycle on Claude Code, Codex, and Cursor — bootstrap, capture, checkpoints, andfinalization happen through hooks without the agent being asked.
• Work loops for everything else — knowl task start, checkpoint, finish, or wrap a singlecommand with knowl task run "Run tests" -- npm test.
• Promotion at session end — a clean finish distills up to eight durable candidates out of thesession, and a command that has succeeded three times becomes a skill atom describing it.
• Handoff — leave one baton for the next session in this repo. It is delivered once, thenarchived.
• Resume keys — park a workstream under a short key you keep, and pick it up in any session,from any directory, any number of times later. knowl resume <key>
• Optional transcript search — off by default, and off means nothing exists on disk. Turn it onand past session prose becomes searchable, so a memory miss degrades to a slower lookup insteadof amnesia.

→ Tasks, sessions, and lifecycle

Your API repo learned something the frontend repo needs. Link them, and a query fans out — whileeach repository keeps its own database and its own ownership boundary.

knowl workspace init product      # create the workspace
knowl workspace add product       # run inside each repo that joins it
                                  # ...or --default-visibility repo to keep its writes private

knowl workspace promote                               # pick what to share from a list
knowl workspace promote --category decision --apply   # or name it outright

Joining a workspace shares what the repo writes from then on, and says so when it does; pass--default-visibility repo to decline. What the repo already knows is shared only when youpromote it. Peer results are labeled with the repo that owns them, and a shared one can be openedin full by id — without its affectedPaths or evidence, which resolve against a checkout you arenot standing in. A peer that is missing or unreadable is skipped and disclosed, never a reason foryour local search to fail.

Writing into a sibling is deliberate rather than incidental. An agent names the repo on the calland that one call runs as that repo — its store, its config, its ownership rules, stamped asits own — exactly as cd-ing there has always behaved for the CLI. Name nothing and a foreign idis refused as before. Either way a repo's private knowledge stays private until it is promoted.

→ Workspaces

• File-backed skills — package a procedure with its scripts under .knowl/skills/, theninspect it before it ever runs. knowl skill list · read · run
• Deterministic synthesis — roll several atoms into one architecture summary with no AIprovider involved: knowl synthesize --scope storage

→ Skills and synthesis

• Portable export/import — checksummed JSONL with four explicit divergence policies for whenthe same atom changed in two places. knowl export · knowl import --on-divergence newer
• Verified snapshots — knowl snapshot create writes a checksum manifest; restore verifiesschema version, size, SHA-256, and SQLite integrity before touching anything, and takes apre-restore snapshot first.
• Garbage collection that previews by default and protects anything recently used. knowl gc
• knowl doctor — one command that checks setup, config, integrity, schema, retrieval, vectorcoverage, agent registration, and workspace health.
• Optional AI — configure a provider for knowl ask and raw-text ingest. Every feature aboveworks without one.

→ Portability and maintenance ·Optional AI

See it: the local viewer

knowl view starts a read-only inspector on 127.0.0.1 with a fresh access token per launch —knowing the port is not enough to read anything.

knowl view

Search, filter by category, spot stale rings, focus a neighborhood, and open any atom to read itsevidence and timeline. The graph links atoms through shared tags and category-derived edges — anavigation aid, not a causal or evidence graph. It shows full local content across every status, soloopback binding is the privacy boundary: do not put it behind a public proxy or tunnel.

→ Local viewer

Everything else

27 MCP tools (plus 3 when transcript search is on, 1 when connected to a cloud workspace, 1 when linked into a local workspace, and 1 when change impact is on)

and two resource URIs · thecomplete CLI, from knowl status to knowl audit · a read-only integrity audit ·retrieval evaluation you can run yourself against the checked-in governance and 500-caseregression suites with knowl eval.

→ CLI reference ·MCP tools ·Benchmarks

Requirements and local data

Node.js 22 or later. Everything Knowl writes for a project lives under .knowl/, which knowl initadds to .gitignore:

Workspace manifests live outside member repositories, because their checkout paths aremachine-local. Exports and snapshots are written only when you ask for them.

Documentation

Everything above is the summary. The full reference is one documentcovering every subsystem in depth — including the parts that are deliberately limited, which isusually what you actually need to know.

Contributing

See CONTRIBUTING.md for setup, the checks to run before a pull request, and theconventions this codebase follows. Contributors are asked to agree to theContributor License Agreement once, on their first pull request.

License

Knowl is licensed under the Apache License 2.0. Apache-2.0 does not grant trademarkrights.