TaskMem

English · 简体中文

让编码工作跨会话、跨 Agent 持续推进。

TaskMem 为每个项目保存一份精简、经过核验、归项目所有的工作状态，主要解决两个问题：

1. 跨会话继续工作。 打开全新的 Claude Code、Codex、Hermes 等受支持 Agent 会话，直接恢复目标、阶段、活动任务、状态和下一步，不必重新解释项目。
2. 跨 Agent、跨会话协同。 一个 Agent 写下 checkpoint 并显式交出控制权，另一个 Agent 即使在新会话里，也能从同一份核验状态继续。

一句话：换会话，不丢工作；换 Agent，不丢上下文。

• 项目所有： 恢复状态保存在项目中可检查的 .taskmem/ 目录。
• 完成可证： init、validate、.taskmem/READY 和 adapter 回读全部一致后，才算启用成功。
• 跨工具： 每个 adapter 都使用同一套核心协议和固定 controller 身份。

TaskMem 保存的是结构化项目记忆，不是聊天全文或“共享大脑”。跨 Agent 协同采用显式顺序交接：同一时间只有一个 controller 写入，另一个 Agent 必须在 checkpoint 和 controller 转移完成后接手。

TaskMem 到底记住什么

项目文件夹仍然保存完整知识：研究、设计、代码、测试和证据继续放在各自的正常文件中。TaskMem 补上的是它们之间的结构：

• 每张任务卡记录目标、阶段、下一步、依赖关系、关键决策和成果文件引用；
• PROJECT_MAP.json 索引模块、任务、依赖和证据关系，但不复制文件正文；
• STATE.md 指向此刻正在推进的工作；
• 每次 checkpoint 会同步活动任务卡、项目地图、当前状态、校验凭据和历史记录。

例如，一个简单待办应用可以形成 保存待办 → 构建列表 → 验证流程 的明确链路，每个任务再分别引用自己的研究、设计、代码和测试文件。新会话恢复的不只是“现在做到哪”，还包括“这一步依赖什么、相关成果在哪里”。

controller 也不需要把整张地图塞进模型。分发任务前，它让 TaskMem 编译一个有限上下文包：执行型子 Agent 会收到单个任务、上游已经接受的关键决策、必须读取的精确文件范围、相关依赖摘要，以及标明只读或可写权限的文件白名单；规划型 Agent 可以收到更大但仍有上限的地图切片。为了缩小包而删除内容时，已接受决策和必读材料不会被截掉。执行型和规划型子 Agent 都不直接写 TaskMem，而是把结果和证据交回 controller，由 controller 核验并写 checkpoint。

三步开始

1. 安装

Setup 会先展示一份合并后的变更计划。确认后，它才会安装 ~/.taskmem 用户级运行时、安全 PATH 目录中的 launcher，以及检测到的受支持 Agent 配置中的受管策略、Skill 或 Hook 区域。普通 npm 安装本身不会修改配置。

npx taskmem setup

2. 在项目里启用

Claude Code、Codex 桌面端、Hermes 等

只打开目录时，Agent 不会自行发言。Codex 桌面端会在第一次聊天前创建工作区，Claude Code 和其他编码 Agent 通常也从一个已有目录启动；TaskMem 会把这两类情况都视为已有项目，并且绝不会静默初始化。

在 Claude Code、Codex、Hermes 等受支持 Agent 中，用户发出第一条消息后，已安装的集成会检查 .taskmem/READY。如果尚未启用，Agent 会在执行实质工作前这样回复：

你：帮我做一个简单的待办事项应用。
编码 Agent：当前项目尚未启用 TaskMem。
            回复“启用 TaskMem”可准备推荐配置，
            回复“跳过”则继续当前任务且本会话不再提示。
你：启用 TaskMem

如果已经决定使用 TaskMem，第一条消息直接发送 启用 TaskMem，即可省去询问。Agent 会使用当前项目的规范物理路径，从目录名和当前请求推导项目名、目标、阶段和下一步；默认建议 agent_mode=single，controller 使用当前 Agent；只有无法安全推导的字段才会追问。它会一次性展示完整方案，你只需确认一次。

确认后，Agent 才会执行 init → validate → adapter resume。必须同时满足以下三项才算成功：

.taskmem/READY 存在
taskmem validate 成功
当前 adapter 精确回读所有已确认字段

这是 Agent 策略约定，不是隐藏的 CLI 关键词解析器。项目数据里出现这几个字不会自动触发写入。

让 Agent 连目录一起创建

直接说明目标：

创建一个使用 TaskMem 的简单个人待办事项应用。

Agent 会在创建目录前，一次性展示项目名、短横线英文 slug、目标、agent_mode、controller、阶段、下一步、可选会话引用和项目父目录。确认后，新目录只会创建在配置父目录的一个直接子目录中，通常是 ~/projects/<slug>。

3. 中断后恢复

在已经存在 .taskmem/READY 的项目中打开全新会话，然后只说：

继续

在 Claude Code、Codex、Hermes 等受支持 Agent 中，使用对应集成提供的恢复入口。Agent 必须依据 adapter 的核验回读继续，不能从聊天记忆重建状态。不同平台的调用方式见后面的平台支持。

随时检查安装和集成状态：

taskmem doctor --json

卸载只移除可验证的 TaskMem 运行时、launcher 和受管配置区域，保留项目自己的 .taskmem/ 历史：

