1. 项目定位与范围

claude-session-continuity-mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现,目标是为 Claude 客户端提供会话连续性 (Session Continuity):在多轮对话、上下文压缩或中断恢复场景下,仍能读取到上一次的关键决策、文件操作痕迹与未完成的工作项。仓库以 TypeScript 为主要实现语言,在运行时通过 5 个钩子 (hooks) 与宿主 (Claude/IDE) 集成,并以 better-sqlite3 作为本地持久化引擎。资料来源：package.json:1-80

社区共识:v1.15.0 之前曾因 Node 26 升级导致 better-sqlite3 原生模块 ABI 不匹配,使所有 5 个 hook 静默失败;该版本同时新增 logHookError 工具函数,从架构层面保证 hook 错误可观测。资料来源：package.json:1-80

2. 进程级架构

服务器进程由三个层次组成,从外到内依次为协议适配层、工具能力层、持久化层。

• 入站请求首先进入 src/index.ts,在那里完成 MCP 初始化与 schema 校验,然后按名称分发到 tools/ 或 tools-v2/。资料来源：src/index.ts:1-120
• tools-v2/ 是默认入口,负责把业务能力以 JSON Schema 的形式暴露给客户端;tools/ 主要承担向后兼容与回退。资料来源：src/tools-v2/index.ts:1-200
• 所有 I/O 边界(参数验证、响应包装)统一依赖 src/schemas.ts,避免在分散的处理器中重复声明形状。资料来源：src/schemas.ts:1-160

3. Hook 体系与故障可观测性

仓库对外暴露 5 个 hook,分别对应 Claude 会话生命周期的关键阶段(例如会话开始、消息前/后、工具调用前后、会话结束)。每个 hook 都遵循同一执行模式:读取 SQLite 中的会话行 → 决定是否注入上下文 → 写回增量状态。

由于 hook 在宿主侧运行,任何抛出的异常都会导致宿主层面的"静默降级"。v1.15.0 的关键修复是新增 logHookError:在 hook 调用入口外层包一层 try/catch,并把错误写入结构化日志,而不是让原生模块崩溃拖垮整个 MCP 服务。资料来源：src/index.ts:40-90

last_work 是 5 个 hook 共享写入的核心字段。最新版本还做了两件事以提升连续性质量:

1. 跳过被注入的命令 (injected command bodies),避免把宿主插入的提示误当成"用户上一次的工作"。资料来源：src/types.ts:1-120
2. 从消息体中抽取真正的请求 (real request),降低上下文回放时的噪声。

4. 数据流与会话写入恢复

sequenceDiagram
    participant C as Claude 客户端
    participant M as MCP 服务器(index.ts)
    participant H as 5 个 Hook
    participant S as SQLite(better-sqlite3)

    C->>M: 1. 初始化握手 / list_tools
    M-->>C: 返回 tools-v2 注册的工具清单
    C->>M: 2. 触发会话事件(开始/消息/工具调用/结束)
    M->>H: 3. 分发给对应的 hook
    H->>S: 4. SELECT 当前会话上下文
    S-->>H: 返回 last_work 等状态
    H->>H: 5. 在 logHookError 包裹下执行业务逻辑
    H->>S: 6. UPDATE 增量状态(过滤注入命令)
    M-->>C: 7. 注入 keep-going 提示或工具结果

要点:

• 步骤 3-6 必须在 hook 内完成,且必须被 logHookError 包裹,否则任何原生层失败都会让回放链路"看上去正常但实际丢失"。
• 步骤 6 的写入受唯一会话 ID 控制,确保并发事件不会互相覆盖。
• 整个链路依赖 [email protected] 及以上,否则在 Node 26 (ABI 147) 上会因 ABI 141 不兼容而无法启动数据库。资料来源：package.json:40-70

5. 工程依赖与运行时约束

package.json 同时锁定了三个关键决策:TypeScript 编译器版本(保证 src/types.ts 的高级类型可用)、MCP SDK 版本(决定 tools/ 与 tools-v2/ 的注册 API)、以及 better-sqlite3 ≥ 12.11.1(ABI 兼容性的硬底线)。资料来源：package.json:60-80

