diff --git a/CHANGELOG.md b/CHANGELOG.md
index 91decac..6c189c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,23 @@
 # Changelog
 
+## 13.0.1 (2026-05-05)
+
+### 修复
+
+- **Hook 环境变量**：所有 hook 命令显式导出 `CLAUDE_MEM_DATA_DIR` 和 `CODEBUDDY_MEM_DATA_DIR`，防止 `bun-runner.js` 回写 `~/.claude-mem/`
+- **数据库文件命名**：主数据库改名为 `codebuddy-mem.db`，保留 `claude-mem.db` 符号链接向后兼容 worker 二进制
+
+### 新增
+
+- **回归测试脚本** `scripts/regression-test.sh`：11 层 47 项全功能回归测试
+- **数据迁移**：支持将旧 `~/.claude-mem/claude-mem.db` 完整迁移到 `~/.codebuddy-mem/`（含 SQLite + Chroma 向量索引）
+
+### 已知问题
+
+- tree-sitter-cli 二进制需通过 Homebrew 安装（npm 下载可能失败）
+- 数据迁移后 `chroma-sync-state.json` 需手动重置水位线，否则语义搜索返回空
+- `pending_messages` 表 schema 与旧 claude-mem 有微小差异（无 `worker_pid` 列和 `failed` 状态）
+
 ## 13.0.0 (2026-05-05)
 
 ### 分叉起点
diff --git a/README.md b/README.md
index 72c6f37..0cee357 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,73 @@
 - **语料库**：构建知识语料库，通过 AI 问答检索
 - **代码结构**：smart_outline / smart_unfold 快速浏览代码
 
+## 数据目录
+
+默认 `~/.codebuddy-mem/`，由 `CODEBUDDY_MEM_DATA_DIR` 环境变量控制。
+
+```
+~/.codebuddy-mem/
+├── codebuddy-mem.db          ← 主数据库 (SQLite)
+├── claude-mem.db → codebuddy-mem.db  ← 符号链接，兼容 worker 硬编码
+├── chroma/                   ← HNSW 向量索引
+├── chroma-sync-state.json    ← 各项目同步水位线
+├── settings.json             ← 运行时配置
+├── supervisor.json           ← 进程管理状态
+└── logs/                     ← 运行日志
+```
+
+> **命名说明**：worker 二进制中硬编码了 `claude-mem.db` 文件名。真实文件已改为 `codebuddy-mem.db`，`claude-mem.db` 是符号链接。上游修复后删除链接即可。
+
+## 从 claude-mem 迁移
+
+```bash
+# 1. 停掉旧版
+pkill -f "thedotmack/claude-mem"
+pkill -f "claude-mem/chroma"
+
+# 2. 复制数据
+cp ~/.claude-mem/claude-mem.db ~/.codebuddy-mem/codebuddy-mem.db
+cp -r ~/.claude-mem/chroma/ ~/.codebuddy-mem/chroma/
+
+# 3. 重置 chroma 同步水位线（否则搜索不返回结果）
+# 将 chroma-sync-state.json 中各项目的 observations/summaries/prompts 置为 0
+
+# 4. 创建符号链接
+cd ~/.codebuddy-mem && ln -s codebuddy-mem.db claude-mem.db
+
+# 5. 清理旧残留
+mv ~/.claude-mem ~/.Trash/
+rm ~/.codebuddy/hooks/claude-mem-*.sh
+```
+
+## Hook 配置
+
+Hook 负责在 CodeBuddy Code 生命周期事件中向 worker 发送数据。必须设置以下环境变量，否则 `bun-runner.js` 会回写到 `~/.claude-mem/`：
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "startup|clear|compact",
+      "hooks": [{
+        "type": "command",
+        "command": "export CLAUDE_MEM_DATA_DIR=\"$HOME/.codebuddy-mem\"; export CODEBUDDY_MEM_DATA_DIR=\"$HOME/.codebuddy-mem\"; ..."
+      }]
+    }]
+  }
+}
+```
+
+完整配置见 `hooks/hooks.json`。
+
+## 回归测试
+
+```bash
+bash scripts/regression-test.sh
+```
+
+11 层 47 项覆盖：进程 / 文件 / 数据库 / 数据统计 / 完整性 / Chroma / 配置 / 日志 / HTTP / Hook / MCP API。
+
 ## 安装
 
 ### 方式一：独立 MCP 服务