Rekindle

npx rekindle init

Rekindle 是一款 MCP 连续性引擎，解决的是会话衔接问题，而不只是存储。会话开始时梳理背景，会话结束时记录信息，在会话中途压缩上下文时也能延续。全部本地运行，全部使用 SQLite，无需 API 密钥。

v0.4.1 — --global 钩子设置现在会写入 ~/.claude/settings.json，这是 Claude Code 在每个项目中都会应用的文件（修复了 #25）；初始化输出与本 README 保持一致。发行说明

快速开始

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

npx rekindle init

这会在你的项目中创建 .rekindle/，其中包含 SQLite 数据库、身份模板、连续性策略、项目注册表、捕获目录和对话记录目录。然后为你的客户端添加 MCP 服务配置：

claude mcp add rekindle -- npx -y rekindle

{
  "mcpServers": {
    "rekindle": {
      "command": "npx",
      "args": ["-y", "rekindle"]
    }
  }
}

npx rekindle setup-hooks

npx rekindle setup-delivery

{
  "mcpServers": {
    "rekindle": {
      "command": "npx",
      "args": ["-y", "rekindle"]
    }
  }
}

{
  "mcpServers": {
    "rekindle": {
      "command": "npx",
      "args": ["-y", "rekindle"]
    }
  }
}

然后填写 .rekindle/identity.md，并将启动指令粘贴到项目的 CLAUDE.md 中。

会话 1 存储，会话 2 记忆，会话 10 预判。

问题所在（43 个会话的数据）

在 43 个会话中，我们测量了 AI 助手在会话开始时未能加载的内容：

现有记忆工具（Mem0、Letta、Zep）专注于优化检索准确率：AI 能否找到它存储的内容？这是必要条件，但并非充分条件。它们都没有解决 AI 是否为本次会话加载了正确的上下文，也没有解决 AI 能否检测到遗漏内容的问题。

Rekindle 解决的是会话定向问题：在助手开始工作前加载身份、近期上下文、记忆健康状态和上下文缺失警告。

完整研究数据集请参阅 docs/gap-analysis.md。

功能

启动：在会话开始时定向

boot_report 会在任何工作开始前运行定向流程：

boot_report
  +-- Read identity document (who am I working with?)
  +-- Scan memory stats (what do I know?)
  +-- Find latest checkpoint (where did we leave off?)
  +-- Read last transcript (what actually happened?)
  +-- Surface open loops (what needs follow-up?)
  +-- Surface PreCompact captures (what survived compaction?)
  +-- Detect gaps (what am I missing?)
  +-- Calculate orientation score (how oriented am I?)
  --> "Carrying forward: [context loaded, gaps identified, score: 80/100]"

挺过漫长的中场：PreCompact 捕获（v0.3）

会话中途的压缩会破坏推理链、失败的尝试、关系细节和语气。PreCompact 钩子会在压缩前自动触发，并保存原本会丢失的内容：

PreCompact hook fires
  +-- Parse JSONL transcript (last N messages)
  +-- Write raw Markdown capture (.rekindle/captures/)
  +-- Write structured JSON snapshot (decisions, open loops, files)
  +-- Update manifest for cheap listing
  --> boot_report surfaces captures on next session start
  --> end_session warns if captures exist but weren't reviewed

三种读取模式用于控制 token 开销：

• summary — 一个段落，开销低
• structured — 决策/循环/警告，开销中等
• raw — 完整的对话摘录，开销高（仅在需要时使用）

捕获：在会话结束时闭环

end_session 会存储结构化的连续性记录，而不只是摘要：

所有记录都带有 type、source 和 session_id 元数据。下次 boot_report 会自动加载检查点。

会话之间：搜索和管理

类别： preference lesson context relationship general

为什么不直接用 CLAUDE.md？

静态文件是被动的。AI 可以读取它，却无法搜索、排序、跟踪已检索的内容，也无法指出缺失的信息。Rekindle 提供：

• 搜索 — 按重要性加权排名的全文搜索
• 结构 — 按类别和项目划分记忆范围
• 方向指引 — 启动时主动加载上下文，而不只是按需检索
• 缺口检测 — 标记缺失的身份信息、空类别和过时数据
• 评分 — 透明的检查清单，让你了解 AI 的方向感如何
• 会话捕获 — 通过检查点、决策和未完成事项进行结构化收尾
• 压缩后续存 — PreCompact 捕获内容可保留摘要压缩掉的信息

