Mitos

Mitos

🔧 早期版本 — 正在积极开发

当你和 AI 助手一起开发软件数月后，你的决策背后的推理过程会逐渐丢失。助手会忘记你为什么选择某种方案，重新推荐你已经否决的选项，而你的设计笔记也会与实际做出的决定脱节。Mitos 是专门用于记录这些决策的记忆层：它会记录每项决策、你排除的备选方案，以及后续决策如何取代早期决策，然后以精简、可信的形式将这些历史提供给你的 AI 助手。

结果是：你的 AI 协作者会始终遵循你实际做出的决定——不再与过去的决定相矛盾，也不会重新提出已经解决的问题；你的决策记录也不会悄然过时。

其底层实现是：供人阅读的 Markdown（decisions.md 及其位于 decisions/archive/ 下的季度归档是始终可供你阅读和搜索的事实来源）、供 Agent 使用的类型化图谱（SQLite + 本地 Qdrant，用于语义回忆），以及一个 MCP 服务，让 Agent 在做决定前检查先例，并在做决定时记录下来。

可在 PyPI 和 MCP Registry 上获取。

---

最快的安装方式：交给你的 Agent

如果你使用 AI 编码 Agent（Claude Code、Cursor、Gemini CLI 等），最简单的方法就是让它完成设置。在你希望使用 mitos 的项目中，向 Agent 提供：

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.

Agent 最终会执行的操作——与人类遵循的步骤相同，全部列在 SETUP.md 中，你可以先阅读：

• 通过 pipx 安装 mitos CLI（从 PyPI 或此仓库安装）；
• 启动本地 Qdrant 容器（使用 qdrant/qdrant，监听端口 7333，与已有的任何 Qdrant 实例隔离）；
• 如果整台机器尚未注册该 MCP 服务，则注册一次；
• 初始化项目工作区，同时按名称注册项目；
• 请你自行设置 API 密钥（mitos set-key）——Gemini 密钥（必需），以及用于冲突审计层的 Anthropic 密钥（强烈建议）；设置指南会告知 Agent 不要处理密钥值。

Agent 在整个过程中会询问多少内容，由你自己的 Agent 设置决定，而不是由此提示词决定。

手动设置

手动完成相同步骤——完整详情请参阅 SETUP.md：

1. 安装（每台机器只需一次）：pipx install mitos-adr
2. 启动 Qdrant（每台机器只需一次，由所有项目共享）：在此仓库中运行 docker compose up -d——mitos 会在 :7333 上运行自己的实例，因此绝不会触碰你用于其他工作的 Qdrant。
3. 注册 MCP 服务（每台机器只需一次，建议为 Agent 注册）：claude mcp add --scope user mitos -- mitos serve。一次注册即可服务所有项目——关于所需资源、其他运行环境，以及为什么必须移除遗留的项目级 .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 .（Agent 将相同内容作为 project 参数传入）。mitos projects 会列出已注册项目，mitos unregister <name> 会移除注册信息（工作区保持原样）。这样，一次安装和一个 MCP 服务就能服务这台机器上的所有项目，同时确保调用绝不会落入错误的语料库。

运行方式

Mitos 按项目运行——每个项目都有自己的决策图和 Qdrant 集合。日常使用中，三个动词构成了工作循环（作为 MCP 工具供 Agent 使用，也有对应的 CLI 命令）：

动词	使用时机
surface_decisions（mitos surface）	做决定之前——是否有先例？每条匹配结果都会附带已被否决的备选方案及其原因。
record_decision（mitos record）	某件事尘埃落定时——记录决定、被否决的路径，以及它与先前决定的关系（取代、修订等）。
query_decisions（mitos query）	按含义查找内容（MCP 工具还支持按确切标识符查找），或仅搜索被否决的选项。

以下几点值得了解：

• Markdown 是事实来源。 每项决定都会写入 decisions.md，轮换时会将已提交的条目移入 decisions/archive/；这两个文件都便于人工阅读和 grep。决策图和搜索索引均由它们生成，且始终可以据此重建（mitos rebuild）。
• 决定的公理绝不会被编辑，而是由后续决定取代。 公理及其机制只会通过后续决定进行取代、更正或修订；其状态（active / superseded / amended）根据这些类型化关系计算，因此关于原因的历史始终得以保留。可通过 mitos amend-commentary 原位修正评论内容（被否决的路径、上下文、范围）。
• 它会安全降级。 如果搜索索引或嵌入 API 不可用，记录功能仍然有效，搜索会降级为对 Markdown 进行如实的文本匹配——不会阻塞，也不会丢失内容，而且降级输出会明确说明已降级。
• 它会自我审计。 语料库扫描（mitos check -p .）会找出彼此存在隐性矛盾的决定。提交门禁（mitos hook-install -p .）会在 git commit 时运行，并阻止已记录决定后发起的提交，直到尝试完成检查；--staged 则会检查仍待写入 decisions.md 的手动编写条目——关于提交门禁、暂存门禁，以及 CI 和 cron 配置示例，请参阅 SETUP.md。

运行 mitos --help 探索其余功能——帮助文本也可用作 API 参考。

存在的意义

通过密集的大模型设计评审来构建软件，会产生大量架构决策，速度快到人无法及时跟踪。一个月采用这种工作方式，就在单个 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 对离线测试套件来说是安全的，但不适用于实时测试层：测试收集扫描是会话级的，因此并行工作进程会删除彼此的 Qdrant 集合，受影响的测试会降级为跳过，而不是失败。

*_live.py 测试套件和黄金 Layer B 会使用你自己的密钥，真实调用 Gemini 和 Anthropic API，并且需要在 :7333 运行 Qdrant。如果无法解析密钥，它们就会跳过，因此新克隆的仓库默认运行快速路径。

密钥会从环境变量、仓库根目录下的 .env 或 ~/.config/mitos/.env 中解析——因此，如果你已经在使用 mitos，运行测试时可能会用到你的个人密钥并产生费用。请明确选择退出：

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

规范的决策格式位于 mitos/format-spec.md。许可证：Apache 2.0。