smart-agent-memory

# Smart Agent Memory 🧠 v2.0

**跨平台 Agent 长期记忆系统** — 分层上下文供给 + Skill经验记忆 + 温度模型 + 自动归档。

## ⚡ 核心原则：分层加载，按需供给

> **绝对不要全量加载记忆！** 先读索引，再按需钻取。这是省 token 的关键。

### 记忆使用流程（每次需要记忆时）

```
1. index    → 读取精简索引（总览，<500 tokens）
2. 判断     → 根据当前任务决定需要哪部分记忆
3. context  → 按 tag/skill/时间 加载具体上下文
4. 行动     → 基于加载的上下文执行任务
```

### Skill 经验记忆流程（工具调用后）

```
工具调用成功/踩坑 → remember "经验总结" --skill <skill-name>
下次调用该工具前 → skill-mem <skill-name> 加载经验
```

## CLI Reference

```bash
CLI=~/.openclaw/skills/smart-agent-memory/scripts/memory-cli.js

# ★ 分层上下文（核心，优先使用）
node $CLI index                              # 精简记忆索引（先读这个！）
node $CLI context --tag <tag>                # 按标签加载上下文
node $CLI context --skill <skill-name>       # 按 Skill 加载经验+相关事实
node $CLI context --days 7                   # 最近 N 天的记忆
node $CLI context --entity-type person       # 按实体类型加载

# ★ Skill 经验记忆
node $CLI remember "该API时间参数必须用ISO格式" --skill api-tool
node $CLI skill-mem <skill-name>             # 读取某 Skill 的经验
node $CLI skill-list                         # 列出所有有经验记忆的 Skill

# 基础记忆操作
node $CLI remember <content> [--tags t1,t2] [--skill name] [--source conversation]
node $CLI recall <query> [--limit 10]
node $CLI forget <id>
node $CLI facts [--tags t1] [--limit 50]

# 教训与实体
node $CLI learn --action "..." --context "..." --outcome positive --insight "..."
node $CLI lessons [--context topic]
node $CLI entity "Alex" person --attr role=CTO
node $CLI entities [--type person]

# ★ 会话生命周期（模拟 mem9 自动钩子）
node $CLI session-start                      # 对话开场：加载记忆概览+最近上下文（一个命令搞定）
node $CLI session-end "本次讨论了XX，决定了YY"  # 对话结束：存会话摘要

# 维护
node $CLI gc [--days 30]                     # 归档冷数据
node $CLI refl...

# 🧠 Smart Agent Memory — 跨平台 Agent 长期记忆系统

> 融合两大开源记忆方案的精华，打造**温度模型 + 结构化存储 + 自动归档 + 知识提炼**的一站式 Agent 记忆引擎。

**纯 Node.js 原生模块，零外部依赖。Windows / macOS / Linux 通用。Node.js >= 22.5 自动启用 SQLite + FTS5。**

---

## 📖 目录

- [项目背景：为什么要做这个？](#-项目背景为什么要做这个)
- [核心优势](#-核心优势)
- [快速开始](#-快速开始)
- [完整命令手册](#-完整命令手册)
- [双层存储架构](#-双层存储架构)
- [温度模型](#-温度模型)
- [智能后端：JSON 与 SQLite](#-智能后端json-与-sqlite)
- [与 OpenClaw 深度集成](#-与-openclaw-深度集成)
- [Agent 每日工作流](#-agent-每日工作流)
- [系统要求](#-系统要求)
- [文件结构](#-文件结构)
- [常见问题](#-常见问题)
- [致谢与来源](#-致谢与来源)

---

## 💡 项目背景：为什么要做这个？

社区里已有两个 Agent 记忆方案，各有优缺点：

### agent-memory-system（by 阿福）

**理念：文件即记忆，日记本方式。**

| 优点 ✅ | 缺点 ❌ |
|---------|---------|
| 温度模型（热/温/冷三级分类） | 只支持 Linux/Mac（bash 脚本） |
| 自动归档 GC（冷数据按月归档） | 依赖 rsync、crontab |
| 夜间反思（每日健康报告） | 无结构化查询能力 |
| 技能提炼（教训 → SKILL.md） | 无实体追踪 |
| Markdown 人可读，QMD 直接搜索 | 搜索只能靠外部工具 |
| 与 OpenClaw workspace 深度融合 | — |

### agent-memory（by ClawHub 社区）

**理念：数据库驱动，程序化 API。**

| 优点 ✅ | 缺点 ❌ |
|---------|---------|
| Fact / Lesson / Entity 三层模型 | 需要 Python 运行环境 |
| SQLite + FTS5 精准全文搜索 | 数据在数据库里，人不可读 |
| 置信度（confidence）模型 | 与 OpenClaw 原生工作流割裂 |
| 访问计数 + 最后访问时间追踪 | 无温度模型，无自动归档 |
| 置换链（supersede）保留历史 | 无夜间反思，无技能提炼 |
| 实体属性自动合并 | — |
| 数据导出（JSON export） | — |

### Smart Agent Memory 的答案：全都要

**把两者的优点合并，缺点全部干掉：**

- ✅ 从 agent-memory-system 继承：温度模型、自动归档、夜间反思、技能提炼、Markdown 文件驱动
- ✅ 从 agent-memory 继承：Fact/Lesson/Entity 结构化存储、全文搜索、置信度、访问追踪、置换链、实体追踪
- 🆕 **新增双层写入*...