knowl

本地优先。类型化。当它不再成立时，它便退休。

快速开始 · 为什么取代 · 存储什么 · 功能 · 智能体设置 · 查看器 · 要求 · 完整参考 →

编码智能体在每个会话开始时都是一片空白，因此团队会记录下内容——而这些记录只会不断增加。 六个月后，存储中仍然报告着你在去年春天就已经迁移走的数据库，因为没有任何东西告诉它那个决定已经结束了。

Knowl 是 Claude Code、Cursor 和 Codex 的跨会话持久记忆：一个仓库本地的类型化知识原子存储——包括决策、约束、架构、事实、目标、状态和技能——通过 MCP 内存服务器或 knowl CLI 进行读写，其中替换会在写入时自动退役其前驱，而不是让它们并列存在。

快速开始

需要 Node.js 22 或更高版本。

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

knowl init 创建 .knowl/ 目录，安装项目指导文件，更新 .gitignore，并为检测到的智能体（Claude Code、Codex、Cursor、Gemini CLI、Claude Desktop）提供 MCP 和生命周期设置。它还会预热本地嵌入模型，但从不依赖该下载是否成功。

记录一些值得保留的内容：

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

通过 CLI 或任何已连接的智能体读取它：

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

然后启动一个新的智能体会话，以便主机加载其指导和 MCP 注册。CLI 和 knowl_query 在相同的治理规则下读取同一个存储。

Related MCP server: Mnemoverse Memory

核心理念：能够自我退役的记忆

大多数记忆系统都是只追加的。存储"我们迁移到了 SQLite"会让"我们使用 PostgreSQL"保持活跃且可检索，因此智能体会同时获取两者，并按排名选择。Knowl 将针对同一主题的写入视为修正：前驱会被标记为 superseded，从正常检索中退出，但仍可通过 knowl timeline 查询。

这一单一行为构成了大部分准确率差异。在 MemoryAgentBench 冲突解决语料库上——455 个事实，100 个关于哪个事实是当前有效的问题，top-5 检索，无 LLM 阅读器：

相同的语料库、相同的排序器、相同的查询路径。唯一的变量是过时的事实是否仍然处于活跃状态。这是 Knowl 自身框架中的检索级别测量：它询问当前事实是否优先返回，且没有模型参与。

在基准测试自身框架中进行端到端验证

由于自己评分的分数价值低于别人评分的分数，相同的声明在 MemoryAgentBench 框架内使用其自己的代码重新运行，并由 LLM 读取 Knowl 返回的结果——这是更难的、完全端到端的设置，在任务提供的最大上下文中：

18,332 个事实，100 个问题，子串精确匹配。每一行都使用 gpt-4o-mini 作为阅读器，包括 Knowl 在内——论文中对此所有 RAG 和记忆智能体都有说明，因此这些数据是可比的。Knowl 的数据在此测量；其他所有数据来自 MemoryAgentBench 论文表 2。论文中未在该任务上评估的系统未列出。

在相同框架中关闭取代功能，Knowl 降至 73，并且该差距在语料库大小变化 40 倍时仍然保持：

这两个部分测量的是不同的事物，不能相互比较：98% 是 6K 下无阅读器的检索 top-1，90 是 262K 下带阅读器的端到端准确率。只有第二部分可与上述已发表系统进行比较。参见 基准测试 了解协议、已检入的结果以及该任务未涵盖的内容——包括多跳任务，其中 Knowl 得分为 7，而检索上限为 14 分。

取代是一种修正，而非删除：项目、其断言及其历史都得以保留。

不是模拟——相同的序列对照已发布的 CLI，从 demo.tape 录制：

存储什么

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

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

Knowl 故意不存储的是你的对话。生命周期捕获记录的是有界事件和摘要——从不记录提示、转录、标准输出或环境变量。原始转录搜索作为可选的、默认关闭的索引存在，覆盖主机已写入的文件。

→ 知识模型参考

连接智能体

knowl serve 通过 stdio MCP 暴露存储；knowl init 为你注册它。安装后的指导要求代理遵循的工作流程很简短：

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.

代理在打开任何文件之前就回答了，并且它知道你所拒绝的选项——代码无法告知它，因为被拒绝的替代方案在代码库中不留痕迹。

在有钩子的地方，它们拥有会话生命周期：引导上下文、捕获、检查点和最终化无需代理请求即可完成。在没有钩子的地方，knowl task run、task start、task checkpoint 和 task finish 手动覆盖相同领域。

knowl init 为它检测到的每个主机写入 MCP 注册。要手动连接，入口在所有地方都相同：

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

在 Windows 上使用 knowl.cmd 作为命令。Codex 在 mcp_servers 下读取相同的入口。

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

Knowl 的用途

Knowl 只有一个工作：为正在处理仓库的代理保持仓库的工程真相准确。不是用户偏好，不是聊天历史——而是代码库的决策、约束和架构，以及其中哪些在今天仍然成立。

由此得出三个选择：

