kronicle-lite

kronicle-lite

一个本地优先的 MCP 服务，能告诉你的 Agent 何时其笔记已过时。

Agent 会撰写笔记、运行手册和决策记录。随后情况发生变化：某个区块被重写，某项决策被推翻，某个流程被废弃。普通记忆存储不会告诉 Agent 这些变化。它仍会依据三轮会话前读到的内容继续推理，而且对此深信不疑。

kronicle-lite 是一个基于 SQLite 的轻量文档存储，其中：

• 每次写入都是哈希链上的一个事件，你可以从公开的创世记录开始用 sha256sum 验证；
• 每次 recall() 命中都会附带一张签名回执，日后可据此回答“这仍是当前版本吗？”——VERIFIED（已验证）、SUPERSEDED（已被取代，附有新版本）、TOMBSTONED（已标记删除）或 UNVERIFIED（未验证）；
• get_system_state 为 Agent 提供一个状态定位调用：传入上次的游标，即可准确获取此后发生的所有变化；离开太久时会显示漂移提示，并列出你可能依赖过、如今已不再正确的内容；
• 每次命中都会附带如实标注——can_act、inspect_only 或 never_act，并说明原因；空结果则会说明搜索了什么、未搜索什么，以及索引是否是最新的。机密内容会在写入追加式哈希链之前被拒绝。

它只需一个进程、一个文件，无需账户。它可通过 stdio 与 Claude Code、Cursor、Claude Desktop、Codex、GitHub Copilot 或任何 MCP 客户端配合运行，也可通过环回 Streamable HTTP 为无法启动进程的客户端提供服务。

一条命令即可了解

npx -y kronicle-lite demo

无需大模型，无需联网，使用后会删除临时目录。放入一份运行手册；Agent 浏览并读到“部署会先进入暂存集群 stg-west-2。”；有人将其改成 stg-east-1；Agent 下一次浏览时，会在采取行动前看到：

- [behavioral] seq 9: You previously relied on "Deploys go to the staging cluster `stg-west-2` first."
  (runbook › Deploy runbook › Deploy target); current truth is "Deploys go to the staging cluster
  `stg-east-1` first." (seq 9). Reconcile before proceeding.
  changed: Deploys go to the staging cluster [-`stg-west-2`-]{+`stg-east-1`+} first.

接着有人手动编辑 SQLite 文件：recall 会扣留被编辑的文本，旧回执验证结果为 UNVERIFIED (content_tampered)，verify-chain 以状态码 1 退出，rebuild 则从链中恢复文本。含有 API 密钥的写入会在加入链之前被拒绝；空的 recall 会通过 absent_in_searched 回答，并列出未搜索的范围；对链本身的编辑也会在对应的 seq 被发现。

0.6.0 — 如实标注。每条 recall 命中都带有 authority: can_act | inspect_only | never_act 及原因；只有块级证据（此刻在记录的源文件中找到该块的原文）才会获得 can_act；已被取代、已删除、被扣留和发生漂移的文本永远不会获得该标记。absence {searched, not_searched, index_fresh, verdict} 会区分“已搜索，未找到”和“未搜索”，过期或未就绪的索引绝不会证明“未找到”。本会话中已读过的命中项排名会降低（但绝不会隐藏）。写入、导入或监听时会拒绝秘密信息（API 密钥、令牌、私钥、连接字符串），也可按请求以脱敏形式存储；读取时还会再次清理提供的文本。serve --core 提供六个工具；recall 会限制内容长度，并附上“阅读完整文档”的指引。规则见 docs/HONESTY.md。所有变更均为增量式：哈希、回执、游标或事件布局均未改变。

0.5.0 弥补了采用审计发现的缺口：Agent 读取的内容现在会与链核对，而不只是与日志核对（recall、verify、verify-chain、doctor、rebuild）；指令文件按项目区分，因此共享数据目录的两个仓库不再互相撤销对方的规则；撤回记录包含旧词和新词；tools/list 缩小了 71%；serve --http 也可为 Cursor 等 2025 年客户端提供服务。详情见 CHANGELOG。

0.3.0 支持 MCP 2026-07-28（TypeScript SDK v2）。每个工具都有 outputSchema 并返回 structuredContent；tools/list 和 server/discover 带有缓存提示；结果带有 resultType。stdio 服务端以及（自 0.5.0 起的）serve --http 均兼容两个时代：仍使用 2025 年 initialize 握手（2025-11-25、2025-06-18、2025-03-26）连接的客户端也能获得服务。

0.4.0 新增外部锚定（checkpoint --push、verify --remote）、链式指令（watch、instruction 类型的撤回）、支持 Git 的块（bind_git、STALE_SOURCE）以及 kronicle-lite doctor。所有变更均为增量式：0.3.0 链可逐字节验证。

kronicle-lite 不是记忆服务。它是与记忆服务并行运行的。继续使用你已有的知识图谱或语义召回工具；将 kronicle-lite 指向那些一旦过时就会造成损失的笔记。

安装

需要 Node ≥ 20。

npm install -g kronicle-lite          # or run via npx, see below
kronicle-lite serve                   # stdio MCP server, data in ~/.kronicle-lite

