Knowl — governed project memory for AI coding agents

Local-first. Typed. And retired the moment it stops being true.

A decision recorded as active, a replacement typed at the command line, the predecessor struck through and marked superseded, then the benchmark result and the full capability set — 98% against 47% on conflict resolution, 27 MCP tools, no API key

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

Coding agents start every session blank, so teams write things down — and those notes only ever
grow. 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 a repository-local store of typed knowledge atoms — decisions, constraints,
architecture, facts, goals, state, and skills — read and written over
MCP or the knowl CLI, where a replacement retires its
predecessor at write time instead of sitting 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, and
offers 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 that
download 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 and
knowl_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 write
as a correction: the predecessor is marked superseded, drops out of normal retrieval, and stays
queryable through knowl timeline.

A write naming a subject the store already holds: the replacement takes the active lane, the predecessor is stamped superseded and moved into history, and a later query sweep matches only the current decision

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:

Conflict-resolution retrieval ablation: supersession on reached 98 percent top-1 with 2 stale returns; supersession off reached 47 percent top-1 with 62 stale returns

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:

MemoryAgentBench FactConsolidation single-hop at 262K context, substring exact match, gpt-4o-mini reader: Knowl 90, GPT-4o long-context 60, BM25 56, NV-Embed-v2 55, HippoRAG-v2 54, GPT-4o-mini long-context 45, Cognee 28, MemGPT 28, Mem0 18

System	FactConsolidation-SH @262K
Knowl	90
GPT-4o (long-context)	60
BM25	56
NV-Embed-v2	55
HippoRAG-v2	54
GPT-4o-mini (long-context)	45
Cognee	28
MemGPT	28
Mem0	18

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 a
40× change in corpus size:

Supersession ablation in MemoryAgentBench's own harness: at 262K context, supersession on scores 90 and off scores 73, a 17 point gap; at 6K context, on scores 94 and off scores 78, a 16 point gap

Context	Supersession ON	OFF	Gap
262K	90	73	+17
6K	94	78	+16

The two sections measure different things and are not comparable to each other: 98% is retrieval
top-1 at 6K with no reader, 90 is end-to-end accuracy at 262K with one. Only the second is
comparable to the published systems above. See benchmarks for the
protocol, the checked-in results, and what the task does not cover — including multi-hop, where
Knowl 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 from
demo.tape:

Terminal recording: knowl decide records a database decision, a second decide on the same subject reports Superseded older decision, and knowl status then reports one active item and one superseded

What gets stored

Every atom has exactly one of seven categories:

Category	Use it for
`fact`	Stable project truths, conventions, and verified behavior
`decision`	A selected option with reasoning and alternatives
`goal`	An intended outcome that guides future work
`constraint`	A rule or boundary that must continue to hold
`architecture`	How components are arranged and interact
`state`	Current progress, readiness, blockers, or operational status
`skill`	A reusable procedure or learned workflow description

A decision atom with its governed fields: status, freshness, confidence, tags, source commit, affected paths, and evidence — one evidence locator shown gone stale

Alongside the content, each atom keeps a status (active, deprecated, rejected, archived,
superseded), a freshness flag, confidence, tags, source commit, affected paths, and optional
evidence pointing at files, commits, tests, commands, URLs, or indexed code symbols. File and
symbol evidence go stale on their own when the code moves, which is how an atom admits it may be
out 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 bounded
events and summaries — never prompts, transcripts, stdout, or environment variables. Raw transcript
search exists as an opt-in, off-by-default index
over files the host already wrote.

→ Knowledge model reference

Connecting an agent

Claude Code
_{MCP · lifecycle · subagents}

Codex
_{MCP · lifecycle · subagents}

Cursor
_{MCP · lifecycle}

Gemini CLI
_{MCP · manual loop}

Claude Desktop
_{MCP · manual loop}

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

Query memory with the words that name the subject before reading repository files.
Use an active hit directly; inspect files only on a miss, conflict, or stale result.
Store durable findings and stated goals as you go, and correct contradicted 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.

Host	MCP	Automatic lifecycle	Subagents	Notes
Claude Code	Yes	Yes	Yes	Prompt guidance is installed as well
Codex	Yes	Yes	Yes	Main turns share one memory session
Cursor	Yes	Yes	No	Finalizes per turn
Gemini CLI	Yes	No	No	MCP plus the manual work loop
Claude Desktop	Yes	No	No	MCP plus the manual work loop

Session lifecycle: bootstrap injects relevant memory, capture records bounded events, checkpoints record milestones, finalization distills durable candidates

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, the
entry 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 a
codebase, and which of them are still true today.

One question answered four times over two years: append-only keeps every answer true forever so a query today matches four contradicting ones, while a governed store ends each replaced answer and matches one

Three choices follow from that:

Typed, not free text. A decision carries reasoning and the alternatives you rejected. A
constraint 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 supersession
let the store tell you that something stopped being true. That is the whole difference between
memory 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 keeps
no transcripts of its own.

Features

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

♻️ Knowledge that corrects itself

Seven typed atom types, where a same-subject write retires its predecessor instead of
sitting beside it. That one behavior is the 90-vs-73 difference.
Evidence attached to a file or symbol goes stale by itself when the code moves.

conflicts · timeline · query --as-of · pr check · code index

🎯 Retrieval tuned for agents

Vector-primary with a bounded BM25 fallback, reranked by freshness, status, and confidence,
so the current answer wins rather than the merely similar one. The embedding model is
local and optional — without it you still get keyword retrieval, and nothing leaves the machine.

query · context --token-budget · config set-model · access report

⏱️ Work that survives the session

On Claude Code, Codex, and Cursor, hooks own bootstrap, capture, checkpoints, and
finalization without the agent being asked. A clean finish distills up to eight durable
candidates. Park a workstream under a key and pick it up in any session, from any directory.

