概览 — Mopheus Docs

Mopheus 跨工单记忆系统的设计理念、Server/Daemon/Runtime 三层架构全景、7 大记忆类型与 OKF 支柱目录映射。

在复杂软件工程与运维协作中，智能体不应当是一次性执行后就遗忘上下文的“失忆者”。Mopheus 构建了一套集中存储、确定性下发、只读投影与持续闭环的跨工单长期记忆体系。

当智能体在某张工单中定位了疑难报错、排查了工具不兼容问题、形成了经过验证的多步骤 SOP、或接受了人类专家的纠偏指导，这些经验会被沉淀为结构化记忆卡片。当新的相关任务被创建或认领时，系统会基于精准的作用域匹配与检索算法，在智能体工作区自动构建上下文记忆，让团队知识资产持续复利。

┌───────────────────────────────────────────────────────────────┐
│                      Mopheus 记忆生命周期                     │
├───────────────────────────────────────────────────────────────┤
│                                                               │
│   工单完成 / 运行时捕获                                       │
│          │                                                    │
│          ▼                                                    │
│   记忆蒸馏 (Distillation) ──► 认知晋升 (Resolution→Playbook)  │
│          │                                                    │
│          ▼                                                    │
│   集中存储 (PostgreSQL)  ──► 单一可信源 / 显式取代版本链      │
│          │                                                    │
│          ▼                                                    │
│   任务下发 (Delivery)    ──► ETag协商 / 节点缓存 / 沙箱投影   │
│          │                                                    │
│          ▼                                                    │
│   沙箱就绪 (Runtime)     ──► MEMORY.md 初筛 / 相对链接通读    │
│                                                               │
└───────────────────────────────────────────────────────────────┘

核心设计理念

集中存储作为单一可信源（Single Source of Truth）
所有记忆持久化数据集中存储在服务端 PostgreSQL 数据库中。智能体所在的宿主机沙箱、容器均为可销毁的瞬态环境，严禁将沙箱本地文件当作无主持久化源。记忆的所有增删改均通过 API 与 CLI 严格受控执行。
确定性按需下发与精准防污染
系统绝不盲目、无脑地将全部记忆倾倒至每个任务中。下发时严格区分工作区通用底座与特定实体作用域（如目标资产 asset_id、技术栈 db_type、发起人 user_id）。专属资产的规格仅定向投递至该资产相关的任务，杜绝跨资产串扰与 Token 浪费。
宿主只读投影与沙箱强隔离
在 Daemon 运行时，记忆卡片通过宿主机工作区共享只读缓存池（Cache Pool）进行分发。Linux 环境下通过 Bubblewrap --ro-bind 只读挂载，非 Linux 环境下通过相对符号链接投影。沙箱内对卡片文件的本地修改绝不会写回缓存池，确保知识库的完整性与安全性。
主动维护与认知晋升（Cognitive Promotion）
记忆不是杂乱的日志堆积。系统鼓励智能体将偶发的错误排障（resolution）提炼为可复用的标准作业程序（procedure），并将通用的架构实践升华为团队偏好（preference），通过 --supersedes 显式淘汰过期旧知。

三层架构全景

Mopheus 记忆系统贯穿管控层、节点传输层与任务沙箱层：

[管控与存储层: Server & PostgreSQL]
  │ • 集中数据表: memory, memory_source, memory_distillation
  │ • 检索引擎: 多维作用域过滤 + 原生加权全文检索 (content_tsv GIN 索引) + pg_trgm 相似度
  │ • ETag 计算与任务级 MEMORY.md 动态构建
  ▼
[传输与缓存层: Mopheus Daemon]
  │ • 工作区共享 Cache Pool (带 .lock 并发控制与原子写入)
  │ • ETag 304 增量协商，避免卡片重复传输
  ▼
[执行与沙箱层: Agent Runtime Sandbox]
  │ • 安全投影: Bubblewrap --ro-bind 或符号链接挂载到 .claude/memory/
  │ • 任务私有索引: .claude/memory/MEMORY.md (任务级定制，不污染共享池)
  │ • 交互契约: 读 MEMORY.md 初筛 -> 读目标卡片全文 -> 用 CLI 存储新知

7 大记忆类型

系统将工程实践中的知识严格抽象为 7 大记忆类型，每种类型对应明确的语义与生命周期定位：