Claude Code

claude mcp add kronicle-lite -- npx -y kronicle-lite serve

可选：将 skills/orient/ 复制到 .claude/skills/orient/，并将 examples/.claude/CLAUDE.md 中的唤醒契约添加到你的 CLAUDE.md（其中包含“在每条会改变世界的命令前先 pulse”）。然后输入 orient，即可让 Agent 重新根据链校准方向。若要推送 Agent 工作期间产生的变更，可添加一个 PostToolUse hook，执行 kronicle-lite orient --cursor C --focus retractions --json（文档）。 若要阻止 Agent 对尚未重新读取的变更执行会改变世界的命令，可添加一个 PreToolUse hook，执行 kronicle-lite pending --actor <agent> --json，并在 pending_count > 0 时拦截（docs/PUSH.md 中的“Pending”）。若要在 git push / terraform apply / kubectl apply 实际执行的时刻，在任何客户端中进行检查，请参阅执行时 pulse shim。 Agent 在阅读内容后写下的备注会关联到所读内容；当来源变更时，该备注会标记为 never_act / stale_derived（docs/HONESTY.md §6）。

Cursor

Cursor 会读取 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json （全局），并在 command、args、env、url 和 headers 中插入 ${workspaceFolder}、${userHome} 和 ${env:NAME}：

{
  "mcpServers": {
    "kronicle-lite": {
      "command": "npx",
      "args": ["-y", "kronicle-lite", "serve", "--actor", "cursor"]
    }
  }
}

此配置使用默认存储（~/.kronicle-lite，与其他客户端共享；自 0.5.0 起，文档按项目隔离），这也是执行时 shim 检查的存储。若要为每个工作区单独使用一个存储，请添加 "--data-dir", "${workspaceFolder}/.kronicle-lite"： shim（0.8.1）会从命令所操作的仓库向上查找项目本地的 .kronicle-lite/；但当 ~/.kronicle-lite 中也有存储时，它们无法判断 Agent 使用的是哪一个，因此会拒绝执行会改变世界的命令，直到你指定其中一个（kronicle-lite shim install --data-dir DIR）。

若要使用下方的 HTTP 模式，请使用 { "url": "http://127.0.0.1:7417/mcp", "headers": { "Authorization": "Bearer ${env:KRONICLE_LITE_BEARER}" } } 代替 command / args。自 0.5.0 起，可为 2025 年代的 HTTP 客户端（如 Cursor）提供服务（无状态）；此前会被拒绝。 来源： Cursor 文档 — Model Context Protocol。

Claude Desktop

claude_desktop_config.json：

{ "mcpServers": { "kronicle-lite": { "command": "npx", "args": ["-y", "kronicle-lite", "serve", "--actor", "claude-desktop"] } } }

Codex

~/.codex/config.toml（或受信任项目中的 .codex/config.toml）：

[mcp_servers.kronicle-lite]
command = "npx"
args = ["-y", "kronicle-lite", "serve", "--actor", "codex"]
# optional: default_tools_approval_mode = "writes"   # prompt only for put/supersede/tombstone

Codex 会在启动时读取服务端的 instructions，并将前 512 个字符用作服务级指导；kronicle-lite 的 instructions 即 orient 循环，长度符合限制。根据 OpenAI 的文档，同一文件还支持 enabled_tools / disabled_tools、startup_timeout_sec（默认值为 10）和 tool_timeout_sec（默认值为 60）。来源： OpenAI — Model Context Protocol。

GitHub Copilot（编码 Agent + 代码审查）

在仓库的 Settings → Copilot → MCP servers（位于“Code, planning, and automation”下）；Copilot 编码 Agent 和 Copilot 代码审查共用此配置：

{
  "mcpServers": {
    "kronicle-lite": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "kronicle-lite", "serve", "--data-dir", "./.kronicle-lite", "--actor", "copilot"],
      "tools": ["get_system_state", "audit_assumptions", "recall", "verify", "verify_chain", "anchor_status"]
    }
  }
}

存储位于检出目录中（./.kronicle-lite）：在同一环境中安装的执行时 shim 会从仓库向上查找该存储（0.8.1），也可以通过 kronicle-lite shim install --data-dir "$PWD/.kronicle-lite" 将其指定为固定路径。

必须设置 tools；GitHub 建议将工具白名单限制为只读工具，因为 Agent 会直接调用这些工具，不会先询问。上方的六个工具是 kronicle-lite 标记为 readOnlyHint: true 的工具；Copilot 代码审查也会使用这些工具（它会忽略没有此注解的工具）。若要让编码 Agent 执行写入操作，可添加 put_document、supersede_block、tombstone_block（或 "*"）。密钥必须命名为 COPILOT_MCP_*，并通过 env 引用。来源： GitHub 文档 — 使用 MCP 扩展 Copilot 编码 Agent。

更多内容见 examples/。

Streamable HTTP：serve --http

适用于无法启动进程的客户端（或同一台设备上共享一个存储的多个客户端）：

