1. 项目定位与核心能力

MemOS 是一个面向大语言模型与 AI Agent 的记忆操作系统（Memory Operating System），目标是把长期记忆的存储、检索、管理统一为一套可组合的运行时层，使对话系统具备上下文感知、个性化以及自我演化能力 README.md:1-30。

仓库同时维护三类交付物：

核心能力可归纳为五点：

1. 统一记忆 API：增删改查接口结构化为可检视、可编辑的记忆图谱，避免黑盒向量库。
2. 多模态记忆：原生支持文本、图像、工具轨迹与角色画像 README.md:32-50。
3. 多 Cube 知识库：通过可组合的 Memory Cube 实现用户、项目、Agent 间的隔离与共享。
4. MemScheduler 异步摄入：基于 Redis Streams 的任务调度，支持优先级、自动恢复与配额 README.md:18-28。
5. 记忆反馈与纠错：用自然语言修订、补充或替换既有记忆。

此外 examples/README.md 提供了 basic_modules、core_memories、mem_cube、mem_agent 等可直接运行的示例，便于快速验证 API 行为 examples/README.md:1-30。

2. 分层架构与运行时视图

MemOS 在仓库中按"核心库 + 插件 + 端侧算法引擎"三层组织。

flowchart TB
    subgraph Apps["应用与插件层"]
        A1[OpenClaw / Hermes Agent 适配器]
        A2[MemOS Cloud Plugin<br/>apps/MemOS-Cloud-OpenClaw-Plugin]
    end
    subgraph Core["核心库 src/memos"]
        B1[MemOS 主类 / 统一 API]
        B2[MemScheduler<br/>Redis Streams + 优先级队列]
        B3[插件框架<br/>base.py / manager.py / hooks.py]
        B4[MemCube / 知识库]
    end
    subgraph Local["端侧算法引擎 apps/memos-local-plugin/core"]
        C1[L1 捕获与轨迹]
        C2[L2 策略归纳]
        C3[L3 世界模型]
        C4[三阶检索 Tier-1/2/3]
        C5[Skill 结晶 + Feedback]
    end
    A1 --> C1
    A2 --> B1
    B1 --> B2
    B1 --> B3
    B1 --> B4
    B3 --> C1
    C1 --> C2 --> C3
    C1 --> C4
    C2 --> C5

核心库的插件系统通过 Python 入口点组 memos.plugins 发现外部实现，由 PluginManager 在启动期加载、按优先级去重并初始化；插件可以挂载 FastAPI 路由、中间件、运行时组件以及 Hook 回调，而不侵入核心请求处理路径 src/memos/plugins/README.md:18-44。

端侧引擎把记忆显式划分为三个层级：L1 traces（执行轨迹）、L2 policies（策略归纳）、L3 world_model（环境/推理规则），并在它们之上结晶出可复用的 Skill apps/memos-local-plugin/core/memory/l1/README.md:1-20。检索侧对应 Tier-1 技能、Tier-2 轨迹与子任务回放、Tier-3 世界模型，分别回答"有没有现成技能""上次怎么做的""环境是什么样"三个不同问题 apps/memos-local-plugin/core/retrieval/README.md:15-40。

3. 关键子系统与协同流程

• 检索管线：core/retrieval 提供 turnStart、toolDriven 等 5 个入口，输出标准化的 InjectionPacket 供适配器塞入宿主提示词；它对每路通道（向量 / FTS5 / 模式匹配 / 结构化）计算 RRF 分数，并对最终候选应用自适应阈值与 MMR 去冗 apps/memos-local-plugin/core/retrieval/README.md:1-60。
• LLM 抽象层：core/llm 把 openai_compatible、anthropic、gemini、bedrock、host、local_only 六类提供方封装到统一 LlmClient 门面后；本地部署场景可选用 local_only 显式禁用 LLM，也支持将请求回投宿主 Agent apps/memos-local-plugin/core/llm/README.md:1-30。
• Skill 生命周期：applyFeedback 是单一状态转移函数，按 trial.pass / trial.fail / user.positive / user.negative 等信号更新 Beta 后验与 η 系数，触发 probationary ↔ active ↔ retired 转换 apps/memos-local-plugin/core/skill/README.md:1-40。
• 反馈与决策修复：core/feedback 收集四类输入信号生成 DecisionRepairDraft，将偏好与反模式以 @repair {json} 内联到 policy，供下次 Skill 打包时吸收 apps/memos-local-plugin/core/feedback/README.md:1-40。
• 云端召回协议：Cloud 插件内置"四步裁决"（来源验证、归属核查、强相关性、新鲜度）以过滤 AI 推测与噪声记忆，避免直接以 [assistant观点] 标签的摘要作为事实 apps/MemOS-Cloud-OpenClaw-Plugin/lib/memos-cloud-api.js:1-60。

