Knowl

你的 CLAUDE.md 只会不断膨胀。Knowl 会在事实发生变化时将其弃用。

快速开始 · 为什么要弃用旧事实 · 存储的内容 · 功能 · 配置 Agent · 查看器 · 要求与本地数据 · 完整参考 →

你的 Agent 每次会话开始时都是一片空白，所以你会一直维护一个 CLAUDE.md。它只会不断膨胀。六个月后，里面仍然写着你去年春天迁移离开的数据库，现在 Agent 会给出两个答案。

Knowl 是面向 AI Agent 的持久化记忆，可用于代码、研究和日常生活，通过 MCP 或命令行使用。事实被替换时，旧事实会被弃用，而不是与新事实相互竞争。无需 API 密钥。如果 Knowl 不确定新事实是否取代了旧事实，就会让两者都保持有效，并提供 knowl supersede 命令供你确认。

关闭这项功能后，检索率会从 98% 降至 47%。端到端得分则从 90 降至 73。 测量方法 ↓

四十秒，一个决策，三个 Agent：

需要 Node.js 22 或更高版本。支持 macOS、Linux 和 Windows。

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

pnpm add -g @dat999zx/knowl
yarn global add @dat999zx/knowl
bun add -g @dat999zx/knowl

npx @dat999zx/knowl init

knowl init 会创建 .knowl/、安装项目指导文件、更新 .gitignore，并向它检测到的 Agent 注册 Knowl。它还会在后台预热本地嵌入模型（约 53 MB）——无论预热结果如何，init 都会成功；即使未完成预热，你仍可使用关键词搜索。

要在更新后刷新所有代码库和所有计算机级宿主，请运行一次 knowl init --all。它只会升级已配置的内容：你的代码库、全局存储（如果有），以及全局指令块（仅在 ~/.claude/CLAUDE.md、~/.codex/AGENTS.md 已存在时更新）。它绝不会创建这些内容；创建请使用 knowl init 和 knowl init --global <host>。它取代了 knowl upgrade --all；后者仍可用于升级一个版本。

设置就这么简单。你无需手动记录记忆：Agent 会在工作过程中读取并写入记忆。

连接 Agent

Claude Code MCP · lifecycle · gate	Codex MCP · lifecycle · gate	Hermes MCP · lifecycle · gate	OpenClaw in-process · plugin · gate	Copilot MCP · lifecycle · gate	Cursor MCP · lifecycle · gate	OpenHands MCP · lifecycle · gate
Antigravity MCP · lifecycle · gate	Windsurf MCP · lifecycle · gate	Cline MCP · lifecycle · plugin	Zed MCP · capture · ACP	JetBrains MCP · capture · ACP	OpenCode MCP · manual loop	Claude Desktop MCP · manual loop

knowl init 会为检测到的每个宿主注册 MCP 服务。之后启动新会话， 让 Agent 获取相关指导，它便会自行查询和写入记忆。

gate 表示 Knowl 可以拒绝会使其他会话正在持有的代码失效的编辑。 Neovim 和 Kiro 与 Zed 和 JetBrains 的工作方式相同，都是通过 knowl acp。Cline 需要添加 一行配置，指向随附的插件。Hermes Agent 会安装一个 Python 插件，供你在终端和 Hermes Desktop 中使用；如果尚未设置 Hermes 的记忆提供程序，knowl init 也会将其设为该提供程序，这样 knowl_query 就不会出现在 Hermes 的工具搜索中。OpenClaw 通过扩展插件在其网关进程内运行，无需子进程开销即可评估写入门控——knowl init openclaw 会复制该插件，并打印用于注册它的两条命令。其他任何 MCP 客户端都无需集成即可使用。

并行运行 Agent？每个 git worktree 都会解析到主检出目录的存储库——Conductor 工作区、Claude Code 的 isolation: "worktree"，或你自己的脚本都共享同一份记忆，无需任何配置。 了解其工作原理及其唯一限制 →

→ 所有宿主及其各自的功能 · Agent 如何使用它 · MCP 工具和资源

核心理念：会自行淘汰的记忆

大多数记忆系统只会追加内容。存储“我们改用了 SQLite”后，“我们使用 PostgreSQL”仍处于活跃状态且可检索，因此 Agent 会同时获取两条信息，再按排名选取。Knowl 会将同一主题的写入视为更正：前一条记忆会标记为 superseded，不再参与常规检索，但仍可通过 knowl timeline 查询。

这一项行为就解释了大部分准确率差异。在 MemoryAgentBench 的冲突解决语料库中—— 455 条事实，100 个询问哪条事实当前有效的问题，top-5 检索，不使用 LLM 阅读器：

