mneme-hq 0.10.0

Canonical Decision Index persistence (ADR-030 D1).

This release makes the persisted decision_index section of project_memory.json the authoritative decision record. Decisions gain immutable versions, content-derived identity, and stable rule lineage; the decisions[] array becomes a derived compatibility snapshot. Existing memory is never converted implicitly: a new command, mneme decision-index migrate, previews and then applies a one-time, lossless migration.

This release contains breaking and compatibility changes. Read Breaking and compatibility changes and Upgrading before migrating a project.

Breaking and compatibility changes

1. Lifecycle conformance: only active decisions take part in Layer 1

After migration, only active decisions take part in Layer 1. Legacy superseded, deprecated, and inactive decisions are retained canonically, but they no longer take part in:

• retrieval;
• enforcement, including their typed rules;
• ConflictDetector;
• benchmark runtime sets;
• the Architecture Audit decision set.

Architecture Audit tier percentages are unchanged. The Audit's total_decisions count and per-decision list drop those non-active entries. The migration preview lists every non-active decision that will leave Layer 1 before anything is written.

2. Rule-ID values change from positional to stable content-derived IDs

rule_id and derived_rule_ids values change from positional IDs (<decision_id>:<RULE_TYPE>:<index>) to stable content-derived IDs (<decision_id>:<RULE_TYPE>:<32 hex>). Field names and ordering are unchanged, and the two formats are never emitted together. The old positional ID is recoverable as <decision_id>:<RULE_TYPE>:<sequence>, using the new sequence field on each rule payload.

Anything that stores, compares, or pattern-matches rule IDs must expect the new value format.

3. EventCatalog canonical apply is retired

mneme eventcatalog import --apply refuses canonical memory. Because mneme init and mneme setup now create canonical memory (see item 9), the EventCatalog apply path is unavailable for every new project. EventCatalog preview remains available. Existing section-less projects may keep the legacy apply path during the compatibility window.

4. Migration limitation: EventCatalog-imported and unrepresentable metadata

Memory containing legacy EventCatalog-imported decisions, or other decisions[] metadata the canonical index cannot represent, cannot migrate in this release and stays on the section-less compatibility path. Migration is lossless or it refuses: there is no force, repair, or loss-acknowledgment option.

5. Older binaries are incompatible with migrated memory

mneme-hq 0.9.2 and earlier write decisions[] directly through legacy writers, which makes a migrated file fail to load. Do not use migrated memory with mneme-hq 0.9.2 or earlier. No in-file version marker exists, because an older binary would ignore it. Upgrade every machine, CI job, and hook that writes to a project's memory before migrating that project.

6. New command: mneme decision-index migrate

mneme decision-index migrate --memory <path> previews the migration, and adding --apply writes exactly the previewed migration (refused if the file changed after it was read). It is the only way to convert existing memory. Running it on already-migrated memory is a no-op.

7. Decision MCP requires canonical memory

mneme decision-mcp refuses to start on section-less memory and directs the user to preview, then apply, the migration. The pre-D1 startup mode that served only the proposal store is gone.

The canonical authority writers refuse section-less memory in the same way and print the same preview-then-apply guidance: mneme adr import --apply and mneme decision accept. None of them migrates implicitly.

8. Additive Decision MCP fields

• Canonical records gain version_id, decision_version_id, and content_digest.
• Rule payloads gain decision_version_id and sequence.
• source_evidence may gain source_revision and observed_at.

Existing fields are unchanged, and the six-tool inventory (decision.propose, decision.propose_batch, decision.get, decision.search, decision.applicable_to, decision.trace) is unchanged.

9. New projects are canonical

mneme init and mneme setup create memory with an empty decision_index. Existing files are never converted implicitly. mneme init --force still resets the file, now to canonical memory.

Added

• Canonical Decision Index persistence. decision_index is the authoritative decision record, with immutable decision versions, content-derived version identity, and stable rule lineage. decisions[] is re-derived from it on every canonical write and verified before every canonical write; divergence fails closed and is never repaired.
• mneme decision-index migrate (see item 6).
• Immutable ADR version evolution. On canonical memory, mneme adr import --apply --update-existing creates or reuses an immutable canonical version for a same-id decision, instead of overwriting the decisions[] entry, and supports cross-id supersession.
• Protection continuity across ADR edits. A protection rule binding that a new ADR version no longer derives is never silently dropped. New adr import options make the choice explicit: --preserve-protection RULE_ID (carry it forward after deterministic revalidation) and --release-protection RULE_ID (release it). An unrelated ADR edit that would drop such a binding fails closed.
• --expected-predecessor ADR-ID=VERSION_ID on adr import makes a retry of an earlier --update-existing apply exact: it reuses the persisted occurrence, creates it if the pinned version is still active, and otherwise fails as stale.
• Canonical writers for mneme protect activate and mneme add_decision. On canonical memory, add_decision creates a first occurrence with identity ["cli-add", <id>]; an exact retry is a no-op and it never edits an existing decision.
• mneme research open-architecture. Research-only harness for the Open Architecture (O1A) benchmark. It is not part of the decision, enforcement, or Audit surfaces.

Fixed

• mneme adr import --apply --approve-conflicts now imports every non-conflicting scope and skips each conflicting scope, as documented. Previously it wrote zero decisions whenever the corpus had an active-active tie, and reported only the first conflict.

Unchanged

• Retrieval ranking, DecisionRetriever, ConflictDetector, and typed-rule enforcement semantics are unchanged for active decisions. Real-corpus parity is pinned by tests before and after migration (runtime projection, retrieval, strict enforcement, ConflictDetector, the Architecture Audit, and the frozen benchmarks).
• mneme.audit/v1 is unchanged.
• The six Decision MCP tools, their authority annotations, and the ADR-027 authority boundary are unchanged. The internal binding_authority field is never exposed through MCP or encoded in a rule_id.

Upgrading

1. Upgrade mneme-hq to 0.10.0 everywhere that writes the project's memory (developer machines, CI, hooks) before migrating. Migrated memory must not be used with 0.9.2 or earlier (item 5).
2. Commit or back up .mneme/project_memory.json.
3. Preview the migration. Nothing is written:

bash mneme decision-index migrate --memory .mneme/project_memory.json

Review the non-active decisions leaving Layer 1 (item 1), the legacy items becoming decisions, and the migrated rule bindings. If the preview refuses, the memory contains state the canonical index cannot represent (item 4); it stays on the section-less compatibility path.

1. Apply exactly the previewed migration:

bash mneme decision-index migrate --memory .mneme/project_memory.json --apply

1. Update anything that stores or matches rule IDs (item 2), and stop using eventcatalog import --apply on the migrated project (item 3).

After migration, decisions[] is a derived compatibility snapshot, and new rule/anti_pattern items no longer synthesize decisions.

Install

:::bash
pip install "mneme-hq[mcp]==0.10.0"

Start the local stdio server (requires canonical memory):

:::bash
mneme decision-mcp