# openclaw-memory-system

**Repository Path**: antwu/openclaw-memory-system

## Basic Information

- **Project Name**: openclaw-memory-system
- **Description**: OpenClaw 记忆系统 2.0 - 正式版
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenClaw 记忆系统 2.0 - OpenViking 风格增强

> 🦞 让 OpenClaw 拥有超强记忆，越用越聪明！

[![OpenClaw](https://img.shields.io/badge/OpenClaw-Agent-blue)](https://openclaw.ai)
[![Python](https://img.shields.io/badge/Python-3.10+-green)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

## 📖 项目简介

本项目为 **OpenClaw AI Agent** 实现了基于 **OpenViking 设计理念** 的分级记忆系统，通过文件系统范式统一管理上下文，支持 L0/L1/L2 三层分级加载，显著降低 Token 消耗（约 60%），同时保持优秀的检索效果。

### ✨ 核心特性

- 🎯 **分级记忆架构** - L0(即时)/L1(短期)/L2(长期) 三层结构，按需加载
- 🔍 **关键词搜索** - 快速检索记忆内容，支持跨层级搜索
- 📦 **自动归档** - 30 天前的记忆自动归档，保持系统精简
- 📊 **访问轨迹** - 记录每次记忆访问，支持后续分析优化
- 🛠️ **命令行工具** - 提供完整的记忆管理 CLI 工具
- 📚 **完整文档** - 架构说明 + 快速上手指南

## 🚀 快速开始

### 环境要求

- Python 3.10+
- OpenClaw 已安装并配置
- 工作区：`C:\Users\Administrator\.openclaw\workspace`

### 安装使用

记忆系统已集成到 OpenClaw 工作区，无需额外安装。

#### 1️⃣ 查看记忆系统状态

```bash
cd C:\Users\Administrator\.openclaw\workspace
python tools/memory_manager.py status
```

**输出示例**：
```json
{
  "L2_longterm": {"size_kb": 4.14},
  "L1_shortterm": {"daily_notes_count": 14, "recent_7_days": 6},
  "archive": {"archived_notes_count": 0},
  "access_log": {"entries": 18}
}
```

#### 2️⃣ 搜索记忆

```bash
# 搜索所有层级
python tools/memory_manager.py search "股票分析"

# 只搜索长期记忆 (L2)
python tools/memory_manager.py search "模型配置" --level L2

# 只搜索日常记忆 (L1)
python tools/memory_manager.py search "系统优化" --level L1
```

#### 3️⃣ 加载会话上下文

```bash
# 只加载长期记忆（默认，获取用户偏好）
python tools/memory_manager.py load-context --level L2

# 加载长期 + 最近 7 天日常记忆
python tools/memory_manager.py load-context --level L1+L2 --days 7

# 只加载日常记忆
python tools/memory_manager.py load-context --level L1 --days 3
```

#### 4️⃣ 压缩日常记忆

```bash
python tools/memory_manager.py compress --date 2026-03-12
```

#### 5️⃣ 归档旧记忆

```bash
# 归档 30 天前的记忆
python tools/memory_manager.py archive --older-than 30
```

## 📐 架构设计

### 三层分级结构

```
┌─────────────────────────────────────────────────────────┐
│  L0 - 即时上下文 (Hot Context)                          │
│  - 当前会话消息                                         │
│  - 最近 5 条对话                                        │
│  Token 预算：~2000                                      │
└─────────────────────────────────────────────────────────┘
                          ↓ 需要时加载
┌─────────────────────────────────────────────────────────┐
│  L1 - 短期记忆 (Working Memory)                         │
│  - 最近 7 天的 daily notes                              │
│  - 当前活跃项目上下文                                   │
│  Token 预算：~8000                                      │
└─────────────────────────────────────────────────────────┘
                          ↓ 需要时加载
┌─────────────────────────────────────────────────────────┐
│  L2 - 长期记忆 (Long-term Memory)                       │
│  - MEMORY.md (curated 重要记忆)                         │
│  - 用户画像/偏好/边界                                   │
│  Token 预算：~4000                                      │
└─────────────────────────────────────────────────────────┘
```

### 文件系统布局

```
workspace/
├── MEMORY.md                      # L2 - 长期记忆（核心）
├── memory/
│   ├── YYYY-MM-DD.md              # L1 - 日常记忆（原始日志）
│   ├── projects/                  # 项目上下文
│   └── archive/                   # 归档记忆（>30 天）
├── docs/
│   ├── MEMORY_ARCHITECTURE.md     # 完整架构说明
│   └── MEMORY_QUICKSTART.md       # 快速上手指南
└── tools/
    └── memory_manager.py          # 记忆管理工具
```

### 记忆流动

```
会话进行中 → L0 (即时上下文)
    ↓ 会话结束
写入 daily note → L1 (短期记忆)
    ↓ 心跳检查（每 30 分钟）
提取重要事件 → L2 (长期记忆)
    ↓ 每周维护
压缩/归档旧记忆 → Archive
```

## 🛠️ 工具命令参考

### memory_manager.py 完整命令

| 命令 | 说明 | 示例 |
|------|------|------|
| `status` | 查看记忆系统状态 | `python tools/memory_manager.py status` |
| `search` | 搜索记忆 | `python tools/memory_manager.py search "关键词"` |
| `compress` | 压缩日常记忆 | `python tools/memory_manager.py compress --date 2026-03-12` |
| `archive` | 归档旧记忆 | `python tools/memory_manager.py archive --older-than 30` |
| `load-context` | 加载分级上下文 | `python tools/memory_manager.py load-context --level L1+L2` |

### search 命令参数

```bash
python tools/memory_manager.py search "关键词" [--level L1|L2|all]
```

- `--level L1`: 只搜索日常记忆
- `--level L2`: 只搜索长期记忆
- `--level all`: 搜索所有层级（默认）

### load-context 命令参数

```bash
python tools/memory_manager.py load-context [--level L1|L2|L1+L2] [--days 7]
```

- `--level L2`: 只加载长期记忆（适合快速获取用户偏好）
- `--level L1+L2`: 加载长期 + 短期记忆（适合复杂任务）
- `--days`: 加载最近 N 天的日常记忆（默认 7）

## 📊 性能指标

| 指标 | 目标 | 实测 |
|------|------|------|
| L2 加载时间 | <100ms | ~50ms ✅ |
| L1 (7 天) 加载时间 | <500ms | ~200ms ✅ |
| 记忆检索准确率 | >90% | 待测试 |
| Token 节省率 | >60% | ~60% ✅ |

## 🔄 自动化维护

### 心跳检查自动执行

每次心跳（30 分钟）会自动：
- ✅ 记录记忆访问轨迹到 `memory/access_log.jsonl`
- ✅ 检查是否需要更新 daily note

### 每周维护（建议周日执行）

```bash
# 1. 归档 30 天前的记忆
python tools/memory_manager.py archive --older-than 30

# 2. 查看状态确认
python tools/memory_manager.py status
```

### 每月维护（建议每月 1 号）

- 审查 `MEMORY.md` 是否有冗余条目
- 检查 `memory/access_log.jsonl` 访问模式
- 清理过大的归档文件

## 💡 最佳实践

### ✅ 推荐做法

1. **会话开始**：加载 L2 长期记忆获取用户偏好
   ```bash
   python tools/memory_manager.py load-context --level L2
   ```

2. **复杂任务**：加载 L1+L2 获取完整上下文
   ```bash
   python tools/memory_manager.py load-context --level L1+L2 --days 7
   ```

3. **快速查找**：使用搜索而非浏览
   ```bash
   python tools/memory_manager.py search "关键词"
   ```

4. **定期归档**：保持 L1 精简
   ```bash
   python tools/memory_manager.py archive --older-than 30
   ```

### ❌ 避免做法

1. ❌ 不要一次性加载所有记忆（Token 浪费）
2. ❌ 不要手动编辑 `access_log.jsonl`（影响轨迹分析）
3. ❌ 不要在 MEMORY.md 记录琐碎细节（保持 curated）
4. ❌ 不要删除原始 daily notes（至少保留 7 天）

## 📚 文档说明

| 文档 | 说明 |
|------|------|
| [MEMORY_ARCHITECTURE.md](docs/MEMORY_ARCHITECTURE.md) | 完整架构设计文档 |
| [MEMORY_QUICKSTART.md](docs/MEMORY_QUICKSTART.md) | 5 分钟快速上手指南 |
| [MEMORY.md](MEMORY.md) | 长期记忆（L2）内容 |
| [HEARTBEAT.md](HEARTBEAT.md) | 心跳任务配置 |

## 🎯 与 OpenViking 对比

| 特性 | OpenViking | 本实现 |
|------|------------|--------|
| 分级加载 | ✅ | ✅ |
| 自动压缩 | ✅ | ✅ (简化版) |
| 检索轨迹 | ✅ | ✅ (简化版) |
| 文件系统范式 | ✅ | ✅ |
| Go/C++ 依赖 | ❌ 需要 | ✅ 无需 |
| 安装复杂度 | 高 | 低（纯 Python） |
| 即时可用 | ❌ | ✅ |

> 💡 本实现借鉴 OpenViking 设计理念，采用轻量级方案，无需复杂依赖即可快速部署使用。

## 🚧 后续改进方向

### 短期（1-2 周）
- [ ] 修复编码问题（统一 UTF-8）
- [ ] 添加简单缓存（内存字典）
- [ ] 集成到 OpenClaw 自动加载流程

### 中期（1 个月）
- [ ] 接入本地嵌入模型（语义搜索）
- [ ] LLM 辅助压缩（用云端模型总结）
- [ ] 添加记忆引用标记（手动建立关联）

### 长期
- [ ] 可视化检索轨迹（Web 界面）
- [ ] 记忆热度分析（自动归档低频记忆）

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [OpenClaw](https://openclaw.ai) - AI Agent 框架
- [OpenViking](https://github.com/volcengine/OpenViking) - 上下文数据库设计灵感
- [MemOS](https://github.com/MemTensor/MemOS) - 记忆管理系统参考

## 📬 联系方式

- **作者**: 澜宝 (ai-king)
- **邮箱**: lanb2026@163.com
- **Gitee**: https://gitee.com/ai-king

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star！**

[📚 查看完整文档](docs/MEMORY_ARCHITECTURE.md) | [🚀 快速上手](docs/MEMORY_QUICKSTART.md)

</div>