Persistent memory for Claude Code, Cursor and Codex. Facts retire when they change.
io.github.dat999zx/knowl — Model Context Protocol (MCP) Server
This MCP server provides persistent memory for Claude Code, Cursor, and Codex. It is designed to store facts and manage their lifecycle so that entries retire when they change, keeping stored context aligned with updated information.
🛠️ Key Features
Persistent memory support for Claude Code, Cursor, and Codex
Fact retention with retirement when facts change
🚀 Use Cases
Maintaining up-to-date factual context across supported coding assistants
Reducing stale information by retiring facts after changes
⚡ Developer Benefits
Clear lifecycle behavior: facts persist until they change
Consistent context availability for multiple tools: Claude Code, Cursor, and Codex
⚠️ Limitations
Documentation available here does not specify tools supported, tool count, or additional capabilities beyond the described persistent memory behavior
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:
Claude Code answers which database the project uses from memory, records the move to Postgres and retires the MySQL decision; Codex answers the same question from that memory in a second terminal; the Claude app answers from the same store over the hosted connector
Quick start
Requires Node.js 22 or later. macOS, Linux and Windows.
bash
npm install -g @dat999zx/knowl
cd your-project
knowl init
Other package managers
The published package is the same one in every case; each of these installs it and puts knowl
on your PATH.
bash
pnpm add -g @dat999zx/knowl
yarn global add @dat999zx/knowl
bun add -g @dat999zx/knowl
Or run it without installing:
bash
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
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 →
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
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:
System
FactConsolidation-SH @262K
Knowl
90
agentmemory
79
GPT-4o (long-context)
60
HippoRAG-v2
54
BM25
48
GPT-4o-mini (long-context)
45
Qwen3-Embedding-4B
29
Cognee
28
MemGPT
28
Mem0
18
MIRIX
14
Zep
7
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 and agentmemory were measured here; every other figure is from the MemoryAgentBench
paper, arXiv 2507.05257v4, Table 3. agentmemory is not
evaluated in that paper — its published numbers are LongMemEval-S retrieval recall, a different
task — so it was run through the same harness with the same config, and both adapters share one
reader code path so neither can drift from the paper's own RAG handler. Method, mechanism and
reproduction steps: FINDINGS.md.
Otherwise shown are every commercial memory system the paper evaluates, plus the highest scorer
from each baseline family. The paper's table has changed between versions — BM25 read 56 in v1 and
reads 48 in v4 — so the version is cited, not just the table.
Knowl's 90 was measured 2026-08-08 and independently reproduced at 89.0 on 2026-08-19 with the
checked-in adapter; agentmemory's 79 is a single run. Every figure here is one run at
temperature: 0.7, and the ablation gap moved 4 points between two runs of the same 6k cell, so
read them to the point rather than the decimal.
Switching supersession off in that same harness drops Knowl to 73, and the gap holds across a
40× change in corpus size:
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:
Sharing memory across a team: knowl.cloud
Everything above is local and needs no account. knowl.cloud is the optional
hosted layer for when one machine is not enough:
Shared workspaces. Knowledge written in one checkout reaches teammates' agents, with each
repository still owning what it publishes.
Browser agents. claude.ai and chatgpt.com cannot run a local process, so they connect over a
remote MCP endpoint with a token scoped to one workspace.
Local-only remains a first-class way to run Knowl. Nothing here is required to use anything above.
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
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.
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, stated goals, and recurring diagnoses 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:
text
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
Write gate
Capture nudge
Notes
Claude Code
Yes
Yes
Yes
Yes
Prompt guidance is installed as well
Codex CLI
Yes
Yes
Yes
Yes
Hooks need codex_hooks; not on Windows
GitHub Copilot
Yes
Yes
Yes
Yes
Reuses Claude Code's hook format
OpenHands
Yes
Yes
Yes
Yes
MCP entry is added by hand
Antigravity
Yes
Yes
Yes
Yes
Context rides injectSteps
Windsurf
Yes
Yes
Yes
Yes
Nudge rides MCP; no stop hook
Cursor
Yes
Yes
Yes
Yes
Finalizes per turn
Cline
Yes
Yes
No
Yes
Lifecycle via the shipped plugin
Hermes Agent
Yes
Yes
Yes
Yes
Python plugin, incl. Hermes Desktop; nudge via pre_verify on edit turns
Zed, JetBrains, Neovim, Kiro
Yes
Yes
No
Yes
Via knowl acp --
Claude Desktop, OpenCode, Roo, …
Yes
No
No
Yes
MCP plus the manual work loop
Full detail, and why each gap exists, in docs/hosts.md.
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:
Knowl does one job: keep a project's settled knowledge accurate for the agents working on it.
Not user preferences, not chat history — the decisions, constraints, and architecture a project
runs on, and which of them are still true today. Most stores sit in a codebase, and the drift and
evidence tooling is aimed there, but nothing in the knowledge model requires 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 project 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.
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.
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.
knowl posture maximal turns the watchful half on in one command — searching past sessions on a
miss, flagging atoms whose files moved, and asking every so often what the session is relying on
but never verified. All of it off until you ask.
task run · handoff · park · resume <key> · posture
🔗 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. Open a shared
peer atom in full by id, or finish that repo's work from here by naming it on the call.
Knowledge a repo already holds is shared only when you promote it.
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.
🛰️ The sessions on this machine can see each other
Twenty agents across four repos, and none of them knew the others existed — so two hit the same
failure and both start fixing it, and a third upgrades the engine the rest are standing on. Knowl
records what each session is on, what it wrote this turn, and which failure it has claimed, then
says so before the second session starts the same fix. Every host with Knowl hooks is in it and
they see each other, Codex beside Claude Code. Prints nothing when you are the only one running.
fleet · knowl_fleet
The commands worth knowing on day one:
bash
knowl query "auth design"# search project memory
knowl list --unread # browse it — and see what nothing ever reads
knowl edit <item-id> # open one memory in the viewer to fix it
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 fleet # every agent session live on this machine, and what it is on
knowl config list # every setting, its value, and how to change it
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 --since origin/main flags knowledge your diff may have
invalidated, before you merge it, and knowl_drift asks the same question from inside the agent
that wrote the branch. What it reports is a cited path that is gone, not one merely edited —
that distinction is what keeps the signal readable.
The claims drift cannot reach — drift watches files, and about half the store cites none.
knowl status dates those instead, by how long since anyone last restated them, and names the
ones furthest past their own category's cadence. It ranks rather than flags: for prose there is
no evidence a claim became false, only the absence of anyone reaffirming it.
Code intelligence — incremental Tree-sitter index over TypeScript, JavaScript, Python and Go, so
evidence can point at symbol:// locators, not just line numbers. knowl index-code
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.
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.
Five 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 shows what
is heavily used, what is stale, and what keeps causing corrections.
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. Keyword indexing keeps up on its own; semantic coverage is filled by
knowl reindex --transcripts, because an embedding model does not belong in a per-turn hook.
The recall gap — how often an agent edited a file this store already knew something about
without ever retrieving it. Invisible from inside a session, because an agent that never
retrieved an atom cannot notice the atom exists. Counted on every tool call, shown to nobody but
you, in knowl status — and split between the main thread and subagents, because a subagent
receives no prompt reminder and no server instructions, so its share is the only read you get on
whether the bootstrap card alone carries the habit.
The write gate's own score — with change impact on, the gate that would refuse an edit to
code another session changed runs in shadow first, recording every refusal it withheld.
knowl status prints the precision that produced, next to the bar it has to clear before it is
allowed to block anything (≥95% over ≥40 adjudicated findings) — so the decision to arm it is
made against a number instead of a hunch. Absent entirely until the gate has withheld something:
a repo that never ran it has not scored 0%, it has measured nothing.
The sessions on this machine can see each other — one roster, on every host
The other half of the same problem: not one session across time, but several at once. Claude Code
keeps a registry of its live sessions and lets one message another; it records nothing about what
any of them is doing, and no other host records anything at all.
A roster at session start — who else is running, grouped by repo, own repo first. Empty when
you are alone, so a single-session user never sees a line about any of this.
Every host with Knowl hooks is in it, and they see each other. A Codex session appears on a
Claude session's roster and the reverse. Liveness comes from the host's own session registry
where it publishes one, and from recency where it does not.
"Another session is already on this problem" — two sessions never see byte-identical output,
so failures are matched on a normalised signature rather than raw text, and a claim is keyed to
the problem rather than the file. The card names the peer, its files, and the exact call to
make; a bare announcement of a conflicting edit is measurably no better than saying nothing.
A pre-flight before a shared surface moves — hooks, host settings, migrations, lock files,
and the knowl install every other session's hooks are running on. Advice on a channel the
agent already receives, never a refusal.
A stop-time nudge when this turn's writes invalidated a file another live session had read,
joined through the read set rather than guessed. Shadow by default — it records what it would
have said, because delivering it withholds a stop and that costs a turn.
Only reachable peers are offered as something to message. A session on another host or under
another config directory is listed and marked, and the card asks you instead — a card that told
the agent to message a session it cannot address teaches it to skip the next one.
Machine-level, not per-repo.~/.knowl/fleet.db, beside the resume keys: a session in
~/work/api upgrading the engine is a fact ~/work/web needs. knowl fleet reads it from any
terminal, inside a project or not.
fleet.enabled ships on, and so do the cards — the roster costs a directory listing and says
nothing when you are alone, and a card is advice on a channel the agent already reads. What
ships quiet is what would cost you something: the per-turn digest, and the stop-time nudge that
withholds a stop.
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.
bash
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 you
promote it. Peer results are labeled with the repo that owns them, and a shared one can be opened
in full by id — without its affectedPaths or evidence, which resolve against a checkout you are
not standing in. A peer that is missing or unreadable is skipped and disclosed, never a reason for
your local search to fail.
Writing into a sibling is deliberate rather than incidental. An agent names the repo on the call
and that one call runs as that repo — its store, its config, its ownership rules, stamped as
its own — exactly as cd-ing there has always behaved for the CLI. Name nothing and a foreign id
is refused as before. Either way a repo's private knowledge stays private until it is promoted.
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
Global playbooks — a procedure that is the same everywhere lives once at ~/.knowl/skills/,
and each repository supplies its own commands and paths through a binding in .knowl/config.json.
A playbook and a binding are two keys: neither runs anything alone, an unbound playbook lists and
reads but refuses to run, and a project skill of the same name shadows the global one.
What runs is shown before it runs — a manifest declares its inputs, its capabilities and
fail-closed preconditions (clean_worktree, on_branch:, command_exists:), an unrecognised
precondition refuses rather than passing, and the run banner prints the fully resolved command.
Approval is per set of bytes and re-checked every run; a repository cannot ship a skill and its
own approval. Capabilities are declarations, not a sandbox, and say so.
Deterministic synthesis — roll several atoms into one architecture summary with no AI
provider involved: knowl synthesize --scope storage
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.
knowl view starts an editor on 127.0.0.1 with a fresh access token per launch — knowing the
port is not enough to read anything, and writes additionally require the request to name this
viewer as its origin, so another page you happen to have open cannot write here.
bash
knowl view
Leave it open while you work and it shows you the agent thinking. A retrieval lights the atoms
it answered with, in rank order, and drops the rest of the graph away. A write arrives on a cleared
stage. A retirement goes dark and stays dark. Each changed atom is captioned with what happened to
it — NEW, UPDATED, SUPERSEDED.
It watches the database rather than the agent, so it makes no difference which tool is working:
Claude Code, Codex, Cursor, or you running knowl query in another terminal all light the same
graph. Nothing was added to any write path to make this work, so when no viewer is open, none of
it runs.
This is also where you fix what your agents got wrong. Open any atom to read its evidence and
timeline, then edit it, archive it, or write a new one by hand. Archiving is reversible — Restore
is on the same panel. Retired atoms stay on the graph as dark points: they are the history, and they
no longer claim to be current.
Beside the graph there is a list, with a lens for what nothing has ever read. That one earns
its place: search only reaches memory you already suspect exists, and an atom carrying no
information is precisely the one nobody thinks to look for. Sorted oldest-first, it surfaces on its
own. knowl list --unread asks the same question from the terminal.
The graph links atoms only through tags few atoms share — a tag on dozens of them is a
category, and the rail already filters by those. An atom nothing else is about stays unlinked
rather than being tied to an arbitrary neighbour. It is 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.
Some things belong to no repository: that you prefer pnpm, that this machine's driver breaks on
CUDA 12, that every project here uses conventional commits. Knowl keeps those in a machine-wide
store at ~/.knowl/global.db, separate from any project's memory.
bash
knowl link global # this project may read and write it; reversible with --off
knowl store "I prefer pnpm over npm" --title "Package manager" --category constraint --namespace global
Your project always answers first. Linking never changes what a repository says about itself —
global entries sit behind the project's own, and can never crowd them out. And a session with no
repository at all, such as a Hermes Desktop window with no folder open, reads the global store
alone rather than having no memory. A project that exists but fails to open stays an error: global
is personal defaults, never a fallback for a broken store.
It follows you to another machine. The machine store syncs to a cloud workspace the same way a
project does — it is not a project, but it is addressed like one:
bash
knowl cloud connect --global # then push and pull with --global
Run any knowl cloud command outside a repository and it uses the machine store on its own,
saying so. That inference is narrow on purpose: only when there is no project above the directory
at all. A project whose config will not parse is an error about that project, never quietly
answered from your personal defaults.
28 MCP tools (plus 3 when transcript search is on, 1 when connected to a cloud workspace, 2 when linked into a local workspace, 1 when change impact is on, 1 for fleet awareness unless it is switched off, and 1 when hooks run over MCP)
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.
A little lives beside your home directory instead, under ~/.knowl/, because it is true of the
machine rather than of any one repository: the machine-wide personal-defaults store
(~/.knowl/global.db), resume keys, the fleet's record of the sessions running right now, your cloud
credential, and the local mirror of a cloud workspace. Workspace manifests live outside member
repositories for the same reason — 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.
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.