版本亮点

v0.4.1

• --global 钩子可在所有位置触发 — setup-hooks --global、setup-delivery --global 和 init --global --with-* 现在会写入 ~/.claude/settings.json（用户范围），而不是 ~/.claude/settings.local.json；Claude Code 仅会在从主目录启动的会话中读取后者（#25）。项目本地设置不变。每条命令都会打印写入的文件
• 未解析工作区警告会说明修复方法 — 当会话启动数据包无法将工作区映射到项目时，现在会说明未加载检查点，并指出两种解决方法：将工作区添加到所读取的注册表（项目存储使用 .rekindle/projects.json，--global 存储使用 ~/.rekindle/projects.json），或设置 REKINDLE_PROJECT。警告不会暴露注册表的绝对路径
• Init 输出与本 README 保持一致 — init 会优先显示 claude mcp add rekindle -- npx -y rekindle（使用 --global 时显示 claude mcp add --scope user ...，以便在全局钩子触发的位置注册服务），列出两个可选钩子（使用时附带 --global），并在使用 --global 时打印 ~/.rekindle/... 路径

v0.4.0

• 需要 Node.js 22 或更高版本 — Node 20 已于 2026 年 4 月结束生命周期，不再受支持；CI 使用 Node 22、24 和 26 运行
• 遵循策略的会话启动 — .rekindle/policy.json 控制转录处理方式（transcript_mode：captured、tail-read-only 或 excluded）、启动字节预算、必需与可选的数据包部分，以及后台钩子是否可以写入（background_writes_allowed）
• 安全的项目交付 — .rekindle/projects.json 将工作区映射到项目；未映射或存在歧义的工作区会标记为 UNKNOWN PROJECT，绝不会收到其他项目的检查点；REKINDLE_PROJECT 是显式覆盖项
• 尾部模式下不显示转录文件名 — 在 tail-read-only 模式下，数据包会显示转录尾部内容，但不显示文件名
• 原子化会话写入 — 会话行与审计行要么一起提交，要么都不提交
• 生产环境审计无问题 — npm audit --omit=dev 检查发现零个漏洞（生产依赖）
• 更小的软件包 — npm 压缩包大小从约 1.9 MB 降至约 110 KB；证据和设计文档保留在 GitHub 上

v0.3.3

• 协议元数据与版本保持一致 — MCP 初始化响应从随包发布的元数据中获取版本，避免发布版本不一致
• 软件包页面信息准确 — 发布到 npm 的 README 会在创建标签和软件包之前标明当前版本
• 扩展自动化测试，并新增打包产物检查，用于比对 MCP 元数据与已安装软件包的版本

v0.3.2

• 一条命令安装交付功能 — npx rekindle setup-delivery（或 init --with-delivery）配置 SessionStart 钩子的启用选项：可重复执行、保留其他工具的钩子，并拒绝损坏的设置文件
• 147 项自动化测试

v0.3.1 — “五项实测门槛”

• 会话启动时交付 — rekindle session-start 通过 SessionStart 钩子，在启动、恢复、/clear 和 /compact 时输出符合预算的定向数据包
• 数据包有预算，回执如实 — 数据包上限为 8,000 个有效 UTF-8 字节，并带有数据包内截断标记；回执仅证明内容已输出，绝不声称模型已看到内容
• 桌面端安全存储 — 存储根目录绝不根据启动位置推导（Claude Desktop 会在 / 目录下启动 MCP 服务）；采用明确的解析顺序，解析失败时立即报错
• 双通道指引 — 工作流指引同时通过工具描述和 MCP 指令传递，从结构上杜绝内容不一致
• Cursor 适配器 — session-start --client cursor 使用白名单解析 stdin；电子邮件和工作区路径绝不会进入回执
• 以实测为依据，而非凭假设 — 上述每项声明均有已发布的测量结果作为依据（证据，试验结果）

v0.3.0 — “挺过漫长的中途阶段” 新增了 PreCompact 捕获系统、未完成事项和审查跟踪 — v0.3.0 发布说明

CLI 命令

从源代码安装

