核心定位

MemOS 将 AI Agent 的记忆管理从分散的工具调用提升为系统级能力，实现了：

• 多层次记忆抽象：从 L1 执行痕迹到 L2 策略归纳，再到 L3 世界模型，形成完整的记忆层次结构
• 反馈驱动的自进化：通过自然语言反馈持续优化记忆质量，无需人工干预
• 异步高性能调度：基于 Redis Streams 的任务调度器，支持高并发场景下的毫秒级延迟
• 多知识库管理：支持多个可组合的记忆立方体（MemCube），实现跨用户、项目和 Agent 的隔离与共享

资料来源：README.md:1-20

系统架构

整体架构图

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

核心模块划分

资料来源：apps/memos-local-plugin/core/logger/README.md:1-25

三层记忆系统

MemOS 采用独特的三层记忆架构，分别对应不同的认知层级：

Tier-1：技能记忆（Skills）

存储已结晶化的技能程序，包含：

• procedureJson：结构化步骤、参数、示例和前置条件
• invocationGuide：可供 Agent 直接引用的 markdown 调用指南
• eta（经验值）：衡量技能可靠性的指标，范围 0-1

技能通过 applyFeedback 生命周期管理，支持以下状态转换：

资料来源：apps/memos-local-plugin/core/skill/README.md:1-45

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

Tier-3：世界模型（World Model）

存储环境拓扑和推理规则，支持深度推理时的上下文检索。

检索引擎

core/retrieval 模块是 MemOS 的检索核心，提供五个入口点：

多通道混合排名

检索采用 Reciprocal Rank Fusion（RRF）融合多个通道：

排名后应用自适应相关阈值：topRelevance · relativeThresholdFloor（默认 0.4），低于阈值的候选被丢弃。

资料来源：apps/memos-local-plugin/core/retrieval/README.md:1-60

反馈与自进化系统

core/feedback 模块实现反馈驱动的记忆优化：

反馈分类

• trial.pass/fail：Agent 试运行结果反馈
• user.positive/negative：用户显式评价
• reward.updated：奖励信号更新

决策修复（Decision Repair）

对于高频失败决策，系统自动生成修复指南：