任何后续重构——例如替换持久化层、把 hook 拆成独立 npm 包——都需要先核对这三项约束,否则会触发与 v1.15.0 类似的环境性故障。架构设计的核心原则是:让 hook 不再静默失败、让会话状态可恢复、让上下文回放只携带真正的工作。

1. 概述：5 个钩子组成的连续性管道

claude-session-continuity-mcp 通过 Claude Code 生命周期内的 5 个钩子构建了一条自动上下文管道，将每次会话的关键事件持久化到本地 SQLite 中，并在下一个会话开始时回放，从而实现"会话连续性"。这 5 个钩子分别覆盖会话启动、用户输入、工具调用、上下文压缩前、会话结束五个时间点。

install.ts 负责将这 5 个钩子注册到 Claude Code 的配置中，确立管道的执行入口。资料来源：src/hooks/install.ts

2. 钩子职责与上下文流转

每个钩子通过 better-sqlite3 进行同步写入，保证事件不丢失。资料来源：src/hooks/session-start.ts、src/hooks/user-prompt-submit.ts、src/hooks/post-tool-use.ts

flowchart LR
    A[SessionStart] --> B[UserPromptSubmit]
    B --> C[PostToolUse]
    C --> C
    C --> D[PreCompact]
    D --> E[SessionEnd]
    E --> SQLite[(better-sqlite3)]
    SQLite --> A

3. v1.15.0 关键修复：写入停止恢复

v1.15.0 发布说明披露了一次严重的"静默故障"：Node 26 升级到 ABI 147 后，预编译的 better-sqlite3 原生模块（针对 ABI 141 构建）加载失败，导致 5 个钩子在用户毫无察觉的情况下全部失活。表现为会话结束后没有写入、下一轮 SessionStart 也读不到任何 last_work。资料来源：src/hooks/post-tool-use.ts、src/hooks/session-end.ts

修复策略包含两个层面：

• 依赖升级：将 better-sqlite3 升级到 12.11.1，使其兼容当前 Node ABI，重建原生绑定。
• 可观测性增强：新增 logHookError 工具函数，在任意钩子抛出异常时打印结构化错误（含堆栈、钩子名、阶段），从此钩子不再"静默死亡"。

资料来源：src/hooks/install.ts、src/hooks/session-start.ts

4. logHookError 与故障恢复语义

logHookError 的设计目的是把"失败"从隐性状态提升为显性日志，配套的故障恢复语义包括：

• 不抛出：钩子回调中若捕获到 SQLite 错误，仅记录日志并放行，避免中断主对话流。
• 就近记录：每个钩子文件内部对自身敏感路径（如 db.prepare(...).run(...)）做 try/catch 包裹并调用 logHookError。
• 降级运行：当持久化失败时，钩子返回最小可用结果（例如空上下文），让 Claude Code 仍可启动下一轮会话。

资料来源：src/hooks/pre-compact.ts、src/hooks/user-prompt-submit.ts

5. 连续性质量改进：`last_work` 净化

v1.15.0 同时优化了 last_work 字段的提取逻辑：跳过由系统注入的命令体（如 <command-name>、<system-reminder>），仅保留真实用户请求。该逻辑主要落在 user-prompt-submit.ts 的解析阶段，使下一会话恢复时能精准还原"用户上一次真正想做的事"，而不是被环境噪声污染的代理字符串。资料来源：src/hooks/user-prompt-submit.ts

6. 维护建议

• 升级 Node 主版本后，必须重新构建 better-sqlite3 原生绑定（npm rebuild better-sqlite3 或升级到兼容版本）。
• 在 CI 中加入"钩子烟雾测试"：模拟一次 SessionStart → UserPromptSubmit → SessionEnd 流程并断言 SQLite 写入条数，可提前发现 ABI 不匹配类故障。
• 任何新增钩子都应使用统一的 logHookError 包裹错误路径，保持"永不静默失败"的契约。

概述

本系统采用 SQLite 作为本地持久化底座，配合嵌入（embedding）缓存与"关系（relation）"工具，构成会话连续性的数据核心。所有会话摘要、用户偏好、最后工作状态以及实体间关系都通过该数据层进行读写，并通过 MCP（Model Context Protocol）暴露给上层代理。整套数据栈设计为同步、零网络依赖、可在 Node.js 进程内直接运行。资料来源：src/db/database.ts:1-40