git clone https://github.com/Skitchy/rekindle.git
cd rekindle
npm install
npm run build
node dist/init/cli.js init

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "npx rekindle precompact-capture",
            "timeout": 60
          }
        ]
      },
      {
        "matcher": "manual",
        "hooks": [
          {
            "type": "command",
            "command": "npx rekindle precompact-capture",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

“完整交付”是指方向说明包在会话边界自动送达，且模型确实能看到它——通过在接收层和模型层进行金丝雀探测来测量，而非凭空假定。详情和证据：兼容性测试结果。

Claude Code：会话开始时的方向说明（可选启用）

npx rekindle setup-delivery

会将此内容写入 .claude/settings.local.json（或使用 --global 时写入 ~/.claude/settings.json）：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          { "type": "command", "command": "npx rekindle session-start", "timeout": 60 }
        ]
      }
    ]
  }
}

数据包上限为 8,000 个有效 UTF-8 字节——经测量：当 hook 输出超过主机限制时，模型只会看到开头部分，且不会显示任何错误。如果为适应预算而删减部分内容，数据包内会有标记说明；.rekindle/receipts/session-start.jsonl 中的回执会准确记录实际发出的内容，但绝不会声称模型看到了这些内容。

Cursor：会话开始时的方向说明（可选启用）

Cursor 的 hook 系统可在会话开始时交付符合预算限制的方向说明包，经测量，已在 v0.3.1 兼容性测试中正常工作。设置需手动进行，且为可选启用——未经请求，Rekindle 绝不会安装 hooks。在项目的 .cursor/hooks.json 中添加：

{
  "version": 1,
  "hooks": {
    "sessionStart": [ { "command": "rekindle session-start --client cursor" } ]
  }
}

**隐私：**Cursor 的 hook 负载包含你的账户邮箱和工作区路径。适配器默认将该负载视为个人信息：只提取会话 ID 和工作区根目录（在进程内用于解析存储位置），原始负载、邮箱和任何路径都不会写入回执或任何其他产物。默认跳过后台 Agent（并如实记录回执）；设置 REKINDLE_ORIENT_BACKGROUND_AGENTS=1 可选择启用。

rekindle/
  src/
    index.ts          MCP server entry point
    server.ts         Server setup, tool registration (10 tools)
    storage/
      sqlite.ts       SQLite + FTS5, schema migration, sessions
    orientation/
      types.ts        OrientationResult, Gap, ScoreItem
      GapDetector.ts  Structural gap detection (8 codes)
      Scorer.ts       Orientation scoring (6 criteria, 100pts)
      OrientationService.ts   Orchestrator
      OrientationRenderer.ts  Markdown + JSON output
    captures/
      types.ts        CaptureEntry, StructuredSnapshot, HookInput
      CaptureManager.ts   Parse, capture, list, read, review tracking
      discover-transcript.ts  Auto-discover session transcripts
      precompact-capture.ts   CLI hook entry point
      capture-now.ts          Manual capture CLI
    tools/
      boot-report.ts  Orientation + open loops + capture awareness
      end-session.ts  Structured session close + capture warning
      list-captures.ts  List PreCompact captures
      read-capture.ts   Read captures in 3 modes
      capture-now.ts    Model-triggered manual capture
      store.ts search.ts list.ts delete.ts update.ts
    delivery/
      budget.ts       UTF-8 packet construction and atomic mandatory sections
      receipts.ts     Emission receipts (never claim model visibility)
      session-start.ts SessionStart hook adapter
      cursor.ts       Cursor hook adapter (privacy-whitelisted stdin)
      guidance.ts     Canonical workflow guidance, both channels
    init/
      cli.ts scaffold.ts setup-hooks.ts setup-delivery.ts templates/

测试

npm test

该测试套件在 CI 中通过 Node 22、24 和 26 运行，涵盖：存储 CRUD + FTS5 排名、方向说明领域（差距检测、策略感知评分、项目解析、服务、渲染）、捕获管理器（解析、限制、审核跟踪、格式化）、交付（原子数据包预算、回执、指导通道、Cursor 隐私哨兵）、两个 hook 的设置（架构、幂等性、拒绝损坏配置），以及 MCP 集成（全部 10 个工具及基于软件包信息生成的服务端元数据）。

路线图

下一步：“以网络的方式思考”——扩散激活、通过嵌入实现语义搜索、差距分析工具、评估测试框架。

许可证

MIT