elite-longterm-memory

精英长期记忆 🧠

面向 AI Agent 的终极记忆系统。 将 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

能够在上下文压缩后保留的活动工作记忆。采用预写日志协议。

# SESSION-STATE.md — Active Working Memory

## Current Task
[What we're working on RIGHT NOW]

## Key Context
- User preference: ...
- Decision made: ...
- Blocker: ...

## Pending Actions
- [ ] ...

规则： 响应前先写入。由用户输入触发，而非 Agent 记忆触发。

第 2 层：温存储（LanceDB 向量）

来源：lancedb-memory

对所有记忆进行语义搜索。自动召回并注入相关上下文。

# 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

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

# 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/）

来源：Clawdbot 原生功能

人类可读的长期记忆。每日日志 + 提炼后的智慧。

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

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

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

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

新功能：自动提取事实

Mem0 会自动从对话中提取事实。减少 80% 的 token 用量。

npm install mem0ai
export MEM0_API_KEY="your-key"

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）

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（温存储）

在 ~/.clawdbot/clawdbot.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（冷存储）

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

4. 验证 MEMORY.md 结构

# Ensure you have:
# - MEMORY.md in workspace root
# - memory/ folder for daily logs
mkdir -p memory

5.（可选）设置 SuperMemory

export SUPERMEMORY_API_KEY="your-key"
# Add to ~/.zshrc for persistence

Agent 指令

会话开始时

1. 阅读 SESSION-STATE.md——这是你的热上下文
2. 运行 memory_search 搜索相关的历史上下文
3. 查看 memory/YYYY-MM-DD.md 中的近期活动

对话期间

1. 用户提供了具体细节？ → 响应前写入 SESSION-STATE.md
2. 做出了重要决策？ → 存入 Git-Notes（静默执行）
3. 用户表达了偏好？ → 使用 memory_store 并设置 importance=0.9

会话结束时

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 协议（关键）

预写日志： 响应前写入状态，而不是响应后。

触发条件	操作
用户说明了偏好	写入 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..."

维护命令

# Audit vector memory
memory_recall query="*" limit=50

# Clear all vectors (nuclear option)
rm -rf ~/.clawdbot/memory/lancedb/
clawdbot gateway restart

# Export Git-Notes
python3 memory.py -p . export --format json > memories.json

# Check memory health
du -sh ~/.clawdbot/memory/
wc -l MEMORY.md
ls -la memory/

记忆为何失效

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

失效模式	原因	修复方法
忘记所有内容	memory_search 已禁用	启用它并添加 OpenAI 密钥
未加载文件	Agent 跳过了记忆读取	将相关规则添加到 AGENTS.md
未捕获事实	没有自动提取	使用 Mem0 或手动记录
子 Agent 彼此隔离	不会继承上下文	在任务提示词中传递上下文
重犯错误	未记录经验教训	写入 memory/lessons.md

解决方案（按所需工作量排序）

1. 快速见效：启用 memory_search

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

clawdbot configure --section web

这样即可对 MEMORY.md 和 memory/*.md 文件进行向量搜索。

2. 推荐：Mem0 集成

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

npm install mem0ai

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），并链接到详细文件。

立即修复清单

问题	修复方法
忘记偏好	在 MEMORY.md 中添加 ## Preferences 部分
重复犯错	将每个错误记录到 memory/lessons.md
子 Agent 缺少上下文	在生成任务提示词中加入关键上下文
忘记近期工作	严格遵守每日文件记录规范
记忆搜索不起作用	检查是否已设置 OPENAI_API_KEY

故障排除

Agent 在对话过程中不断遗忘： → SESSION-STATE.md 未更新。检查 WAL 协议。

注入了无关记忆： → 禁用 autoCapture，提高 minImportance 阈值。

记忆过大，回忆缓慢： → 执行清理：清除旧向量，归档每日日志。

Git-Notes 未持久保存： → 运行 git notes push，与远程同步。

memory_search 没有返回结果： → 检查 OpenAI API 密钥：echo $OPENAI_API_KEY → 确认 clawdbot.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 构建 — Next Frontier AI 工具包的一部分