MemOS Local Plugin v2.0.8 — 深度研究报告

Codex 核验（2026-10-09）：本报告为当时的源码观察。式 (1−λ)+λ·γ^(T−t) 中，γ 调低会增强对近期步骤的偏重；γ→1 或 λ=0 才趋于均匀。V̄_with−V̄_without 是观察分组差值，未经随机对照不能称为策略的因果增益。当前 Hermes 的 memory.provider 一次激活一个 provider；gbrain 与 MemOS 共存需要显式组合 provider/独立工具，不是设置两个名称即自动共存。首次下载本地 embedding 模型需要网络；LLM 回退到远端时内容仍会出机。依据Hermes memory provider 源码。

基于完整源码分析：@memtensor/memos-local-plugin (Reflect2Evolve V7) 研究日期: 2026-07-15

---

1. 整体架构

1.1 模块关系图

┌─────────────────────────────────────────────────────────────────────┐
│                       agent-contract/ (DTO + JSON-RPC + Events)      │
│   TurnInputDTO, TurnResultDTO, InjectionPacket, CoreEvent, Errors   │
└────────────┬────────────────────────────────────────────────┬───────┘
             │  JSON-RPC (stdio/TCP)                           │ in-process
┌────────────▼──────────┐                    ┌────────────────▼────────┐
│  bridge/ (stdio.ts)   │                    │  adapters/hermes/       │
│  bridge.cts           │◄──── JSON-RPC ────►│  __init__.py (Python)   │
│  methods.ts (dispatch)│                    │  MemTensorProvider      │
└────────────┬──────────┘                    └─────────────────────────┘
             │
┌────────────▼────────────────────────────────────────────────────────┐
│                              core/                                   │
│                                                                      │
│  ┌─────────┐    ┌──────────┐    ┌──────────┐    ┌───────────────┐   │
│  │ capture │───►│  reward  │───►│ L2 (policy)│───►│ L3 (world    │   │
│  │ (L1)    │    │(backprop)│    │ induction  │    │  model)      │   │
│  └─────────┘    └──────────┘    └──────────┘    └───────┬───────┘   │
│                                                         │           │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────▼───────┐   │
│  │ retrieval    │◄───│ feedback     │◄───│    skill             │   │
│  │ (T1/T2/T3)   │    │ (repair)     │    │ (crystallization)    │   │
│  └──────────────┘    └──────────────┘    └──────────────────────┘   │
│                                                                      │
│  ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐ ┌────────────┐  │
│  │ session  │ │ config  │ │ storage  │ │ llm    │ │ embedding  │  │
│  │ manager  │ │ schema  │ │ (SQLite) │ │ client │ │ engine     │  │
│  └──────────┘ └─────────┘ └──────────┘ └────────┘ └────────────┘  │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │  pipeline/ (orchestrator.ts + memory-core.ts)                │   │
│  │  The single `createPipeline` -> MemoryCore facade            │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
         │                           │
         ▼                           ▼
┌─────────────────┐    ┌──────────────────────────────┐
│  server/ (HTTP)  │    │  viewer/ (Preact SPA)        │
│  port :18800     │    │  Memory Viewer Dashboard     │
│  REST API + SSE  │    │  Tasks/Policies/Skills/Logs  │
└─────────────────┘    └──────────────────────────────┘

1.2 数据流（一次完整的用户交互周期）

User Turn
   │
   ▼
onTurnStart() ──► Intent Classifier ──► Injection Scheduler
   │                                        │
   │                                        ▼
   │                             Three-Tier Retrieval (T1/T2/T3)
   │                                        │
   │                                        ▼
   │                              InjectionPacket (context)
   │
   ▼
Agent acts (LLM call + tool calls)
   │
   ▼
onTurnEnd() ──► Lite Capture (extract steps, summarize, embed)
   │
   ▼  (episode finalized?)
Topic-End Reflection ──► Reward Scoring (R_human) ──► Backprop (V_t)
   │
   ▼
L2 Induction (policy discovery from traces)
   │
   ▼
L3 Abstraction (world model from policy clusters)
   │
   ▼
Skill Crystallization (procedures from policies)
   │
   ▼
