ultra-memory 3.0.4 → 3.0.5

package/SKILL.md

@@ -2,10 +2,10 @@
 name: ultra-memory
 description: >
   ultra-memory 是多模型 AI 的超长会话记忆系统。
-  【必须触发-中文】用户说以下任意词或短语：记住、别忘了、记录一下、不要忘记、上次我们做了什么、帮我回忆、继续上次的、从上次继续、记忆、帮我记、追踪进度
-  【必须触发-英文】用户说以下任意词或短语：remember、don't forget、recall、what did we do、pick up where we left off、continue from last time、memory、keep track、track progress、log this
-  【隐式触发】用户消息描述了一个持续性任务且消息中包含项目名词（"开发X"、"处理Y数据集"、"完成Z功能"），即使没有明确说"记住"，也必须初始化记忆
-  【不触发】用户只问了一个问题且无后续任务；对话是单次咨询性质；用户说"随便聊聊"或类似表达；用户明确说"不用记录"
+  【必须触发-中文】用户说以下任意词：记住、别忘了、记录一下、不要忘记、上次我们做了什么、帮我回忆、继续上次的、从上次继续、记忆、帮我记、追踪进度
+  【必须触发-英文】用户说以下任意词：remember、don't forget、recall、what did we do、pick up where we left off、continue from last time、memory、keep track、track progress、log this
+  【隐式触发-A+B】同时满足以下两条时触发：(A)消息含持续性任务动词：开发、实现、处理、完成、构建、develop、implement、create、fix；(B)消息中包含项目名词（专有名词/文件名/系统名）
+  【不触发】用户只问一个问题无后续；单次咨询无操作步骤；说"随便聊聊"、"just chatting"；明确说"不用记录"
 ---
 
 # Ultra Memory — 多模型记忆操作手册
@@ -14,10 +14,10 @@ AI Agent 的操作记忆系统，每次操作后记录，跨会话持久化，
 
 ## 前置说明
 
-脚本已存在于 `$SKILL_DIR/scripts/` 目录，直接调用，不需要理解内部架构。
+脚本已全部存在于 `$SKILL_DIR/scripts/`，直接调用，不需要生成，不需要理解内部架构。
 
-存储根目录：`$ULTRA_MEMORY_HOME`（默认 `~/.ultra-memory/`）
-会话 ID 由 init.py 自动生成，模型不需要自己生成。
+- `ULTRA_MEMORY_HOME` 默认值为 `~/.ultra-memory/`
+- `SKILL_DIR` 由 clawbot 注入，如未定义则用 `~/.openclaw/workspace/skills/ultra-memory/`
 
 ---
 
@@ -25,32 +25,28 @@ AI Agent 的操作记忆系统，每次操作后记录，跨会话持久化，
 
 ### 触发条件
 
-以下任意情况出现时，立即执行初始化命令：
-1. 首次与用户对话
-2. 用户说了记忆触发词（见 description）
-3. 用户描述持续性任务且包含项目名词（隐式触发）
+满足 frontmatter 中任意触发规则时，第一件事执行此步骤。
 
 ### 执行命令
 
 ```bash
-python3 $SKILL_DIR/scripts/init.py --project <项目名>
+python3 $SKILL_DIR/scripts/init.py --project <项目名> --resume
 ```
 
 **参数说明：**
-- `--project`：项目名称（用于跨会话分组）。从用户消息中提取项目名词作为值；无法提取则用 `default`。
+- `--project`：项目名称。从用户最近一条消息中提取最显著的名词作为值；无法提取则用 `default`。
+- `--resume`：必须加此参数，让脚本尝试恢复同项目的最近会话。
 
 ### 成功标志
 
-输出中必须同时包含以下两个信号：
-
 | 输出中的字符串 | 模型必须执行的动作 |
 |-------------|----------------|
 | `MEMORY_READY` | 确认初始化成功 |
-| `session_id: sess_xxxxx` | 从该行提取等号后面的值，保存为当前 `SESSION_ID` 变量 |
+| `session_id: sess_xxxxx` | 从该行冒号后提取值，保存为 `SESSION_ID` |
 
-### 告知用户
+### 有上次会话摘要时
 
-> "记忆系统已就绪（session_id: sess_xxxxx），开始记录本次操作。"
+将摘要内容告知用户，并询问："要从这里继续吗？"
 
 ---
 