kronicle-lite serve --http                       # http://127.0.0.1:7417/mcp
kronicle-lite serve --http --port 9000           # other port
kronicle-lite serve --http --bearer-file ./token # token from a file you manage
kronicle-lite serve --http --bearer "$TOKEN"     # token from the environment

• 身份验证。 每个请求都必须携带 Authorization: Bearer <token>。默认情况下，令牌存放在 <data dir>/http-bearer.token 中，首次运行时生成，文件权限为 0600；使用 cat ~/.kronicle-lite/http-bearer.token 查看。
• 环回地址。 绑定到 127.0.0.1；会根据环回地址验证 Host 和 Origin（防御 DNS 重绑定）。使用 --host 0.0.0.0 --allow-host myhost.lan --allow-origin myhost.lan 可开放访问；请在前面配置 TLS。
• 无状态，兼容两个时代。 不使用会话 ID，GET/DELETE 返回 405。2026-07-28 请求会在 _meta 和 MCP-Protocol-Version 标头中携带协议版本；对于使用 initialize 启动的 2025 年版本客户端（Cursor 和目前大多数客户端），每个请求都会由一个全新的服务实例处理（0.5.0）。--modern-only 会像 0.4.0 一样，通过 UnsupportedProtocolVersionError（-32022）拒绝这些请求。
• 信任域。 单租户：令牌就是整个存储。请参阅 docs/THREAT-MODEL.md。

六十秒快速体验

安装 npm install -g kronicle-lite 后，即可在空目录中直接使用（数据存放在 ~/.kronicle-lite；添加 --data-dir DIR 可将数据存放在其他位置）：

printf '# Deploy runbook\n\n## Deploy target\nDeploys go to the staging cluster `stg-west-2` first.\n' > runbook.md

# store it: split into blocks, one hash-chained event per change
kronicle-lite put runbook runbook.md --title Runbook

# orient as an agent would, and keep the cursor it hands back
C=$(kronicle-lite orient --actor me --json | node -pe 'JSON.parse(require("fs").readFileSync(0)).cursor_compact')

# change the runbook behind the agent's back
sed -i.bak 's/stg-west-2/stg-east-1/' runbook.md
kronicle-lite put runbook runbook.md --title Runbook

# orient again with the cursor: the retraction says what changed, in words
kronicle-lite orient --actor me --cursor "$C" --focus retractions

# recompute every hash and link, and re-hash every stored block; exit 1 on a mismatch
kronicle-lite verify-chain > /dev/null && echo "chain and store verify"

# sign a Merkle checkpoint; take the chain elsewhere and rebuild from it
kronicle-lite checkpoint > /dev/null
kronicle-lite export --out events.jsonl
kronicle-lite import --data-dir ./copy --in events.jsonl

在 Agent 会话中，工作流程如下：get_system_state → 工作 → recall（保留回执）→ 在基于旧回执继续操作前运行 verify → 使用你的 cursor 写入 → 下一轮使用新的 cursor 再次运行 get_system_state。

锚定到本地之外（0.4.0）

kronicle-lite 免费且在本地运行。锚定只需添加一个标志 — checkpoint --push — 和一个任何人都可以检查的 URL。本地密钥可以证明这些行仍与本机签署的内容一致；但它无法对本机所有者提供任何证明，因为密钥由所有者持有。锚定服务会用自己的密钥对你签署的 Merkle 根进行联合签名，并附上 received_at 时间，因此即使本地重新签名，之后对已锚定范围的改写仍可被检测到。

# config: flags > env > <data-dir>/config.json > default
export KRONICLE_ANCHOR_KEY=KLA_…                 # or {"license_key": "KLA_…"} in config.json (0600)
# export KRONICLE_ANCHOR_URL=https://anchor.isokron.ai   # the default

kronicle-lite checkpoint --push        # sign a checkpoint, anchor it, store the countersigned receipt
kronicle-lite verify --remote          # recompute every anchored range; exit 1 on
                                       #   "local chain diverges from anchor at [a,b]"
kronicle-lite verify --remote --offline   # same, from stored receipts + the pinned service keys
kronicle-lite anchor status            # last anchor, status, events since (no network)
kronicle-lite anchor keys              # pinned anchor service keys (add PEM-FILE | remove KEY_ID | reset)

• **哪些内容会离开本机：**根、范围、签名和你的公钥。 绝不会发送事件或内容。详情请见 FORMAT §9 和 THREAT-MODEL。
• MCP：checkpoint_chain {push: true} 会在本地检查点旁返回锚定结果；anchor_status（只读）会将本地链与上次锚定进行比较（match | diverged | beyond_head | gap | unverified），remote: true 还会向服务查询。一旦有内容完成锚定， get_system_state 就会添加一行横幅：anchored N events ago (status)；在此之前，它不会提及锚定，而 doctor 只有在配置了许可证密钥或 URL 时才会探测服务。
• **服务。**默认服务 https://anchor.isokron.ai 已部署 Free 计划。无法连接时，--push 会在本地保存检查点，并以状态码 2 退出，显示 anchor service unreachable at …； verify --remote 也会以相同方式退出；所有本地命令、MCP 服务和 orient 的行为都与未启用锚定时完全相同。
• **客户端信任的内容（0.8.1）。**只有联合签名收据：每次比较都使用收据中的根和范围，且收据的联合签名必须通过固定的服务密钥验证，检查点签名必须通过你自己的链密钥验证 — 绝不使用服务列表中未经签名的字段或本地 anchors.root 列。首次在线推送或执行 verify --remote 时，会固定服务提供的密钥（<data-dir>/anchor-keys.pinned.json，0600）；之后只有在固定密钥提供后继签名，或通过 anchor keys add 添加时，才会接受新密钥。即使服务停止列出你持有的收据，也会对其进行检查。 除非主机为环回地址或你传入 --insecure-http，否则会拒绝 http:// URL；请优先使用 KRONICLE_ANCHOR_KEY / config.json，而不是 --key（它会发出警告：其他用户可以看到 argv）。
• 退出码：0 表示正常，1 表示分歧、冲突或收据不可信，2 表示用法或 I/O 错误（包括无法连接和被拒绝的 http:// URL）。