Feedback/Repair (failure detection, decision guidance)

---

2. 三层记忆模型

2.1 L1 Trace (Step-Level Grounded Records)

文件: core/capture/, core/types.ts (TraceRow)

• 定义: 每一条 L1 trace 对应 agent 的一步操作（一个 tool call 或一段 assistant 文本），记录 action + observation + reflection + value
• 核心字段: id, episodeId, sessionId, userText, agentText, summary, toolCalls, reflection, value, alpha, rHuman, priority, tags, errorSignatures, vecSummary, vecAction, turnId
• Capture 流程 (core/capture/capture.ts):
  • runLite(): 每轮对话后增量提取新 steps → normalize → 生成 summary → embed → 写入 trace rows (reflection=null, alpha=0)
  • runReflect(): 主题结束后批量 reflection 评分（windowed batch mode）→ 回写 reflection + alpha → 触发 downstream reward
  • Windowed batch 模式: 主窗口 20 条（overlap 3），退化到 9 条（overlap 3），episode 级别回退。反射分类: PIVOTAL(alpha=1) > RELATED/RELATED_DEFAULT(alpha=0.5) > IRRELEVANT(alpha=0)
• Embedding: 双向量 vecSummary（用户意图语义）+ vecAction（agent 行为语义），支持 6 种 embedding provider（local/openai/gemini/cohere/voyage/mistral）

2.2 L2 Policy (Sub-Task Strategies)

文件: core/memory/l2/l2.ts

• 定义: 跨 trace 归纳出的子任务策略模式，核心是触发条件 + 操作步骤 + 验证标准 + 边界条件
• PolicyRow 核心字段: id, title, trigger, procedure, verification, boundary, support, gain, status (candidate|active|archived), experienceType, evidencePolarity, decisionGuidance (preference/antiPattern), skillEligible
• Induction 流程 (runL2):
  1. Associate: 每个高 V trace 与现有 policy 做 cosine + signature 匹配。匹配到的 bump support；未匹配的进入 candidate pool
  2. Candidate Pool: 按 PatternSignature 分桶，等待收集足够多的 episodes (minEpisodesForInduction)
  3. Induce: 对 ready buckets 运行 l2.induction LLM prompt → 生成 draft policy
  4. Dedup: 检查 content duplication + cosine similarity 去重
  5. Gain Computation: G = V̄_with − V̄_without，经 EMA 平滑 (gainEmaAlpha=0.4)
  6. Status Transition: candidate → active (gain ≥ minGain, support ≥ minSupport), active → archived (gain < archiveGain)
• PatternSignature: 从 trace 的 error signatures + tool names + tags 计算的语义指纹，用于跨候选池匹配

2.3 L3 World Model (Environmental Cognition)

文件: core/memory/l3/l3.ts

• 定义: 从多个相关 L2 policy 中抽象出的环境认知模型，包含拓扑结构 (ℰ)、行为规则 (ℐ)、约束禁忌 (𝒞)
• WorldModelRow 核心字段: id, title, body (markdown), structure ({environment, inference, constraints}), domainTags, confidence, policyIds, status (active|archived), version
• Abstraction 流程 (runL3):
  1. Gather: 收集所有 active policies（gain ≥ minPolicyGain=0.02, support ≥ minPolicySupport=1）
  2. Cluster: 使用 clusterPolicies() 按 domain key + centroid proximity 分簇（minSimilarity=0.6）
  3. Cooldown: 每个 domain tag 有 cooldown 保护（默认 1 天），避免反复抽象
  4. Abstract: 对每个存活 cluster 运行 l3.abstraction LLM prompt → 生成结构化 (ℰ, ℐ, 𝒞) draft
  5. Merge or Create: 与现有 world model 做 cosine 比较，高于阈值则 merge/update，否则 insert new
  6. Confidence: 初始 confidence=0.5，positive feedback +0.05，negative -0.05；confidence < 0.2 的隐藏于 Tier-3 检索

---

3. 反射加权回报回传算法

文件: core/reward/backprop.ts

这是 MemOS 的核心信用分配机制，公式：

