ultra-memory 3.0.3 → 3.0.5

package/SKILL.md

@@ -1,235 +1,283 @@
 ---
 name: ultra-memory
 description: >
-  ultra-memory 是 AI Agent 的超长会话记忆系统。
-  【必须触发-中文】用户说：记住、别忘了、记录一下、上次我们做了什么、帮我回忆、继续上次、从上次继续、不要忘记、上次、跨会话、继续昨天、还有印象吗、我们上次讨论过、之前那个是怎么写的、还记得吗、这次不要忘、帮我追踪、帮我记着
-  【必须触发-英文】用户说：remember this、don't forget、recall、what did we do、pick up where we left off、continue from last time、memory、keep track、log this、what was that、remind me、context lost、continue from yesterday、from last session
-  【隐式触发】用户描述了一个持续性任务（开发某项目、处理某数据集、持续性工作），即使未说"记住"也必须初始化记忆；对话操作数超过30条；用户说"继续昨天的任务"/"接着上次做"
-  【不触发】单次问答（"帮我写个正则"、"查一下天气"）；纯代码补全、文件格式转换等无状态操作；用户已在 context 中能找到所需信息；用户明确说"不用记录"/"just this once"
+  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
+  【隐式触发-A+B】同时满足以下两条时触发：(A)消息含持续性任务动词：开发、实现、处理、完成、构建、develop、implement、create、fix；(B)消息中包含项目名词（专有名词/文件名/系统名）
+  【不触发】用户只问一个问题无后续；单次咨询无操作步骤；说"随便聊聊"、"just chatting"；明确说"不用记录"
 ---
 
-# Ultra Memory — 超长会话记忆
+# Ultra Memory — 多模型记忆操作手册
 
 AI Agent 的操作记忆系统，每次操作后记录，跨会话持久化，可检索可进化。
 
 ## 前置说明
 
-所有脚本已存在于 `~/.ultra-memory/scripts/` 或技能目录下：
-- `init.py` — 初始化会话
-- `log_op.py` — 记录操作
-- `recall.py` — 检索记忆
-- `summarize.py` — 压缩摘要
-- `restore.py` — 恢复会话
-- `extract_entities.py` — 提取实体
+脚本已全部存在于 `$SKILL_DIR/scripts/`，直接调用，不需要生成，不需要理解内部架构。
 
-存储根目录：`~/.ultra-memory/`（可配置环境变量 `ULTRA_MEMORY_HOME`）
-不需要理解内部架构，只需按步骤调用脚本。
+- `ULTRA_MEMORY_HOME` 默认值为 `~/.ultra-memory/`
+- `SKILL_DIR` 由 clawbot 注入，如未定义则用 `~/.openclaw/workspace/skills/ultra-memory/`
 
 ---
 
 ## 步骤一：会话初始化
 
-### 触发时机
+### 触发条件
 