相同的语料库、排序器和查询路径。唯一变量是过时的事实是否仍处于活跃状态。这是 Knowl 自有测试框架中的检索层面测量：它会检查当前事实是否排在首位，整个过程中不涉及模型。

在基准测试自带的测试框架中完成端到端验证

因为自己给自己打分，可信度不如由他人打分，所以我们在 MemoryAgentBench 的测试框架中，由其自有代码评分，重新运行了同一项测试，并让 LLM 读取 Knowl 返回的内容——这是难度更高、完整端到端的设置，使用任务提供的最大上下文：

18,332 条事实、100 个问题、子串精确匹配。每一行都使用 gpt-4o-mini 作为阅读器，Knowl 也不例外——论文说明所有 RAG 和记忆 Agent 都采用这一设置，因此结果可以直接比较。 Knowl 和 agentmemory 的数据是在这里测得的；其他所有数据均来自 MemoryAgentBench 论文，arXiv 2507.05257v4，表 3。agentmemory 未在该论文中评估——它已发布的数据是 LongMemEval 检索召回率，属于不同任务——因此我们用相同配置通过同一测试框架运行了它；两个适配器共用同一条阅读器代码路径，所以它们都与论文自有的 RAG 处理程序保持一致。方法、机制和复现步骤见：FINDINGS.md。

此外还展示了论文评估的所有商业记忆系统，以及每个基线类别中得分最高的系统。论文的表格在不同版本间有过变化——BM25 在 v1 中为 56 分，在 v4 中为 48 分——因此我们注明了版本，而不只是表格。

Knowl 的 90 分测于 2026-08-08，并于 2026-08-19 使用仓库中提供的适配器独立复现，得分为 89.0；agentmemory 的 79 分来自单次运行。此处每个数据均为在 temperature: 0.7 下运行一次的结果；同一 6k 测试单元运行两次，消融差距相差了 4 分，因此请关注整数分数，不要过度解读小数。

在同一测试框架中关闭 supersession 后，Knowl 的得分降至 73；即使语料规模相差 40 倍，这一差距仍然存在：

这两个部分衡量的是不同指标，彼此不可比较：98% 是 6K 上下文且不使用阅读器时的检索 top-1 准确率，90 是 262K 上下文且使用阅读器时的端到端准确率。只有后者可与上方公布的系统进行比较。有关协议、仓库中提供的结果，以及此任务未涵盖的内容，请参阅 基准测试——包括多跳任务，Knowl 得分为 7，而检索分数上限为 14。

Supersession 是更正，不是删除：条目、其中的断言及其历史记录都会保留。

这不是演示模型——以下内容是对已发布 CLI 执行同一序列的录屏，记录来自 demo.tape：

以上所有内容都在本地，无需账户。knowl.cloud 是可选的托管层，适用于一台机器不够用的情况：

• 共享工作区。 在一个检出目录中编写的知识会同步给队友的 Agent，同时每个仓库仍自行管理其发布的内容。
• 浏览器 Agent。 claude.ai 和 chatgpt.com 无法运行本地进程，因此它们通过远程 MCP 端点连接，并使用作用域限定在单个工作区的令牌。

仅在本地运行仍是使用 Knowl 的一流方式。使用上述任何功能都不需要这里的内容。

存储的内容

每个原子恰好属于以下七个类别之一：

除内容外，每个原子还会保留状态（active、deprecated、rejected、archived、superseded）、新鲜度标志、置信度、标签、源提交、受影响路径，以及指向文件、提交、测试、命令、URL 或已索引代码符号的可选证据。当代码发生变动时，文件和符号证据会自行失效。这样，原子就能承认自身可能已过时，而不是断言一个已不复存在的仓库版本。

Kn​​owl 有意不存储的是你的对话。生命周期采集会记录有限范围的事件和摘要——绝不记录提示词、转录文本、标准输出或环境变量。原始转录搜索是针对主机已写入文件的可关闭索引。

→ 知识模型参考

Agent 如何使用它

knowl serve 通过 stdio MCP 暴露存储；knowl init 会为你完成注册。已安装的指导要求 Agent 遵循的工作流很简短：

1. 在读取仓库文件之前，先用能说明主题的词查询记忆。
2. 命中有效记忆时直接使用；只有未命中、存在冲突或结果过时时才检查文件。
3. 随时存储持久的发现、明确表达的目标和反复出现的诊断；如果记忆与事实矛盾，应予以修正，而不是重复记录。

