task-memory-server

LLM 上下文丢失后的任务状态恢复工具。通过 MCP + Hooks + 对话日志解析，实现任务进度的自动持久化，上下文压缩或新开会话后一键恢复。

问题

使用 Claude Code 等大模型工具时：

• 上下文窗口有限，复杂任务经常触发压缩
• 压缩后细节丢失，决策依据被抹掉
• 新开会话需要人工重新喂上下文
• 不知道任务做到哪一步了
• 多窗口并行时，无法查看其他窗口的进展
• 已完成的子任务产出，新窗口看不到

解决方案

四层持久化架构：

┌──────────────────────────────────────────────────┐
│  MCP Tools (主动记录)                              │  task_start / task_advance / task_decide
├──────────────────────────────────────────────────┤
│  Hooks (被动捕获)                                  │  afterToolUse → 实时更新 state.json
│                                                   │  beforeContextCompress → 自动保存检查点
├──────────────────────────────────────────────────┤
│  对话日志解析 (LLM 输出捕获)                       │  读取 Claude Code 本地日志，提取 LLM 文本输出
├──────────────────────────────────────────────────┤
│  本地文件 (持久化存储)                              │  state.json / log.jsonl / decisions.md
└──────────────────────────────────────────────────┘

• MCP Tools：LLM 主动调用的结构化接口，记录任务计划、步骤推进、关键决策
• Hooks：每次工具调用后自动更新状态快照 + 追加日志，上下文压缩前自动保存检查点，零摩擦
• 对话日志解析：读取 Claude Code 本地存储的完整对话记录，提取 LLM 的文本输出和思考过程（无需额外配置）
• 恢复引擎：合并状态 + 日志 + 决策 + 对话上下文，生成 O(1) 大小的恢复摘要

安装

npm 全局安装（推荐）

npm install -g task-memory-server

安装后自动配置 MCP Server + Hooks + 行为规则，重启 Claude Code 即可使用。

从源码安装

git clone <repo-url>
cd task-memory-server
npm install
npm run build
npm link
task-memory init --global

配置

# 全局配置（推荐，所有项目生效）
task-memory init --global

# 或仅当前项目
task-memory init

自动配置：

1. MCP Server — 注册 taskmem 到 ~/.claude.json，15 个 tools 可用
2. Hook: afterToolUse — 每次 Edit/Write/Bash/Grep/Glob/Read 后自动追踪，实时更新 state.json
3. Hook: beforeContextCompress — 上下文压缩前自动保存检查点
4. 行为规则 — 写入 ~/.claude/CLAUDE.md，引导 Claude 自动使用 tools

配置完成后 重启 Claude Code 即可激活。

使用

1. 开始任务

用自然语言告诉 Claude：

开始一个任务: 重构认证中间件
计划:
1. 分析现有代码
2. 设计新接口
3. 实现 Redis 存储
4. 接入中间件
5. 编写测试

Claude 会调用 task_start，创建 .task-memory/tasks/{task-id}/state.json。

2. 推进进度

每完成一步，Claude 自动调用 task_advance。你也可以手动提醒：

记录进度：分析完成，下一步是设计接口

3. 记录决策

做出关键选择时：

记录决策：选择 Redis 而不是内存缓存，因为合规要求跨实例失效
考虑过的备选：Memcached, 内存 LRU

4. 恢复上下文（核心功能）

上下文丢失后，在新会话中说：

恢复任务

Claude 调用 task_recover，拿到完整的恢复摘要（包含 LLM 对话上下文）：

## Task Recovery: 重构认证中间件

Status: in_progress | Phase: 4/6

### Completed Steps
- ✅ 分析现有代码
- ✅ 设计新接口
- ✅ 实现 Redis 存储

### Next Step
→ 接入中间件

### Key Decisions
- 选择 Redis（合规要求跨实例失效）

### Files Modified
- src/auth/types.ts

### Files Created
- src/auth/token-store.ts

