Ultra Memory — 多模型记忆操作手册#

AI Agent 的操作记忆系统，每次操作后记录，跨会话持久化，可检索可进化。

前置说明#

脚本位于 $SKILL_DIR/scripts/，直接调用，不需要生成，不需要理解内部架构。

• ULTRA_MEMORY_HOME 默认值为 ~/.ultra-memory/
• SKILL_DIR 解析顺序见步骤零

---

步骤零：环境探测#

每次触发条件满足后，第一件事执行此步骤，决定运行模式。

1. 解析 SKILL_DIR#

bash

# 按顺序尝试，取第一个找到 init.py 的路径
for _d in \
  "${SKILL_DIR}" \
  "${ULTRA_MEMORY_SKILL_DIR}" \
  "${HOME}/ultra-memory" \
  "${HOME}/.openclaw/workspace/skills/ultra-memory" \
  "$(npm root -g 2>/dev/null)/ultra-memory"; do
  if [ -f "${_d}/scripts/init.py" ]; then
    export SKILL_DIR="${_d}"
    echo "SCRIPT_AVAILABLE:${SKILL_DIR}"
    break
  fi
done

2. 判断运行模式#

输出运行模式后续行为SCRIPT_AVAILABLE:<路径>脚本模式按步骤一至七正常执行无任何输出 / 命令不可执行无脚本模式跳转到附录 E 执行，不再调用任何脚本

无脚本模式的典型场景：claude.ai web、无文件系统的在线 LLM 平台。

---

步骤一：会话初始化#

触发条件#

满足 frontmatter 中任意触发规则时，第一件事执行此步骤。

执行命令#

bash

python3 $SKILL_DIR/scripts/init.py --project <项目名> --resume [--scope <scope>]

参数说明：

• --project：项目名称。从用户最近一条消息中提取最显著的名词作为值；无法提取则用 default。
• --resume：必须加此参数，让脚本尝试恢复同项目的最近会话。
• --scope（可选）：隔离空间，用于多用户或多 Agent 场景。格式： user:alice、 agent:bot1、 project:myapp。不同 scope 的记忆完全隔离，互不干扰。省略时使用默认共享空间。

成功标志#

输出中的字符串模型必须执行的动作MEMORY_READY确认初始化成功session_id: sess_xxxxx从该行冒号后提取值，保存为 SESSION_ID

有上次会话摘要时#

将摘要内容告知用户，并询问："要从这里继续吗？"

---

步骤二：操作记录#

触发条件#

每次 用户与 AI 之间发生以下任意事件后，立即调用：

刚发生了什么op_type调用了任何工具tool_call创建或修改了文件file_write读取了文件file_read执行了 shell 命令bash_exec做出了重要判断或选择方案reasoning用户给出了新指令或改变了目标user_instruction做出了技术或方案决策decision发生了错误或需要回退error完成了一个明确的阶段目标milestone

执行命令#

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 必填。

示例#

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

高级用法：

bash

# 时间旅行：查询指定时间点的知识状态（如"上周我们的决策是什么"）
python3 $SKILL_DIR/scripts/recall.py \
  --session $SESSION_ID \
  --query "..." \
  --as-of 2026-03-01T00:00:00Z

# 实体历史：查看同名实体的所有版本变迁
python3 $SKILL_DIR/scripts/recall.py \
  --session $SESSION_ID \
  --history "clean_df"

结果展示#

将脚本输出原样展示给用户，不加工。

---

步骤四：摘要压缩#

触发条件#

满足以下 任意条件 时，立即执行：

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

成功标志#

命令返回 exit code 0，输出包含 摘要压缩完成。

---

步骤五：跨会话恢复#

触发条件#

用户说以下任意表达时触发： 继续昨天的、接着上次、从上次开始、继续之前的、continue from last、pick up where、resume、continue yesterday

执行命令#

bash

python3 $SKILL_DIR/scripts/restore.py --project <项目名>

从输出提取信息#

输出中的字符串模型必须执行的动作SESSION_ID=sess_xxxxx从等号后提取值，更新为新的 SESSION_ID``TASK_STATUS=complete告知用户"上次任务已完成"TASK_STATUS=in_progress告知用户"上次任务进行中"💬 <自然语言总结>直接说给用户📌 <继续建议>直接说给用户

将恢复内容告知用户，询问："要从这里继续吗？"

---

步骤六：记忆进化#

记忆进化在操作间隙进行，不打断主任务。

6A：用户画像积累#

触发条件（满足任意一条，立即更新）：

1. 用户纠正了 AI 生成的代码风格
2. 用户在两个方案中选择了其中一个
3. 用户说出自己的技术栈（含"我用"、"我们用"、"我们的项目用"、"we use"、"our stack"）
4. 用户表示某种工作方式更顺手
5. 用户明确描述了自己的偏好