4. 部署形态、社区关注与已知边界

MemOS 同时提供云端托管（memos.openmem.net）与本地化部署，并区分轻量 Quick Mode 与全量 Full Mode 两套部署镜像 README.md:60-80。

社区近期关注集中在以下几点，应在集成时留意：

• 多 Agent 隔离：历史上曾出现 patternSearch 缺少 ownerFilter 导致跨 Agent 记忆泄露的问题（#1361）以及 memory_search 默认 owner 硬编码为 agent:main 的回归（#1318）。当前 v2.0.20 引入了"按 hubInstanceId 隔离共享状态"的修复 apps/memos-local-plugin/package.json:1-40，多 Agent 场景应显式校验返回片段的 owner。
• CJK 检索：FTS5 内置分词器对 2 字中文（早报、你好）以及混合 ASCII+CJK token（C盘、API网关）存在召回盲区；社区正在推动可配置 FTS5 tokenizer 的方案（#1961）。当前实现通过 LIKE %term% 的 pattern 通道为短词兜底，但生产环境建议同步监控 FTS 命中率。
• 本地化生态：用户希望为本地插件增加 Hermes Agent MCP 插件（#1472）、自托管 MemOS API 支持（#1433）以及原生 Ollama provider（#1231）；在本地引擎选型时，可优先参考 core/llm 的 local_only 哨兵与 openai_compatible 适配层。
• 检索管线演进：v2.0.20 的 refactor: add search pipeline hooks for context rendering 把 context 渲染独立为可插拔 hook，便于在不改算法的前提下替换注入格式（参见 Release v2.0.20）。

See Also

• MemOS 插件系统详解
• 三阶检索管线（Tier-1 / Tier-2 / Tier-3）
• MemScheduler 与异步摄入
• Skill 生命周期与反馈回路

概述

MemOS 的核心记忆框架围绕四个相互协作的子系统构建：MemCube 作为统一的记忆容器，MemScheduler 负责异步摄入与任务调度，MemReader 处理多模态原始数据的解析与结构化，检索管线 在查询时执行多通道混合召回。该体系的目标是为 LLM 提供"可检查、可编辑、可分层"的记忆抽象，区别于传统"黑盒向量库"。框架同时通过插件机制（src/memos/plugins/README.md）和适配器层（apps/memos-local-plugin/adapters/README.md）扩展到 OpenClaw、Hermes Agent 等宿主运行时。

flowchart LR
    U[用户/Agent 消息] --> R[MemReader<br/>解析与结构化]
    R --> Q[MemCube<br/>L1 痕迹/L2 策略/L3 世界模型]
    Q -.异步摄入.-> S[MemScheduler<br/>Redis Streams 队列]
    Q --> P[(持久化<br/>SQLite/PolarDB/Neo4j)]
    Q <--> T[检索管线<br/>vec+fts+pattern+structural]
    T --> L[LLM 上下文渲染]
    F[反馈信号] --> Q

MemCube：分层可组合的记忆容器

MemCube 是 MemOS 抽象出的"记忆立方体"概念，对应 README 中描述的 Multi-Cube KB——用户、项目、Agent 各自持有一个或多个可组合的立方体，支持隔离与受控共享（README.md）。每个 MemCube 的内部结构按 L1 痕迹（traces）/ L2 策略（policies）/ L3 世界模型 / 结晶化技能（Skills） 分层组织，并由 MemScheduler 异步演化（apps/memos-local-plugin/package.json 中的 *description* 字段：*layered L1/L2/L3 memory, reflection-weighted value backprop, cross-task policy induction, skill crystallization*）。

每个 MemCube 实例的类型由 GeneralMemCubeConfig 等配置类定义，仓库内置样例 examples/data/mem_cube_2/ 即为 memos.configs.mem_cube.GeneralMemCubeConfig（examples/data/mem_cube_2/README.md）。按照迁移指南，原先直接访问 mem_cube.text_mem.get_all() 的旧式 API 已被 SingleCubeView / CompositeCubeView 取代（examples/mem_cube/_deprecated/README.md）。新的 View 架构提供统一 API、跨多立方体组合能力，并在结果中携带 cube_id 字段以便追踪来源。