• 有类型，而非自由文本。 一个决策带有其推理和你拒绝的替代方案。一个约束是必须持续保持的规则。一个 state 原子预期会过期。检索可以根据这些差异排序；它无法根据笔记文件中的段落排序。

• 受管，而非仅追加。 状态、新鲜度、来源、冲突身份和取代让存储告诉你某件事不再为真。这就是记忆与不断增长的笔记堆之间的全部区别。

• 仓库本地，而非服务。 数据库位于它所描述的代码旁边。没有账户，没有出口，没有供应商介于你和你的项目历史之间。

Knowl 故意不作为一个个性化层。它对你的用户没有看法，并且不保留自己的转录。

特性

以下所有内容都可以从 CLI 和任何连接 MCP 的代理中使用，针对同一个本地数据库。没有账户，没有服务器，没有 API 密钥。每个项目都链接到完整参考以获取详细信息——以及限制。

♻️ 自我纠正的知识

七种有类型的原子类型，其中写入相同主题会取代其前身，而不是放在它旁边。这一行为就是90-vs-73 的差异。附加到文件或符号的证据在代码移动时会自行过时。

conflicts · timeline · query --as-of · pr --since · index-code

🎯 为代理调优的检索

向量为主，辅以有界的 BM25 回退，按新鲜度、状态和置信度重新排序，因此当前答案获胜，而不仅仅是相似的答案。嵌入模型是本地且可选的——没有它你仍然可以获得关键词检索，并且没有任何内容离开机器。

query · context --token-budget · config set-model · access

⏱️ 跨会话持久的工作

在 Claude Code、Codex 和 Cursor 上，钩子负责引导、捕获、检查点和最终化，无需代理请求即可完成。一个干净的结束提炼出最多八个持久候选。在一个键下搁置一个工作流，并在任何会话中从任何目录中拾取它。

task run · handoff · park · resume <key>

🔗 工作区

你的 API 仓库学到了前端仓库需要的东西。链接它们，查询就会扩散，同时每个仓库保留自己的数据库和自己的所有权边界。通过 ID 完全打开一个共享的对等原子，或者通过在调用中命名该仓库从此处完成该仓库的工作。仓库已经持有的知识只有在推广时才会共享。

workspace init · workspace add · workspace promote --apply

📦 可重用流程

将一个流程及其脚本打包到 .knowl/skills/ 下，然后在它运行之前读取它。将多个原子确定性地汇总成一个架构摘要，完全不涉及任何 AI 提供商。

skill list · skill read · skill run · synthesize

💾 你的数据，以及如何找回它

带校验和的 JSONL 导入导出，有四种明确的策略处理当同一个原子在两个地方发生变化时。恢复会在触及任何内容之前验证模式、大小、SHA-256 和 SQLite 完整性，并首先拍摄恢复前快照。

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

第一天值得了解的命令：

knowl query "auth design"              # search project memory
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 doctor                           # setup, retrieval, and registration

• 七种原子类型——上面列出。结构而非一个不断增长的笔记文件。

• 自动取代——写入相同主题会取代其前身。这就是上面的90-vs-73 差异。

• 冲突身份——将一个原子标记为互斥，Knowl 会拒绝同一个问题的第二个活跃答案，而不是静默地同时持有它们。knowl conflicts

• 完整历史——一个原子曾经拥有的每个版本都作为不可变断言存在。knowl timeline <item-id>

• 时间旅行——询问项目在过去某个日期相信什么：knowl query "auth design" --as-of 2026-01-01T00:00:00Z

• 证据——将文件、符号、提交、测试、命令或 URL 附加到原子。文件和符号证据在代码移动时会自行过时。

• 漂移检测——knowl pr --since origin/main 在你合并之前标记你的差异可能已使其无效的知识。

• 代码智能——对 .ts / .tsx / .js / .jsx 的增量 Tree-sitter 索引，因此证据可以指向 symbol:// 定位符，而不仅仅是行号。knowl index-code

• 秘密安全的写入——每次写入在落地前都会检查检测到的秘密、敏感路径和超大内容。持久的记忆是凭证最不应该落入的地方。

→ 知识模型 · 证据和漂移

• 向量为主的排序，带有有界的 BM25 回退，按新鲜度、状态、置信度和最近性重新排序——因此当前答案获胜，而不仅仅是相似的答案。（这是代理/MCP 路径；来自 CLI 的单仓库 knowl query 是词法排序。）

• 离线运行。 嵌入模型是本地且可选的；没有它你仍然可以获得关键词检索。检索永远不会将你的查询发送到任何地方。

• 五个捆绑的嵌入预设，包括一个覆盖 200 多种语言的多语言预设，以及用于你自己的 ONNX 模型的 custom。knowl config set-model <model>

• 精确标识符支持——文件名、项目 ID 和 symbol:// 定位符即使在语义相似性较弱时也能命中。

