The mneme command-line interface

$ pipx install "mneme-hq==0.10.0"
# Include the optional MCP runtime:
$ pipx install "mneme-hq[mcp]==0.10.0"

Installs the mneme entry point on your PATH. Scaffold a new corpus with mneme init; every other subcommand requires --memory pointing at a project_memory.json file. An example corpus ships at examples/project_memory.json.

From source (contributors): git clone https://github.com/MnemeHQ/mneme && cd mneme && pip install -e .

Creates the memory file (including its parent directory) containing a valid, empty decision corpus — deliberately zero seeded decisions, because every recorded decision is enforceable and sample content would create phantom rules. Exits non-zero without writing if the target file already exists, unless --force is supplied. On 0.10.0 the new file already holds an authoritative decision_index section, so it needs no migration.

$ mneme init
Created .mneme/project_memory.json

Adds an authoritative decision_index section to project_memory.json. The index holds each decision, its immutable versions, and its rule bindings; the existing decisions[] array becomes a compatibility snapshot derived from it. The command changes only that one file. The MCP server, mneme decision accept, and mneme adr import --apply need migrated memory and exit 2 without it. mneme check, test_query, list_decisions, and the adr import preview work with either.

$ mneme decision-index migrate --memory .mneme/project_memory.json
Decision Index migration preview: .mneme/project_memory.json
  Native decisions:                2
  Active after migration:          2
  Non-active leaving Layer 1:      1
    ADR-000 (superseded)
  Legacy items becoming decisions: 1
    rule-001
  Migrated rule bindings:          0
  ...
Preview only; nothing was written. Re-run with --apply to write exactly this migration.

$ mneme decision-index migrate --memory .mneme/project_memory.json --apply
Migrated .mneme/project_memory.json: decision_index is now authoritative.

• Lossless or it refuses. If any decision can’t be represented in the index, it prints ERROR: migration refused: …, exits 2, and writes nothing. Decisions added with add_decision or imported from ADR files migrate. A decision whose source is a free-text note, or points at something other than an ADR file (such as an EventCatalog import, source.type: "eventcatalog"), can’t be represented, so migration refuses. Because adr import --apply also needs migrated memory, keep such a decision this way: write it as an ADR file, remove its row from decisions[], migrate, then import the ADR.
• Safe to re-run. On migrated memory it prints Already migrated: decision_index is authoritative and valid; nothing to do. and leaves the file byte-identical.
• No lost updates. --apply refuses if the file changed after it was read.
• Superseded decisions stop being enforced. Decisions marked superseded, deprecated, or inactive move out of decisions[] but stay in the index with their lifecycle. Before migration, mneme check still loaded such a row; after it, only active decisions are retrieved and enforced. The preview lists them under “Non-active leaving Layer 1”.

Lists every decision in the corpus with id, summary, scope, and constraints. On migrated memory it lists active decisions only. Read-only.

$ mneme list_decisions --memory examples/project_memory.json

Writes a new decision directly to the JSON file. The Pipeline runtime is never mutated — this is a file operation only. Fails with exit code 2 if the id already exists. On migrated memory it creates the first version of a decision only: an identical retry writes nothing and exits 0, and the same id with different content exits 2. To change a decision, edit its ADR and run adr import --update-existing.

$ mneme add_decision --memory examples/project_memory.json \
    --id mneme_042 \
    --decision "Use JSON storage" \
    --scope storage \
    --constraint "no postgres" \
    --anti-pattern "sqlalchemy"

Useful for debugging which decisions are surfaced for a given task description before you wire enforcement into a workflow. Prints every decision ranked by score, plus the top-N context packet that would actually be injected.

$ mneme test_query --memory examples/project_memory.json \
    --query "should I add postgres?"

Reads an input file (a prompt, a generated diff, a draft), retrieves the relevant decisions for --query, and runs the enforcer. Prints any violations and exits with a code that reflects the verdict.

$ mneme check --memory examples/project_memory.json \
    --input draft.md \
    --query "working on storage layer" \
    --mode strict

Classifies every active decision in the corpus — Protected, Mneme-ready, Requires modelling, or Guidance — and reports the protection summary and per-decision detail. This is the classification surface mneme protect consumes; the tiers are frozen P1.2 semantics that activation never reinterprets.

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

