# https://github.com/MemTensor/MemOS 项目说明书
生成时间：2026-05-31 22:15:58 UTC
## 目录
- [MemOS 简介](#home)
- [快速开始](#quickstart)
- [系统架构](#architecture)
- [记忆层次系统](#memory-layers)
- [技能系统](#skill-system)
- [会话与 Episode 管理](#session-management)
- [检索系统](#retrieval-system)
- [本地插件 (memos-local-plugin)](#local-plugin)
- [云端插件 (OpenClaw Cloud Plugin)](#cloud-plugin)
- [多 Agent 支持与隔离](#multi-agent)
## MemOS 简介
### 相关页面
相关主题：[系统架构](#architecture), [快速开始](#quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md)
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md)
- [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
- [apps/memos-local-plugin/core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md)
- [apps/memos-local-plugin/core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
- [apps/memos-local-plugin/core/logger/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/logger/README.md)
- [examples/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/README.md)
- [apps/openwork-memos-integration/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/README.md)
# MemOS 简介
MemOS（Memory Operating System）是一个面向 AI Agent 的记忆操作系统，旨在为大型语言模型（LLM）提供持久化、层级化的记忆能力。MemOS 由 MemTensor 团队开发，采用 Apache 2.0 开源许可，支持本地部署和云端服务两种模式。
## 核心定位
MemOS 将 AI Agent 的记忆管理从分散的工具调用提升为系统级能力，实现了：
- **多层次记忆抽象**：从 L1 执行痕迹到 L2 策略归纳，再到 L3 世界模型，形成完整的记忆层次结构
- **反馈驱动的自进化**：通过自然语言反馈持续优化记忆质量，无需人工干预
- **异步高性能调度**：基于 Redis Streams 的任务调度器，支持高并发场景下的毫秒级延迟
- **多知识库管理**：支持多个可组合的记忆立方体（MemCube），实现跨用户、项目和 Agent 的隔离与共享
资料来源：[README.md:1-20](https://github.com/MemTensor/MemOS/blob/main/README.md)
## 系统架构
### 整体架构图
```mermaid
graph TB
subgraph "应用层"
HA[Hermes Agent]
OC[OpenClaw]
OW[Openwork]
end
subgraph "适配器层"
HA_AD[Hermes Adapter]
OC_AD[OpenClaw Adapter]
end
subgraph "核心引擎 core/"
RET[检索 Retrieval]
CAP[捕获 Capture]
FB[反馈 Feedback]
SK[技能 Skill]
L1[L1 记忆]
L2[L2 策略]
L3[L3 世界模型]
end
subgraph "存储层 storage/"
DB[(SQLite)]
VEC[(向量索引)]
REDIS[(Redis)]
end
HA --> HA_AD
OC --> OC_AD
OW --> HA_AD
HA_AD --> RET
OC_AD --> RET
RET --> CAP
CAP --> L1
L1 --> FB
FB --> SK
SK --> L2
L2 --> L3
HA_AD --> DB
OC_AD --> DB
RET --> VEC
CAP --> REDIS
```
### 核心模块划分
| 模块 | 路径 | 职责说明 |
|------|------|----------|
| retrieval | `core/retrieval/*` | 三层记忆检索引擎（Tier-1/2/3） |
| feedback | `core/feedback/*` | 反馈分类与决策修复生成 |
| skill | `core/skill/*` | 技能生命周期管理与打包 |
| memory/l1 | `core/memory/l1/*` | L1 执行痕迹捕获与存储 |
| pipeline | `core/pipeline/*` | 记忆管线编排与调度 |
| storage | `core/storage/*` | SQLite 数据库抽象层 |
| embedding | `core/embedding/*` | 向量嵌入服务 |
| llm | `core/llm/*` | LLM 接口封装 |
资料来源：[apps/memos-local-plugin/core/logger/README.md:1-25](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/logger/README.md)
## 三层记忆系统
MemOS 采用独特的三层记忆架构，分别对应不同的认知层级：
### Tier-1：技能记忆（Skills）
存储已结晶化的技能程序，包含：
- `procedureJson`：结构化步骤、参数、示例和前置条件
- `invocationGuide`：可供 Agent 直接引用的 markdown 调用指南
- `eta`（经验值）：衡量技能可靠性的指标，范围 0-1
技能通过 `applyFeedback` 生命周期管理，支持以下状态转换：
| 信号 | η 影响 | 状态可能变化 |
|------|--------|--------------|
| trial.pass | Beta 后验 `(passed+1)/(attempts+2)` | probationary → active |
| trial.fail | Beta 后验 | probationary → retired |
| user.positive | η += etaDelta | retired → probationary |
| user.negative | η -= etaDelta | 任意 → retired |
| reward.updated | 0.7·η + 0.3·newGain | 任意 → retired |
资料来源：[apps/memos-local-plugin/core/skill/README.md:1-45](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### Tier-2：执行痕迹（Traces）
记录 Agent 的完整执行轨迹，支持：
- 向量相似度搜索（`vec_summary`、`vec_action`）
- FTS5 全文检索（英文及 CJK 字符 ≥ 3 字符）
- 结构化匹配（错误签名verbatim replay）
- 模式匹配（短中文词/动词的 2-char fallback）
每个最终化的 episode 至少产生 1 条 L1 trace，即使 capture 失败也会生成 stub，确保时间线完整。
资料来源：[apps/memos-local-plugin/core/memory/l1/README.md:1-40](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md)
### Tier-3：世界模型（World Model）
存储环境拓扑和推理规则，支持深度推理时的上下文检索。
## 检索引擎
`core/retrieval` 模块是 MemOS 的检索核心，提供五个入口点：
| 入口点 | 触发场景 |
|--------|----------|
| turnStart | 用户回合开始 |
| toolDriven | 工具调用驱动 |
| subAgent | 子 Agent 启动 |
| decisionRepair | 决策修复事件 |
| skillRecall | 技能召回 |
### 多通道混合排名
检索采用 Reciprocal Rank Fusion（RRF）融合多个通道：
| 通道 | 数据源 | 匹配方式 | 用途 |
|------|--------|----------|------|
| semantic_summary | `traces.vec_summary` | cosine | 语义召回用户/助手对话 |
| semantic_action | `traces.vec_action` | cosine | 语义召回 Agent 动作序列 |
| vec | `skills.vec`, `world_model.vec` | cosine | Tier-1/Tier-3 语义召回 |
| fts | FTS5 trigram MATCH | 关键词精确匹配 | 英文及 CJK ≥ 3 字符 |
| pattern | `LIKE %term%` | 2-char 中文bigram | 短中文名/动词 fallback |
| structural | `instr(error_signatures_json)` | verbatim | 错误签名回放 |
排名后应用自适应相关阈值：`topRelevance · relativeThresholdFloor`（默认 0.4），低于阈值的候选被丢弃。
资料来源：[apps/memos-local-plugin/core/retrieval/README.md:1-60](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
## 反馈与自进化系统
`core/feedback` 模块实现反馈驱动的记忆优化：
### 反馈分类
- **trial.pass/fail**：Agent 试运行结果反馈
- **user.positive/negative**：用户显式评价
- **reward.updated**：奖励信号更新
### 决策修复（Decision Repair）
对于高频失败决策，系统自动生成修复指南：
```ts
{
context_hash: string, // 锚点哈希
preference: string, // 应该做什么
anti_pattern: string, // 应该避免什么
high_value_trace_ids: string[], // 高价值证据
low_value_trace_ids: string[], // 低价值证据
validated: boolean // UI 审核状态
}
```
策略通过 `@repair {json}` 标签内联到 `policy.boundary`，技能打包器在结晶/重建时拾取。
资料来源：[apps/memos-local-plugin/core/feedback/README.md:1-50](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md)
## 存储层
### SQLite 配置
| Pragma | 设置值 | 用途 |
|--------|--------|------|
| journal_mode | WAL | 允许并发读取（viewer）与写入共存 |
| synchronous | NORMAL | WAL 模式下的良好平衡 |
| foreign_keys | ON | 强制引用完整性 |
| temp_store | MEMORY | 避免 CTE 临时文件 |
| busy_timeout | 5000 | 跨进程竞争容错（毫秒） |
### 数据库入口
```ts
import { openDb, runMigrations, makeRepos } from "./core/storage/index.js";
const db = openDb({ filepath: "/path/to/memos.db", agent: "openclaw" });
runMigrations(db);
const repos = makeRepos(db);
repos.traces.insert({...});
const top = repos.traces.searchByVector(queryVec, 5);
```
资料来源：[apps/memos-local-plugin/core/storage/README.md:1-45](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
## 部署模式
### 本地部署（memos-local-plugin）
完全本地化运行，无需网络依赖：
- **存储**：SQLite + 向量索引
- **LLM 接口**：支持 Ollama 自托管
- **适用场景**：Hermes Agent、OpenClaw 本地开发
### 云端部署（MemOS Cloud）
托管记忆服务：
- **存储**：云端数据库
- **特点**：72% 更低的 token 消耗、多 Agent 记忆共享
- **适用场景**：OpenClaw 云端网关
### Openwork 集成
Openwork（开源 AI 桌面 Agent）可通过 MemOS API key 接入长期记忆功能，相关记忆自动注入系统提示，任务完成后自动保存新记忆。
资料来源：[apps/openwork-memos-integration/README.md:1-80](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/README.md)
## 配置管理
所有算法参数位于 `config.yaml` 的 `algorithm.*` 路径下：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| algorithm.retrieval.tier1TopK | - | Tier-1 召回数量 |
| algorithm.retrieval.tier2TopK | - | Tier-2 召回数量 |
| algorithm.retrieval.tier3TopK | - | Tier-3 召回数量 |
| algorithm.retrieval.relativeThresholdFloor | 0.4 | 自适应相关阈值 |
| algorithm.feedback.* | - | 反馈处理参数 |
| logging.redact.extraKeys | - | 日志脱敏额外键 |
| logging.redact.extraPatterns | - | 日志脱敏额外模式 |
资料来源：[apps/memos-local-plugin/core/retrieval/README.md:70-80](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
## 已知问题与社区热点
### 多 Agent 隔离问题
社区报告了 `patternSearch` 缺少 `ownerFilter` 导致的记忆隔离泄漏问题，影响多 Agent 场景下的中文查询和短英文查询（Issue #1361）。相关问题还包括 `memory_search` 工具硬编码 `owner` 默认值为 `"agent:main"` 而非当前 Agent（Issue #1318）。
### Daemon 模式启动问题
`core.init()` 在处理脏 episode 重评分时会阻塞 HTTP viewer 启动，社区已提交多个相关 Issue（#1839、#1840、#1841）进行修复。
### 大 Episode 处理
大型合并 episode 可能触发 L2/L3/skill-evolution 级联风暴，导致 OpenClaw 会话停滞（Issue #1755）。
### 记忆迁移功能
社区请求增加修改已有记忆 `agent_id` 的功能，便于系统迁移时保持记忆完整性（Issue #1288）。
### Ollama 原生支持
用户请求为 `memos-local-openclaw` 添加原生 Ollama provider 支持，包括 embedding 和 summarizer，实现真正的全本地化 MemOS 部署（Issue #1231）。
## 版本演进
| 版本 | 发布日期 | 主要变更 |
|------|----------|----------|
| v2.0.17 | 2026-05 | web/ 重命名为 viewer/、embedding 维度推断修复 |
| v2.0 | 2026-05-09 | memos-local-plugin 2.0 正式版发布，支持 Hermes Agent 和 OpenClaw |
| v1.0.0 | 2025-08-07 | MemCube 首次发布，引入 LongMemEval 评估 |
资料来源：[README.md:50-100](https://github.com/MemTensor/MemOS/blob/main/README.md)
## 相关资源
- 文档站点：https://memos-docs.openmem.net
- 论文：https://arxiv.org/abs/2507.03724
- Discord 社区：https://discord.gg/Txbx3gebZR
- GitHub Issues：https://github.com/MemTensor/MemOS/issues
---
## 快速开始
相关源码文件
以下源码文件用于生成本页说明：
- [docker/docker-compose.yml](https://github.com/MemTensor/MemOS/blob/main/docker/docker-compose.yml)
- [docker/.env.example](https://github.com/MemTensor/MemOS/blob/main/docker/.env.example)
- [docs/cn/open_source/getting_started/installation.md](https://github.com/MemTensor/MemOS/blob/main/docs/cn/open_source/getting_started/installation.md)
- [docs/en/open_source/getting_started/installation.md](https://github.com/MemTensor/MemOS/blob/main/docs/en/open_source/getting_started/installation.md)
- [apps/memos-local-plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md)
# 快速开始
本文档帮助你在本地或服务器环境中快速部署和运行 MemOS。MemOS 是一个分层记忆系统，支持 L1 轨迹、L2 策略、L3 世界模型和技能结晶化，通过自进化机制让 AI Agent 持续改进。
## 环境要求
| 组件 | 最低要求 | 推荐配置 |
|------|----------|----------|
| Docker | 20.10+ | 24.0+ |
| Docker Compose | 2.0+ | 2.20+ |
| 内存 | 4 GB | 8 GB+ |
| 磁盘 | 10 GB | 20 GB+ |
| Python | 3.10+ | 3.11+ |
| Node.js | 18+ | 20 LTS (memos-local-plugin) |
资料来源：[docker/docker-compose.yml:1-50]()
## 安装方式
### 方式一：Docker 快速部署（推荐）
这是最简洁的部署方式，适合生产环境和开发测试。
```bash
# 克隆仓库
git clone https://github.com/MemTensor/MemOS.git
cd MemOS
# 进入 Docker 目录
cd docker
# 复制环境变量配置
cp .env.example .env
# 编辑 .env 文件配置必要参数
nano .env
# 启动所有服务
docker-compose up -d
```
#### 环境变量配置
| 变量名 | 说明 | 示例 |
|--------|------|------|
| `REDIS_HOST` | Redis 服务地址 | `localhost` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql://user:pass@localhost:5432/memos` |
| `API_KEY` | MemOS API 认证密钥 | `your-secret-key` |
| `LOG_LEVEL` | 日志级别 | `info` / `debug` |
| `MEMOS_PLUGIN_MODE` | 插件运行模式 | `local` / `cloud` |
资料来源：[docker/.env.example:1-30]()
### 方式二：本地开发部署
适用于需要修改源码或进行二次开发的高级用户。
```bash
# 安装后端依赖
pip install -e .
# 安装前端依赖 (如需要)
cd apps/memos-local-plugin
npm install
# 配置环境变量
cp .env.example .env
```
## memos-local-plugin 快速上手
memos-local-plugin 是 MemOS 的本地记忆插件，兼容 Hermes Agent 和 OpenClaw，支持 100% 本地运行。
### 安装插件
```bash
# 使用安装脚本（Linux/macOS）
curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh | bash
# 或使用 PowerShell（Windows）
powershell -ExecutionPolicy Bypass -File install.ps1
```
资料来源：[apps/memos-local-plugin/package.json:1-20]()
### 运行 Bridge 服务
```bash
# 开发模式（实时日志）
npm run bridge
# 守护进程模式（后台运行 + HTTP 查看器）
npm run bridge:daemon
```
> **注意**：守护进程模式下，HTTP 查看器在 `core.init()` 完成前不会启动。如果 `core.init()` 因大量 LLM/embedding API 调用而阻塞，查看器启动会延迟。详见 [Issue #1839](https://github.com/MemTensor/MemOS/issues/1839)。
### 启动本地查看器
```bash
# 开发模式
npm run viewer:dev
# 构建生产版本
npm run build:viewer
```
## 配置指南
### 配置文件位置
| 组件 | 配置文件路径 |
|------|---------------|
| memos-local-plugin | `config.yaml` |
| Docker 部署 | `docker/.env` |
| 插件配置 UI | Gateway 配置目录下 |
### 核心配置项
```yaml
# config.yaml
algorithm:
retrieval:
tier1TopK: 5 # Tier-1 技能检索返回数量
tier2TopK: 10 # Tier-2 轨迹检索返回数量
tier3TopK: 3 # Tier-3 世界模型检索返回数量
relativeThresholdFloor: 0.4 # 相对相关度阈值
logging:
level: info
redact:
extraKeys: [] # 额外需要脱敏的密钥
skill:
minEta: 0.3 # 技能最小可信度
retireEta: 0.1 # 技能自动退休阈值
```
资料来源：[core/retrieval/README.md:60-80]()
### LLM Provider 配置
MemOS 支持多种 LLM 提供者：
| Provider | Embedding | Summarizer | 本地支持 |
|----------|-----------|------------|---------|
| OpenAI | ✅ | ✅ | ❌ |
| Anthropic | ❌ | ✅ | ❌ |
| Ollama | ✅ | ✅ | ✅ |
| 自托管 API | 可配置 | 可配置 | ✅ |
> **用户需求**：社区已有功能请求添加原生 Ollama 支持，以实现完全本地化部署。详见 [Issue #1231](https://github.com/MemTensor/MemOS/issues/1231)。
## 首次运行流程
```mermaid
graph TD
A[启动 MemOS] --> B{初始化数据库}
B -->|首次运行| C[执行数据库迁移]
B -->|已存在| D[跳过迁移]
C --> E[加载配置]
D --> E
E --> F{启动模式}
F -->|Daemon| G[启动 Bridge]
F -->|前台| H[直接运行]
G --> I[后台初始化 core.init]
H --> J[等待初始化完成]
I --> K[启动 HTTP 查看器]
J --> L[系统就绪]
K --> L
```
### 数据库初始化
```bash
# 查看迁移状态
npm run db:migrate:status
# 执行迁移
npm run db:migrate
# 查看已应用的迁移
sqlite3 memos.db "SELECT name FROM schema_migrations;"
```
### 验证安装
启动后访问以下端点验证服务状态：
```bash
# 检查健康状态
curl http://localhost:3000/health
# 检查 API 版本
curl http://localhost:3000/api/version
# 查看记忆统计
curl http://localhost:3000/api/stats
```
## 常见问题排查
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 查看器无法启动 | `core.init()` 阻塞 | 使用前台模式 `npm run bridge`，避免守护进程 |
| API 请求超时 | LLM/Embedding 服务响应慢 | 增加超时配置或检查网络连接 |
| 记忆隔离泄漏 | `ownerFilter` 缺失 | 确保使用 v4.x+ 版本，配置正确的 `agent_id` |
| 大量合并 episodes 触发风暴 | L2/L3 处理过载 | 调整 `capture` 批处理大小，限制并发 |
资料来源：[Issue #1755](https://github.com/MemTensor/MemOS/issues/1755)，[Issue #1361](https://github.com/MemTensor/MemOS/issues/1361)
### 日志查看
```bash
# 查看实时日志
tail -f logs/memos.log
# 查看错误日志
grep "ERROR" logs/memos.log
# 查看特定模块日志
grep "core.retrieval" logs/memos.log
```
## 记忆迁移
如需在不同系统间迁移记忆数据，可通过修改已有记忆的 `agent_id` 实现：
```bash
# 导出记忆
memos-cli export --agent old-agent --output memories.json
# 修改 agent_id 后导入
memos-cli import --agent new-agent --input memories.json
```
此功能由 [Issue #1288](https://github.com/MemTensor/MemOS/issues/1288) 引入。
## 下一步
- [配置高级选项](CONFIG-ADVANCED.md) - 深入调优检索和记忆算法
- [记忆反馈与修正](FEEDBACK.md) - 使用自然语言反馈精炼记忆
- [技能生命周期](SKILL.md) - 理解技能从诞生到退休的完整流程
- [检索架构](RETRIEVAL.md) - 深入了解三层检索系统
---
## 系统架构
### 相关页面
相关主题：[记忆层次系统](#memory-layers), [技能系统](#skill-system), [检索系统](#retrieval-system)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin/core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md)
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
- [apps/memos-local-plugin/core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
- [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md)
- [apps/memos-local-plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md)
- [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md)
- [examples/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/README.md)
# 系统架构
## 概述
MemOS 是一个多层次记忆管理系统，旨在为 AI Agent 提供长期记忆能力。该系统采用分层架构设计，支持从原始轨迹追踪（L1）到策略归纳（L2）再到世界模型抽象（L3）的完整记忆进化流程。资料来源：[README.md:1-20]()
系统核心特性包括：
- **分层记忆管理**：L1 轨迹、L2 策略、L3 世界模型的多层次抽象
- **异步调度**：基于 Redis Streams 的任务调度器，支持毫秒级延迟
- **本地优先存储**：SQLite WAL 模式，支持并发读写
- **反馈驱动的记忆修正**：通过自然语言反馈持续优化记忆质量
- **多 Agent 隔离**：基于 ownerFilter 的记忆隔离机制
## 整体架构
```mermaid
graph TB
subgraph "应用层"
OpenClaw[OpenClaw Gateway]
Hermes[Hermes Agent]
Cloud[MemOS Cloud]
end
subgraph "memos-local-plugin 核心"
Bridge[bridge.cts 桥接层]
Pipeline[memory-core Pipeline]
Viewer[HTTP Viewer]
end
subgraph "核心子系统"
Capture[core/capture 捕获]
L1[core/memory/l1 L1存储]
L2[core/policy L2策略]
L3[core/world-model L3抽象]
Skill[core/skill 技能系统]
Retrieval[core/retrieval 检索]
Feedback[core/feedback 反馈]
end
subgraph "存储层"
SQLite[(SQLite WAL)]
FTS[FTS5 全文索引]
Vector[Vector 向量索引]
end
subgraph "外部服务"
LLM[LLM Provider]
Embed[Embedding Provider]
Redis[(Redis Streams)]
end
OpenClaw --> Bridge
Hermes --> Bridge
Cloud --> Bridge
Bridge --> Pipeline
Pipeline --> Capture
Capture --> L1
Pipeline --> L2
Pipeline --> L3
Pipeline --> Skill
Pipeline --> Retrieval
Retrieval --> Feedback
Pipeline --> SQLite
SQLite --> FTS
SQLite --> Vector
LLM --> Pipeline
Embed --> Pipeline
Redis --> Pipeline
```
## 核心子系统
### L1 记忆层
L1 是系统的基础存储层，负责存储原始轨迹和执行过程中的轻量级富化数据。资料来源：[apps/memos-local-plugin/core/memory/l1/README.md:1-30]()
**设计原则**：
- L1 采用与捕获管道（capture pipeline）捆绑的架构，而非独立目录结构
- 仅负责存储和写入时的轻量富化（标签、错误签名），无归纳或聚类逻辑
- 每个最终化 episode 至少产生 1 条 L1 轨迹，失败捕获仍会发出轨迹存根
**关键组件**：
| 组件 | 文件路径 | 功能 |
|------|----------|------|
| 轨迹捕获 | `core/capture/trace.ts` | 原始执行轨迹存储 |
| 错误签名 | `core/capture/error-signature.ts` | 结构化匹配输入 |
| 领域标签 | `core/capture/tagger.ts` | 领域标签富化 |
| 轨迹存储 | `traces.ts` | 轨迹数据持久化 |
**不变量**：
- 每个最终化 episode 产生 ≥ 1 条 L1 轨迹
- `TraceRow.errorSignatures` 在存储层始终为 `string[]`（默认 `'[]'`）
- `TraceRow.value` 初始值为 0，仅由 `core/reward/backprop.ts` 修改
### L2 策略层
L2 负责从高价值轨迹中归纳策略模式。与 L1 不同，L2 采用完整的订阅者/归纳器/签名架构，包含独立的生命周期管理。资料来源：[apps/memos-local-plugin/core/memory/l1/README.md:25-40]()
### L3 世界模型层
L3 负责环境拓扑和推理规则的抽象，为深度推理提供世界模型支撑。与 L2 类似，采用完整的算法密集型架构。
### 技能系统（Skill）
技能系统管理可复用的技能结晶，其生命周期由 `applyFeedback` 函数控制。资料来源：[apps/memos-local-plugin/core/skill/README.md:1-50]()
**技能数据结构**：
| 字段 | 描述 |
|------|------|
| `procedureJson` | 结构化步骤、参数、示例、前置条件 |
| `invocationGuide` | 简洁的 Markdown 提示块 |
| `η` (eta) | 技能效能值，初始由策略增益种子化 |
| `vec` | 技能摘要+触发器的嵌入向量 |
| `sourcePolicyIds` | 源策略 ID 集合 |
**技能状态转换**：
| 信号 | η 效果 | 状态变更 |
|------|--------|----------|
| `trial.pass` | Beta 后验 `(passed+1)/(attempts+2)` | probationary → active |
| `trial.fail` | Beta 后验 | probationary → retired |
| `user.positive` | `η += etaDelta` | retired → probationary |
| `user.negative` | `η -= etaDelta` | any → retired |
| `reward.updated` | 混合 `0.7·η + 0.3·newGain` | any → retired |
## 检索系统
检索系统将用户输入转换为 `InjectionPacket`，通过多通道混合检索（向量、余弦相似度、FTS5、模式匹配）返回相关记忆。资料来源：[apps/memos-local-plugin/core/retrieval/README.md:1-80]()
### 三层检索架构
| 层级 | 源表 | 查询通道 | 回答问题 |
|------|------|----------|----------|
| Tier 1 | `skills` | `vec` 余弦 | "我有执行这个任务的技能吗？" |
| Tier 2 | `traces`, rollup | `vec_summary`, `vec_action`, `fts`, `pattern`, `structural` | "上次尝试这个时，什么方法有效？" |
| Tier 3 | `world_model` | `vec`, `fts`, `pattern` | "我实际在什么环境中操作？" |
### 检索入口点
```ts
import {
turnStartRetrieve, // 对话轮次开始 — 完整 Tier 1+2+3
toolDrivenRetrieve, // memos_search / memos_timeline 等工具驱动
skillInvokeRetrieve, // 技能调用前触发
subAgentRetrieve, // 子 Agent 伴随任务提示创建
repairRetrieve, // N 次工具失败 → 反模式召回
} from "@memtensor/memos-local-plugin/core/retrieval";
```
### 多通道排名算法
检索系统使用**递归排名融合（RRF）**算法整合多个检索通道：
```mermaid
graph LR
Query[查询] --> Vec[向量检索]
Query --> FTS[FTS5 全文检索]
Query --> Pattern[模式匹配]
Query --> Struct[结构化检索]
Vec --> RRF[RRF 排名融合]
FTS --> RRF
Pattern --> RRF
Struct --> RRF
RRF --> Threshold[自适应阈值过滤]
Threshold --> MMR[最大边际相关性]
MMR --> Result[InjectionPacket]
```
**排名公式**：多通道命中的行获得一个 `ChannelRank`，排名器对各通道求和 `1 / (k + rank_i + 1)`，同时命中向量和 FTS 的结果获得显著更高的 RRF 分数。
### 自适应相关阈值
排名器计算**顶部相关性**后，丢弃所有低于 `topRelevance · relativeThresholdFloor`（默认 `0.4`）的候选。这是一种自适应的绝对 `minTraceSim` 地板值变体。
## 存储架构
### SQLite WAL 模式
存储层采用 SQLite 作为本地数据库核心，启用 WAL（Write-Ahead Logging）模式支持并发读写。资料来源：[apps/memos-local-plugin/core/storage/README.md:1-50]()
**关键 Pragma 配置**：
| Pragma | 值 | 原因 |
|--------|-----|------|
| `journal_mode` | WAL | 允许并发读取器（Viewer）在守护进程写入时工作 |
| `synchronous` | NORMAL | 良好的 WAL 权衡；提升到 FULL 成本增加约 2 倍写入 |
| `foreign_keys` | ON | 强制引用完整性 |
| `temp_store` | MEMORY | 避免 CTE 的临时文件折腾 |
| `busy_timeout` | 5000 | 跨进程忙等待容忍 |
### 数据表结构
```
core/storage/
├── schema.ts 表定义
├── episodes.ts Episode 记录
├── traces.ts 轨迹 + 向量搜索
├── policies.ts 策略 + 向量搜索
├── world_model.ts 世界模型 + 向量搜索
├── skills.ts 技能 + 向量搜索
├── feedback.ts 反馈记录
├── decision_repairs.ts 决策修复
├── candidate_pool.ts 候选池
├── audit.ts 审计日志
├── kv.ts 键值存储
└── migrations.ts 迁移记录
```
### 向量搜索集成
系统为 `traces`、`policies`、`world_model`、`skills` 表提供向量搜索能力，支持语义相似度检索。
## 反馈系统
反馈系统通过自然语言反馈修正记忆，支持两种路径：用户直接反馈和基于轨迹的自动反馈。资料来源：[apps/memos-local-plugin/core/feedback/README.md:1-30]()
### 反馈处理流程
```mermaid
graph TD
UserFeedback[用户反馈] --> Signal[反馈信号]
TraceAnalysis[轨迹分析] --> Signal
Signal --> Evaluate{信号类型}
Evaluate -->|trial.pass| UpdateEta[更新 η - 正向]
Evaluate -->|trial.fail| UpdateEtaNeg[更新 η - 负向]
Evaluate -->|user.positive| UpdateEta[更新 η - 正向]
Evaluate -->|user.negative| UpdateEtaNeg[更新 η - 负向]
Evaluate -->|reward.updated| BlendEta[混合 η 更新]
UpdateEta --> SkillEvent[SkillEventBus 事件]
UpdateEtaNeg --> SkillEvent
BlendEta --> SkillEvent
SkillEvent --> SkillUpdate[技能状态变更]
SkillUpdate --> Storage[存储更新]
```
### 测试覆盖
| 测试文件 | 覆盖范围 |
|----------|----------|
| `classifier.test.ts` | 形状 + 偏好提取 |
| `evidence.test.ts` | 高/低分裂、关键词宽松、capTrace 尾部保留 |
| `synthesize.test.ts` | LLM 路径、无效 JSON、传输失败、模板回退、置信度钳制 |
| `events.test.ts` | 总线契约 + 监听器隔离 |
| `feedback.integration.test.ts` | 端到端 `runRepair` 真实 SQLite |
| `subscriber.test.ts` | 突发→队列运行、用户反馈、并发突发序列化 |
## 桥接层（Bridge）
Bridge 是 memos-local-plugin 与宿主 Agent（OpenClaw/Hermes）之间的通信层，负责协议转换和生命周期管理。资料来源：[apps/memos-local-plugin/README.md:1-30]()
### 运行模式
| 模式 | 命令 | 说明 |
|------|------|------|
| 前台 | `npm run bridge` | 阻塞运行，日志输出到控制台 |
| 守护 | `npm run bridge:daemon` | 后台运行，支持 HTTP Viewer |
### 守护进程模式已知问题
社区反馈揭示了守护模式下的多个问题（相关 Issue: #1839, #1840, #1841）：
- **启动阻塞**：`core.init()` 在进行 LLM/Embedding API 调用时会阻塞，导致 HTTP Viewer 无法及时启动
- **进程级联**：大型合并 episode 触发 L2/L3/Skill 演化风暴，导致 OpenClaw 会话停滞
- **API 速率限制螺旋**：dirty episode 重新评分期间可能触发大量 API 调用
## 插件适配器
### OpenClaw 适配器
适用于 OpenClaw Gateway 的生命周期钩子，支持云端和本地两种部署模式。
### Hermes Agent 适配器
适用于 Hermes Agent（OpenClaw 的独立架构），提供本地优先的记忆能力。
**MCP 支持**（相关 Issue: #1472）：
- 记忆删除的 MCP 工具支持
- 记忆过滤与自定义标签
## 异步调度
系统支持通过 MemScheduler 进行异步记忆操作，基于 Redis Streams 实现毫秒级延迟。资料来源：[examples/README.md:1-20]()
**调度器特性**：
- 任务优先级支持
- 自动恢复机制
- 基于配额的调度策略
- 队列隔离
## 配置架构
### 检索算法配置
所有检索算法参数位于 `algorithm.retrieval.*` 配置路径下：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `tier1TopK` | - | Tier 1 检索返回数量 |
| `tier2TopK` | - | Tier 2 检索返回数量 |
| `tier3TopK` | - | Tier 3 检索返回数量 |
| `relativeThresholdFloor` | `0.4` | 自适应相关阈值地板值 |
| `weightCosine` | - | 余弦权重 |
| `weightPriority` | - | 优先级权重 |
详细高级配置参见 `docs/CONFIG-ADVANCED.md`。
## 部署模式
### 本地插件部署（memos-local-plugin）
适用于需要 100% 本地部署的场景：
```bash
npm install
npm run bridge # 前台模式
npm run bridge:daemon # 守护模式
```
**平台支持**：
- macOS (Apple Silicon) — 官方支持
- Windows — 实验性支持
**功能特性**：
- 混合检索（FTS5 + 向量）
- 智能去重
- 分层技能演化
- 多 Agent 协作
- 零云依赖
### 外部集成
**Openwork 集成**：Openwork 可连接 MemOS 提供长期记忆能力，设置 MemOS API key 后，相关记忆会被注入系统提示，新记忆会在任务完成后保存。资料来源：[apps/openwork-memos-integration/README.md:1-50]()
## 安全性考量
### 多 Agent 记忆隔离
系统通过 `ownerFilter` 实现多 Agent 场景下的记忆隔离。社区报告（Issue #1361, #1318）揭示了以下潜在漏洞：
- `patternSearch` 分支缺少 `ownerFilter` 导致记忆隔离泄漏
- `memory_search` 工具硬编码 `owner` 默认值为 `"agent:main"` 而非当前 Agent
**受影响范围**：多 Agent 协作场景下的中文查询和短英文查询
### 敏感信息处理
日志系统提供敏感信息脱敏功能，支持通过 `logging.redact.extraKeys` / `extraPatterns` 添加自定义脱敏规则。资料来源：[apps/memos-local-plugin/core/logger/README.md:1-30]()
## 开发与测试
### 项目结构
```
apps/
├── memos-local-plugin/ 本地插件主包
│ ├── core/ 核心子系统
│ │ ├── capture/ 捕获管道
│ │ ├── feedback/ 反馈处理
│ │ ├── memory/l1/ L1 存储
│ │ ├── pipeline/ 记忆核心管道
│ │ ├── retrieval/ 检索系统
│ │ ├── skill/ 技能管理
│ │ ├── storage/ 存储层
│ │ └── logger/ 日志系统
│ ├── bridge.cts 桥接层入口
│ └── viewer/ HTTP 查看器
├── memos-cloud-openclaw-plugin/ 云端 OpenClaw 插件
├── openwork-memos-integration/ Openwork 集成
└── ...
```
### 测试命令
| 命令 | 用途 |
|------|------|
| `npm test` | 运行所有测试 |
| `npm run test:unit` | 单元测试 |
| `npm run test:integration` | 集成测试 |
| `npm run test:e2e` | 端到端测试 |
| `npm run lint` | TypeScript 类型检查 |
---
## 记忆层次系统
### 相关页面
相关主题：[系统架构](#architecture), [技能系统](#skill-system), [会话与 Episode 管理](#session-management)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin/core/memory/l1](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1)
- [apps/memos-local-plugin/core/memory/l2](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l2)
- [apps/memos-local-plugin/core/memory/l3](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l3)
- [apps/memos-local-plugin/core/capture](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/capture)
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
- [apps/memos-local-plugin/core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
# 记忆层次系统
## 概述
MemOS 采用分层记忆架构，将记忆按照抽象层级组织为 **L1（轨迹层）**、**L2（策略层）** 和 **L3（世界模型层）** 三个核心层次，辅以从 L2 提炼出的 **Skills（技能层）**。这一设计遵循 V7 文档中定义的"层次化记忆检索"（Hierarchical Memory Retrieval）理念，每一层回答不同粒度的问题：
| 层次 | 问题 | 抽象级别 | 数据来源 |
|------|------|----------|----------|
| **L1 轨迹** | 上一次执行时具体发生了什么？ | 步骤级 | 原始对话/工具调用轨迹 |
| **L2 策略** | 这类任务的标准操作流程是什么？ | 任务级 | 高价值轨迹归纳 |
| **L3 世界模型** | 当前环境的基本拓扑和约束是什么？ | 推理级 | 环境信息抽象 |
| **Skills 技能** | 遇到 X 任务时应该调用哪个已知流程？ | 可执行级 | L2 策略结晶 |
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
---
## 系统架构总览
```mermaid
graph TD
subgraph "Agent 运行时"
A[用户对话/工具调用]
end
subgraph "记忆捕获 (Capture)"
A --> B[Episode 封存]
B --> C[轨迹提取]
C --> D[Reward 打分]
end
subgraph "记忆层次"
C --> E[L1 Traces 轨迹层]
D --> F[L2 Policies 策略层]
F --> G[L3 World Model 世界模型层]
F --> H[Skills 技能层]
end
subgraph "记忆检索 (Retrieval)"
E --> I[Tier 1: 技能检索]
E --> J[Tier 2: 轨迹检索]
G --> K[Tier 3: 世界模型检索]
I --> L[Ranker 排序]
J --> L
K --> L
L --> M[InjectionPacket 注入包]
end
M --> N[System Prompt]
```
---
## L1 轨迹层
### 设计目标
L1 是最底层的记忆单元，记录每次 episode（任务会话）的原始轨迹。每当 agent 完成一次任务（无论成功或失败），系统都会生成对应的轨迹记录。轨迹包含对话内容、工具调用序列、执行结果等原始信息，并附加轻量级元数据（标签、错误签名等）。
资料来源：[core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md)
### 数据模型
L1 轨迹的核心字段定义在 `traces` 表中：
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT PRIMARY KEY | 轨迹唯一标识 |
| `agent` | TEXT | 所属 agent 标识 |
| `episodeId` | TEXT | 所属 episode ID |
| `value` | REAL | 奖励值（初始为 0） |
| `vecSummary` | BLOB | 摘要文本向量 |
| `vecAction` | BLOB | 动作序列向量 |
| `errorSignatures` | TEXT | 错误签名 JSON 数组（默认 `'[]'`） |
| `tags` | TEXT | 标签 JSON 数组 |
| `createdAt` | INTEGER | 创建时间戳 |
> **不变式**：每个 finalize 的 episode 必须产生 ≥ 1 条 L1 轨迹，即使 capture 失败也会发出一个轨迹 stub，确保 episode 时间线不为空。
>
> **注意**：`errorSignatures` 在类型定义中为可选（新增列在迁移 004），但在存储层始终为 `string[]`，默认为 `'[]'`。
>
> **注意**：`value` 字段初始为 0，仅由 `core/reward/backprop.ts` 修改，capture 阶段不会改变它。
资料来源：[core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md)
### L1 存储位置
L1 相关模块位于 `core/memory/l1/` 目录，其数据存储操作委托给 `core/storage/` 中的 `traces.ts` 仓储：
```ts
core/storage/
├── index.ts // makeRepos(db) 导出
├── traces.ts // L1 轨迹 CRUD + 向量搜索
```
```ts
import { openDb, runMigrations, makeRepos } from "./core/storage/index.js";
const db = openDb({ filepath: "/Users/.../memos.db", agent: "openclaw" });
runMigrations(db);
const repos = makeRepos(db);
// 插入轨迹
repos.traces.insert({...});
// 向量检索
const top = repos.traces.searchByVector(queryVec, 5);
```
资料来源：[core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
### 写入时的轻量级富化
L1 轨迹在捕获阶段会经过以下富化处理（位于 `core/capture/`）：
| 富化类型 | 输入 | 输出文件 |
|----------|------|----------|
| 摘要嵌入 | `traces.summary` | `traces.vec_summary` |
| 动作嵌入 | `tool call sequence` | `traces.vec_action` |
| 结构化匹配 | `error signature` | `traces.errorSignatures` |
| 领域标签 | `tagger.ts` 输出 | `traces.tags` |
```ts
// core/capture/ 模块组成
core/capture/
├── index.ts // 入口 + 编排
├── summarizer.ts // 摘要生成（LLM 调用）
├── embedder.ts // 向量化
├── tier2-inducer.ts // L2 策略归纳触发
├── tier3-abductor.ts // L3 世界模型抽象触发
├── error-signature.ts // 结构化匹配
├── tagger.ts // 领域标签富化
```
资料来源：[core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md)
---
## L2 策略层
### 设计目标
L2 从高价值 L1 轨迹中归纳出可复用的策略（Policy）。策略是对成功执行模式的抽象描述，不包含具体的命令级细节。当系统遇到类似任务时，可以快速检索相关策略作为参考。
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
### 策略归纳流程
L2 策略归纳由 `tier2-inducer.ts` 触发，发生在轨迹捕获之后。当某条轨迹的价值分数（`value`）超过预设阈值时，系统会调用 LLM 对轨迹进行归纳，生成结构化的策略文本。
```ts
// core/capture/tier2-inducer.ts 核心逻辑（伪代码）
async function inducePolicy(episode: Episode): Promise {
const highValueTraces = episode.traces.filter(t => t.value > threshold);
if (highValueTraces.length === 0) return null;
const policyText = await llm.induce(highValueTraces);
return {
id: generateId(),
sourceTraceIds: highValueTraces.map(t => t.id),
content: policyText,
createdAt: Date.now()
};
}
```
### 数据模型
L2 策略存储在 `policies` 表中：
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT PRIMARY KEY | 策略唯一标识 |
| `vec` | BLOB | 策略内容向量（用于 Tier-2 检索） |
| `priority` | INTEGER | 优先级分数 |
| `sourceTraceIds` | TEXT | 来源轨迹 ID 列表 |
策略的 `vec` 向量通过 `policies.ts` 仓储的向量搜索接口进行索引和检索。
资料来源：[core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
### 社区相关问题
> ⚠️ **已知问题**：大型合并 episode 可能触发 L2/L3/Skills 进化的级联风暴，导致 OpenClaw 会话阻塞。
>
> 当处理长时间运行的 OpenClaw 开发工作流时，`memos-local-plugin` 可能创建或重新打开一个非常大的 episode，进而触发昂贵的后处理流程（capture / reward rescore / L2 induction / L3 abstraction / skill evolution）。
>
> 详见 [Issue #1755](https://github.com/MemTensor/MemOS/issues/1755)
---
## L3 世界模型层
### 设计目标
L3 提炼出关于运行环境的高层拓扑和推理规则，回答"我当前实际在什么环境中操作？"这类元认知问题。世界模型包含系统约束、环境依赖关系、常见故障模式等抽象知识。
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
### 世界模型抽象流程
L3 抽象由 `tier3-abductor.ts` 触发，发生在 L2 归纳之后。系统会分析多个相关策略的共性，提炼出环境级别的约束和拓扑信息。
```ts
// core/capture/tier3-abductor.ts 核心逻辑（伪代码）
async function abductWorldModel(policies: Policy[]): Promise {
if (policies.length < minClusterSize) return null;
const envConstraints = await llm.extractConstraints(policies);
const topology = await llm.extractTopology(policies);
return {
id: generateId(),
envConstraints,
topology,
sourcePolicyIds: policies.map(p => p.id)
};
}
```
### 数据模型
L3 世界模型存储在 `world_model` 表中：
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT PRIMARY KEY | 世界模型唯一标识 |
| `vec` | BLOB | 环境描述向量 |
| `constraints` | TEXT | 环境约束 JSON |
| `topology` | TEXT | 拓扑结构 JSON |
| `sourcePolicyIds` | TEXT | 来源策略 ID 列表 |
资料来源：[core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
---
## Skills 技能层
### 设计目标
Skills 是从 L2 策略结晶而来的可执行单元，具有命名、参数和调用指南。当 agent 需要执行特定任务时，可以直接从 Skills 中检索匹配的条目，而无需重新推理完整策略。
资料来源：[core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### 技能生命周期
`applyFeedback` 是单一状态转换函数，`applySkillFeedback` 是其编排包装器，负责持久化和事件发布：
| 信号 | η 变化 | 可能的状态转换 |
|------|--------|----------------|
| `trial.pass` | Beta 后验 `(passed+1)/(attempts+2)` | probationary → active（达到阈值） |
| `trial.fail` | Beta 后验 | probationary → retired（达到阈值） |
| `user.positive` | `η += etaDelta` | retired → probationary（达到阈值） |
| `user.negative` | `η -= etaDelta` | 任何状态 → retired（低于 retireEta） |
| `reward.updated` | 混合 0.7·η + 0.3·newGain | 任何状态 → retired（低于 retireEta） |
> **η（eta）**：技能的可靠性分数，类似于 Beta 分布的均值，用于决定技能是否应该被激活或退役。
资料来源：[core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### 技能数据结构
技能从 L2 策略的 draft 塑造为 `SkillRow`：
| 字段 | 说明 |
|------|------|
| `procedureJson` | 结构化步骤、参数、示例、前置条件 |
| `invocationGuide` | 简洁的 markdown 提示块，agent 适配器在 Tier-1 检索选中该技能时注入系统提示词 |
| `eta` | 从策略 gain 种子（新鲜 mint）或携带并重新缩放（rebuild） |
| `vec` | 技能摘要 + 触发器的嵌入，用于 Tier-1 余弦检索 |
| `sourcePolicyIds` | 与现有技能条目的集合并集 |
资料来源：[core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### 技能检索（Tier-1）
Tier-1 检索专门用于 Skills 的匹配，通过向量检索 + FTS + 模式匹配三个通道协同工作：
```ts
import { skillInvokeRetrieve } from "@memtensor/memos-local-plugin/core/retrieval";
// 当 agent 即将调用 skill. 时触发
const result = await skillInvokeRetrieve(ctx, { skillName: "deploy-docker" });
```
---
## 层次化检索系统
### 三层检索架构
检索系统将查询路由到对应的记忆层次，每层返回不同粒度的参考信息：
| 检索层 | 源表 | 召回内容 | 回答的问题 |
|--------|------|----------|------------|
| **Tier 1** | `skills` | 匹配的可执行技能（η ≥ minEta） | "遇到 X 任务应该调用哪个已知流程？" |
| **Tier 2** | `traces`, rollup | 高价值轨迹片段 + 子任务 episode 摘要 | "上次尝试这个时，什么方法有效？" |
| **Tier 3** | `world_model` | 环境拓扑 / 推理规则 | "我当前实际在什么环境中操作？" |
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
### 五个检索入口点
所有检索入口返回 `RetrievalResult = { packet, stats }`：
```ts
import {
turnStartRetrieve, // 对话轮次开始 — 完整 Tier 1+2+3
toolDrivenRetrieve, // memos_search / memos_timeline / …
skillInvokeRetrieve, // agent 即将调用 skill.
subAgentRetrieve, // 子 agent 用 mission prompt 启动
repairRetrieve, // N 次工具失败 → 反模式召回
} from "@memtensor/memos-local-plugin/core/retrieval";
```
每个入口选择运行哪些层、是否允许低优先级（"反模式"）轨迹、以及保留多少片段。
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
### 多通道召回
| 通道 | 索引 | 用途 |
|------|------|------|
| `vec_summary` | `traces.vec_summary` 余弦 | 语义召回用户/助手说了什么 |
| `vec_action` | `traces.vec_action` 余弦 | 语义召回 agent 的动作/工具序列 |
| `vec` | `skills.vec`, `world_model.vec` 余弦 | Tier-1 / Tier-3 语义召回 |
| `fts` | FTS5 trigram MATCH | 关键词精准命中（英文 + CJK ≥ 3 字符） |
| `pattern` | LIKE `%term%` (CJK bigrams + 2-char ASCII) | 低于 trigram 窗口的 2 字符中文名/动词 |
| `structural` | `instr(error_signatures_json, '""')` | 逐字错误签名回放 |
同时在多个通道中命中的行每个匹配携带一个 `ChannelRank`。排名器对通道求和 `1 / (k + rank_i + 1)`，因此由向量和 FTS 共同确认的命中比单一通道获得明显更高的 RRF 分数。
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
### 自适应相关性阈值 + 智能 MMR 种子
在每个通道 RRF 之后，排名器计算 **top relevance** 并丢弃所有低于 `topRelevance · relativeThresholdFloor`（默认 `0.4`）的候选。这是绝对 `minTraceSim` 底限的自适应变体——强查询（top relevance ≈ 1.0）需要所有候选都高匹配度，而模糊查询则允许更多低分候选通过。
---
## 配置选项
每层记忆的检索参数位于 `config.yaml` 的 `algorithm.retrieval.*` 下：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `tier1TopK` | — | Tier-1 技能检索返回数量 |
| `tier2TopK` | — | Tier-2 轨迹检索返回数量 |
| `tier3TopK` | — | Tier-3 世界模型检索返回数量 |
| `relativeThresholdFloor` | `0.4` | 自适应相关性阈值 |
| `weightCosine` | — | 余弦权重 |
| `weightPriority` | — | 优先级权重 |
| `weightFts` | — | FTS 权重 |
用户可见的配置模板仅暴露 `tier1TopK / tier2TopK / tier3TopK`，其他参数使用文档化的默认值（详见 `docs/CONFIG-ADVANCED.md`）。
资料来源：[core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
---
## 数据存储与索引
### 数据库架构
记忆层次系统使用 SQLite 存储，配置 WAL 模式以支持并发读取：
| Pragma | 值 | 原因 |
|--------|-----|------|
| `journal_mode` | WAL | 允许守护进程写入时并发读取器（viewer） |
| `synchronous` | NORMAL | 良好的 WAL 权衡；提升到 FULL 成本约 2× 写入 |
| `foreign_keys` | ON | 强制引用完整性 |
| `temp_store` | MEMORY | 避免 CTE 临时文件折腾 |
| `busy_timeout` | 5000 | 跨进程锁等待 |
### 向量搜索
所有记忆层（L1 轨迹、L2 策略、L3 世界模型、Skills）都支持向量搜索：
```ts
// traces 向量搜索
const topTraces = repos.traces.searchByVector(queryVec, 5);
// policies 向量搜索
const topPolicies = repos.policies.searchByVector(queryVec, 3);
// world_model 向量搜索
const topWorldModels = repos.worldModel.searchByVector(queryVec, 2);
// skills 向量搜索
const topSkills = repos.skills.searchByVector(queryVec, 1);
```
资料来源：[core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
---
## 常见问题与已知限制
### 多 Agent 记忆隔离
> 🔴 **漏洞报告**：`patternSearch` 缺少 `ownerFilter`，导致多 Agent 场景下记忆隔离泄漏。
>
> 在多 Agent 协作场景中，当使用中文查询或短英文查询时，`memory_search` 工具的 `patternSearch` 分支可能返回其他 Agent 的记忆，造成信息泄露。
>
> 详见 [Issue #1361](https://github.com/MemTensor/MemOS/issues/1361)
### 记忆迁移
> 📦 **功能请求**：增加修改已有记忆 `agent_id` 的功能，以便在迁移系统时记忆不丢失。
>
> 当用户需要在不同 agent ID 之间迁移记忆数据时，当前系统没有提供便捷的批量修改接口。
>
> 详见 [Issue #1288](https://github.com/MemTensor/MemOS/issues/1288)
### 大型 Episode 处理
> ⚠️ **性能问题**：大型合并 episode 可能触发 L2/L3/Skill-evolution 风暴，阻塞 OpenClaw 会话。
>
> 在长时间运行的开发工作流中，超大 episode 会触发级联的昂贵后处理操作。
>
> 详见 [Issue #1755](https://github.com/MemTensor/MemOS/issues/1755)
---
## 模块目录结构
```
apps/memos-local-plugin/core/
├── memory/
│ ├── l1/ # L1 轨迹层
│ │ └── README.md
│ ├── l2/ # L2 策略层
│ │ └── README.md
│ └── l3/ # L3 世界模型层
│ └── README.md
├── capture/ # 记忆捕获管道
│ ├── index.ts
│ ├── summarizer.ts
│ ├── embedder.ts
│ ├── tier2-inducer.ts
│ ├── tier3-abductor.ts
│ ├── error-signature.ts
│ └── tagger.ts
├── retrieval/ # 层次化检索
│ ├── index.ts
│ ├── retrieve.ts
│ ├── query-builder.ts
│ ├── tier1-skill.ts
│ ├── tier2-trace.ts
│ ├── tier3-world.ts
│ ├── ranker.ts
│ ├── llm-filter.ts
│ ├── injector.ts
│ ├── events.ts
│ ├── ALGORITHMS.md
│ └── README.md
├── skill/ # 技能生命周期
│ ├── index.ts
│ ├── lifecycle.ts
│ └── README.md
└── storage/ # 数据库仓储
├── index.ts
├── traces.ts
├── policies.ts
├── world_model.ts
├── skills.ts
├── migrations.ts
└── README.md
---
## 技能系统
### 相关页面
相关主题：[记忆层次系统](#memory-layers), [检索系统](#retrieval-system)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin/core/skill](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill)
- [apps/memos-local-plugin/src/skill](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/src/skill)
- [apps/memos-local-plugin/core/feedback](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback)
- [apps/memos-local-plugin/core/retrieval](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval)
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
- [apps/memos-local-plugin/docs/Reflect2Skill_方法论设计.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/docs/Reflect2Skill_方法论设计.md)
# 技能系统
## 概述
技能系统（Skill System）是 MemOS 本地插件中用于将反馈信号结晶化为可复用工具的核心模块。它是 MemOS 三层记忆架构中的 **Tier-1 层级**，负责在任务级别回答"Do I have a named skill for this?"这一关键问题。
技能系统从 L2 策略诱导和用户反馈中提取高价值行为模式，转化为结构化的技能（Skill），供 Agent 在后续执行中直接调用。技能系统与反馈系统、检索系统紧密协作，形成了完整的"反馈→学习→检索→执行"闭环。
资料来源：[core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
## 架构概览
```
graph TD
subgraph 反馈层
A[反馈信号] --> B{信号类型}
B -->|trial.pass| C[Beta 后验更新]
B -->|trial.fail| C
B -->|user.positive| D[η 提升]
B -->|user.negative| E[η 降低]
B -->|reward.updated| F[增益混合]
end
subgraph 技能状态机
C --> G{阈值检查}
D --> G
E --> G
F --> G
G -->|通过| H[probationary]
G -->|失败| I[retired]
H -->|持续通过| J[active]
J -->|衰减| I
I -->|用户激活| H
end
subgraph 技能存储
K[SkillRow] --> K1[procedureJson]
K --> K2[invocationGuide]
K --> K3[η 值]
K --> K4[vec 向量]
K --> K5[sourcePolicyIds]
end
subgraph Tier-1 检索
L[检索请求] --> M[vec cosine]
L --> N[fts 匹配]
L --> O[pattern 匹配]
M --> P[RRF 排名]
N --> P
O --> P
P --> Q[InjectionPacket]
end
```
资料来源：[core/skill/README.md:1-50](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
## 技能数据结构
技能以 `SkillRow` 的形式持久化存储，包含以下核心字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `procedureJson` | `string` | 结构化步骤、参数、示例、前置条件 |
| `invocationGuide` | `string` | Markdown 格式的调用指南，插入 Agent 系统提示词 |
| `η` (eta) | `number` | 技能质量指标，控制生命周期状态转换 |
| `vec` | `number[]` | 技能摘要和触发器的嵌入向量，用于 Tier-1 余弦检索 |
| `sourcePolicyIds` | `string[]` | 源策略 ID 集合，用于追踪技能来源 |
资料来源：[core/skill/README.md:20-30](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### procedureJson 结构
`procedureJson` 字段包含技能的完整操作定义：
```json
{
"steps": ["步骤1", "步骤2", "步骤3"],
"parameters": {
"paramName": {
"type": "string",
"required": true,
"description": "参数描述"
}
},
"examples": [
{
"input": "示例输入",
"output": "预期输出"
}
],
"preconditions": ["前置条件1", "前置条件2"]
}
```
### invocationGuide 格式
`invocationGuide` 是供 Agent 适配器直接插入系统提示词的 Markdown 块：
```markdown
## 技能：{skill_name}
**触发条件**: {trigger_description}
**执行步骤**:
1. {step_1}
2. {step_2}
**参数说明**:
- `{param_name}`: {description}
**注意事项**:
- {note_1}
- {note_2}
```
资料来源：[core/skill/README.md:15-25](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
## 生命周期与状态机
### 技能状态
技能具有三种主要状态：
| 状态 | 说明 | 可被检索 |
|------|------|----------|
| `probationary` | 试用期状态，新创建或重新激活的技能 | 是（需 η ≥ minEta） |
| `active` | 活跃状态，正常使用的技能 | 是 |
| `retired` | 退役状态，不再推荐但未删除 | 否 |
资料来源：[core/skill/README.md:35-45](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### η 质量指标
`η`（eta）是技能的核心质量指标，采用 Beta 后验分布建模：
- 初始值从策略增益（gain）种子化
- 重建时从旧技能继承并重新缩放
- 范围 `[0, 1]`，值越高表示技能越可靠
### 状态转换规则
`applyFeedback` 函数（见 `lifecycle.ts`）是单一状态转换函数，`applySkillFeedback` 是其编排封装：
| 信号 | η 变化 | 状态转换 |
|------|--------|----------|
| `trial.pass` | Beta 后验 `(passed+1)/(attempts+2)` | probationary → active（阈值到达） |
| `trial.fail` | Beta 后验 | probationary → retired（阈值到达） |
| `user.positive` | `η += etaDelta` | retired → probationary（阈值到达） |
| `user.negative` | `η -= etaDelta` | 任何状态 → retired（η < retireEta） |
| `reward.updated` | 混合 `0.7·η + 0.3·newGain` | 任何状态 → retired（η < retireEta） |
资料来源：[core/skill/README.md:45-55](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
```
graph LR
A[probationary] -->|trial.pass 阈值到达| B[active]
A -->|trial.fail 阈值到达| C[retired]
B -->|η < retireEta| C
C -->|user.positive 阈值到达| A
A -->|η < retireEta| C
```
## 反馈驱动进化
### 反馈信号来源
技能进化由反馈系统驱动，通过 `SkillEventBus` 事件总线发出信号：
```typescript
// 反馈信号类型
type SkillSignal =
| { type: 'trial.pass'; skillId: string }
| { type: 'trial.fail'; skillId: string }
| { type: 'user.positive'; skillId: string }
| { type: 'user.negative'; skillId: string }
| { type: 'reward.updated'; skillId: string; newGain: number };
```
资料来源：[core/skill/README.md:60-70](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
### 与反馈系统集成
反馈系统中的 `runRepair` 流程与技能系统紧密协作：
1. 当修复决策被执行并产生正面结果时，触发 `trial.pass`
2. 当修复失败或产生负面结果时，触发 `trial.fail`
3. 用户可以直接对技能进行正/负面评价
4. 奖励更新时，重新评估技能增益
```
graph TD
subgraph 反馈子系统
A[runRepair] --> B{执行结果}
B -->|成功| C[trial.pass]
B -->|失败| D[trial.fail]
end
subgraph 技能子系统
C --> E[applySkillFeedback]
D --> E
F[user feedback] --> E
G[reward updated] --> E
E --> H[更新 η 值]
H --> I{状态转换检查}
I -->|通过| J[状态更新]
I -->|失败| K[emit SkillEventBus]
end
```
资料来源：[core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md)
## Tier-1 检索
### 检索通道
技能作为 Tier-1 层级，通过以下检索通道被召回：
| 通道 | 数据源 | 匹配方式 | 用途 |
|------|--------|----------|------|
| `vec` | `skills.vec` | 余弦相似度 | 语义相似技能召回 |
| `fts` | FTS5 索引 | trigram MATCH | 关键词精确匹配 |
| `pattern` | LIKE 查询 | CJK 二元组 + 2字符 ASCII | 短中文名称/动词匹配 |
资料来源：[core/retrieval/README.md:1-20](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
### 检索流程
```
graph TD
A[检索请求] --> B[query-builder 构建查询]
B --> C{选择检索通道}
C -->|vec| D[向量相似度计算]
C -->|fts| E[FTS5 trigram 匹配]
C -->|pattern| F[pattern 匹配]
D --> G[RRF 排名合并]
E --> G
F --> G
G --> H[自适应阈值过滤]
H --> I[η ≥ minEta 检查]
I -->|通过| J[生成 InjectionPacket]
I -->|失败| K[过滤掉]
J --> L[返回给 Agent]
```
### 检索入口
检索系统提供五个入口点，均可返回 `RetrievalResult = { packet, stats }`：
```typescript
import {
turnStartRetrieve, // 对话轮次开始 — 全量 Tier 1+2+3
toolDrivenRetrieve, // memos_search / memos_timeline 等工具驱动
skillInvokeRetrieve, // Agent 即将调用 skill.
subAgentRetrieve, // 子 Agent 伴随任务提示词启动
repairRetrieve, // N 次工具失败 → 反模式召回
} from "@memtensor/memos-local-plugin/core/retrieval";
```
资料来源：[core/retrieval/README.md:60-80](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
## 配置参数
技能系统的主要配置项位于 `config.yaml` 的 `algorithm.retrieval.*` 路径下：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `tier1TopK` | 5 | Tier-1 检索返回的最大技能数 |
| `minEta` | 0.5 | 技能可被检索的最小 η 值阈值 |
| `retireEta` | 0.3 | 技能被退役的 η 值阈值 |
| `etaDelta` | 0.1 | 用户反馈导致的 η 变化量 |
| `probationThreshold` | 0.7 | 从 probationary 进入 active 所需 η |
进阶配置文档：`docs/CONFIG-ADVANCED.md`
资料来源：[core/retrieval/README.md:100-110](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
## 源代码结构
```
apps/memos-local-plugin/core/skill/
├── lifecycle.ts # 状态转换逻辑 applySkillFeedback
├── skill.ts # 技能核心类定义
├── events.ts # SkillEventBus 事件总线
├── index.ts # 公共导出
└── README.md # 本文档
```
```
apps/memos-local-plugin/src/skill/
├── skill.ts # 技能相关工具函数
└── *.ts # 其他技能工具模块
```
资料来源：[apps/memos-local-plugin/core/skill](https://github.com/MemTensor/MemOS/tree/main/apps/memos-local-plugin/core/skill)
## 社区关注与已知问题
### 大型合并事件触发技能风暴
**Issue #1755** 报告了在长时间运行的 OpenClaw 开发工作流中，`memos-local-plugin` 可能创建或重新打开非常大的 episode，进而触发级联的昂贵后处理（包括技能进化），可能使 OpenClaw 会话停滞。
症状：
- 大型合并事件后技能进化请求激增
- L2/L3 抽象与技能演化同时触发
- API 速率限制螺旋
建议措施：
- 监控 episode 大小，设置合并阈值
- 考虑批量处理技能进化请求
- 实现冷却期机制避免风暴
资料来源：[memos-local-plugin issues #1755](https://github.com/MemTensor/MemOS/issues/1755)
### 记忆所有权隔离问题
**Issue #1318** 和 **Issue #1361** 报告了 `memory_search` 工具硬编码默认所有者为 `agent:main` 而非当前 Agent 的问题，这可能导致多 Agent 场景下的记忆隔离泄漏。
这与技能系统直接相关，因为技能作为 Tier-1 记忆也可能受到所有权隔离问题影响。
资料来源：[memos-local-plugin issues #1318](https://github.com/MemTensor/MemOS/issues/1318), [#1361](https://github.com/MemTensor/MemOS/issues/1361)
## 方法论设计
技能系统的设计遵循 "Reflect to Evolve" 方法论：
1. **反馈收集**：从试用结果、用户评价、奖励更新中收集反馈信号
2. **质量评估**：使用 Beta 后验分布评估技能可靠性
3. **状态进化**：基于质量指标动态调整技能生命周期状态
4. **检索优化**：多通道 RRF 排名确保高质量技能优先召回
资料来源：[docs/Reflect2Skill_方法论设计.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/docs/Reflect2Skill_%E6%96%B9%E6%B3%95%E8%AE%BA%E8%AE%BE%E8%AE%A1.md)
## 最佳实践
### 技能创建
- 从成功的 L2 策略诱导中创建新技能
- 确保 `procedureJson` 包含足够的上下文和前置条件
- 提供清晰的 `invocationGuide` 供 Agent 理解
### 技能维护
- 定期检查 η 值处于边缘状态的技能
- 关注 `probationary` 状态的技能转化率
- 清理长期处于 `retired` 状态的技能
### 故障排查
- 检查 `SkillEventBus` 事件日志
- 验证检索返回的技能是否符合预期
- 监控 η 值异常波动的技能
---
## 会话与 Episode 管理
### 相关页面
相关主题：[记忆层次系统](#memory-layers)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin/core/session/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/session/README.md)
- [apps/memos-local-plugin/core/session](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/session)
- [apps/memos-local-plugin/core/storage/repos/episodes.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/repos/episodes.ts)
- [apps/memos-local-plugin/core/storage/repos/sessions.ts](https.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/repos/sessions.ts)
- [apps/memos-local-plugin/core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
# 会话与 Episode 管理
## 概述
会话与 Episode 管理是 MemOS 本地插件的核心模块，负责管理 Agent 生命周期内的对话上下文边界。该模块作为外部世界（适配器 ↔ Agent ↔ 多用户）与算法流水线之间的桥梁，确保每个 LLM 侧的内存操作都能正确关联到已知的会话和 Episode。
这一管理机制的核心职责包括：
- **会话生命周期管理**：创建、维护和清理与 Agent 进程的逻辑连接
- **Episode 状态追踪**：跟踪每次用户查询及其完整的 Agent 响应弧（包括工具调用、子 Agent）
- **意图分类**：在会话开始时对用户意图进行分类，为后续处理提供上下文
- **事件驱动架构**：通过事件总线协调各模块之间的协作
资料来源：[core/session/README.md]()
## 核心概念
MemOS 采用三层结构来组织对话数据，每个层级都有其特定的职责和生命周期。
| 概念 | 定义 | 存储位置 | 生命周期 |
|------|------|----------|----------|
| **Session（会话）** | 与 Agent 的长期逻辑连接，每个运行的 Agent 进程对应一个 Session | `sessions` 表 | 进程级别，长期存在 |
| **Episode（片段）** | 一次用户查询及其完整 Agent 响应弧（工具调用、子 Agent） | `episodes` 表 | 每个用户查询创建一个 |
| **Turn（轮次）** | Episode 内的单条消息（用户/助手/工具/系统） | 内存快照 | 临时，Phase 6 时持久化为 trace |
### Session 与 Episode 的关系
```mermaid
graph TB
subgraph Session["Session（长期）"]
A["sessions 表
agent_id, metadata"]
end
subgraph Episode["Episode（每次用户查询）"]
B1["Episode 1"]
B2["Episode 2"]
B3["Episode N"]
end
subgraph Turn["Turn（消息序列）"]
C1["User Message"]
C2["Assistant Message"]
C3["Tool Call"]
C4["Tool Result"]
C5["Sub-agent Message"]
end
A --> B1
A --> B2
A --> B3
B1 --> C1
B1 --> C2
B1 --> C3
B1 --> C4
B1 --> C5
style Session fill:#e1f5fe
style Episode fill:#fff3e0
style Turn fill:#e8f5e9
```
**设计决策**：每个用户查询开启一个新的 Episode。子 Agent 跳跃**不会**开启新 Episode，而是向父 Episode 添加更多 Turn。这一设计符合"每个 Episode 一个奖励信号"的原则，同时通过 `trace_depth` 属性保留每个 trace 的嵌套深度信息。
资料来源：[core/session/README.md:概念定义]()
## 架构设计
### 模块结构
会话管理模块位于 `core/session/`，其核心组件包括：
```
core/session/
├── index.ts # 公共 API 导出
├── session-manager.ts # 会话管理器（核心）
├── intent-classifier.ts # 意图分类器
├── adapters/ # 存储适配器
│ ├── sessions-repo.ts
│ └── episodes-repo.ts
├── events.ts # 事件总线定义
└── README.md
```
### 核心组件
#### 1. SessionManager（会话管理器）
`SessionManager` 是整个模块的核心，负责会话和 Episode 的完整生命周期管理。
```typescript
const sm = createSessionManager({
sessionsRepo: adaptSessionsRepo(sqliteSessions),
episodesRepo: adaptEpisodesRepo(sqliteEpisodes),
intentClassifier: intent
});
```
**主要职责**：
- 创建和管理会话实例
- 启动和追踪 Episode
- 处理 Turn 的添加和 finalization
- 管理空闲会话的清理
- 优雅关闭时的资源回收
资料来源：[core/session/README.md:公共API]()
#### 2. IntentClassifier（意图分类器）
`IntentClassifier` 使用 LLM 对用户意图进行分类，为后续处理提供上下文。
```typescript
const intent = createIntentClassifier({
llm,
timeoutMs: 5000
});
```
**关键特性**：
- 支持 `disableLlm=true` 配置，用于 `llm.provider=local_only` 场景
- 当禁用 LLM 时，分类器不会尝试网络调用，避免本地部署失败
资料来源：[core/session/README.md:注意事项]()
### 数据流
```mermaid
sequenceDiagram
participant Adapter
participant SessionManager
participant IntentClassifier
participant EpisodeRepo
participant EventBus
Adapter->>SessionManager: openSession(agentId)
SessionManager->>EpisodeRepo: 创建/获取 session
EpisodeRepo-->>SessionManager: Session 实例
Adapter->>SessionManager: startEpisode(userQuery)
SessionManager->>IntentClassifier: classifyIntent(query)
IntentClassifier-->>SessionManager: IntentResult
SessionManager->>EpisodeRepo: 创建 episode
SessionManager->>EventBus: emit('episode:started')
loop 对话循环
Adapter->>SessionManager: addTurn(message)
SessionManager->>EpisodeRepo: 追加 turn
SessionManager->>EventBus: emit('turn:added')
end
Adapter->>SessionManager: finalizeEpisode(result)
SessionManager->>EpisodeRepo: 更新 episode 状态
SessionManager->>EventBus: emit('episode:finalized')
```
## 公共 API
### 核心函数
```typescript
import {
createSessionManager,
createIntentClassifier,
adaptSessionsRepo,
adaptEpisodesRepo
} from "@memos/core";
```
| 函数 | 用途 | 参数 |
|------|------|------|
| `createSessionManager()` | 创建会话管理器实例 | `{sessionsRepo, episodesRepo, intentClassifier}` |
| `createIntentClassifier()` | 创建意图分类器 | `{llm, timeoutMs}` |
| `adaptSessionsRepo()` | 适配会话仓储 | SQLite 仓储实例 |
| `adaptEpisodesRepo()` | 适配 Episode 仓储 | SQLite 仓储实例 |
### SessionManager 方法
| 方法 | 说明 | 抛出场景 |
|------|------|----------|
| `openSession()` | 打开或创建会话 | - |
| `startEpisode()` | 为用户查询启动新 Episode | 已存在开启中的 Episode |
| `addTurn()` | 添加消息到当前 Episode | 无开启中的 Episode |
| `finalizeEpisode()` | 完成 Episode 并持久化 | 无开启中的 Episode |
| `abandonEpisode()` | 放弃当前 Episode | 无开启中的 Episode |
| `pruneIdle()` | 清理空闲会话 | - |
| `shutdown()` | 优雅关闭，回收资源 | - |
资料来源：[core/session/README.md:公共API]()
## 存储层集成
### 数据库 Schema
会话和 Episode 数据存储在 SQLite 数据库中，与其他数据（traces、skills、policies 等）共存于同一数据库文件。
```typescript
import { openDb, runMigrations, makeRepos } from "./core/storage/index.js";
const db = openDb({
filepath: "/Users/.../memos.db",
agent: "openclaw"
});
runMigrations(db); // 幂等操作，首次运行后开销极小
const repos = makeRepos(db);
repos.sessions.create({...});
repos.episodes.create({...});
```
### 数据库配置
| Pragma | 值 | 用途 |
|--------|-----|------|
| `journal_mode` | WAL | 允许守护进程写入时 viewer 并发读取 |
| `synchronous` | NORMAL | WAL 模式下的良好折中，FULL 模式写入开销翻倍 |
| `foreign_keys` | ON | 强制引用完整性 |
| `temp_store` | MEMORY | 避免 CTE 的临时文件抖动 |
| `busy_timeout` | 5000 | 跨进程忙等容忍度 |
资料来源：[core/storage/README.md:Pragmas]()
## Episode 生命周期
### 状态流转
```mermaid
stateDiagram-v2
[*] --> idle: 系统启动
idle --> open: 用户发起查询
open --> open: addTurn()
open --> finalized: finalizeEpisode()
open --> abandoned: abandonEpisode()
finalized --> [*]
abandoned --> [*]
note right of open: 子 Agent 消息
通过 addTurn() 添加
note right of finalized: 触发 capture
reward 计算
L2/L3 诱导
```
### 大型 Episode 问题
**已知问题**（Issue #1755）：在长时间运行的 OpenClaw 开发工作流中，`memos-local-plugin` 可能创建或重新打开非常大的 Episode，进而触发昂贵的后处理级联：
- `capture` 执行时间显著增加
- Reward 重新评分
- L2 策略诱导
- L3 世界模型抽象
- Skill 进化
这可能导致 OpenClaw 会话停滞。社区正在积极处理这一问题。
资料来源：[GitHub Issue #1755](https://github.com/MemTensor/MemOS/issues/1755)
## 事件系统
Session 模块通过事件总线与其他核心模块协调工作。
```typescript
import { createSessionEventBus } from "@memos/core";
const bus = createSessionEventBus();
// 订阅 Episode 事件
bus.on('episode:started', (episode) => {
console.log('New episode started:', episode.id);
});
bus.on('episode:finalized', (episode, result) => {
console.log('Episode completed:', episode.id);
});
```
### 事件类型
| 事件 | 触发时机 | 典型订阅者 |
|------|----------|------------|
| `session:opened` | 新会话创建 | Retrieval, Metrics |
| `session:closed` | 会话关闭 | Cleanup |
| `episode:started` | Episode 开始 | Capture Pipeline |
| `episode:turn:added` | Turn 添加 | - |
| `episode:finalized` | Episode 完成 | L2/L3 Induction |
| `episode:abandoned` | Episode 放弃 | - |
## 配置选项
### IntentClassifier 配置
```typescript
interface IntentClassifierConfig {
llm: LlmClient; // LLM 客户端实例
timeoutMs: number; // 超时时间，默认 5000ms
disableLlm?: boolean; // 禁用 LLM（用于 local_only 模式）
}
```
### SessionManager 配置
```typescript
interface SessionManagerConfig {
sessionsRepo: SessionsRepo; // 会话仓储
episodesRepo: EpisodesRepo; // Episode 仓储
intentClassifier: IntentClassifier; // 意图分类器
idleTimeoutMs?: number; // 空闲超时，默认 30 分钟
}
```
## 最佳实践
### 1. 正确的初始化顺序
```typescript
// 1. 打开数据库
const db = openDb({ filepath, agent });
runMigrations(db);
const repos = makeRepos(db);
// 2. 创建适配器
const sessionsRepo = adaptSessionsRepo(repos.sessions);
const episodesRepo = adaptEpisodesRepo(repos.episodes);
// 3. 创建分类器
const intentClassifier = createIntentClassifier({ llm, timeoutMs: 5000 });
// 4. 创建管理器
const sessionManager = createSessionManager({
sessionsRepo,
episodesRepo,
intentClassifier
});
```
### 2. 生命周期管理
```typescript
// 启动会话
const session = await sessionManager.openSession(agentId);
// 处理用户查询
const episode = await sessionManager.startEpisode(userQuery);
// 添加对话轮次
await sessionManager.addTurn({ role: 'user', content: '...' });
await sessionManager.addTurn({ role: 'assistant', content: '...' });
// 完成 Episode
await sessionManager.finalizeEpisode({ success: true, reward: 1.0 });
// 关闭时清理
await sessionManager.shutdown();
db.close();
```
### 3. 避免并发写入
**限制**：Session 模块不支持单会话并发。每个 Agent 进程应使用独立的 session_id。如果需要并行 Agent，应打开不同的会话 ID。
资料来源：[core/session/README.md:注意事项]()
## 局限性
| 限制 | 说明 | 应对方案 |
|------|------|----------|
| 无单会话并发 | 假设一个 Agent 进程一次写入 | 使用不同 session_id |
| Turn ID 临时性 | Turn ID 仅在内存快照中稳定 | Phase 6 使用 trace ID（`tr_*`）替代 |
| Intent LLM 不可靠 | local_only 模式下可能失败 | 使用 `disableLlm=true` 配置 |
资料来源：[core/session/README.md:注意事项]()
## 测试
模块提供了完整的测试覆盖，位于 `tests/unit/session/`：
- `session-manager.test.ts` — 会话生命周期、幂等性、空闲清理
- `intent-classifier.test.ts` — 分类逻辑、超时处理
- `session.integration.test.ts` — 端到端集成测试
```bash
# 运行会话模块测试
npm test -- tests/unit/session
```
## 相关模块
| 模块 | 交互关系 |
|------|----------|
| **core/storage** | 提供 Episode 和 Session 的持久化存储 |
| **core/capture** | 订阅 `episode:finalized` 事件触发 trace 捕获 |
| **core/feedback** | 使用 Episode 数据进行反馈处理 |
| **core/retrieval** | 查询 Episode 和 trace 进行上下文检索 |
| **core/pipeline** | 编排各模块的初始化顺序 |
## 常见问题
### Q: 如何在多 Agent 场景下隔离记忆？
每个 Agent 进程应使用独立的 session_id。确保在 `openSession()` 时传入正确的 agent_id，以便 Episode 和 trace 与特定 Agent 关联。
### Q: Episode 卡在 "open" 状态怎么办？
检查是否有未处理的 `finalizeEpisode()` 或 `abandonEpisode()` 调用。长期运行的工具调用可能导致 Episode 保持开启状态。
### Q: 如何迁移已有记忆的 agent_id？
Issue #1288 记录了此功能需求，允许在系统迁移时修改已有记忆的 agent_id，避免记忆丢失。
资料来源：[GitHub Issue #1288](https://github.com/MemTensor/MemOS/issues/1288)
---
## 检索系统
### 相关页面
相关主题：[系统架构](#architecture), [技能系统](#skill-system)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/retrieval/retrieve.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/retrieve.ts)
- [apps/memos-local-plugin/core/retrieval/ranker.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/ranker.ts)
- [apps/memos-local-plugin/core/retrieval/tier1-skill.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/tier1-skill.ts)
- [apps/memos-local-plugin/core/retrieval/tier2-trace.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/tier2-trace.ts)
- [apps/memos-local-plugin/core/retrieval/tier3-world.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/tier3-world.ts)
- [apps/memos-local-plugin/core/retrieval/query-builder.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/query-builder.ts)
- [apps/memos-local-plugin/core/storage/keyword.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/keyword.ts)
# 检索系统
## 概述
MemOS 的检索系统（Retrieval System）是记忆系统核心组件，负责将用户对话上下文转化为可注入宿主提示词（system prompt）的记忆片段。该模块实现 V7 §2.6 "Hierarchical Memory Retrieval" 规范，采用三层记忆架构（Tier 1/2/3），支持多通道混合检索（向量、FTS5、关键词、模式匹配、结构化匹配），并通过 Reciprocal Rank Fusion（RRF）算法实现跨通道结果融合。
**核心职责：**
- 根据不同触发场景选择合适的检索入口
- 构建查询向量和关键词提取
- 执行多通道并行检索
- RRF 排序与自适应相关性阈值过滤
- 生成可注入宿主系统的 `InjectionPacket`
**设计原则：**
- 纯读取操作，无写入
- 无 LLM 调用
- 通过私有事件总线发送流水线事件
资料来源：[core/retrieval/README.md:1-35]()
---
## 系统架构
### 模块结构
```
core/retrieval/
├── types.ts # DTO 定义（RetrievalDeps / RetrievalResult / Tier* shapes / ChannelRank）
├── query-builder.ts # 上下文 → 文本 + 标签 + ftsMatch + patternTerms
├── tier1-skill.ts # 技能检索（vec + fts + pattern）
├── tier2-trace.ts # 轨迹 + 事件聚合检索（vec×2 + fts + pattern + structural）
├── tier3-world.ts # 世界模型检索（vec + fts + pattern）
├── ranker.ts # 每通道 RRF + 相对阈值 + Smart-Seed MMR
├── llm-filter.ts # 后排序 LLM 精度通道（fail-closed）
├── injector.ts # RankedCandidate[] → InjectionPacket（+ 渲染）
├── retrieve.ts # 5 个入口点
├── events.ts # 事件总线创建
├── index.ts # 公开导出
└── README.md # 本文档
```
资料来源：[core/retrieval/README.md:68-84]()
### 检索管道流程
```mermaid
graph TD
A[检索请求] --> B[构建 Query]
B --> C[查询向量嵌入]
B --> D[提取 FTS5 关键词]
B --> E[提取 Pattern 词]
C --> F1[Tier1 向量检索]
C --> F2[Tier2 向量检索]
C --> F3[Tier3 向量检索]
D --> G1[FTS5 检索]
D --> G2[FTS5 检索]
D --> G3[FTS5 检索]
E --> H1[Pattern 检索]
E --> H2[Pattern 检索]
E --> H3[Pattern 检索]
F1 --> I[RRF 融合]
F2 --> I
F3 --> I
G1 --> I
G2 --> I
G3 --> I
H1 --> I
H2 --> I
H3 --> I
I --> J[自适应阈值过滤]
J --> K[LLM 精度过滤]
K --> L[Smart MMR 去重]
L --> M[生成 InjectionPacket]
```
---
## 三层记忆架构
### 层级对比
| 层级 | 源表 | 回答问题 | 语义粒度 |
|------|------|----------|----------|
| **Tier 1** | `skills` | "我是否有针对此任务的命名技能？" | 任务级 |
| **Tier 2** | `traces`, 事件聚合 | "上次我尝试这个时，什么有效？" | 步骤级 |
| **Tier 3** | `world_model` | "我实际在什么环境中操作？" | 推理级 |
资料来源：[core/retrieval/README.md:40-50]()
### Tier 1 — 技能检索
**职责：** 检索 η ≥ minEta 的活跃技能结晶。
**检索通道：**
- `vec`: `skills.vec` 余弦相似度
- `fts`: FTS5 trigram MATCH
- `pattern`: LIKE 模糊匹配（CJK 二元组 + 2 字符 ASCII）
**配置参数：**
- `tier1TopK`: 默认返回 Top-K 技能
```typescript
// tier1-skill.ts 核心逻辑
export async function retrieveTier1Skills(
query: RetrievalQuery,
deps: RetrievalDeps
): Promise
```
资料来源：[core/retrieval/tier1-skill.ts]()
### Tier 2 — 轨迹检索
**职责：** 检索高价值轨迹片段和子任务事件摘要。
**检索通道：**
- `vec_summary`: `traces.vec_summary` 余弦相似度
- `vec_action`: `traces.vec_action` 余弦相似度
- `fts`: FTS5 关键词匹配
- `pattern`: LIKE 模糊匹配
- `structural`: `instr(error_signatures_json, '""')` 结构化匹配
**特殊处理：**
- 事件聚合：将同一 episode 的多个轨迹合并
- 优先级加权：`weightCosine·cos + weightPriority·priorityFor(V, Δt)`
```typescript
// tier2-trace.ts 核心逻辑
export async function retrieveTier2Traces(
query: RetrievalQuery,
deps: RetrievalDeps
): Promise
```
资料来源：[core/retrieval/tier2-trace.ts]()
### Tier 3 — 世界模型检索
**职责：** 检索环境拓扑和推理规则。
**检索通道：**
- `vec`: `world_model.vec` 余弦相似度
- `fts`: FTS5 trigram MATCH
- `pattern`: LIKE 模糊匹配
```typescript
// tier3-world.ts 核心逻辑
export async function retrieveTier3World(
query: RetrievalQuery,
deps: RetrievalDeps
): Promise
```
资料来源：[core/retrieval/tier3-world.ts]()
---
## 检索入口点
系统提供 5 个公开入口点，每个入口根据场景选择执行哪些层级：
```typescript
import {
turnStartRetrieve, // 对话轮次开始 — 完整 Tier 1+2+3
toolDrivenRetrieve, // memos_search / memos_timeline 等工具调用
skillInvokeRetrieve, // Agent 即将调用 skill.
subAgentRetrieve, // 子 Agent 伴随任务提示启动
repairRetrieve, // N 次工具失败 → 反模式召回
} from "@memtensor/memos-local-plugin/core/retrieval";
```
资料来源：[core/retrieval/README.md:56-65]()
### 入口策略表
| 入口 | 执行的层级 | 允许低优先级（反模式） | 典型 Snippet 保留数 |
|------|------------|----------------------|---------------------|
| `turnStartRetrieve` | Tier 1 + 2 + 3 | 否 | 5 |
| `toolDrivenRetrieve` | Tier 2 + 3 | 否 | 3 |
| `skillInvokeRetrieve` | Tier 1 | 否 | 3 |
| `subAgentRetrieve` | Tier 1 + 2 | 是 | 3 |
| `repairRetrieve` | Tier 2 | 是 | 2 |
---
## 查询构建
`query-builder.ts` 实现了 `buildQuery(ctx)` 函数，是生成嵌入向量的唯一数据源：
```typescript
interface RetrievalQuery {
text: string; // 嵌入文本
tags: string[]; // 领域标签（docker、pip、plugin 等）
ftsMatch?: string; // FTS5 MATCH 语法
patternTerms?: string[]; // Pattern 模糊词（CJK 二元组 + 2-char ASCII）
}
```
**标签提取规则：**
使用与 `core/capture/tagger.ts` 相同的关键词表，确保检索标签过滤与捕获标签一致。
资料来源：[core/retrieval/query-builder.ts]()
---
## 多通道检索
### 通道类型
| 通道 | 源列 | 匹配方式 | 用途 |
|------|------|----------|------|
| `vec` | `skills.vec`, `world_model.vec` | 余弦相似度 | 语义召回 |
| `vec_summary` | `traces.vec_summary` | 余弦相似度 | 用户/助手对话语义召回 |
| `vec_action` | `traces.vec_action` | 余弦相似度 | Agent 动作/工具序列语义召回 |
| `fts` | FTS5 虚拟表 | trigram MATCH | 英文 + CJK ≥ 3 字符精确命中 |
| `pattern` | `LIKE '%term%'` | CJK 二元组 + 2-char ASCII | 低于 trigram 窗口的中文人名/动词 |
| `structural` | `instr()` | 错误签名精确匹配 | verbatim 错误签名回放 |
**设计意图：**
在多个通道中命中的行携带独立的 `ChannelRank`。排序器对每个通道求 `1 / (k + rank_i + 1)` 之和，使得向量和 FTS 双重确认的命中获得明显更高的 RRF 分数。
资料来源：[core/retrieval/README.md:88-97]()
### 关键词通道辅助
FTS5 和 Pattern 检索的辅助函数位于 `core/storage/keyword.ts`：
- `prepareFtsMatch()`: 构造 FTS5 MATCH 查询
- `extractPatternTerms()`: 提取 Pattern 匹配词
- `reciprocalRankScore()`: 计算 RRF 分数
资料来源：[core/storage/keyword.ts]()
---
## 排序器
`ranker.ts` 实现了排序逻辑，包含三个核心功能：
### 1. 每层级优先级混合
对于 Tier 2 轨迹和事件：
```
relevance = weightCosine·cos + weightPriority·priorityFor(V, Δt)
```
其中 `priorityFor(V, Δt)` 考虑：
- 轨迹价值评分 V
- 时间衰减 Δt
### 2. 自适应相关性阈值
排序后，计算 `topRelevance`（最高相关性），将所有低于 `topRelevance · relativeThresholdFloor`（默认 0.4）的候选者丢弃。
**自适应阈值优势：**
- 强查询：topRelevance 高，绝对阈值也随之升高
- 弱查询：topRelevance 低，阈值相应降低
### 3. Smart Seed MMR
在精排后，使用 Smart MMR 算法进行去重和多样性采样。
```typescript
// ranker.ts 核心接口
export function rank(
candidates: ChannelCandidates[],
config: RankerConfig
): RankedCandidate[]
```
资料来源：[core/retrieval/ranker.ts]()
---
## LLM 精度过滤
`llm-filter.ts` 在排序后执行可选的 LLM 后处理，用于精度提升：
- **模式：** fail-closed（LLM 调用失败时拒绝所有候选）
- **目的：** 减少假阳性，提升检索精度
- **触发条件：** 可配置，通常用于高价值查询
```typescript
// llm-filter.ts
export async function applyLlmFilter(
candidates: RankedCandidate[],
deps: RetrievalDeps
): Promise
```
资料来源：[core/retrieval/llm-filter.ts]()
---
## 注入包生成
`injector.ts` 负责将 `RankedCandidate[]` 转换为宿主系统可用的 `InjectionPacket`：
```typescript
interface InjectionPacket {
tier1?: SkillSnippet[]; // Tier 1 技能片段
tier2?: TraceSnippet[]; // Tier 2 轨迹片段
tier3?: WorldSnippet[]; // Tier 3 世界模型片段
rendered: string; // 渲染后的文本（可直接注入 prompt）
stats: RetrievalStats; // 检索统计信息
}
```
资料来源：[core/retrieval/injector.ts]()
---
## 配置参数
所有检索相关参数位于 `algorithm.retrieval.*` 配置路径：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `tier1TopK` | 3 | Tier 1 检索返回数 |
| `tier2TopK` | 5 | Tier 2 检索返回数 |
| `tier3TopK` | 3 | Tier 3 检索返回数 |
| `relativeThresholdFloor` | 0.4 | 自适应相关性阈值系数 |
| `weightCosine` | 0.7 | 向量权重 |
| `weightPriority` | 0.3 | 优先级权重 |
**高级配置：**
用户可见配置模板仅暴露 `tier1TopK / tier2TopK / tier3TopK`，其他参数使用文档化默认值（见 `docs/CONFIG-ADVANCED.md`）。
资料来源：[core/retrieval/README.md:119-125]()
---
## 事件系统
检索流水线通过私有 `RetrievalEventBus` 发送事件，供 Phase 15 等编排器转发至 viewer / 审计日志：
```typescript
import { createRetrievalEventBus } from "./events.js";
const bus = createRetrievalEventBus();
bus.emit("retrieval:start", { query });
bus.emit("retrieval:complete", { results });
```
---
## 已知问题与限制
### Issue #1361: Pattern 检索缺少 ownerFilter
**严重等级：** 高
**问题描述：** 在多 Agent 协作场景中，`memory_search` 工具的 patternSearch 分支缺少 `ownerFilter`，导致记忆隔离泄漏。
**影响范围：**
- 中文查询
- 短英文查询（2 字符）
**修复建议：** 在 patternSearch 分支添加与向量检索相同的 `ownerFilter` 过滤条件。
资料来源：[Issue #1361](https://github.com/MemTensor/MemOS/issues/1361)
### Issue #1318: memory_search 硬编码 owner 默认值
**问题描述：** `memory_search` 工具的 owner 默认值硬编码为 `"agent:main"`，而非当前 Agent。
**影响：** 多 Agent 场景下可能检索到错误 Agent 的记忆。
资料来源：[Issue #1318](https://github.com/MemTensor/MemOS/issues/1318)
---
## 相关文档
- [核心模块文档](../core/README.md)
- [存储系统](../storage/README.md)
- [捕获管道](../capture/README.md)
- [反馈系统](../feedback/README.md)
- [技能系统](../skill/README.md)
- [高级配置指南](../../docs/CONFIG-ADVANCED.md)
---
## 本地插件 (memos-local-plugin)
### 相关页面
相关主题：[云端插件 (OpenClaw Cloud Plugin)](#cloud-plugin), [多 Agent 支持与隔离](#multi-agent)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin)
- [apps/memos-local-plugin/bridge.cts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/bridge.cts)
- [apps/memos-local-plugin/viewer](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/viewer)
- [apps/memos-local-plugin/adapters/openclaw](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/openclaw)
- [apps/memos-local-plugin/adapters/hermes](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/hermes)
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md)
- [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md)
- [apps/memos-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json)
# 本地插件 (memos-local-plugin)
## 概述
memos-local-plugin 是 MemOS 2.0 的本地优先记忆核心，专为 **Hermes Agent** 和 **OpenClaw** 设计。它提供完全本地化的记忆存储，无需云端依赖，同时支持自进化记忆架构（L1 轨迹、L2 策略、L3 世界模型和结晶化 Skills）。 资料来源：[README.md]()
该插件通过统一的 TypeScript 核心连接多种 Agent 运行时，采用分层记忆检索策略实现上下文感知，并通过反馈驱动实现 Skill 的动态演进。 资料来源：[apps/memos-local-plugin/core/retrieval/README.md]()
## 架构概览
memos-local-plugin 采用**适配器架构**，将 TypeScript 核心与不同 Agent 运行时解耦：
```mermaid
graph TD
subgraph "Agent Runtimes"
HA[Hermes Agent]
OC[OpenClaw]
end
subgraph "Adapters"
HA_Adapter[hermes 适配器]
OC_Adapter[openclaw 适配器]
end
subgraph "Shared Core"
Retrieval[core/retrieval
三层检索引擎]
Feedback[core/feedback
反馈处理]
Skill[core/skill
Skill 生命周期]
Storage[core/storage
SQLite + FTS5]
end
subgraph "Storage"
SQLite[(SQLite
本地数据库)]
FTS[FTS5
全文索引]
end
HA --> HA_Adapter
OC --> OC_Adapter
HA_Adapter --> bridge[bridge.cts]
OC_Adapter --> bridge
bridge --> Retrieval
bridge --> Feedback
bridge --> Skill
Retrieval --> Storage
Feedback --> Storage
Skill --> Storage
Storage --> SQLite
Storage --> FTS
```
核心组件说明：
| 组件 | 路径 | 职责 |
|------|------|------|
| **bridge.cts** | `/` | JSON-RPC 桥接层，连接适配器与核心 |
| **core/retrieval** | `core/retrieval/` | Tier-1/2/3 检索引擎 |
| **core/feedback** | `core/feedback/` | 决策修复与反馈合成 |
| **core/skill** | `core/skill/` | Skill 生命周期管理 |
| **core/storage** | `core/storage/` | SQLite + FTS5 存储层 |
资料来源：[apps/memos-local-plugin/adapters/hermes/README.md]()
## 适配器层
### Hermes 适配器
Hermes Agent 是 Python 实现的 Agent，bridge 通过 **stdio JSON-RPC 2.0** 与其通信：
```
┌──────────────────────────┐ stdio JSON-RPC 2.0 ┌─────────────────────┐
│ Hermes Python 进程 │ ─────────────────────────────▶ │ node bridge.cts │
│ │ │ │
│ MemTensorProvider ──────┼───── turn.start / turn.end ───▶│ MemoryCore (core/) │
│ │◀──── events.notify ───────────│ │
│ │◀──── logs.forward ────────────│ │
└──────────────────────────┘ └─────────────────────┘
```
Python 端为**无状态代理**，所有算法逻辑（L1/L2/L3、skills、retrieval、feedback、decision repair）均位于共享的 TS 核心。 资料来源：[apps/memos-local-plugin/adapters/hermes/README.md]()
**协议接口表：**
| Hermes 钩子 | JSON-RPC 方法 | 用途 |
|------------|--------------|------|
| `initialize(session_id)` | `session.open` | 打开会话 |
| `turn.start()` | `turn.start` | 触发 L1/L2/L3 检索 |
| `turn.end(messages)` | `turn.end` | 保存轨迹，触发后处理 |
| `tool.start(id, name, input)` | `tool.start` | 记录工具调用开始 |
| `tool.end(id, output)` | `tool.end` | 记录工具调用结果 |
| `skill.apply(name)` | `skill.apply` | 记录 Skill 使用 |
| `feedback.submit(text)` | `feedback.submit` | 用户反馈入口 |
### OpenClaw 适配器
OpenClaw 适配器通过 Gateway 生命周期钩子与 OpenClaw 集成，支持记忆的自动召回与保存。 资料来源：[apps/memos-local-openclaw/package.json]()
```json
{
"openclaw": {
"id": "memos-local-openclaw-plugin",
"extensions": ["./index.ts"],
"skills": ["skill/memos-memory-guide"],
"installDependencies": true
}
}
```
## 三层检索引擎
core/retrieval 模块将用户输入转化为 `InjectionPacket`，这是插入宿主提示词的规范 DTO。它实现了 V7-§2.6 "Hierarchical Memory Retrieval" 规范。 资料来源：[apps/memos-local-plugin/core/retrieval/README.md]()
### 检索层级
| 层级 | 源表 | 召回内容 |
|------|------|----------|
| **Tier-1** | `skills` | 匹配的结晶化 Skills（η ≥ minEta） |
| **Tier-2** | `traces`, rollup | 高价值轨迹片段 + 子任务 episode 摘要 |
| **Tier-3** | `world_model` | 环境拓扑 / 推理规则 |
### 五个入口点
所有入口均返回 `RetrievalResult = { packet, candidates }`：
1. **turnStart** — Agent 对话轮次开始时触发
2. **toolDriven** — 工具调用时触发
3. **subAgent** — 子 Agent 启动时触发
4. **decisionRepair** — 决策修复事件触发
5. **skillTrigger** — Skill 触发检查
### 多通道检索
检索引擎通过五个通道并行搜索：
| 通道 | 索引字段 | 用途 |
|------|----------|------|
| `vec_summary` | `traces.vec_summary` cosine | 用户/助手对话的语义召回 |
| `vec_action` | `traces.vec_action` cosine | Agent 动作/工具序列的语义召回 |
| `vec` | `skills.vec`, `world_model.vec` cosine | Tier-1/Tier-3 语义召回 |
| `fts` | FTS5 trigram MATCH | 关键词精确命中（英文 + 中文 ≥ 3 字符） |
| `pattern` | `LIKE %term%` | 低于 trigram 窗口的 2 字符中文名/动词 |
多通道命中的行通过 **RRF (Reciprocal Rank Fusion)** 进行融合排序，同时被向量和 FTS 确认的命中会获得显著更高的排名。 资料来源：[apps/memos-local-plugin/core/retrieval/README.md]()
### 自适应阈值与智能 MMR
检索后，排名器计算 **top relevance** 并丢弃所有低于 `topRelevance · relativeThresholdFloor`（默认 0.4）的候选。Smart-seed MMR 确保多样性结果。
## Skill 系统
Skill 是从反馈中结晶化的高价值策略，执行时 η（效率值）达到阈值的 policy 会被打包为可执行 Skill。 资料来源：[apps/memos-local-plugin/core/skill/README.md]()
### Skill 结构
```typescript
interface SkillRow {
id: string;
name: string;
procedureJson: string; // 结构化步骤、参数、示例、前置条件
invocationGuide: string; // Markdown 提示块，插入系统提示词
eta: number; // 效率值
vec: number[]; // Skill 摘要 + 触发词的 embedding
sourcePolicyIds: string[]; // 源 policy ID 集合
status: 'probationary' | 'active' | 'retired';
}
```
### 生命周期状态机
`applyFeedback` 是单一状态转换函数：
| 信号 | 对 η 的影响 | 可能的 status 变化 |
|------|------------|-------------------|
| `trial.pass` | Beta 后验 `(passed+1)/(attempts+2)` | probationary → active |
| `trial.fail` | Beta 后验 | probationary → retired |
| `user.positive` | `η += etaDelta` | retired → probationary |
| `user.negative` | `η -= etaDelta` | any → retired |
| `reward.updated` | Blend 0.7·η + 0.3·newGain | any → retired |
资料来源：[apps/memos-local-plugin/core/skill/README.md]()
## 反馈系统
core/feedback 负责决策修复和反馈合成，将自然语言反馈转化为记忆优化操作。 资料来源：[apps/memos-local-plugin/core/feedback/README.md]()
### 反馈处理流程
```mermaid
graph LR
A[用户反馈文本] --> B[classifyFeedback]
B --> C{分类结果}
C -->|negative| D[extractAntiPattern]
C -->|positive| E[extractPreference]
C -->|neutral| F[discard]
D --> G[gatherRepairEvidence]
E --> G
G --> H[synthesizeDraft]
H --> I[attachRepairToPolicies]
I --> J[(decision_repairs 表)]
```
### 持久化
`decision_repairs` 是主表结构：
| 字段 | 说明 |
|------|------|
| `context_hash` | 冷却查找和检索的锚点 |
| `preference` | Agent 可见的正面指导 |
| `anti_pattern` | Agent 可见的反面指导 |
| `high_value_trace_ids` | 证据 JSON 数组 |
| `low_value_trace_ids` | 低价值证据 JSON 数组 |
| `validated` | UI 拇指向上门控，默认 false |
Policies 通过紧凑的 `@repair {json}` 标签内联携带指导。 资料来源：[apps/memos-local-plugin/core/feedback/README.md]()
### 公开 API
```typescript
export {
attachFeedbackSubscriber, // 连接四个输入通道
runRepair, // 命令式入口
classifyFeedback, // 独立分类器（UI 内联预览用）
createFailureSignals, // 滚动窗口追踪器
gatherRepairEvidence,
synthesizeDraft,
attachRepairToPolicies,
createFeedbackEventBus,
type FeedbackConfig,
type FeedbackEvent,
type DecisionRepairDraft,
type RepairInput,
type RepairResult,
}
```
## 存储层
### SQLite + FTS5
本地插件使用 SQLite 作为主存储，配合 FTS5 实现全文检索：
- **FTS5 trigram** — 英文和中文（≥3字符）的关键词检索
- **Pattern 搜索** — 2字符中文名/动词的回退检索
- **向量检索** — 语义相似度计算
### 数据库表
核心表包括：
| 表名 | 用途 |
|------|------|
| `traces` | L1 对话轨迹（包含 vec_summary, vec_action） |
| `policies` | L2 策略规则 |
| `world_model` | L3 世界模型 |
| `skills` | 结晶化 Skill |
| `decision_repairs` | 决策修复记录 |
| `episodes` | 子任务 episode 汇总 |
## 守护进程模式与 Viewer
插件支持 `--daemon` 模式启动，此时 HTTP Viewer 服务器在 `core.init()` 完成后启动。 资料来源：[社区 Issue #1839]()
```mermaid
graph TD
A[--daemon 启动] --> B[core.init 执行]
B --> C{init 是否阻塞?}
C -->|是| D[Viewer 延迟启动]
C -->|否| E[Viewer 立即启动]
D --> F[Heavy LLM/embedding API 调用]
F --> G[可能触发 API 限流]
```
**已知问题：** 当 `core.init()` 在大量 LLM/embedding API 调用中阻塞时，Viewer 可能无法及时启动，社区已报告相关 Issue（#1839, #1840, #1841）。
## 配置管理
所有配置项位于 `algorithm.retrieval.*` 和相关命名空间下。公开配置模板仅暴露关键参数：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `tier1TopK` | - | Tier-1 检索返回数量 |
| `tier2TopK` | - | Tier-2 检索返回数量 |
| `tier3TopK` | - | Tier-3 检索返回数量 |
| `relativeThresholdFloor` | 0.4 | 自适应相关性阈值 |
| `minTraceSim` | - | 绝对相似度下限 |
高级配置详见 `docs/CONFIG-ADVANCED.md`。 资料来源：[apps/memos-local-plugin/core/retrieval/README.md]()
## 已知问题与限制
### 多 Agent 记忆隔离漏洞
在 patternSearch 分支中，`ownerFilter` 缺失导致多 Agent 场景下的记忆隔离泄漏。中文查询和短英文查询受影响（Issue #1361）。
### Hardcoded Owner 默认值
`memory_search` 工具的 owner 默认硬编码为 `"agent:main"` 而非当前 Agent，导致记忆检索错误关联（Issue #1318）。
### 大型 Episode 后处理风暴
在长时间 OpenClaw 开发工作流中，大型 merged episodes 可能触发 L2/L3/skill-evolution 级联后处理，导致会话阻塞（Issue #1755）。
### Ollama 本地部署支持
社区请求添加原生 Ollama provider 支持，以实现完全本地化部署（Issue #1231）。
## 安装与使用
### NPM 包
```bash
npm install @memtensor/memos-local-plugin
```
### 依赖
```json
{
"engines": {
"node": ">=18.0.0"
}
}
```
资料来源：[apps/memos-local-openclaw/package.json]()
### 开发命令
| 命令 | 用途 |
|------|------|
| `npm run build` | TypeScript 编译 |
| `npm run dev` | 监听模式编译 |
| `npm run test` | 运行测试 |
| `npm run test:watch` | 监听模式测试 |
## 相关资源
| 资源 | 链接 |
|------|------|
| 官方网站 | https://memos-claw.openmem.net/ |
| 文档 | https://memos-docs.openmem.net/cn/openclaw/local_plugin |
| GitHub | https://github.com/MemTensor/MemOS/tree/main/apps/memos-local-plugin |
| NPM 包 | https://www.npmjs.com/package/@memtensor/memos-local-plugin |
---
## 云端插件 (OpenClaw Cloud Plugin)
### 相关页面
相关主题：[本地插件 (memos-local-plugin)](#local-plugin)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/MemOS-Cloud-OpenClaw-Plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/README.md)
- [apps/MemOS-Cloud-OpenClaw-Plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/package.json)
- [apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js)
- [apps/memos-local-plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md)
- [apps/memos-local-plugin/adapters/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/README.md)
# 云端插件 (OpenClaw Cloud Plugin)
## 概述
MemOS Cloud OpenClaw Plugin 是由 MemTensor 官方维护的 OpenClaw 生命周期插件，提供与 MemOS Cloud 的云端记忆交互能力。该插件属于轻量级集成方案，通过 OpenClaw Gateway 的生命周期钩子实现**记忆召回**和**记忆写入**两大核心功能。
| 属性 | 值 |
|------|-----|
| 包名 | `@memtensor/memos-cloud-openclaw-plugin` |
| 当前版本 | 0.1.12 |
| 许可证 | MIT |
| 入口文件 | `index.js` |
| 配置方式 | 配置文件 + 图形界面 |
### 与本地插件的定位差异
| 维度 | 云端插件 | 本地插件 (`memos-local-plugin`) |
|------|----------|--------------------------------|
| 记忆存储 | MemOS Cloud 服务器 | SQLite 本地数据库 |
| 嵌入模型 | 云端 API | 本地 HuggingFace Transformers |
| LLM 交互 | 依赖云端 | 可完全离线运行 |
| 依赖复杂度 | 低（仅需 API Key） | 高（含 Puppeteer、SQLite 等） |
| 适用场景 | 云端部署、简单集成 | 本地开发、完全隐私控制 |
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/README.md)
---
## 核心功能
### 记忆召回 (Recall)
插件在 OpenClaw Agent 启动前触发 `/search/memory` API 调用，将召回的相关记忆上下文注入到 Agent 的系统提示词中：
```mermaid
sequenceDiagram
participant OpenClaw as OpenClaw Gateway
participant Plugin as Cloud Plugin
participant MemOS as MemOS Cloud API
OpenClaw->>Plugin: before_agent_start 钩子触发
Plugin->>MemOS: GET /search/memory
MemOS-->>Plugin: 相关记忆列表
Plugin-->>OpenClaw: 注入上下文到 Prompt
```
### 记忆写入 (Add)
每次 Agent 对话结束后，插件通过 `agent_end` 钩子将对话内容写入 MemOS Cloud：
```mermaid
sequenceDiagram
participant OpenClaw as OpenClaw Gateway
participant Plugin as Cloud Plugin
participant MemOS as MemOS Cloud API
OpenClaw->>Plugin: agent_end 钩子触发
Plugin->>Plugin: 序列化对话消息
Plugin->>MemOS: POST /add/message
MemOS-->>Plugin: 写入确认
```
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/README.md)
---
## 安装与配置
### NPM 安装（推荐）
```bash
openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
openclaw gateway restart
```
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/README.md)
### 配置项说明
插件配置存储在宿主配置文件的 `plugins.entries.memos-cloud-openclaw-plugin.config` 路径下：
| 配置项 | 说明 | 必填 |
|--------|------|------|
| `MEMOS_API_KEY` | MemOS Cloud API 认证令牌 | 是 |
| `MEMOS_API_URL` | MemOS Cloud API 端点 | 是 |
| `enabled` | 插件启用状态（布尔值） | 否 |
### 认证方式
插件使用 **Token 认证**：
```
Authorization: Token
```
---
## 配置界面 (Config UI)
### 界面功能
插件启动时自动启动本地配置页面，提供以下功能：
| 功能 | 说明 |
|------|------|
| 查看当前配置 | 实时读取配置文件内容 |
| 结构化编辑 | 已知字段以表单控件展示 |
| JSON 编辑 | 未知字段保留在额外 JSON 区域 |
| 保存配置 | 写入配置文件 |
| 重启网关 | 触发 Gateway 重启 |
| 重新加载 | 从磁盘重新读取配置 |
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js)
### 界面地址
默认访问地址：`http://127.0.0.1:38463`
如首选端口已被占用，插件会自动选择下一个可用端口。
### 支持的宿主
| 宿主 | 配置文件路径 |
|------|-------------|
| OpenClaw | `~/.openclaw/openclaw.json` |
| Moltbot | `~/.moltbot/moltbot.json` |
| ClawDBot | `~/.clawdbot/clawdbot.json` |
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/README.md)
---
## 插件架构
### 入口点定义
插件通过 `package.json` 中的 `openclaw`、`moltbot`、`clawdbot` 字段声明生命周期钩子和扩展点：
```json
{
"openclaw": {
"hooks": ["./index.js"],
"extensions": ["./index.js"]
},
"moltbot": {
"hooks": ["./index.js"],
"extensions": ["./index.js"]
},
"clawdbot": {
"hooks": ["./index.js"],
"extensions": ["./index.js"]
}
}
```
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/package.json)
### 与本地插件的桥接架构对比
云端插件采用与本地插件不同的集成模式：
```mermaid
graph LR
subgraph 本地插件架构
A1[OpenClaw] --> B1[bridge.ts]
B1 --> C1[MemoryCore]
C1 --> D1[SQLite]
C1 --> E1[本地 Embedding]
end
subgraph 云端插件架构
A2[OpenClaw] --> B2[Cloud Plugin]
B2 --> C2[MemOS Cloud API]
end
```
| 架构特性 | 云端插件 | 本地插件 |
|----------|----------|----------|
| 进程模型 | 单进程 | 可分离进程（Hermes 适配器） |
| 内存调用 | 直接 API 调用 | 直接函数调用 |
| 网络依赖 | 必须 | 可选（离线模式） |
| 扩展工具 | 基础召回/写入 | memos_search、memos_get、memos_timeline 等 |
资料来源：[apps/memos-local-plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md)
---
## 生命周期钩子
| 钩子名称 | 触发时机 | 插件动作 |
|----------|----------|----------|
| `before_agent_start` | Agent 启动前 | 调用 `/search/memory` 召回记忆 |
| `agent_end` | Agent 对话结束后 | 调用 `/add/message` 写入记忆 |
---
## 发布管理
### 版本同步
插件使用脚本自动同步版本号：
```bash
npm run sync-version
```
发布时自动将版本变更提交到 Git：
```bash
npm version
git add openclaw.plugin.json moltbot.plugin.json clawdbot.plugin.json
```
### 发布命令
| 命令 | 说明 |
|------|------|
| `npm run publish-beta` | 发布 Beta 版本 |
| `npm run publish-beta-patch` | 预发布补丁版本到 Beta 频道 |
| `npm run publish-latest` | 发布正式版本 |
| `npm run publish-latest-patch` | 发布补丁正式版本 |
资料来源：[apps/MemOS-Cloud-OpenClaw-Plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/package.json)
---
## 已知问题与社区反馈
### 相关 Issue
| Issue | 类型 | 描述 |
|-------|------|------|
| [#1433](https://github.com/MemTensor/MemOS/issues/1433) | 功能请求 | 希望 OpenClaw 插件新增对自托管部署的 MemOS API 支持 |
| [#1472](https://github.com/MemTensor/MemOS/issues/1472) | 功能请求 | Hermes Agent MCP Plugin 开发请求 |
| [#1318](https://github.com/MemTensor/MemOS/issues/1318) | Bug | memory_search tool 默认 owner 为 "agent:main" 而非当前 agent |
### 自托管部署需求
社区有用户请求支持自托管的 MemOS 实例（而非仅支持官方 MemOS Cloud）。当前插件设计为云端优先，如需支持自托管可能需要扩展 API 端点配置能力。
---
## 使用建议
1. **首次配置**：安装后访问配置界面（通常在 `http://127.0.0.1:38463`），填入 MemOS Cloud API Key 和端点
2. **保存后重启**：部分配置变更需要手动重启 Gateway 才能生效
3. **多宿主支持**：如同时使用多个 Agent 宿主，需分别为每个宿主配置插件
4. **隐私敏感场景**：如需完全本地化的记忆管理，建议使用 `memos-local-plugin` 而非云端插件
---
## 多 Agent 支持与隔离
### 相关页面
相关主题：[本地插件 (memos-local-plugin)](#local-plugin), [检索系统](#retrieval-system)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/memos-local-plugin/core/id.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/id.ts)
- [apps/memos-local-plugin/core/runtime/namespace.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/runtime/namespace.ts)
- [apps/memos-local-plugin/core/storage/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/storage/README.md)
- [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)
- [apps/memos-local-plugin/core/retrieval/ranker.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/ranker.ts)
- [apps/memos-local-plugin/core/retrieval/tier1-skill.ts](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/tier1-skill.ts)
- [apps/memos-local-plugin/adapters/hermes/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/hermes/README.md)
# 多 Agent 支持与隔离
## 概述
MemOS 的多 Agent 支持允许在同一个 MemOS 实例中运行多个独立的 Agent，每个 Agent 拥有完全隔离的记忆空间、Skill 和世界模型。`memos-local-plugin` 通过 `agent_id` 字段实现数据层面的隔离，确保不同 Agent 的记忆不会相互泄露或干扰。
多 Agent 隔离的核心机制包括：
- **Agent 标识体系**：每个 Agent 通过唯一的 `agent_id` 进行标识
- **命名空间隔离**：运行时通过 namespace 机制管理 Agent 上下文
- **存储层过滤**：所有数据库查询默认附加 `ownerFilter` 条件
- **检索层过滤**：向量检索、关键词检索和模式检索均支持 `ownerFilter`
> **社区相关问题**：
> - Issue #1361 报告了 `patternSearch` 缺少 `ownerFilter` 导致的记忆隔离泄漏漏洞
> - Issue #1318 报告了 `memory_search` 工具硬编码 `owner` 为 `"agent:main"` 的问题
---
## Agent 标识体系
### agent_id 的结构
Agent ID 采用层级命名规范，格式为 `agent:` 或 `agent::`。主 Agent 通常使用 `agent:main`，子 Agent 可以使用 `agent:sub:task-xxx` 等格式。
```typescript
// core/id.ts 中的类型定义
interface AgentId {
role: string; // 如 "main", "sub", "worker"
name: string; // 具体名称
namespace: string; // 可选的命名空间前缀
}
```
### Agent ID 的分配
在不同运行时环境中，Agent ID 的分配方式如下：
| 运行时环境 | Agent ID 来源 | 配置方式 |
|-----------|--------------|---------|
| OpenClaw | Gateway 配置 | `config.yaml` 中 `agent.id` 字段 |
| Hermes | Python 端传入 | `initialize(session_id)` 时指定 |
| 本地开发 | 环境变量 | `MEMOS_AGENT_ID` 环境变量 |
```typescript
// adapters/hermes/README.md 中的会话初始化
const sessionId = await provider.initialize(agentSessionId);
// JSON-RPC 调用: session.open(sessionId, { agentId: ... })
```
---
## 命名空间隔离机制
### Runtime Namespace
`core/runtime/namespace.ts` 提供了运行时命名空间管理，为每个 Agent 会话维护独立的执行上下文：
```mermaid
graph TD
A[Agent Session 启动] --> B{创建/加入 Namespace}
B -->|主 Agent| C[namespace: main]
B -->|子 Agent| D[namespace: sub:{agentId}]
C --> E[加载对应 agent_id 的配置]
D --> E
E --> F[初始化 MemoryCore]
F --> G[关联 Storage Owner]
```
### Namespace 包含的内容
每个命名空间维护以下隔离资源：
| 资源类型 | 隔离级别 | 说明 |
|---------|---------|------|
| 记忆数据 | 严格隔离 | 仅返回 `owner = agent_id` 的记录 |
| Skills | 严格隔离 | 每个 Agent 独立的 Skill 演化树 |
| 世界模型 | 严格隔离 | 独立的 L3 抽象层 |
| 反馈历史 | 严格隔离 | 仅影响本 Agent 的 Skill η 值 |
| 检索上下文 | 会话隔离 | 临时会话级上下文 |
---
## 存储层隔离
### 数据库 Schema 中的 Owner 字段
所有核心数据表均包含 `owner` 字段，用于标识数据所属的 Agent：
```typescript
// core/storage/ 中的表结构
interface TraceRow {
id: string;
owner: string; // agent_id，必填
vec_summary: number[];
vec_action: number[];
// ...
}
interface SkillRow {
id: string;
owner: string; // agent_id
sourcePolicyIds: string[];
eta: number;
// ...
}
```
### ownerFilter 的实现
存储层在所有查询中自动附加 `ownerFilter` 条件：
```typescript
// 检索 traces 时自动过滤
async searchByVector(
queryVec: number[],
topK: number,
owner: string // 必须指定
): Promise {
const sql = `
SELECT * FROM traces
WHERE owner = ? -- ownerFilter
AND vec_summary MATCH ?
ORDER BY distance
LIMIT ?
`;
return db.all(sql, [owner, queryVec, topK]);
}
```
### 隔离泄漏漏洞 (Issue #1361)
社区报告了一个严重的隔离漏洞：在 `patternSearch` 分支中缺少 `ownerFilter`，导致中文查询和短英文查询会返回其他 Agent 的记忆。
**受影响版本**：memos-local-openclaw-plugin v4.x
**漏洞影响**：
| 查询类型 | 受影响范围 |
|---------|-----------|
| 中文查询 (≤2字符) | 可能泄露其他 Agent 记忆 |
| 短英文查询 (≤2字符) | 可能泄露其他 Agent 记忆 |
| 标准长度查询 | 正常走 FTS5 + ownerFilter |
**修复建议**：在 `patternSearch` 分支添加 `ownerFilter` 条件：
```typescript
// 修复后的 patternSearch
const sql = `
SELECT * FROM traces
WHERE owner = ? -- 添加 ownerFilter
AND pattern MATCH ?
LIMIT ?
`;
```
---
## 检索层隔离
### 多通道检索与 Owner 过滤
检索系统支持五种检索通道，每种通道均实现 `ownerFilter`：
| 检索通道 | 底层技术 | Owner 过滤 | 用途 |
|---------|---------|-----------|------|
| `vec` | 向量余弦相似度 | ✅ | 语义相似记忆 |
| `fts` | FTS5 trigram MATCH | ✅ | 关键词精确匹配 |
| `pattern` | LIKE %term% | ⚠️ 部分缺失 | 短中文/英文匹配 |
| `structural` | JSON 包含查询 | ✅ | 错误签名回放 |
| `keyword` | 域标签过滤 | ✅ | 领域分类检索 |
### Tier 级别的检索隔离
```mermaid
graph LR
A[Tier 1 检索] -->|Skill| B[skills 表
ownerFilter: agent_id]
A --> C[Skills 独立演化]
D[Tier 2 检索] -->|Trace| E[traces 表
ownerFilter: agent_id]
D --> F[Episodes 聚合]
G[Tier 3 检索] -->|World Model| H[world_model 表
ownerFilter: agent_id]
G --> I[环境抽象]
```
### Ranker 中的 Owner 上下文
`core/retrieval/ranker.ts` 在排序阶段维护 Owner 上下文：
```typescript
interface RetrievalContext {
agentId: string;
sessionId: string;
ownerFilter: string; // 来自 agentId
}
function rank(candidates: Candidate[], ctx: RetrievalContext): RankedCandidate[] {
// 所有候选必须通过 ownerFilter
return candidates
.filter(c => c.owner === ctx.ownerFilter)
.map(c => ({
...c,
rrfScore: calculateRRF(c)
}));
}
```
---
## 多 Agent 协作模式
### 主-从 Agent 协作
当主 Agent 派生子 Agent 时，可以共享部分上下文：
```typescript
// 主 Agent 创建子 Agent 会话
const subAgentId = `agent:sub:${taskId}`;
await bridge.session.open(subAgentId, {
parentAgentId: "agent:main",
missionContext: mainAgentContext
});
```
### 跨 Agent 记忆共享
MemOS 支持受控的跨 Agent 记忆共享：
```yaml
# config.yaml
multiAgent:
sharing:
# 允许子 Agent 读取主 Agent 的特定 Tier
readAncestorTiers: [1] # 只共享 Skill
# 允许特定域标签跨 Agent 可见
sharedDomains: ["common-knowledge"]
```
---
## Agent ID 迁移功能
Issue #1288 请求添加修改现有记忆 `agent_id` 的功能，以便在迁移系统时记忆不丢失。
### 迁移场景
| 场景 | 说明 |
|-----|------|
| Agent 重命名 | 将 `agent:main` 改为 `agent:primary` |
| 环境迁移 | 从开发环境迁移到生产环境 |
| 备份恢复 | 恢复时指定新的 Agent ID |
### 迁移 API
```typescript
// 管理员级别的 Agent ID 重写
interface AgentMigration {
fromAgentId: string;
toAgentId: string;
options: {
dryRun: boolean; // 预览不执行
updateSkills: boolean; // 同时迁移关联的 Skills
updatePolicies: boolean; // 同时迁移关联的 Policies
};
}
await memos.migrateAgent({
fromAgentId: "agent:main",
toAgentId: "agent:production",
options: { dryRun: true }
});
```
---
## 配置与最佳实践
### 多 Agent 配置模板
```yaml
# config.yaml
agent:
id: agent:main # 当前 Agent ID
multiAgent:
enabled: true
isolation:
strict: true # 强制严格隔离
allowCrossTier: false # 禁止跨 Tier 检索
registry:
- id: agent:main
role: primary
- id: agent:sub:analysis
role: analysis
parent: agent:main
```
### 开发调试建议
调试多 Agent 问题时，可使用以下命令查看隔离状态：
```bash
# 查看特定 Agent 的记忆数量
memos-cli query --agent agent:main --stats
# 查看跨 Agent 隔离泄漏
memos-cli audit --check-isolation
```
---
## 已知问题与限制
| Issue | 严重程度 | 描述 | 状态 |
|-------|---------|------|------|
| #1361 | 高 | patternSearch 缺少 ownerFilter | 已报告，待修复 |
| #1318 | 中 | memory_search 硬编码 agent:main | 已报告，待修复 |
| #1755 | 中 | 大型合并 Episode 触发 L2/L3 风暴 | 已修复 |
---
## 总结
MemOS 通过多层隔离机制支持多 Agent 场景：
1. **数据层**：所有表包含 `owner` 字段，查询自动附加 `ownerFilter`
2. **检索层**：五通道检索支持 Owner 过滤，Ranker 维护 Owner 上下文
3. **运行时层**：Namespace 机制为每个 Agent 会话提供独立上下文
4. **配置层**：灵活的 `config.yaml` 支持细粒度隔离策略
核心隔离依赖于所有查询路径正确应用 `ownerFilter`。社区发现的 `patternSearch` 隔离泄漏问题（Issue #1361）提醒我们，边界情况（如短文本模式匹配）仍需特别关注。
---
---
## Doramagic 踩坑日志
项目：MemTensor/MemOS
摘要：发现 12 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Daemon mode viewer blocked by core.init() — process cascade and API rate-limit spiral。
## 1. 安装坑 · 来源证据：Bug: Daemon mode viewer blocked by core.init() — process cascade and API rate-limit spiral
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Daemon mode viewer blocked by core.init() — process cascade and API rate-limit spiral
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_330e4904858d471396474b8fcad51b24 | https://github.com/MemTensor/MemOS/issues/1839 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：fix: Daemon viewer fails to start when core.init() blocks on dirty episode rescoring — triggers zombie process avalanche
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Daemon viewer fails to start when core.init() blocks on dirty episode rescoring — triggers zombie process avalanche
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0a3cd77cc4c046cdbef6607285d34155 | https://github.com/MemTensor/MemOS/issues/1841 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：memos-local-plugin: large merged episodes can trigger L2/L3/skill-evolution storm and stall OpenClaw sessions
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：memos-local-plugin: large merged episodes can trigger L2/L3/skill-evolution storm and stall OpenClaw sessions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e9b3d5a05cd1452e904e3882ddf8696e | https://github.com/MemTensor/MemOS/issues/1755 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 配置坑 · 来源证据：test: AutoDev PR assignment smoke test
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：test: AutoDev PR assignment smoke test
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5d4006dd3c1f479885cdfba90a741638 | https://github.com/MemTensor/MemOS/issues/1802 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1014729376 | https://github.com/MemTensor/MemOS | host_targets=claude, chatgpt
## 6. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1014729376 | https://github.com/MemTensor/MemOS | README/documentation is current enough for a first validation pass.
## 7. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1014729376 | https://github.com/MemTensor/MemOS | last_activity_observed missing
## 8. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1014729376 | https://github.com/MemTensor/MemOS | no_demo; severity=medium
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1014729376 | https://github.com/MemTensor/MemOS | no_demo; severity=medium
## 10. 安全/权限坑 · 来源证据：fix: The timed_with_status method was swallowing exceptions, making debugging difficult
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：fix: The timed_with_status method was swallowing exceptions, making debugging difficult
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_57aa58a45acb4c1cb7d644b3a4d1c3eb | https://github.com/MemTensor/MemOS/issues/1679 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 11. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1014729376 | https://github.com/MemTensor/MemOS | issue_or_pr_quality=unknown
## 12. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1014729376 | https://github.com/MemTensor/MemOS | release_recency=unknown