OpenClaw 永久记忆系统技术解析

OpenClaw（Clawdbot）是一个开源本地化AI助手，采用MIT许可证，核心特性是具备永久记忆系统。与传统云端AI不同，它在用户本地设备运行，确保数据隐私和所有权。系统通过双层存储（每日日志和长期记忆）实现持久化记忆，支持语义和关键词混合搜索。架构上区分临时上下文和永久记忆，采用SQLite向量存储和智能检索机制。提供多代理隔离工作空间，支持独立记忆管理。配置灵活，包括基础设置和高级选项如

MichaelIp

15人浏览 · 2026-02-14 04:59:41

MichaelIp · 2026-02-14 04:59:41 发布

这里写自定义目录标题

1. 概述
- 1.1 核心特点
2. 系统架构
- 2.1 记忆与上下文区分
- 2.2 记忆存储结构
- - 2.2.1 第一层：每日日志
  - 2.2.2 第二层：长期记忆
3. 记忆访问机制
- 3.1 记忆工具
- - 3.1.1 记忆搜索工具
  - 3.1.2 记忆读取工具
- 3.2 写入触发规则
4. 索引与搜索机制
- 4.1 索引管道
- - 4.1.1 分块策略
  - 4.1.2 向量存储
- 4.2 混合搜索算法
5. 上下文管理
- 5.1 上下文压缩（Compaction）
- - 5.1.1 压缩过程
  - 5.1.2 压缩配置
- 5.2 记忆刷新机制
- 5.3 修剪策略
- - 5.3.1 工具结果修剪
  - 5.3.2 缓存TTL修剪
6. 会话生命周期
- 6.1 会话重置模式
- 6.2 会话记忆钩子
7. 多代理支持
- 7.1 隔离架构
- 7.2 代理配置
8. 配置指南
- 8.1 基础配置
- 8.2 高级配置
9. 最佳实践
- 9.1 记忆管理
- 9.2 性能优化
- 9.3 故障排除
- - 9.3.1 常见问题
  - 9.3.2 日志检查
10. 设计原则总结
11. 参考资料

1. 概述

OpenClaw（Clawdbot）是一个开源的本地化AI助手（MIT许可证），其核心特性是具备永久记忆系统。与传统云端AI服务不同，OpenClaw在用户本地设备上运行，提供完整的记忆所有权和隐私控制。系统通过双层文件存储和智能检索机制，实现跨会话的持久化记忆。

1.1 核心特点

本地优先：所有记忆数据存储在用户本地
透明可编辑：记忆以纯Markdown格式存储
无限扩展：记忆容量不受限制
智能检索：支持语义和关键词混合搜索
多代理隔离：支持独立的工作空间和记忆空间

2. 系统架构

2.1 记忆与上下文区分

维度	上下文（Context）	记忆（Memory）
存在形式	单次请求的输入	磁盘持久化存储
生命周期	临时性，仅限当前请求	永久性，跨会话持久
容量限制	受模型上下文窗口限制	无限制
成本	消耗API Token	仅存储成本
访问方式	直接注入	按需检索

2.2 记忆存储结构

~/clawd/                          # 主代理工作空间
├── MEMORY.md                     # 长期记忆层（Layer 2）
└── memory/
    ├── 2026-01-26.md            # 每日日志（Layer 1）
    ├── 2026-01-25.md
    └── ...

2.2.1 第一层：每日日志

文件：memory/YYYY-MM-DD.md
特性：追加写入，按时间顺序记录
内容：日常对话、临时备忘、即时想法
示例：

# 2026-01-26

## 10:30 - API架构讨论
用户倾向使用REST而非GraphQL，原因：团队熟悉度、实现简单性。

## 14:15 - 用户偏好
用户明确表示更偏好TypeScript而非JavaScript。

2.2.2 第二层：长期记忆

文件：MEMORY.md
特性：结构化整理，重要信息提炼
内容：用户偏好、关键决策、重要联系人、项目元数据
示例：

# 长期记忆

## 用户偏好
- 编码语言：偏好TypeScript > JavaScript
- 沟通风格：喜欢简洁解释
- 当前项目：Acme仪表板开发

## 关键决策
- 2026-01-20：选择REST API而非GraphQL
- 2026-01-15：确定使用PostgreSQL数据库

3. 记忆访问机制

3.1 记忆工具

3.1.1 记忆搜索工具

{
  "name": "memory_search",
  "description": "强制性回忆步骤：在回答有关先前工作、决策、日期、人员、偏好或待办事项的问题之前，语义搜索MEMORY.md + memory/*.md",
  "parameters": {
    "query": "我们关于API的决定是什么？",
    "maxResults": 6,
    "minScore": 0.35
  }
}

返回结果：

{
  "results": [
    {
      "path": "memory/2026-01-20.md",
      "startLine": 45,
      "endLine": 52,
      "score": 0.87,
      "snippet": "## API讨论\n决定使用REST而非GraphQL，原因：简单性...",
      "source": "memory"
    }
  ],
  "provider": "openai",
  "model": "text-embedding-3-small"
}

