PythonAI算法
OpenClaw 记忆系统：三层记忆架构与 Daily Notes 机制
本文介绍 OpenClaw 记忆系统的三层架构（工作记忆、短期记忆、长期记忆）及 Daily Notes 机制。通过分层存储解决上下文限制与长期记忆矛盾，支持语义检索、会话隔离及隐私合规。涵盖写入机制、向量配置、故障排查及最佳实践，帮助开发者构建具备持续学习能力的智能 Agent。
本文介绍 OpenClaw 记忆系统的三层架构（工作记忆、短期记忆、长期记忆）及 Daily Notes 机制。通过分层存储解决上下文限制与长期记忆矛盾，支持语义检索、会话隔离及隐私合规。涵盖写入机制、向量配置、故障排查及最佳实践，帮助开发者构建具备持续学习能力的智能 Agent。
在构建生产级 AI Agent 时，一个常被低估的架构难题是状态持久化。无状态的 LLM 调用虽然简单，但无法形成累积性的用户理解；而粗暴的全量历史拼接又很快会触达 Token 上限。OpenClaw 的记忆系统通过分层存储架构与智能归档机制，在上下文窗口限制与长期记忆能力之间建立了工程化的平衡。 本文将从架构实现角度，拆解 OpenClaw 的三层记忆模型、Daily Notes 持久化机制、语义检索配置策略以及多会话隔离原则，帮助开发者设计出既具备持续学习能力、又符合隐私合规要求的记忆方案。
OpenClaw 采用分层越界（Tiered Overflow）设计，将记忆按时间维度与重要性维度划分为三个层级，分别对应不同的存储介质与检索策略。
┌─────────────────────────────────────────────────────────────┐
│ L1 工作记忆 (Working Memory)
│ ┌──────────────────────────────────────────────────────┐
│ │ 存储位置：LLM 上下文窗口 (Context Window)
│ │ 内容形态：原始对话历史 + 系统提示词
│ │ 生命周期：单个会话 (Session)
│ │ 容量限制：受限于模型 Max Tokens (通常 4k-128k)
│ └──────────────────────────────────────────────────────┘
│
│ 溢出 (Overflow)
▼
│ ┌──────────────────────────────────────────────────────┐
│ │ 压缩/摘要 ◄── Pre-compaction Flush
│ └──────────────────────────────────────────────────────┘
│
└──────────────────────────┼──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ L2 短期记忆 (Daily Notes)
│ ┌──────────────────────────────────────────────────────┐
│ │ 存储位置：~/.openclaw/workspace/<ws>/memory/
│ │ YYYY-MM-DD.md
│ │ 内容形态：Markdown 格式的每日会话摘要
│ │ 更新频率：实时追加 + 每日归档
│ │ 保留策略：默认 30 天可配置
│ └──────────────────────────────────────────────────────┘
│
│ 语义提取 (Semantic Extraction)
▼
│ ┌──────────────────────────────────────────────────────┐
│ │ Embedding 向量化 ◄── 关键事实抽取
│ └──────────────────────────────────────────────────────┘
│
└──────────────────────────┼──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ L3 长期记忆 (Episodic Memory)
│ ┌──────────────────────────────────────────────────────┐
│ │ 存储位置：~/.openclaw/workspace/<ws>/agents/
│ │ <agentId>/MEMORY.md
│ │ 内容形态：结构化事实库 + 用户画像标签
│ │ 持久周期：永久（除非手动清理）
│ │ 加载时机：Agent 初始化时注入系统提示词
│ └──────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────┘
L1 工作记忆：热上下文管理 OpenClaw 在内存中维护一个双端队列（Deque）结构，存储当前会话的原始消息。当检测到 Token 消耗超过阈值（默认 80% 的上下文窗口）时，触发智能裁剪：
L2 短期记忆：Daily Notes 机制 以自然日为单位的 Markdown 文件，采用追加写（Append-only）模式：
# 2026-03-09 Session Log
## 10:23 - Project Discussion
User asked about microservices migration strategy. Key points:
- Current monolith uses Python/Django
- Target: Kubernetes + Go microservices
- Concern: Data consistency during migration
## 14:15 - Code Review
Reviewed PR #234: Added circuit breaker pattern to payment service.
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"]
开发者可通过 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）与乐观锁（版本号）结合的策略：
L1 向 L2 的溢流由压缩守护进程自动处理，触发条件包括：
触发条件检查（每轮对话后）
│
▼
┌──────────────────────┐
│ Token 使用率 > 80% ? │──Yes──► 启动 Compaction
└──────────┬───────────┘
│ No
▼
┌──────────────────────┐
│ 会话空闲 > 5 分钟 ? │──Yes──► 启动 Compaction
└──────────┬───────────┘
│ No
▼
保持 L1 现状
压缩算法流程：
原始对话历史 (L1)
│
▼
┌─────────────────────────┐
│ 1. 语义分块
│ - 按主题边界切分对话
│ - 识别独立的事实单元
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ 2. 重要性评分
│ - 用户显式强调 (+2)
│ - 包含决策/结论 (+1)
│ - 闲聊/过渡 (-1)
└──────────┬──────────────┘
│
▼
┌─────────────────────────┐
│ 3. 摘要生成
│ - 高重要性：保留原文
│ - 中重要性：生成摘要
│ - 低重要性：丢弃
└──────────┬──────────────┘
│
▼
写入 L2 (Daily Notes)
OpenClaw 的记忆检索并非简单的关键词匹配，而是基于 Embedding 向量的语义相似度搜索。架构师需在精度、成本与隐私之间做权衡。
memorySearch.provider 支持多种后端，适用场景各异：
| Provider | 模型能力 | 数据隐私 | 成本 | 适用场景 |
|---|---|---|---|---|
| OpenAI | text-embedding-3-large (3072d) | 数据出境 | $0.13/1M tokens | 高精度通用场景 |
| Gemini | embedding-001 | 数据出境 | 免费额度高 | 多语言混合场景 |
| Voyage | voyage-2 (1024d) | 数据出境 | $0.10/1M tokens | 代码/技术文档专用 |
| Ollama | nomic-embed-text (768d) | 本地计算 | 仅硬件成本 | 离线/隐私敏感环境 |
| Local | ONNX 运行时加载自定义模型 | 本地计算 | 硬件成本 | 定制化领域模型 |
配置示例：
{"memorySearch":{"provider":"ollama","model":"nomic-embed-text:latest","baseUrl":"http://localhost:11434","dimensions":768,"metric":"cosine","topK":5,"threshold":0.72}}
文本分块（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 对记忆的访问实施最小权限原则，不同会话类型具有不同的记忆可见性。
Workspace 记忆存储
│
├──► Main Session (1:1 专属会话)
│ │
│ ├──► 加载 MEMORY.md (L3 长期记忆)
│ │ - 用户画像
│ │ - 项目上下文
│ │
│ ├──► 加载本周 Daily Notes (L2)
│ │ - 近期上下文
│ │
│ └──► 实时对话历史 (L1)
│
└──► Group Session (1:N 群组会话)
│
├──► 不加载 MEMORY.md
│ - 防止隐私泄露给其他参与者
├──► 仅加载 Session 创建后的对话历史
└──► 可选：共享白板 (Shared Context)
- 显式授权的知识库
安全隔离原理：
当需要在 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"，以下是系统性排查路径。
症状： 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
症状： 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"}}}
症状： 语义搜索返回无关内容，或抛出 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
session_state 临时存储Current project: {{memory.project_name}}
Tech stack: {{memory.tech_stack}}
敏感信息过滤： 在写入 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 结构）。只有将记忆系统视为与模型选型同等重要的基础设施，才能构建出真正具备持续学习能力的智能应用。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online