### LLM Conversation Context
(Extracted from Claude Code's local conversation logs)
**LLM Text Output (recent):**
- 建议使用 Redis Cluster 而非单节点，确保高可用...
- TokenStore 接口设计：get/set/refresh/delete 四个方法...

---
Recovery Prompt:
继续任务：重构认证中间件。最近动作（实时）：09:15 执行: npm test; 09:12 编辑 token-store.ts...
最后操作：执行: npm test（2026-06-19T09:15:00）...

不用重新解释任务，不用翻历史，直接继续。

5. 跨窗口查看

多个窗口并行工作时，在新窗口中查看其他任务进展：

查看所有任务

## All Tasks (2)

[>] 重构认证中间件 <-- active
    ID: task-xxx | in_progress | 4/6 steps | Updated: 2026-06-19T09:15:00
    Last: 09:15 执行: npm test

[x] 数据库迁移
    ID: task-yyy | completed | 3/3 steps | Updated: 2026-06-19T08:00:00
    Deliverables: + migration.sql, ~ schema.ts
    Summary: 完成用户表迁移到新结构

查看某个任务详情：

查看任务 task-yyy 的详情

## Completed Task: 数据库迁移

Status: completed | Progress: 3/3 | ID: task-yyy
Description: 完成用户表迁移到新结构
Completed at: 2026-06-19T08:00:00

Steps:
  [x] 1. 分析现有 schema
  [x] 2. 编写迁移脚本
  [x] 3. 验证数据完整性

Files created:
  + db/migrations/001_user_table.sql
Files modified:
  ~ src/models/user.ts

6. CLI 直接使用

task-memory status    # 查看当前任务进度
task-memory recover   # 打印恢复摘要
task-memory serve     # 运行 MCP server（调试）
task-memory proxy     # 运行 API 代理（捕获完整对话）

可用的 MCP Tools

| Tool | 说明 | |------|------| | task_start | 开始新任务，传入名称和计划 | | task_advance | 完成当前步骤，推进到下一步 | | task_decide | 记录关键决策及理由 | | task_checkpoint | 保存命名检查点 | | task_recover | 恢复上下文，生成恢复摘要（含 LLM 对话上下文） | | task_status | 查看当前任务状态和进度 | | task_list | 列出所有任务（含最新操作、已完成任务的产出） | | task_peek | 查看其他任务的详情，不切换当前任务 | | task_switch | 切换到另一个任务 | | task_file_track | 追踪文件变更 | | task_blocker | 添加/移除阻塞项 | | task_complete | 标记任务完成 | | task_session_read | 按 session ID 读取 Claude Code 会话记录（JoySwitch DB 快速查询，无 JoySwitch 时自动扫描本地日志） | | task_sessions_list | 列出最近的会话（有 JoySwitch 时显示 token 统计） | | task_session_auto | 自动发现当前项目的会话记录，无需 session ID，新窗口查看之前工作内容 |

本地文件结构

.task-memory/
├── active.json                           # 当前会话的任务绑定（多窗口隔离）
└── tasks/
    ├── task-1718800000000/
    │   ├── state.json                    # 任务状态快照（实时更新）
    │   ├── log.jsonl                     # 事件流（append-only，最多 10000 条）
    │   ├── decisions.md                  # 关键决策记录
    │   └── checkpoints/
    │       ├── auth-impl-done.json
    │       └── pre-compress-4-steps.json
    └── task-1718800100000/
        ├── state.json
        ├── log.jsonl
        └── ...

建议将 .task-memory/ 加入 .gitignore（任务状态是本地开发状态，不需要提交）。

多窗口隔离

每个 Claude Code 窗口通过 TASK_MEMORY_SESSION 环境变量绑定不同的 active task，互不干扰：

• 窗口 A 执行 task_start "重构认证" → 绑定 task-xxx
• 窗口 B 执行 task_start "性能优化" → 绑定 task-yyy
• 窗口 A 的 task_advance 只影响 task-xxx
• 两个窗口可以通过 task_list / task_peek 互相查看进度

API 代理（可选）

如果你需要捕获完整的 API 请求/响应（包括 LLM 的每一轮输出），可以启动 API 代理：

task-memory proxy

这会在 127.0.0.1:15730 启动一个代理，转发到 JoySwitch 或直接转发到 Anthropic API。配置：

# 设置环境变量指向代理
export ANTHROPIC_BASE_URL=http://127.0.0.1:15730/v1

# 或自定义上游和端口
TASK_PROXY_PORT=15730 TASK_PROXY_UPSTREAM=http://127.0.0.1:15721 task-memory proxy

代理会将完整的对话内容写入 .task-memory/conversations/{task-id}.jsonl。

注意：如果 JoySwitch 已内置日志中间件，则无需此代理。此代理是给无法修改上游代理的用户使用的备选方案。

会话记录查询

通过 task_session_read 和 task_sessions_list，可以直接按 session ID 读取 Claude Code 的完整对话记录。

使用场景

• claude --resume <session-id> 恢复会话时，想查看之前的对话内容
• 跨窗口查看其他会话的对话记录
• 分析某个会话的 token 使用量

双模式查询

1. JoySwitch 模式（有 JoySwitch 的用户）：通过 ~/.joyswitch/joyswitch.db 的 session_log_sync 表快速定位 session 文件，还能查看 token 统计
2. 回退模式（无 JoySwitch 的用户）：扫描 ~/.claude/projects/ 目录查找对应的 session 文件

注意：JoySwitch 本身并不存储对话内容，它只是提供了 session_id → 文件路径的索引和 token 统计。真正的对话数据始终存储在 Claude Code 自己的 ~/.claude/projects/{project-hash}/{session-uuid}.jsonl 文件中，这些文件由 Claude Code 实时写入。因此 task-memory 可以完全独立于 JoySwitch 读取全量会话内容。

自动发现（无需 session ID）

task_session_auto 会自动匹配当前工作目录对应的 Claude Code 项目，并列出所有历史会话。新开窗口时直接说：

查看之前的会话内容

## Sessions for Current Project (3 found)

### 6685ab87-e505-45e8-95ee-94df554ff3fe
  Last modified: 2026-06-19T04:06:58 | 2203 lines | 6725.3 KB

### b3c81333-b5a1-4655-8125-5ca9da4a109e
  Last modified: 2026-06-19T02:42:14 | 54 lines | 80.3 KB

---

### Latest Session Content (6685ab87...)
Source: joyswitch | Models: GLM-5.1
Messages: 717 user, 1056 assistant, 641 tool calls
Time: 2026-06-19T02:00:00 → 2026-06-19T04:06:58

**Recent Assistant Output:**
- 建议使用 Redis Cluster 而非单节点...
- TokenStore 接口设计：get/set/refresh/delete...

task_recover 自动增强

task_recover 现在会自动包含上一个会话的上下文（不仅仅是当前会话），这意味着：

• 新窗口恢复任务时，能看到上一次会话的 LLM 输出和思考
• 即使 task-memory 的状态记录不完整，会话日志也能补全缺失信息

示例

查看会话 8c759199-efc0-4392-8602-830d524bdc7c 的内容

## Session: 8c759199-efc0-4392-8602-830d524bdc7c

Source: joyswitch | File: ~/.claude/projects/.../8c759199....jsonl
Messages: 165 user, 250 assistant, 163 tool calls
Time: 2026-06-19T02:51:47 → 2026-06-19T03:56:48
Models: GLM-5.1

### Recent Assistant Output
- 建议使用 Redis Cluster 而非单节点...
- TokenStore 接口设计：get/set/refresh/delete...

### Recent Tool Calls
- Edit: {"file_path":"src/auth/token-store.ts",...}

列出最近会话：

列出最近的会话

## Recent Sessions (from JoySwitch DB)

### 6685ab87-e505-45e8-95ee-94df554ff3fe
  Requests: 422 | Models: GLM-5.1, joyswitch
  Time: 2026-06-19T02:00:00 → 2026-06-19T06:00:00
  Tokens: 7,715,511 in / 157,679 out

工作原理

正常工作流:
  用户指令 → Claude 调用 MCP tools → 状态写入本地文件
  工具调用 → Hook 自动更新 state.json（实时快照）
           → Hook 自动追加 log.jsonl（详细记录）

上下文压缩/新会话:
  压缩前 → Hook 自动保存检查点
  新会话 → 调用 task_recover
         → 读取 state.json（在哪里 + 最后在做什么）
         → 读取 log.jsonl（详细操作历史）
         → 读取 decisions.md（为什么这样做）
         → 解析 Claude Code 本地对话日志（LLM 说了什么）
         → 生成 recovery_prompt（O(1) 恢复摘要）
         → 继续工作

恢复所需信息量是 O(1)（固定大小的状态摘要），而不是 O(n)（完整对话历史）。

License

MIT