Mitos

🔧 Frühversion — wird aktiv weiterentwickelt

Wenn du über Monate hinweg Software mit KI-Assistenten entwickelst, geht die Begründung hinter deinen Entscheidungen verloren. Der Assistent vergisst, warum du einen Ansatz gewählt hast, schlägt dir Optionen vor, die du bereits verworfen hast, und deine Design-Notizen driften immer weiter von dem ab, was tatsächlich entschieden wurde. Mitos ist eine Gedächtnisschicht für diese Entscheidungen: Sie erfasst jede Entscheidung, die Alternativen, die du ausgeschlossen hast, und wie spätere Entscheidungen frühere ersetzen – und gibt diese Historie anschließend in kompakter, vertrauenswürdiger Form an deinen KI-Assistenten zurück.

Das Ergebnis: Dein KI-Kollaborateur bleibt konsistent mit den Entscheidungen, die du tatsächlich getroffen hast – er widerspricht einer früheren Entscheidung nicht mehr und macht eine bereits geklärte Frage nicht wieder auf, und deine Entscheidungsdokumentation verrottet nie still und unbemerkt.

Unter der Haube: Markdown für Menschen (decisions.md ist die Quelle der Wahrheit, die du jederzeit lesen und durchsuchen kannst), ein typisierter Graph für die Agenten (SQLite und ein lokales Qdrant für den semantischen Abruf) sowie ein MCP-Server, damit Agenten vor einer Entscheidung Präzedenzfälle prüfen und Entscheidungen festhalten, während sie sie treffen.

Verfügbar auf PyPI und in der MCP Registry.

Schnellste Installation: Gib es deinem Agenten

Wenn du mit einem KI-Coding-Agenten arbeitest (Claude Code, Cursor, Gemini CLI, …), ist der einfachste Weg, die Einrichtung von ihm erledigen zu lassen. Gib deinem Agenten in dem Projekt, in dem du mitos verwenden möchtest:

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.

Was dein Agent letztendlich tun wird – dieselben Schritte, die auch ein Mensch ausführt, alle in SETUP.md nachlesbar:

• die mitos-CLI über pipx installieren (von PyPI oder aus diesem Repository);

• einen lokalen Qdrant-Container starten (qdrant/qdrant auf Port 7333, isoliert von jedem Qdrant, das du bereits betreibst);

• den MCP-Server einmal maschinenweit registrieren, falls das nicht bereits geschehen ist;

• das Projekt-Workspace initialisieren – dabei wird das Projekt auch unter seinem Namen registriert;

• dich bitten, deine API-Schlüssel selbst zu setzen (mitos set-key) – einen Gemini-Schlüssel (erforderlich) und einen Anthropic-Schlüssel für die Konflikt-Audit-Schicht (dringend empfohlen); die Setup-Anleitung weist die Agenten an, keine Schlüsselwerte anzufassen.

Wie viele Rückfragen dein Agent unterwegs stellt, bestimmen die Einstellungen deines eigenen Agenten – nicht diesen Prompt.

Related MCP server: mcp-adr

Manuelle Einrichtung

Dieselben Schritte von Hand – ausführliche Details in SETUP.md:

1. Installieren (einmal pro Maschine): pipx install mitos-adr

2. Qdrant starten (einmal pro Maschine, von allen Projekten gemeinsam genutzt): docker compose up -d aus diesem Repository – mitos betreibt eine eigene Instanz auf :7333, sodass nie ein Qdrant für andere Arbeit berührt wird.

3. MCP-Server registrieren (einmal pro Maschine, empfohlen für Agenten): claude mcp add --scope user mitos -- mitos serve. Eine Registrierung versorgt alle Projekte – was sie kostet, wie es für andere Agenten-Harnesses funktioniert und warum ein übriggebliebener projektweit projektspezifischer .mcp.json-Eintrag verschwinden muss, steht in SETUP.md.