f_t = (1-λ) + λ·γ^(T-t)          # 时序位置权重
recovery_t = 1 if α_t>0 and α_{t-1}=0 else 0  # 恢复信号
r_t = 1 + δ·recovery_t            # 恢复加成
w_t = α_t · f_t · r_t             # 综合权重
V_t = (w_t / Σw) · R_human        # 当 Σw>0
V_t = 0                           # 当 Σw=0

参数:

• γ (gamma=0.9): 时序衰减因子，越靠近任务结束的步骤权重越高
• λ (lambda=0.5): 位置偏置混合系数，0=全平坦，1=纯 γ^(T-t) 衰减
• δ (delta=0.1): 恢复加成系数，当 alpha 从 0 变为 >0 时给予额外权重
• α_t (alpha): 反射权重，从 reflection 分类映射：IRRELEVANT→0, RELATED→0.5, RELATED_DEFAULT→0.5, PIVOTAL→1

Priority 衰减:

priority_t = max(V_t, 0) · 0.5^(Δt_days / halfLifeDays)

• decayHalfLifeDays=30: 30 天内 priority 衰减到一半

完整 Reward 管线 (core/reward/reward.ts):

1. Episode 终了 → 构建 task summary
2. 收集 explicit/implicit feedback
3. scoreHuman(): R_human ∈ [-1, 1]，通过 LLM 评分或 heuristic 回退
4. backprop(): 按上述公式分配 V_t 到每个 trace
5. Persist: 更新 trace 的 value/alpha/rHuman/priority，更新 episode 的 rTask/outcome
6. Emit reward.updated → 触发下游 L2/L3/Skill

Episode Outcome:

• rTask ≥ 0.5 → success
• rTask ≤ -0.15 → failure
• 中间值 → unknown

---

4. 技能结晶机制

文件: core/skill/skill.ts, core/skill/crystallize.ts

4.1 Eligibility 评估

evaluateEligibility() 对每个 L2 policy：

• success 模式: support ≥ minSupport(2), gain ≥ minGain(0.02) → crystallize
• 已有 skill 的新 evidence: 与现有 skill 内容比对 → rebuild 或 skip
• 无证据 / 低质量: skip

4.2 Crystallization 流程

1. Gather evidence: 从 policy 关联的 trace 中精选高 V traces
2. Gather counter-examples: V<0 的 negative trace（用于 anti-pattern）
3. LLM call: SKILL_CRYSTALLIZE_PROMPT (或 SKILL_REBUILD_PROMPT) → 生成结构化 draft
4. Verifier: verifyDraft() — 启发式一致性检查
5. Build SkillRow: packager.buildSkillRow() — 构建完整技能行
6. Upsert: 写入 skills 表，状态为 candidate
7. Graduation: 经过 candidateTrials(3) 次 trial（tracked in skill_trials），通过验证后晋升为 active

4.3 SkillRow 核心字段

• name: 规范化名称
• invocationGuide: 调用指南（Markdown，注入到 agent prompt）
• procedureJson: 结构化过程（工具序列）
• eta: 采用率 [0,1]，η < 0.1 时归档
• support, gain: 从源 policy 继承
• evidenceAnchors: 结晶时的证据 L1 trace 列表
• decisionGuidance: { preference, antiPattern }
• repairOrigin: 是否从修复流程产生（晋升门槛更高）

4.4 Rebuild 机制

• L1 (minor): 仅更新 eta/support/gain，不修改 procedure
• L2 (major): 重新生成整个 skill（允许改名，仅限于 repair-origin skill 的首次 rebuild）
• L3 (full): 重建 invocationGuide + procedure + evidence 全部

---

5. 检索策略

文件: core/retrieval/retrieve.ts

5.1 Three-Tier Architecture

(数字 = 默认 topK)

5.2 多通道检索

每个 tier 使用多个通道并行查询，最后通过 RRF (Reciprocal Rank Fusion) 融合：

• Vector (cosine): vecSummary / vecAction / vec
• FTS5 (full-text): SQLite FTS5 索引
• Pattern (LIKE): CJK 双字母 + 短 ASCII 回退
• Structural (error signatures): V7 §2.6 精确错误签名匹配

5.3 Ranking Pipeline

