Knowl

Knowl is an open-source, persistent memory layer for AI coding agents, built around a single insight: stale knowledge is worse than no knowledge because it gets trusted. It runs as a local CLI and MCP server, storing typed facts in a SQLite database inside your repository — no API keys, no external service, no egress. The optional hosted layer at knowl.cloud adds shared team workspaces and browser-agent connectors on top of the same local-first foundation.

What It Is

Knowl gives every fact an agent stores a record of where it came from, a review trail, and a successor when it changes. Instead of appending new information alongside old, Knowl marks the predecessor as superseded and removes it from normal retrieval — so the answer an agent hands back is the current one, and you can see who settled it. The project describes this as "memory that retires itself," and the core behavior is implemented in a local SQLite store with no dependency on a running service.

The Supersession Model

The central design choice is that a same-subject write is treated as a correction, not an addition. When an agent stores a new fact about a subject the store already holds, the old fact is stamped superseded, drops out of normal retrieval, and stays queryable through knowl timeline. According to the project's own benchmarking, switching supersession off in the MemoryAgentBench harness drops end-to-end accuracy from 90 to 73 at 262K context — a 17-point gap that holds across a 40× change in corpus size. The project reports scoring 90 on MemoryAgentBench FactConsolidation single-hop at 262K (gpt-4o-mini reader), measured 2026-08-08 and independently reproduced at 89.0 on 2026-08-19.

Architecture and Knowledge Model

Every stored atom has one of seven typed categories — fact, decision, goal, constraint, architecture, state, or skill — and carries status, freshness, confidence, tags, source commit, affected paths, and optional evidence. Evidence can point at files, symbols, commits, tests, commands, or URLs; file and symbol evidence go stale automatically when the code moves. The store is vector-primary with a bounded BM25 fallback, reranked by freshness, status, and confidence. Five bundled embedding presets are included, and the embedding model is local and optional — without it, keyword retrieval still works and nothing leaves the machine.

Key architectural properties:

• Local SQLite under .knowl/ in the project repository
• 27 MCP tools exposed over stdio; knowl init registers them automatically
• No delete verb — superseded knowledge is retired, not removed
• Secret scanning on every write, before it lands
• knowl view starts a local browser viewer bound to 127.0.0.1 with a per-launch access token

Agent Integration and Setup Path

Setup is a single npm install -g @dat999zx/knowl followed by knowl init in the project directory. The init command creates .knowl/, installs guidance files, updates .gitignore, registers Knowl with detected agents, and warms a local embedding model (~53 MB) in the background. Supported clients include Claude Code, Codex CLI, Cursor, GitHub Copilot, OpenHands, Antigravity, Windsurf, Cline, Zed, JetBrains, Neovim, Kiro, Claude Desktop, and OpenCode — each initialized with one knowl init <client> command. Clients that support lifecycle hooks (Claude Code, Codex, Cursor, Copilot, OpenHands, Antigravity, Windsurf) get automatic bootstrap, capture, checkpoints, and finalization without the agent being asked.

Update: v5.15.0

The latest release is v5.15.0, published 2026-08-27, as shown in the GitHub repository. The project was created 2026-06-24 and has been actively releasing; the README and benchmark findings were last updated in August 2026. The Apache-2.0 licensed codebase is written in TypeScript and available at github.com/dat999zx/knowl. The knowl.cloud hosted layer adds optional shared workspaces and remote MCP endpoints for browser-based agents that cannot run a local process.

Why It Matters for Agent Memory

The project directly addresses a problem acknowledged in documentation from Anthropic and OpenAI: agent memory stores accumulate duplicates, contradictions, and stale entries over time. Knowl's approach — typed atoms, automatic supersession, evidence staleness detection, and a no-delete policy — is designed to make the store tell you when something stopped being true, rather than silently returning the old answer alongside the new one. The local viewer (knowl view) shows the agent's memory graph in real time, lighting atoms as they are retrieved or written, and surfaces what nothing has ever read via knowl list --unread.