Mitos

🔧 早期发布 —— 持续开发中

当你与 AI 助手构建软件数月或更久时，决策背后的思考过程会丢失。助手会忘记你为什么选择某种方案，重新提出你已经淘汰的选项，而你的设计笔记会逐渐和实际拍板的决策脱节。Mitos 就是这些决策的记忆层：它记录每一条决策、你排除过的备选方案，以及后续决策如何取代早先的决策——然后再以紧凑、可信的形式把这段历史反馈给你的 AI 助手。

结果是：你的 AI 协作者始终与你真正做过的判断保持一致——它不会与过去的决策相矛盾，也不会重新翻开已定论的问题，同时你的决策记录永远不会悄悄烂掉。

技术内部是这样的：markdown 供人类阅读（decisions.md 是你随时可以阅读和 grep 的事实来源），一套类型化图供智能体使用（SQLite + 本地 Qdrant 做语义召回），以及一个 MCP 服务器，让智能体在做决定前先查先例，并在做出决定时记录决策。

你可以在 PyPI 和 MCP Registry 上获取它。

最快安装：把它交给你的智能体

如果你在使用 AI 编程智能体（例如 Claude Code、Cursor、Gemini CLI……），最快捷的路径是让智能体替你完成全部安装。在你想要使用 mitos 的项目中，把你的智能体需要做的步骤交给它：

Read https://github.com/dovahkiin-v/mitos/blob/main/SETUP.md and set up mitos
for this project. When done, run `mitos status .` from the project directory
and report the result.

你的智能体最终会做的事情——与人类手动执行的步骤完全相同——全部写在 SETUP.md 中，你可以随时先读一遍：

• 通过 pipx 安装 mitos CLI（可以从 PyPI 或这个仓库安装）；

• 启动一个本地 Qdrant 容器（使用 qdrant/qdrant，监听 7333 端口，与你已有的其他 Qdrant 实例完全隔离）；

• 注册 MCP 服务器，每台机器只需注册一次（如果尚未注册的话）；

• 初始化项目工作区，同时把项目按名称注册；

• 让你自己手动设置 API 密钥（mitos set-key）——一个 Gemini 密钥（必须），以及一个 Anthropic 密钥，用于冲突审计层（强烈推荐）；安装指南约定智能体不要接触密钥本身的取值。

智能体在这一过程中会向你询问多少问题，由你自己智能体的配置所决定，而不是由这个提示词决定。

Related MCP server: mcp-adr

手动安装

手工逐步完成同样的操作——完整细节见 SETUP.md：

1. 安装（每台机器一次）：pipx install mitos-adr

2. 启动 Qdrant（每台机器一次，所有项目共享）：在本仓库中执行 docker compose up -d —— mitos 会运行自己的实例，监听 :7333，因此你从未与你为其他工作使用的任何 Qdrant 实例产生冲突。

3. 注册 MCP 服务器（本地端口每次，推荐给智能体）：执行 claude mcp add --scope user mitos -- mitos serve。一次注册即可服务所有项目 —— 关于它有什么代价、对其他 harness 怎么说，以及为什么需要移除项目里遗留的 .mcp.json 条目，参见 SETUP.md。

4. 每个项目：在项目根目录执行 mitos init，然后执行 mitos set-key --global <your-Gemini-key>（一个密钥覆盖所有东西；去 https://aistudio.google.com/app/apikey 获取）。目前 Gemini 是经过测试的嵌入提供方；多提供方抽象已经被列入路线图。

5. 验证：执行 mitos status . → 显示 READY ✓。

整个过程中 mitos status . 就是你的指南针：它精确告诉你什么已完成、什么缺失、以及这个项目下一步该做什么。当不指定项目名时，mitos status 回答的是另一个问题——这台机器上已经有什么——列出每一个已注册的项目并检查 Qdrant。

每条命令都必须指定它的项目。 不存在默认目标：mitos init 注册出项目名，从那时起每个动词都通过 -p <name>、-p <absolute path> 或 -p .（在项目根目录内）来指向项目（智能体在调用时也用同样的 project 参数）。mitos projects 列出所有已注册的项目。正是这样，一次安装和一个 MCP 服务器就能服务这台机器上的所有项目程序，却不会让任何一次调用落入错误的语料库。

它是怎么运行的

Mitos 是按项目隔离的 —— 每个项目拥有自己的决策图和自己的 Qdrant 集合。日常使用中，三个动词构成整个回路（对智能体来说是 MCP 工具，同时有完全相同的 CLI 孪生命令）：

几个值得知道的特性：

• Markdown 是唯一事实源头。每一条决策都会落到 decisions.md，可供人类阅读和 grep；决策图和搜索索引都是从这个文件派生出来的，可以随时重建（使用 mitos rebuild）。

• 决策永不修改、删除——只会被取代。状态（active / superseded / amended）是根据决策间的类型化关系计算出来的，因此为什么会这样的历史永远留存。

• 安全降级。如果搜索索引或 embedding API 不可用，记录仍然可以正常工作，搜索会退回为对 markdown 的诚实文本匹配；不会阻塞任何操作、不会丢失任何数据，降级的输出也会明确告诉你它处于降级状态。

• 自我审计。语料库扫描（mitos check -p .）能发现彼此静默冲突的决策，而 --staged 可以把新条目作为 pre-commit 或 CI 的一个门槛 —— 关于 pre-commit hook、CI 和 cron 方案，均见 SETUP.md，这些方案会以三种不同的方式指定项目名称。

尝试 mitos --help 可以探索其余内容——帮助文本同时就是 API 参考。

它为什么存在

通过 AI 设计评审来构建软件，产生架构决策的速度快于一个人能跟踪的速度。仅一个月的工作方式就在一个 markdown 文件里产生了近 900 条决策记录——我们的方法已经退化成人工不可读、不可 grep、不可维护。现有的 ADR 工具是为偶尔记录一条决策的人类团队而设计的；而 mitos 是为那种 AI 助手持续生成、消费决策的独行开发者打造的。

如果你的工作方式恰好是这样，项目大小其实并不太重要——决策量越大，mitos 就越快由“可选”变成“必需”。

开发

pip install -e '.[test]'
MITOS_NO_LIVE_TESTS=1 pytest -m "not packaging" -n auto   # offline suite, parallel (~50s)
pytest -m "not packaging"                                 # adds the live tier — serial only
pytest -m packaging                                       # real-install check: fresh venv + pip install

-n auto 对离线测试套件是安全的，但不适合线上（live）层：测试集合的扫描是会话作用域的，因此并行 worker 会删除彼此的 Qdrant 集合，相关测试会退化为 skip（跳过）而不是失败。

*_live.py 测试套件和 golden Layer B 会真实地使用你自己 key 发起 Gemini 和 Anthropic API 调用，并且依赖 :7333 上的 Qdrant。当找不到可用的 key 时它们自动跳过，所以全新克隆默认走快速路径。

密钥可以从环境变量、仓库根的 .env 或 ~/.config/mitos/.env 中解析 —— 因此如果你已经在使用 mitos，一次测试运行可能会读取你个人的 key 并消耗你的配额。请显式退出：

MITOS_NO_LIVE_TESTS=1 PYTHONPATH=. pytest -m "not packaging"

标准的决策格式定义在 mitos/format-spec.md。许可证：Apache 2.0。