elite-longterm-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

AI Agent的终极内存系统。将6种经过验证的方法整合为一个可靠的架构。

再也不会丢失上下文，再也不会忘记决策，再也不会重复犯错。

Architecture Overview

架构概述

┌─────────────────────────────────────────────────────────────────┐
│                    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      │                                │
│                  └─────────────┘                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    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      │                                │
│                  └─────────────┘                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

The 5 Memory Layers

5层内存架构

Layer 1: HOT RAM (SESSION-STATE.md)

第一层：HOT RAM（SESSION-STATE.md）

From: bulletproof-memory

Active working memory that survives compaction. Write-Ahead Log protocol.

markdown

undefined

源自：bulletproof-memory

可在压缩后保留的活跃工作内存。采用预写日志（WAL）协议。

markdown

undefined

SESSION-STATE.md — Active Working Memory

Current Task

当前任务

[What we're working on RIGHT NOW]

[我们当前正在处理的工作]

Key Context

关键上下文

User preference: ...
Decision made: ...
Blocker: ...

用户偏好：...
已做决策：...
阻塞问题：...

Pending Actions

待办操作


**Rule:** Write BEFORE responding. Triggered by user input, not agent memory.


**规则：** 先写入再回复。由用户输入触发，而非Agent内存。

Layer 2: WARM STORE (LanceDB Vectors)

第二层：WARM STORE（LanceDB向量存储）

From: lancedb-memory

Semantic search across all memories. Auto-recall injects relevant context.

bash

undefined

源自：lancedb-memory

跨所有内存的语义搜索。自动召回会注入相关上下文。

bash

undefined

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

undefined

memory_store text="User prefers dark mode" category="preference" importance=0.9

undefined

Layer 3: COLD STORE (Git-Notes Knowledge Graph)

第三层：COLD STORE（Git-Notes知识图谱）

From: git-notes-memory

Structured decisions, learnings, and context. Branch-aware.

bash

undefined

源自：git-notes-memory

结构化的决策、经验总结和上下文信息。支持分支感知。

bash

undefined

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"

undefined

python3 memory.py -p $DIR get "frontend"

undefined

Layer 4: CURATED ARCHIVE (MEMORY.md + daily/)

第四层：精选归档（MEMORY.md + daily/）

From: OpenClaw native

Human-readable long-term memory. Daily logs + distilled wisdom.

workspace/
├── MEMORY.md              # Curated long-term (the good stuff)
└── memory/
    ├── 2026-01-30.md      # Daily log
    ├── 2026-01-29.md
    └── topics/            # Topic-specific files

源自：OpenClaw原生功能

人类可读的长期内存。每日日志+提炼的经验总结。

workspace/
├── MEMORY.md              # 精选长期内存（核心内容）
└── memory/
    ├── 2026-01-30.md      # 每日日志
    ├── 2026-01-29.md
    └── topics/            # 主题特定文件

Layer 5: CLOUD BACKUP (SuperMemory) — Optional

第五层：云备份（SuperMemory）—— 可选

From: supermemory

Cross-device sync. Chat with your knowledge base.

bash

export SUPERMEMORY_API_KEY="your-key"
supermemory add "Important context"
supermemory search "what did we decide about..."

源自：supermemory

跨设备同步。可与你的知识库对话。

bash

export SUPERMEMORY_API_KEY="your-key"
supermemory add "Important context"
supermemory search "what did we decide about..."

Layer 6: AUTO-EXTRACTION (Mem0) — Recommended

第六层：自动提取（Mem0）—— 推荐

NEW: Automatic fact extraction

Mem0 automatically extracts facts from conversations. 80% token reduction.

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" });

Benefits:

Auto-extracts preferences, decisions, facts
Deduplicates and updates existing memories
80% reduction in tokens vs raw history
Works across sessions automatically

新增：自动事实提取

Mem0可自动从对话中提取事实，减少80%的令牌消耗。

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 });

// 对话自动提取事实
await client.add(messages, { user_id: "user123" });

// 获取相关内存
const memories = await client.search(query, { user_id: "user123" });

优势：

自动提取偏好、决策、事实
去重并更新现有内存
相比原始历史记录减少80%的令牌消耗
自动跨会话工作

Quick Setup

快速设置

1. Create SESSION-STATE.md (Hot RAM)

1. 创建SESSION-STATE.md（热内存）

bash

cat > SESSION-STATE.md << 'EOF'

bash

cat > SESSION-STATE.md << 'EOF'

SESSION-STATE.md — Active Working Memory

This file is the agent's "RAM" — survives compaction, restarts, distractions.

该文件是Agent的“RAM”——可在压缩、重启、注意力分散后保留。

Current Task

当前任务

[None]

[无]

Key Context

关键上下文

[None yet]

[暂无]

Pending Actions

待办操作

None

Recent Decisions

近期决策

[None yet]

Last updated: [timestamp] EOF

undefined

[暂无]

最后更新：[时间戳] EOF

undefined

2. Enable LanceDB (Warm Store)

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
        }
      }
    }
  }
}

在

~/.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. Initialize Git-Notes (Cold Store)

3. 初始化Git-Notes（冷存储）

bash

cd ~/clawd
git init  # if not already
python3 skills/git-notes-memory/memory.py -p . sync --start

bash

cd ~/clawd
git init  # 如果尚未初始化
python3 skills/git-notes-memory/memory.py -p . sync --start

4. Verify MEMORY.md Structure

4. 验证MEMORY.md结构

bash

undefined

bash

undefined

Ensure you have:

确保你拥有：

- MEMORY.md in workspace root

- 工作区根目录下的MEMORY.md

- memory/ folder for daily logs

- 用于每日日志的memory/文件夹

mkdir -p memory

undefined

mkdir -p memory

