Files

DESKTOP-72TV0V4\caoxiaozhu 237ab9f6d7 chore: 清理旧版 teams 需求文档

移除已归档的 teams 目录下的需求分析文档

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-13 21:24:42 +08:00

8.7 KiB

Raw Blame History

OpenCLAW 记忆模块调研报告

调研目标

调研 OpenCLAW 的记忆模块（Memory Module）功能，了解其架构设计、核心功能和实现原理。

一、OpenCLAW 简介

OpenCLAW 是一个开源的个人 AI Agent 网关平台（GitHub: https://github.com/openclaw/openclaw），旨在让 AI 成为能实际操作用户设备、拥有持久化记忆并能主动发起任务的私人助理。

二、记忆模块架构设计

2.1 三层记忆架构

OpenCLAW 采用经典的三层类继承架构：

┌─────────────────────────────────────────────┐
│           顶层：导览员（检索层）              │
│     负责处理用户查询，快速找到最相关的记忆    │
├─────────────────────────────────────────────┤
│         中间层：翻译官（嵌入层）              │
│       把文字转化为机器能理解的数学向量       │
├─────────────────────────────────────────────┤
│        底层：书架管理员（存储层）             │
│         负责文本块的入库、上架和盘点         │
└─────────────────────────────────────────────┘

2.2 三层记忆类型

记忆类型	描述	存储方式
短期记忆 (Short-term Context)	当前会话的上下文信息	存于 Context Window
语义记忆 (Semantic Memory)	长期稳定的知识	SQLite + 向量索引
情景记忆 (Episodic Memory)	具体事件和经历	memory/YYYY-MM-DD.md

三、核心功能特性

3.1 混合搜索（Hybrid Search）

OpenCLAW 实现了 BM25 + 向量语义 的混合搜索：

BM25 全文检索：基于 SQLite FTS5 引擎，擅长精确关键词匹配
向量语义检索：通过嵌入模型将文本转化为高维向量，基于余弦相似度捕捉语义关联

权重配置：默认 7:3（语义 70%，精确 30%）

3.2 时间衰减机制

引入指数时间衰减模型，模拟人类记忆的遗忘曲线：

衰减后得分 = 原始得分 × e^(-λ × 天数)

半衰期默认 30 天
30 天后检索权重衰减为原来的一半
60 天后只剩四分之一

常青记忆（Evergreen Memory）：

MEMORY.md（根级记忆文件）不受时间衰减影响
memory/patterns.md 等主题归纳文件也不衰减
按日期命名的记录（如 memory/2024-01-15.md）正常应用衰减

3.3 MMR 重排算法

使用 MMR（Maximal Marginal Relevance，最大边际相关性） 算法进行结果重排，避免信息冗余：

MMR(d) = λ × 相关性(d) - (1-λ) × max(与已选结果的相似度)

采用 Jaccard 集合相似度 替代余弦相似度，计算更轻量。

3.4 多提供商嵌入支持

提供商	默认模型	特点
OpenAI	text-embedding-3-small	业界主流，质量稳定
Gemini	gemini-embedding-001	支持 API Key 自动轮换
Voyage	voyage-4-large	高维度，擅长长文本
Mistral	mistral-embed	多语言能力出色
本地	embeddinggemma-300m (GGUF)	完全离线，数据不出本机

四级降级链条：确保任何环境下都能提供服务

3.5 嵌入缓存与索引重建

Embedding 缓存：以 provider + model + 文本内容哈希 为主键，同一段文本只需计算一次嵌入
原子化重建：采用"双数据库原子交换"策略，索引重建期间用户无感知

3.6 实时同步机制

三条并行的同步通道：

文件监控（chokidar）：实时监听 MEMORY.md 和 memory/ 目录变化，通过防抖机制避免重复触发
会话增量同步：维护 delta 追踪器，只在增量达到阈值时触发更新
定时轮询：兜底机制，确保不会遗漏

3.7 中文检索支持

采用字级别 + bigram 策略：