1. Channels → Candidates: 每个通道返回 (id, score) 对
2. Fusion (RRF): score = Σ[1/(k + rank_per_channel)]，k=60
3. Blend: 最终 relevance = weightCosine·cosine + weightPriority·priority (0.6:0.4)
4. MMR (Maximal Marginal Relevance): λ=0.7 平衡相关性与多样性
5. LLM Filter: 小模型 LLM 判断 semantic relevance，丢弃无关项
6. Relative Threshold: 低于 topRelevance × 0.2 的丢弃

5.4 Injection Scheduler

文件: core/injection/scheduler.ts

基于 Intent 分类的结果决定检索计划：

---

6. Hermes 集成方式

文件: adapters/hermes/memos_provider/__init__.py (MemTensorProvider)

6.1 生命周期钩子映射

6.2 Communication Protocol

• Transport: stdio (JSON-RPC 2.0 over stdin/stdout to Node.js bridge.cts)
• Alternative: TCP mode (bridge.cts with --daemon)
• Python → Node: JSON-RPC request messages
• Node → Python: JSON-RPC responses + notifications (events, logs)
• Host LLM Bridge: Python adapter registers host.llm.complete handler → MemOS 可以回退到 Hermes 自己的 LLM 做 scoring/skill-evolution

6.3 关键适配细节

• Tool call capture: 注册 post_tool_call hook 实时捕获工具调用 → 在 sync_turn 中 flush
• Model thinking capture: 从 post_llm_call 的 conversation_history 提取 reasoning 块
• Verifier feedback 识别: _is_verifier_feedback_prompt() 检测自然反馈模式
• Hermes 内部 review 过滤: 识别 Hermes 的 background memory/skill review turns 并跳过
• Tool failure 检测: _on_transform_tool_result() 在连续失败 ≥3 次后附加 repair hint

6.4 工具清单

Hermes 可用的记忆工具（get_tool_schemas()）:

• memos_search — 语义搜索记忆
• memos_get — 获取单条 trace
• memos_timeline — 时间线预览
• memos_environment — 环境/世界认知
• memos_skill_list — 列出技能
• memos_skill_get — 获取完整技能

---

7. 配置项详解

7.1 顶层配置

7.2 Provider 配置

7.3 Algorithm 配置

Capture:

Reward:

L2 Induction:

L3 Abstraction:

Skill:

Retrieval:

Session:

---

8. JSON-RPC 协议接口

文件: agent-contract/jsonrpc.ts, bridge/methods.ts

JSON-RPC 2.0 完整方法注册表:

Lifecycle: core.init, core.shutdown, core.health Session/Episode: session.open, session.close, episode.open, episode.close Turn Pipeline: turn.start, turn.end Memory Queries: memory.search, memory.get_trace, memory.get_policy, memory.get_world, memory.list_episodes, memory.timeline, memory.list_traces, memory.list_world_models Skills: skill.list, skill.get, skill.archive Retrieval: retrieval.query Subagent: subagent.record Config: config.get, config.patch Hub: hub.status, hub.publish, hub.pull Observability: logs.tail, logs.forward, events.subscribe, events.unsubscribe

---

9. Viewer & Server

