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_decisionsRead

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_decisionWrite

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_queryRead

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 checkEnforce

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 generateExport

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 benchmarkMeasure

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)	Meaning
PASS	0	No violations.
WARN	1	Constraint matched. Suggests friction but not a block in `warn` mode.
FAIL	2	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.

The mneme command-line interface

Install

list_decisions

add_decision

test_query

check

cursor generate

benchmark

Exit codes

CI usage

GitHub Actions — PR diff gate

Pre-commit — local warn-mode

The `mneme` command-line interface