MemScheduler：基于 Redis Streams 的异步调度

MemScheduler 在 README 的 v1.0.1 更新中明确为"基于 Redis Streams 与队列隔离重建"的任务调度器，特性包括 任务优先级、自动恢复与配额调度（README.md）。其默认 LLM 入口在 v2.0.10 改为 general_llm（参考 Release v2.0.10 变更日志），并为 OpenAI MemReader 增加 backup config。调度器面向"毫秒级延迟的异步记忆摄入"，与同步 API 共同提供 Add/Retrieve/Edit/Delete 的统一能力，仓库内提供完整示例 examples/mem_scheduler/（examples/README.md）。

MemReader：多模态原始数据解析

MemReader 负责把文本、文件、图像、消息等多模态原始输入转化为可入库的记忆结构，examples/mem_reader/ 下分类了 parser、builder、sample、runner 等演示（examples/README.md）。MemReader 内部严重依赖 LLM 层做结构化抽取，apps/memos-local-plugin/core/llm/ 通过 LlmClient 外观暴露五大真实提供者（openai_compatible / anthropic / gemini / bedrock / host）与 local_only 哨兵（apps/memos-local-plugin/core/llm/README.md），所有算法层必须经过该外观以避免耦合供应商 SDK。

MemReader 的输出会经由 core/feedback/ 中的 attachFeedbackSubscriber / runRepair 进入 *decision_repairs* 表，把失败信号综合成 L2 策略补丁 @repair {json} 内联到 policy.boundary，再由 core/skill/packager.ts 重新结晶（apps/memos-local-plugin/core/feedback/README.md、apps/memos-local-plugin/core/skill/README.md）。

检索管线：多通道混合召回

apps/memos-local-plugin/core/retrieval/ 描述了"六通道 + RRF"的混合召回策略（apps/memos-local-plugin/core/retrieval/README.md）：

多通道融合采用 RRF：候选在多个通道出现时累加 1 / (k + rank_i + 1)，单通道误报被自然抑制。随后采用自适应阈值 topRelevance · relativeThresholdFloor（默认 0.4）剔除弱匹配，并结合 MMR 提升多样性。v2.0.20 进一步引入 *search pipeline hooks for context rendering* 重构（Release v2.0.20），把上下文渲染阶段拆分为可插拔 hook。Hermes 适配器还通过 bridge_client.py 的 JSON-RPC stdio 把 Node 实现的算法核暴露给 Python 宿主（apps/memos-local-plugin/adapters/hermes/README.md）。

已知问题与社区关注

• CJK 短词召回：FTS5 三元组窗口对 2 字中文（"早报""你好""配置"）以及混合 ASCII+CJK（"C盘""API 接口"）失效，社区在 #1961 提议引入可配置的 FTS5 tokenizer，并通过新增 pattern 通道进行兜底。
• 多 Agent 隔离：memos-local-openclaw-plugin 的 patternSearch 路径曾缺失 ownerFilter（#1361），memory_search 工具曾将 owner 硬编码为 "agent:main"（#1318），后续在 v2.0.12/v2.0.13 多次修复并以 hubInstanceId 隔离共享状态。
• LLM 后备：v2.0.10 为 OpenAI MemReader 增加 backup config；v2.0.19 修正"失败任务被错误记为成功经验"；社区在 #1231 提议为 memos-local-openclaw 增加原生 ollama 提供者，覆盖 embedding 与 summarizer。

参见

• README.md
• src/memos/plugins/README.md
• apps/memos-local-plugin/core/retrieval/README.md
• apps/memos-local-plugin/core/skill/README.md
• examples/mem_cube/_deprecated/README.md

概览

MemOS 提供三种面向 Agent 的记忆插件，分别覆盖"本地自托管"、"本地 OpenClaw 旧链路"和"云托管调用"三种部署形态。核心框架位于 src/memos/plugins，通过 Python 入口点 memos.plugins 发现插件，由 PluginManager 加载、按优先级去重、并初始化启用的插件（src/memos/plugins/README.md:30-41）。

下表汇总三个核心插件的定位与能力差异：

资料来源：README.md:50-75；apps/memos-local-plugin/package.json:2-25；apps/MemOS-Cloud-OpenClaw-Plugin/README.md:1-30。