链接指令（0.4.0）

Agent 的指令也是笔记，会以相同方式过时： 有人编辑 CLAUDE.md，重写规则文件，或 Claude Code 的自动 记忆索引发生变化。kronicle-lite 可以将这些指令串联起来，因此，变更后的指令属于取代，而下一次 get_system_state 会将其列为 instruction 类型的撤回，并以文字说明（You previously relied on instruction "Use pnpm, not npm." (instructions/acme-api-1a2b3c4d/claude-md › Project); current truth is "Use bun, not npm." …）。文件被删除时， 其区块会退役（严重性为 safety）。

默认文件集相对于 git 工作树根目录（或工作目录）。 从 0.5.0 起，每个 slug 都包含一个项目密钥，即 <repo dir name>-<8 hex of the root path's sha256>，因此一个数据目录可以服务多个仓库： 同步仓库 B 的 CLAUDE.md 永远不会影响仓库 A，而在 A 中定向的 Agent 不会看到 B 的指令变更（all_projects: true / --all-projects 可显示这些变更）。KRONICLE_LITE_PROJECT=<name> 可固定密钥。

文件	slug
CLAUDE.md	instructions/<key>/claude-md
AGENTS.md	instructions/<key>/agents-md
.claude/rules/**/*.md	instructions/<key>/claude-rules/<path>
.cursor/rules/**	instructions/<key>/cursor-rules/<path>
Claude Code 自动记忆 MEMORY.md	memory/<key>/MEMORY
从 0.4.0 升级：首次同步某个文件时，如果无键文档（instructions/claude-md）中仍保存着与该文件完全相同的文本，就地重命名该文档（生成 document.renamed 事件）：块保持不变，凭据仍可验证，不会撤回。如果无键文档保存的是其他文本（在共享数据目录中可能属于另一个项目），则保持原样。

自动记忆保存在 ~/.claude/projects/<project>/memory/MEMORY.md 中，其中 <project> 是 Git 仓库的主工作树根目录（所有工作树和子目录共享；在 Git 仓库外则为当前工作目录），且其中每个非字母数字字符都会替换为 -。CLAUDE_CONFIG_DIR、CLAUDE_CODE_PROJECT_DIR_NAME 和 autoMemoryDirectory 均按 Claude Code 文档中的说明处理 （记忆， 会话）。 kronicle-lite watch --list 会打印解析出的路径。

kronicle-lite put --from-instructions          # one shot: chain whatever changed
kronicle-lite watch                            # keep chaining while files change (Ctrl-C to stop)
kronicle-lite watch docs/ AGENTS.md --interval 5000
kronicle-lite watch --list [--json]            # show the resolved set and slugs

未更改的文件不会追加任何内容。watch 会使用 fs.watch 监视所在目录，并结合防抖（150 ms；--debounce）和轮询检查（--interval，默认 2000 ms），轮询检查也会发现新的规则文件；--poll 则仅使用轮询。

在项目内移动文件且内容保持不变，属于重命名而非移除：无论先同步两个路径中的哪一个，文档都会跟随文件移动（生成 document.renamed 事件，块和凭据保持不变，不会撤回）。仅格式变更——除换行符外原始文本相同，包括行尾空格、段落内的重新排版和空行（但代码、引文或链接目标内部不包括在内）——会像其他变更一样串联处理，但会记录在 format_only_edits 下，而不是作为撤回来处理。其他所有变更都会连同差异一起撤回：字符、引号、日期、大小写或连字符变更，行内的双空格或制表符，强调或列表标记变更（*↔_、1)↔1.、重新编号：Agent 会将原始文本复制到命令中），段落移到其他章节，以及章节内的块顺序调整。疑似拼写错误的变更会带有 hint: likely_typo，这只是一个标签。

在 Claude Code 中：使用钩子，而不是监视器。 Claude Code 已经会监视文件：SessionStart 钩子可以返回 watchPaths，而每当其中一个路径在磁盘上发生变化时，FileChanged 钩子就会运行，不论是谁写入了该文件 （钩子：FileChanged）。 put --from-instructions --stdin-hook 同时充当这两种钩子：在 SessionStart 时同步文件集并通过 watchPaths 响应；在 FileChanged 时重新写入单个文件，并在有变更时发布一行 systemMessage。它绝不会导致钩子失败。这就是 cc-anchor 的 watchPaths / FileChanged 钩子的形式；如果当前使用的 cc-anchor 尚未提供该钩子，或没有使用 cc-anchor，请将其添加到 .claude/settings.json 中：

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "kronicle-lite put --from-instructions --stdin-hook", "timeout": 30 }] }
    ],
    "FileChanged": [
      { "hooks": [{ "type": "command", "command": "kronicle-lite put --from-instructions --stdin-hook", "timeout": 30 }] }
    ]
  }
}

FileChanged 组有意不设置 matcher：这样它就会针对动态监视列表中的每个路径运行。为钩子全局安装 kronicle-lite（npx 每次调用会增加数秒耗时），并传入与 MCP 服务相同的 --data-dir。在其他所有环境中——Cursor、Codex、Copilot 或普通编辑器——请在终端中运行 kronicle-lite watch，或将其作为用户服务运行。

Git 感知块（0.4.0）

从 Git 仓库中的文件写入文档时，可以记录其来源 blob，这样“操作手册说 X”就会根据当前操作手册文件进行核验，而不仅仅是根据存储内容核验：

kronicle-lite put deploy docs/deploy.md --bind-git     # records {repo_root, commit, path, blob_sha}

通过 MCP 使用：put_document {slug, title, markdown, source_path, bind_git: true}。 当工作树文件发生变化（或被删除）时，对该文档凭据执行 verify 会返回 STALE_SOURCE，而 audit_assumptions 会将相关主张评为 stale_source；两者都会附带差异统计（+3 −1），以及绑定 blob 与工作树 blob；get_system_state 会在 来源漂移 标题下列出该文档。使用 --bind-git 重新写入以重新绑定。它只会使用 git rev-parse / git hash-object / git cat-file；如果在仓库外（或未安装 Git），写入仍会成功并显示警告，但不会绑定任何内容。

kronicle-lite doctor（0.4.0）

kronicle-lite doctor                 # human-readable; exit 1 when any check fails
kronicle-lite doctor --json          # the full report
kronicle-lite doctor --no-network    # skip the anchor reachability probe
kronicle-lite doctor --full          # verify the whole chain, not the last 1000 events
kronicle-lite rebuild                # re-derive documents and blocks from a chain that verifies

只读：不会创建数据目录，也不会写入密钥、配置或架构。 检查内容：Node 版本（≥ 20）；数据目录和密钥文件的权限模式（目录为 0700， 密钥为 0600——签名密钥、游标密钥、Bearer 令牌或包含许可证的 config.json 若可被组或其他用户读取，则检查失败）；PRAGMA integrity_check； 最近 1000 个事件的链链接和哈希，以及每个检查点；从链中重放并重新哈希的 已存储文档、修订版本和块（0.5.0；若不匹配则检查失败，链验证通过后，rebuild 会修复一次）；FTS5 索引与 blocks 的一致性；此版本提供的 MCP 目录与此版本固定的 指纹是否一致；config.json 的合理性；最后一个锚点与本地根节点是否一致（不一致则检查失败）； 锚点服务是否可访问（仅在配置了锚定时检查，且只发出警告）；哪些 MCP 客户端已配置 kronicle-lite （~/.claude.json 用户和本地作用域、.mcp.json、.cursor/mcp.json、 ~/.cursor/mcp.json、~/.codex/config.toml——只读取，不写入），以及配置使用的 --data-dir。在 Windows 上，会额外提示 POSIX 权限模式在该系统上不起作用，并提供一条 用于限制数据目录权限的 icacls 命令。

执行时脉冲垫片

推送钩子只能触达配置了钩子的客户端，而在 Bash 调用前进行检查，会漏掉在 build && deploy 运行期间才到达的运行手册变更，也会漏掉隐藏在 make release、bash -c "$CMD" 或包装脚本中的部署。垫片会在真正的二进制文件执行时进行检查，适用于任何客户端（Claude Code、Cursor、Codex、Hermes，以及终端中的人工用户）：

kronicle-lite shim install                      # git terraform tofu kubectl helm npm pnpm yarn → ~/.kronicle-lite/shims
export PATH="$HOME/.kronicle-lite/shims:$PATH"  # FIRST on PATH: shell profile and each agent's environment
kronicle-lite shim status                       # active on PATH? real binaries? anything blocking here?
kronicle-lite shim install --git-hook           # git: also a pre-push hook in this repo (catches every push)

每个垫片都是一个小型 POSIX shell 包装器（Windows 上另有 .cmd/.ps1）。只读调用（git status、terraform plan、kubectl get）会立即通过仅使用 shell 内建命令的方式执行真正的二进制文件，开销约为 1 ms，且不会启动 node。会改变世界的命令（git push、terraform apply、kubectl apply|delete|patch|replace|rollout …、helm install|upgrade|uninstall、npm|pnpm|yarn publish、npm run deploy，以及你自己的 --world "make release,docker push"）会先运行 kronicle-lite pulse（约 0.2 秒）：如果某个文档自上次检查后发生了变更，而读取过该文档的人尚未重新读取当前版本，就会拒绝执行，并显示差异（退出码 77）：

$ terraform apply
kronicle-lite shim: did NOT run `terraform apply` — kronicle-lite has 1 change(s) you have not reconciled (head seq 7):
- runbook › Runbook › Deploy (seq 7, supersession/behavioral): relied on "Target: prod-a" → now "Target: prod-b"; diff: Target: [-prod-a-]{+prod-b+} [not yet re-read at the current version by: agent-a]
Re-read the pending item(s) above … reading the current version clears the gate by itself. Then run the command again.
Still to re-read the current version: agent-a (the invoking actor, agent-a).
If you cannot re-read them yourself, stop and ask the operator.

此门控与版本绑定，类似 pending：一旦 Agent 再次查看运行手册（或读取 kronicle://docs/runbook）并获得当前版本，同一命令就会运行，无需确认。需要重新读取的人：使用 shim install --pending-actor <agent> 指定的 Agent；否则为调用方（其环境中的 KRONICLE_LITE_ACTOR）；若仍未指定（或使用 --all-readers），则为所有读取过变更区块的人。项目指的是该命令所操作的项目（git -C、--git-dir、terraform -chdir= 等）。kronicle-lite shim ack --through SEQ 是操作员覆盖选项：需要终端或 --operator，操作会被记录，且拒绝提示中不会提及此选项。

PATH 垫片只能拦截通过 PATH 找到的命令；shim install --git-hook 会添加一个 git pre-push 钩子，检查每次推送（绝对路径、sudo、别名、钩子、rebase -x；--no-verify 除外）。--mode warn 会打印相同的信息并运行命令。如果存储未通过完整性检查，在两种模式下都会拒绝会改变世界的命令（故障时默认拒绝）；存储文件损坏时也是如此（0.8.1）。垫片会检查服务使用的存储：shim install --data-dir DIR 会固定该目录；否则使用 $KRONICLE_LITE_DATA_DIR 或 ~/.kronicle-lite，以及仓库上方项目本地的 .kronicle-lite/（0.8.1）。若没有存储，或存在两个不同的存储，拒绝模式会拒绝会改变世界的命令；若缺少 kronicle-lite CLI 或发生崩溃，则允许命令运行（故障时默认放行，仅在 stderr 中提示一次，并记录到 .kronicle-shim/shim.log）。检查超时（KRONICLE_SHIM_TIMEOUT，默认值为 10 s）时，每次都会打印 kronicle-lite check TIMED OUT … was NOT checked 并运行命令；若使用 shim install --on-timeout deny，则会以退出码 77 拒绝执行。每次会改变世界的调用，其检查时间和结果都会写入 shim.log。匹配规则、递归保护、对账、按项目确认以及客户端代码片段详见：docs/PUSH.md § Shims。

工具

工具	功能	写入链
get_system_state	获取概况。since_cursor → 此后发生的变化；漂移提示；撤回内容及其 old_text / new_text / diff；此后写入的你自己的笔记（carried_notes）；完整性检查；新游标。没有新内容 → 一行答复。focus：orientation（默认）、recent_changes、retractions、pulse。response_format：markdown（默认）或 json。限定于此项目（all_projects 可取消此限制）；仅格式编辑列在 format_only_edits 下（使用 include_format_only 可包含）。	否
audit_assumptions	对声明 {symbol, value}（区块 ID、文档 slug 或 head）进行评级 → current | stale | contradicted | retracted | unknown | stale_source，并返回当前事实和一行协调说明。	否
recall	对有效区块进行 FTS5 bm25 搜索；每条命中都带有绑定到链头的收据 v2，以及（0.6.0）authority / authority_reason / authority_basis；结果带有 authority_floor、absence，并在提供 cursor 时进行注意力重排（already_read）。若区块存储文本的哈希与链不再匹配，则会将其扣留（withheld），绝不提供。搜索此项目的文档和未限定范围的文档（all_projects 可取消此限制）。收据以 receipt_id 返回（设置 receipts: "inline" 可返回对象）。top_k、include_tombstoned、include_receipts、receipts、max_chars（默认 4000）、all_projects、cursor、actor_id。	否（存储收据）
verify	根据实时存储重新推导收据（对象或 receipt_id；0.9.0：通过 receipts / receipt_ids 最多传入 100 条，顶层结果 = 第一条非 VERIFIED 状态），检查签名、区块是否存在、重新哈希的区块文本与链是否一致、链绑定、取代关系遍历、绑定到 Git 的来源 → VERIFIED | SUPERSEDED | TOMBSTONED | UNVERIFIED | STALE_SOURCE + 原因。	否
verify_chain	重新计算某个范围内的每个哈希和链接；定位首个不匹配项；检查点结果；对整个链还会检查投影（重新推导并哈希每个存储的文档和区块）。	否
checkpoint_chain	使用本地密钥为某个 seq 范围签署 Merkle 根；push: true 还会将其锚定到外部。	否（检查点、锚定表）
anchor_status	最近一次外部锚定、此后的事件，以及本地链是否仍与之匹配（remote: true 会查询服务）。	否
put_document	按 slug 创建或重新写入 Markdown 文档。未更改的区块保留原 ID；已更改的区块会被取代；已移除的区块会被标记为墓碑。bind_git + source_path 可将文档绑定到文件的 Git blob。检测到机密信息时会拒绝操作（secret_detected）；redact_secrets: true 会存储脱敏副本。	是
supersede_block	用新内容和原因替换一个有效区块（机密信息防护与 put_document 相同）。	是
tombstone_block	使用原因将一个有效区块标记为退役。	是
apply	0.9.0：在单个 SQLite 事务中执行最多 50 个 put / supersede / tombstone 操作（all_or_nothing），或采用 best_effort；每个操作均可设置 expect_version；dry_run 预览精确差异，并返回一次性且会过期的 confirm_token，该令牌绑定到计划及其所见版本（状态已更改 → stale_plan）；idempotency_key 可重放；生成一个 apply.committed 事件（文档）。	是
audit_record	0.9.0：追加 MCP 审计证据（catalog_snapshot、call_measured、finding、gate_result、fix_applied、regression_result），进行架构验证，全部成功或全部失败，并通过 event_key 实现幂等；仅存储哈希和 blob 引用（文档）。	是
audit_query	0.9.0：按 audit_id 和/或目录 fingerprint 查询审计事件，并返回每项发现的当前状态（discovered / refuted / reopened / accepted）。	否
每个写入工具都接受可选的 cursor，并返回新的链头
以及 stale_write_advisory（仅作提示；过期写入检查不会阻止操作，机密信息防护机制会阻止）。kronicle://docs/{slug} 资源提供文档的当前修订版。put_document 最多列出前 100 个
区块，并通过 block_counts 汇总所有区块；blocks_next
（kronicle://docs/{slug}/blocks/{revision}/{offset}）用于分页获取其余区块。每个工具结果都小于 8 MiB；单条消息（stdio 行或 HTTP 正文）最大可达 16 MiB（KRONICLE_LITE_MAX_MESSAGE_BYTES），超出时会返回 JSON-RPC 错误，同时服务仍会继续运行。

serve --core（0.6.0）仅提供 get_system_state、 audit_assumptions、recall、verify、put_document 和 supersede_block，适用于上下文窗口较小的场景：tools/list 为 10.5 KB，而不是 14.2 KB。其目录单独固定 （.mcp-catalog/kronicle-lite-core.json）。

审计证据与证据包（0.9.0）

kronicle-lite audit put-blob | record | query | export 将 MCP 审计的 证据保存在链上（相关制品存储在与链相邻的内容寻址 Blob 存储中），而 audit export --audit-id A --out DIR 会生成一个确定性的证据包，供 kronicle-lite verify-bundle DIR 离线检查：规范字节、事件哈希、链连续性、签名的 Merkle 根、制品哈希、引用以及已编辑 / 缺失列表。检查通过只能证明记录完整，不能证明审计结论正确；对其根进行锚定可证明其在某个时间点已存在。操作流程：docs/EVIDENCE-BUNDLE.md。

诚实标签（0.6.0）

你看到的内容	含义	操作
authority: can_act	这段确切的区块文本当前存在于其记录的源文件中	依据它采取行动
authority: inspect_only	没有区块级证据（没有来源、仅有文档级来源信息、由模型编写的记忆，或无法读取来源）	可据此推理；采取行动前先核实
authority: never_act	已被取代、已墓碑化、因完整性问题而被扣留，或来源已不再包含它 / 已不存在	不要依据它采取行动；重新读取来源或查找后继内容
absence.verdict: absent_in_searched	在 searched 列出的范围内没有匹配项，且索引是最新的	将其视为在这些范围内不存在；not_searched 列出未搜索的范围
absence.verdict: cannot_certify	索引已过期 / 未热启动、匹配项被扣留，或未执行任何搜索	无法得出结论；修复存储（verify-chain、rebuild）或查询
already_read: true	你在本次会话中之前读过它（排名较低）	跳过它，除非需要再次查看
truncated	内容已截断以适应 max_chars	阅读 truncated.read 或增大 max_chars

完整规则表和不变量： docs/HONESTY.md。

密钥和秘密信息会被拒绝写入，而不是标记为已删除（0.6.0）

该链只追加数据，写入的每个字节都会参与哈希计算。墓碑标记会让 recall 隐藏一个区块，但不会从 events 表、export 或任何备份中移除秘密；按设计，删除它会破坏验证。因此，put_document、supersede_block、tombstone_block、kronicle-lite put、put --from-instructions、watch 和 import 都会在写入链之前扫描常见的秘密信息格式（服务商 API 密钥和令牌、私钥、JWT、scheme://user:password@ 连接字符串、Bearer 请求头、…_PASSWORD= / …_TOKEN= 赋值），并在发现时拒绝写入，返回 secret_detected，指出检测器和行号（绝不包含秘密信息）。覆盖方式：redact_secrets: true / --redact-secrets 会将副本中的每处匹配内容替换为 [REDACTED:<detector>] 后再写入链；import --allow-secrets 会原样导入（链中已写入的字节无法脱敏，否则会破坏其哈希）。独立的读取时规则集会在 recall、orient、audit_assumptions 和文档资源中遮蔽任何意外写入的数据（0.6.0 之前的数据、--allow-secrets）。

每个工具都声明了 outputSchema，并以 structuredContent 和文本块的形式返回相同的 JSON（默认情况下，get_system_state 会在文本块中呈现 Markdown；response_format: "json" 会让文本也采用 JSON 格式）。从 0.5.0 起，tools/list 会公布精简的输出架构（每个顶层字段都包含其类型、枚举值和 required；嵌套结构则仅以类型表示）和简短说明：12.4 KB，而非 43.2 KB（0.6.0 中为 13.6 KB，包含诚实标签字段）。结果仍会根据完整架构进行验证，该架构由 kronicle://schemas/tools 资源提供；orient 技能包含更详尽的指南。生成的目录固定在 .mcp-catalog/kronicle-lite.json，CI 会在字节不一致时失败（npm run catalog:check），因为说明或架构一旦变更，就会悄无声息地使每个客户端的提示词缓存前缀失效。

完整的哈希计算规则和载荷结构：docs/FORMAT.md。 本地签名能证明和不能证明的内容： docs/THREAT-MODEL.md。

对比

针对“Agent 根据过时笔记进行推理”这一问题，比较四个重要维度。以下内容依据各项目在本文撰写时的文档；欢迎指正。

	本地优先	防篡改日志	过时检测	签名回执
kronicle-lite	是（SQLite 文件）	是（SHA-256 链、公开创世区块、签名的 Merkle 检查点）	是（orient 差异、漂移提示、撤回、回执 SUPERSEDED/TOMBSTONED）	是（Ed25519，与链绑定）
参考 MCP 记忆服务	是（JSONL 知识图谱）	否	否	否
basic-memory	是（Markdown 文件 + SQLite 索引）	否	否	否
mem0	部分支持（可自托管；默认使用托管平台）	否	否（会对记忆去重和更新，但不会告知 Agent）	否
InALign	默认支持（记录 Agent 执行的操作的来源，可选云端）	是（SHA-256 链）	否	未说明

坦诚地说：前三者都是记忆存储，各自都能胜任本职工作；但它们都无法回答“我读到的内容是否发生了变化？”。InALign 对 Agent 做过的事进行哈希链记录；kronicle-lite 对 Agent 所知的内容进行哈希链记录，并对其被告知的内容签名。

简要保证

• 这条链可从公开创世块（sha256("kronicle-lite-genesis-v1")）开始验证。 验证时不需要任何秘密。
• Agent 读取的内容会对照链进行检查，而不只是检查日志： recall、verify 和文档资源会重新计算已存储文本的哈希值 （BLAKE3），并与创建该文本的事件进行核对；如果不匹配，则拒绝操作； verify-chain 和 doctor 会根据整条链重新推导整个存储。
• 收据会将 (block_id, content_hash, doc_slug, revision) 绑定到 (chain_seq, chain_head_hash)。如果 Agent 使用的存储被重置或改写，旧收据会变为 UNVERIFIED，而不会悄无声息地变成 VERIFIED。
• 签名密钥是本地的。它可证明数据不会因意外或无特权编辑而遭到破坏；但这不等同于第三方公证。若要将其用于对抗性场景，请先阅读威胁模型。
• 即使游标有误，定向操作也不会失败；服务会根据飞行记录器恢复位置，并说明这一点。
• （0.6.0）can_act 仅来自区块级证据；空的 recall 绝不会根据过时或尚未加载的索引声称“未找到”；如果简报隐藏了某个范围，就会说明内容不完整。

开发

npm install
npm run build          # tsup → dist/
npm test               # builds, then vitest (unit + MCP in-process, stdio, HTTP, legacy handshake);
                       # CI runs it on Ubuntu (Node 20, 22) and Windows (Node 22)
npm run lint
npm run catalog:check  # tools/list bytes vs .mcp-catalog/ (re-snapshot with catalog:snapshot)

有关有意尚未实现的内容（针对已发布锚点日根的包含证明、由链支持的工单、语义召回），请参阅 CONTRIBUTING.md（需要 DCO 签署）和 ROADMAP.md。

锚点验收测试会使用测试中的服务存根运行。如果也要在 Miniflare 下针对真实的 isokron-anchor Worker 运行这些测试，请将 KRONICLE_ANCHOR_WORKER_DIR 指向已安装其依赖项的代码库检出目录：KRONICLE_ANCHOR_WORKER_DIR=../isokron-anchor npx vitest run test/anchor.test.ts。

超越单个 Agent

kronicle-lite 有意设计为单个参与者、单个进程、单个信任域。 IsoKron 是基于相同理念发展而来的平台——由多个 Agent 共享的类型化图、可避免并行 Agent 冲突的声明隔离机制，以及按租户划分的链。该平台仍在开发中，尚未提供自助服务； https://isokron.ai 介绍了目前已有和尚未实现的内容。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。

---

由一位被裁员的支持工程师在 AZ 科奇斯县离网打造 — https://theexiledentrepreneur.com