{
  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

存储层

SQLite 配置

数据库入口

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

部署模式

本地部署（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

配置管理

所有算法参数位于 config.yaml 的 algorithm.* 路径下：

资料来源：apps/memos-local-plugin/core/retrieval/README.md:70-80

已知问题与社区热点

多 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）。

版本演进

资料来源：README.md:50-100

相关资源

• 文档站点：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:1-50

安装方式

方式一：Docker 快速部署（推荐）

这是最简洁的部署方式，适合生产环境和开发测试。

# 克隆仓库
git clone https://github.com/MemTensor/MemOS.git
cd MemOS

# 进入 Docker 目录
cd docker

# 复制环境变量配置
cp .env.example .env

# 编辑 .env 文件配置必要参数
nano .env

# 启动所有服务
docker-compose up -d

#### 环境变量配置

资料来源：docker/.env.example:1-30

方式二：本地开发部署

适用于需要修改源码或进行二次开发的高级用户。

# 安装后端依赖
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% 本地运行。

安装插件

# 使用安装脚本（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 服务

# 开发模式（实时日志）
npm run bridge

# 守护进程模式（后台运行 + HTTP 查看器）
npm run bridge:daemon

注意：守护进程模式下，HTTP 查看器在 core.init() 完成前不会启动。如果 core.init() 因大量 LLM/embedding API 调用而阻塞，查看器启动会延迟。详见 Issue #1839。

启动本地查看器

# 开发模式
npm run viewer:dev

# 构建生产版本
npm run build:viewer

配置指南

配置文件位置

核心配置项

# 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 提供者：

用户需求：社区已有功能请求添加原生 Ollama 支持，以实现完全本地化部署。详见 Issue #1231。

首次运行流程

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

数据库初始化

# 查看迁移状态
npm run db:migrate:status

# 执行迁移
npm run db:migrate

# 查看已应用的迁移
sqlite3 memos.db "SELECT name FROM schema_migrations;"

验证安装

启动后访问以下端点验证服务状态：

# 检查健康状态
curl http://localhost:3000/health

# 检查 API 版本
curl http://localhost:3000/api/version

# 查看记忆统计
curl http://localhost:3000/api/stats

常见问题排查

资料来源：Issue #1755，Issue #1361

日志查看

# 查看实时日志
tail -f logs/memos.log

# 查看错误日志
grep "ERROR" logs/memos.log

# 查看特定模块日志
grep "core.retrieval" logs/memos.log

记忆迁移

如需在不同系统间迁移记忆数据，可通过修改已有记忆的 agent_id 实现：

# 导出记忆
memos-cli export --agent old-agent --output memories.json

# 修改 agent_id 后导入
memos-cli import --agent new-agent --input memories.json

此功能由 Issue #1288 引入。

下一步

• 配置高级选项 - 深入调优检索和记忆算法
• 记忆反馈与修正 - 使用自然语言反馈精炼记忆
• 技能生命周期 - 理解技能从诞生到退休的完整流程
• 检索架构 - 深入了解三层检索系统

概述

MemOS 是一个多层次记忆管理系统，旨在为 AI Agent 提供长期记忆能力。该系统采用分层架构设计，支持从原始轨迹追踪（L1）到策略归纳（L2）再到世界模型抽象（L3）的完整记忆进化流程。资料来源：README.md:1-20

系统核心特性包括：

• 分层记忆管理：L1 轨迹、L2 策略、L3 世界模型的多层次抽象
• 异步调度：基于 Redis Streams 的任务调度器，支持毫秒级延迟
• 本地优先存储：SQLite WAL 模式，支持并发读写
• 反馈驱动的记忆修正：通过自然语言反馈持续优化记忆质量
• 多 Agent 隔离：基于 ownerFilter 的记忆隔离机制

整体架构

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 轨迹，失败捕获仍会发出轨迹存根

关键组件：

不变量：

• 每个最终化 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

技能数据结构：

技能状态转换：

检索系统

检索系统将用户输入转换为 InjectionPacket，通过多通道混合检索（向量、余弦相似度、FTS5、模式匹配）返回相关记忆。资料来源：apps/memos-local-plugin/core/retrieval/README.md:1-80

三层检索架构

检索入口点

import {
  turnStartRetrieve,     // 对话轮次开始 — 完整 Tier 1+2+3
  toolDrivenRetrieve,    // memos_search / memos_timeline 等工具驱动
  skillInvokeRetrieve,   // 技能调用前触发
  subAgentRetrieve,      // 子 Agent 伴随任务提示创建
  repairRetrieve,        // N 次工具失败 → 反模式召回
} from "@memtensor/memos-local-plugin/core/retrieval";

多通道排名算法

检索系统使用递归排名融合（RRF）算法整合多个检索通道：

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 配置：

数据表结构

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

反馈处理流程

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[存储更新]

测试覆盖

桥接层（Bridge）

Bridge 是 memos-local-plugin 与宿主 Agent（OpenClaw/Hermes）之间的通信层，负责协议转换和生命周期管理。资料来源：apps/memos-local-plugin/README.md:1-30

运行模式

守护进程模式已知问题

社区反馈揭示了守护模式下的多个问题（相关 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.* 配置路径下：

详细高级配置参见 docs/CONFIG-ADVANCED.md。

部署模式

本地插件部署（memos-local-plugin）

适用于需要 100% 本地部署的场景：

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 集成
└── ...

测试命令

概述

MemOS 采用分层记忆架构，将记忆按照抽象层级组织为 L1（轨迹层）、L2（策略层） 和 L3（世界模型层） 三个核心层次，辅以从 L2 提炼出的 Skills（技能层）。这一设计遵循 V7 文档中定义的"层次化记忆检索"（Hierarchical Memory Retrieval）理念，每一层回答不同粒度的问题：

资料来源：core/retrieval/README.md

概述

技能系统（Skill System）是 MemOS 本地插件中用于将反馈信号结晶化为可复用工具的核心模块。它是 MemOS 三层记忆架构中的 Tier-1 层级，负责在任务级别回答"Do I have a named skill for this?"这一关键问题。

技能系统从 L2 策略诱导和用户反馈中提取高价值行为模式，转化为结构化的技能（Skill），供 Agent 在后续执行中直接调用。技能系统与反馈系统、检索系统紧密协作，形成了完整的"反馈→学习→检索→执行"闭环。

资料来源：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

技能数据结构

技能以 SkillRow 的形式持久化存储，包含以下核心字段：

资料来源：core/skill/README.md:20-30

procedureJson 结构

procedureJson 字段包含技能的完整操作定义：

{
  "steps": ["步骤1", "步骤2", "步骤3"],
  "parameters": {
    "paramName": {
      "type": "string",
      "required": true,
      "description": "参数描述"
    }
  },
  "examples": [
    {
      "input": "示例输入",
      "output": "预期输出"
    }
  ],
  "preconditions": ["前置条件1", "前置条件2"]
}

invocationGuide 格式

invocationGuide 是供 Agent 适配器直接插入系统提示词的 Markdown 块：

## 技能：{skill_name}

**触发条件**: {trigger_description}

**执行步骤**:
1. {step_1}
2. {step_2}

**参数说明**:
- `{param_name}`: {description}

**注意事项**:
- {note_1}
- {note_2}

资料来源：core/skill/README.md:15-25

生命周期与状态机

技能状态

技能具有三种主要状态：

资料来源：core/skill/README.md:35-45

η 质量指标

η（eta）是技能的核心质量指标，采用 Beta 后验分布建模：

• 初始值从策略增益（gain）种子化
• 重建时从旧技能继承并重新缩放
• 范围 [0, 1]，值越高表示技能越可靠

状态转换规则

applyFeedback 函数（见 lifecycle.ts）是单一状态转换函数，applySkillFeedback 是其编排封装：

资料来源：core/skill/README.md:45-55

graph LR
    A[probationary] -->|trial.pass 阈值到达| B[active]
    A -->|trial.fail 阈值到达| C[retired]
    B -->|η < retireEta| C
    C -->|user.positive 阈值到达| A
    A -->|η < retireEta| C

反馈驱动进化

反馈信号来源

技能进化由反馈系统驱动，通过 SkillEventBus 事件总线发出信号：

// 反馈信号类型
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

与反馈系统集成

反馈系统中的 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

Tier-1 检索

检索通道

技能作为 Tier-1 层级，通过以下检索通道被召回：

资料来源：core/retrieval/README.md:1-20

检索流程

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 }：