-首次与用户对话时，或用户提到记忆相关触发词时，立即执行。
+满足 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:`，记录该会话 ID。
+| 输出中的字符串 | 模型必须执行的动作 |
+|-------------|----------------|
+| `MEMORY_READY` | 确认初始化成功 |
+| `session_id: sess_xxxxx` | 从该行冒号后提取值，保存为 `SESSION_ID` |
 
-### 告知用户
+### 有上次会话摘要时
 
-初始化成功后，立即告知用户：
-> "记忆系统已就绪（session_id: xxx），开始记录本次操作。"
+将摘要内容告知用户，并询问："要从这里继续吗？"
 
 ---
 
 ## 步骤二：操作记录
 
-**每次**以下任意事件发生时，立即调用 `log_op.py` 追加写入 ops.jsonl。
+### 触发条件
 
-### 操作类型与命令对照表
+**每次**用户与 AI 之间发生以下任意事件后，立即调用：
 
-| 事件 | op_type | 命令示例 |
-|------|---------|---------|
-| 执行了 shell 命令 | `bash_exec` | `python3 log_op.py --session <id> --type bash_exec --summary "执行了..." --detail '{"cmd":"...","exit_code":0}'` |
-| 创建或修改了文件 | `file_write` | `python3 log_op.py --session <id> --type file_write --summary "创建了..." --detail '{"path":"..."}'` |
-| 读取了文件 | `file_read` | `python3 log_op.py --session <id> --type file_read --summary "读取了..." --detail '{"path":"..."}'` |
-| 进行了重要推理 | `reasoning` | `python3 log_op.py --session <id> --type reasoning --summary "决定用..." --detail '{"confidence":0.9}'` |
-| 做出了关键决策 | `decision` | `python3 log_op.py --session <id> --type decision --summary "选用X方案" --detail '{"rationale":"..."}'` |
-| 发生了错误或回退 | `error` | `python3 log_op.py --session <id> --type error --summary "报错..." --detail '{"traceback":"..."}'` |
-| 用户给了新指令 | `user_instruction` | `python3 log_op.py --session <id> --type user_instruction --summary "用户要求..."` |
-| 某个目标已完成 | `milestone` | `python3 log_op.py --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 即为成功，输出形如：
-> `[ultra-memory] [1] bash_exec: 执行了 pip install pandas，安装成功`
+```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`：立即执行步骤四。
 
 ---
 
 ## 步骤三：记忆检索
 
-### 触发时机
+### 触发条件
 