记忆类型 (Legacy ID)	通用别名 (Generic Name)	核心语义与定位	典型场景
`error_resolution`	`resolution`	针对特定报错、异常或失败的诊断路径与确切修复方案。	"PostgreSQL unique constraint violation: HandleDBError loses error details"
`failure_scenario`	`risk`	必须警惕的系统缺陷、工具不兼容、崩溃、OOM 或运维陷阱。严禁归入 fact。	"save-images.sh 与 Docker 29 containerd image store 不兼容"
`success_playbook`	`procedure`	经过端到端验证的多步骤标准作业程序（SOP），以结构化 JSON 存储。	"PostgreSQL 15 升级至 17 跨版本迁移与 JSON 表达式验证 Playbook"
`environment_fact`	`fact`	目标系统或基础设施的持久静态规格（版本、硬件拓扑、挂载点、连接配置）。	`/src 与 /home/moclaw-dev/repos 为只读挂载`
`human_correction`	`correction`	人类专家在工单交互中纠正智能体思路与操作的记录。排序享最高置信度加权。	"Mopheus 仓库解析规则：monorepo 与落地页分仓解析规则"
`preference`	`preference`	团队或个人明确声明的架构标准、代码规范、操作限制或工作流偏好。	"API 错误码必须使用 errx 定义，严禁抛出裸 403 字符串"
`reference_doc`	`reference` / `docs`	项目级核心参考手册、接口协议、架构规范或白皮书文档。	"Mopheus 项目开发规范与模块关系参考手册"

环境事实与偏好的作用域分级

Mopheus 的环境事实与偏好采用严格的作用域分级机制。环境事实与资产（asset_id）深度挂钩，并不会全量注入到所有任务中，而是按资产绑定关系确定性分发：

通用环境事实 vs 资产专属事实：
- 工作区通用环境事实（未绑定 asset_id）：描述全局基础设施规范（如宿主机全局挂载拓扑、通用网络环境），作为 L0 全局底座注入到工作区所有任务中。
- 资产专属环境事实（绑定具体 asset_id）：描述特定资产的硬件容量、实例参数、独有端口或内核特性。此类事实严格与目标资产绑定，绝不进入全局底座；仅当任务或工单显式关联该 asset_id 时，才会在 L2 候选集中按需精准下发，杜绝跨资产配置混淆。
团队全局规约 vs 个人偏好：
- 团队全局规约（未绑定 user_id）：适用于整个工作区的统一工程标准与代码规范，作为全局基线生效。
- 个人偏好（绑定具体 user_id）：仅当该用户发起任务（origin_user_id）时定向激活，支持个性化工作流，同时保证不干扰其他团队成员。

记忆类型与 OKF 四大支柱目录拓扑

在沙箱投影以及离线导出（mop memory export）时，7 大记忆类型遵循 Open Knowledge Format (OKF) 规范，精准映射到四大支柱（Four Pillars）目录：

.claude/memory/
├── MEMORY.md                      # 任务专属导航索引表
├── runbooks/                      # Pillar 1: 实操演练与运维手册
│   ├── errors/<id>.md             # ├── resolution (error_resolution)
│   ├── pitfalls/<id>.md           # ├── risk (failure_scenario)
│   └── playbooks/<id>.md          # └── procedure (success_playbook)
├── facts/                         # Pillar 2: 静态环境与配置规格
│   └── specs/<id>.md              # └── fact (environment_fact)
├── conventions/                   # Pillar 3: 规约与纠偏准则
│   ├── corrections/<id>.md        # ├── correction (human_correction)
│   └── preferences/<id>.md        # └── preference (preference)
└── docs/                          # Pillar 4: 参考文档与权威手册
    └── <id>.md                    # └── reference / docs (reference_doc)

启用与功能开关

跨工单记忆功能受工作区功能标志（Feature Flag）保护：

工作区管理员进入 管理面板 → 功能（Features）。
将 记忆（memory） 功能开关置为 启用（Enabled）（或设置为 选定（Selected） 并配置允许的工作区白名单）。
启用后，该工作区将自动开启任务启动时的记忆注入、工单完成后的蒸馏触发、以及 Web/CLI 维度的记忆管理能力。

概览

核心设计理念Copy Anchor Link

三层架构全景Copy Anchor Link

7 大记忆类型Copy Anchor Link

环境事实与偏好的作用域分级Copy Anchor Link

记忆类型与 OKF 四大支柱目录拓扑Copy Anchor Link