Memory System

Memory System v1.4.0 — 三层记忆架构

让 AI 从金鱼变成大象。

一个完整的 AI Agent 记忆系统，基于认知科学原理设计，实现：

• 🧠 三层记忆架构：工作记忆 → 长期记忆 → 原始日志
• ⚡ 自动整合：每日 Consolidation，无需手动维护
• 🎯 智能衰减：重要信息永不遗忘，琐碎信息自然淡化
• 📊 结构化存储：Facts / Beliefs / Summaries 分类管理
• 🔍 高效检索：多维索引，毫秒级响应
• 🔥 访问追踪（v1.1）：常用记忆权重更高
• ⏰ 时间敏感（v1.1）：自动识别和清理过期信息

设计理念

为什么需要这个系统？

核心原则

1. 检索优先 — 不是"记得多"，而是"找得准"
2. 写复杂读简单 — 复杂逻辑在写入时处理，读取 O(1)
3. 重要性由语义决定 — 不依赖使用频率，不漏重要信息
4. 自动衰减 — 旧记忆自动降权，不依赖手动清理

架构概览

┌─────────────────────────────────────────────────────────────┐
│                     Layer 1: 工作记忆                        │
│                   (snapshot.md, ~2000 tokens)                │
│         每次对话自动注入，包含最重要的上下文                    │
└─────────────────────────────────────────────────────────────┘
                              ↑
                    Consolidation Phase 7 生成
                              ↑
┌─────────────────────────────────────────────────────────────┐
│                     Layer 2: 长期记忆                        │
│              (facts.jsonl / beliefs.jsonl / summaries.jsonl) │
│                                                             │
│   ┌─────────────┐              ┌─────────────┐              │
│   │   active/   │  ←— 衰减 —→  │  archive/   │              │
│   │  (活跃池)    │    score     │  (归档池)    │              │
│   │  参与检索    │    < 0.05    │  冷藏保存    │              │
│   └─────────────┘              └─────────────┘              │
│                                                             │
│   entities/     — 实体档案（人物、地点、项目）                  │
│   index/        — 多维索引（关键词、时间线、关系）              │
└─────────────────────────────────────────────────────────────┘
                              ↑
                    Consolidation Phase 1-6 处理
                              ↑
┌─────────────────────────────────────────────────────────────┐
│                     Layer 3: 原始日志                        │
│                    (OpenClaw Session Transcript)             │
│                  只读取，不修改，完整保留原始对话               │
└─────────────────────────────────────────────────────────────┘

文件结构

workspace/memory/
├── config.json                    # 系统配置
├── layer1/
│   └── snapshot.md                # 工作记忆快照（自动生成）
├── layer2/
│   ├── active/                    # 活跃池（参与检索和衰减）
│   │   ├── facts.jsonl            # 事实库
│   │   ├── beliefs.jsonl          # 推断库
│   │   └── summaries.jsonl        # 摘要库
│   ├── archive/                   # 归档池（冷藏保存）
│   │   ├── facts.jsonl
│   │   ├── beliefs.jsonl
│   │   └── summaries.jsonl
│   ├── entities/                  # 实体档案
│   │   ├── _index.json            # 实体索引
│   │   └── {entity_id}.json       # 单个实体详情
│   └── index/                     # 检索索引
│       ├── keywords.json          # 关键词 → 记忆ID
│       ├── timeline.json          # 时间 → 记忆ID
│       └── relations.json         # 实体 → 相关记忆
└── state/
    ├── consolidation.json         # Consolidation 状态（支持断点续传）
    └── rankings.json              # 当前排名快照

记忆类型

Facts（事实）

用户明确陈述的信息，置信度 = 1.0

{
  "id": "f_20260204_001",
  "content": "用户对花生过敏",
  "importance": 1.0,
  "score": 0.95,
  "entities": ["用户"],
  "created": "2026-02-04T10:30:00Z",
  "source": "session_abc123:15"
}

Beliefs（推断）

基于对话推断的信息，置信度 < 1.0

