Mneme Decision MCP
OfficialSummary: Mneme Decision MCP is a local, read-and-propose-only server over the Mneme Decision Index — you can submit candidate architectural decisions and query decision state, but it exposes no authority to change it.
Propose one decision (
decision.propose) — submits a non-authoritative candidate (statusproposed) with title, statement, rationale, provenance, scope hints, and related ids; identical submissions are idempotent, and authority fields are hard-rejected.Propose in batch (
decision.propose_batch) — submits multiple candidates from one producer output, each with independent identity; optionalshared_provenancefallback is applied when a candidate omits provenance. No batch acceptance semantics.Fetch a record (
decision.get) — reads one proposal or canonical decision by stable id, returningproposal,canonical_decision, ornot_found.Search (
decision.search) — deterministic substring/exact-metadata search across proposals and canonical decisions, returned in separate lists with AND-combined filters.Check applicability (
decision.applicable_to) — returns records whose scope hints or context overlap supplied paths/context; pure retrieval matching, no glob or typed-rule evaluation.Trace lineage (
decision.trace) — returns known deterministic lineage (provenance, acceptance, rules, declared evidence) for a proposal or canonical decision id.Read safely — all query tools are read-only, idempotent, and non-destructive; rule-lineage integrity failures fail closed as protocol errors.
No authority or enforcement — no accept, reject, activate, supersede, exception, bypass, or trusted-evidence operations, and no allow/warn/fail verdicts. Canonical state changes remain human-driven via the Mneme CLI.
Runs Mneme as a deterministic CI gate in GitHub Actions, failing builds when proposed changes violate governed architectural decisions.
Runs Mneme as a deterministic CI gate in GitLab CI, blocking incompatible changes before merge.
Integrates with Google Antigravity to apply architectural governance within Antigravity coding workflows.
Mneme HQ
Mneme is an open decision and control layer for agentic software development.
It turns durable engineering decisions into agent context, deterministic enforcement, and inspectable enforcement results across AI coding agents, repositories, and CI workflows. Architecture is the first supported decision domain: Mneme prevents architectural drift by turning architectural decisions and ADRs into deterministic guardrails across coding agents, repository mutations, generated rules, and CI gates.
Where is your architecture actually enforced? Run the Architecture Audit to see which decisions are protected, which can become deterministic guardrails, and which still depend on someone remembering the rules. Try it →
Mneme is the decision layer behind that drift-prevention mechanism. It keeps recorded engineering decisions active as AI coding systems propose and modify code, instead of leaving ADRs as passive documentation.