import {
  turnStartRetrieve,     // 对话轮次开始 — 全量 Tier 1+2+3
  toolDrivenRetrieve,    // memos_search / memos_timeline 等工具驱动
  skillInvokeRetrieve,   // Agent 即将调用 skill.<name>
  subAgentRetrieve,      // 子 Agent 伴随任务提示词启动
  repairRetrieve,        // N 次工具失败 → 反模式召回
} from "@memtensor/memos-local-plugin/core/retrieval";

资料来源：core/retrieval/README.md:60-80

配置参数

技能系统的主要配置项位于 config.yaml 的 algorithm.retrieval.* 路径下：

进阶配置文档：docs/CONFIG-ADVANCED.md

资料来源：core/retrieval/README.md:100-110

源代码结构

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

社区关注与已知问题

大型合并事件触发技能风暴

Issue #1755 报告了在长时间运行的 OpenClaw 开发工作流中，memos-local-plugin 可能创建或重新打开非常大的 episode，进而触发级联的昂贵后处理（包括技能进化），可能使 OpenClaw 会话停滞。

症状：

• 大型合并事件后技能进化请求激增
• L2/L3 抽象与技能演化同时触发
• API 速率限制螺旋

建议措施：

• 监控 episode 大小，设置合并阈值
• 考虑批量处理技能进化请求
• 实现冷却期机制避免风暴

资料来源：memos-local-plugin issues #1755

记忆所有权隔离问题

Issue #1318 和 Issue #1361 报告了 memory_search 工具硬编码默认所有者为 agent:main 而非当前 Agent 的问题，这可能导致多 Agent 场景下的记忆隔离泄漏。

这与技能系统直接相关，因为技能作为 Tier-1 记忆也可能受到所有权隔离问题影响。

资料来源：memos-local-plugin issues #1318, #1361