单字保证召回率
bigram 捕捉常见双字词组合
内置约 80 个中文停用词过滤

四、数据流架构

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  用户输入    │────▶│   混合搜索   │────▶│   MMR重排   │
│  (查询)      │     │ BM25+向量   │     │  去冗余     │
└──────────────┘     └──────────────┘     └──────────────┘
                                                 │
                     ┌───────────────────────────┘
                     ▼
              ┌──────────────┐
              │   时间衰减   │
              │   +常青记忆  │
              └──────────────┘
                     │
                     ▼
              ┌──────────────┐
              │   返回结果   │
              │  给 Agent    │
              └──────────────┘

五、存储结构

workspace/
├── MEMORY.md              # 常青记忆（根级）
├── memory/
│   ├── patterns.md       # 主题归纳（常青）
│   ├── 2024-01-15.md     # 按日期的情景记忆
│   └── ...
└── .claude/
    └── memory/           # SQLite 向量索引
        └── index.db

六、总结与启发

设计哲学

原则	体现
混合优于单一	BM25 和向量搜索各有盲区，融合才能互补
韧性优于性能	四级降级链条确保任何环境下都能提供服务
仿生优于机械	时间衰减与常青记忆模拟人类认知的自然规律
务实优于完美	Jaccard 替代余弦相似度，bigram 替代专业分词

可借鉴点

三层记忆架构：短期/语义/情景记忆分离
混合搜索：BM25 + 向量检索结合
时间衰减：模拟人类遗忘曲线
常青记忆：区分核心知识和时效信息
多级降级：确保服务高可用
实时同步：文件监控 + 增量同步 + 定时轮询

七、参考资料

OpenCLAW 官方 GitHub: https://github.com/openclaw/openclaw
OpenCLAW 记忆系统深度解析: https://zhuanlan.zhihu.com/p/2010072734986702963
OpenCLAW Design Patterns: https://kenhuangus.substack.com/p/the-openclaw-design-patternspart
OpenCLAW 记忆系统架构: https://zhuanlan.zhihu.com/p/2005943466006438841

八、可行性评估（algorithm-dev）

8.1 与现有系统兼容性分析

维度	现有 X-Agents	OpenCLAW	兼容性
存储格式	Markdown 文件	Markdown 文件	✅ 高度兼容
短期记忆	SessionMemory（内存）	sessions/ 目录	✅ 可对齐
长期记忆	AgentMemory（文件）	MEMORY.md	✅ 可对齐
检索机制	无	BM25+向量混合	❌ 需新增
嵌入服务	无	多种 provider	❌ 需新增
分块策略	无	400 token 滑动窗口	❌ 需新增

8.2 工程落地技术难点

嵌入服务集成 - 需要选择嵌入提供者（本地 ONNX vs 远程 API）
向量数据库 - 需要集成 Milvus/Chroma/FAISS 等
混合检索加权融合 - 需要实现 70/30 加权融合算法
分块策略 - 需要实现带重叠的滑动窗口分块
预压缩冲刷 - 需要监控 token 数量并触发自动保存

8.3 可行性结论

✅ 可行性：高

建议方案

方案A（推荐）- 集成 memsearch 库

Zilliz 提取并开源的 Python 库，完全复现 OpenCLAW 记忆架构
支持多种嵌入提供者（推荐本地 ONNX，无需 API key）
支持 Milvus Lite（单用户）/Milvus Server（团队）/Zilliz Cloud（生产）
开箱即用，集成成本低

方案B - 自研轻量级实现

保持现有 Markdown 文件存储
简化检索：仅用关键词搜索或简单向量相似度
开发周期更长，但可控性更高

推荐采用 memsearch 库，可以快速获得成熟的 OpenCLAW 记忆能力，同时保持 Markdown 文件的可读性和版本可控性。

8.4 待确认事项

是否需要新增向量数据库服务？（Milvus Lite vs 自建）
嵌入模型选择本地 ONNX 还是远程 API？
是否需要支持多用户协作场景？

8.7 KiB Raw Blame History Unescape Escape