npx taskmem uninstall

Checkpoint 什么时候写

1. 首次启用时，所有字段必须在写入后被 validate 和 adapter 回读核验。
2. 在任务开始或切换、验收通过、暂停、交接、会话结束前写 checkpoint；controller 会把新接受的决策及其证据引用提升到任务卡，再让活动任务卡、项目地图、STATE、READY 和历史记录一起更新。只有 checkpoint 描述或旧聊天记录，不等于已经建立决策索引。
3. 日常恢复只读取紧凑的项目和活动任务事实，不默认注入完整 STATE、任务正文、历史归档或聊天。
4. 每次写入都携带刚读到的 STATE.updated_at；旧写入会失败，其他 Agent 必须先显式转移 controller。

在 Claude Code 中，“已经读过”不再只靠模型自述：提示和工具 Hook 会注入当前决策与必读清单，只记录真正送进模型且与当前文件一致的 Read 行；所有必读范围完成前，实质工具和结束回答都会被阻止。

STATE.md 只保留最近五条 checkpoint 摘要；完整 v3 历史位于 .taskmem/archive/checkpoints/ 中受约束、按内容寻址的记录。

如何跨 Agent、跨会话交接

受支持的 Agent 可以在同一套项目 checkpoint 历史上顺序推进，即使每次接手都发生在全新会话。事实在 checkpoint 后可用；同一时间只有一个 controller 拥有写权限。

这不是实时协作。完整聊天仍留在各平台会话库中，TaskMem 只保存可接手的有限事实。

在一次多 Agent 任务内部，controller 不会把整个项目记忆交给子 Agent，而是先编译任务包：

taskmem compile-context --root . --task T-build-list --audience worker --agent codex --json

包里只有当前任务、相关图谱节点和已登记的项目文件引用。子 Agent 返回代码、测试与证据，只有 controller 负责核验并更新 TaskMem。

Git、跨机器与隐私

TaskMem 不会替你修改 .gitignore、commit、push、切分支、合并或同步 .taskmem/。

• 同一台机器：本地 .taskmem/ 即可恢复。
• 跨机器或团队：先检查完整 .taskmem/ diff 中的项目细节和会话引用，确认仓库隐私策略允许后，再通过可信渠道有意同步。
• 多分支：TaskMem 不自动合并分叉的 STATE.md 历史。先决定保留哪一个状态，validate 后由单一 controller 写一个新 checkpoint。
• 归档：历史不会进入日常上下文，但目前不会自动清理。

完整说明见 Git、分支、跨机器、保留与敏感信息策略。安全与限制的权威版本仍是英文 SECURITY.md 和 KNOWN_LIMITATIONS.md。

平台支持

TaskMem 0.3.0 运行于 Node.js 20+ 的 macOS 和 Linux，并拒绝 Windows。完整集成清单如下：

• Claude Code： 受管策略、SessionStart 恢复、由 UserPromptSubmit / PreToolUse / PostToolBatch 组成的必读上下文门禁，以及 Stop checkpoint Hook。

• Codex： 受管策略，以及经过结构核验的 SessionStart 和 Stop Hook；Hook 信任仍由平台管理。

• Hermes： 受管策略和 pre_llm_call 恢复；原生 Hook 授权仍由平台管理。

• Qoder： 受管 SessionStart 恢复、Stop checkpoint 检查，以及固定的 qoder controller/adapter 身份。

• QoderWork： 受管 TaskMem Skill、官方文档范围内的 Stop Hook，以及固定的 qoder_work 身份；稳定入口是显式发送“使用 TaskMem skill”，不声称官方未承诺的 SessionStart 输出注入。

• WorkBuddy： 固定的 workbuddy adapter 身份和用户主动创建/导入的自定义 Skill 模板；不会静默修改 WorkBuddy 设置，也不声称已有自动 Hook 协议。

Qoder、QoderWork 和 WorkBuddy 已包含在 0.3.0 包中并通过契约测试，但真实客户端验收仍待完成。TRAE 仍是调研候选。

详见带官方依据的 平台兼容矩阵。

已有 TaskMem 项目是否要统一升级

不要批量重写本地所有项目。已有 v3 项目仍可读取，下一次由合法 controller 写 checkpoint 或交接时，会惰性生成项目地图。新的语义保障从 controller 把当前任务真实的依赖、已接受决策、成果引用和必读材料登记进任务卡时开始。TaskMem 不会从旧聊天或 checkpoint 描述中猜这些关系；重要项目在下次恢复时做一次当前任务整理，暂时不用的项目等重新打开时再处理。旧 v2 项目继续按原 schema 兼容运行，不会被静默迁移。

证据与限制

0.3.0 的不可变证据包括 恢复演示、顺序交接演示、核心实现 和 打包产物测试。

• 普通运行与贡献者源码测试支持 Node.js 20+；可复现发布构建仍固定为 Node 24.15.0 和 npm 11.12.1。
• TaskMem 0.3.0 是早期版本，有仓库测试和打包产物测试，但尚无独立验证。
• 项目状态是不可信数据，不是可执行指令；用于关键工作前请阅读权威英文 安全边界 与 已知限制。

Apache-2.0 许可。

如果 TaskMem 让你少解释了一次，点一个 Star 能帮助更多编码 Agent 用户发现它。