undefined

5. (Optional) Setup SuperMemory

5.（可选）设置SuperMemory

bash

export SUPERMEMORY_API_KEY="your-key"

bash

export SUPERMEMORY_API_KEY="your-key"

Add to ~/.zshrc for persistence

添加到~/.zshrc以持久化设置

undefined

undefined

Agent Instructions

Agent操作指南

On Session Start

会话启动时

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

读取SESSION-STATE.md —— 这是你的热上下文
运行
```
memory_search
```
获取相关的历史上下文
查看memory/YYYY-MM-DD.md获取近期活动记录

During Conversation

对话过程中

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

用户提供具体细节？ → 先写入SESSION-STATE.md再回复
做出重要决策？ → 存储到Git-Notes（静默操作）
用户表达偏好？ → 使用
```
memory_store
```
，设置importance=0.9

On Session End

会话结束时

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

更新SESSION-STATE.md为最终状态
将重要内容迁移到MEMORY.md以长期保存
创建/更新memory/YYYY-MM-DD.md中的每日日志

Memory Hygiene (Weekly)

内存维护（每周）

Review SESSION-STATE.md — archive completed tasks
Check LanceDB for junk:
```
memory_recall query="*" limit=50
```
Clear irrelevant vectors:
```
memory_forget id=<id>
```
Consolidate daily logs into MEMORY.md

检查SESSION-STATE.md —— 归档已完成任务
检查LanceDB中的无效内容：
```
memory_recall query="*" limit=50
```
清除无关向量：
```
memory_forget id=<id>
```
将每日日志合并到MEMORY.md

The WAL Protocol (Critical)

WAL协议（至关重要）

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.

预写日志（WAL）： 先写入状态再回复，而非之后。

触发条件	操作
用户表达偏好	写入SESSION-STATE.md → 再回复
用户做出决策	写入SESSION-STATE.md → 再回复
用户给出截止日期	写入SESSION-STATE.md → 再回复
用户纠正你的错误	写入SESSION-STATE.md → 再回复

原因？ 如果你先回复，然后在保存前崩溃/压缩，上下文就会丢失。WAL确保数据持久性。

Example Workflow

示例工作流

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..."

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

Agent（内部操作）：
1. 写入SESSION-STATE.md：“决策：使用Tailwind，而非原生CSS”
2. 存储到Git-Notes：关于CSS框架的决策
3. 执行memory_store：“User prefers Tailwind over vanilla CSS” importance=0.9
4. 然后回复：“好的——就用Tailwind...”

Maintenance Commands

维护命令

bash

undefined

bash

undefined

Audit vector memory

审计向量内存

memory_recall query="*" limit=50

Clear all vectors (nuclear option)

清除所有向量（终极方案）

rm -rf ~/.openclaw/memory/lancedb/ openclaw gateway restart

Export Git-Notes

导出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/

undefined

du -sh ~/.openclaw/memory/ wc -l MEMORY.md ls -la memory/

undefined

Why Memory Fails

内存系统失效的原因

Understanding the root causes helps you fix them:

Failure Mode	Cause	Fix
Forgets everything	`memory_search` 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

了解根本原因有助于解决问题：

失效模式	原因	修复方案
完全忘记所有内容	`memory_search` 已禁用	启用该功能并添加OpenAI密钥
文件未加载	Agent跳过读取内存	将读取内存添加到AGENTS.md规则中
事实未被捕获	未启用自动提取	使用Mem0或手动记录
子Agent孤立	未继承上下文	在任务提示中传递上下文
重复犯错	经验教训未记录	写入memory/lessons.md

Solutions (Ranked by Effort)

解决方案（按实施难度排序）

1. Quick Win: Enable memory_search

1. 快速见效：启用memory_search

If you have an OpenAI key, enable semantic search:

bash

openclaw configure --section web

This enables vector search over MEMORY.md + memory/*.md files.

如果你有OpenAI密钥，启用语义搜索：

bash

openclaw configure --section web

这将启用对MEMORY.md + memory/*.md文件的向量搜索。

2. Recommended: Mem0 Integration

2. 推荐方案：Mem0集成

Auto-extract facts from conversations. 80% token reduction.

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" });

自动从对话中提取事实，减少80%的令牌消耗。

bash

npm install mem0ai

javascript

const { MemoryClient } = require('mem0ai');

const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });

// 自动提取并存储
await client.add([
  { role:"user", content:"I prefer Tailwind over vanilla CSS" }
], { user_id:"ty" });

// 获取相关内存
const memories = await client.search("CSS preferences", { user_id:"ty" });

3. Better File Structure (No Dependencies)

3. 优化文件结构（无依赖）

memory/
├── projects/
│   ├── strykr.md
│   └── taska.md
├── people/
│   └── contacts.md
├── decisions/
│   └── 2026-01.md
├── lessons/
│   └── mistakes.md
└── preferences.md

Keep MEMORY.md as a summary (<5KB), link to detailed files.

memory/
├── projects/
│   ├── strykr.md
│   └── taska.md
├── people/
│   └── contacts.md
├── decisions/
│   └── 2026-01.md
├── lessons/
│   └── mistakes.md
└── preferences.md

将MEMORY.md保持为摘要（<5KB），链接到详细文件。

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

问题	修复方案
忘记用户偏好	在MEMORY.md中添加 `## 偏好` 章节
重复犯错	将每个错误记录到 `memory/lessons.md`
子Agent缺乏上下文	在任务提示中包含关键上下文
忘记近期工作	严格执行每日文件记录规范
memory_search无返回结果	检查OpenAI API密钥： `echo $OPENAI_API_KEY`
→ 验证openclaw.json中已启用memorySearch

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

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开发 —— 属于Next Frontier AI工具集的一部分