Solid surfaces ship today; dashed surfaces are planned. Support levels per integration: integrations matrix.
Current phase: Layer 1 validation. Retrieval, enforcement, and benchmark semantics are governed by the accepted architecture and freeze record. See Current Phase before changing core behavior.
What Mneme does
Mneme separates architectural guidance from deterministic enforcement:
Records architectural decisions in a structured, auditable decision corpus.
Retrieves relevant decisions when an agent or model needs architectural guidance.
Enforces governed rules deterministically under explicit applicability semantics.
Integrates at the earliest reliable boundary exposed by each coding workflow.
Audits bypassable mutation paths where pre-change blocking is not technically available.
Runs in CI as a final deterministic gate before incompatible changes are accepted.
The same input and governed decision state produce the same enforcement result. Mneme does not depend on an LLM judge for its core allow/warn/fail decisions.
Mneme is not a general-purpose vector store, conversational memory system, autonomous coding agent, or deployment observability platform.
Related MCP server: mcp-memoria
Install
Requires Python 3.11+.
pip install mneme-hqVerify the CLI:
mneme --helpFor repository development:
git clone https://github.com/MnemeHQ/mneme.git
cd mneme
pip install -e ".[dev]"Decision MCP
Mneme exposes the Decision Index over a local MCP server so MCP-capable clients can propose candidate architectural decisions and query decision state without gaining authority to change that state.
Install the optional MCP dependency:
pip install "mneme-hq[mcp]"Start the local stdio server. Canonical reads come from the persisted Decision Index in .mneme/project_memory.json by default; the proposal store remains separate.
mneme decision-mcpUse --memory to select another project memory file. The file must contain a valid authoritative decision_index section; MCP fails closed rather than reconstructing authority from the compatibility decisions[] snapshot.
mneme decision-mcp --memory path/to/project_memory.jsonMemory created by mneme init or mneme setup already carries an empty decision_index section and needs no migration. An older file with no decision_index section yet makes MCP stop with an error that tells you to migrate. Preview the migration first. It writes nothing and lists the visible effects: non-active decisions leave Layer 1, and legacy rule/anti_pattern items are migrated once.
mneme decision-index migrate --memory path/to/project_memory.jsonThen apply exactly that migration:
mneme decision-index migrate --memory path/to/project_memory.json --applyMigration is lossless or it refuses. There is no force or repair mode. Memory containing legacy decision metadata that the canonical index cannot represent, such as EventCatalog-imported decisions, stays on the section-less path and is not migrated.
--adr-dir is now optional validation input only. Mneme still validates and precedence-resolves that corpus before startup, but ADRs do not become a second MCP authority source.
mneme decision-mcp --memory path/to/project_memory.json --adr-dir path/to/adrsThe MCP surface is intentionally frozen to six tools:
decision.proposedecision.propose_batchdecision.getdecision.searchdecision.applicable_todecision.trace
Proposal tools create non-authoritative proposals only. Read tools query proposal and canonical decision state. MCP deliberately exposes no accept, reject, activate, supersede, exception, bypass, or trusted-evidence authority.
Human authority remains explicit through mneme decision proposals | show | accept | reject. Accepting a proposal materializes a canonical decision; it does not activate protection or run the Architecture Audit.
See ADR-027 and the v0.9.0 release notes for the authority boundary and release contract.
Architecture Audit
See where your architecture is actually protected — and where it still depends on people remembering the rules.
Mneme audits your repository and shows which architectural decisions are:
Protected — already enforced mechanically
Mneme-ready — can be turned into a deterministic guardrail
Requires modelling — important, but not yet safe to automate
Guidance — useful context, but not something that should be enforced
Run an audit:
mneme audit --memory .mneme/project_memory.json --repo-root .For a Mneme-ready decision, validate the proposed protection before enabling it:
mneme protect validate <decision-id> --memory .mneme/project_memory.jsonThen explicitly activate it:
mneme protect activate <decision-id> --memory .mneme/project_memory.jsonMneme only reports a decision as Protected after it can verify that real enforcement is in place. The full activation contract is documented in Protection Activation.
60-second enforcement example
Initialize a project-local decision corpus:
mneme initRecord one architectural decision:
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"Create a proposed input that violates it:
python -c "import pathlib; pathlib.Path('prompt.txt').write_text('Set up a new YAML config file', encoding='utf-8')"Run the deterministic check:
mneme check \
--memory .mneme/project_memory.json \
--input prompt.txt \
--query configurationIn strict mode, the 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 common enforcement surface. Agent integrations translate their native events into the same Mneme decision and enforcement model.
For a non-authoritative preview of which canonical decisions would apply to
caller-asserted context labels, add an opt-in, repeatable
--applicability-preview <label> to mneme check:
mneme check --memory .mneme/project_memory.json --input prompt.txt --query configuration --applicability-preview platform:windowsThe preview prints only on stderr, independently of the normal check
result. It does not trust the supplied labels, exclude decisions, change
enforcement, or change stdout, JSON mneme.check/v1, hook behavior, or exit
codes. Section-less memory or a preview computation error reports
PREVIEW UNAVAILABLE on stderr; it does not migrate memory or weaken
enforcement. This preview is not a security control.
Setup mode (no enforcement)
mneme setup initializes Mneme in a repository without changing how the team works: it creates or detects project memory, detects supported agent environments, and reports protection readiness — all without enabling any blocking enforcement. Setup never turns warn/observe behavior into blocking behavior; activation of preventive enforcement is always a separate, explicit decision.
mneme setupOptionally record an opaque Architecture Audit reference so the setup can be attributed back to a saved Audit baseline:
mneme setup --audit-ref <reference>Setup is idempotent: rerunning it against an existing Mneme project leaves valid configuration untouched.
How it works
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 gateMneme applies governance at the earliest reliable boundary a workflow exposes:
Before generation when architectural context can be injected into the model call.
Before supported file mutations when an agent exposes a blocking pre-tool hook.
After bypassable mutations through bounded working-tree audits where shell/script writes cannot be inspected safely before execution.
Before merge through CLI-based CI gates.
These boundaries are complementary. An integration only claims the surfaces that have been implemented and validated for that harness.
Retrieval is not enforcement
Decision retrieval answers: which architectural decisions are useful as guidance for this task?
Enforcement answers: does the proposed change violate a governed rule that applies here?
Those concerns are intentionally separated. See ADR-017, ADR-019, and ADR-020.
Supported surfaces
The authoritative support matrix lives in docs/integrations/README.md. The labels below are evidence levels, not interchangeable marketing terms.
Support level | Surface |
Native integration | Claude Code |
Native integration | Claude Agent SDK |
Native integration | Google Antigravity |
Native integration | Codex CLI |
Native integration | Kiro CLI 3.0 / v3 |
Validated compatibility | Paperclip — CLI and ACP transports, no adapter required |
Rules export | Cursor |
CLI-based CI gate | GitHub Actions, GitLab CI |
Experimental | OpenCode |
Planned | Deep Agents middleware POC |
Each integration documents its actual blocking boundary, bypass paths, degraded behavior, and validation evidence. Start with the integration matrix, not assumptions based on another harness.
ADRs and project memory
Mneme can compile architecture decisions into structured governance records rather than treating ADRs as passive prose.
The repository governance source of truth is .mneme/project_memory.json. The ADR import path preserves explicit source provenance where available so typed rules can be inspected and enforced consistently.
See:
Architecture guarantees
Three principles govern the current mechanism:
Deterministic > clever. Enforcement behavior must be reproducible.
Auditable > autonomous. A verdict should be traceable to the decision, rule, applicability state, and evidence that produced it.
Prevention before review. When a reliable pre-change boundary exists, use it; when it does not, surface the limitation and audit later rather than pretending the path is blocked.
The current Layer 1 scope, frozen surfaces, accepted amendments, experimental work, and deferred Layer 2 work are maintained in docs/architecture/current-phase.md.
Do not infer architecture from this README when a linked ADR or architecture document is more specific.
Benchmark and validation
Mneme's benchmark is a regression and integrity instrument for retrieval and enforcement behavior. It is not a general model-quality benchmark.
The benchmark keeps retrieval and enforcement scoring distinct so changes cannot silently improve one surface while regressing another.
See:
Demos
More examples: mnemehq.com/demo
Contributing
Before changing retrieval, enforcement, applicability, conflict handling, or benchmark semantics, read the architecture and ADRs that govern that surface.
Core behavioral changes may require the repository's charter-amendment procedure. Documentation, tooling, integrations, and examples do not automatically authorize changes to frozen behavior.
License
MIT. See LICENSE.
Available Tools
6 toolsdecision.applicable_toGet retrieval/context applicabilityARead-onlyIdempotent
Return proposals and canonical decisions whose scope hints or context scope overlap the supplied context/paths. This is retrieval/context applicability only: proposal scope hints are NOT typed-rule applicability (ADR-020) and paths are never glob-evaluated. Read only: this tool never mutates any state and returns no rules or enforcement data. When both inputs are omitted or empty, both match lists are empty.
Inputs: paths, context. Returns: object
decision.getGet a proposal or canonical decisionARead-onlyIdempotent
Read one record by stable id. Returns record_type 'proposal', 'canonical_decision', or 'not_found'. Read only: this tool never mutates any state. Use decision.search when you do not already have a stable id.
Inputs: record_id (required). Returns: object
decision.proposePropose a decision (non-authoritative)AIdempotent
Submit one candidate architectural decision. The proposal enters the Mneme decision index as a non-authoritative proposal with status 'proposed'. This grants NO authority: the proposal is never enforceable and can only become canonical through separate Mneme human authority (D2C), which this MCP does not expose. Repeated identical source/version/content submissions are idempotent. Use decision.propose_batch when submitting multiple candidates.
Inputs: candidate (required). Returns: object
decision.propose_batchPropose decisions in batch (non-authoritative)AIdempotent
Submit multiple candidate architectural decisions from one producer output. Each candidate receives its own independent proposal identity and enters as a non-authoritative proposal with status 'proposed'. There are no batch acceptance semantics: batch submission grants NO authority, and every proposal remains independently reviewable. Use decision.propose for a single candidate.
Inputs: candidates (required), shared_provenance. Returns: object
decision.searchSearch proposals and canonical decisionsARead-onlyIdempotent
Deterministic text/exact-metadata search. Proposals (lifecycle proposed/accepted/rejected) and canonical decisions (lifecycle active/superseded/deprecated/inactive) are returned in separate lists and never merged. Read only: this tool never mutates any state. Search rank has no enforcement meaning. Use decision.get when you already have a stable id. Within each record domain, all applicable filters combine with AND semantics; proposal-only filters do not exclude canonical results, and vice versa.
Inputs: query, producer_name, proposal_status, source_reference, +2 more. Returns: object
decision.traceTrace decision lineageARead-onlyIdempotent
Return the deterministic lineage actually known for a proposal id or canonical decision id. The result_type is explicit (proposal_trace / canonical_trace / trace_not_found); unresolved ids stay type-unknown. Read only: this tool never mutates any state. Canonical rule-lineage integrity failures fail closed as protocol errors and are never returned as partial traces. Use decision.get for the record alone; use decision.trace when you need provenance, acceptance, rule, or declared-evidence lineage.
Inputs: record_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct action-resource pair: propose/propose_batch differ only in cardinality and cross-reference each other, while get/search/applicable_to/trace are clearly separated by input type (stable id vs text vs context/path vs provenance). No two tools would be confused for the same operation.
All tools share the decision.* namespace and use short, imperative verbs (propose, get, search, trace). The two compound names (propose_batch, applicable_to) use the same underscore convention, so the naming feels systematic and predictable.
Six tools is a tight, purposeful surface for a decision index: two write paths (single/batch), three read/retrieval paths (by id, text search, context overlap), and one provenance trace. Each tool has a distinct role and none feels redundant.
The core write-once proposal plus retrieval workflow is well covered, including batch submission and lineage tracing. However, there is no way to update, withdraw, or transition a proposal's status within the MCP; this is explicitly delegated to external human authority, but agents still cannot correct or retire a mistaken proposal.
Maintenance
Related MCP Connectors
Append-only decisions with provenance, supersession, retrieval, and audited MCP actions.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Read-only Streamable HTTP MCP for Nomos corpus search, 42 DoD gates, and governance comparisons.
15Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables preserving, querying, and managing engineering decisions with reasoning and evidence through CLI, HTTP API, and MCP tools.16-
- FlicenseNot gradedqualityCmaintenanceShared project memory MCP server for storing and retrieving technical decisions, lessons learned, ADRs, and cross-links between projects.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read and update a repository's decision ledger, check which files a decision governs, find stale files after a decision reversal, and record or reverse decisions over MCP.13 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to create, list, and read numbered Markdown Architecture Decision Records, and to review designs against pluggable domain rule packs (general, insurance, banking, healthcare, agentic AI) that return PASS/FAIL/UNKNOWN verdicts with evidence. Supports custom rule packs supplied via a local directory of YAML files.MIT