claims-mcp

claims-mcp

一个为 Agent 设计的小型记忆库，将其所知视为会随时间变旧的声明。你可以针对某个实体提出声明（“acme 的优先级是第 1 位”“发布进展顺利”）。每条声明都会根据其易变程度设定的半衰期衰减，服务会告诉你哪些声明已过时、哪些彼此矛盾。

这是一个基于 stdio 的 MCP 服务，同时提供一个使用本地 SQLite 文件的 CLI。无需网络，也无需账号。

运行时：Bun。 v0 使用 bun:sqlite，因此需要在 Bun ≥ 1.1 上运行，不能直接在 Node 上运行。后续可能会提供基于 node:sqlite 的 Node 版本。

模型

字段	含义
entity	声明所针对的对象（自由文本键）。
kind	priority（可携带 assertedRank）、status、fact、relationship。
volatility	stable（半衰期 365d）、slow（30d）、volatile（7d）。
confidence	上次确认时的 0..1。自 lastConfirmed 起每经过一个半衰期，有效置信度就减半，最低为 0.05。
state	active、stale、contradicted、retired。只有 active 声明会被检查。

声明的标识为 (entity, kind, claim)：再次提出相同声明时会更新它，而不是创建副本。

MCP 工具

工具	功能
claim_add	提出或更新一条声明。
claim_search	在声明文本和实体中进行不区分大小写的子字符串搜索。
claim_confirm	立即重新确认：重置衰减、重新激活，并可选择设置置信度。
claim_retract	退役一条声明。
claims_contradictions	查找活跃声明之间的冲突：duplicate-rank（两个实体声称拥有相同优先级排名）、status-conflict（同一实体有多条活跃状态声明）。传入每周排名 observed，还可获取 rank-drop：对于一个声称拥有某优先级的实体，如果所有信号在连续 3 个有效周期内给出的排名都比 rank + 2 更差，就会触发此规则。
claims_decayed	查找超过过时阈值（默认为 0.5）的活跃声明，按过时程度从高到低排列。

资源：claims://all（以 JSON 格式提供所有声明）。

observed 的格式为 { "signals": [{ "<entity>": [rank_now, rank_1_period_ago, ...] }, ...], "validPeriods": [true, ...] }。观测数据由你提供（提交次数、花费时间或任何可用于排名的数据）；服务不会收集这些数据。

使用

bun install

添加到 MCP 客户端（此处以 Claude Code 为例）：

claude mcp add claims -- bun /path/to/claims-mcp/src/mcp.ts

数据库位于 ~/.claims-mcp/claims.db；可使用 --db <path> 或 CLAIMS_MCP_DB 指定其他路径。

CLI：

bun src/cli.ts add acme priority slow 0.8 "acme comes first" --rank 1
bun src/cli.ts search comes
bun src/cli.ts stale 0.5
bun src/cli.ts contradictions
bun src/cli.ts confirm <id>
bun src/cli.ts retract <id>

开发

bun test          # 19 tests, synthetic claims only
bun run typecheck
bun run audit     # publish gate: home paths, private names, secret patterns

设置 AUDIT_TERMS="name1|name2"，即可在审计中添加你自己的私有名称。

来源

并非直接提取而来。衰减曲线和排名下降规则移植自一个个人 Agent 记忆库（排名下降规则现在使用调用方提供的观测数据）；duplicate-rank 和 status-conflict 规则则是专为此软件包编写的全新声明间逻辑。它与原项目不共享代码、数据或存储。

作者

由 Diego González Zapiain 在 Lojik Labs 开发。已作为 io.github.dgonzap30/claims-mcp 收录于 官方 MCP Registry。

许可证

MIT