1. SQLite 数据层（`src/db/database.ts`）

数据层使用 better-sqlite3 原生模块进行同步读写，相比异步驱动更适合 MCP 钩子（hook）场景——钩子需要在请求响应生命周期内阻塞返回结果。资料来源：src/db/database.ts:1-30

1.1 关键依赖与版本

• 依赖：[email protected]（v1.15.0 升级）
• 历史问题：Node 26 升级至 ABI 147，而旧版 better-sqlite3 构建于 ABI 141，导致原生模块加载失败，5 个钩子被静默停用
• 修复策略：将 better-sqlite3 升至与当前 Node ABI 兼容的版本，并配合 logHookError 让任何钩子异常都不再被吞掉
• 资料来源：package.json

1.2 钩子错误可见性

v1.15.0 引入 logHookError，统一将钩子内部的异常通过 logger 写盘，避免因原生模块失配等"无声故障"导致会话连续性中断。资料来源：src/utils/logger.ts:1-50 src/db/database.ts:40-90

2. 嵌入与缓存（`src/utils/embedding.ts`、`src/utils/cache.ts`）

2.1 嵌入管线

embedding.ts 负责把文本片段（会话摘要、last_work、实体描述）转换为向量表示，供语义检索使用。其典型流程为：

1. 规范化文本（去除注入的命令体、空标记）
2. 调用嵌入模型获得向量
3. 将向量与主键一并落库或写入缓存
4. 资料来源：src/utils/embedding.ts:1-60

2.2 缓存策略

cache.ts 在嵌入层之上提供短期缓存，避免对相同文本重复调用模型。缓存键通常由文本指纹 + 模型版本组成，命中后直接返回已计算向量。资料来源：src/utils/cache.ts:1-50

2.3 与 `last_work` 的关系

v1.15.0 同时优化了 last_work 的清理逻辑：跳过被注入的命令体，仅提取真实用户请求，保证嵌入向量反映意图而非噪声。资料来源：src/utils/embedding.ts:60-110

3. 记忆与关系工具（`src/tools/memory.ts`、`src/tools/relation.ts`）

memory.ts 是写入入口，所有钩子最终都通过它落地持久化数据；relation.ts 则在记忆之上叠加图结构，使代理能够回答"X 与 Y 的上次关联是什么"这类跨会话查询。资料来源：src/tools/memory.ts:1-60 src/tools/relation.ts:1-60

4. 数据流与架构

flowchart LR
  Hook[Claude Hooks] -->|写入| Mem[memory.ts]
  Hook -->|查询| Rel[relation.ts]
  Mem --> DB[(better-sqlite3)]
  Rel --> DB
  Mem --> Emb[embedding.ts]
  Emb --> Cache[cache.ts]
  Emb --> DB
  DB --> Logger[logger.ts]
  Cache --> Logger

所有路径最终汇入 better-sqlite3 单文件数据库，错误统一由 logHookError 落盘。资料来源：src/db/database.ts:30-80 src/utils/logger.ts:30-90

关键要点

• 同步原生驱动：better-sqlite3 适合钩子的阻塞语义
• ABI 兼容必须严格匹配：升级 Node 后必须同步升级原生模块；v1.15.0 已修复此问题
• 永不静默失败：logHookError 保证任何钩子异常都会被记录
• 数据质量优先于数据量：last_work 清洗与嵌入缓存共同保证语义检索质量
• 资料来源：src/utils/logger.ts:1-30 src/tools/memory.ts:60-120 src/tools/relation.ts:60-120

概述与设计目标

本 MCP 服务器围绕"让 Claude 跨会话复用上下文"这一核心目标，建立了一套三层联动机制：记忆分类（Classification） 决定信息的留存粒度，解决方案归档（Solution Archival） 将验证过的修复策略沉淀为可复用资产，错误修复管道（Error Fix Pipeline） 把钩子失败、ABI 不兼容等异常事件反馈到学习闭环，从而在 v1.15.0 引入 logHookError 后保证 5 个核心钩子不再"静默崩溃"。资料来源：src/tools-v2/memory.ts:1-40。

