项目搬了家，AI 却不记得了

把项目从 ~/Documents/xxx 搬到 ~/Projects/xxx，或者只是改了个名，会遇到一个让人以为数据丢了的现象：

代码还在，git 历史还在，但 ZCode 里的「项目记忆」读不到了，历史会话也从列表里消失了。

第一反应当然是「完了，备份没做全」。实际上不用慌——真正该修的不是数据，是索引。

搬家之后，什么坏了、什么没坏

东西	搬家后	为什么
代码、依赖、git 历史	完好	都在项目目录里
项目记忆	读不到	记忆目录名 = 项目名-sha256(路径)[:16]，路径一变哈希就变
历史会话	文件没丢，但列表里看不到	会话按 ID 存，归属标签写的是旧路径

关键认知：会话内容永远不丢，只是「找不到」。所以修复是安全的，最坏情况可以回滚。

根因：路径就是身份

大多数工具用「项目目录名」当身份，改名影响有限。ZCode 更彻底——它用项目绝对路径算哈希，嵌进记忆目录名里。路径一变，那个 16 位哈希就全变了，ZCode 自然认不出这是同一个项目。

麻烦的是，ZCode 同时还在用两套标识：

1. 记忆目录名里的路径哈希（无损）
2. 会话表里的 project_id（有损 slug）

第二套是个坑：两个毫不相干的项目可能共享同一个 project_id。用它做匹配条件，会静默合并两个项目的会话——不报错，但数据串了。

三步修复法

第 1 步  识别绑定层   这个工具把「项目身份」存在哪？（目录名？数据库？配置文件？）
第 2 步  规划        算出新标识，先改 1 个项目试点，人工验证
第 3 步  批量 + 查盲区  批量执行，然后用清单逐项扫「改名/搬家会破坏的东西」

大部分人只做了第 3 步的一半——改记忆目录名——然后发现还有一堆东西坏了。因为盲区在项目外面：项目内的引用你查得再细，也查不到用户目录下的软链和后台服务配置。

要改的三处

#	改什么	怎么改
1	记忆目录名	重命名 ~/.zcode/cli/memories/projects/ 下的目录，末尾哈希换成新路径的 sha256[:16]
2	会话归属	按旧路径精确匹配后，更新 session 表的 directory 字段
3	会话分组键	同一条更新里，把 project_id 设为目标工作区的锚定值

⚠️ project_id 绝不能当匹配条件。它是有损 slug，会撞名；误用它会静默合并两个项目的会话。永远用 directory 精确匹配。

另外有一处不要动：会话正文文件（rollout/*.jsonl）和 session_entry 表。只改「索引 / 标签」，风险完全可控。

5 条避坑经验

1. 先查盲区再动手。 项目内的引用你查得再细，也查不到 ~/.agents/skills/ 里的软链和服务配置。
2. kill 进程 ≠ 停服务。 带 KeepAlive 的 launchd 服务会被立刻拉回来，必须先 unload 再操作数据库。
3. project_id 会撞名。 永远用 directory 精确匹配。
4. 改前一定先 commit。 未提交的工作目录内容一旦丢了，git 也救不回来。
5. 会话内容永远不用动。 只改索引层，最坏可以回滚。

第 2 条是我自己踩过的——kill 掉进程之后正准备改数据库，服务自己回来了，只能再走一遍 unload。

为什么这份指南不给自动迁移脚本

这是个刻意的决定。

AI 工具的存储布局会随版本变。一个写死路径和表名的脚本，在工具升级后会立刻过时，而且会制造事故——它会对着一个已经变了的数据结构执行 UPDATE，而这恰恰是最不该自动化的操作。

所以给的是机制 + 清单：让人（或 Agent）现场判断当前环境到底把身份存在哪、该怎么改。

给 AI Agent 的用法

这套流程天然适合交给 Agent 执行，因为它的每一步都是「探测 → 判断 → 执行 → 验证」，而不是照抄命令。仓库里的执行手册按四个阶段拆开：

• 阶段 1 · 侦察与规划：在目标环境里定位绑定层，算出新标识
• 阶段 2 · 记忆迁移：文件层，低风险，可回滚
• 阶段 3 · 会话迁移：数据库层，必须先停服务
• 回滚手册：任何阶段不满意都能退回

Agent 需要的不是照抄，而是按「识别绑定层」的方法推导出这台机器上对应的命令。

一点边界说明

这份内容只讲 ZCode，全文来自本机实测：存储结构实证、SQL 实跑、命令实机验证。别的 AI 工具不在这份指南的覆盖范围内——如果在别的工具上踩到同类问题，可以套用第四节的方法，但那些结论没有实测过。

我把这件事完整沉淀成了一个开源仓库，包含绑定机制详解、7 项盲区清单、踩坑实录和一次真实迁移的全过程：

Henry-yuan/Zcode-project-migration（MIT）

如果你也在用 AI 编码工具、遇到过类似的项目搬家失忆问题，可以看看；或者你手上有别的场景想让我一起梳理成方法论，微信找我。