@@ -58,26 +54,55 @@ python3 $SKILL_DIR/scripts/init.py --project <项目名>
 
 ### 触发条件
 
-**每次**用户与 AI 之间发生以下任意事件时，立即执行记录命令：
+**每次**用户与 AI 之间发生以下任意事件后，立即调用：
 
-| 事件 | op_type | 命令 |
-|------|---------|------|
-| 执行了 shell 命令 | `bash_exec` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type bash_exec --summary "<一句话描述>" --detail '{"cmd":"<命令>","exit_code":<数字>}'` |
-| 创建或修改了文件 | `file_write` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type file_write --summary "<一句话描述>" --detail '{"path":"<文件路径>"}'` |
-| 读取了文件 | `file_read` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type file_read --summary "<一句话描述>" --detail '{"path":"<文件路径>"}'` |
-| 进行了重要推理 | `reasoning` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type reasoning --summary "<推理结论>" --detail '{"confidence":<0-1>}'` |
-| 做出了关键决策 | `decision` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type decision --summary "<决策内容>" --detail '{"rationale":"<决策依据>"}'` |
-| 发生了错误或回退 | `error` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type error --summary "<错误描述>" --detail '{"traceback":"<错误信息>"}'` |
-| 用户给了新指令 | `user_instruction` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type user_instruction --summary "<用户说的话>"` |
-| 某个目标已完成 | `milestone` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type milestone --summary "<完成的内容>"` |
+| 刚发生了什么 | op_type |
+|-------------|---------|
+| 调用了任何工具 | `tool_call` |
+| 创建或修改了文件 | `file_write` |
+| 读取了文件 | `file_read` |
+| 执行了 shell 命令 | `bash_exec` |
+| 做出了重要判断或选择方案 | `reasoning` |
+| 用户给出了新指令或改变了目标 | `user_instruction` |
+| 做出了技术或方案决策 | `decision` |
+| 发生了错误或需要回退 | `error` |
+| 完成了一个明确的阶段目标 | `milestone` |
 
-### 成功标志
+### 执行命令
 
-命令返回 exit code 0 即为成功。
+```bash
+python3 $SKILL_DIR/scripts/log_op.py \
+  --session $SESSION_ID \
+  --type <op_type> \
+  --summary "<用一句话描述刚才做了什么，50字内>" \
+  --detail '{"key": "value"}' \
+  --tags "tag1,tag2"
+```
 
-### 自动标签
+`--detail` 和 `--tags` 可省略，`--summary` 和 `--type` 必填。
 
-`log_op.py` 会根据操作类型和内容自动追加标签（`setup`、`dependency`、`code`、`test` 等），无需手动指定 `--tags`。
+### 示例
+
+```bash
+# 执行 bash 命令后
+python3 $SKILL_DIR/scripts/log_op.py \
+  --session $SESSION_ID \
+  --type bash_exec \
+  --summary "执行 pip install pandas，成功，版本 2.2.0" \
+  --detail '{"cmd": "pip install pandas", "exit_code": 0}'
+
+# 完成阶段目标后
+python3 $SKILL_DIR/scripts/log_op.py \
+  --session $SESSION_ID \
+  --type milestone \
+  --summary "数据清洗模块完成，通过全部单元测试"
+```
+
+### 成功标志
+
+命令返回 exit code 0。
+
+看到 `COMPRESS_SUGGESTED`：立即执行步骤四。
 
 ---
 
@@ -85,31 +110,21 @@ python3 $SKILL_DIR/scripts/init.py --project <项目名>
 
 ### 触发条件
 
-用户问及以下任意问题时执行：
-- "之前做了什么"
-- "上次那个函数在哪里"
-- "之前遇到过这个问题吗"
-- "我们用过哪些文件"
-- "上次选了什么方案"
-- 其他需要查找历史记忆的问题
+用户问及以下任意问题时立即执行：
+之前、上次、那个函数、那个文件、那个命令、我们做过、怎么写的、什么名字、previously、last time、what was、how did we、that function、that file
 
 ### 执行命令
 
 ```bash
-python3 $SKILL_DIR/scripts/recall.py --session $SESSION_ID --query "<用户问题的关键词>" --top-k 5
+python3 $SKILL_DIR/scripts/recall.py \
+  --session $SESSION_ID \
+  --query "<从用户问题中提取的关键词>" \
+  --top-k 5
 ```
 
 ### 结果展示
 