memos-local-plugin：分层记忆与本地核心

memos-local-plugin 自述为 *Reflect2Evolve memory plugin*，提供 L1 trace、L2 policy、L3 world model 三层结构与 skill 结晶，由反馈驱动检索（apps/memos-local-plugin/package.json:3-4）。其核心检索管线包含六条通道：vec_summary、vec_action、vec、fts、pattern、structural，其中 fts 使用 FTS5 三元组匹配（迁移 010），pattern 通过 LIKE %term% 处理 CJK 二元组与 2 字符 ASCII（apps/memos-local-plugin/core/retrieval/README.md:23-35）。多通道命中按 1/(k+rank_i+1) 求和（RRF），并在 top relevance 上施加 relativeThresholdFloor（默认 0.4）以过滤弱候选（apps/memos-local-plugin/core/retrieval/README.md:42-50）。

Skill 子系统通过 Beta 后验、状态机迁移（probationary → active → retired）与事件总线管理结晶后的经验；生命周期由 applyFeedback 单一状态转移函数驱动（apps/memos-local-plugin/core/skill/README.md:38-50）。feedback 子系统负责决策修复（decision repair），提供 runRepair、classifyFeedback 等入口，并持久化到 decision_repairs 表，包含 context_hash（用于冷却检索）、preference/anti_pattern（指导条目）以及证据 JSON（apps/memos-local-plugin/core/feedback/README.md:38-58）。

LLM 层提供 openai_compatible、anthropic、gemini、bedrock、host、local_only 六个 Provider，统一通过 LlmClient 门面调用（apps/memos-local-plugin/core/llm/README.md:11-25）。社区已请求对 memos-local-openclaw 增加原生 Ollama 支持以实现真正的全本地部署（#1231）。

memos-local-openclaw：早期本地 OpenClaw 插件

memos-local-openclaw-plugin 定位为 *full-write, hybrid-recall, progressive retrieval*，面向 OpenClaw 单一宿主环境，使用 index.ts 作为主入口并通过 openclaw.extensions 注册（apps/memos-local-openclaw/package.json:2-20）。v2.0.11 起引入多 OpenClaw 共享、双实例隔离与 viewer 改进；v2.0.13 修复 hubInstanceId 作用域共享问题并增加 hub embedding 与并行召回（Release v2.0.13）。

社区报告其 memory_search 的 patternSearch 分支缺少 ownerFilter，在多 Agent 协作下会出现记忆隔离泄漏（#1361），而 owner 默认硬编码为 "agent:main" 也被反馈过（#1318）。针对 CJK 短查询，仓库已规划可配置的 FTS5 tokenizer（#1961）。

MemOS Cloud OpenClaw Plugin：云端生命周期桥接

云插件 memos-cloud-openclaw-plugin 通过 openclaw.hooks 与 openclaw.extensions 注册到 OpenClaw Gateway（apps/MemOS-Cloud-OpenClaw-Plugin/package.json:14-30），在 before_agent_start 调用 /search/memory 召回上下文，在 agent_end 调用 /add.message 写回，使用 Authorization: Token <MEMOS_API_KEY>（apps/MemOS-Cloud-OpenClaw-Plugin/README.md:5-12）。插件附带本地 Config UI（默认 http://127.0.0.1:38463），可直接读写 ~/.openclaw/openclaw.json、~/.moltbot/moltbot.json、~/.clawdbot/clawdbot.json，端口冲突时自动顺延（apps/MemOS-Cloud-OpenClaw-Plugin/README.md:14-30）。社区希望该插件同时支持自托管 MemOS 部署的 API（#1433）。

适配器：OpenClaw 与 Hermes Agent

memos-local-plugin 共享一个 TS 核心，并通过两个适配器桥接不同宿主。OpenClaw 适配器使用 extensions 注册；Hermes Agent 适配器是 Python 实现，因此通过 bridge.cts 的 stdio JSON-RPC 2.0 通道调用核心（apps/memos-local-plugin/adapters/hermes/README.md:9-22）。Python 端是无状态的 MemTensorProvider，所有 L1/L2/L3、Skill、Retrieval、Feedback、Decision Repair 逻辑都在共享的 TS 核心中实现。Hermes 钩子（如 initialize(session_id)）映射为 session.open 等 JSON-RPC 方法，并以 events.notify 与 logs.forward 反向回传（apps/memos-local-plugin/adapters/hermes/README.md:24-32）。

