# Knowl

> Persistent memory for AI coding agents that retires stale facts automatically, storing typed knowledge locally with provenance, supersession history, and MCP integration.

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

## Features
- Automatic fact supersession — stale facts are retired, not deleted
- Seven typed atom categories: fact, decision, goal, constraint, architecture, state, skill
- Local SQLite storage with no API keys or external service required
- 27 MCP tools exposed over stdio MCP protocol
- Vector-primary retrieval with BM25 fallback, reranked by freshness and confidence
- Five bundled local embedding presets including multilingual (200+ languages)
- Evidence attachment: files, symbols, commits, tests, commands, URLs
- Automatic evidence staleness detection when code moves
- Session lifecycle hooks for Claude Code, Codex, Cursor, Copilot, OpenHands
- Local browser viewer (knowl view) with real-time memory graph
- Workspace sharing across multiple repositories
- Conflict detection and dispute resolution
- Time-travel queries with --as-of flag
- Drift detection via knowl pr --since
- Secret scanning on every write
- Checksummed JSONL export/import with divergence policies
- Verified snapshots with SHA-256 and SQLite integrity checks
- File-backed reusable skill packages
- Transcript search (opt-in, off by default)
- Parallel agent support via git worktrees
- knowl doctor setup and health check command
- Token-budgeted context packs for agents
- Usage feedback and access analytics
- Retrieval evaluation against checked-in regression suites

## Integrations
Claude Code, Codex CLI, Cursor, GitHub Copilot, OpenHands, Antigravity, Windsurf, Cline, Zed, JetBrains, Neovim, Kiro, Claude Desktop, OpenCode, Any MCP-compatible client

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, JETBRAINS_PLUGIN, CLI

## Pricing
Open Source, Free tier available

## Version
5.15.0

## Links
- Website: https://knowl.cloud
- Documentation: https://docs.knowl.cloud/
- Repository: https://github.com/dat999zx/knowl
- EveryDev.ai: https://www.everydev.ai/tools/knowl