{
  "id": "b_20260204_001",
  "content": "用户可能在科技公司工作",
  "confidence": 0.6,
  "importance": 0.5,
  "score": 0.72,
  "basis": "提到在北京工作，经常开会",
  "entities": ["用户"],
  "created": "2026-02-04T10:30:00Z"
}

Summaries（摘要）

多个相关 facts 的聚合

{
  "id": "s_20260204_001",
  "content": "用户是学生，对 AI 技术感兴趣，正在开发个人项目",
  "importance": 0.9,
  "score": 0.88,
  "source_facts": ["f_001", "f_015", "f_023"],
  "entities": ["用户", "个人项目"],
  "created": "2026-02-04T10:30:00Z"
}

重要性评分机制

内在重要性（信息本身的性质）

外在信号（用户表达方式）

评分公式

importance = min(1.0, intrinsic_score + explicit_signal)

衰减机制

衰减率（每日）

Importance 影响衰减

actual_decay = base_decay × (1 - importance × 0.5)

示例：

• importance=1.0 的 fact：实际衰减 0.4%/天，半衰期 ~174 天
• importance=0.5 的 fact：实际衰减 0.6%/天，半衰期 ~116 天

归档规则

score < 0.05 → 移入 archive/（冷藏，不再参与检索）

Consolidation 流程

每日自动执行，将原始对话转化为结构化记忆。

┌─────────────────────────────────────────────────────────────┐
│  Phase 1: 轻量全量                                          │
│  ─────────────────                                          │
│  • 读取今日对话（OpenClaw Session）                          │
│  • 按规则切分为语义片段                                      │
│  • 标记类型：陈述/问题/指令/闲聊                              │
│  • 成本：0 tokens（纯规则）                                  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: 重要性筛选                                        │
│  ─────────────────                                          │
│  • 模型判断哪些片段值得长期记忆                               │
│  • 标注 importance 等级                                     │
│  • 成本：~700 tokens                                        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: 深度提取                                          │
│  ─────────────────                                          │
│  • 将筛选出的片段转为结构化 facts/beliefs                     │
│  • 识别实体（人名、地名、项目名）                             │
│  • 成本：~500 tokens                                        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 4: Layer 2 维护                                      │
│  ─────────────────                                          │
│  • 4a: Facts 去重合并（同实体同属性 → 合并，保留历史）         │
│  • 4b: Beliefs 验证（被新 fact 证实 → 升级为 fact）          │
│  • 4c: Summaries 生成（同主题 ≥3 facts → 生成摘要）          │
│  • 4d: Entities 更新（维护实体档案）                         │
│  • 成本：~400 tokens（条件触发）                             │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 5: 权重更新                                          │
│  ─────────────────                                          │
│  • 所有活跃记忆按衰减率降权                                   │
│  • score < 0.05 → 移入 archive/                             │
│  • 成本：0 tokens（纯规则）                                  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 6: 索引更新                                          │
│  ─────────────────                                          │
│  • 增量更新 keywords/timeline/relations 索引                 │
│  • 成本：0 tokens（纯规则）                                  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 7: Layer 1 快照                                      │
│  ─────────────────                                          │
│  • 按 score 排名生成工作记忆快照                              │
│  • 控制在 ~2000 tokens                                      │
│  • 排名靠前 → 内容更丰富                                     │
│  • 成本：~200 tokens（排名变化时）                            │
└─────────────────────────────────────────────────────────────┘

总成本：~1800 tokens/天

触发机制

断点续传

如果执行中断，下次自动从断点继续：

// state/consolidation.json
{
  "last_run": "2026-02-04T03:00:00Z",
  "last_success": "2026-02-04T03:00:00Z",
  "current_phase": null,
  "phase_data": {},
  "retry_count": 0
}

Layer 1 快照结构

# 工作记忆快照
> 生成时间: 2026-02-04T03:00:00Z | 记忆数: 156 | 活跃: 142 | 归档: 14

## 身份
- 名字: Tkao
- 定位: 用户 的数字镜像