-将脚本输出直接展示给用户。输出格式如下：
-
-```
-[RECALL] 找到 N 条相关记录：
-1. [ops #23 · 14:18] <操作摘要>
-2. [summary · 里程碑] <里程碑内容>
-3. [知识库 · 标题] <内容摘要>
-4. [跨会话 · 日期 · 项目] <历史摘要>
-```
+将脚本输出原样展示给用户，不加工。
 
 ---
 
@@ -117,15 +132,19 @@ python3 $SKILL_DIR/scripts/recall.py --session $SESSION_ID --query "<用户问
 
 ### 触发条件
 
-满足以下**任意条件**时，立即执行压缩命令：
+满足以下**任意条件**时，立即执行：
 
-1. 操作日志达到 **50 条**
-2. 距上次压缩超过 **30 分钟**
-3. 用户明确说"总结一下"或"做个总结"
-4. 脚本输出中包含 `COMPRESS_SUGGESTED` 信号
+1. 步骤二中脚本输出了 `COMPRESS_SUGGESTED`
+2. 用户说：总结一下、目前进展、Summary、summarize
+3. 当前对话已超过 **30 轮**
 
 ### 执行命令
 
+```bash
+python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID
+```
+
+条数不足时强制执行：
 ```bash
 python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID --force
 ```
@@ -140,12 +159,8 @@ python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID --force
 
 ### 触发条件
 
-用户说以下任意表达时执行：
-- "继续上次"
-- "从上次继续"
-- "记得昨天那个项目吗"
-- "还记得吗"
-- "继续上次的工作"
+用户说以下任意表达时触发：
+继续昨天的、接着上次、从上次开始、继续之前的、continue from last、pick up where、resume、continue yesterday
 
 ### 执行命令
 
@@ -153,23 +168,17 @@ python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID --force
 python3 $SKILL_DIR/scripts/restore.py --project <项目名>
 ```
 
-### 成功标志
-
-输出中包含 `SESSION_ID=sess_xxxxx` 信号。
-
 ### 从输出提取信息
 
 | 输出中的字符串 | 模型必须执行的动作 |
 |-------------|----------------|
-| `SESSION_ID=sess_xxxxx` | 从等号后面提取值，保存为新的 `SESSION_ID` |
+| `SESSION_ID=sess_xxxxx` | 从等号后提取值，更新为新的 `SESSION_ID` |
 | `TASK_STATUS=complete` | 告知用户"上次任务已完成" |
 | `TASK_STATUS=in_progress` | 告知用户"上次任务进行中" |
-| `💬 <自然语言总结>` | 直接将总结说给用户 |
-| `📌 <继续建议>` | 直接将建议说给用户 |
+| `💬 <自然语言总结>` | 直接说给用户 |
+| `📌 <继续建议>` | 直接说给用户 |
 
-### 告知用户
-
-> "我找到了上次会话的记录。{自然语言总结}。{继续建议}。"
+将恢复内容告知用户，询问："要从这里继续吗？"
 
 ---
 
@@ -177,25 +186,25 @@ python3 $SKILL_DIR/scripts/restore.py --project <项目名>
 
 记忆进化在操作间隙进行，不打断主任务。
 
-### 6.1 用户画像积累
+### 6A：用户画像积累
 
-**触发条件（满足任意一条，立即更新画像）：**
+**触发条件（满足任意一条，立即更新）：**
 
 1. 用户纠正了 AI 生成的代码风格
-2. 用户在两个技术方案中选择了其中一个
-3. 用户说出自己的技术栈（如"我用 Vue"、"我们用 Python"）
-4. 用户表示某种工作流程更顺手
+2. 用户在两个方案中选择了其中一个
+3. 用户说出自己的技术栈（含"我用"、"我们用"、"我们的项目用"、"we use"、"our stack"）
+4. 用户表示某种工作方式更顺手
 5. 用户明确描述了自己的偏好
 
-**执行命令 — 方式 A（MCP 工具，推荐）：**
+**执行方式 — 方式 A（MCP 工具，推荐）：**
 
-调用 `memory_profile` 工具，`action=update`，`updates` 中填写观察到的偏好字段。
+调用 `memory_profile`，`action=update`，`updates` 填写观察到的偏好字段。
 
-**执行命令 — 方式 B（直接修改文件）：**
+**执行方式 — 方式 B（直接修改文件）：**
 
 ```bash
 # 文件路径：$ULTRA_MEMORY_HOME/semantic/user_profile.json