文件: server/http.ts, server/routes/*, viewer/dist/

• HTTP Server: 纯 Node.js http 模块（无框架），扁平路由
• Viewer SPA: Preact (Dist 文件在 viewer/dist/)，在浏览器中渲染
• API: RESTful JSON API at /api/v1/*
• SSE Events: 实时事件流 (events.subscribe → events.notify)，驱动 Overview 面板
• 端口: Hermes → :18800, OpenClaw → :18799
• 安全: API key gating + session cookie (可选密码保护)
• Viewer 仪表板:
  • Overview: 实时活动流（记忆/经验/环境/技能/反馈摘要）
  • Tasks: 任务列表（episodes）按时间线排列
  • Memories: L1 trace 浏览
  • Policies: L2 经验/策略
  • Skills: 已结晶技能
  • Environment: L3 世界模型
  • Logs: 结构化日志查看器
  • Settings: 配置管理

---

10. 最佳实践总结

10.1 部署配置建议

1. 轻量模式 vs 完整模式:

   • algorithm.lightweightMemory.enabled: true — 仅摘要+检索，适合大多数用户
   • false — 完整自演化闭环（L2/L3/Skill），需要强 LLM（建议 skillEvolver 使用专用模型）

2. LLM 策略:

   • llm.provider = host — 复用 Hermes 的 LLM（零配置）
   • 若启用了完整 self-evolution，设置 skillEvolver.provider + skillEvolver.model 为更强模型
   • llm.fallbackToHost: true — provider 失败时回退，确保健壮性

3. Embedding:

   • local (默认) — 零配置，all-MiniLM-L6-v2 384 维，离线可用
   • 生产环境可切换到 openai_compatible/voyage 以获得更高精度

4. Reward 调参:

   • gamma 0.9 关注近期步骤；调低会更偏重近期，趋近 1 才更均匀
   • decayHalfLifeDays 30 天：适合长期记忆；短期工作流可调低
   • minExchangesForCompletion 保持 1（支持单轮 CLI 模式）

10.2 检索场景优化

1. LLM Filter:

   • llmFilterEnabled: true + llmFilterMaxKeep: 8 — 推荐，大幅降低无关注入
   • llmFilterCandidateBodyChars：默认 500 chars，token 预算充足时可调高

2. Skill 注入模式:

   • skillInjectionMode: summary — 默认，只在 prompt 中注入摘要 + 调用提示
   • 通过 memos_skill_get 工具在需要时拉取完整内容
   • 这比 full 模式更 token 高效

3. 域名 (domain) 预设:

   • 默认 "" — 适用于通用 agent 会话
   • domain: ir — 信息检索专用模式，使用 readOnlyInjectionProfile 约束注入类型

10.3 Session 与 Episode 策略

• followUpMode: merge_follow_ups — 适合需要连续上下文的场景（默认）
• mergeMaxGapMs 默认 2h — 超过 2 小时自动新 episode
• 如果需要精确的逐任务信用分配，使用 episode_per_turn

10.4 运维

• SQLite 数据库自动管理，无需手动维护
• Viewer 位于 :18800 — 浏览器实时监控记忆活动
• 日志轮转默认 50MB × 14 份，审计日志永久保存
• 配置修改后无需重启 agent（通过 /api/v1/config 热更新）

---

11. 与现有架构（gbrain + multi-layer-memory）的对比和互补

11.1 对比

11.2 互补关系

两者不是替代关系，而是互补的：

1. MemOS 强在「从经验中学习」:

   • 自动归纳跨任务策略（L2 Policy Induction）
   • 构建环境认知模型（L3 World Model）
   • 自主结晶可调用技能（Skill Crystallization）
   • 反射加权回报回传（Reflection-Weighted Backprop）

2. gbrain 强在「知识管理」:

   • 结构化的知识图谱（页面+链接+事实）
   • Schema pack 类型系统
   • 语义搜索 + 假设推理
   • 多源联邦查询

3. 推荐的融合方式:

   • gbrain 作为长期知识库：存储结构化知识、公司信息、人脉关系、决策记录
   • MemOS 作为经验记忆系统：存储 agent 的操作经验、成功模式、失败教训、自生成的技能
   • 共存设计需组合 memory provider 或将另一系统暴露为独立工具——gbrain 提供知识检索，MemOS 提供经验检索；尚未证明原生自动共存

4. 具体分工建议:

   • 文档和知识类 → gbrain (put_page/query 等)
   • agent 历史交互和经验模式 → MemOS (memos_search/memos_skill_get)
   • 用户反馈来自每个 Hermes 对话自然流入 MemOS 的反射+回传回路
   • MemOS 结晶的技能可作为 skill_view 的补充来源

11.3 数据流图（共存场景）

Hermes Agent
   │
   ├── on_turn_start()
   │   ├── gbrain.query() → 知识注入
   │   └── memos.turn.start() → 经验检索 (T1/T2/T3)
   │
   ├── agent acts
   │
   └── on_turn_end()
       ├── gbrain.extract_facts() → 知识提取
       └── memos.turn.end() → 痕迹捕获 → 反射 → 回报 → 归纳 → 结晶

---

附录: 关键文件索引