OpenClaw 记忆系统：三层记忆架构与 Daily Notes 机制

L3 长期记忆：事实萃取库 经过人工审核或高频访问验证的事实，以结构化键值对形式存储：

## User Preferences
- code_style: "PEP8 with type hints"
- preferred_languages: ["Python", "Rust"]
- infrastructure: "AWS EKS, Terraform"
## Project Context
- current_project: "Payment Gateway v2"
- tech_stack: "Go, gRPC, PostgreSQL"
- constraints: ["PCI-DSS compliance", "99.99% SLA"]

二、记忆写入机制：从被动记录到主动归档

2.1 Agent 主动写入

开发者可通过 SDK 显式控制记忆写入时机，避免自动机制带来的噪声：

from openclaw import Agent, MemoryLevel

agent = Agent("assistant")
# 显式写入长期记忆（重要事实）
await agent.memory.commit(
    level=MemoryLevel.L3,
    content="User is allergic to shellfish",
    tags=["health","constraints"]
)
# 批量写入短期记忆（日常上下文）
await agent.memory.extend(["Discussed Q2 roadmap priorities","Agreed on microservices split strategy"])

写入冲突解决： 当并发写入同一记忆文件时，OpenClaw 采用文件级锁（flock）与乐观锁（版本号）结合的策略：

• 短时间尺度（同一进程内）：内存队列缓冲，批量 flush
• 跨进程并发：基于 inode 的 advisory locking，失败时退避重试

2.2 Pre-compaction Flush 自动归档

L1 向 L2 的溢流由压缩守护进程自动处理，触发条件包括：

触发条件检查（每轮对话后）
│
▼
┌──────────────────────┐
│ Token 使用率 > 80% ? │──Yes──► 启动 Compaction
└──────────┬───────────┘
│ No
▼
┌──────────────────────┐
│ 会话空闲 > 5 分钟 ? │──Yes──► 启动 Compaction
└──────────┬───────────┘
│ No
▼
保持 L1 现状

压缩算法流程：

  原始对话历史 (L1)
│
▼
┌─────────────────────────┐
│ 1. 语义分块
│ - 按主题边界切分对话
│ - 识别独立的事实单元
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ 2. 重要性评分
│ - 用户显式强调 (+2)
│ - 包含决策/结论 (+1)
│ - 闲聊/过渡 (-1)
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ 3. 摘要生成
│ - 高重要性：保留原文
│ - 中重要性：生成摘要
│ - 低重要性：丢弃
└──────────┬──────────────┘
│
▼
写入 L2 (Daily Notes)

三、语义搜索配置：向量检索的工程化实践

OpenClaw 的记忆检索并非简单的关键词匹配，而是基于 Embedding 向量的语义相似度搜索。架构师需在精度、成本与隐私之间做权衡。

3.1 Provider 选型矩阵

memorySearch.provider 支持多种后端，适用场景各异：

配置示例：

{"memorySearch":{"provider":"ollama","model":"nomic-embed-text:latest","baseUrl":"http://localhost:11434","dimensions":768,"metric":"cosine","topK":5,"threshold":0.72}}

3.2 嵌入策略与分块优化

文本分块（Chunking）策略直接影响检索精度：

 Daily Notes (Markdown)
│
▼
┌──────────────────────────────┐
│ 按标题层级分块 (H2/H3 边界)
│ - 保持语义完整性
│ - 块大小：256-512 tokens
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ 重叠窗口 (Overlap: 50 tokens)
│ - 防止上下文截断
│ - 保证跨边界语义连贯
└──────────┬───────────────────┘
│
▼
生成向量索引 (Chroma/FAISS)

混合检索（Hybrid Search）： OpenClaw 默认结合向量相似度与关键词 BM25 分数，通过 RRF（Reciprocal Rank Fusion）重排序：

# 内部实现逻辑
vector_results = vector_search(query_embedding, top_k=10)
keyword_results = bm25_search(query_text, top_k=10)
# RRF 融合
final_scores = {}
for rank, doc in enumerate(vector_results):
    final_scores[doc.id] += 1.0/(k + rank)
for rank, doc in enumerate(keyword_results):
    final_scores[doc.id] += 1.0/(k + rank)

四、记忆加载规则：会话隔离与安全边界

OpenClaw 对记忆的访问实施最小权限原则，不同会话类型具有不同的记忆可见性。

4.1 Main Session 与 Group Session 隔离模型

Workspace 记忆存储
│
├──► Main Session (1:1 专属会话)
│   │
│   ├──► 加载 MEMORY.md (L3 长期记忆)
│   │   - 用户画像
│   │   - 项目上下文
│   │
│   ├──► 加载本周 Daily Notes (L2)
│   │   - 近期上下文
│   │
│   └──► 实时对话历史 (L1)
│
└──► Group Session (1:N 群组会话)
    │
    ├──► 不加载 MEMORY.md
    │   - 防止隐私泄露给其他参与者
    ├──► 仅加载 Session 创建后的对话历史
    └──► 可选：共享白板 (Shared Context)
        - 显式授权的知识库

安全隔离原理：