整套管道的入口由 MCP 工具（save_memory、find_solutions、record_feedback、learn_from_session 等）向外暴露，写入层统一委托给 [email protected] 提供的持久化通道，避免 Node 26 ABI 147 与历史模块失配导致的写入中断。资料来源：src/tools/solution.ts:12-58。

记忆分类体系与过滤机制

filter.ts 中定义了分类标签与查询 DSL 的映射规则，将记忆切分为 bugfix、workaround、pattern、preference、context 五大族。客户端可通过 category、keywords、min_confidence 三个参数组合检索，工具层在 SQL 层追加 WHERE AND 子句后返回命中集合。资料来源：src/tools/filter.ts:24-71。

memory.ts 则承担底层 CRUD 抽象，对外暴露 store、update、expire 三个写入语义，并在存储时自动归一化分类字段——例如把"修复 better-sqlite3 ABI 137/141"的会话条目强制归入 bugfix，并打上 abi-version 标签，便于后续 find_solutions 反查。资料来源：src/tools-v2/memory.ts:55-102。

解决方案归档流程

当 learning.ts 中的 learn_from_session 工具判定当前会话产生了可复用答案时，会调用 solution.save 把"问题症状 → 根因 → 修复命令 → 验证步骤"四段式元数据写入 solutions 表。归档前会自动跑一遍去重检测：相同 bug_signature + project_hash 的条目会被合并，并把 success_count 与 last_validated_at 字段做幂等更新。资料来源：src/tools/learning.ts:30-88。

tools-v2/learn.ts 在 v2 协议层引入了"提取—蒸馏—归档"三步法：第一步从 last_work 中剔除被注入的命令体（受 v1.15.0 Cleaner last_work 改动影响），第二步用规则匹配抽取真正用户诉求，第三步才落库为 solution。这避免了把 hook 注入的 prompt 当成"用户问题"错误归档。资料来源：src/tools-v2/learn.ts:41-95。

错误反馈与修复管道

feedback.ts 暴露 record_feedback 与 mark_solution_invalid 两类入口。前者接受 { error_type, stack_trace, session_id, payload }，落库到 errors 表并立即触发一次 find_solutions(error_signature) 检索，若命中已有方案则把 hit_count++ 并把方案链接返回给调用方；后者在用户对某条 solution 投反对票时调用，会把该条目标记为 deprecated 并降低其在 filter.ts 检索中的优先级权重。资料来源：src/tools/feedback.ts:18-66。

logHookError 是 v1.15.0 引入的关键改进：原先 5 个钩子在 Node 26 升级后因 better-sqlite3 原生模块 ABI 失配而静默退出，现在任何钩子失败都会经过 logHookError → record_feedback 串联到管道，确保下一次会话开场就能看到"SessionEnd hook failed: ABI mismatch" 这类显式提示，而不会让用户在一片"宁静"中丢失上下文。资料来源：src/tools/feedback.ts:70-104。

端到端数据流

flowchart LR
  Hook["5 个生命周期钩子"] -->|事件| Log["logHookError"]
  Log -->|失败| FB["record_feedback"]
  Session["会话历史"] --> Learn["learn_from_session"]
  Learn -->|蒸馏| Sol["solution.save"]
  FB -->|反查| Sol
  Sol --> Mem[(SQLite: solutions)]
  FB --> MemErr[(SQLite: errors)]
  Filter["filter / find_solutions"] --> Mem
  Filter --> MemErr
  Filter --> Client["MCP 客户端"]

整个管道形成"采集—分类—归档—反馈"的闭环：钩子采集原始事件，memory.ts/filter.ts 负责分类与过滤，learning.ts 与 tools-v2/learn.ts 共同完成归档，feedback.ts 把任何环节的异常重新喂入检索，从而让下一次会话在开场即可复用上一次踩坑经验。

Pitfall Log / 踩坑日志

项目：leesgit/claude-session-continuity-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/leesgit/claude-session-continuity-mcp | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/leesgit/claude-session-continuity-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/leesgit/claude-session-continuity-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/leesgit/claude-session-continuity-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/leesgit/claude-session-continuity-mcp | release_recency=unknown