执行方式 — 方式 A（MCP 工具，推荐）：

调用 memory_profile， action=update， updates 填写观察到的偏好字段。

执行方式 — 方式 B（直接修改文件）：

bash

# 文件路径：$ULTRA_MEMORY_HOME/semantic/user_profile.json
# 只更新观察到的字段，不覆盖已有字段，使用 JSON merge 方式

user_profile.json 可更新字段：

json

{
  "tech_stack": ["观察到的技术栈"],
  "language": "zh-CN 或 en",
  "work_style": {
    "confirm_before_implement": true,
    "prefers_concise_code": true
  },
  "observed_patterns": ["倾向先确认方案再实现"]
}

6B：知识沉淀#

触发条件（满足任意一条，立即写入知识库）：

1. 解决了一个报错或 bug（记录问题现象 + 解决方案）
2. 做出了技术选型决策（选了什么 + 为什么）
3. 发现了某个工具或库的使用技巧
4. 完成了一个可复用的代码模式

文件路径：

text

$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl

执行方式 — 方式 A（MCP 工具，推荐）：

调用 memory_knowledge_add， title 必填（20字内）， content 必填（200字内）， project 和 tags 可选。

执行方式 — 方式 B（直接追加）：

追加写入 knowledge_base.jsonl，每行一条 JSON，不覆盖。

knowledge_base.jsonl 格式：

json

{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "20字内标题", "content": "200字内描述", "tags": ["tag1"]}

6C：里程碑记录#

触发条件 — 用户说出以下任意表达，立即记录：

中文：好了、完成了、搞定了、做完了、弄好了、可以了、没问题了、测试通过、上线了

英文：done、finished、completed、it works、all good、passed、deployed、ready

执行命令：

bash

python3 $SKILL_DIR/scripts/log_op.py \
  --session $SESSION_ID \
  --type milestone \
  --summary "<用户刚完成的事情，一句话描述>"

---

步骤七：元反思与进化#

记忆积累不等于进化。进化需要对记忆做二次加工：提炼模式、纠正偏差、淘汰噪音。

7A：定期元反思#

触发条件（满足任意一条）：

1. 当前会话里程碑累计达到 5 个（从 init.py 返回的 op_count 判断，每次 milestone 后检查）
2. 用户说：回顾一下、总结经验、我们学到了什么、reflect、what have we learned、review progress
3. 距上次元反思超过 3 天（从 user_profile.json 的 last_reflection 字段判断，不存在则视为从未反思过）

执行步骤（按顺序执行，不可跳过）：

第一步：读取近期知识库

bash

# 读取最近 20 条知识库条目
tail -20 $ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl

第二步：读取近期会话摘要

bash

# 读取当前会话摘要
cat $ULTRA_MEMORY_HOME/sessions/$SESSION_ID/summary.md 2>/dev/null || echo "暂无摘要"

第三步：模型自主提炼（核心步骤）

基于读取到的内容，模型执行以下判断，每一项都必须完成：

判断项执行动作发现两条或以上内容相似的知识条目合并为一条更精炼的条目，写入 knowledge_base.jsonl，原条目加 "merged": true 标记发现某个知识点在多次操作中反复出现将其标记为 "importance": "high"，写回该条目发现某条知识点超过 30 天未被检索且不是 high importance将其标记为 "stale": true发现用户行为与 user_profile.json 记录不符更新 user_profile.json 对应字段，加 "corrected_at" 时间戳总结出一个新的用户工作规律追加到 user_profile.json 的 observed_patterns 数组

第四步：写入反思记录

bash

python3 $SKILL_DIR/scripts/log_op.py \
  --session $SESSION_ID \
  --type reasoning \
  --summary "元反思完成：<一句话描述本次提炼了什么>" \
  --tags "reflection,evolution"

第五步：更新反思时间戳

将 user_profile.json 的 last_reflection 字段更新为当前 UTC 时间（ISO 格式）。

第六步：告知用户（简短）

用一句话告知用户反思结果。不需要展示完整报告，一句话即可，不打断主任务。

---

7B：错误修正#

触发条件（满足任意一条）：

1. 用户说：不对、你记错了、不是这样的、纠正一下、wrong、that's not right、correct that
2. 用户描述的信息与 user_profile.json 中的记录明显矛盾

执行步骤：

第一步：定位错误记录

bash

cat $ULTRA_MEMORY_HOME/semantic/user_profile.json

第二步：模型判断需要修正的字段

找到与用户当前描述矛盾的字段。

第三步：修正并记录

更新 user_profile.json 对应字段，同时在该字段旁追加：

json