4. Pro Projekt: mitos init aus dem Projekt-Root ausführen, danach mitos set-key --global <your-Gemini-key> (ein Schlüssel deckt alles ab; bekommst du unter https://aistudio.google.com/app/apikey). Gemini ist der heute getestete Embedding-Anbieter; eine Abstraktion mehrere Anbieter ist in der Roadmap geplant.

5. Prüfen: mitos status . → READY ✓

mitos status . ist dabei der Kompass: Er sagt dir genau, was schon erledigt ist, was noch fehlt und was als Nächstes für dieses Projekt zu tun ist. Ohne Projektnamen beantwortet mitos status die andere Frage – was diese Maschine hat – und listet jedes registrierte Projekt auf und prüft Qdrant.

Jedes Kommando benannt sein Projekt. Es gibt kein Standardziel: mitos init registriert das Projekt unter seinem Namen, und danach akzeptiert jedes Verb -p <Name>, -p <absoluter Pfad> oder -p . aus dem Projekt-Root (Agenten übergeben dasselbe als project-Argument). mitos projects listet auf, was registriert ist. Das ist es, was eine Installation und ein MCP-Server jedes Projekt auf der Maschine bedienen, ohne einen einzigen Anruf im falschen Korpus.

Wie es läuft

Mitos ist projektbezogen – jedes Projekt bekommt seinen eigenen Entscheidungsgraph und seine eigene Qdrant-Sammlung. Im Alltag tragen die drei Verben den Kreislauf (als MCP-Tools für Agenten, unter mit identischen CLI-Zwillingen):

Ein paar Eigenschaften, die es wert sind:

• Das Markdown ist die Quelle der Wahrheit. Jede Entscheidung landet in decisions.md, lesbar und mit grep durchsuchbar; Graph und Suchindex werden daraus abgeleitet und können jederzeit neu aufgebaut werden (mitos rebuild).

• Entscheidungen werden nie bearbeitet oder gelöscht – sie werden ersetzt. Der Status (aktiv / ersetzt / geändert) wird aus den typisierten Beziehungen zwischen Entscheidungen berechnet, sodass die Geschichte des Warum bestehen bleibt.

• Es fällt sicher aus. Wenn der Suchindex oder die „Embedding"-API gestört, funktioniert die Aufzeichnung weiterhin und die Suche fällt in einen ehrlichen Textabgleich über das Markdown zurück – nichts blockiert, nichts geht verloren, und die degradierte Ausgabe benennt sich selbst.

• Es prüft sich selbst. Der Korpus-Durchlauf (mitos check -p .) findet Entscheidungen, die einander stillschweigend widersprechen, und ein --staged prüft neue Einträge als Gate im Pre-Commit- oder CI-Schritt – siehe dazu für Hooks, CI- und Cron-Rezepte in SETUP.md, die ihr Projekt auf drei verschiedene Po(), die drei verschiedene Wege benennen.

Entdecke den Rest mit mitos --help – die Hilfe erfüllt einen zweiten Job als API-Referenz.

Warum es das gibt

Softwarebau durch spädte, KI-unterstsetzte Design-Reviews erzeugt Architekturentscheidungen schneller, als eine Person nachvollziehen kann. Ein Monat dieser Arbeitsweise brachte fast 900 Entscheidungsdatensätze in eine einzige Markdown-Datei – nicht mehr durchsuchLG, nicht mehr lesbar und auch nicht mehr von Hand verwaltbar. Die bisherige ADR-Werkzeuge sind für menschliche Teams gebaut, die gelegentliche Entscheidungen dokumentieren; mitos ist für eine Entwicklerin oder einen Entwickler gebaut, der mit KI-Agenten arbeitet, die ständig Entscheidungen erzeugen und konsumieren.

Entwicklung

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 netto ist für die Offline-Suite and nicht für die Live-Ebene ist: Der Durchlauf der Testcollect ist „session-scoped", sodass die parallelen Worker sich gegenseitig die Qdrant-Collections löschen und die betroffenen Tests als Skips anstatt Failures hochgestuft werden.

Die *_live.py-Suites und der Goldene Layer B führen echte Gemini- und Anthropic-API-Aufrufe gegen deine eigenen Keys aus und brauchen Qdrant auf :7333. Sie werden übersprungen, wenn kein Schlüssel aufgelöst werden kann – so läuft ein frischer Clone standardmäßig auf dem schnellen Pfad.

Schlüssel werden aus der Umgebung, aus .env im Projekt-Work-Wurzel oder from ~/.config/mitos/.env aufgelöst. Wenn du mitos bereits nutzt, kann ein Testlauf deinen persönlichen Schlüssel aufgreifen und damit verbrauchen. Melde dich dafür ausdrücklich ab:

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

Das kanonische Entscheidformat liegt in mitos/format-spec.md. Lizenz: Apache 2.0.