openwork-memos-integration 提供了面向 macOS (Apple Silicon) 的本地 Agent 演示安装包；它调用用户自身的 OpenAI/Anthropic/Google/xAI/Ollama 密钥（apps/openwork-memos-integration/README.md）。仓库 examples/ 目录包含 API、基本模块、核心记忆、MemCube、Dream、MemChat、MemAgent 等可运行示例（examples/README.md:18-35）。v2.0.20 引入的 *search pipeline hooks for context rendering*（#1924）使宿主可在检索后对上下文渲染进行二次处理，便于集成方实现自定义格式化。社区也已为 Hermes Agent 提出 MCP 插件请求（#1472）。

已知限制与社区关注点

• 多 Agent 隔离：memos-local-openclaw 的 patternSearch 缺 ownerFilter，中文/短英文查询在协作场景下存在跨 Agent 泄漏（#1361；#1318）。
• CJK 检索精度：FTS5 三元组无法覆盖 2 字符中文及 ASCII+CJK 混合词，社区提案引入可配置 tokenizer（#1961）。
• Provider 覆盖：希望补齐 memos-local-openclaw 的 Ollama provider 支持（embedding + summarizer）（#1231）。
• 部署灵活性：云插件希望同时支持自托管 MemOS API（#1433），并补齐 Hermes Agent 的 MCP 适配（#1472）。

See Also

• MemOS 插件框架（src/memos/plugins）
• memos-local-plugin 2.0（Reflect2Evolve）
• memos-local-openclaw-plugin
• MemOS Cloud OpenClaw Plugin
• MemOS Examples
• Openwork × MemOS Integration

部署模式总览

MemOS 项目提供多种部署形态,以适配云端与本地、托管与自托管的不同使用场景。根据 README.md 的描述,核心部署选项分为以下几类:

对于本地化部署场景,memos-local-plugin 提供了面向 Hermes Agent 与 OpenClaw 的本地记忆插件,支持 100% 本地存储、零云依赖,功能上覆盖 L1 traces、L2 policies、L3 world models 以及技能结晶演化 README.md。

本地插件部署

memos-local-plugin 的打包与发布由其 package.json 控制。其 scripts 段定义了完整的构建、测试与启动流程:

# 构建 TypeScript 与运行时资源
npm run build

# 同时构建 viewer (前端)
npm run build:viewer

# 启动桥接进程
npm run bridge
# 或以后台守护模式
npm run bridge:daemon

来源:apps/memos-local-plugin/package.json

postinstall 钩子 (scripts/postinstall.cjs) 在安装完成后自动执行,Windows 平台的安装体验在 v2.0.17 起被增强,详见社区反馈 Release v2.0.17 中 feat: enhance memos-local-plugin Windows installation experience。

配置文件管理

所有配置都通过 YAML 加载与写入。core/config 模块提供以下能力 apps/memos-local-plugin/core/config/README.md:

• 行级错误定位 的 YAML 读取 (reader.ts)
• 保留注释与顺序 的深度合并写入 (writer.ts)
• 首次启动无配置文件 时记录警告并使用默认值,不会因缺失配置导致崩溃
• 写入后自动重新 chmod 600,防止密钥意外泄露
• Web viewer 的 GET /api/config 在返回前端前会脱敏 敏感字段

graph LR
  A[配置文件读取] --> B{文件存在?}
  B -- 是 --> C[reader.ts 行级解析]
  B -- 否 --> D[使用默认值 + 警告日志]
  C --> E[writer.ts 深度合并]
  D --> E
  E --> F[chmod 600 写入磁盘]
  E --> G[脱敏后暴露给 Viewer]

运维与日志

core/logger 提供了面向多模块的分通道日志能力,支持以下子通道 apps/memos-local-plugin/core/logger/README.md:

边缘场景处理:

• 磁盘满 / 权限拒绝:文件传输降级为仅控制台输出,并向内存环形缓冲区发出单条错误(同时通过 SSE 上报)。
• 进程异常终止:每个传输在 beforeExit 与 SIGINT / SIGTERM 上 flushSync()。
• 审计日志:默认永不删除,需要归档时可手动将 logs/ 下的 gzip 压缩文件移出。
• 密钥脱敏:基于规则的尽力而为机制,可通过 logging.redact.extraKeys / extraPatterns 自定义规则。

常见问题与故障排查

1. CJK 检索召回不足