Creates project state in setup mode: context and non-blocking checks only — never enforcement. Enabling protection is always a separate, explicit decision (mneme protect activate). Optionally records an opaque Architecture Audit setup reference, taken verbatim and resolved by Audit pairing. Run it inside a git repository; outside one it exits 2. Memory it creates is already migrated to the Decision Index.

$ mneme setup --memory .mneme/project_memory.json

Lists decisions that are active, currently unprotected, and canonically Mneme-ready. Already-Protected, Requires-modelling, Guidance, and superseded decisions are never candidates, and no model decides eligibility — the audit's frozen classification decides it.

$ mneme protect list --memory .mneme/project_memory.json

Shows one decision's canonical tier, guardrail, evidence, and whether the activation rule is installed — all derived from the repository, never stored.

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

Deterministically validates a decision's proposed protection against the existing enforcement engine — without writing anything and without enabling protection. Four checks: prohibited input detected as a typed FAIL; permitted input not blocked; path applicability respected (canonical policy sources exempt); unrelated paths unaffected.

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

Activation is an explicit user action — the only command that installs enforcement. It appends the typed FORBID_LITERAL rule to that one decision's record in project memory (idempotent; refuses on any unsafe or unsupported state), then re-loads from disk and re-runs the canonical assessment. Only an independently observed Protected tier is reported as verified.

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

Starts the local server. It reads canonical decisions from the Decision Index in --memory and stores proposals in --proposals. It exits with code 2 if the memory file is missing or not yet migrated; run decision-index migrate first. The server exposes proposal and read tools only; no MCP authority operation exists.

$ mneme decision-mcp
$ mneme decision-mcp --proposals .mneme/decision_proposals.json \
    --memory .mneme/project_memory.json --adr-dir docs/adr

Requires mneme-hq[mcp]. Full tool, storage, error, and authority reference: MCP server.

$ mneme decision proposals
$ mneme decision show <proposal-id>
$ mneme decision accept <proposal-id> --memory .mneme/project_memory.json
$ mneme decision reject <proposal-id>

proposals and show are read-only. accept writes a canonical decision version into the Decision Index, which needs migrated memory; it does not run Audit or activate protection. reject makes no project-memory change. All four default to .mneme/decision_proposals.json; accept also accepts --decision-id.

Full lifecycle, provenance, flags, exit codes, and what changed in 0.10.0: Decision proposals.

Generates a Cursor-compatible rules file scoped to the supplied query. Writes the corpus into a format the Cursor agent reads directly, so the same decisions are surfaced to the IDE agent as to the rest of the toolchain. See the Cursor integration page for end-to-end setup.

$ mneme cursor generate --memory examples/project_memory.json \
    --query "working on storage layer" \
    --output .cursor/rules/mneme.mdc

Runs every scenario in the supplied directory against the decision corpus and prints a terminal report. Optional --json and --markdown flags emit machine- and human-readable reports for CI artifacts. Scenario categories map onto the governance violation hierarchy; the benchmark methodology is documented at /benchmark/.

$ mneme benchmark examples/benchmarks/ \
    --memory examples/project_memory.json \
    --json reports/bench.json \
    --markdown reports/bench.md

Parses every ADR markdown file in a directory (YAML frontmatter required), validates the corpus, resolves precedence, and writes compiled decisions into the target memory. Runs as a preview by default; nothing is written until --apply. Full walkthrough: ADR import guide. Step by step: Turn an ADR into an enforceable decision.

$ mneme adr import docs/adr \
    --memory .mneme/project_memory.json \
    --dry-run
$ mneme adr import docs/adr \
    --memory .mneme/project_memory.json \
    --apply

Protected rules can’t be dropped silently. If an edited ADR would drop a rule binding installed by mneme protect activate, or any binding carried over by decision-index migrate (authority legacy_unknown), --update-existing exits 2 instead of removing it; choose --preserve-protection or --release-protection for each rule it names. After migrating 0.9.x memory, that includes any rule you change or remove in an ADR. Rules first derived from an ADR on 0.10.0 follow the ADR. adr import --apply needs migrated memory; the preview doesn’t. On migrated memory, rule ids take the form <decision_id>:<TYPE>:<32 hex>, derived from the rule’s value and applicability rather than its position. A superseded ADR is recorded in the Decision Index with its lifecycle but is not enforced.