3.1.2 记忆读取工具

{
  "name": "memory_get",
  "description": "在memory_search后从记忆文件读取特定行",
  "parameters": {
    "path": "memory/2026-01-20.md",
    "from": 45,
    "lines": 15
  }
}

3.2 写入触发规则

触发条件	写入目标	内容类型
日常笔记、“记住这个”	memory/YYYY-MM-DD.md	临时记忆
持久事实、偏好、决策	MEMORY.md	长期记忆
经验教训	AGENTS.md 或 TOOLS.md	技能改进

4. 索引与搜索机制

4.1 索引管道

文件保存 → 文件监控 → 分块处理 → 向量化 → 存储索引

4.1.1 分块策略

块大小：~400个Token
重叠大小：80个Token
分块目的：平衡语义连贯性与搜索粒度
重叠优势：确保跨块边界的信息被完整捕获

4.1.2 向量存储

数据库：SQLite + sqlite-vec扩展
表结构：

chunks：存储分块元数据
chunks_vec：向量存储（sqlite-vec）
chunks_fts：全文搜索索引（FTS5）
embedding_cache：避免重复向量化

4.2 混合搜索算法

评分公式：

最终得分 = (0.7 × 向量相似度得分) + (0.3 × BM25关键词得分)

向量搜索：语义相似性（主要信号）
BM25搜索：精确关键词匹配（辅助信号）
阈值过滤：默认minScore=0.35

5. 上下文管理

5.1 上下文压缩（Compaction）

当对话接近模型上下文窗口限制时，系统自动触发压缩机制：

5.1.1 压缩过程

原始对话（180K/200K Token） → 触发压缩
    ↓
总结第1-140轮对话 → 保持第141-150轮完整
    ↓
生成紧凑摘要并保存 → 新上下文（45K/200K Token）

5.1.2 压缩配置

agents:
  defaults:
    compaction:
      reserveTokensFloor: 20000
      memoryFlush:
        enabled: true
        softThresholdTokens: 4000
        systemPrompt: "会话接近压缩点，立即存储持久记忆"
        prompt: "将持久笔记写入memory/YYYY-MM-DD.md；如无需存储，回复NO_REPLY"

5.2 记忆刷新机制

在压缩发生前，系统执行静默记忆刷新：

检测阈值：上下文使用率超过软阈值
触发刷新：系统提示AI存储重要信息
自动写入：AI将关键信息写入记忆文件
安全压缩：确保重要信息已持久化后再压缩

5.3 修剪策略

5.3.1 工具结果修剪

软修剪：截断长输出，保留头尾关键部分
硬清除：完全移除旧工具结果，替换为占位符
磁盘保留：JSONL文件中的原始数据保持不变

5.3.2 缓存TTL修剪

agent:
  contextPruning:
    mode: "cache-ttl"
    ttl: "600"
    keepLastAssistants: 3
    softTrim:
      maxChars: 4000
      headChars: 1500
      tailChars: 1500
    hardClear:
      enabled: true
      placeholder: "[旧工具结果内容已清除]"

6. 会话生命周期

6.1 会话重置模式

模式	行为描述
daily	固定时间重置（默认：当地时间4:00 AM）
idle	无活动N分钟后重置
daily+idle	任一条件满足即重置

6.2 会话记忆钩子

当使用/new命令开始新会话时：

从结束的会话中提取最后15条消息
通过LLM生成描述性slug
保存为独立记忆文件：memory/2026-01-26-api-design.md
新会话可通过memory_search访问该上下文

7. 多代理支持

7.1 隔离架构

~/.clawdbot/memory/              # 状态目录（索引）
├── main.sqlite                  # "main"代理向量索引
└── work.sqlite                  # "work"代理向量索引

~/clawd/                         # "main"代理工作空间
├── MEMORY.md
└── memory/

~/clawd-work/                    # "work"代理工作空间
├── MEMORY.md
└── memory/

7.2 代理配置

工作空间隔离：每个代理拥有独立文件目录
索引隔离：每个代理拥有独立的SQLite索引
默认行为：代理只能访问自身工作空间
可选配置：可通过绝对路径访问其他工作空间（需显式启用）

8. 配置指南

8.1 基础配置

# clawdbot.yaml

agents:
  main:
    workspace: ~/clawd
    memory:
      embeddingProvider: openai
      embeddingModel: text-embedding-3-small
      chunkSize: 400
      chunkOverlap: 80
      searchWeights:
        vector: 0.7
        keyword: 0.3

8.2 高级配置

{
  "agents": {
    "defaults": {
      "compaction": {
        "enabled": true,
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "prompt": "将持久笔记写入memory/YYYY-MM-DD.md；如无需存储，回复NO_REPLY"
        }
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": 600,
        "keepLastAssistants": 3
      }
    }
  }
}