KMP

KMP — 记住缘由的 Agent 记忆

本地优先。附带证据。包含时间。

KMP 是面向编码 Agent 的本地优先记忆。它作为一个小型二进制程序，内置 SQLite 存储，运行在 Codex、Claude Code 和 Hermes Agent 旁边，并记住做出了什么决定、依据是什么，以及事情发生的时间。它不保存对话记录。无需账户、服务或 API 密钥：记忆保留在你的设备上。

向 Agent 提问 “我们为什么选择 SQLite？”，它会根据存储的证据作答；如果证据不足，它会回答 UNKNOWN，而不是猜测。提问 “给我看看这项决定背后的记忆”，内置于二进制程序中的查看器 ChronoLoom 就会打开并定位到该决定，同时高亮显示其证据路径。时间是一个可供浏览的维度，你和 Agent 可以共同操控视图。记忆工具负责检索和审计证据，视图工具负责操控共享的 ChronoLoom 视图，而运行中的服务所提供的功能以 tools/list 为准。

问题

你的 Agent 今天做出了一项决定。明天开启新会话，或换用另一个 Agent，它可能会从头重新发现同一事故，也可能因为决定的缘由藏在已经消失的上下文窗口中，而悄悄推翻这项决定。摘要会丢失缘由；对话记录则会把它埋没。

KMP 将决定、所依据的证据以及发生时间保存为有类型的时间记忆，供下一个会话查询，而不必重新推导：

• 证据决定哪些说法有据可依；
• 关系说明两条记忆为何相互关联；
• 时间穿梭明确、基于游标且可审计；
• 旧决定会被新决定取代，但绝不会悄悄改写；
• 证据不足时，UNKNOWN 是诚实的回答。

两分钟了解它

在你的宿主环境中安装 KMP（见下文），然后在任意项目中：

kmp-mcp demo

它会在该项目的记忆中写入一个完整示例——涵盖结账服务、一次事故、取代先前决定的新决定，以及用于验证的测量结果；随后打开 ChronoLoom 显示该示例，并打印可提问的问题：

你提问	你会得到
“为什么向支付服务提供商发起的重试次数上限是两次？”	这项决定，以及它引用的事故和 ADR。
“2026 年 8 月，我们对重试问题的看法是什么？”	当时的旧决定，而不是后来取代它的次数上限。
“2026 年 9 月，关于重试的问题发生了什么变化？”	按顺序呈现的事故、次数上限和测量结果。
“给我看看重试次数上限决定背后的记忆。”	ChronoLoom 会打开并定位到该决定，同时高亮显示其证据路径。

在请求中提及 KMP 和 example:kmp-demo。此示例不会进入你项目的已提交内容包。更多示例，包括 KMP 自身的记忆。

安装

安装插件、运行设置，然后重启一次宿主环境。指南会在首次读取时创建一个全新的存储；无需再运行其他操作。

Claude Code

/plugin marketplace add underpass-ai/kmp@marketplace
/plugin install kmp@underpass
/kmp:setup

Codex CLI

codex plugin marketplace add underpass-ai/kmp --ref marketplace
codex plugin add kmp@underpass

然后让 Codex 运行 kmp-setup。

Hermes Agent

安装 kmp-mcp 后，通过原生生命周期注册它并安装技能：

kmp-mcp setup --hermes

验证

kmp-mcp doctor

或运行 /kmp:doctor。MCP 注册由插件负责，因此不要手动添加第二个 KMP 服务。对于没有已发布引擎的平台，可使用 cargo install kmp-mcp --locked 作为备用方案；MCPB 包、发行版 tarball 和 Pi 编码 Agent 的相关说明请参阅插件安装指南。存储选择和修复请参阅 Embedded KMP。

像和真人交谈一样使用它

通常，你只需提出想要的结果。KMP 技能会选择记忆操作。

你说	Agent 执行的操作	你会得到
“继续 KMP 文档工作。”	在重新推导之前唤起 project:kmp。	当前决策、约束和后续行动。
“我们为什么选择 SQLite？”	查询记忆并依据已存储的证据作答。	有依据的答案，或 UNKNOWN。
“KMP 记得昨天的什么？”	确定时间区间并浏览其中每个时间页面。	那段时间内按顺序排列的记忆。
“为什么三月推迟了发布？”	站在三月查询记忆：只有发生在该时间范围内的内容会参与比较，生命周期也按当时的状态读取。	来自那个时间点的有依据答案，或标明时间范围外最近匹配项的 UNKNOWN。
“记住，日志显示重试会放大问题，因此重试次数上限为 2。”	记录决策、证据及有意义的关联。	持久状态，并附有可审计的原因。
“展示这起事故与那个决策之间的证据链。”	追踪带类型的路径并检查其证据。	已存储的关联、理由和来源。
“撤销那个决策。”	写入一个取代旧状态的新状态。	两个决策都会在时间线上保留。
“保存项目记忆。”	导出维护中的项目包并显示其差异。	可供审查的 .kmp/memory.jsonl。

