Demo · Scenario 1 of 3 5 min read PASS

Storage decision enforcement

An AI coding agent is asked to refactor a storage backend "for scalability." Without governance it proposes a Postgres migration. With Mneme, ADR-001 is injected before generation and the agent extends the existing JSON storage module instead. Same prompt, same model, different answer.

By Theo Valmis · · All scenarios

The scenario

The codebase is a single-binary Python service that uses a flat-file JSON store for all persistence. This is a deliberate choice, not an accident. ADR-001 records it explicitly:

ADR-001 · JSON storage only, no external database. The service runs on edge hardware where shipping a separate database is operationally unacceptable. Postgres, Redis, and SQLite are all out of scope until the product crosses a usage threshold defined in ADR-005.

An engineer opens Claude Code or Cursor and types the prompt that any team will eventually type:

prompt
> Refactor the storage backend for scalability.

Without Mneme

The model has no project context. It pattern-matches the request against everything it has seen during training, where "refactor for scalability" almost always means a database migration. The output is fluent and confident:

without mneme
I recommend migrating to a distributed database
architecture. Consider replacing JSON storage with
PostgreSQL or Redis. Add a migration layer and ORM
for long-term scalability.

Three architectural decisions are silently violated: ADR-001 (no external DB), ADR-003 (no ORM in v1), and ADR-005 (extend before rebuild). The diff that follows would survive review only if a reviewer happened to remember all three. At AI-assisted velocity, that is not a reliable filter.

With Mneme

Mneme intercepts the same prompt before generation. The retriever scores the prompt against project_memory.json and surfaces the relevant decision records into the model's context:

with mneme
Injecting project decisions...
↳ ADR-001: JSON storage only — no external DB
↳ ADR-003: No ORM in v1
↳ ADR-005: Extend before rebuild

Storage decision enforced. Per ADR-001, JSON
storage is locked — no Postgres, no Redis, no
ORM in v1. Extend the current storage module
instead.

The model is the same. The prompt is the same. Only the context changed. The output now respects the project's architectural truth.

What mneme check returns

If the engineer commits the change anyway, the post-generation enforcement layer runs mneme check --mode strict against the diff and emits a structured verdict. For this scenario, the storage check returns PASS:

mneme check · storage row
PASS
Storage decision enforced — JSON only, no new databases.

The verdict is structured (PASS / WARN / FAIL with the originating decision ID), so it can gate pull requests, feed dashboards, or block deploys via the GitHub Actions enforcement gate.

How to wire this up in your repo

Three lines of setup:

pip install mneme && mneme init && mneme check

mneme init seeds project_memory.json with placeholder ADRs. Replace them with your own decisions. The Claude Code hook picks up the file automatically; the Cursor integration exports the same corpus into .cursor/rules/ so your editor session sees identical constraints.

For the architectural argument behind a single tool-agnostic decision store, see architectural governance across heterogeneous AI coding agents. For how Mneme aligns with NIST CAISI, MCP, and AGENTS.md, see the standards landscape.

FAQ

What is ADR-001 in this scenario?
A project decision record stating that the codebase uses JSON file storage only — no external database, no migration to PostgreSQL, Redis, or similar. The decision is stored in project_memory.json and surfaced to any AI coding agent that asks Mneme for relevant constraints before generating code. ADRs are first-class records, not paragraphs in a CLAUDE.md.
Why does the same model give a different answer with Mneme?
Without Mneme, the model relies on training-data priors that say "JSON storage at scale should migrate to a real database." With Mneme, the model receives ADR-001 in its context window before generating, so it proposes extending the existing storage module instead of replacing it. The model itself is unchanged; the context is enforced. See why prompt memory fails at scale for the broader pattern.
Does this work in CI as well as the editor?
Yes. The same decision corpus drives interactive coding sessions through Claude Code or Cursor and the GitHub Actions enforcement gate that runs mneme check on every pull request. A diff that contradicts ADR-001 would be flagged in CI even if it slipped past the editor-time hook.
← All demo scenarios