task run · handoff · park · resume <key>

🔗 Workspaces

Your API repo learned something the frontend repo needs. Link them and a query fans out,
while each repository keeps its own database and its own ownership boundary. Knowledge a
repo already holds is shared only when you promote it, and only the owner can retire its
own atoms.

workspace init · workspace add · workspace promote --apply

📦 Reusable procedures

Package a procedure with its scripts under .knowl/skills/, then read it before it ever
runs. Roll several atoms into one architecture summary deterministically, with no AI
provider involved at all.

skill list · skill read · skill run · synthesize

💾 Your data, and getting it back

Checksummed JSONL export and import with four explicit policies for when the same atom
changed in two places. Restore verifies schema, size, SHA-256, and SQLite integrity
before touching anything, and takes a pre-restore snapshot first.

export · import --on-divergence · snapshot create · gc · doctor

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 check --since origin/main     # knowledge your diff may invalidate
knowl doctor                           # setup, retrieval, and registration

Knowledge that corrects itself — seven typed atom types, and a write that retires what it replaces

Seven atom types — listed above. Structure instead of one growing
notes file.
Automatic supersession — a same-subject write retires its predecessor. This is the
90-vs-73 difference above.
Conflict identity — mark an atom exclusive and Knowl refuses a second active answer to the
same 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 and
symbol evidence go stale by themselves when the code moves.
Drift detection — knowl pr check --since origin/main flags knowledge your diff may have
invalidated, before you merge it.
Code intelligence — incremental Tree-sitter index over .ts / .tsx / .js / .jsx, so
evidence can point at symbol:// locators, not just line numbers. knowl code index
Secret-safe writes — every write is screened for detected secrets, sensitive paths, and
oversized content before it lands. Long-lived memory is the last place a credential should end up.

→ Knowledge model ·
Evidence and drift

Retrieval tuned for agents — the current answer wins, not merely the similar one

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 the
agent/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 keyword
retrieval. Retrieval never sends your query anywhere.
Four bundled embedding presets, including a multilingual one covering 200+ languages, plus
custom for your own ONNX model. knowl config set-model <model>
Exact-identifier support — filenames, item IDs, and symbol:// locators still hit even when
semantic similarity is weak.
Token-budgeted context packs — hand an agent a fixed-size briefing with constraints pinned
first, 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 report shows what
is heavily used, what is stale, and what keeps causing corrections.

→ Retrieval and context

Work that survives the end of a session — hooks, work loops, handoff batons, and resume keys

Automatic lifecycle on Claude Code, Codex, and Cursor — bootstrap, capture, checkpoints, and
finalization happen through hooks without the agent being asked.
Work loops for everything else — knowl task start, checkpoint, finish, or wrap a single
command with knowl task run "Run tests" -- npm test.
Promotion at session end — a clean finish distills up to eight durable candidates out of the
session, 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, then
archived.
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 on
and past session prose becomes searchable, so a memory miss degrades to a slower lookup instead
of amnesia.

→ Tasks, sessions, and lifecycle

Workspaces: many repos, one shared memory — you decide what each repo shares

Your API repo learned something the frontend repo needs. Link them, and a query fans out — while
each 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 --category decision           # preview what would be shared
knowl workspace promote --category decision --apply   # publish it

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 you
promote it. Peer results are read-only and labeled with the repo that owns them, and only the
owner can retire its own atoms. A peer that is missing or unreadable is skipped and disclosed,
never a reason for your local search to fail.

→ Workspaces

Reusable procedures — file-backed skills you can inspect before they run

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

→ Skills and synthesis

Your data, and getting it back — portable export, verified snapshots, and one doctor command

Portable export/import — checksummed JSONL with four explicit divergence policies for when
the same atom changed in two places. knowl export · knowl import --on-divergence newer
Verified snapshots — knowl snapshot create writes a checksum manifest; restore verifies
schema version, size, SHA-256, and SQLite integrity before touching anything, and takes a
pre-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, vector
coverage, agent registration, and workspace health.
Optional AI — configure a provider for knowl ask and raw-text ingest. Every feature above
works 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

Knowl local viewer showing the project-memory graph Knowl local viewer showing details for a selected knowledge atom

Search, filter by category, spot stale rings, focus a neighborhood, and open any atom to read its
evidence and timeline. The graph links atoms through shared tags and category-derived edges — a
navigation aid, not a causal or evidence graph. It shows full local content across every status, so
loopback 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, and 1 when connected to a cloud workspace)

and two resource URIs · the
complete 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-case
regression suites with knowl eval retrieval.

→ 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 init
adds to .gitignore:

Path	Holds
`.knowl/config.json`	Project, search, security, AI, and workspace configuration
`.knowl/knowl.db`	Atoms, assertions, knowledge commits, full-text index, feedback, embeddings
`.knowl/skills/`	File-backed skill packages

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

Documentation

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

If you want to know…	Go to
What an atom is, and what each field means	Knowledge model
How a query is ranked, and what wins ties	Retrieval and context
What a hook records, and when	Tasks, sessions, lifecycle
How an atom notices the code moved	Evidence and drift
How several repos share memory safely	Workspaces
How a procedure becomes reusable	Skills and synthesis
How to export, snapshot, or restore	Portability and maintenance
What the viewer shows, and its privacy boundary	Local viewer
How the pieces fit, and where the trust boundaries are	Architecture
How to wire a specific host	Agent setup
How the numbers on this page were measured	Benchmarks
Every command and every flag	CLI reference
Every MCP tool and resource	MCP tools
What needs a provider, and what never does	Optional AI
Exactly what lands on disk	Local data

Contributing

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

License

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