• Main Session：假设用户与 Agent 建立信任关系，可访问完整个人历史
• Group Session：多参与者环境，默认零记忆启动，避免：
  • 用户 A 的隐私信息被用户 B 通过 Agent 获取
  • 跨项目的敏感数据混用

4.2 显式记忆共享机制

当需要在 Group Session 中引入背景知识时，采用显式授权模式：

# 创建群组会话时注入特定记忆片段
group_session = await openclaw.create_group_session(
    participants=["user1","user2","agent"],
    shared_context=["project_requirements_v2.md", # 仅项目相关文档
                    "api_design_spec.md"],
    exclude_personal_memory=True # 严格隔离个人 L3 记忆
)

五、记忆故障排查：生产环境诊断指南

记忆系统故障往往表现为"Agent 健忘"或"回答 hallucination"，以下是系统性排查路径。

5.1 Workspace 写入权限故障

症状： Agent 表现出"金鱼记忆"，每次对话都像是初次见面。

诊断流程：

# 检查记忆持久化
ls -la ~/.openclaw/
# - 应为 700 (drwx------)
# - 属主应为运行用户

# 检查磁盘空间
df -h
# - 内存目录剩余空间 < 10%
# - 触发只读保护模式

# 检查文件锁竞争
lsof +D ~/.openclaw/
# - 多实例并发写入冲突
# - 解决方案：改用 Redis 后端

修复命令：

# 自动修复权限
openclaw doctor --fix-permissions
# 验证写入能力
openclaw memory test-write --workspace default
# 应返回：Successfully wrote test chunk to L2 memory

5.2 Token 上限导致的记忆遗忘

症状： Agent 在长对话中后期开始重复询问已确认的信息。

根因分析： 当 L1 工作记忆达到模型上下文上限时，即使 L2/L3 存在历史记录，也可能因检索失败或注入位置错误导致记忆"未激活"。

排查步骤：

对话中断/重复询问
│
▼
┌──────────────────────────────┐
│ 检查当前上下文占用           │
│ openclaw session inspect     │
│ - current_tokens: 15234/16384│
│ - 使用率：93%                │
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ 检查记忆检索结果             │
│ - 是否触发 RAG？             │
│ - topK 返回是否为空？        │
│ ├── 空：向量数据库未构建     │
│ │ 运行：openclaw index rebuild│
│ └── 有结果但未被采用         │
│     检查 prompt 模板           │
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ 优化策略                     │
│ 1. 增大 topK (5→10)          │
│ 2. 降低 threshold (0.75→0.65)│
│ 3. 启用重排序 (Reranker)     │
│ 4. 摘要压缩早期对话          │
└──────────────────────────────┘

配置调优：

{"memory":{"contextManagement":{"reserveTokens":2000,// 为检索结果预留空间
"compressionThreshold":0.8,
"summarizationModel":"gpt-4o-mini"// 专用轻量模型做摘要},
"retrieval":{"topK":7,"threshold":0.68,"rerank":true,"rerankModel":"cohere-rerank-v3"}}}

5.3 向量索引损坏修复

症状： 语义搜索返回无关内容，或抛出 Index out of range 异常。

重建索引：

# 备份现有记忆
cp -r ~/.openclaw/workspace/default/memory ./memory_backup
# 重建向量索引（保留原始文本，仅重建 Embedding）
openclaw memory rebuild-index --workspace default --provider ollama
# 验证相似度搜索
openclaw memory search "What was the database choice last week?" --verbose

六、架构设计建议与最佳实践

6.1 记忆分层策略

• 高频变更数据（如临时变量、中间计算结果）：仅保留在 L1，不持久化；使用 session_state 临时存储
• 业务上下文（如当前项目技术栈）：写入 L3 MEMORY.md；在 Agent systemPrompt 中通过模板变量注入：

Current project: {{memory.project_name}}
Tech stack: {{memory.tech_stack}}

• 历史记录（如昨日讨论结论）：依赖 L2 Daily Notes + RAG 检索；定期（每周）将高频访问的 L2 内容升格至 L3

6.2 隐私与合规

敏感信息过滤： 在写入 L2/L3 前，通过实体识别（NER）自动检测并脱敏：

{"memory":{"privacy":{"detectPII": true,
"redactPatterns":["\\b\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}\\b",# 信用卡
"\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"# 邮箱
]}}}

记忆遗忘权（Right to be Forgotten）：

# 删除特定用户所有记忆
openclaw memory purge --user user_123 --all-levels
# 删除特定会话痕迹
openclaw memory purge --session sess_abc --level L1

结语

OpenClaw 的记忆系统通过 L1/L2/L3 的分层架构，巧妙地解决了大模型上下文限制与长期记忆需求之间的矛盾。作为架构师，理解 Daily Notes 的持久化机制、语义检索的向量配置以及会话隔离的安全模型，是构建可靠 Agent 应用的基础。 在实际部署中，建议建立记忆健康度监控（记忆命中率、检索延迟、存储增长率），并定期进行记忆质量审计（清理过期 L2 数据、优化 L3 结构）。只有将记忆系统视为与模型选型同等重要的基础设施，才能构建出真正具备持续学习能力的智能应用。