🧠 Memory MI#

⚠️ CRITICAL - 必须执行的流程

每轮对话必须按以下顺序执行， 不可跳过任何步骤：

text

[用户输入]
    ↓
Step 1: [MUST] 执行 memory_search.py 检索记忆
    ↓
Step 2: 生成回复（融入记忆）
    ↓
Step 3: [MUST] 执行 memory_daemon.py queue 保存记忆（后台）
    ↓
Step 4: 显示回复给用户

自检清单（每轮对话后确认）：

• 是否执行了 memory_search.py？
• 是否执行了 memory_daemon.py queue？
• 是否看到 "已加入保存队列"？

---

🚀 快速使用#

1. 确保守护进程已启动#

bash

# 检查状态
python3 scripts/memory_daemon.py status

# 如未启动，执行
python3 scripts/memory_daemon.py start

2. 检索记忆（同步，必须等待）#

bash

python3 scripts/memory_search.py --user-id "<USER_ID>" --query "<用户输入>"

示例:

bash

python3 scripts/memory_search.py \
  --user-id "ou_c4f3245c6fca9" \
  --query "我想喝奶茶"

输出:

json

{
  "success": true,
  "memories": {
    "l0": "用户喜欢少糖奶茶",
    "l1": "用户是比亚迪车主"
  }
}

3. 保存记忆（后台异步，立即返回）#

bash

python3 scripts/memory_daemon.py queue \
  --user-id "<USER_ID>" \
  --query "<用户输入>" \
  --response "<AI回复>"

示例:

bash

python3 scripts/memory_daemon.py queue \
  --user-id "ou_c4f3245c6fca9" \
  --query "我想喝少糖奶茶" \
  --response "好的主人，记得要少糖哦～"

输出:

text

[OK] 已加入保存队列

---

👤 用户ID获取#

从 inbound_meta 中提取：

python

user_id = inbound_meta.get("sender_id") or inbound_meta.get("user_id")

各平台字段：

平台字段示例Feishusender_id``ou_c4f3245c6fca9Discordsender_id``123456789012345678Telegramsender_id``123456789

---

🔄 完整对话示例#

场景：用户点奶茶#

用户输入: "我刚点了杯奶茶"

AI 内部执行:

bash

# Step 1: 检索记忆
USER_ID="ou_c4f3245c6fca9"
QUERY="我刚点了杯奶茶"

MEMORIES=$(python3 scripts/memory_search.py \
  --user-id "$USER_ID" \
  --query "$QUERY")
# 返回: {"memories": {"l0": "用户喜欢少糖"}}

# Step 2: 生成回复（融入记忆）
RESPONSE="哈哈，主人你这奶茶频率可以啊！记得要少糖哦～"

# Step 3: 后台保存（立即返回）
python3 scripts/memory_daemon.py queue \
  --user-id "$USER_ID" \
  --query "$QUERY" \
  --response "$RESPONSE"
# 输出: [OK] 已加入保存队列

# Step 4: 显示回复给用户
echo "$RESPONSE"

用户看到: "哈哈，主人你这奶茶频率可以啊！记得要少糖哦～" ✅

后台处理: 守护进程自动将记忆写入文件

---

📊 性能对比#

步骤方式耗时是否阻塞检索memory_search.py0.1-0.3s✅ 必须等待保存memory_add.py (同步)0.5-2s❌ 不推荐保存memory_add_async.py0.08s✅ 推荐保存memory_daemon.py queue0.05s✅ 最推荐

---

📋 列出已有记忆（memory_list）#

用于查看用户所有的对话记忆，支持按层级统计和限制返回数量。

基本用法#

bash

python3 scripts/memory_list.py --user-id "<USER_ID>"

示例:

bash

# 列出所有记忆
python3 scripts/memory_list.py \
  --user-id "ou_c4f3245c6fca9"

# 只列出 L2 长期偏好
python3 scripts/memory_list.py \
  --user-id "<USER_ID>" \
  --level l2

# 只列出最近的 5 条 L1 记忆
python3 scripts/memory_list.py \
  --user-id "<USER_ID>" \
  --level l1 \
  --limit 5

输出格式（JSON）#

json

{
  "success": true,
  "user_id": "ou_c4f3245c6fca9",
  "memories": [
    {
      "line_num": 1,
      "level": "l2",
      "query": "我喜欢喝拿铁",
      "response": "记住了，你喜欢拿铁咖啡～",
      "timestamp": "2026-03-09T10:30:00"
    }
  ],
  "count": 15,
  "by_level": {
    "l0": 5,
    "l1": 3,
    "l2": 7
  },
  "filtered_by_level": "l2",
  "returned": 10
}

参数说明#

参数说明默认值--user-id用户唯一标识（必需）---level记忆层级过滤： l0/ l1/ l2全部--limit限制返回的记录数全部--format输出格式： json 或 text``json``--data-path记忆数据目录~/.openclaw/workspace/skills/Mi-MemoryStack/data

层级说明#

层级含义示例l0短期事实具体事件、问答记录l1用户画像身份、职业、个人信息l2长期偏好喜欢/讨厌/习惯/偏好

文本格式输出#

bash

python3 scripts/memory_list.py --user-id "<USER_ID>" --format text

输出示例：

text

============================================================
用户记忆列表 - ou_c4f3245c6fca9
============================================================
总记录数: 15
  - L0 (短期事实): 5 条
  - L1 (用户画像): 3 条
  - L2 (长期偏好): 7 条

[1] [L2] #1
    Q: 我喜欢喝拿铁
    A: 记住了，你喜欢拿铁咖啡～

---

🔧 故障排查#

1. 检查守护进程状态#

bash

python3 scripts/memory_daemon.py status

2. 重启守护进程#

bash

python3 scripts/memory_daemon.py stop
python3 scripts/memory_daemon.py start

3. 查看日志#

bash

cat ~/.openclaw/memory_daemon.log

4. 验证保存结果#

bash

cat data/<user_id>.jsonl

---

⚠️ 重要提醒#

1. 守护进程必须先启动，否则 queue 命令会失败
2. 每轮对话必须执行保存，不可遗漏
3. 用户ID必须正确，确保多用户隔离
4. 保存后立即返回，不等待后台完成

---

📖 更多信息#

• 守护进程: scripts/memory_daemon.py
• 搜索记忆: scripts/memory_search.py
• 列出记忆: scripts/memory_list.py