-# 只更新观察到的字段，不覆盖已有字段
+# 只更新观察到的字段，不覆盖已有字段，使用 JSON merge 方式
 ```
 
 **user_profile.json 可更新字段：**
@@ -203,41 +212,47 @@ python3 $SKILL_DIR/scripts/restore.py --project <项目名>
 ```json
 {
   "tech_stack": ["观察到的技术栈"],
+  "language": "zh-CN 或 en",
   "work_style": {
     "confirm_before_implement": true,
     "prefers_concise_code": true
   },
-  "language": "zh-CN 或 en",
-  "observed_patterns": ["观察到的工作习惯描述"]
+  "observed_patterns": ["倾向先确认方案再实现"]
 }
 ```
 
-### 6.2 知识沉淀
+### 6B：知识沉淀
 
 **触发条件（满足任意一条，立即写入知识库）：**
 
 1. 解决了一个报错或 bug（记录问题现象 + 解决方案）
-2. 做出了技术选型决策（记录选了什么 + 为什么）
+2. 做出了技术选型决策（选了什么 + 为什么）
 3. 发现了某个工具或库的使用技巧
-4. 完成了一个可复用的代码模式或函数
+4. 完成了一个可复用的代码模式
+
+**文件路径：**
 
-**执行命令 — 方式 A（MCP 工具，推荐）：**
+```
+$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl
+```
 
-调用 `memory_knowledge_add` 工具，`title` 必填（20字内），`content` 必填（200字内），`project` 和 `tags` 可选。
+**执行方式 — 方式 A（MCP 工具，推荐）：**
 
-**执行命令 — 方式 B（直接追加）：**
+调用 `memory_knowledge_add`，`title` 必填（20字内），`content` 必填（200字内），`project` 和 `tags` 可选。
 
-追加写入 `$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl`，每行一条 JSON。
+**执行方式 — 方式 B（直接追加）：**
+
+追加写入 `knowledge_base.jsonl`，每行一条 JSON，不覆盖。
 
 **knowledge_base.jsonl 格式：**
 
 ```json
-{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "简短标题（20字内）", "content": "内容描述（200字内）", "tags": ["tag1", "tag2"]}
+{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "20字内标题", "content": "200字内描述", "tags": ["tag1"]}
 ```
 
-### 6.3 里程碑记录
+### 6C：里程碑记录
 
-**触发条件 — 用户说出以下任意表达，立即记录 milestone：**
+**触发条件 — 用户说出以下任意表达，立即记录：**
 
 中文：好了、完成了、搞定了、做完了、弄好了、可以了、没问题了、测试通过、上线了
 
@@ -246,23 +261,23 @@ python3 $SKILL_DIR/scripts/restore.py --project <项目名>
 **执行命令：**
 
 ```bash
