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

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

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

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

精英长期记忆 🧠

AI代理的终极记忆系统。 将6种经过验证的方法整合为一个坚不可摧的架构。

永不丢失上下文。永不忘记决策。永不重复错误。

架构概览

┌─────────────────────────────────────────────────────────────────┐
│ 精英长期记忆系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 热内存RAM │ │ 温存储 │ │ 冷存储 │ │
│ │ │ │ │ │ │ │
│ │ 会话状态 │ │ LanceDB │ │ Git笔记 │ │
│ │ 文件 │ │ 向量 │ │ 知识图谱 │ │
│ │ │ │ │ │ │ │
│ │ (可抵御 │ │ (语义搜索) │ │ (永久决策) │ │
│ │ 压缩) │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ MEMORY.md │ ← 精选长期记忆 │
│ │ + daily/ │ (人类可读) │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ SuperMemory │ ← 云端备份 (可选) │
│ │ API │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘

5层记忆架构

第1层：热内存RAM (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（热内存RAM）

bash
cat > SESSION-STATE.md << EOF

SESSION-STATE.md — 活动工作内存

该文件是代理的RAM — 可抵御压缩、重启、干扰。

当前任务

[无]

关键上下文

[暂无]

待处理操作

- [ ] 无

近期决策

[暂无]

最后更新：[时间戳] 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笔记（静默）
表达偏好？ → memory_store设置importance=0.9

会话结束时

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 → 然后响应
用户做出决策

为什么？ 如果你先响应然后在保存前崩溃/压缩，上下文就会丢失。WAL确保持久性。

示例工作流

用户：这个项目我们用Tailwind，不用原生CSS

代理（内部）：

1. 写入SESSION-STATE.md：决策：使用Tailwind，不用原生CSS
存储到Git笔记：关于CSS框架的决策
memory_store：用户偏好Tailwind而非原生CSS importance=0.9
然后响应：收到 — 就用Tailwind...

维护命令

bash

审计向量记忆

memory_recall query=* limit

elite-longterm-memory精英长期记忆