Mneme Decision MCP

Mneme HQ

Prevenção de deriva arquitetural para o SDLC de IA agêntica.

A Mneme transforma decisões arquiteturais e ADRs em guarda-corpos determinísticos para o SDLC de IA agêntica — abrangendo agentes de codificação, mutações de repositório, regras geradas e portões de CI.

Onde a sua arquitetura é realmente aplicada? Execute a Auditoria de Arquitetura para ver quais decisões estão protegidas, quais podem se tornar guarda-corpos determinísticos e quais ainda dependem de alguém lembrar das regras. Experimente →

A Mneme é a camada de governança arquitetural por trás desse mecanismo de prevenção de deriva. Ela mantém decisões de engenharia registradas ativas enquanto sistemas de IA de codificação propõem e modificam código, em vez de deixar os ADRs como documentação passiva.

Fase atual: Validação da Camada 1. A semântica de recuperação, aplicação e benchmark é regida pela arquitetura aceita e pelo registro de congelamento. Consulte Fase Atual antes de alterar o comportamento central.

O que a Mneme faz

A Mneme separa a orientação arquitetural da aplicação determinística:

• Registra decisões arquiteturais em um corpus de decisões estruturado e auditável.
• Recupera decisões relevantes quando um agente ou modelo precisa de orientação arquitetural.
• Aplica regras governadas deterministicamente sob semântica explícita de aplicabilidade.
• Integra-se no limite confiável mais precoce exposto por cada fluxo de trabalho de codificação.
• Audita caminhos de mutação contornáveis onde o bloqueio pré-alteração não está tecnicamente disponível.
• Executa em CI como um portão determinístico final antes que alterações incompatíveis sejam aceitas.

A mesma entrada e o mesmo estado de decisão governado produzem o mesmo resultado de aplicação. A Mneme não depende de um avaliador LLM para suas decisões centrais de permitir/avisar/bloquear.

A Mneme não é um armazenamento vetorial de propósito geral, sistema de memória conversacional, agente de codificação autônomo ou plataforma de observabilidade de implantação.

Instalação

Requer Python 3.11+.

pip install mneme-hq

Verifique a CLI:

mneme --help

Para desenvolvimento no repositório:

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

Decision MCP

A Mneme expõe o Índice de Decisões por meio de um servidor MCP local para que clientes compatíveis com MCP possam propor decisões arquiteturais candidatas e consultar o estado das decisões sem obter autoridade para alterar esse estado.

Instale a dependência MCP opcional:

pip install "mneme-hq[mcp]"

Inicie o servidor stdio local com o armazenamento de propostas habilitado:

mneme decision-mcp

Opcionalmente, adicione um corpus canônico de ADRs. A Mneme valida e resolve precedências do corpus antes de o servidor iniciar; estado de ADR inválido ou ambíguo falha de forma fechada, em vez de servir uma visão de autoridade degradada.

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

A superfície MCP está intencionalmente congelada em seis ferramentas:

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

As ferramentas de proposta criam apenas propostas não autoritativas. As ferramentas de leitura consultam o estado de propostas e de decisões canônicas. O MCP expõe deliberadamente nenhuma autoridade de aceitar, rejeitar, ativar, substituir, exceção, contorno ou evidência confiável.

A autoridade humana permanece explícita por meio de mneme decision proposals | show | accept | reject. Aceitar uma proposta materializa uma decisão canônica; não ativa proteção nem executa a Auditoria de Arquitetura.

Consulte ADR-027 e as notas de versão v0.9.0 para o limite de autoridade e o contrato de versão.

Auditoria de Arquitetura

Veja onde a sua arquitetura está realmente protegida — e onde ainda depende de pessoas lembrarem das regras.

A Mneme audita o seu repositório e mostra quais decisões arquiteturais estão:

• Protegidas — já aplicadas mecanicamente
• Prontas para Mneme — podem ser transformadas em um guarda-corpo determinístico
• Exigem modelagem — importantes, mas ainda não seguras para automatizar
• Orientação — contexto útil, mas que não deve ser aplicado

Execute uma auditoria:

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

Para uma decisão pronta para Mneme, valide a proteção proposta antes de habilitá-la:

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

Em seguida, ative-a explicitamente:

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

A Mneme só relata uma decisão como Protegida depois de verificar que a aplicação real está em vigor. O contrato completo de ativação está documentado em Ativação de Proteção.

Experimente a Auditoria de Arquitetura →

Exemplo de aplicação em 60 segundos

Inicialize um corpus de decisões local ao projeto:

mneme init

Registre uma decisão arquitetural:

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"

Crie uma entrada proposta que a viole:

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

Execute a verificação determinística:

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

No modo estrito, a proposta YAML proibida retorna um veredito FAIL e código de saída 2. Uma proposta JSON em conformidade retorna PASS e código de saída 0.

A CLI é a superfície comum de aplicação. As integrações de agente traduzem seus eventos nativos para o mesmo modelo de decisão e aplicação da Mneme.

Modo de configuração (sem aplicação)

