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 is 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:

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 <your-Gemini-key> (one key covers everything; get it at https://aistudio.google.com/app/apikey). Gemini is the tested embedding provider today; a multi-provide

... View full README on GitHub