存储规范

Mopheus 记忆系统的底层存储由服务端关系型数据库统一纳管，而在面向人类阅读、沙箱内展示与跨系统流转时，统一采用 Open Knowledge Format (OKF) 格式进行序列化。

本文详细介绍 OKF 的文件规范、存储架构、版本取代链以及离线运维命令。

集中式存储架构Copy Anchor Link

在 Mopheus 中，数据库是记忆数据的唯一持久化可信源（Single Source of Truth）。

              ┌─────────────────────────────────────┐
              │      PostgreSQL 集中存储数据库      │
              │                                     │
              │  • memory (主表，含 content_tsv)    │
              │  • memory_source (工单关联来源表)   │
              │  • memory_distillation (蒸馏审计表) │
              └──────────────────┬──────────────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 │                               │
        读请求 (Pull/Recall)            写请求 (Store/Update)
                 │                               │
                 ▼                               ▼
      ┌──────────────────────┐        ┌──────────────────────┐
      │  Daemon / 沙箱投影   │        │     Mopheus CLI      │
      │  (.claude/memory/)   │        │   (mop memory ...)   │
      │  *纯只读消费沙盘*    │        │ *唯一受控写入途径*   │
      └──────────────────────┘        └──────────────────────┘

数据库主表结构与索引Copy Anchor Link

• memory 表：
  • id (UUID): 记忆卡片唯一主键。
  • workspace_id (UUID): 工作区隔离主键，严格保证租户数据隔离。
  • memory_type (INT): 记忆分类枚举（0~6），对应 OKF 7 大类型。
  • title (VARCHAR 100): 单行精炼标题，作为快速初筛依据。
  • content (TEXT): 核心记忆正文。
  • context_tags (JSONB): 上下文元数据标签，建立 GIN 包含索引（@>），支持按技术栈、资产、环境高效过滤。
  • occurrence_count (INT): 累计被不同工单确认有效的次数。
  • recall_hit_count (BIGINT): 被智能体任务检索命中的累计次数。
  • content_tsv (TSVECTOR): 由触发器自动预计算的标题（A 权）+ 正文（B 权）全文向量，挂载 GIN 倒排索引，驱动毫秒级多语言全文检索。
  • superseded_by (UUID): 指向取代该卡片的新记忆 ID。被取代的记录自动停止在活跃检索中下发。
  • enabled (BOOL): 逻辑可用开关。
• memory_source 表：
  • memory_id (UUID): 关联的记忆 ID。
  • ticket_id (UUID): 产出或确认该记忆的来源工单 ID，建立多对多溯源追踪。
• memory_distillation 表：
  • 记录工单维度的蒸馏生命周期和审计数据（ticket_id, workspace_id, db_type, distilled_at, distilled_by, skipped_reason）。历史列 memory_count 已弃用，不再维护或通过接口返回；当前关联记忆数请查询工单记忆列表。
• 反面原则（Anti-pattern）：
  • 沙箱本地文件非持久源：智能体任务运行时生成的容器或工作目录属于瞬态临时文件。如果在沙箱内直接用编辑器写入或修改 .claude/memory/ 下的文件，任务结束后这些修改不会自动同步回数据库，将随沙箱销毁而丢失。
  • 唯一受控写入通道：所有记忆的新建、编辑、停用与淘汰，必须通过 mop memory store 或 mop memory update CLI 命令提交。

OKF (Open Knowledge Format) 规范Copy Anchor Link

OKF (Open Knowledge Format) 是 Google 提出的面向 AI 智能体与人类工程师的开放知识卡片标准，采用 YAML Frontmatter + Markdown Body 的统一形态。Mopheus 记忆系统全面遵循并实现了该规范。

1. YAML Frontmatter 元数据定义Copy Anchor Link

每张卡片顶部必须包含严格的 YAML Frontmatter 区块：

---
id: c971377d-839b-43e8-bf11-4ff24de977ce
type: failure_scenario
title: "save-images.sh 与 Docker 29 (containerd image store) 不兼容，需单独修复"
occurrence: 1
last_seen_at: 2026-10-10T14:19:07Z
superseded_by: null
component: install-script
description: "Docker 29 开启 containerd image store 时 save-images.sh 导出失败"
labels:
  - docker
  - release
