MOS

MOS（MJS Agent Ops System）是一个面向 agent 的本地记忆与操作规范框架。它的目标不是把所有历史塞进上下文，而是让 agent 通过短规则、skill、memory、tools、eval 的方式，按需恢复状态、联想经验、执行流程、写回长期结论。

当前重点版本是 mos_v3/。

1. 新用户怎么用 MOS v3

1.1 先看三个入口

新用户第一次使用时，按顺序阅读：

1. mos_v3/mos_core/mos_always_rules.md
   短常驻规则，适合放到 Codex、Claude Code、Cursor、Windsurf、Gemini CLI 等 agent 的全局或项目规则里。

2. mos_v3/mos_core/ARCHITECTURE_AND_FLOW.md
   中文总说明，解释 MOS v3 架构、目录、流程、触发方式、人类最小用法。

3. mos_v3/mos_core/README.md
mos_core 的具体目录和命令入口说明。

1.2 最小启动流程

进入 MOS v3 核心目录：

cd mos_v3\mos_core

查看当前状态：

py -3 tools\mos_cli.py status

查看可用 skill：

py -3 tools\mos_cli.py skill-list

根据任务关键词生成启动包：

py -3 tools\mos_cli.py bootstrap "你的任务关键词"

查找相关历史经验：

py -3 tools\mos_cli.py associate "你的任务关键词"

如果要在 Git 仓库中修改文件，先做预检：

py -3 tools\mos_cli.py git-preflight --repo <你的仓库路径>

1.3 给 agent 使用

推荐方式：

1. 把 mos_v3/mos_core/mos_always_rules.md 放进 agent 的常驻规则。
2. 不要把整个 mos_v3 全文塞进提示词。
3. 让 agent 根据触发场景按需读取：
   • 新会话恢复：读 active_task.md、最近 task_log.md，运行 bootstrap。
   • 需要历史经验：运行 associate。
   • 需要写长期记忆：读 memory_upsert_policy.md。
   • 需要 Git 操作：读 agent_git_collaboration_policy.md。
   • 需要提示词优化：读 skills/prompt_optimization/SKILL.md。

这样可以减少上下文占用，只常驻最重要规则，其他 memory 随时联想和取用。

2. MOS v3 架构

MOS v3 使用四层结构：

Skill + Memory + Tools + Eval

• Skill：可复用流程，位于 mos_v3/mos_core/skills/。
• Memory：长期结论、当前任务、handoff、source refs。
• Tools：本地一次性 CLI 工具，位于 mos_v3/mos_core/tools/。
• Eval：检查记忆系统是否有效，位于 mos_v3/mos_core/eval/。

核心原则：

• 常驻规则要短。
• 长期记忆不全文常驻。
• 搜索和索引只是导航。
• 关键结论必须回源验证。
• 新经验要写成 memory card 或候选卡片。
• 稳定重复流程要升级成 skill 或工具。

3. 常用命令

cd mos_v3\mos_core

py -3 tools\mos_cli.py status
py -3 tools\mos_cli.py skill-list
py -3 tools\mos_cli.py bootstrap "任务关键词"
py -3 tools\mos_cli.py associate "任务关键词"
py -3 tools\mos_cli.py search "关键词" --top-k 8
py -3 tools\mos_cli.py rebuild
py -3 tools\mos_cli.py graph
py -3 tools\mos_cli.py eval-memory
py -3 tools\mos_cli.py git-preflight --repo <repo>

4. 如何写入长期记忆

不要直接把聊天内容复制进 memory。

推荐流程：

1. 先检索已有记忆，确认是否已有类似结论。
2. 优先更新已有 memory card。
3. 没有合适卡片时，创建候选卡片。
4. 写入后重建索引。
5. 关键结论必须带证据等级和回源入口。

相关入口：

• mos_v3/mos_core/memory_upsert_policy.md
• mos_v3/mos_core/memory_cards/TEMPLATE.md
• mos_v3/mos_core/tools/upsert_memory_card.py

5. 安全规则

不要把以下内容写入 MOS：

• 密码；
• token；
• API key；
• 私钥；
• 私有端点；
• 账号专属路径；
• 未去敏的原始日志；
• 任何凭据或隐私数据。

如果任务必须使用凭据，只能运行时从原始凭据源读取，不写入 memory、索引、日志或 agent 配置。

6. 版本归档

本仓库也保留早期版本归档：

• mjs_agent_ops_system_v0.rar：MOS v0 原始压缩包。
• mjs_agent_ops_system_v1_codex.rar：MOS v1 Codex 版本压缩包。
• mos_v2.rar：MOS v2 压缩包。

版本说明：

• version_notes/MOS_v0.md
• version_notes/MOS_v1.md
• version_notes/MOS_v2.md

历史 release 分支和 tag：

• release/v0 / v0
• release/v1 / v1
• release/v2 / v2

7. 维护原则

1. 修改文件前先检查 Git 状态。
2. 提交前运行 git-preflight。
3. 提交信息默认中文，说明背景、改动、验证、影响。
4. 不提交生成索引、缓存、日志、凭据。
5. 对 MOS v3 的规则、skill、tools、eval 改动，应同步更新文档和必要 memory card。