• 基于令牌预算的上下文包——为代理提供一个固定大小的简报，约束优先固定，因此不可协商的规则永远不会被截断：knowl context --query "auth rollout" --token-budget 1500

• 使用反馈——代理报告一个结果是否有帮助，knowl access 显示哪些被大量使用、哪些过时以及哪些不断引起修正。

→ 检索和上下文

• 自动生命周期在 Claude Code、Codex 和 Cursor 上——引导、捕获、检查点和最终化通过钩子完成，无需代理请求。

• 其他所有情况的工作循环——knowl task start、checkpoint、finish，或者用 knowl task run "Run tests" -- npm test 包装单个命令。

• 会话结束时的推广——一个干净的结束从会话中提炼出最多八个持久候选，并且一个成功三次的命令会成为一个 skill 原子来描述它。

• 交接——为这个仓库中的下一个会话留下一根接力棒。它会被交付一次，然后归档。

• 恢复键——在你保留的一个简短键下搁置一个工作流，并在任何会话中从任何目录中随时拾取它，次数不限。knowl resume <key>

• 可选的转录搜索——默认关闭，关闭意味着磁盘上没有任何内容。打开后，过去的会话文本变得可搜索，因此记忆缺失会降级为较慢的查找，而不是失忆。

→ 任务、会话和生命周期

你的 API 仓库学到了前端仓库需要的东西。链接它们，查询就会扩散——同时每个仓库保留自己的数据库和自己的所有权边界。

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

加入一个工作区会共享仓库从那时起写入的内容，并在这样做时说明；传递 --default-visibility repo 以拒绝。仓库已经知道的内容只有在推广时才会共享。对等结果用拥有它们的仓库标记，共享的结果可以通过 ID 完全打开——但不包含它的 affectedPaths 或证据，这些会针对你不在的检出目录解析。缺失或无法读取的对等结果会被跳过并披露，绝不会成为本地搜索失败的原因。

写入兄弟仓库是刻意而非偶然的。代理在调用中命名仓库，该调用作为该仓库运行——其存储、其配置、其所有权规则，标记为其自身——就像 cd 到那里对 CLI 的行为一样。不命名任何东西，则像以前一样拒绝外部 ID。无论哪种方式，仓库的私有知识在推广之前保持私有。

→ 工作区

• 基于文件的技能 — 将流程及其脚本打包至 .knowl/skills/ 目录下，运行前即可检查其内容。knowl skill list · read · run

• 确定性合成 — 无需AI提供商即可将多个原子整合为一份架构摘要：knowl synthesize --scope storage

→ 技能与合成

• 可移植导出/导入 — 带校验和的JSONL格式，内置四种明确的差异处理策略，应对同一原子在两处同时变更的情况。knowl export · knowl import --on-divergence newer

• 已验证快照 — knowl snapshot create 写入校验清单；恢复时会在操作前验证架构版本、文件大小、SHA-256哈希及SQLite完整性，并先创建恢复前的快照。

• 垃圾回收 — 默认预览模式，保护近期使用的内容。knowl gc

• knowl doctor — 单条命令即可检查配置、完整性、架构、检索、向量覆盖、代理注册及工作区健康状态。

• 可选AI — 为 knowl ask 和原始文本导入配置提供商。以上所有功能均无需AI即可运行。

→ 可移植性与维护 · 可选AI

可视化：本地查看器

knowl view 在 127.0.0.1 上启动只读检查器，每次启动生成新的访问令牌——仅知道端口号无法读取任何数据。

knowl view

支持搜索、按类别筛选、标记过时圆环、聚焦邻域、打开任意原子查看证据和时间线。图谱通过共享标签和类别衍生边连接原子——这是导航辅助工具，而非因果或证据图谱。它显示所有状态下完整的本地内容，因此回环绑定是隐私边界：切勿将其置于公共代理或隧道之后。

→ 本地查看器

其他功能

27个MCP工具（启用会话搜索时增加3个，连接云工作区时增加1个，链接到本地工作区时增加1个，启用变更影响分析时增加1个）

以及两个资源URI · 完整的CLI，从 knowl status 到 knowl audit · 只读完整性审计 · 检索评估，您可使用 knowl eval 对照已检入的治理套件和500例回归套件自行运行。

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

系统要求与本地数据

Node.js 22或更高版本。Knowl为项目写入的所有数据均位于 .knowl/ 目录下，knowl init 会自动将其添加到 .gitignore：

工作区清单存储在成员仓库之外，因为其检出路径为机器本地路径。导出和快照仅在您要求时才会写入。

文档

以上内容为概要介绍。完整参考文档 是一份涵盖所有子系统的深度指南——包括那些被有意限制的部分，而这通常正是您真正需要了解的内容。

贡献指南

请参阅 CONTRIBUTING.md 了解项目设置、拉取请求前需要运行的检查项目，以及本代码库遵守的规范。贡献者在首次提交拉取请求时需同意 贡献者许可协议。

许可协议

Knowl 采用 Apache License 2.0 许可。Apache-2.0 不授予商标权利。