CLI reference

# The `mneme` command-line interface

Reference for every subcommand the OSS `mneme` CLI ships with: managing the decision corpus, querying it, enforcing it against generated content, exporting to editor surfaces, and running the governance benchmark suite. The CLI is the deterministic surface; the same operations are available programmatically.

## Install

Python 3.10+. MIT-licensed. No vector store, no ML runtime.

    $ git clone https://github.com/TheoV823/mneme
    $ cd mneme
    $ pip install -e .

After install, the `mneme` entry point is on your PATH. Every subcommand requires `--memory` pointing at a `project_memory.json` file. An example corpus ships at `examples/project_memory.json`.

## list_decisions

Print every decision in the memory file.

mneme list_decisions Read

Lists every decision in the corpus with id, summary, scope, and constraints. Read-only.

    $ mneme list_decisions --memory examples/project_memory.json

Flags

Flag | Required | Description
--- | --- | ---
--memory | yes | Path to `project_memory.json`.

## add_decision

Append a new decision to the corpus.

mneme add_decision Write

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.

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

Flags

Flag | Required | Description
--- | --- | ---
--memory | yes | Path to `project_memory.json`.
--id | yes | Stable id for the decision (e.g. `mneme_042`).
--decision | yes | Short statement of the decision.
--rationale | no | Optional free-text explanation.
--scope | no, repeatable | One or more scope tags. Pass `--scope` multiple times.
--constraint | no, repeatable | One or more constraints the decision implies.
--anti-pattern | no, repeatable | One or more patterns to flag against.

## test_query

Run a query through the retriever and show scores plus the injected context.

mneme test_query Read

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?"

Flags

Flag | Required | Description
--- | --- | ---
--memory | yes | Path to `project_memory.json`.
--query | yes | The task description / prompt context to retrieve against.
--top | no | How many top decisions to show in the injected packet. Defaults to the package default.

## check

Enforce decisions against an input file. The command at the center of the governance loop.

mneme check Enforce

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

Flags

Flag | Required | Description
--- | --- | ---
--memory | yes | Path to `project_memory.json`.
--input | yes | Path to the file to check.
--query | yes | Context query for retrieval. Determines which decisions are in scope.
--top | no | How many top decisions to retrieve. Defaults to the package default.
--mode | no | `strict` (default) or `warn`. See exit codes.

Mode semantics. `strict` exits non-zero on any violation, making it suitable as a merge gate. `warn` always exits zero, useful while a team is still shaping its decision corpus and does not want a noisy corpus to block work.

## cursor generate

Export retrieved decisions to a Cursor `.mdc` rules file.

mneme cursor generate Export

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

Flags

Flag | Required | Description
--- | --- | ---
--memory | yes | Path to `project_memory.json`.
--query | yes | Context query for retrieval.
--output | no | Output path. Defaults to `.cursor/rules/mneme.mdc`.
--top | no | How many top decisions to include.

## benchmark

Run the governance benchmark suite and report violation-detection results.

mneme benchmark Measure

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

Flags

Flag | Required | Description
--- | --- | ---
benchmarks_dir | yes (positional) | Directory containing benchmark scenario subdirectories.
--memory | yes | Path to `project_memory.json`.
--json | no | Write a JSON report to `FILE`.
--markdown | no | Write a Markdown report to `FILE`.

## Exit codes

Designed for CI gating. The codes are stable across releases.

mneme check · by mode

Verdict | strict (default) | warn | Meaning
--- | --- | --- | ---
PASS | 0 | 0 | No violations.
WARN | 1 | 0 | Constraint matched. Suggests friction but not a block in `warn` mode.
FAIL | 2 | 0 | Anti-pattern hit. In `strict` mode this is a hard fail.

mneme benchmark

Code | Meaning
--- | ---
0 | All scenarios passed.
1 | At least one scenario failed.
2 | Supplied `benchmarks_dir` is not a directory.

mneme add_decision

Code | Meaning
--- | ---
0 | Decision appended.
2 | A decision with the supplied `--id` already exists.

## CI usage

The check command is designed to live as a pre-merge governance gate. The simplest viable wiring:

### GitHub Actions — PR diff gate

Run `mneme check` against the PR diff in strict mode. Exit code 1 (WARN) or 2 (FAIL) blocks the merge.

    name: governance
    on: [pull_request]
    jobs:
      governance:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-python@v5
            with: { python-version: '3.11' }
          - run: pip install -e .
          - name: Render PR diff
            run: git diff origin/${{ github.base_ref }}...HEAD > pr.diff
          - name: Governance check
            run: |
              mneme check \
                --memory .mneme/project_memory.json \
                --input pr.diff \
                --query "${{ github.event.pull_request.title }}" \
                --mode strict

Full example wired into a working repo: /integrations/github-actions/.

### Pre-commit — local warn-mode

Run in `warn` mode locally so the developer sees friction without blocking the commit. Pair with strict-mode CI for the actual gate.

    # .git/hooks/pre-commit
    $ mneme check \
        --memory .mneme/project_memory.json \
        --input "$(git diff --cached)" \
        --query "$(git log -1 --pretty=%B)" \
        --mode warn

What it catches Governance violations → Twelve worked examples of the violations the CLI is built to detect. CI wiring GitHub Actions integration → End-to-end PR-diff governance using `mneme check`. Measurement Benchmark methodology → How the suite the `benchmark` command runs is composed and scored.