-用户问及"之前做了什么"、"上次那个函数在哪里"、"之前遇到过这个问题吗"等记忆相关问题时执行。
+用户问及以下任意问题时立即执行：
+之前、上次、那个函数、那个文件、那个命令、我们做过、怎么写的、什么名字、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
 ```
 
-### 检索范围
-
-按以下优先级检索：
-1. 当前会话 `ops.jsonl`（精确匹配）
-2. 当前会话 `summary.md`（摘要快速定位）
-3. 跨会话 `knowledge_base.jsonl`（语义相似）
-4. 跨会话 `user_profile.json`（偏好匹配）
-
 ### 结果展示
 
-将检索结果直接展示给用户，格式如下：
-```
-[RECALL] 找到 N 条相关记录：
-
-[ops #23 · 14:18] <操作摘要>
-[summary · 里程碑] <里程碑内容>
-[跨会话 · 日期 · 项目] <历史记录摘要>
-```
+将脚本输出原样展示给用户，不加工。
 
 ---
 
 ## 步骤四：摘要压缩
 
-### 触发时机
+### 触发条件
 
-满足以下**任一条件**时，立即执行压缩：
+满足以下**任意条件**时，立即执行：
 
-1. 操作日志达到 **50 条**
-2. 距上次压缩超过 **30 分钟**
-3. 用户明确说"总结一下"
-4. 当前 context 占用超过 **60%**
+1. 步骤二中脚本输出了 `COMPRESS_SUGGESTED`
+2. 用户说：总结一下、目前进展、Summary、summarize
+3. 当前对话已超过 **30 轮**
 
 ### 执行命令
 
 ```bash
-python3 <skill_dir>/scripts/summarize.py --session <session_id> --force
+python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID
+```
+
+条数不足时强制执行：
+```bash
+python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID --force
 ```
 
-### 期望输出
+### 成功标志
 
-生成/更新 `~/.ultra-memory/sessions/<session_id>/summary.md`，输出包含：
-- 已完成里程碑（[✅] 标记）
-- 当前进行中（[ ] 标记）
-- 下一步建议（[💡] 标记）
-- 操作统计（[📊] 标记）
+命令返回 exit code 0，输出包含 `摘要压缩完成`。
 
 ---
 
 ## 步骤五：跨会话恢复
 
-### 触发时机
+### 触发条件
 
-用户说"继续上次"、"从上次继续"、"记得昨天那个项目吗"等时执行。也在新会话开始时（检测到 session_id 变化）自动执行。
+用户说以下任意表达时触发：
+继续昨天的、接着上次、从上次开始、继续之前的、continue from last、pick up where、resume、continue yesterday
 
 ### 执行命令
 
 ```bash
-python3 <skill_dir>/scripts/restore.py --project <项目名>
+python3 $SKILL_DIR/scripts/restore.py --project <项目名>
 ```
 
-### 告知用户
+### 从输出提取信息
 
-恢复成功后，立即告知用户：
-> "我找到了上次会话的记录。上次我们做到了：[里程碑摘要]。当前状态：[进行中任务]。下一步建议：[具体建议]。"
+| 输出中的字符串 | 模型必须执行的动作 |
+|-------------|----------------|
+| `SESSION_ID=sess_xxxxx` | 从等号后提取值，更新为新的 `SESSION_ID` |
+| `TASK_STATUS=complete` | 告知用户"上次任务已完成" |
+| `TASK_STATUS=in_progress` | 告知用户"上次任务进行中" |
+| `💬 <自然语言总结>` | 直接说给用户 |
+| `📌 <继续建议>` | 直接说给用户 |
 
-如果找到了用户画像，也在回复中体现用户偏好。
+将恢复内容告知用户，询问："要从这里继续吗？"
 
 ---
 
 ## 步骤六：记忆进化
 
-记忆进化在每次操作中持续进行，不打断主任务。
+记忆进化在操作间隙进行，不打断主任务。
+
+### 6A：用户画像积累
 
-### 6.1 用户画像更新
+**触发条件（满足任意一条，立即更新）：**
+
+1. 用户纠正了 AI 生成的代码风格
+2. 用户在两个方案中选择了其中一个
+3. 用户说出自己的技术栈（含"我用"、"我们用"、"我们的项目用"、"we use"、"our stack"）
+4. 用户表示某种工作方式更顺手
+5. 用户明确描述了自己的偏好
+
+**执行方式 — 方式 A（MCP 工具，推荐）：**
 
-**触发时机：**
-- 用户纠正了 AI 的代码风格或实现方式
-- 用户选择/拒绝了某个技术方案
-- 用户明确说出自己的技术栈或偏好
-- 用户表示某种工作流程更顺手
+调用 `memory_profile`，`action=update`，`updates` 填写观察到的偏好字段。
 
-**执行方式（二选一）：**
+**执行方式 — 方式 B（直接修改文件）：**
 
-方式 A — 使用 MCP 工具：
 ```bash
-python3 <skill_dir>/scripts/mcp-server.js  # 通过 MCP 调用 memory_profile
+# 文件路径：$ULTRA_MEMORY_HOME/semantic/user_profile.json
+# 只更新观察到的字段，不覆盖已有字段，使用 JSON merge 方式
 ```
 
-方式 B — 直接读写 JSON：
-```
-文件路径：~/.ultra-memory/semantic/user_profile.json
-```
+**user_profile.json 可更新字段：**
 
-**user_profile.json 格式：**
 ```json
 {
-  "tech_stack": ["Python", "Vue3"],
-  "work_style": {"prefers_concise_code": true},
-  "projects": ["ai-data-qa"],
-  "language": "zh-CN",
-  "observed_patterns": ["倾向在实现前讨论方案"]
+  "tech_stack": ["观察到的技术栈"],
+  "language": "zh-CN 或 en",
+  "work_style": {
+    "confirm_before_implement": true,
+    "prefers_concise_code": true
+  },
+  "observed_patterns": ["倾向先确认方案再实现"]
 }
 ```
 
-### 6.2 知识库写入
+### 6B：知识沉淀
 
-**触发时机：**
-- 解决了一个棘手的 bug（记录问题现象 + 解决方案）
-- 做出了重要的技术选型决策（记录选了什么、为什么、放弃了什么）
-- 发现了某个工具/库的使用技巧
-- 完成了一个可复用的代码模式
+**触发条件（满足任意一条，立即写入知识库）：**
+
+1. 解决了一个报错或 bug（记录问题现象 + 解决方案）
+2. 做出了技术选型决策（选了什么 + 为什么）
+3. 发现了某个工具或库的使用技巧
+4. 完成了一个可复用的代码模式
+
+**文件路径：**
 
-**执行方式 — 方式 A（MCP 工具，推荐）：**
-```bash
-# 通过 memory_knowledge_add MCP 工具写入
-# 参数：title（必填，100字内）、content（必填，200字内）、project（可选）、tags（可选）
 ```
+$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl
+```
+
+**执行方式 — 方式 A（MCP 工具，推荐）：**
+
+调用 `memory_knowledge_add`，`title` 必填（20字内），`content` 必填（200字内），`project` 和 `tags` 可选。
 
 **执行方式 — 方式 B（直接追加）：**
-直接追加写入 `~/.ultra-memory/semantic/knowledge_base.jsonl`，每行一条 JSON。
+
+追加写入 `knowledge_base.jsonl`，每行一条 JSON，不覆盖。
 
 **knowledge_base.jsonl 格式：**
+
 ```json
-{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "简短标题", "content": "内容（200字内）", "tags": ["bug-fix", "python"]}
+{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "20字内标题", "content": "200字内描述", "tags": ["tag1"]}
 ```
 
-### 6.3 里程碑追踪
+### 6C：里程碑记录
 
-**触发时机：**
-- 用户说"好了"、"完成了"、"搞定了"、"done"、"finished"
-- 某个功能/模块通过了测试
-- 阶段任务全部完成，用户准备切换下一个子任务
+**触发条件 — 用户说出以下任意表达，立即记录：**
 
-**执行方式：**
-使用 `op_type=milestone` 调用 `log_op.py`（见步骤二表格）。
+中文：好了、完成了、搞定了、做完了、弄好了、可以了、没问题了、测试通过、上线了
 
-**作用：** 里程碑记录在 `summary.md` 中，恢复会话时优先展示，让用户快速找回状态。
+英文：done、finished、completed、it works、all good、passed、deployed、ready
+
+**执行命令：**
+
+```bash
+python3 $SKILL_DIR/scripts/log_op.py \
+  --session $SESSION_ID \
+  --type milestone \
+  --summary "<用户刚完成的事情，一句话描述>"
+```
+
+---
+
+## 信号对照表
+
+| 脚本输出 | 立即执行 |
+|---------|---------|
+| `MEMORY_READY` | 确认成功，继续主任务 |
+| `session_id: sess_xxxxx` | 保存为 SESSION_ID |
+| `COMPRESS_SUGGESTED` | 执行 summarize.py --session $SESSION_ID |
+| `SESSION_ID=sess_xxxxx` | 更新 SESSION_ID 为该值 |
+| 非零退出码 | 静默跳过，继续主任务 |
 
 ---
 
@@ -237,48 +285,51 @@ python3 <skill_dir>/scripts/mcp-server.js  # 通过 MCP 调用 memory_profile
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
-| `ULTRA_MEMORY_HOME` | `~/.ultra-memory/` | 存储根目录 |
-| `ULTRA_MEMORY_SESSION` | 自动生成 | 当前会话 session_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 次，仍失败则静默跳过 |
+
+**最重要原则：记忆功能失败不能影响主任务。静默处理，不打印错误。**
 
 ---
 
 ## 完整执行流程
 
 ```
-用户发起对话
-    │
-    ├─ 首次对话或听到记忆触发词？
-    │   └─ 是 → 步骤一：init.py → 告知用户"记忆就绪"
-    │
-    ├─ 用户说记忆相关问题？
-    │   └─ 是 → 步骤三：recall.py → 展示检索结果
-    │
-    └─ 每次用户与 AI 交互后：
-        │
-        ├─ 操作数 % 10 == 0 且 context > 60%？
-        │   └─ 是 → 步骤四：summarize.py
-        │
-        ├─ 发现用户偏好 / 解决重要问题 / 完成里程碑？
-        │   └─ 是 → 步骤六：进化（画像/知识库/里程碑）
-        │
-        └─ 步骤二：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.3",
+  "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