Mneme is an architectural drift prevention tool for the agentic AI software development lifecycle (SDLC), officially described as an "open-ended decision and control layer." It turns durable engineering decisions into context for AI coding assistants, deterministic enforcement rules, and inspectable execution outcomes, spanning AI coding agents, code repositories, and CI workflows. Architecture is the first supported decision domain: Mneme prevents architectural drift by turning architectural decisions and ADRs into deterministic guardrails.
Purpose and Positioning Mneme's core goal is to keep recorded engineering decisions active when AI coding systems propose and modify code, rather than leaving ADRs in a passive documentation state. It explicitly distinguishes "architectural guidance" from "deterministic enforcement": recording architectural decisions into a structured, auditable decision corpus; retrieving relevant decisions when an agent or model needs architectural guidance; deterministically enforcing governed rules under explicit applicability semantics; integrating at the earliest reliable boundary exposed by each coding workflow; auditing bypassable modification paths that cannot be blocked before the change; and running in CI as a final deterministic gate to prevent incompatible changes from being accepted.
Key Capabilities
- Decision recording and retrieval: record architectural decisions in a structured, auditable way and retrieve relevant decisions as guidance when needed.
- Deterministic enforcement: enforce governed rules under explicit applicability semantics, with core allow/warn/fail determinations not relying on an LLM judge.
- Multi-boundary integration: inject architectural context before generation, intercept before supported file modifications via a blocking pre-tool hook, perform bounded worktree audits for bypassable modifications, and block before merge via a CLI CI gate.
- Architecture Audit: audit the repository and show which architectural decisions are already protected (mechanically enforced), which can be turned into deterministic guardrails (Mneme-ready), which need modeling, and which serve only as guidance. Report as Protected only when real enforcement can be verified to be in place.
- MCP local server: expose the Decision Index through a local stdio MCP server; MCP clients can propose candidate architectural decisions and query decision status, but have no authority to change status. The MCP surface is fixed at six tools: decision.propose, decision.propose_batch, decision.search, decision.applicable_to, etc.; the proposal tools only create non-authoritative proposals, and read toolsHas query proposals and canonical decision status, without exposing accept, reject, activate, supersede, exception, bypass, or trusted evidence permissions.
- Project memory: the source of truth for repository governance is .mneme/project_memory.json; ADR import paths preserve explicit source provenance when available.
- Benchmarks and validation: benchmarks are regression and integrity tools for retrieval and enforcement behavior; retrieval and enforcement scores remain independent.
Usage Requires Python 3.11+. The CLI can be validated and supports repository development. After installing the optional MCP dependencies, start the local stdio server; canonical reads come by default from the Decision Index persisted in .mneme/project_memory.json, while proposal storage remains independent. --memory can be used to select another project memory file, which must contain a valid authoritative decision_index section; otherwise MCP will fail closed rather than rebuilding authority from a compatible decisions[] snapshot. Memory created by mneme init or mneme setup already has an empty decision_index section, so no migration is needed; when an older file lacks that section, MCP reports an error and prompts for migration. You can first preview the migration (without writing, listing the visible impact), then apply the migration. Migration is lossless or it is refused; there is no force or repair mode. --adr-dir is now optional validation input; ADRs will not become a second source of MCP authority.
60-second execution example: initialize a project-local decision corpus; record an architectural decision; create a proposed input that violates that decision; run the deterministic check. In strict mode, a prohibited YAML proposal returns a FAIL verdict and exit code 2; a compliant JSON proposal returns PASS and exit code 0. The CLI is the general execution surface; agent integrations translate native events into the same Mneme decision and enforcement model.
mneme check can add an optional, repeatable --applicability-preview <label> to non-authoritatively preview which canonical decisions would apply to a context label asserted by the caller. The preview is written only to stderr, is independent of the normal check result, does not trust the supplied label, does not exclude decisions, and does not change enforcement, stdout, JSON mneme.check/v1, hook behavior, or exit codes. A memory without the section or a preview computation error reports PREVIEW UNAVAILABLE on stderr, does not migrate memory, and does not weaken enforcement. This preview is not a security control.
Setup mode (no enforcement): mneme setup initializes Mneme without changing how the team works, creates or detects project memory, detects supported agent environments, and reports protection readiness, without enabling any blocking enforcement. Setup never turns warning/observation behavior into blocking behavior; activation of preventive enforcement is always a separate, explicit decision. It can optionally record an opaque Architecture Audit reference so that setup can be attributed back to a saved audit baseline. Setup is idempotent.
Applicable scenarios Suitable for software teams using AI coding agents (such as Claude Code, Cursor, etc.) and agentic workflows that want to continuously enforce architectural decisions while AI proposes and modifies code, prevent architectural drift, and set up a final deterministic gate in CI. Also suitable for scenarios that need to turn ADRs from passive documents into inspectable, enforceable guardrails.
Limitations and boundaries Mneme is not a general-purpose vector store, conversational memory system, autonomous coding agent, or deployment observability platform. Retrieval is not enforcement: retrieval answers which architectural decisions can serve as guidance for this task, while enforcement answers whether a proposed change violates the governed rules applicable here; the two are intentionally separate. Integrations declare only the surfaces that have been implemented and verified for that toolchain. It is currently in the Layer 1 validation phase; retrieval, enforcement, and benchmark semantics are governed by accepted architecture and frozen records. Core behavior changes may require the repository's charter amendment process. The license is MIT.