-python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type milestone --summary "<用户刚完成的事情的一句话描述>"
+python3 $SKILL_DIR/scripts/log_op.py \
+  --session $SESSION_ID \
+  --type milestone \
+  --summary "<用户刚完成的事情，一句话描述>"
 ```
 
 ---
 
 ## 信号对照表
 
-| 脚本输出信号 | 模型必须执行的动作 |
-|------------|----------------|
-| `MEMORY_READY` | 初始化成功；从同行使提取 session_id |
-| `session_id: sess_xxxxx` | 提取等号后值，保存为 SESSION_ID |
-| `COMPRESS_SUGGESTED` | 立即执行 summarize.py |
-| `SESSION_ID=sess_xxxxx` | restore 成功；提取等号后值，保存为新的 SESSION_ID |
-| `TASK_STATUS=complete` | 告知用户"上次任务已完成" |
-| `TASK_STATUS=in_progress` | 告知用户"上次任务进行中" |
-| `⚡ 建议运行: python3 scripts/summarize.py` | 执行该命令 |
-| 脚本返回 exit code != 0 | 静默跳过，继续主任务 |
+| 脚本输出 | 立即执行 |
+|---------|---------|
+| `MEMORY_READY` | 确认成功，继续主任务 |
+| `session_id: sess_xxxxx` | 保存为 SESSION_ID |
+| `COMPRESS_SUGGESTED` | 执行 summarize.py --session $SESSION_ID |
+| `SESSION_ID=sess_xxxxx` | 更新 SESSION_ID 为该值 |
+| 非零退出码 | 静默跳过，继续主任务 |
 
 ---
 
@@ -270,52 +285,51 @@ python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type milestone --su
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
-| `ULTRA_MEMORY_HOME` | `~/.ultra-memory/` | 存储根目录 |
-| `SESSION_ID` | init.py 执行后自动生成 | 当前会话 ID，保存后供后续命令使用 |
+| `ULTRA_MEMORY_HOME` | `~/.ultra-memory/` | 记忆存储根目录 |
+| `SKILL_DIR` | clawbot 注入 | skill 安装目录，未定义时用 `~/.openclaw/workspace/skills/ultra-memory/` |
+| `SESSION_ID` | init.py 执行后自动生成 | 当前会话 ID，保存后供后续所有命令使用 |
 
 ---
 
 ## 异常处理表
 
-| 异常情况 | 处理方式 |
-|---------|---------|
-| 脚本执行失败（exit code != 0） | **静默跳过**，继续主任务。记忆功能失败**不阻塞**用户实际需求 |
-| 脚本超时（>15s） | **静默跳过**，不重试 |
-| 存储目录无写入权限 | **静默跳过**，尝试写入内存缓冲区，下次重试 |
-| 脚本文件不存在 | **静默跳过**，在当前 context 中手动维护摘要 |
+| 情况 | 处理方式 |
+|------|---------|
+| init.py 找不到上次会话 | 正常，作为新会话继续 |
+| log_op.py 报会话不存在 | 重新执行 init.py，再记录 |
+| SESSION_ID 丢失 | 执行 init.py --project <名> --resume 尝试恢复 |
+| 任意脚本非零退出码 | **静默跳过**，不中断主任务 |
+| summarize.py 条数不足 | 加 --force 参数重新执行 |
 | 用户明确说"不用记录" | 立即停止记录，后续操作不再调用 log_op.py |
-| 文件被占用无法追加 | 自动重试 1 次，仍失败则静默跳过 |
-| SESSION_ID 未设置 | 先执行 init.py 初始化会话，再继续 |
+
+**最重要原则：记忆功能失败不能影响主任务。静默处理，不打印错误。**
 
 ---
 
 ## 完整执行流程
 
 ```