方法论设计

技能系统的设计遵循 "Reflect to Evolve" 方法论：

1. 反馈收集：从试用结果、用户评价、奖励更新中收集反馈信号
2. 质量评估：使用 Beta 后验分布评估技能可靠性
3. 状态进化：基于质量指标动态调整技能生命周期状态
4. 检索优化：多通道 RRF 排名确保高质量技能优先召回

资料来源：docs/Reflect2Skill_方法论设计.md

最佳实践

技能创建

• 从成功的 L2 策略诱导中创建新技能
• 确保 procedureJson 包含足够的上下文和前置条件
• 提供清晰的 invocationGuide 供 Agent 理解

技能维护

• 定期检查 η 值处于边缘状态的技能
• 关注 probationary 状态的技能转化率
• 清理长期处于 retired 状态的技能

故障排查

• 检查 SkillEventBus 事件日志
• 验证检索返回的技能是否符合预期
• 监控 η 值异常波动的技能

概述

会话与 Episode 管理是 MemOS 本地插件的核心模块，负责管理 Agent 生命周期内的对话上下文边界。该模块作为外部世界（适配器 ↔ Agent ↔ 多用户）与算法流水线之间的桥梁，确保每个 LLM 侧的内存操作都能正确关联到已知的会话和 Episode。

这一管理机制的核心职责包括：

• 会话生命周期管理：创建、维护和清理与 Agent 进程的逻辑连接
• Episode 状态追踪：跟踪每次用户查询及其完整的 Agent 响应弧（包括工具调用、子 Agent）
• 意图分类：在会话开始时对用户意图进行分类，为后续处理提供上下文
• 事件驱动架构：通过事件总线协调各模块之间的协作

资料来源：core/session/README.md

核心概念

MemOS 采用三层结构来组织对话数据，每个层级都有其特定的职责和生命周期。

Session 与 Episode 的关系

graph TB
    subgraph Session["Session（长期）"]
        A["sessions 表<br/>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 的完整生命周期管理。

const sm = createSessionManager({
  sessionsRepo: adaptSessionsRepo(sqliteSessions),
  episodesRepo: adaptEpisodesRepo(sqliteEpisodes),
  intentClassifier: intent
});

主要职责：

• 创建和管理会话实例
• 启动和追踪 Episode
• 处理 Turn 的添加和 finalization
• 管理空闲会话的清理
• 优雅关闭时的资源回收

资料来源：core/session/README.md:公共API

#### 2. IntentClassifier（意图分类器）

IntentClassifier 使用 LLM 对用户意图进行分类，为后续处理提供上下文。

const intent = createIntentClassifier({ 
  llm, 
  timeoutMs: 5000 
});

关键特性：

• 支持 disableLlm=true 配置，用于 llm.provider=local_only 场景
• 当禁用 LLM 时，分类器不会尝试网络调用，避免本地部署失败

资料来源：core/session/README.md:注意事项

数据流

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

核心函数

import { 
  createSessionManager, 
  createIntentClassifier,
  adaptSessionsRepo, 
  adaptEpisodesRepo 
} from "@memos/core";

SessionManager 方法

资料来源：core/session/README.md:公共API

存储层集成

数据库 Schema

会话和 Episode 数据存储在 SQLite 数据库中，与其他数据（traces、skills、policies 等）共存于同一数据库文件。

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({...});

数据库配置

资料来源：core/storage/README.md:Pragmas

Episode 生命周期

状态流转

stateDiagram-v2
    [*] --> idle: 系统启动
    idle --> open: 用户发起查询
    open --> open: addTurn()
    open --> finalized: finalizeEpisode()
    open --> abandoned: abandonEpisode()
    finalized --> [*]
    abandoned --> [*]
    
    note right of open: 子 Agent 消息<br/>通过 addTurn() 添加
    note right of finalized: 触发 capture<br/>reward 计算<br/>L2/L3 诱导

大型 Episode 问题

已知问题（Issue #1755）：在长时间运行的 OpenClaw 开发工作流中，memos-local-plugin 可能创建或重新打开非常大的 Episode，进而触发昂贵的后处理级联：

• capture 执行时间显著增加
• Reward 重新评分
• L2 策略诱导
• L3 世界模型抽象
• Skill 进化

这可能导致 OpenClaw 会话停滞。社区正在积极处理这一问题。

资料来源：GitHub Issue #1755

事件系统

Session 模块通过事件总线与其他核心模块协调工作。

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);
});

