Current release, mneme-hq 0.10.0: a local stdio MCP server with exactly six Decision Index tools, introduced in 0.9.0. It reads authoritative decisions from the persisted Decision Index in project memory and records non-authoritative proposals. Human decision authority and deterministic protection remain separate surfaces.
Operator reference · mneme-hq 0.10.0
Decision context over MCP, with authority kept outside the protocol.
Use mneme decision-mcp to let an MCP host query Mneme's Decision Index or submit candidate architectural decisions. The server is local and stdio-only.
Install and run
The MCP SDK is an optional dependency. Install the released package with the extra, then start the server from the repository whose decision state you want to expose.
Before you start: the server reads decisions from project memory and will not start unless that file has an authoritative decision_index section. Projects created with mneme init or mneme setup on 0.10.0 already have one. For memory written by 0.9.x, preview the migration, review what it reports, then apply it:
Upgrade every process that writes this file to 0.10.0 before you apply, including CI jobs, hooks, and teammates’ installs. Migrated memory must not be written by 0.9.2 or earlier; see version compatibility and the migrate reference.
The process communicates over standard input and standard output. It does not expose HTTP, SSE, a hosted endpoint, authentication, RBAC, or multi-tenant infrastructure.
Option
Behavior in 0.10.0
--proposals <path>
Use a specific decision-proposals JSON file. When omitted, the durable default is .mneme/decision_proposals.json. Passing an empty string explicitly selects an in-memory proposal store.
--memory <path>
The project memory file whose decision_index section the server reads. Defaults to .mneme/project_memory.json. Every canonical read comes from this file.
--adr-dir <path>
Optional. Validate that ADR directory before startup: it must pass parse, corpus validation, and precedence resolution. There is no default. ADRs stay validation and import sources; the server never reads decisions from them.
Strict startup: the server exits with code 2 if the memory file doesn’t exist; if it has no decision_index section, in which case it prints the two mneme decision-index migrate commands to run; or if the section is invalid, for example after a 0.9.2 write (ERROR: the canonical Decision Index in … is invalid). With --adr-dir, a folder that doesn’t exist, an empty-string value, a malformed ADR, an invalid corpus, or unresolved precedence also stops startup. An existing but empty folder passes validation. Mneme does not silently serve an ambiguous canonical view.
Configure an MCP host
Mneme ships the server command, not a client-specific installer or generated config. For an MCP host that supports launching a local stdio process, use this process definition in the host's own MCP configuration format:
Add "--adr-dir", "docs/adr" only when you want startup to validate that directory as a schema-valid Mneme ADR corpus. MCP host configuration formats differ; this is the process contract, not a claim of validated support for a named client.
Storage and canonical input
Canonical decisions come from the Decision Index: the decision_index section of the project memory file passed with --memory. The server validates it once at startup, then reloads it for every canonical read, so a decision accepted with mneme decision accept is visible without restarting the server. Canonical records carry the identity of the decision version they come from: version_id, decision_version_id, and content_digest.
The proposal store is separate. By default it is the local file .mneme/decision_proposals.json, written by Mneme’s JSON proposal store and re-read before each read, so a proposal that a separate CLI process accepts or rejects shows its new status without a restart. An empty-string --proposals selects an in-memory store that only this process can see. The server never stores proposals in project memory.
--adr-dir never changes what the server reads. To bring ADR changes into the Decision Index, run mneme adr import.
The frozen six-tool surface
The tool inventory is part of the authority boundary. Version 0.9.0 introduced exactly these six names and no aliases, and 0.10.0 keeps them with unchanged input schemas. The current released 0.10.0 runtime publishes parameter descriptions and JSON Schema through MCP tools/list.
Machine-readable contract:decision-tools.json is generated from the exact released mneme-hq[mcp]==0.10.0 runtime. It includes each tool's description, input and output schema, MCP annotations, and request examples that CI validates by actually calling the released tools. It is drift-checked against tools/list, not maintained as a second hand-authored API specification.
decision.proposeWrite · proposal only
Purpose
Submit one candidate architectural decision. Identical source, version, and content submissions are idempotent.
Inputs
candidate with required non-empty title and statement; optional rationale, scope hints, architecture context, related decision IDs, and source provenance. A usable proposal requires provenance: producer name/type and source reference, with optional external ID, source version, repository locator, and origin classification.
Result
created, reused, and a proposal record containing proposal_id, proposal_status, candidate content, provenance, fingerprints, proposed time, and any accepted decision link.
Errors
Malformed or missing provenance, empty required text, unknown fields, or forbidden authority fields return a tool error.
Boundary
Creates or reuses only a proposed record. It cannot accept it, create a canonical decision, add rules, or change enforcement.
decision.propose_batchWrite · proposal only
Purpose
Submit multiple independent candidates from one producer output while preserving input order.
Inputs
Non-empty candidates list and optional shared_provenance. Candidate-level provenance takes precedence where supplied; every candidate must resolve to provenance.
Result
results contains one ordered propose result per candidate, each with its own proposal identity and created/reused outcome.
Errors
Empty batches, unresolved provenance, malformed candidates, or forbidden fields fail the call.
Boundary
No batch acceptance exists. Every returned proposal remains independently reviewable and non-authoritative.
decision.getRead only
Purpose
Retrieve one proposal, or one canonical decision from the Decision Index, by stable ID.
Inputs
Non-empty record_id.
Result
An explicit record_type of proposal, canonical_decision, or not_found. Proposal and canonical lifecycle vocabularies remain separate. A canonical decision is returned whatever its lifecycle, including superseded and deprecated ones, with its lifecycle_status.
Errors
Malformed input is a tool error. An unknown ID is successful typed data, not an error.
Boundary
Never mutates proposal, canonical, rule, evidence, or enforcement state.
decision.searchRead only
Purpose
Run deterministic text and exact-metadata search across proposals and the Decision Index.
Inputs
Optional text query; proposal status; canonical lifecycle status; producer name; source reference; and origin classification.
Result
Separate proposals and canonical_decisions lists. Search ranking has no enforcement meaning.
Errors
Invalid lifecycle or origin vocabularies and malformed fields return a tool error.
Boundary
Retrieval only. Search cannot decide applicability for a typed rule or grant authority.
decision.applicable_toRead only
Purpose
Find proposal scope hints and canonical context scopes that overlap supplied context or paths.
Inputs
Optional context and paths string lists.
Result
proposal_hint_matches plus slim canonical_scope_matches containing identity, statement, lifecycle, and context scope.
Errors
Malformed argument types return a tool error.
Boundary
Scope hints are retrieval context, not rule applicability. Paths are not glob-evaluated, and the result contains no rules or enforcement state.
decision.traceRead only · fail closed
Purpose
Return the lineage actually known for a proposal or canonical decision.
Inputs
Non-empty record_id.
Result
Explicit result_type: proposal_trace, canonical_trace, or trace_not_found. Missing links are named rather than invented.
Errors
Malformed input is a tool error. Canonical rule-lineage integrity failure aborts the call with JSON-RPC internal error -32603; no partial trace is returned.
Boundary
Trace reports proposal, canonical, rule, and declared-evidence links where they exist. It cannot create or repair any link.
Errors and fail-closed behavior
Unknown IDs are returned as typed not_found or trace_not_found results.
Invalid inputs return MCP tool errors so the caller can correct the request.
Authority-shaped input such as producer-supplied status, proposal IDs, timestamps, canonical lifecycle, typed rules, trusted evidence, or enforcement state is rejected, not ignored.
Canonical integrity failures abort the protocol call. A missing or unmigrated Decision Index, or an invalid --adr-dir corpus, prevents server startup.
Tool results do not serialize stack traces.
MCP is not the authority surface
MCP may submit a candidate and read the state Mneme exposes. It cannot accept, reject, activate, supersede, create an exception, install a typed rule, submit trusted evidence, or bypass review. Those operations are deliberately absent from the registered tool list.
Human authority stays in the CLI. Review proposals with mneme decision proposals and mneme decision show, then use mneme decision accept or mneme decision reject. See the decision proposal workflow.
Acceptance writes a new canonical decision version into the Decision Index in project memory. It still does not install deterministic protection or run the Architecture Audit. Retrieval, authority, Audit, and enforcement remain distinct.
Downstream governance consumers
A downstream system does not need to adopt Mneme's data model, storage, or workflow to use the Decision Index. A consumer that can launch the local mneme decision-mcp process calls decision.applicable_to for a proposed change, receives the governing decisions with provenance, and folds that into whatever review, risk-scoring, or triage logic it already runs. This requires local stdio access; there is no hosted endpoint a remote service could call.
Change proposed (PR, agent patch, generated diff)
|
v
Consumer calls decision.applicable_to(...)
|
v
Mneme returns applicable decisions + provenance
|
v
Consumer performs its own review, risk scoring,
prioritization, or workflow routing
This is the boundary the MCP server is built for: a stable protocol surface for exchanging decision context, not a shared implementation. See the integration overview for how this boundary is intended to compose with review and change-management tooling.
Version compatibility
Mixed versions: once memory is migrated, every process that writes it must run 0.10.0 or later. A 0.9.2 or earlier writer, such as add_decision in an old CI image, succeeds without an error. The next 0.10.0 mneme check or test_query on that file then fails with DecisionIndexPersistenceError, because the decisions[] compatibility snapshot no longer matches the Decision Index. The MCP server then refuses to start, and decision-index migrate won’t repair the file: restore it from version control and redo the change with 0.10.0.
Memory that can’t migrate: migration is lossless or it refuses, and it writes nothing when it refuses. A decision whose source is a free-text note, or points at something other than an ADR file (such as an EventCatalog import), has no representation in the index. Memory that contains one stays unmigrated, and the MCP server can’t start on it. To keep the decision, write it as an ADR file, remove its row from decisions[], migrate, then import the ADR; adr import --apply itself needs migrated memory.
The server does not watch files. It re-reads the Decision Index and the proposal file when a tool reads them.
For the wider protocol boundary, see Mneme's standards landscape. MCP provides interoperability; it does not define Mneme's governance semantics.