社区 #1961 指出,FTS5 内置分词器对中文 2 字词(如 "早报"、"你好"、"配置")无法匹配,因为 trigram 窗口要求最小 3 字符。同时,混合 ASCII+CJK 的 token(如 "C盘"、"API")也会失败。memos-local-plugin 的检索模块在 core/retrieval 中引入了 pattern 通道,通过 LIKE %term% 模式匹配 CJK bigram 与 2 字符 ASCII,以弥补 FTS5 窗口的盲区 apps/memos-local-plugin/core/retrieval/README.md。vec 通道使用 vec_summary / vec_action 余弦相似度,fts 通道使用 FTS5 trigram MATCH,pattern 与 structural (错误签名回放) 通道互补,共同形成 RRF 融合打分。

2. 多 Agent 记忆隔离泄漏

社区 #1361 与 #1318 报告了 memory_search 工具的 patternSearch 分支在多 Agent 协作场景中缺少 ownerFilter,可能导致跨 Agent 信息泄露。修复方向是为 pattern 分支强制注入 owner 字段过滤,见 Release v2.0.13 的 fix(memos-local): scope sharing state by hubInstanceId 变更。

3. Windows 安装路径错误

Release v2.0.11 中 fix: fix windows dir error 修复了路径处理问题;v2.0.17 进一步增强了 Windows 安装体验 apps/memos-local-plugin/package.json。如再次出现路径相关错误,建议先清理 node_modules 后重新运行 postinstall。

4. LLM Provider 配置

core/llm 模块提供 5 个真实 provider 与 2 个哨兵 provider apps/memos-local-plugin/core/llm/README.md:

• openai_compatible (原生 JSON + SSE,适用于 OpenAI、Azure、智谱、SiliconFlow、百炼)
• anthropic (Messages API,基于提示的 JSON)
• gemini (原生 JSON + SSE)
• bedrock (Converse API,签名 v4 由调用方处理)
• host (委派给宿主 Agent)
• local_only (始终抛出 LLM_UNAVAILABLE)

社区 #1231 提议为 memos-local-openclaw 增加原生 ollama provider 支持,目前可通过 openai_compatible 接入 Ollama 兼容端点。

5. 失败任务被误记为"成功经验"

Release v2.0.19 中的 fix: The failed task was wrongly recorded as a "successful experience" 修复了奖励回写阶段的判定错误。涉及的代码路径位于 core/reward/backprop.ts,可结合 L1 轨迹的 value 字段(始终从 0 起始、仅由 backprop 修改)进行校验 apps/memos-local-plugin/core/memory/l1/README.md。

6. 技能生命周期异常

技能 applyFeedback 是单一状态转换入口,使用 Beta 后验更新 η,并根据 trial.pass / trial.fail / user.positive / user.negative / reward.updated 等信号切换状态 apps/memos-local-plugin/core/skill/README.md。若技能长时间停留在 probationary,可检查 eta 是否超过阈值,或查阅 SkillEventBus 的事件流。

7. Cloud 插件配置丢失

MemOS-Cloud-OpenClaw-Plugin 的配置页面会保留 schema 之外的自定义键到"额外 JSON 字段",以避免未来字段在保存时丢失 apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js。若发现配置项被覆盖,应先在页面中检查"额外 JSON"区域,再行保存。

See Also

• memos-local-plugin/core/retrieval/README.md: 多层级召回与通道融合
• memos-local-plugin/core/capture/README.md: 反射与轨迹提取阶段
• memos-local-plugin/core/llm/README.md: LLM Provider 配置
• examples/README.md: 各模块示例索引
• 社区问题: #1961 FTS5 CJK 分词、#1361 多 Agent 隔离、#1231 Ollama 支持、#1318 owner 默认值

Pitfall Log / 踩坑日志

项目：MemTensor/MemOS

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：fix:。

1. 安装坑 · 来源证据：fix:

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix:
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/MemTensor/MemOS/issues/1950 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/MemTensor/MemOS | host_targets=claude, chatgpt, openclaw

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/MemTensor/MemOS | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/MemTensor/MemOS | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/MemTensor/MemOS | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/MemTensor/MemOS | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：feat: support configurable FTS5 tokenizer for better CJK search

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: support configurable FTS5 tokenizer for better CJK search
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/MemTensor/MemOS/issues/1961 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/MemTensor/MemOS | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/MemTensor/MemOS | release_recency=unknown