repo: mopheus
scope: known-defect
---

关键字段释义：Copy Anchor Link

• id：卡片全局唯一 UUID。
• type：记忆类型标识符，支持标准类型（如 error_resolution, failure_scenario）或通用别名（如 resolution, risk）。
• title：不超过 100 字符的一行概述。禁止使用空洞标题（如“报错修复”），必须是具备充分信息密度的断言。
• occurrence：置信度/确认次数，默认为 1。每次被新工单复核确认时自动递增。
• last_seen_at：最近一次被工单触发或确认的 UTC ISO 8601 时间戳。
• superseded_by：若该卡片已被新记忆取代，此处记录新卡片的 UUID；若未被取代则为 null。
• 顶层扩展元数据（<custom_keys>）：数据库 context_tags 中的所有键值（如 description、labels、asset_id、db_type、error_code 及自定义键值）在导出与下发时按字典序展开为标准 YAML Frontmatter 顶层字段；导入时除 6 个系统保留字段外的所有顶层 YAML 键值（并向后兼容旧版 context_tags 字段）会自动收敛回 context_tags JSONB。

2. Markdown 正文规范Copy Anchor Link

OKF 卡片根据类型分为两类正文格式要求：

普通文本正文（resolution, risk, fact, correction, preference, reference）Copy Anchor Link

采用 GitHub Flavored Markdown 撰写，要求结构清晰、上下文完整，包含根本原因、现象描述与修复步骤：

2026-10-10 v2.2.10 发布时实测确认：install/scripts/save-images.sh 在 Docker 29.6.0（containerd image store）下必定失败。

## 失败链路
1. Docker 29 已把 --platform 从 `docker inspect` 移到 `docker image inspect`，导致 image_id 为空。
2. 回退到 save_ref 时，`docker save` 试图序列化整个 manifest list，本地缺少其它架构子镜像触发 NotFound。

## 修复方向
改用 `docker image inspect --platform` 取平台信息，并在 save 时使用 `docker image save --platform $DOCKER_PLATFORM $image`。

结构化 JSON 正文（procedure / success_playbook 专用）Copy Anchor Link

对于具备高度标准作业流程的 procedure 类型，其正文必须是自包含的结构化 JSON 对象，包含五大要素：

{
  "fault": "PostgreSQL 17 主机执行未显式类型转换的 JSON 路径查询时报类型不匹配错误",
  "preconditions": [
    "目标数据库为 PostgreSQL 17+",
    "表结构包含 jsonb 类型字段"
  ],
  "steps": [
    "定位报错 SQL 中涉及 jsonb 字段的表达式提取语句",
    "将 col->>'field' 格式替换为 (col->>'field')::target_type",
    "执行 EXPLAIN ANALYZE 确认执行计划未发生全表扫描"
  ],
  "validation": [
    "执行回归测试用例，确认 HTTP 200 响应正常",
    "检查 PostgreSQL pg_stat_activity 确认无死锁或长事务堆积"
  ],
  "rollback": "若业务逻辑异常，重新执行 ALTER TABLE 降级脚本或恢复备份视图定义"
}

回滚（rollback）规范：对于可逆操作，必须记录明确回滚命令；对于破坏性不可逆操作（如 DROP、TRUNCATE），必须显式声明 "This operation is not reversible."。

3. OKF 四大支柱（Four Pillars）目录规范Copy Anchor Link

在文件系统呈现时，记忆卡片必须严格按照其类型归入对应的四大支柱目录中：

1. runbooks/（实操演练与处置手册）：
   • runbooks/errors/<id>.md：存放 error_resolution（报错排查修复）。
   • runbooks/pitfalls/<id>.md：存放 failure_scenario（缺陷与避坑踩坑指南）。
   • runbooks/playbooks/<id>.md：存放 success_playbook（标准作业程序 SOP）。
2. facts/（静态环境规格）：
   • facts/specs/<id>.md：存放 environment_fact（环境持久静态配置与硬件规格）。