"_correction_note": "用户于 <日期> 纠正，原值为 <旧值>"

第四步：记录修正操作

bash

python3 $SKILL_DIR/scripts/log_op.py \
  --session $SESSION_ID \
  --type decision \
  --summary "用户画像修正：<字段名> 从 <旧值> 改为 <新值>" \
  --tags "correction,profile"

第五步：告知用户

"好的，我已经更新了记录，<字段名> 现在是 <新值>。"

---

7C：知识蒸馏（每月一次）#

触发条件（必须同时满足，按顺序检查）：

先决条件（任一不满足则直接跳过，不读时间戳）：

bash

# 检查知识库是否存在且条目数 ≥ 10
[ -f "$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl" ] \
  && [ "$(wc -l < "$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl")" -ge 10 ] \
  && echo "KB_SUFFICIENT" || echo "KB_SKIP"

输出 KB_SKIP → 立即跳过本步骤，不执行后续任何检查。

时间条件（先决条件通过后才检查）：

读取 user_profile.json 的 last_distillation 字段：

• 字段不存在：视为"本机首次蒸馏"，触发一次
• 字段存在且距今 > 30 天：触发
• 字段存在且距今 ≤ 30 天：跳过

为什么先检查知识库再检查时间戳： 换机器或清存储后知识库为空，若先检查时间戳会因字段缺失而触发，但步骤一统计条目数后立即跳过，造成每次会话都执行无效检查。倒序检查后空库直接短路，不会误触发。

在步骤七 7A 执行完毕后，额外执行本步骤。

执行步骤：

第一步：统计知识库规模（已在触发条件中完成，此处直接读结果）

第二步：提取高价值条目

读取全部 knowledge_base.jsonl，筛选满足以下任意条件的条目：

• "importance": "high"
• tags 中包含 "reusable" 或 "pattern"
• 同一 title 关键词出现超过 2 次

第三步：生成项目级知识摘要

基于筛选出的条目，生成一段 200 字以内的项目级知识摘要，格式：

json

{"ts": "<当前UTC时间>", "type": "distillation", "period": "<YYYY-MM>", "project": "<项目名>", "summary": "<200字以内的知识摘要>", "source_count": <来源条目数>, "tags": ["distillation"]}

追加写入 knowledge_base.jsonl。

第四步：更新蒸馏时间戳

将 user_profile.json 的 last_distillation 更新为当前 UTC 时间。

---

信号对照表#

脚本输出立即执行MEMORY_READY确认成功，继续主任务session_id: sess_xxxxx保存为 SESSION_IDCOMPRESS_SUGGESTED执行 summarize.py --session $SESSION_IDSESSION_ID=sess_xxxxx更新 SESSION_ID 为该值非零退出码静默跳过，继续主任务op_count 达到 5 的倍数且含 milestone触发步骤 7Auser_profile.json last_reflection 距今 > 3 天下次会话初始化后触发步骤 7A

---

环境变量表#

变量默认值说明ULTRA_MEMORY_HOME``~/.ultra-memory/记忆存储根目录；使用 scope 时自动切换到 <HOME>/scopes/<scope>/``ULTRA_MEMORY_SESSION空当前会话 ID；配置后 Claude Code 自动捕获钩子（hook_capture.py）使用此值SKILL_DIRclawbot 注入skill 安装目录；未定义时步骤零按 ~/ultra-memory → ~/.openclaw/workspace/skills/ultra-memory → npm root -g 顺序探测，均未找到则切换无脚本模式ULTRA_MEMORY_SKILL_DIR用户手动设置SKILL_DIR 的备用名，优先级低于 SKILL_DIR，高于路径探测SESSION_IDinit.py 执行后自动生成当前会话 ID，保存后供后续所有命令使用

---

异常处理表#

情况处理方式init.py 找不到上次会话正常，作为新会话继续log_op.py 报会话不存在重新执行 init.py，再记录SESSION_ID 丢失执行 init.py --project <名> --resume 尝试恢复任意脚本非零退出码静默跳过，不中断主任务summarize.py 条数不足加 --force 参数重新执行用户明确说"不用记录"立即停止记录，后续操作不再调用 log_op.pyknowledge_base.jsonl 不存在跳过 7A 的知识库读取，仅基于摘要执行反思user_profile.json 解析失败重新创建空文件，不中断进化流程

最重要原则：记忆功能失败不能影响主任务。静默处理，不打印错误。

---

完整执行流程#

text

触发条件满足
  └─ 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 向量检索升级、自动 hook 配置、安全注意事项等）见 references/advanced-config.md。

---

附录 A：检索行为说明#

recall.py 同时在五层记忆中搜索，结果按相关度和时间综合排序：

