Elite Longterm Memory 🧠
The ultimate memory system for AI agents. Combines 6 proven approaches into one bulletproof architecture.
Never lose context. Never forget decisions. Never repeat mistakes.
Architecture Overview
CODEBLOCK0
The 5 Memory Layers
Layer 1: HOT RAM (SESSION-STATE.md)
From: bulletproof-memory
Active working memory that survives compaction. Write-Ahead Log protocol.
CODEBLOCK1
Rule: Write BEFORE responding. Triggered by user input, not agent memory.
Layer 2: WARM STORE (LanceDB Vectors)
From: lancedb-memory
Semantic search across all memories. Auto-recall injects relevant context.
CODEBLOCK2
Layer 3: COLD STORE (Git-Notes Knowledge Graph)
From: git-notes-memory
Structured decisions, learnings, and context. Branch-aware.
CODEBLOCK3
Layer 4: CURATED ARCHIVE (MEMORY.md + daily/)
From: OpenClaw native
Human-readable long-term memory. Daily logs + distilled wisdom.
CODEBLOCK4
Layer 5: CLOUD BACKUP (SuperMemory) — Optional
From: supermemory
Cross-device sync. Chat with your knowledge base.
CODEBLOCK5
Layer 6: AUTO-EXTRACTION (Mem0) — Recommended
NEW: Automatic fact extraction
Mem0 automatically extracts facts from conversations. 80% token reduction.
CODEBLOCK6
CODEBLOCK7
Benefits:
- - Auto-extracts preferences, decisions, facts
- Deduplicates and updates existing memories
- 80% reduction in tokens vs raw history
- Works across sessions automatically
Quick Setup
1. Create SESSION-STATE.md (Hot RAM)
CODEBLOCK8
2. Enable LanceDB (Warm Store)
In ~/.openclaw/openclaw.json:
CODEBLOCK9
3. Initialize Git-Notes (Cold Store)
CODEBLOCK10
4. Verify MEMORY.md Structure
CODEBLOCK11
5. (Optional) Setup SuperMemory
CODEBLOCK12
Agent Instructions
On Session Start
- 1. Read SESSION-STATE.md — this is your hot context
- Run
memory_search for relevant prior context - Check memory/YYYY-MM-DD.md for recent activity
During Conversation
- 1. User gives concrete detail? → Write to SESSION-STATE.md BEFORE responding
- Important decision made? → Store in Git-Notes (SILENTLY)
- Preference expressed? →
memory_store with importance=0.9
On Session End
- 1. Update SESSION-STATE.md with final state
- Move significant items to MEMORY.md if worth keeping long-term
- Create/update daily log in memory/YYYY-MM-DD.md
Memory Hygiene (Weekly)
- 1. Review SESSION-STATE.md — archive completed tasks
- Check LanceDB for junk: INLINECODE3
- Clear irrelevant vectors: INLINECODE4
- Consolidate daily logs into MEMORY.md
The WAL Protocol (Critical)
Write-Ahead Log: Write state BEFORE responding, not after.
| Trigger | Action |
|---|
| User states preference | Write to SESSION-STATE.md → then respond |
| User makes decision |
Write to SESSION-STATE.md → then respond |
| User gives deadline | Write to SESSION-STATE.md → then respond |
| User corrects you | Write to SESSION-STATE.md → then respond |
Why? If you respond first and crash/compact before saving, context is lost. WAL ensures durability.
Example Workflow
CODEBLOCK13
Maintenance Commands
CODEBLOCK14
Why Memory Fails
Understanding the root causes helps you fix them:
| Failure Mode | Cause | Fix |
|---|
| Forgets everything | INLINECODE5 disabled | Enable + add OpenAI key |
| Files not loaded |
Agent skips reading memory | Add to AGENTS.md rules |
| Facts not captured | No auto-extraction | Use Mem0 or manual logging |
| Sub-agents isolated | Don't inherit context | Pass context in task prompt |
| Repeats mistakes | Lessons not logged | Write to memory/lessons.md |
Solutions (Ranked by Effort)
1. Quick Win: Enable memory_search
If you have an OpenAI key, enable semantic search:
CODEBLOCK15
This enables vector search over MEMORY.md + memory/*.md files.
2. Recommended: Mem0 Integration
Auto-extract facts from conversations. 80% token reduction.
CODEBLOCK16
CODEBLOCK17
3. Better File Structure (No Dependencies)
CODEBLOCK18
Keep MEMORY.md as a summary (<5KB), link to detailed files.
Immediate Fixes Checklist
| Problem | Fix |
|---|
| Forgets preferences | Add ## Preferences section to MEMORY.md |
| Repeats mistakes |
Log every mistake to
memory/lessons.md |
| Sub-agents lack context | Include key context in spawn task prompt |
| Forgets recent work | Strict daily file discipline |
| Memory search not working | Check
OPENAI_API_KEY is set |
Troubleshooting
Agent keeps forgetting mid-conversation:
→ SESSION-STATE.md not being updated. Check WAL protocol.
Irrelevant memories injected:
→ Disable autoCapture, increase minImportance threshold.
Memory too large, slow recall:
→ Run hygiene: clear old vectors, archive daily logs.
Git-Notes not persisting:
→ Run git notes push to sync with remote.
memory_search returns nothing:
→ Check OpenAI API key: echo $OPENAI_API_KEY
→ Verify memorySearch enabled in openclaw.json
Links
- - 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
Built by @NextXFrontier — Part of the Next Frontier AI toolkit精英长期记忆 🧠
AI代理的终极记忆系统。 将6种经过验证的方法整合到一个坚不可摧的架构中。
永不丢失上下文。永不忘记决策。永不重复错误。
架构概览
┌─────────────────────────────────────────────────────────────────┐
│ 精英长期记忆系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 热内存 │ │ 温存储 │ │ 冷存储 │ │
│ │ │ │ │ │ │ │
│ │ 会话状态.md │ │ LanceDB │ │ Git笔记 │ │
│ │ │ │ 向量 │ │ 知识图谱 │ │
│ │ (可抵御压缩)│ │ (语义搜索) │ │ (永久决策) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ MEMORY.md │ ← 精选长期记忆 │
│ │ + daily/ │ (人类可读) │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ SuperMemory │ ← 云备份 (可选) │
│ │ API │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
5层记忆架构
第1层：热内存 (SESSION-STATE.md)
来源：bulletproof-memory
可抵御压缩的活动工作内存。预写日志协议。
markdown
SESSION-STATE.md — 活动工作内存
当前任务
[我们正在处理的事情]
关键上下文
- - 用户偏好：...
- 已做决策：...
- 阻塞项：...
待处理操作
规则： 在响应前写入。由用户输入触发，而非代理记忆。
第2层：温存储 (LanceDB向量)
来源：lancedb-memory
跨所有记忆的语义搜索。自动召回注入相关上下文。
bash
自动召回（自动发生）
memory_recall query=项目状态 limit=5
手动存储
memory_store text=用户偏好深色模式 category=偏好 importance=0.9
第3层：冷存储 (Git笔记知识图谱)
来源：git-notes-memory
结构化决策、学习经验和上下文。分支感知。
bash
存储决策（静默 - 从不宣布）
python3 memory.py -p $DIR remember {type:decision,content:使用React作为前端} -t tech -i h
检索上下文
python3 memory.py -p $DIR get 前端
第4层：精选归档 (MEMORY.md + daily/)
来源：OpenClaw原生
人类可读的长期记忆。每日日志 + 提炼的智慧。
workspace/
├── MEMORY.md # 精选长期记忆（精华内容）
└── memory/
├── 2026-01-30.md # 每日日志
├── 2026-01-29.md
└── topics/ # 主题特定文件
第5层：云备份 (SuperMemory) — 可选
来源：supermemory
跨设备同步。与知识库对话。
bash
export SUPERMEMORYAPIKEY=your-key
supermemory add 重要上下文
supermemory search 我们之前关于...做了什么决定
第6层：自动提取 (Mem0) — 推荐
新增：自动事实提取
Mem0自动从对话中提取事实。减少80%的token消耗。
bash
npm install mem0ai
export MEM0APIKEY=your-key
javascript
const { MemoryClient } = require(mem0ai);
const client = new MemoryClient({ apiKey: process.env.MEM0APIKEY });
// 对话自动提取事实
await client.add(messages, { user_id: user123 });
// 检索相关记忆
const memories = await client.search(query, { user_id: user123 });
优势：
- - 自动提取偏好、决策、事实
- 去重并更新现有记忆
- 相比原始历史减少80%的token消耗
- 跨会话自动工作
快速设置
1. 创建 SESSION-STATE.md（热内存）
bash
cat > SESSION-STATE.md << EOF
SESSION-STATE.md — 活动工作内存
此文件是代理的内存——可抵御压缩、重启和干扰。
当前任务
[无]
关键上下文
[暂无]
待处理操作
近期决策
[暂无]
最后更新：[时间戳]
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笔记（冷存储）
bash
cd ~/clawd
git init # 如果尚未初始化
python3 skills/git-notes-memory/memory.py -p . sync --start
4. 验证 MEMORY.md 结构
bash
确保你有：
- 工作区根目录下的 MEMORY.md
- 用于每日日志的 memory/ 文件夹
mkdir -p memory
5. （可选）设置 SuperMemory
bash
export SUPERMEMORYAPIKEY=your-key
添加到 ~/.zshrc 以持久化
代理指令
会话启动时
- 1. 读取 SESSION-STATE.md — 这是你的热上下文
- 运行 memory_search 查找相关先前上下文
- 检查 memory/YYYY-MM-DD.md 了解近期活动
对话期间
- 1. 用户提供了具体细节？ → 在响应前写入 SESSION-STATE.md
- 做出了重要决策？ → 存储到 Git笔记（静默执行）
- 表达了偏好？ → 使用 importance=0.9 的 memory_store
会话结束时
- 1. 用最终状态更新 SESSION-STATE.md
- 如果值得长期保留，将重要项目移至 MEMORY.md
- 在 memory/YYYY-MM-DD.md 中创建/更新每日日志
记忆维护（每周）
- 1. 审查 SESSION-STATE.md — 归档已完成任务
- 检查 LanceDB 中的垃圾数据：memoryrecall query=* limit=50
- 清除无关向量：memoryforget id=
- 将每日日志整合到 MEMORY.md
WAL协议（关键）
预写日志： 在响应前写入状态，而非响应后。
| 触发条件 | 操作 |
|---|
| 用户陈述偏好 | 写入 SESSION-STATE.md → 然后响应 |
| 用户做出决策 |
写入 SESSION-STATE.md → 然后响应 |
| 用户给出截止日期 | 写入 SESSION-STATE.md → 然后响应 |
| 用户纠正你 | 写入 SESSION-STATE.md → 然后响应 |
为什么？ 如果你先响应然后在保存前崩溃/压缩，上下文就会丢失。WAL确保持久性。
示例工作流
用户：这个项目我们用Tailwind，不用原生CSS
代理（内部）：
- 1. 写入 SESSION-STATE.md：决策：使用Tailwind，不用原生CSS
- 存储到 Git笔记：关于CSS框架的决策
- memory_store：用户偏好Tailwind而非原生CSS importance=0.9
- 然后响应：收到——就用Tailwind...
维护命令
bash
审计向量记忆
memory_recall query=* limit=50
清除所有向量（核选项）
rm -rf ~/.opencl