实际效果如下——开启一个没有上下文、没有粘贴任何内容的新会话：

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.

Agent 在打开任何文件之前就给出了答案，而且它还知道你否决过哪些选项——代码无法告诉它这些，因为被否决的替代方案不会在代码库中留下痕迹。

完整详情以及各项缺失的原因，见 docs/hosts.md。

在支持 Hooks 的宿主中，Hooks 负责会话生命周期：上下文引导、内容捕获、检查点和收尾都会自动完成，无需 Agent 提出请求。在不支持 Hooks 的宿主中，knowl task run、task start、task checkpoint 和 task finish 可手动完成相同的工作。

knowl init 会为检测到的每个宿主写入 MCP 注册信息。若要手动配置，所有宿主使用的条目都相同：

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve", "--host", "<host>"] }
  }
}

在 Windows 上，将 knowl.cmd 用作命令。Codex 会在 mcp_servers 下读取相同的条目。

→ MCP 工具和资源 · 生命周期参考

Knowl 的用途

Knowl 为使用它的 Agent 保持已确定知识的准确性：项目运行所依赖的决策、约束、事实和目标，以及它们如今是否仍然成立。大多数存储都位于代码库中，漂移检测和证据工具也主要面向代码库，但知识模型并不局限于代码：项目存储可以保存一篇论文，而机器级全局存储则保存关于你、适用于各个项目的事实。Knowl 存储提炼后的知识原子，从不保存聊天记录。

由此得出三项选择：

• 类型化，而非自由文本。 决策会附带推理过程和你否决的备选方案。约束是必须持续成立的规则。state 知识原子则预期会过时。检索可以根据这些差异排序，却无法根据笔记文件中的段落排序。
• 受治理，而非只追加。 状态、新鲜度、来源、冲突身份和取代关系，让存储能够告诉你某件事已经不再成立。这正是记忆与不断堆积的笔记之间的根本区别。
• 仓库本地，而非服务。 数据库与其描述的项目并排存放。无需账户，不会向外传输数据，也没有供应商介入你和自己的项目历史之间。

Knowl 不保存转录内容，也绝不捕获提示词。可选的 AI 导入功能只会读取你交给它的文本，并通过领域配置文件（code、general、academic 或自定义配置）决定哪些内容值得保留。领域配置文件和提供方

功能

以下所有功能都可通过 CLI 和任何连接 MCP 的 Agent 使用，并操作同一个本地数据库。无需账户、服务或 API 密钥。每项功能都链接到完整参考文档，了解详情和限制。

📦 可复用流程

将流程及其脚本打包到 .knowl/skills/ 下，并在运行前先读取。确定性地将多个原子条目汇总为一份架构摘要，全程无需调用任何 AI 提供商。

skill list · skill read · skill run · synthesize

💾 你的数据，以及如何取回

支持校验和的 JSONL 导出与导入，并提供四种明确策略，用于处理同一原子条目在两个位置发生更改的情况。恢复会在进行任何操作之前验证架构、大小、SHA-256 和 SQLite 完整性，并先创建恢复前快照。

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

🛰️ 这台机器上的会话可以互相看见

四个代码仓库里有 20 个 Agent，彼此却毫不知情——于是两个 Agent 遇到同一个故障，都开始修复；第三个 Agent 又升级了其他 Agent 所依赖的引擎。Knowl 会记录每个会话正在处理什么、本轮写入了什么，以及它认领了哪个故障，然后在第二个会话开始做同样的修复之前告知它。所有安装了 Knowl hooks 的宿主都在其中，Codex 和 Claude Code 也能彼此看见。只有一个会话在运行时，不会输出任何内容。

fleet · knowl_fleet

第一天就值得了解的命令：

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 fleet                            # every agent session live on this machine, and what it is on
knowl config list                      # every setting, its value, and how to change it
knowl doctor                           # setup, retrieval, and registration

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

knowl view 会在 127.0.0.1 上启动编辑器，每次启动都会生成新的访问令牌——仅知道端口并不足以读取任何内容；此外，写入请求还必须将此查看器指定为其来源，因此你碰巧打开的其他页面无法在此处写入。

knowl view

工作时让它保持打开，它就会显示 Agent 的思考过程。 检索会按排名顺序点亮用于回答的原子，并隐藏图谱中的其余部分。写入会在清空的画布上显示。归档操作会让原子变暗，并保持暗色。每个发生变化的原子都会标注其变更类型——NEW、UPDATED、SUPERSEDED。