• 近期操作权重高于久远操作（时间衰减）
• 关键词在多个层都命中时，该结果排名靠前
• 安装 sentence-transformers 后，召回精度会进一步提升（可选，完全本地运行）
• 输出为相关片段而非完整记录，节省上下文空间

---

附录 B：记忆分层#

每条操作压缩后自动标记层级，影响 gc 清理策略：

层级操作类型说明coremilestone / decision / error / user_instruction长期保留workingreasoning / file_write / bash_exec当前会话活跃peripheralfile_read / tool_call历史细节，可清理

summary.md 压缩后会显示各层计数。

---

附录 C：manage.py 管理工具#

bash

# 列出所有会话
python3 $SKILL_DIR/scripts/manage.py list
python3 $SKILL_DIR/scripts/manage.py list --project my-project

# 跨所有会话全文搜索
python3 $SKILL_DIR/scripts/manage.py search "pandas 数据清洗"
python3 $SKILL_DIR/scripts/manage.py search "error" --limit 50

# 全局统计（操作数、tier 分布、项目分布、知识库规模）
python3 $SKILL_DIR/scripts/manage.py stats

# 导出完整记忆备份
python3 $SKILL_DIR/scripts/manage.py export --format json --output backup.json
python3 $SKILL_DIR/scripts/manage.py export --format markdown --output memory.md

# 垃圾回收：清理 90 天未活跃且无核心操作的会话（默认预演）
python3 $SKILL_DIR/scripts/manage.py gc
python3 $SKILL_DIR/scripts/manage.py gc --days 30 --no-dry-run  # 实际执行

# 补写 tier 分层标记（历史数据迁移）
python3 $SKILL_DIR/scripts/manage.py tier
python3 $SKILL_DIR/scripts/manage.py tier --session sess_xxxxx

# 列出所有隔离 scope（多用户/多 Agent）
python3 $SKILL_DIR/scripts/manage.py scopes

---

附录 D：REST API 认证（可选）#

启动 REST 服务器时可配置 Bearer Token 保护：

bash

# 方式 1：命令行参数
python3 $SKILL_DIR/platform/server.py --token your-secret-token

# 方式 2：环境变量
ULTRA_MEMORY_TOKEN=your-secret-token python3 $SKILL_DIR/platform/server.py

# 客户端调用时携带 Header：
# Authorization: Bearer your-secret-token

不配置 token 时服务器维持原有行为（仅监听 127.0.0.1，局域网不可访问）。

---

附录 E：无脚本降级模式#

适用场景： claude.ai web 对话、无文件系统的在线 LLM 平台、 $SKILL_DIR 探测失败的任意环境。

此模式不依赖文件系统、Python 脚本或任何外部工具，完全依赖 AI 自身维护结构化记忆 prompt。

---

E1：会话内记忆结构#

AI 在内心维护以下结构（不主动输出给用户，仅在需要时引用）：

text

MEMORY_STATE:
  project: <项目名>
  started: <ISO时间>
  ops: []           # 近 20 条操作；格式: {seq, type, summary}
  milestones: []    # 里程碑列表（长期保留）
  decisions: []     # 关键决策（长期保留）
  knowledge: []     # 知识点，最多 10 条
  profile:
    tech_stack: []
    observed_patterns: []

核心原则：ops 满 20 条时，将最旧的非 milestone/decision 操作合并进 milestones 或丢弃。

---

E2：操作记录（替代 log_op.py）#

每次发生 E2 触发事件（见主文步骤二的触发条件表）后，AI 在内心更新 MEMORY_STATE.ops。无需输出，不增加对话轮数。

---

E3：记忆检索（替代 recall.py）#

用户询问历史时，AI 直接扫描 MEMORY_STATE 内所有字段，提取相关条目回答。

---

E4：摘要压缩（替代 summarize.py）#

对话超过 30 轮 或用户说"总结一下"时，AI 执行内部压缩：

1. 将 ops 中重要性低的条目合并进 milestones/ decisions
2. 清空 ops，仅保留最近 5 条
3. 向用户简述压缩结果（一句话）

---

E5：跨会话限制（必须向用户说明）#

首次进入无脚本模式时，AI 主动告知用户：

"当前运行在无脚本模式，记忆仅在本次对话有效，关闭后无法恢复。如需跨会话持久化，请在 Claude Code 或安装了 ultra-memory 的环境中使用。"

此说明只输出一次，不重复。

---

E6：功能对比#

功能脚本模式无脚本模式操作记录✅ 持久化文件✅ 会话内维护关键词检索✅ BM25 + 向量✅ AI 直接扫描摘要压缩✅ 自动✅ 手动触发跨会话恢复✅❌用户画像积累✅ 持久化⚠️ 仅当前会话知识蒸馏✅❌多 scope 隔离✅❌