Knowl is a persistent memory system designed for coding agents such as Claude Code, Cursor, and Codex, working through MCP or CLI. The core problem it solves is: agents start each session from a blank slate, while traditional CLAUDE.md files only grow and never shrink, so over time old facts (such as a database that has already been migrated away) are still retrieved alongside new facts, causing the agent to receive conflicting answers. Knowl's approach is: when a fact on the same topic is replaced by a new write, the old fact is marked as superseded and exits normal retrieval, but can still be queried through knowl timeline. If the system is unsure whether the new fact truly replaces the old fact, it keeps both and prompts the user to manually confirm using the knowl supersede command.
Installation and initialization: Requires Node.js 22 or higher, and supports macOS, Linux, and Windows. It can be installed via the published package, putting knowl into PATH; it can also be run directly without installation. Running knowl init creates the .knowl/ directory, installs project bootstrap files, updates .gitignore, and registers Knowl with detected agents, while warming up the local embedding model in the background (about 53MB; it is usable regardless of whether initialization succeeds, and keyword search still works without the embedding model). After updating, you can run knowl init --all to refresh all repository and host registrations.
Connecting agents: knowl init registers an MCP server for each detected host, after which starting a new session allows the agent to query and write memories on its own. Supported hosts include Claude Code, Codex, Cursor, Zed, JetBrains, Neovim, Kiro, Cline, Hermes Agent, OpenClaw, etc.; other MCP clients can also be used without integration. When agents run in parallel, each git worktree resolves to the main checkout storage, and Conductor workspaces, Claude Code worktree isolation, etc. share one memory.
Knowledge model: Each atom has one of seven types, and stores status (active, deprecated, rejected, archived, superseded), freshness markers, confidence, tags, source commits, affected paths, and optional evidence pointing to files, commits, tests, commands, URLs or indexed code symbols. File and symbol evidence automatically expires as code moves. Knowl does not store conversations; lifecycle capture only records bounded events and summaries, not prompts, transcripts, stdout, or environment variables.
Usage: knowl serve exposes the store through stdio MCP; agents are guided to first query memory using the vocabulary of a named topic, use active results directly when they hit, inspect files only when there is no hit, a conflict, or the results are stale, and continuously store durable findings, goals, and recurring diagnostics, correcting contradicted memories rather than storing duplicates. Hosts with hooks can automate bootstrap, capture, checkpoints, and wrap-up; those without hooks can use knowl task run, task start, task checkpoint, and task finish manually.
Applicable scenarios: Keep a project's established knowledge accurate for agents—decisions, constraints, architecture, and whether they still hold. Knowl emphasizes typed rather than free-text, governed rather than append-only, and repository-local rather than service-based. It is explicitly not a personalization layer and does not save user preferences or chat history.
Limitations and notes: The runtime CLI does not support direct execution under the Bun or Deno runtime because it bundles native plugins (SQLite, tree-sitter, embedding runtime), although Bun can be used for installation. In multi-hop retrieval scenarios, Knowl scores 7, with a retrieval ceiling of 14 points. Information such as exact pricing, charging model, and the complete list of specific platform support is not yet available.
