Mneme Decision MCP

Mneme HQ

Prevención de deriva arquitectónica para el SDLC de IA agéntica.

Mneme convierte las decisiones arquitectónicas y los ADR en salvaguardas deterministas para el SDLC de IA agéntica — en agentes de codificación, mutaciones de repositorio, reglas generadas y compuertas de CI.

¿Dónde se aplica realmente tu arquitectura? Ejecuta la Auditoría de Arquitectura para ver qué decisiones están protegidas, cuáles pueden convertirse en salvaguardas deterministas y cuáles aún dependen de que alguien recuerde las reglas. Pruébala →

Mneme es la capa de gobernanza arquitectónica detrás de ese mecanismo de prevención de deriva. Mantiene activas las decisiones de ingeniería registradas mientras los sistemas de IA proponen y modifican código, en lugar de dejar los ADR como documentación pasiva.

Fase actual: Validación de la Capa 1. La recuperación, la aplicación y la semántica de referencia están gobernadas por la arquitectura aceptada y el registro de congelación. Consulta Fase Actual antes de cambiar el comportamiento central.

Qué hace Mneme

Mneme separa la guía arquitectónica de la aplicación determinista:

• Registra decisiones arquitectónicas en un corpus de decisiones estructurado y auditable.
• Recupera decisiones relevantes cuando un agente o modelo necesita guía arquitectónica.
• Aplica reglas gobernadas de forma determinista bajo semántica de aplicabilidad explícita.
• Se integra en el límite confiable más temprano que expone cada flujo de trabajo de codificación.
• Audita rutas de mutación evadibles donde el bloqueo previo al cambio no está técnicamente disponible.
• Se ejecuta en CI como compuerta determinista final antes de que se acepten cambios incompatibles.

La misma entrada y el mismo estado de decisión gobernada producen el mismo resultado de aplicación. Mneme no depende de un juez LLM para sus decisiones centrales de permitir/advertir/bloquear.

Mneme no es un almacén vectorial de propósito general, un sistema de memoria conversacional, un agente de codificación autónomo ni una plataforma de observabilidad de despliegues.

Instalación

Requiere Python 3.11+.

pip install mneme-hq

Verifica la CLI:

mneme --help

Para desarrollo en el repositorio:

git clone https://github.com/MnemeHQ/mneme.git
cd mneme
pip install -e ".[dev]"

Decision MCP

Mneme expone el Índice de Decisiones a través de un servidor MCP local para que los clientes compatibles con MCP puedan proponer decisiones arquitectónicas candidatas y consultar el estado de las decisiones sin obtener autoridad para cambiar ese estado.

Instala la dependencia opcional de MCP:

pip install "mneme-hq[mcp]"

Inicia el servidor stdio local con el almacén de propuestas habilitado:

mneme decision-mcp

Opcionalmente, añade un corpus canónico de ADR. Mneme valida y resuelve precedencias del corpus antes de que el servidor se inicie; el estado de ADR inválido o ambiguo falla de forma cerrada en lugar de servir una vista de autoridad degradada.

mneme decision-mcp --adr-dir path/to/adrs

La superficie de MCP está intencionalmente congelada a seis herramientas:

• decision.propose
• decision.propose_batch
• decision.get
• decision.search
• decision.applicable_to
• decision.trace

Las herramientas de propuesta solo crean propuestas no autoritativas. Las herramientas de lectura consultan el estado de propuestas y decisiones canónicas. MCP deliberadamente no expone autoridad de aceptar, rechazar, activar, superar, excepción, evasión o evidencia de confianza.

La autoridad humana permanece explícita a través de mneme decision proposals | show | accept | reject. Aceptar una propuesta materializa una decisión canónica; no activa protección ni ejecuta la Auditoría de Arquitectura.

Consulta ADR-027 y las notas de la versión v0.9.0 para el límite de autoridad y el contrato de versiones.

Auditoría de Arquitectura

Mira dónde está realmente protegida tu arquitectura — y dónde aún depende de que las personas recuerden las reglas.

Mneme audita tu repositorio y muestra qué decisiones arquitectónicas están:

• Protegidas — ya aplicadas mecánicamente
• Listas para Mneme — pueden convertirse en una salvaguarda determinista
• Requieren modelado — importantes, pero aún no seguras de automatizar
• Guía — contexto útil, pero no algo que deba aplicarse

Ejecuta una auditoría:

mneme audit --memory .mneme/project_memory.json --repo-root .

Para una decisión lista para Mneme, valida la protección propuesta antes de habilitarla:

mneme protect validate <decision-id> --memory .mneme/project_memory.json

Luego actívala explícitamente:

mneme protect activate <decision-id> --memory .mneme/project_memory.json

Mneme solo reporta una decisión como Protegida después de poder verificar que la aplicación real está en vigor. El contrato completo de activación está documentado en Activación de Protección.

Prueba la Auditoría de Arquitectura →

Ejemplo de aplicación en 60 segundos

Inicializa un corpus de decisiones local al proyecto:

mneme init

Registra una decisión arquitectónica:

mneme add_decision \
  --memory .mneme/project_memory.json \
  --id config-format \
  --decision "Use JSON for configuration files" \
  --scope config \
  --constraint "Use JSON only" \
  --anti-pattern "Do not use YAML"

Crea una entrada propuesta que la viole:

python -c "import pathlib; pathlib.Path('prompt.txt').write_text('Set up a new YAML config file', encoding='utf-8')"

Ejecuta la verificación determinista:

mneme check \
  --memory .mneme/project_memory.json \
  --input prompt.txt \
  --query configuration

En modo estricto, la propuesta YAML prohibida devuelve un veredicto FAIL y código de salida 2. Una propuesta JSON conforme devuelve PASS y código de salida 0.