事件类型

配置选项

IntentClassifier 配置

interface IntentClassifierConfig {
  llm: LlmClient;           // LLM 客户端实例
  timeoutMs: number;        // 超时时间，默认 5000ms
  disableLlm?: boolean;     // 禁用 LLM（用于 local_only 模式）
}

SessionManager 配置

interface SessionManagerConfig {
  sessionsRepo: SessionsRepo;      // 会话仓储
  episodesRepo: EpisodesRepo;      // Episode 仓储
  intentClassifier: IntentClassifier; // 意图分类器
  idleTimeoutMs?: number;         // 空闲超时，默认 30 分钟
}

最佳实践

1. 正确的初始化顺序

// 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. 生命周期管理

// 启动会话
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:注意事项

局限性

资料来源：core/session/README.md:注意事项

测试

模块提供了完整的测试覆盖，位于 tests/unit/session/：

• session-manager.test.ts — 会话生命周期、幂等性、空闲清理
• intent-classifier.test.ts — 分类逻辑、超时处理
• session.integration.test.ts — 端到端集成测试

# 运行会话模块测试
npm test -- tests/unit/session

相关模块

常见问题

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

概述

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

概述

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 运行时解耦：

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<br/>三层检索引擎]
        Feedback[core/feedback<br/>反馈处理]
        Skill[core/skill<br/>Skill 生命周期]
        Storage[core/storage<br/>SQLite + FTS5]
    end
    
    subgraph "Storage"
        SQLite[(SQLite<br/>本地数据库)]
        FTS[FTS5<br/>全文索引]
    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

核心组件说明：

资料来源：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

协议接口表：

OpenClaw 适配器

OpenClaw 适配器通过 Gateway 生命周期钩子与 OpenClaw 集成，支持记忆的自动召回与保存。 资料来源：apps/memos-local-openclaw/package.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

检索层级

五个入口点

所有入口均返回 RetrievalResult = { packet, candidates }：

1. turnStart — Agent 对话轮次开始时触发
2. toolDriven — 工具调用时触发
3. subAgent — 子 Agent 启动时触发
4. decisionRepair — 决策修复事件触发
5. skillTrigger — Skill 触发检查

多通道检索

检索引擎通过五个通道并行搜索：

多通道命中的行通过 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 结构

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 是单一状态转换函数：

资料来源：apps/memos-local-plugin/core/skill/README.md

反馈系统

core/feedback 负责决策修复和反馈合成，将自然语言反馈转化为记忆优化操作。 资料来源：apps/memos-local-plugin/core/feedback/README.md

反馈处理流程

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 是主表结构：

Policies 通过紧凑的 @repair {json} 标签内联携带指导。 资料来源：apps/memos-local-plugin/core/feedback/README.md

公开 API

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字符中文名/动词的回退检索
• 向量检索 — 语义相似度计算

数据库表

核心表包括：

守护进程模式与 Viewer

插件支持 --daemon 模式启动，此时 HTTP Viewer 服务器在 core.init() 完成后启动。 资料来源：社区 Issue #1839

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.* 和相关命名空间下。公开配置模板仅暴露关键参数：

高级配置详见 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 包

npm install @memtensor/memos-local-plugin

依赖

{
  "engines": {
    "node": ">=18.0.0"
  }
}

资料来源：apps/memos-local-openclaw/package.json

开发命令

相关资源

概述

MemOS Cloud OpenClaw Plugin 是由 MemTensor 官方维护的 OpenClaw 生命周期插件，提供与 MemOS Cloud 的云端记忆交互能力。该插件属于轻量级集成方案，通过 OpenClaw Gateway 的生命周期钩子实现记忆召回和记忆写入两大核心功能。

与本地插件的定位差异

资料来源：apps/MemOS-Cloud-OpenClaw-Plugin/README.md

概述

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" 的问题

Pitfall Log / 踩坑日志

项目：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