## 用户
- 名字: 张三 (用户)
- 专业: 计算机科学大三
- 核心项目: 个人项目

## 约束
- 隐私边界: 不透露项目细节、家庭信息、经济状况
- 交互风格: 轻松友好，效率优先

## 核心记忆 (Top 5)
1. [1.0] 用户对花生过敏
2. [0.95] 用户正在开发个人项目，基于 某平台
3. [0.91] 用户希望经济独立，随心玩转 AI 工具
4. [0.88] 用户代码能力有限(⭐⭐)，依赖 AI 辅助
5. [0.85] 用户在某大学就读

## 近期要点 (3天内)
- 2026-02-04: 完成记忆系统 Consolidation 设计
- 2026-02-03: 讨论三层架构和 Router 逻辑
- 2026-02-02: Moltbook 社交任务配置完成

## 索引
[完整记忆库: 156 条 | 实体: 23 个 | 主题: 12 类]
使用 memory_search 检索详细信息

⚠️ LLM 配置（重要）

v1.1.7 起引入 LLM 深度集成，需要配置 API Key 才能启用智能功能（未配置时全部功能规则驱动、优雅降级）。

配置 API Key

# 方法 1: 环境变量（推荐）
export OPENAI_API_KEY="sk-your-api-key-here"

# 方法 2: 在 .bashrc 或 .zshrc 中永久配置
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

# 方法 3: 在 config.json 中配置
# memory/config.json
{
  "llm_api_key": "sk-your-api-key-here",
  ...
}

可选配置

# 自定义 API Base URL（用于代理或兼容 API）
export OPENAI_BASE_URL="https://api.openai.com/v1"

# 自定义模型（默认 gpt-4o-mini）
export MEMORY_LLM_MODEL="gpt-4o-mini"

# 禁用 LLM（纯规则模式）
export MEMORY_LLM_ENABLED="false"

LLM 功能说明

注意：即使没有配置 API Key，系统也能正常工作（回退到纯规则模式）。LLM 是增强功能，不是必需的。

使用方法

初始化

# 创建目录结构和默认配置
python3 src/memory.py init

手动执行 Consolidation

# 完整流程
python3 src/memory.py consolidate

# 强制执行（忽略时间检查）
python3 src/memory.py consolidate --force

# 只执行某个阶段（调试用）
python3 src/memory.py consolidate --phase 2

手动添加记忆

# 添加 fact
python3 src/memory.py capture "用户对花生过敏" \
  --type fact \
  --importance 1.0 \
  --entities "用户"

# 添加 belief
python3 src/memory.py capture "用户可能喜欢咖啡" \
  --type belief \
  --confidence 0.6 \
  --importance 0.5

查看状态

# 系统状态
python3 src/memory.py status

# 统计信息
python3 src/memory.py stats

# 输出示例:
# 📊 Memory System Stats
# ══════════════════════
# Total: 156 memories
# Active: 142 | Archive: 14
# 
# By Type:
#   Facts: 89 (57%)
#   Beliefs: 42 (27%)
#   Summaries: 25 (16%)
# 
# By Importance:
#   Critical (0.9-1.0): 12
#   High (0.7-0.9): 45
#   Medium (0.4-0.7): 67
#   Low (0-0.4): 32
# 
# Last Consolidation: 2026-02-04T03:00:00Z
# Next Scheduled: 2026-02-05T03:00:00Z

维护命令

# 重建索引
python3 src/memory.py rebuild-index

# 验证数据完整性
python3 src/memory.py validate

# 手动归档
python3 src/memory.py archive <memory_id>

配置说明

// memory/config.json
{
  "version": "1.0",
  
  "decay_rates": {
    "fact": 0.008,
    "belief": 0.07,
    "summary": 0.025
  },
  
  "thresholds": {
    "archive": 0.05,
    "summary_trigger": 3
  },
  
  "token_budget": {
    "layer1_total": 2000,
    "layer1_top1": 0.4,
    "layer1_top2": 0.25,
    "layer1_top3": 0.15,
    "layer1_rest": 0.2
  },
  
  "consolidation": {
    "schedule": "0 3 * * *",
    "fallback_hours": 48,
    "model": "default"
  },
  
  "importance_rules": {
    "identity_health_safety": 1.0,
    "preference_relation_status": 0.8,
    "general_fact": 0.5,
    "temporary": 0.2
  }
}