La CLI es la superficie común de aplicación. Las integraciones de agentes traducen sus eventos nativos al mismo modelo de decisión y aplicación de Mneme.

Modo de configuración (sin aplicación)

mneme setup inicializa Mneme en un repositorio sin cambiar cómo trabaja el equipo: crea o detecta la memoria del proyecto, detecta entornos de agentes compatibles y reporta la preparación de protección — todo sin habilitar ninguna aplicación bloqueante. La configuración nunca convierte el comportamiento de advertir/observar en bloqueante; la activación de la aplicación preventiva es siempre una decisión separada y explícita.

mneme setup

Opcionalmente, registra una referencia opaca de Auditoría de Arquitectura para que la configuración pueda atribuirse a una línea base de Auditoría guardada:

mneme setup --audit-ref <reference>

La configuración es idempotente: volver a ejecutarla sobre un proyecto Mneme existente deja la configuración válida intacta.

Cómo funciona

Architectural decisions / ADRs
            |
            v
   structured decision corpus
            |
      +-----+--------------------+
      |                          |
      v                          v
relevant guidance       deterministic enforcement
   retrieval             + applicability checks
      |                          |
      +------------+-------------+
                   |
                   v
       workflow-specific boundary
                   |
      +------------+-------------+
      |            |             |
 pre-change     post-change      CI
   hooks          audit          gate

Mneme aplica gobernanza en el límite confiable más temprano que expone un flujo de trabajo:

1. Antes de la generación cuando el contexto arquitectónico puede inyectarse en la llamada al modelo.
2. Antes de mutaciones de archivos compatibles cuando un agente expone un enganche de bloqueo previo a la herramienta.
3. Después de mutaciones evadibles mediante auditorías acotadas del árbol de trabajo donde las escrituras de shell/scripts no pueden inspeccionarse de forma segura antes de la ejecución.
4. Antes de la fusión mediante compuertas de CI basadas en CLI.

Estos límites son complementarios. Una integración solo reclama las superficies que se han implementado y validado para ese entorno.

La recuperación no es aplicación

La recuperación de decisiones responde: ¿qué decisiones arquitectónicas son útiles como guía para esta tarea?

La aplicación responde: ¿la propuesta de cambio viola una regla gobernada que aplica aquí?

Esas preocupaciones están intencionalmente separadas. Consulta ADR-017, ADR-019 y ADR-020.

Superficies compatibles

La matriz de soporte autoritativa vive en docs/integrations/README.md. Las etiquetas a continuación son niveles de evidencia, no términos de marketing intercambiables.

Nivel de soporte	Superficie
Integración nativa	Claude Code
Integración nativa	Claude Agent SDK
Integración nativa	Google Antigravity
Integración nativa	Codex CLI
Integración nativa	Kiro CLI 3.0 / v3
Compatibilidad validada	Paperclip — transportes CLI y ACP, sin adaptador requerido
Exportación de reglas	Cursor
Compuerta de CI basada en CLI	GitHub Actions, GitLab CI
Experimental	OpenCode
Planificado	POC de middleware Deep Agents

Cada integración documenta su límite de bloqueo real, rutas de evasión, comportamiento degradado y evidencia de validación. Comienza con la matriz de integraciones, no con suposiciones basadas en otro entorno.

ADR y memoria del proyecto

Mneme puede compilar decisiones de arquitectura en registros de gobernanza estructurados en lugar de tratar los ADR como prosa pasiva.

La fuente de verdad de gobernanza del repositorio es .mneme/project_memory.json. La ruta de importación de ADR preserva la procedencia explícita de la fuente cuando está disponible, para que las reglas tipadas puedan inspeccionarse y aplicarse de manera consistente.

Consulta:

• Importación de ADR
• ADR aceptados
• Fase de arquitectura actual

Garantías de arquitectura

Tres principios gobiernan el mecanismo actual:

• Determinista > ingenioso. El comportamiento de aplicación debe ser reproducible.
• Auditable > autónomo. Un veredicto debe poder rastrearse hasta la decisión, la regla, el estado de aplicabilidad y la evidencia que lo produjo.
• Prevención antes que revisión. Cuando existe un límite confiable previo al cambio, úsalo; cuando no existe, expón la limitación y audita después en lugar de pretender que la ruta está bloqueada.

El alcance actual de la Capa 1, las superficies congeladas, las enmiendas aceptadas, el trabajo experimental y el trabajo diferido de la Capa 2 se mantienen en docs/architecture/current-phase.md.

No infieras la arquitectura de este README cuando un ADR enlazado o un documento de arquitectura sea más específico.

Benchmark y validación

El benchmark de Mneme es un instrumento de regresión e integridad para el comportamiento de recuperación y aplicación. No es un benchmark general de calidad de modelos.

El benchmark mantiene separadas las puntuaciones de recuperación y aplicación para que los cambios no puedan mejorar silenciosamente una superficie mientras degradan otra.

Consulta:

• Metodología del benchmark
• Benchmark público
• Fase actual y congelación
• Notas de versión

Demos

• Agente Python gobernado
• Importación de ADR
• Deriva arquitectónica
• Gobernanza de GitHub Actions
• Política de dependencias

Más ejemplos: mnemehq.com/demo

Contribuciones

Antes de cambiar la recuperación, la aplicación, la aplicabilidad, el manejo de conflictos o la semántica del benchmark, lee la arquitectura y los ADR que gobiernan esa superficie.

• Contribuciones
• Fase de arquitectura actual
• Política de seguridad
• Registro de cambios

Los cambios de comportamiento central pueden requerir el procedimiento de enmienda del estatuto del repositorio. La documentación, las herramientas, las integraciones y los ejemplos no autorizan automáticamente cambios en el comportamiento congelado.

Licencia

MIT. Consulta LICENSE.