-用户发起对话
-    │
-    ├─ 首次对话或听到记忆触发词或描述持续性任务含项目名词？
-    │   └─ 是 → 执行 init.py
-    │       ├─ 输出含 MEMORY_READY？→ 提取 session_id，告知用户
-    │       └─ 输出含 COMPRESS_SUGGESTED？→ 执行 summarize.py
-    │
-    ├─ 用户说记忆相关问题？
-    │   └─ 是 → 执行 recall.py → 将结果展示给用户
-    │
-    ├─ 用户说恢复相关表达？
-    │   └─ 是 → 执行 restore.py → 提取 session_id + 总结 + 建议，告知用户
-    │
-    └─ 每次用户与 AI 交互后：
-        │
-        ├─ 操作数达到 50 条？→ 执行 summarize.py
-        ├─ 脚本输出含 COMPRESS_SUGGESTED？→ 执行 summarize.py
-        ├─ 满足画像积累条件？→ 更新 user_profile.json
-        ├─ 满足知识沉淀条件？→ 写入 knowledge_base.jsonl
-        ├─ 用户说完成相关表达？→ 记录 milestone
-        │
-        └─ 执行 log_op.py（记录本次操作）
+触发条件满足
+  └─ init.py --project <名> --resume
+       ├─ 提取 session_id → 保存为 SESSION_ID
+       └─ 有上次摘要 → 告知用户，询问是否继续
+
+执行任务（每次操作后）
+  ├─ 执行操作
+  ├─ log_op.py --session $SESSION_ID --type <type> --summary "..."
+  ├─ 输出 COMPRESS_SUGGESTED → summarize.py --session $SESSION_ID
+  └─ 观察到用户偏好/完成知识点 → 执行步骤六
+
+用户问"之前做了什么"
+  └─ recall.py --session $SESSION_ID --query "关键词"
+       └─ 原样展示输出给用户
+
+用户说"继续上次"（新会话）
+  └─ restore.py --project <名>
+       ├─ 提取新 SESSION_ID
+       └─ 告知用户恢复内容，询问是否继续
 ```
 
 ---
 
-进阶配置（过滤规则、LanceDB 向量检索升级、安全注意事项等）见 `references/advanced-config.md`。
+进阶配置（过滤规则、LanceDB 向量检索升级、自动 hook 配置、安全注意事项等）见 `references/advanced-config.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-memory",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "超长会话记忆系统 — 5层记忆架构，零外部依赖，支持所有LLM平台（Claude/GPT/Gemini/Qwen等）",
   "keywords": [
     "ai",

package/scripts/clawbot_hook.py

@@ -0,0 +1,256 @@
+#!/usr/bin/env python3
+"""
+ultra-memory clawbot auto-hook
+
+在 clawbot 的对话循环中自动触发 ultra-memory 记录，
+不依赖模型主动调用，保证任何模型（Claude/Gemini/MiniMax等）记忆都完整。
+
+用法（在 clawbot 的 skill_runner 或对话循环中导入）：
+    from clawbot_hook import UltraMemoryHook
+    hook = UltraMemoryHook()
+    # 每轮对话结束后：
+    hook.on_turn_end(session_id, model_name, user_msg, assistant_msg)
+
+此模块放置在 clawbot/core/ 或作为 ultra-memory 技能的一部分。
+"""
+
+import subprocess
+import re
+import os
+import json
+from pathlib import Path
+from datetime import datetime, timezone
+
+# ── 路径配置 ──────────────────────────────────────────────────────────────
+
+def _get_skill_dir():
+    """获取 SKILL_DIR，优先级：环境变量 > 默认安装路径"""
+    env = os.environ.get("SKILL_DIR")
+    if env:
+        return Path(env)
+    # 尝试常见安装路径
+    for p in [
+        Path.home() / ".openclaw" / "workspace" / "skills" / "ultra-memory",
+        Path(__file__).parent.parent,
+    ]:
+        if (p / "scripts" / "init.py").exists():
+            return p
+    return Path(__file__).parent
+
+
+SKILL_DIR = _get_skill_dir()
+LOG_SCRIPT = SKILL_DIR / "scripts" / "log_op.py"
+INIT_SCRIPT = SKILL_DIR / "scripts" / "init.py"
+SUMMARIZE_SCRIPT = SKILL_DIR / "scripts" / "summarize.py"
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+
+
+# ── 核心 Hook 类 ──────────────────────────────────────────────────────────
+
+class UltraMemoryHook:
+    """
+    ultra-memory 自动 hook。
+
+    在每轮对话结束后自动记录，模型不需要主动调用。
+    所有失败静默跳过，不影响主对话流程。
+    """
+
+    def __init__(self):
+        self._session_id = None  # 当前 session_id
+
+    # ── 对话轮次 Hook ───────────────────────────────────────────────────
+
+    def on_turn_end(
+        self,
+        session_id: str | None,
+        model_name: str,
+        user_msg: str,
+        assistant_msg: str,
+        project: str = "default",
+    ):
+        """
+        每轮对话结束后自动调用。
+
+        Args:
+            session_id: 当前会话 ID（未初始化则传入 None）
+            model_name: 当前模型名称（claude/gemini/minimax 等）
+            user_msg: 本轮用户消息
+            assistant_msg: 本轮模型输出
+            project: 项目名（从用户消息提取，无法提取用 default）
+        """
+        # 1. 确保有 session_id
+        if not session_id and not self._session_id:
+            sid = self._init_session(project)
+            if sid:
+                self._session_id = sid
+            return  # 首次初始化，等待下一轮再记录
+
+        sid = session_id or self._session_id
+        if not sid:
+            return
+
+        # 2. 自动记录本轮交互
+        self._log_turn(sid, model_name, user_msg, assistant_msg)
+
+        # 3. 检查压缩信号
+        self._check_compress(sid)
+
+    def _init_session(self, project: str) -> str | None:
+        """初始化会话，返回 session_id，失败返回 None"""
+        if not INIT_SCRIPT.exists():
+            return None
+
+        try:
+            result = subprocess.run(
+                ["python3", str(INIT_SCRIPT), "--project", project, "--resume"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+                errors="replace",
+            )
+            # 从输出中提取 session_id
+            match = re.search(r"session_id:\s*(sess_\w+)", result.stdout)
+            if match:
+                sid = match.group(1)
+                # 读取历史摘要注入上下文（供模型使用）
+                self._inject_context(sid)
+                return sid
+        except Exception:
+            pass
+        return None
+
+    def _log_turn(
+        self,
+        session_id: str,
+        model_name: str,
+        user_msg: str,
+        assistant_msg: str,
+    ):
+        """记录本轮交互，失败静默跳过"""
+        if not LOG_SCRIPT.exists():
+            return
+
+        summary = f"[{model_name}] 用户: {user_msg[:60]}{'...' if len(user_msg) > 60 else ''}"
+        detail = {
+            "model": model_name,
+            "user_msg_len": len(user_msg),
+            "assistant_msg_len": len(assistant_msg),
+            "user_preview": user_msg[:100],
+            "turn_ts": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        }
+
+        try:
+            result = subprocess.run(
+                [
+                    "python3", str(LOG_SCRIPT),
+                    "--session", session_id,
+                    "--type", "tool_call",
+                    "--summary", summary,
+                    "--detail", json.dumps(detail, ensure_ascii=False),
+                    "--tags", f"model:{model_name},auto",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                errors="replace",
+            )
+            # 检查压缩信号
+            if "COMPRESS_SUGGESTED" in result.stdout:
+                self._auto_summarize(session_id)
+        except Exception:
+            pass  # 静默跳过，不影响主流程
+
+    def _auto_summarize(self, session_id: str):
+        """自动触发摘要压缩"""
+        if not SUMMARIZE_SCRIPT.exists():
+            return
+        try:
+            subprocess.run(
+                ["python3", str(SUMMARIZE_SCRIPT), "--session", session_id],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                errors="replace",
+            )
+        except Exception:
+            pass
+
+    def _inject_context(self, session_id: str):
+        """
+        从 init.py 输出中读取历史摘要，注入到上下文供模型使用。
+        由 clawbot skill_runner 在模型调用前注入。
+        """
+        # 读取 session 目录下的 summary.md（最近一次压缩结果）
+        session_dir = ULTRA_MEMORY_HOME / "sessions" / session_id
+        summary_file = session_dir / "summary.md"
+        if not summary_file.exists():
+            return ""
+
+        try:
+            with open(summary_file, encoding="utf-8") as f:
+                content = f.read()
+            # 只取最后一个摘要块
+            blocks = content.split("---")
+            return blocks[-1].strip() if blocks else content.strip()
+        except Exception:
+            return ""
+
+    # ── 工具调用 Hook（可选）─────────────────────────────────────────────
+
+    def on_tool_call(
+        self,
+        session_id: str | None,
+        tool_name: str,
+        tool_input: dict,
+        tool_output: str,
+    ):
+        """
+        每次工具调用后自动记录（可选，需要 clawbot 支持 post_tool_call hook）。
+
+        Args:
+            session_id: 当前会话 ID
+            tool_name: 工具名称
+            tool_input: 工具输入参数
+            tool_output: 工具输出（截断到前200字）
+        """
+        sid = session_id or self._session_id
+        if not sid or not LOG_SCRIPT.exists():
+            return
+
+        summary = f"工具调用: {tool_name}"
+        detail = {
+            "tool": tool_name,
+            "input": str(tool_input)[:200],
+            "output_preview": tool_output[:200] if tool_output else "",
+        }
+
+        try:
+            subprocess.run(
+                [
+                    "python3", str(LOG_SCRIPT),
+                    "--session", sid,
+                    "--type", "tool_call",
+                    "--summary", summary,
+                    "--detail", json.dumps(detail, ensure_ascii=False),
+                    "--tags", f"tool:{tool_name},auto",
+                ],
+                capture_output=True,
+                timeout=5,
+                errors="replace",
+            )
+        except Exception:
+            pass
+
+    # ── 会话管理 ───────────────────────────────────────────────────────
+
+    def get_session_id(self) -> str | None:
+        """获取当前 session_id"""
+        return self._session_id
+
+    def set_session_id(self, session_id: str):
+        """手动设置 session_id（clawbot 恢复会话时调用）"""
+        self._session_id = session_id
+
+    def clear(self):
+        """清除当前会话（开始新会话时调用）"""
+        self._session_id = None