mneme setup inicializa a Mneme em um repositório sem alterar a forma como a equipe trabalha: cria ou detecta a memória do projeto, detecta ambientes de agente compatíveis e relata a prontidão de proteção — tudo sem habilitar qualquer aplicação bloqueante. A configuração nunca transforma o comportamento de aviso/observação em comportamento bloqueante; a ativação da aplicação preventiva é sempre uma decisão separada e explícita.

mneme setup

Opcionalmente, registre uma referência opaca da Auditoria de Arquitetura para que a configuração possa ser atribuída a uma linha de base de Auditoria salva:

mneme setup --audit-ref <reference>

A configuração é idempotente: executá-la novamente em um projeto Mneme existente deixa a configuração válida intacta.

Como 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

A Mneme aplica a governança no limite confiável mais precoce que um fluxo de trabalho expõe:

1. Antes da geração, quando o contexto arquitetural pode ser injetado na chamada do modelo.
2. Antes de mutações de arquivo compatíveis, quando um agente expõe um gancho de pré-ferramenta bloqueante.
3. Após mutações contornáveis, por meio de auditorias limitadas da árvore de trabalho, quando gravações via shell/script não podem ser inspecionadas com segurança antes da execução.
4. Antes do merge, por meio de portões de CI baseados em CLI.

Esses limites são complementares. Uma integração reivindica apenas as superfícies que foram implementadas e validadas para aquele harness.

Recuperação não é aplicação

A recuperação de decisões responde: quais decisões arquiteturais são úteis como orientação para esta tarefa?

A aplicação responde: a alteração proposta viola uma regra governada que se aplica aqui?

Essas preocupações são intencionalmente separadas. Consulte ADR-017, ADR-019 e ADR-020.

Superfícies compatíveis

A matriz de suporte autoritativa está em docs/integrations/README.md. Os rótulos abaixo são níveis de evidência, não termos de marketing intercambiáveis.

Nível de suporte	Superfície
Integração nativa	Claude Code
Integração nativa	Claude Agent SDK
Integração nativa	Google Antigravity
Integração nativa	Codex CLI
Integração nativa	Kiro CLI 3.0 / v3
Compatibilidade validada	Paperclip — transportes CLI e ACP, sem adaptador necessário
Exportação de regras	Cursor
Portão de CI baseado em CLI	GitHub Actions, GitLab CI
Experimental	OpenCode
Planejado	Deep Agents middleware POC

Cada integração documenta seu limite de bloqueio real, caminhos de contorno, comportamento degradado e evidência de validação. Comece pela matriz de integrações, não por suposições baseadas em outro harness.

ADRs e memória do projeto

A Mneme pode compilar decisões de arquitetura em registros de governança estruturados, em vez de tratar ADRs como prosa passiva.

A fonte de verdade da governança do repositório é .mneme/project_memory.json. O caminho de importação de ADR preserva a proveniência explícita da fonte quando disponível, para que regras tipadas possam ser inspecionadas e aplicadas de forma consistente.

Consulte:

• Importação de ADR
• ADRs aceitos
• Fase arquitetural atual

Garantias de arquitetura

Três princípios regem o mecanismo atual:

• Determinístico > engenhoso. O comportamento de aplicação deve ser reproduzível.
• Auditável > autônomo. Um veredito deve ser rastreável até a decisão, a regra, o estado de aplicabilidade e a evidência que o produziu.
• Prevenção antes de revisão. Quando existe um limite confiável pré-alteração, use-o; quando não existe, exponha a limitação e audite depois, em vez de fingir que o caminho está bloqueado.

O escopo atual da Camada 1, superfícies congeladas, emendas aceitas, trabalho experimental e trabalho adiado da Camada 2 são mantidos em docs/architecture/current-phase.md.

Não infira arquitetura deste README quando um ADR vinculado ou documento de arquitetura for mais específico.

Benchmark e validação

O benchmark da Mneme é um instrumento de regressão e integridade para o comportamento de recuperação e aplicação. Não é um benchmark geral de qualidade de modelo.

O benchmark mantém a pontuação de recuperação e aplicação distintas, para que alterações não possam melhorar silenciosamente uma superfície enquanto regridem outra.

Consulte:

• Metodologia do benchmark
• Benchmark público
• Fase atual e congelamento
• Notas de versão

Demonstrações

• Agente Python Governado
• Importação de ADR
• Deriva Arquitetural
• Governança do GitHub Actions
• Política de Dependências

Mais exemplos: mnemehq.com/demo

Contribuindo

Antes de alterar a semântica de recuperação, aplicação, aplicabilidade, tratamento de conflitos ou benchmark, leia a arquitetura e os ADRs que regem essa superfície.

• Contribuindo
• Fase arquitetural atual
• Política de segurança
• Changelog

Alterações comportamentais centrais podem exigir o procedimento de emenda do estatuto do repositório. Documentação, ferramentas, integrações e exemplos não autorizam automaticamente alterações em comportamento congelado.

Licença

MIT. Consulte LICENSE.