3. conventions/（架构规约与偏好）：
   • conventions/corrections/<id>.md：存放 human_correction（人工纠偏记录）。
   • conventions/preferences/<id>.md：存放 preference（团队与个人架构偏好）。
4. docs/（参考手册与设计文档）：
   • docs/<id>.md：存放 reference_doc（大型参考手册与长文规范）。

记忆生命周期与版本淘汰Copy Anchor Link

记忆不是永恒不变的静态文本，随着系统迭代，旧记忆会过期、出现冲突或被更优方案取代。

1. 相似度去重与计数累加（Dedup & Occurrence）Copy Anchor Link

当通过 CLI 录入或蒸馏产生新记忆时，系统会自动执行基于 pg_trgm 的文本相似度检测：

• 同类型且相似度超过阈值（procedure 阈值 0.28、preference 阈值 0.25、其他类型阈值 0.30）：
  • 系统不会插入重复记录，而是复用已有记录 ID。
  • 若来自新工单，occurrence_count 自动 +1，并刷新 last_seen_at 时间戳。
  • 多次在真实场景被触发和验证的记忆，其权重与可信度会逐步提升。

2. 显式版本取代链（Supersedes）Copy Anchor Link

当旧方案被废弃（如某个工具升级废弃了某参数，或旧的 Workaround 已被正式补丁替代），新卡片必须显式声明取代旧卡片：

mop memory store \
  --type risk \
  --title "save-images.sh Docker 29 修复方案" \
  --content "..." \
  --supersedes c971377d-839b-43e8-bf11-4ff24de977ce

• 后端行为：系统会将被取代旧卡片的 superseded_by 字段置为新卡片 ID，同时将其 enabled 设为 false。
• 回滚保障：如果新卡片未来被删除，被其取代的旧卡片会自动恢复为 enabled = true，确保知识回退链路安全可靠。

离线管理与 CLI 运维工具Copy Anchor Link

Mopheus CLI 提供了完备的离线导出、导入与静态校验工具链，便于将知识卡片纳入 Git 版本控制或在不同工作区之间迁移。

1. 全量导出为本地 OKF 结构Copy Anchor Link

将指定工作区内的全部记忆导出为标准的 OKF 四大支柱目录结构，并自动生成根目录 MEMORY.md 索引表：

mop memory export --dir ./workspace-memories

导出的目录结构可直接提交至 Git 仓库做版本化留存。

2. 静态目录校验（Lint / Validate）Copy Anchor Link

在将外部知识或人工编写的卡片导入系统之前，执行严格的静态合规检查：

mop memory validate --dir ./workspace-memories

校验规则包括：

• 文件必须位于合规的 4 大支柱子目录（runbooks/, facts/, conventions/, docs/）。
• 必须包含以 --- 完整开闭合的有效 YAML Frontmatter。
• type 必须属于合规的 7 种记忆类型（或通用别名）。
• content 正文内容不能为空。

3. 批量离线导入Copy Anchor Link

将经过验证的 OKF 目录结构批量同步导入到当前工作区中：

mop memory import --dir ./workspace-memories

• 导入会自动识别已有卡片并执行更新（若更新时间戳更新），或创建新卡片。
• 支持幂等执行，适合在 CI/CD 流水线中做预置知识库的初始化灌库。

文件扫描与过滤边界Copy Anchor Link

• 自动忽略非 Markdown 文件：导入器遍历目录时仅扫描扩展名为 .md 的文件，自动跳过目录中夹带的图片（PNG/JPG）、Office 文档（Word/Excel）、PDF、视频或压缩包等非 Markdown 文件；根目录的 MEMORY.md 索引文件也会被自动排除。
• 严格校验 Markdown 文件：目录内遍历到的所有 .md 文件均被视作待导入的记忆卡片，必须符合 OKF YAML Frontmatter 规范（包含完整的 --- 分隔符、有效的 type 类型以及非空正文）。若存在无 Frontmatter 的普通 Markdown 文件（如杂质 README.md），解析时会中断并报错 PARSE_FAILED。
• 安全预检建议：在执行批量导入前，强烈建议先运行 mop memory validate --dir <dir> 进行全量合规预检。