knowl

<div align="center">

<img src="docs/assets/hero.png" alt="Knowl — the knowledge operating system for AI agents: memory, knowledge, context, continuity" width="100%" />

**Your CLAUDE.md only grows. Knowl retires facts when they change.**

[![npm](https://img.shields.io/npm/v/%40dat999zx%2Fknowl?color=4fd8e8&label=npm)](https://www.npmjs.com/package/@dat999zx/knowl)
[![CI](https://img.shields.io/github/actions/workflow/status/dat999zx/knowl/ci.yml?branch=main&label=CI)](https://github.com/dat999zx/knowl/actions/workflows/ci.yml)
[![license](https://img.shields.io/badge/license-Apache--2.0-85c577)](LICENSE)
[![node](https://img.shields.io/badge/node-%E2%89%A522-70b6fd)](package.json)
[![MCP](https://img.shields.io/badge/protocol-MCP-cab049)](https://modelcontextprotocol.io)

<a href="https://discord.gg/YrWbHe8FBB"><img src="https://img.shields.io/badge/Discord-Join%20the%20server-5865F2?logo=discord&logoColor=white&style=for-the-badge" alt="Join the Knowl Discord" height="40" /></a>

<p align="center">
  <a href="#the-idea-memory-that-retires-itself"><picture><source media="(prefers-color-scheme: light)" srcset="docs/assets/chips/light/stat-supersession.svg"><img src="docs/assets/chips/stat-supersession.svg" alt="Scores 90 on MemoryAgentBench FactConsolidation single-hop at 262K" height="38" /></picture></a>
  <a href="#quick-start"><picture><source media="(prefers-color-scheme: light)" srcset="docs/assets/chips/light/stat-nokeys.svg"><img src="docs/assets/chips/stat-nokeys.svg" alt="0 API keys needed" height="38" /></picture></a>
  <a href="#everything-else"><picture><source media="(prefers-color-scheme: light)" srcset="docs/assets/chips/light/stat-tools.svg"><img src="docs/assets/chips/stat-tools.svg" alt="28 MCP tools" height="38" /></picture></a>
  <a href="#what-knowl-is-for"><picture><source media="(prefers-color-scheme: light)" srcset="docs/assets/chips/light/stat-local.svg"><img src="docs/assets/chips/stat-local.svg" alt="100% local, no egress" height="38" /></picture></a>
</p>

[Quick start](#quick-start) ·
[Why supersession](#the-idea-memory-that-retires-itself) ·
[What gets stored](#what-gets-stored) ·
[Features](#features) ·
[Agent setup](#connecting-an-agent) ·
[Viewer](#see-it-the-local-viewer) ·
[Requirements](#requirements-and-local-data) ·
**[Full reference →](docs/reference.md)**

</div>

---

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](https://modelcontextprotocol.io) 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 ↓](#the-idea-memory-that-retires-itself)

Forty seconds, one decision, three agents:

<div align="center">
<img src="docs/assets/knowl-showcase.webp" alt="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" width="88%" />
</div>

## Quick start

Requires Node.js 22 or later. macOS, Linux and Windows.

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

<details>
<summary>Other package managers</summary>

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.

</details>

`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

<table>
<tr>
<td align="center" width="14%">
<a href="https://claude.com/product/claude-code"><img src="docs/assets/logos/anthropic.svg" alt="Claude Code" width="40" height="40" /></a><br/>
<strong>Claude Code</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://github.com/openai/codex"><img src="docs/assets/logos/openai.svg" alt="Codex" width="40" height="40" /></a><br/>
<strong>Codex</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://hermes-agent.nousresearch.com"><img src="docs/assets/logos/hermes.png" alt="Hermes Agent" width="40" height="40" /></a><br/>
<strong>Hermes</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://github.com/openclaw/openclaw"><img src="docs/assets/logos/openclaw.svg" alt="OpenClaw" width="40" height="40" /></a><br/>
<strong>OpenClaw</strong><br/>
<sub>in-process · plugin · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://github.com/features/copilot"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/githubcopilot-dark.svg" /><img src="docs/assets/logos/githubcopilot.svg" alt="Copilot" width="40" height="40" /></picture></a><br/>
<strong>Copilot</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://cursor.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/cursor-dark.svg" /><img src="docs/assets/logos/cursor.svg" alt="Cursor" width="40" height="40" /></picture></a><br/>
<strong>Cursor</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://openhands.dev"><img src="docs/assets/logos/openhands.svg" alt="OpenHands" width="40" height="40" /></a><br/>
<strong>OpenHands</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
</tr>
<tr>
<td align="center" width="14%">
<a href="https://antigravity.google"><img src="docs/assets/logos/antigravity.svg" alt="Antigravity" width="40" height="40" /></a><br/>
<strong>Antigravity</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://windsurf.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/windsurf-dark.svg" /><img src="docs/assets/logos/windsurf.svg" alt="Windsurf" width="40" height="40" /></picture></a><br/>
<strong>Windsurf</strong><br/>
<sub>MCP · lifecycle · gate</sub>
</td>
<td align="center" width="14%">
<a href="https://github.com/cline/cline"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/cline-dark.svg" /><img src="docs/assets/logos/cline.svg" alt="Cline" width="40" height="40" /></picture></a><br/>
<strong>Cline</strong><br/>
<sub>MCP · lifecycle · plugin</sub>
</td>
<td align="center" width="14%">
<a href="https://zed.dev"><img src="docs/assets/logos/zed.svg" alt="Zed" width="40" height="40" /></a><br/>
<strong>Zed</strong><br/>
<sub>MCP · capture · ACP</sub>
</td>
<td align="center" width="14%">
<a href="https://www.jetbrains.com"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/jetbrains-dark.svg" /><img src="docs/assets/logos/jetbrains.svg" alt="JetBrains" width="40" height="40" /></picture></a><br/>
<strong>JetBrains</strong><br/>
<sub>MCP · capture · ACP</sub>
</td>
<td align="center" width="14%">
<a href="https://github.com/anomalyco/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/opencode-dark.svg" /><img src="docs/assets/logos/opencode.svg" alt="OpenCode" width="40" height="40" /></picture></a><br/>
<strong>OpenCode</strong><br/>
<sub>MCP · manual loop</sub>
</td>
<td align="center" width="14%">
<a href="https://claude.ai/download"><img src="docs/assets/logos/anthropic.svg" alt="Claude Desktop" width="40" height="40" /></a><br/>
<strong>Claude Desktop</strong><br/>
<sub>MCP · manual loop</sub>
</td>
</tr>
</table>

`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](https://conductor.build) 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 →](docs/hosts.md#parallel-agents-and-git-worktrees)

→ [Every host, and what each one can do](docs/hosts.md) · [How agents use it](#how-agents-use-it) · [MCP tools and resources](docs/reference.md#mcp-tools-and-resources)

## The idea: memory that retires itself

Most memory systems are append-only. Storing "we moved to SQLite" leaves "we use Postg