它监视的是数据库，而非 Agent，因此无论使用哪个工具都没有区别：Claude Code、Codex、Cursor，或是在另一个终端中运行 knowl query 的你，都会点亮同一个图谱。为实现这一功能，任何写入路径都无需改动，因此没有打开查看器时，这一切都不会运行。

这里也可以修正 Agent 出错的内容。 打开任意原子即可查看其证据和时间线，然后编辑、归档，或手动写入新原子。归档可以撤销——同一面板中有“恢复”按钮。已退役的原子仍会作为暗色点留在图谱上：它们是历史记录，不再声称自己是当前信息。

图谱旁边有一个列表，还可以查看从未被读取过的内容。这个功能很有用：搜索只能找到你已经怀疑存在的记忆，而没有任何信息的原子恰恰是没人会想到去找的内容。列表按时间从早到晚排序，会自动显示这些原子。knowl list --unread 可在终端中查询同样的内容。

图谱只通过少数原子共有的标签连接原子——数十个原子共有的标签属于分类，而侧栏已经可以按这些标签筛选。若某个原子没有与其他内容相关联，它就会保持未连接状态，而不会被随意连到某个邻近原子上。图谱是导航辅助工具，并非因果图或证据图。它会显示所有状态下的完整本地内容，因此隐私边界由环回绑定构成：请勿将它置于公共代理或隧道之后。

→ 本地查看器

只对你成立、而非对某个代码仓库成立的记忆

有些信息不属于任何代码仓库：你偏好使用 pnpm，这台机器的驱动程序在 CUDA 12 下会出问题，这里的每个项目都使用 conventional commits。Knowl 会将这些信息保存在机器级存储 ~/.knowl/global.db 中，与任何项目的记忆分开。

knowl link global        # this project may read and write it; reversible with --off
knowl store "I prefer pnpm over npm" --title "Package manager" --category constraint --namespace global

始终优先使用项目自身的回答。 链接永远不会改变代码仓库对自身的描述——全局条目排在项目条目之后，绝不会挤占项目条目的位置。没有代码仓库的会话也能读取记忆，例如没有打开文件夹的 Hermes Desktop 窗口会单独读取全局存储，而不会没有记忆。项目存在但无法打开时，仍会报错：全局存储是个人默认值，绝不是损坏存储的后备方案。

AI 写入全局存储时会使用 general 配置，除非 ~/.knowl/config.json 中的 ai.profile 指定了其他配置。

换一台机器也能使用。 机器存储会像项目一样同步到云工作区——它不是项目，但寻址方式与项目相同：

knowl cloud connect --global   # then push and pull with --global

在代码仓库之外运行任何 knowl cloud 命令时，命令会自行使用机器存储，并说明这一点。此推断有意限定得很窄：只有当当前目录上方完全没有项目时才会触发。项目配置无法解析时，会报与该项目有关的错误，绝不会悄悄改用你的个人默认值。

→ 记忆命名空间与全局层

其他内容

28 个 MCP 工具（另有 3 个用于转录搜索已开启时，1 个用于连接到云工作区时，2 个用于链接到本地工作区时，1 个用于变更影响已开启时，除非关闭，否则 1 个用于集群感知功能，以及 1 个用于通过 MCP 运行钩子时）

以及 2 个资源 URI · 完整的 CLI，从 knowl status 到 knowl audit · 只读完整性审计 · 你可以使用 knowl eval，针对已纳入版本控制的治理测试套件和包含 500 个案例的回归测试套件自行运行的检索评估

→ CLI 参考 · MCP 工具 · 基准测试

要求与本地数据

Node.js 22 或更高版本。Knowl 为项目写入的所有内容都存放在 .knowl/ 下，knowl init 会将该目录添加到 .gitignore：

还有少量数据存放在你的主目录旁边的 ~/.knowl/ 下，因为这些数据适用于整台机器，而非某个代码仓库：机器级个人默认值存储（~/.knowl/global.db）、恢复密钥、记录当前运行会话的集群记录、你的云凭据，以及云工作区的本地镜像。工作区清单出于相同原因存放在成员代码仓库之外——其检出路径仅适用于本机。只有在你主动要求时，才会写入导出文件和快照。

文档

以上内容就是摘要。完整参考文档是一份涵盖所有子系统的文档，其中详细介绍了各项内容——包括那些有意受到限制的部分，而这通常正是你真正需要了解的内容。

参与贡献

有关设置、提交拉取请求前需要运行的检查，以及本代码库遵循的约定，请参阅 CONTRIBUTING.md。贡献者需要在首次提交拉取请求时，同意一次贡献者许可协议。

许可证

Knowl 根据 Apache License 2.0 授权。Apache-2.0 不授予商标权。