介绍
# Elite Longterm Memory 🧠
**面向 AI 代理的终极记忆系统。** 将 6 种经过验证的方法结合到一个无懈可击的架构中。
永不丢失上下文。永不遗忘决策。永不重复错误。
## 架构概览
``` ┌─────────────────────────────────────────────────────────────────┐ │ ELITE LONGTERM MEMORY │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ HOT RAM │ │ WARM STORE │ │ COLD STORE │ │ │ │ │ │ │ │ │ │ │ │ SESSION- │ │ LanceDB │ │ Git-Notes │ │ │ │ STATE.md │ │ Vectors │ │ Knowledge │ │ │ │ │ │ │ │ Graph │ │ │ │ (survives │ │ (semantic │ │ (permanent │ │ │ │ compaction)│ │ search) │ │ decisions) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌─────────────┐ │ │ │ MEMORY.md │ ← Curated long-term │ │ │ + daily/ │ (human-readable) │ │ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ SuperMemory │ ← Cloud backup (optional) │ │ │ API │ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ```
## 5 个记忆层
### 第 1 层：热 RAM (SESSION-STATE.md) **来源：bulletproof-memory**
在压缩后仍能保留的活跃工作记忆。预写日志（Write-Ahead Log）协议。
```markdown # SESSION-STATE.md — Active Working Memory
## Current Task [What we're working on RIGHT NOW]
## Key Context - User preference: ... - Decision made: ... - Blocker: ...
## Pending Actions - [ ] ... ```
**规则：** 在响应之前写入。由用户输入触发，而非代理记忆。
### 第 2 层：温存储 (LanceDB 向量) **来源：lancedb-memory**
跨所有记忆的语义搜索。自动召回会注入相关上下文。
```bash # Auto-recall (happens automatically) memory_recall query="project status" limit=5
# Manual store memory_store text="User prefers dark mode" category="preference" importance=0.9 ```
### 第 3 层：冷存储 (Git-Notes 知识图谱) **来源：git-notes-memory**
结构化的决策、学习和上下文。感知分支。
```bash # Store a decision (SILENT - never announce) python3 memory.py -p $DIR remember '{"type":"decision","content":"Use React for frontend"}' -t tech -i h
# Retrieve context python3 memory.py -p $DIR get "frontend" ```
### 第 4 层：精选归档 (MEMORY.md + daily/) **来源：OpenClaw 原生**
人类可读的长期记忆。每日日志 + 提炼的智慧。
``` workspace/ ├── MEMORY.md # Curated long-term (the good stuff) └── memory/ ├── 2026-01-30.md # Daily log ├── 2026-01-29.md └── topics/ # Topic-specific files ```
### 第 5 层：云端备份 (SuperMemory) — 可选 **来源：supermemory**
跨设备同步。与您的知识库聊天。
```bash export SUPERMEMORY_API_KEY="your-key" supermemory add "Important context" supermemory search "what did we decide about..." ```
### 第 6 层：自动提取 — 推荐 **新增：自动事实提取**
Mem0 自动从对话中提取事实。减少 80% 的 token。
```bash npm install mem0ai export MEM0_API_KEY="your-key" ```
```javascript const { MemoryClient } = require('mem0ai'); const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
// Conversations auto-extract facts await client.add(messages, { user_id: "user123" });
// Retrieve relevant memories const memories = await client.search(query, { user_id: "user123" }); ```
优势： - 自动提取偏好、决策、事实 - 去重并更新现有记忆 - 相比原始历史记录减少 80% 的 token - 跨会话自动工作
## 快速设置
### 1. 创建 SESSION-STATE.md (热 RAM)
```bash cat > SESSION-STATE.md << 'EOF' # SESSION-STATE.md — Active Working Memory
This file is the agent's "RAM" — survives compaction, restarts, distractions.
## Current Task [None]
## Key Context [None yet]
## Pending Actions - [ ] None
## Recent Decisions [None yet]
--- *Last updated: [timestamp]* EOF ```
### 2. 启用 LanceDB (温存储)
在 `~/.openclaw/openclaw.json` 中：
```json { "memorySearch": { "enabled": true, "provider": "openai", "sources": ["memory"], "minScore": 0.3, "maxResults": 10 }, "plugins": { "entries": { "memory-lancedb": { "enabled": true, "config": { "autoCapture": false, "autoRecall": true, "captureCategories": ["preference", "decision", "fact"], "minImportance": 0.7 } } } } } ```
### 3. 初始化 Git-Notes (冷存储)
```bash cd ~/clawd git init # if not already python3 skills/git-notes-memory/memory.py -p . sync --start ```
### 4. 验证 MEMORY.md 结构
```bash # Ensure you have: # - MEMORY.md in workspace root # - memory/ folder for daily logs mkdir -p memory ```
### 5. （可选）设置 SuperMemory
```bash export SUPERMEMORY_API_KEY="your-key" # Add to ~/.zshrc for persistence ```
## 代理指令
### 会话开始时 1. 读取 SESSION-STATE.md —— 这是您的热上下文 2. 运行 `memory_search` 以获取相关的先前上下文 3. 检查 memory/YYYY-MM-DD.md 以获取近期活动
### 对话期间 1. **用户提供了具体细节？** → 在响应之前写入 SESSION-STATE.md 2. **做出了重要决策？** → 存储到 Git-Notes 中（静默） 3. **表达了偏好？** → 使用 importance=0.9 执行 `memory_store`
### 会话结束时 1. 用最终状态更新 SESSION-STATE.md 2. 如果值得长期保留，将重要项目移至 MEMORY.md 3. 在 memory/YYYY-MM-DD.md 中创建/更新每日日志
### 记忆卫生（每周） 1. 检查 SESSION-STATE.md —— 归档已完成的任务 2. 检查 LanceDB 中的垃圾：`memory_recall query="*" limit=50` 3. 清除无关向量：`memory_forget id=<id>` 4. 将每日日志整合到 MEMORY.md 中
## WAL 协议（关键）
**预写日志（Write-Ahead Log）：** 在响应*之前*写入状态，而不是之后。
| 触发条件 | 动作 | |---------|--------| | 用户陈述偏好 | 写入 SESSION-STATE.md → 然后响应 | | 用户做出决策 | 写入 SESSION-STATE.md → 然后响应 | | 用户给出截止日期 | 写入 SESSION-STATE.md → 然后响应 | | 用户纠正您 | 写入 SESSION-STATE.md → 然后响应 |
**为什么？** 如果您先响应，然后在保存之前崩溃/被压缩，上下文就会丢失。WAL 确保持久性。
## 示例工作流
``` User: "Let's use Tailwind for this project, not vanilla CSS"
Agent (internal): 1. Write to SESSION-STATE.md: "Decision: Use Tailwind, not vanilla CSS" 2. Store in Git-Notes: decision about CSS framework 3. memory_store: "User prefers Tailwind over vanilla CSS" importance=0.9 4. THEN respond: "Got it — Tailwind it is..." ```
## 维护命令
```bash # Audit vector memory memory_recall query="*" limit=50
# Clear all vectors (nuclear option) rm -rf ~/.openclaw/memory/lancedb/ openclaw gateway restart
# Export Git-Notes python3 memory.py -p . export --format json > memories.json
# Check memory health du -sh ~/.openclaw/memory/ wc -l MEMORY.md ls -la memory/ ```
## 记忆为何失效
了解根本原因有助于您修复它们：
| 失效模式 | 原因 | 修复方法 | |--------------|-------|-----| | 遗忘一切 | `memory_search` 已禁用 | 启用 + 添加 OpenAI 密钥 | | 文件未加载 | 代理跳过读取记忆 | 添加到 AGENTS.md 规则中 | | 未捕获事实 | 无自动提取 | 使用 Mem0 或手动记录 | | 子代理隔离 | 不继承上下文 | 在任务提示中传递上下文 | | 重复错误 | 未记录教训 | 写入 memory/lessons.md |
## 解决方案（按工作量排序）
### 1. 快速见效：启用 memory_search
如果您拥有 OpenAI 密钥，请启用语义搜索：
```bash openclaw configure --section web ```
这将启用对 MEMORY.md + memory/*.md 文件的向量搜索。
### 2. 推荐：Mem0 集成
从对话中自动提取事实。减少 80% 的 token。
```bash npm install mem0ai ```
```javascript const { MemoryClient } = require('mem0ai');
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });
// Auto-extract and store await client.add([ { role: "user", content: "I prefer Tailwind over vanilla CSS" } ], { user_id: "ty" });
// Retrieve relevant memories const memories = await client.search("CSS preferences", { user_id: "ty" }); ```
### 3. 更好的文件结构（无依赖）
``` memory/ ├── projects/ │ ├── strykr.md │ └── taska.md ├── people/ │ └── contacts.md ├── decisions/ │ └── 2026-01.md ├── lessons/ │ └── mistakes.md └── preferences.md ```
保持 MEMORY.md 为摘要（<5KB），链接到详细文件。
## 即时修复检查清单
| 问题 | 修复方法 | |---------|-----| | 遗忘偏好 | 将 `## Preferences` 部分添加到 MEMORY.md | | 重复错误 | 将每个错误记录到 `memory/lessons.md` | | 子代理缺乏上下文 | 在生成任务提示中包含关键上下文 | | 遗忘近期工作 | 严格的每日文件纪律 | | 记忆搜索不工作 | 检查是否设置了 `OPENAI_API_KEY` |
## 故障排除
**代理在对话中持续遗忘：** → SESSION-STATE.md 未被更新。检查 WAL 协议。
**注入了无关记忆：** → 禁用 autoCapture，提高 minImportance 阈值。
**记忆过大，召回缓慢：** → 运行卫生清理：清除旧向量，归档每日日志。
**Git-Notes 未持久化：** → 运行 `git notes push` 与远程同步。
**memory_search 无返回：** → 检查 OpenAI API 密钥：`echo $OPENAI_API_KEY` → 验证 openclaw.json 中启用了 memorySearch
---
## 链接
- bulletproof-memory: https://clawdhub.com/skills/bulletproof-memory - lancedb-memory: https://clawdhub.com/skills/lancedb-memory - git-notes-memory: https://clawdhub.com/skills/git-notes-memory - memory-hygiene: https://clawdhub.com/skills/memory-hygiene - supermemory: https://clawdhub.com/skills/supermemory
---
*由 [@NextXFrontier](https://x.com/NextXFrontier) 构建 — Next Frontier AI 工具包的一部分*