KMP 是记忆，不是监控。存储持久的决策和证据，而不是对话记录。

它也会等待你提出请求。如果一个会话从未提及记忆，就完全不会调用 KMP。提及 KMP、运行 /kmp:* 命令，或在项目的 CLAUDE.md 或 AGENTS.md 中选择启用，才会开启使用途径。如果你希望它自动进入已知工作：

kmp-mcp config memory-routing always
kmp-mcp config memory-routing on-request   # the default

你可以用任何语言提问。存储的证据绝不会被翻译；答案会以你的语言返回。了解其工作原理。

工作原理——10 秒版

flowchart LR
    U[You] --> H[Codex or Claude]
    H --> S[KMP skill]
    S -->|chooses a move| M[kmp-mcp]
    M --> K[embedded kernel]
    K --> D[(.kernel/\nSQLite)]
    K --> V[local read-only viewer]

插件会安装技能并声明一个本地 MCP 进程。技能会将意图转换为一个或多个带类型的工具。kmp-mcp 会验证请求，内核则读取或写入本地图谱时序存储。将返回的证据转化为对话式文字的是 Agent，而不是 KMP。

层	负责	不负责
插件	安装、宿主发现、技能和唯一的 MCP 声明。	记忆语义或第二套工具词汇。
技能	决定何时恢复、提问、导航、审计、写入、诊断、保存或还原。	持久化。
kmp‑mcp	基于本地 stdio、经过模式校验的工具边界。	根据用户的描述选择工作流。
内核	校验、时间存储、遍历、确定性检索和证据证明。	生成文字或编造理由。

探索 ChronoLoom · 技术架构

本地即本地

边界	默认行为
记忆	存储在你的机器上，通常位于仓库的 .kernel/ 中。
MCP 传输	Agent 主机与 kmp-mcp 之间通过本地 stdio 通信。
查看器	只读的回环 HTTP，通常以 http://127.0.0.1:7317/ 为根地址，并受每个会话随机生成的能力令牌保护。
外部服务	不需要任何服务；可选的 TypeSafe Jev 集成会将选定文本发送到已配置的服务。
Underpass	在此路径中不会接收任何记忆，也不会运行任何服务。
更新	设置和更新会联系 GitHub Releases，以获取带校验和的安装包；Claude 会话钩子每天可以检查发布版本。
本地元数据	Agent 身份和指南发送记录存放在记忆检索范围之外；质量诊断使用单独的本地日志。
云端 Agent	返回给云端 Agent 的证据受该主机的数据政策约束。

.kernel/ 是机器状态目录，会被 git 忽略。项目范围的存储还会维护 .kmp/memory.jsonl。导出和 Git 提交都是本地操作；推送、同步或共享此捆绑包会让其中的内容在其他地方可用。共享前请检查差异。Agent 读取的证据同样受主机的数据政策约束，无论你是否共享此捆绑包。

KMP 自身的记忆

这个仓库也在实践自己所倡导的做法。.kmp/memory.jsonl 记录了 KMP 为何如此设计：每项决策背后的原因、说明该决策的文档，以及取代旧决策的新决策。使用 /kmp:restore 恢复，并询问“为什么发布最后才推进 marketplace 分支？”写入方式。

真正需要时再使用共享记忆

多台机器可以通过由 Kubernetes 提供支持、以 Neo4j、Valkey 和 NATS JetStream 为后端的拓扑，共享一个运行中的 KMP 服务。它仍然免费、开源且由用户自行运维。“企业级”描述的是运维形态，而非付费层级或由 Underpass 托管的产品。这也意味着需要自行负责基础设施、TLS、身份、授权和可观测性。在这些责任能带来实际价值之前，请先保持本地部署。之后再阅读企业版 KMP。

项目状态

KMP 尚未达到 1.0 版：如今已实用，同时仍在积极演进，并明确说明其尚不完善之处。发布自动化会为 Linux x86_64/arm64、macOS arm64/x86_64 和 Windows x86_64 构建 kmp-mcp。默认使用嵌入式路径；远程 API 的版本为 v1beta1，需要由运维人员负责。

我们不会把过时的基准测试数据贴进 README。可复现的最新证据应先放在研究中，再用于支持相关论断。