与 OpenClaw 集成

1. 配置 Layer 1 自动注入

在 OpenClaw 配置中添加：

{
  "agents": {
    "main": {
      "systemPromptFiles": [
        "memory/layer1/snapshot.md"
      ]
    }
  }
}

2. 配置定时 Consolidation

添加 Cron Job：

{
  "name": "Memory Consolidation",
  "schedule": {"kind": "cron", "expr": "0 3 * * *"},
  "payload": {"kind": "systemEvent", "text": "执行记忆整合: python3 src/memory.py consolidate"},
  "sessionTarget": "main"
}

3. 配置 Heartbeat 兜底

在 HEARTBEAT.md 中添加：

## Memory Consolidation 检查
如果距离上次 Consolidation > 48 小时：
  执行 `python3 src/memory.py consolidate`

4. 配置检索规则

在 AGENTS.md 中添加：

## 记忆检索规则

### 自动注入
- Layer 1 snapshot 已通过 systemPromptFiles 自动注入

### 主动检索触发条件
当用户消息包含以下情况时，调用 memory_search：
- 提到过去："之前"、"上次"、"以前"
- 询问偏好："我喜欢"、"我讨厌"
- 涉及人物：人名、关系词
- 涉及项目：项目名、任务名
- 显式请求："你还记得"、"帮我回忆"

设计亮点

1. 认知科学启发

2. 工程优化

3. 与现有系统兼容

• 不修改 OpenClaw 源码
• 利用现有的 memory_search 能力
• 通过配置和 AGENTS.md 集成

性能指标

版本历史

v1.2.0 ~ v1.4.0（当前）

• 噪声前置过滤 + inject 动态注入 + QMD(BM25) 集成（v1.2.x）
• Memory Operator + 冲突消解协议 + 虚假记忆过滤（v1.3.0）
• 时间驱动指数衰减修正 + 中文索引 2-gram 修复（v1.4.x）
• 完整版本表见 README.md

v1.1.7

• LLM 深度集成：语义复杂度检测 + 智能触发 + 失败回退
• 扩大 LLM 触发区间：0.20.5（原 0.20.3）
• API Key 多源获取：环境变量 → 配置文件 → 参数传入
• 复杂内容强制 LLM 复核

v1.1.6

• 引号实体提取（优先级最高）
• 分层冲突信号（Tier 1/2）
• 去重阈值改用相对比例（30%）
• 中文分词优化

v1.1.5

• 三层实体识别（硬编码 → 学习 → LLM）
• 竞争性抑制（相似实体降权）
• 访问加成修复（最近 N 天）

v1.1.4

• 访问日志追踪
• 时间敏感记忆

v1.1.3

• LLM 兜底机制

v1.1.0

• Router 检索系统
• Consolidation 完整流程

v1.0.0

• 三层架构设计
• Consolidation 7 Phase 流程
• 重要性评分机制
• 衰减和归档机制

路线图

v1.2（计划）

• IO 竞态：切换 SQLite 后端
• 冷启动优化：模块合并/延迟加载
• 增量索引更新
• 整合期实体抑制

v2.0（远期）

• 语义嵌入增强检索
• 多 Agent 记忆共享
• 可视化记忆图谱

参考文档

• 设计文档 — 完整的架构设计说明
• Consolidation 报告 — 7 Phase 详细实现
• API 参考 — CLI 命令和配置说明
• CHANGELOG — 完整版本更新日志

致谢

本系统设计参考了：

• 认知科学中的记忆整合理论
• Ebbinghaus 遗忘曲线
• 现有 AI Agent 记忆系统（memory-system-v2, triple-memory）
• Crabby 🦀 的深度测试和犀利评价

Memory System v1.4.0 — 让 AI 拥有真正的记忆。 🧠