Knowl

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

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 optionalevidencepointing 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.

knowl serveexposes the store over stdio MCP;knowl initregisters it for you. The workflow the installed guidance asks agents to follow is short:
- Query memory with the words that name the subjectbeforereading 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:

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 yourejected— 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, andtask finishcover the same ground manually.

knowl initwrites 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 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.

- Typed, not free text.A decision carries reasoning and the alternatives you rejected. A constraint is a rule that must keep holding. Astateatom isexpectedto 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 somethingstoppedbeing 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.

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

Vector-primary with a bounded BM25 fallback, reranked by freshness, status, and confidence, so thecurrentanswer 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

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>

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.

workspace init·workspace add·workspace promote --apply

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

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 integritybeforetouching anything, and takes a pre-restore snapshot first.

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

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 doctor # setup, retrieval, and registration

- Vector-primary rankingwith a bounded BM25 fallback, reranked by freshness, status, confidence, and recency — so thecurrentanswer wins, not merely the similar one. (This is the agent/MCP path; a single-repoknowl queryfrom 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, pluscustomfor your own ONNX model.knowl config set-model <model>
- Exact-identifier support— filenames, item IDs, andsymbol://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, andknowl accessshows what is heavily used, what is stale, and what keeps causing corrections.

- Automatic lifecycleon Claude Code, Codex, and Cursor — bootstrap, capture, checkpoints, and finalization happen through hooks without the agent being asked.
- Work loopsfor everything else —knowl task start,checkpoint,finish, or wrap a single command withknowl 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 askillatom 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.

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 # pick what to share from a list knowl workspace promote --category decision --apply # or name it outright

Joining a workspace shares what the repo writesfrom then on, and says so when it does; pass--default-visibility repoto 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 itsaffectedPathsor 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 runsasthat repo — its store, its config, its ownership rules, stamped as its own — exactly ascd-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.

- 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

- 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 createwrites a checksum manifest; restore verifies schema version, size, SHA-256, and SQLite integritybeforetouching anything, and takes a pre-restore snapshot first.
- Garbage collectionthat 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 forknowl askand raw-text ingest. Every feature above works without one.

knowl viewstarts an editor on127.0.0.1with 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.

This is 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.

Beside the graph there is a list, with a lens forwhat 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 --unreadasks the same question from the terminal.

The graph links atoms only through tagsfewatoms 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.

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, fromknowl statustoknowl audit· aread-only integrity audit·retrieval evaluationyou can run yourself against the checked-in governance and 500-case regression suites withknowl eval.

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

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