🧠 mi-memorystack-v2

⚠️ CRITICAL - 必须执行的流程

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

[用户输入]
    ↓
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. 确保守护进程已启动

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

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

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

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

示例:

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

输出:

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

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

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

示例:

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

输出:

[OK] 已加入保存队列

---

👤 用户ID获取

从 inbound_meta 中提取：

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

各平台字段： | 平台 | 字段 | 示例 | |------|------|------| | Feishu | sender_id | ou_c4f3245c6fca9 | | Discord | sender_id | 123456789012345678 | | Telegram | sender_id | 123456789 |

---

🔄 完整对话示例

场景：用户点奶茶

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

AI 内部执行:

# 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.py	0.1-0.3s	✅ 必须等待
保存	memory_add.py (同步)	0.5-2s	❌ 不推荐
保存	memory_add_async.py	0.08s	✅ 推荐
保存	memory_daemon.py queue	0.05s	✅ 最推荐

---

📋 列出已有记忆（memory_list）

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

基本用法

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

示例:

# 列出所有记忆
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）

{
  "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-v2/data

层级说明

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

文本格式输出

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

输出示例：

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

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

---

🔧 故障排查

1. 检查守护进程状态

python3 scripts/memory_daemon.py status

2. 重启守护进程

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

3. 查看日志

cat ~/.openclaw/memory_daemon.log

4. 验证保存结果

cat data/<user_id>.jsonl

---

⚠️ 重要提醒

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

---

📖 更多信息

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