Kael Thread Rebuild MCP

为 Claude Code 长会话重建上下文：按预算携带近期对话，移除工具运行记录，在新 session 中继续。

Kael Thread Rebuild MCP 提供对话筛选、换窗预览、候选验证、会话切换和回滚请求。保留范围由用户配置；不使用模型对对话打分或生成摘要。

这是独立的社区开源项目，非 Anthropic 官方产品。

安装指南 · 配置与预算 · 工作原理与限制 · 首次验收 · 版本说明

适用场景

• 在 Claude Code 中进行长期聊天、角色创作或连续讨论，希望保留近期对话的具体措辞。

• 会话积累了大量工具结果、图片和运行记录，需要为后续交流腾出上下文。

• 使用 tmux、systemd 或自行维护的 claude -p runner，并能够配置 MCP 和启动方式。

本项目操作本机 Claude Code transcript，不适用于 ChatGPT 或 Claude 网页聊天。它不提供长期记忆检索，可以与独立记忆系统配合使用。

Related MCP server: claude-memory-mcp

主要能力

• 可配置携带预算：按估算 token 数保留最近整轮；超预算可移除最老整轮，或停止并交由用户处理。

• 对话提取：处理连续用户消息、未回复的末尾消息，以及已适配的 channel 和排队输入格式。

• 换窗预览：doctor、dirty、plan 分别检查配置、运行记录体积和预计携带结果。

• 两阶段切换：先登记请求，再在当前回复结束后由 worker 处理。

• 备份与验证：保存源文件副本，校验候选内容、事件链及源文件变化，并检查切换目标身份。

按需设置对话预算

例如，携带最近约 60,000 token 的对话：

carry_max_tokens = 60000
carry_overflow = "drop_oldest"
max_event_chars = 0
include_open_tail = true

这是可选配置，代码默认 carry_max_tokens = 0，表示不限携带预算。drop_oldest 从最老整轮开始移除；block 则拒绝超预算的换窗。退出新窗口的旧回合仍保留在源 transcript 和 operation 备份中，不会自动召回。

若携带对话约 60,000 token、启动上下文约 30,000 token，新窗口初始占用约 90,000 token。对可用容量为 1,000,000 token 的会话，约为 9%。这是计算示例，不是固定开销或效果保证。

预算基于文本估算，不是严格的总上下文上限。drop_oldest 至少保留最后一轮，极长单轮仍可能超预算。详见配置说明。

开始使用

需要 Python 3.11+、可运行的 Claude Code，以及受支持的运行方式。首次建议选择独立测试会话。

git clone https://github.com/y2489518-ai/kael-thread-rebuild-mcp.git
cd kael-thread-rebuild-mcp
python3 -m venv .venv
.venv/bin/pip install .

安装 Python 包后，仍需配置 transcript 路径、启动参数和 MCP/worker 接入。请继续阅读安装指南。

使用流程

1. 检查配置并预览：doctor → dirty → plan。

2. 用户确认保留范围后，登记换窗请求。

3. 当前回复结束，worker 备份源 transcript、筛选对话并验证候选。

4. 检查源文件和目标身份后切换；激活失败时尝试恢复旧 session。

5. 检查 operation 状态，并在新窗口验证对话与消息收发。

使用边界

当前版本按规则提取文本，会规范化空白并剥离识别到的注入块，不承诺逐字节无损或完整运行状态迁移。用户正文中的同名标签、混合事件和未适配插件存在保留边界；聊天回复提取尚未按接收对象过滤。

工具结果可能包含代码任务的重要证据，移除后可能需要重新读取。进程存活不等于聊天通道恢复；首次使用及宿主升级后应完成端到端验收。详见工作原理与限制。

开发与贡献

.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest

测试不能替代真实宿主上的恢复验收。请阅读贡献指南，反馈问题时不要附带未脱敏的对话和凭据。

许可证

采用 MIT License。