常见问题

KMP 会把我的记忆发送到其他地方吗？

在默认的嵌入式设置下不会。进程、存储和查看器都在本地运行。Agent 主机可能由云端提供支持，因此发送给该 Agent 的证据受主机的数据政策约束。

我需要 Docker、Kubernetes 或数据库服务器吗？

不需要。随附的嵌入式二进制文件使用 SQLite。Kubernetes 仅用于部署共享服务。

KMP 内置大模型吗？

默认的嵌入式路径不需要生成式模型。KMP 会验证、存储并检索证据；你的 Agent 会撰写最终答案和英文搜索摘要。可选的 TypeSafe Jev 功能会将选定文本发送给外部模型进行判断；可选的语义检索则使用本地编码器。这些集成都需要显式配置。请参阅检索默认设置与可选启用项。

Codex 和 Claude 可以共享同一份记忆吗？

可以：两者都使用相同的 MCP 合约，而且 SQLite 支持多个本地主机。可使用维护中的项目捆绑包在机器间迁移状态，或使用企业级拓扑实现共享网络访问。

UNKNOWN 是错误吗？

不是。这表示所选记忆中没有适用于该问题的证据。这比自信地编造内容更安全。

工具消失了。现在该怎么办？

运行主机的 kmp-doctor 工作流，并按照 工具缺失运行手册操作。常见原因 包括主机会话过期、MCP 所有权重复、缺少二进制文件或存储格式不受支持。

企业版 KMP 需要付费吗？

不需要。代码采用 Apache-2.0 许可。你需要自行运营并支付所选基础设施的费用。

MCP 工具

用于记忆、用于查看者当前视图，以及用于持久化 Agent 身份和渐进式引导的工具。tools/list 是权威来源。

工具	用途
kmp_guide	打开能力图谱，保留 Agent 身份，并展开一个示例卡片。
kmp_wake	恢复精简状态，以便继续工作。
kmp_ask	检索语义问题的证据，或返回 UNKNOWN。
kmp_relate	在多个 about 共享的范围和时钟内，读取它们的记忆彼此之间的关系。
kmp_time	沿一个时钟浏览记忆：rewind 和 forward 从游标处或指定区间向后和向前翻页，goto 跳转到某个时间、序列或 ref，near 读取某个位置附近的内容。
kmp_trace	审计两个 ref 之间的路径，或从种子 ref 搜索证据；检查返回的支持信息和完整性。
kmp_inspect	在明确指定的 about 中检查一个对象及其链接和证据。
kmp_write_memory	验证并记录一项决策、约束或结果。
kmp_ingest	导入精确的规范记忆图谱。
kmp_relabel	更改记忆所代表的标签——添加、移除并说明原因，而不重写其文本。
kmp_condense	为一个已存储的正文撰写精简阅读卡，并将其绑定到读取时对应的精确版本。
kmp_summaries_audit	查看某个 about 的记忆相对于其英文搜索摘要的状态：缺少什么、lint 拒绝什么，以及哪些摘要已通过检查但仍无法检索到多少内容。
kmp_curate	将 TypeSafe Jev 作为可选的第二位审阅者，审查一个或多个 about 之间的关系：列出未声明的关系对及 Jev 会选择的类型，并列出 Jev 对其理由存疑的已声明关系。所有关系均由 Agent 编写。
kmp_view_open	打开或重新载入某个 about 的 ChronoLoom 视图。
kmp_view_apply_intent	在乐观并发控制下，通过声明含义——焦点、时钟、缩放、筛选器、选择——来移动该视图。
kmp_view_get_state	读取视图的语义状态，而非其像素。

视图工具绝不会写入记忆：它们使用封闭的语义词汇表，不包含坐标；织机前的人拥有优先权——基于过期版本准备的意图会发生冲突，而不会强行夺走视图。

kmp-setup、kmp-doctor、kmp-info、kmp-catchup、kmp-save、kmp-restore 和 kmp-revert 等人工工作流组合了 MCP 接口。它们不是额外的记忆动词。经机器检查的所有权映射位于 plugins/kmp/capabilities.json。

文档和项目链接

• 文档主页
• 嵌入式 KMP
• 检索默认设置和存储配置
• 语言
• 示例
• 企业版 KMP
• 技术架构
• 运行手册
• 开发
• 研究
• 贡献指南
• 安全策略
• 更新日志
• 问题 · 讨论

当文字说明与实现不一致时，以实现和可执行检查为准：MCP 架构、插件能力、CLI 帮助、Helm 配置值、API 契约和 CI 脚本才是事实来源。

许可证

Apache License 2.0。免费且开源。