Mitos

🔧 Versión temprana — en desarrollo activo

Cuando construyes software con asistentes de IA durante meses, el razonamiento que hay detrás de tus decisiones se pierde. El asistente olvida por qué elegiste una opción, vuelve a sugerir alternativas que ya descartaste y tus notas de diseño se desincronizan con lo que realmente se decidió. Mitos es una capa de memoria para esas decisiones: registra cada decisión, las alternativas que descartaste y cómo las decisiones posteriores sustituyen a las anteriores; después devuelve ese historial a tu asistente de IA de una forma compacta y fiable.

El resultado: tu colaborador de IA se mantiene fiel a las decisiones que realmente has tomado — deja de contradecir una decisión pasada o de reabrir una cuestión ya zanjada, y tu registro de decisiones nunca se estropea en silencio.

A nivel interno: markdown para humanos (decisions.md es la fuente de verdad que siempre puedes leer y consultar con grep), un grafo tipado para los agentes (SQLite + un Qdrant local para la recuperación semántica) y un servidor MCP para que los agentes consulten precedentes antes de decidir y registren decisiones a medida que las toman.

Disponible en PyPI y en el MCP Registry.

La forma más rápida de instalarlo: dáselo a tu agente

Si trabajas con un agente de IA para programar (Claude Code, Cursor, Gemini CLI, …), la vía más fácil es dejar que él haga la configuración. En el proyecto en el que quieras usar mitos, dale a tu agente:

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.

Lo que tu agente acabará haciendo son los mismos pasos que seguiría una persona, todos en SETUP.md, donde puedes leerlos antes:

• instalar la CLI de mitos mediante pipx (desde PyPI o desde este repositorio);

• levantar un contenedor local de Qdrant (qdrant/qdrant en el puerto 7333, aislado de cualquier Qdrant que ya tengas en marcha);

• registrar el servidor MCP una sola vez para toda la máquina, si todavía no está registrado;

• inicializar el espacio de trabajo del proyecto, lo que también lo registra por nombre;

• pedirte que configures tus claves de API tú mismo (mitos set-key): una clave de Gemini (obligatoria) y una clave de Anthropic para la capa de auditoría de conflictos (muy recomendada); la guía de configuración indica a los agentes que no manipulen los valores de las claves.

Cuántas preguntas te haga tu agente por el camino depende de la configuración de tu propio agente, no de esta instrucción.

Related MCP server: mcp-adr

Configuración manual

Los mismos pasos a mano — con todo el detalle en SETUP.md:

1. Instala (una vez por máquina): pipx install mitos-adr

2. Arranca Qdrant (una vez por máquina, compartido por todos los proyectos): docker compose up -d desde este repositorio — mitos ejecuta su instancia en :7333, así que nunca toca un Qdrant que uses para otro trabajo.

3. Registra el servidor MCP (una vez por máquina, recomendable para agentes): claude mcp add --scope user mitos -- mitos serve. Un único registro sirve a todos los proyectos — consulta SETUP.md para ver qué implica, para otros entornos y por qué debe eliminarse cualquier entrada .mcp.json residual a nivel de proyecto.

4. Por proyecto: mitos init desde la raíz del proyecto y después mitos set-key --global <your-Gemini-key> (una sola clave sirve para todo; consíguela en https://aistudio.google.com/app/apikey). Hoy Gemini es el proveedor de embeddings probado; en la hoja de ruta hay una abstracción multintegrador.

5. Verifica: mitos status . → READY ✓.

mitos status . es la brújula en todo momento: dice exactamente qué está hecho, qué falta y qué hacer después para ese proyecto. Sin un proyecto nombrado, mitos status responde a la otra pregunta, qué tiene esta máquina: lista todos los proyectos registrados y comprueba Qdrant.

Cada comando indica su proyecto por nombre. No hay un destino por defecto: mitos init registra el proyecto por nombre, y a partir de ahí cada verbo acepta -p <name>, -p <absolute path> o -p . desde la raíz del proyecto (los agentes pasar lo mismo como argumento project). mitos projects muestra lo que está registrado. Eso es lo que permite que una sola instalación y un único servidor MCP atiendan a todos los proyectos de la máquina, sin que una consulta llegue nunca al corpus equivocado.

Cómo funciona

Mitos es por proyecto — cada proyecto tiene su propio grafo de decisiones y su propia colección de Qdrant. En el día a día, tres verbos sostienen el ciclo (como herramientas MCP para agentes, con idénticos equivalentes en la CLI):

Algunas características que conviene conocer:

• El markdown es la fuente de verdad. Cada decisión acaba en decisions.md, legible y consultable con grep; el grafo y el índice de búsqueda se derivan de él y siempre se pueden reconstruir (mitos rebuild).

• Las decisiones no se editan ni se eliminan — se sustituyen. El estado (activa / sustituida / enmendada) se calcula a partir de relations tipadas entre decisiones, de modo que la historia del por quén siempre sobrevive.

• Es seguro frente los ".*" fallos. Si se cae el índice de búsqueda o la API de embeddings, el registro sigue funcionando y la búsqueda se reduce a una coincidencia de texto honesta sobre el markdown — nada se bloquea, nada se pierde, y la salida degradada dice que está degradada.

• Se audita a sí mismo. El barrido del corpus (mitos check -p .) encuentra decisiones que se contradicen en silencio, y --staged filtra las nuevas entradas para usarse en pre-commit o paso CI — consulta SETUP.md para el hook y las recetas de CI y cron, que usan nombran el proyecto de tres semanas distintas.

Explora el resto con mitos --help — el texto de ayuda también hace de referencia de la API.

Por qué existe

Construir software mediante revisiones de diseño intensivas con LLM produce decisiones más rápido de lo que una persona puede seguir. Un mes de ese estilo de trabajo generó casi 900 records de decisión en un único archivo markdown — ya no era consultable con grep, readable ni legible a mano. Las herramientas de ADR existentes están pensadas para equipos humanos que registran una decisión de vez; mitos está pensado para un desarrollador solitario cuyos asistentes de IA generan y consumen decisiones de forma continua. Ese es tu modo de trabajo, sin importar el tamaño del proyecto: cuanto mayor es el volumen de decisiones, más rápido passes mitos de un comodidad a una necesidad.

Desarrollo

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 es seguro para la suite offline pero no para la capa en vivo: el proceso de recolección de tests está limitado a la sesión, por lo que los workers paralelos se eliminan colecciones de Qdrant entre sí y los tests afectados se reducen a omisiones en lugar de fallos.

Las suibles *_live.py y golden Layer B hacen Llamadas reales a las APIs de Gemini y Anthropic con tus propias claves y aq. require Qdrant en :7333. Se omiten cuando no hay ninguna clave configurable, así que un clon recién creado usa la vía rápida por defecto.

Las claves se resuelven desde the entorno, un .env en la raíz del repositorio o ~/.config/mitos/.env — así que si ya usas mitos, una ejecución de pruebas puede tomar tu clave personal y gastarla. Puedes renunciar a explícitamente de;

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

El formato canónico de las decisiones se define en mitos/format-spec.md. Licencia: Apache-2.0.