Mitos

What Mitos does

Mitos MCP server maintains an architectural decision record for each project. A decision includes the chosen approach, alternatives that were rejected, and relationships to earlier decisions, such as superseding or amending them. This preserves the reasoning behind a design instead of treating each new assistant conversation as an isolated interaction.

The project’s Markdown files remain the authoritative record. Decisions are written to decisions.md, while committed entries can be rotated into quarterly files under decisions/archive/. These files are readable and searchable with ordinary text tools. The graph and search data are derived from the Markdown and can be rebuilt.

This places Mitos in the Knowledge & Memory category for workflows where AI coding agents need to check precedent before proposing or committing an architectural change.

How it works

Mitos MCP server runs per project. Each project has its own decision graph and Qdrant collections, while one machine-level installation and MCP registration can serve multiple registered projects. Commands and agent calls identify the target with a project name, an absolute path, or . from the project root; there is no implicit default project.

The main workflow has three operations:

• surface_decisions finds relevant prior decisions before a new choice is made and includes previously rejected alternatives.
• record_decision stores a settled choice, its rejected paths, and typed relationships to existing records.
• query_decisions searches by meaning, exact handle, or rejected option.

Semantic recall uses a local Qdrant instance and Gemini embeddings. If the index or embedding service is unavailable, recording continues and searches fall back to text matching over the Markdown, with degraded output reported. mitos check audits the corpus for contradictory decisions. An optional commit hook checks decision changes before allowing a commit to proceed.

Setup and configuration

Install the CLI with pipx install mitos-adr. Start the project’s Qdrant container on port 7333, register the MCP process with the client, and run mitos init from each project root. Use mitos set-key --global to configure a Gemini API key; this is the tested embedding provider and is required. An Anthropic key is strongly recommended for the conflict-audit layer.

Run mitos status . to see missing setup steps and confirm readiness. mitos projects lists registered projects, while mitos unregister <name> removes a registration without deleting its workspace. The CLI provides counterparts for the MCP operations, including surface, record, query, rebuild, and check.

Tools and capabilities

The Mitos MCP server provides decision surfacing, decision recording, and decision querying for agents. It also supports a durable Markdown record, typed decision relationships, semantic retrieval through Qdrant, exact-handle lookup, rejected-option searches, graph rebuilding, and contradiction audits. The CLI and MCP interfaces expose the same core workflow.

Limitations and notes

Mitos is marked Alpha and is actively developed. Python 3.13 or newer is indicated. Gemini is the currently tested embedding provider; multi-provider support is described as a future item. The live test suites make real Gemini and Anthropic API calls and require Qdrant, so API usage and local service availability matter for those features.

The architecture intentionally does not edit a decision’s core axiom in place. Later decisions express correction, amendment, or supersession, while commentary can be edited with mitos amend-commentary. The Markdown corpus should therefore be treated as the durable source from which derived stores can be regenerated.