# 🧠 记忆系统使用指南

> ⚠️ **所有模型切换时必须首先阅读此文档！**  
> 这是记忆系统的核心说明，确保不同模型之间的记忆连续性。

---

## 📋 快速启动清单

新模型上线后，**必须按顺序执行以下步骤**：

### ⚡ 第一步：快速记忆卡片（30 秒）

**Read `memory/QUICK_START.md`** — 这是核心记忆的浓缩版，包含：
- 用户称呼和身份
- 交互偏好（必须遵守！）
- 当前项目状态
- 关键记忆点
- 模型切换检查清单

### 📚 第二步：完整记忆系统指南

**Read `memory/README.md`**（本文件）— 理解记忆系统的完整架构和使用方法

### 🔧 第三步：确认记忆系统结构

```bash
# 查看记忆系统状态
python3 /home/ubuntu/.openclaw/workspace/memory_manager.py status

# 导出完整记忆摘要（可选）
python3 /home/ubuntu/.openclaw/workspace/memory_manager.py summary
```

### 📖 第四步：读取核心记忆文件

**必须读取以下文件**（按优先级）：

| 优先级 | 文件 | 说明 |
|--------|------|------|
| 🔴 P0 | `memory/QUICK_START.md` | 快速记忆卡片（30 秒了解核心） |
| 🔴 P0 | `MEMORY.md` | 核心长期记忆，用户身份、偏好、项目 |
| 🔴 P0 | `memory/preferences.md` | 用户交互偏好、禁忌、期望 |
| 🟡 P1 | `memory/decisions.md` | 历史重要决策 |
| 🟡 P1 | `memory/projects.md` | 当前项目状态 |
| 🟢 P2 | `memory/contacts.md` | 联系人信息 |
| 🟢 P2 | `memory/YYYY-MM-DD.md` | 最近 3 天的日志（了解近期上下文） |

### ✅ 第五步：验证记忆加载

向用户确认：
> "记忆系统已加载，我已读取 [X] 条核心记忆，包括 [举例 1-2 条关键信息]。"

---

## 🏗️ 记忆系统架构

### 双层结构

```
workspace/
├── MEMORY.md              # 长期记忆核心库
├── memory_manager.py      # 记忆管理脚本
└── memory/
    ├── README.md          # 本文件（模型切换必读）
    ├── contacts.md        # 联系人
    ├── decisions.md       # 决策记录
    ├── preferences.md     # 用户偏好
    ├── projects.md        # 项目跟踪
    ├── 2026-03-13.md      # 每日日志（30 天衰减）
    └── ...
```

### 记忆分类

| 分类 | 文件 | 内容示例 |
|------|------|----------|
| 👥 联系人 | `contacts.md` | 用户称呼、身份、关系网络 |
| 📝 决策 | `decisions.md` | "2026-03-13 安装 A 股技能" |
| ⚙️ 偏好 | `preferences.md` | "效率优先"、"称呼老大" |
| 📁 项目 | `projects.md` | 项目进度、关注股票列表 |
| 📅 日志 | `YYYY-MM-DD.md` | 当日会话流水账 |

---

## 📊 记忆写入规则

### 重要性评分（1-5 分）

| 评分 | 标准 | 写入位置 |
|------|------|----------|
| 5 分 | 系统配置、核心身份、用户明确要求"永久保存" | MEMORY.md + 分类文件 |
| 4 分 | 重要决策、关键偏好、项目里程碑 | MEMORY.md + 分类文件 |
| 3 分 | 一般任务、临时计划 | 当日日志 |
| 2 分 | 日常对话、简单查询 | 当日日志 |
| 1 分 | 寒暄、无关内容 | 丢弃 |

### 写入命令

```bash
# 自动评分写入
python3 memory_manager.py write "用户今天决定关注中钨高新"

# 强制写入长期记忆（用户说"记下来"时）
python3 memory_manager.py write "用户不吃香菜" --force-long
```

---

## 🔍 记忆检索

### 搜索命令

```bash
# 关键词搜索
python3 memory_manager.py search "股票"

# 分类内搜索
python3 memory_manager.py search "偏好" --category preferences
```

### 检索策略

1. **优先查长期记忆**（MEMORY.md + 分类文件）
2. **再查近期日志**（最近 7 天）
3. **最后查全部日志**（30 天内）

---

## 🔄 模型切换流程

### 新模型启动时

```
1. 读取 memory/README.md（本文件）
   ↓
2. 读取 MEMORY.md（核心记忆）
   ↓
3. 读取 memory/preferences.md（用户偏好）
   ↓
4. 读取 memory/projects.md（当前项目）
   ↓
5. 读取最近 3 天的日志（了解近期上下文）
   ↓
6. 向用户确认记忆加载完成
```

### 旧模型退出时

```
1. 总结本次会话的重要信息
   ↓
2. 使用 memory_manager.py 写入记忆
   ↓
3. 更新 memory/projects.md（如有进度变化）
   ↓
4. 告知用户"记忆已保存"
```

---

## 🧹 记忆维护

### 每日维护（Heartbeat 任务）

- 检查当日日志是否已创建
- 审查是否有重要信息需要提炼至长期记忆

### 每周维护

```bash
# 清理 30 天前的日志
python3 memory_manager.py cleanup

# 检查记忆系统状态
python3 memory_manager.py status
```

### 每月维护

- 审查 `MEMORY.md`，删除过时信息
- 归档旧的项目文件
- 向用户汇报记忆系统使用情况

---

## ⚠️ 注意事项

### 安全红线

- **不要**在群聊/共享会话中读取 MEMORY.md（可能泄露用户隐私）
- **不要**将记忆内容发送给第三方
- **不要**在未确认的情况下删除记忆文件

### 最佳实践

- ✅ 每次会话开始前读取记忆
- ✅ 重要信息立即写入，不要依赖" mental notes"
- ✅ 定期向用户确认记忆准确性
- ✅ 模型切换时主动告知"我已读取之前的记忆"

---

## 🛠️ 故障排查

| 问题 | 解决方案 |
|------|----------|
| 找不到记忆文件 | 运行 `memory_manager.py status` 检查 |
| 记忆内容过时 | 手动编辑对应文件，或运行 `cleanup` |
| 新模型不知道之前的对话 | 检查是否按流程读取了记忆文件 |
| 记忆文件太多 | 运行 `cleanup` 清理 30 天前的日志 |

---

## 📞 联系维护者

如记忆系统出现问题，请联系用户（船长/老大）进行修复。

---

*最后更新：2026-03-13 | 皮皮虾维护 🦐*