Mitos

Mitos

🔧 Early release — actively developed

When you build software with AI assistants over months, the *reasoning* behind your decisions gets lost. The assistant forgets why you chose one approach, re-suggests options you already rejected, and your design notes drift out of sync with what was actually decided. Mitos is a memory layer for those decisions: it records each decision, the alternatives you ruled out, and how later decisions replace earlier ones — then feeds that history back to your AI assistant in a compact, trustworthy form.

The result: your AI collaborator stays consistent with the calls you've actually made — it stops contradicting a past decision or re-opening a settled question, and your decision record never silently rots.

Under the hood: markdown for humans (decisions.md and its quarterly archives under decisions/archive/ are the source of truth you can always read and grep), a typed graph for the agents (SQLite + a local Qdrant for semantic recall), and an MCP server so agents check precedent before deciding and record decisions as they make them.

Available on PyPI and the MCP Registry.

---

Fastest install: hand it to your agent

If you work with an AI coding agent (Claude Code, Cursor, Gemini CLI, …), the easiest path is to let it do the setup. In the project you want mitos in, give your 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.

What your agent will end up doing — the same steps a human follows, all in SETUP.md where you can read them first:

• install the mitos CLI via pipx (from PyPI or this repository);
• start a local Qdrant container (qdrant/qdrant on port 7333, isolated from any Qdrant you already run);
• register the MCP server once for the whole machine, if it isn't registered already;
• initialize the project workspace, which also registers the project by name;
• ask you to set your API keys yourself (mitos set-key) — a Gemini key (required), and an Anthropic key for the conflict-audit layer (strongly recommended); the setup guide tells agents not to handle key values.

How much your agent asks along the way is governed by your own agent's settings, not by this prompt.

Manual setup

The same steps by hand — full detail in [SETUP.md](SETUP.md):

1. Install (once per machine): pipx install mitos-adr
2. Start Qdrant (once per machine, shared by all projects): docker compose up -d from this repo — mitos runs its own instance on :7333, so it never touches a Qdrant you use for other work.
3. Register the MCP server (once per machine, recommended for agents): claude mcp add --scope user mitos -- mitos serve. One registration serves every project — see SETUP.md for what it costs, for other harnesses, and for why a leftover per-project .mcp.json entry has to go.
4. Per project: mitos init from the project root, then mitos set-key --global (one key covers everything; get it at https://aistudio.google.com/app/apikey). Gemini is the tested embedding provider today; a multi-provider abstraction is on the roadmap.
5. Verify: mitos status . → READY ✓.

mitos status . is the compass throughout: it says exactly what's done, what's missing, and what to do next for that project. With no project named, mitos status answers the other question — what does this machine have — listing every registered project and checking Qdrant.

Every command names its project. There is no default target: mitos init registers the project by name, and from then on each verb takes -p , -p , or -p . from the project root (agents pass the same thing as a project argument). mitos projects lists what's registered, and mitos unregister removes a registration (the workspace stays as it is). That is what lets one install and one MCP server serve every project on the machine without a call ever landing in the wrong corpus.

How it runs

Mitos is per-project — each project gets its own decision graph and its own Qdrant collections. Day to day, three verbs carry the loop (as MCP tools for agents, with CLI twins):

A few properties worth knowing:

• The markdown is the source of truth. Every decision lands in decisions.md, and rotation moves committed entries into decisions/archive/; both are human-readable and greppable, and the graph and the search index are derived from them and can always be rebuilt from them (mitos rebuild).
• A decision's axiom is never edited — it's superseded. The axiom and its mechanisms change only through a later decision that supersedes, corrects or amends it, and state (active / superseded / amended) is computed from those typed relations, so the history of *why* always survives. Commentary (rejected paths, context, scope) can be fixed in place with mitos amend-commentary.
• It fails safe. If the search index or the embedding API is down, recording still works and search degrades to an honest text-match over the markdown — nothing blocks, nothing is lost, and degraded output says it's degraded.
• It audits itself. The corpus sweep (mitos check -p .) finds decisions that silently contradict each other. The commit gate (mitos hook-install -p .) runs on git commit and holds a commit made after decisions were recorded until a check has been attempted, and --staged checks hand-authored entries still pending in decisions.md — see SETUP.md for the commit gate, the staged gate, and the CI and cron recipes.

Explore the rest with mitos --help — the help text doubles as the API reference.

Why it exists

Building software through intensive LLM design reviews produces architectural decisions faster than a person can track. One month of that working style produced close to 900 decision records in a single markdown file — no longer greppable, readable, or manageable by hand. Existing ADR tools are built for human teams logging the occasional decision; mitos is built for a solo developer whose AI assistants generate and consume decisions continuously.

If that's your way of working, project size doesn't matter much — the higher the decision volume, the faster mitos moves from comfort to necessity.

Development

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 is safe for the offline suite and not for the live tier: the test-collection sweep is session-scoped, so parallel workers delete each other's Qdrant collections and the affected tests degrade to skips rather than failures.

The *_live.py suites and golden Layer B make real Gemini and Anthropic API calls against your own keys, and need Qdrant on :7333. They skip when no key is resolvable, so a fresh clone runs the fast path by default.

Keys resolve from the environment, a repo-root .env, or ~/.config/mitos/.env — so if you already *use* mitos, a test run can pick up your personal key and spend against it. Opt out explicitly:

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

The canonical decision format lives in mitos/format-spec.md. License: Apache 2.0.