Mneme HQ — Q&A and Glossary

Mneme HQ is the decision and control layer for agentic software development, starting with architecture: it compiles your architectural decision records into a deterministic active constraint set, supplies those decisions to AI coding agents as context, and checks each proposed change against them before it is written.

pipx install "mneme-hq>=0.9.2"

Three runtime dependencies: anthropic >= 0.25.0, python-dotenv >= 1.0.0 and PyYAML >= 6.0. Python 3.11 or later. No vector database, no model server, no background service. Optional extras add the MCP server (mcp) and the LangChain and LangGraph integration (langchain). The [api] extra is still declared for compatibility and pulls in FastAPI and Uvicorn, but the historical HTTP wrapper has been separated from the active core, so do not read it as a supported endpoint.

Three steps. First, install the CLI with pipx install "mneme-hq>=0.9.2". Second, create the decision corpus: mneme init scaffolds an empty .mneme/project_memory.json. Add the three to ten architectural decisions you care most about, or import an existing ADR directory:

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

Without --apply the import is a preview and writes nothing. Third, turn on enforcement. In Claude Code, load the plugin from a Mneme checkout with claude --plugin-dir ./integrations/claude-code-plugin. In CI, run the check on each changed file:

mneme check \
  --memory .mneme/project_memory.json \
  --input src/storage/store.py \
  --query "storage layer" \
  --mode warn

Use --mode warn while the corpus settles, then drop the flag, because strict is the default. The GitHub Actions integration has a reference workflow.

No. Mneme HQ is local-first. Your .mneme/project_memory.json, your ADRs, your code and your enforcement verdicts stay in your repository. mneme check and the Claude Code hook reach a verdict without calling a model or any Mneme HQ-hosted service. The one outbound model call in the package is the built-in LLM adapter, which uses Anthropic's API and runs only when you use the demo or call Pipeline yourself.

It means a decision reaches the agent before the code exists, instead of a reviewer finding the conflict afterwards. Mneme HQ applies it at two points. Before generation, the relevant decisions are retrieved and placed in the model's context, as a context packet or as generated Cursor rules. Before a change lands, the Claude Code hook checks the proposed mutation and can block it before it is written.

Code review comes too late for this. By the time generated code reaches a pull request, the diff exists, the reviewer's attention is finite, and the rejected pattern is already in the conversation history, where a later model call can read it as accepted. The full argument is on the governance before generation concept page.

The gradual erosion of architectural decisions as code is added without enforcement. Drift is invisible in any single change but compounds over time. AI-assisted development accelerates drift because code output increases without a corresponding increase in review capacity. A team that catches 95% of architectural violations in review still ships compounding drift if AI generates five times more code than humans review.

Teams that already write ADRs or keep an architecture document, have several developers using AI coding agents on the same codebase (Claude Code, Cursor, Copilot), and care more about architectural consistency than raw generation speed. The fit is strongest in regulated industries (fintech, health, government-adjacent), open-source projects with strict scope discipline, and any team where "we already decided this six months ago" is a familiar phrase.

Enforcement is scoped to one repository at a time, so adoption starts with a single repo. Distributing policy across an organization is Layer 2 work and is not shipped.

Teams without explicit architectural decisions to enforce. Mneme HQ enforces decisions you have already written down and does not write them for you. A team that has never written down its architectural choices won't benefit until it does. The right first step for such a team is to write five to ten ADRs.

Mneme HQ covers one narrow slice of AI safety: keeping AI-generated code inside the decisions a project has recorded. It does nothing for alignment, model safety or training. The safety claim it makes is reproducibility: you can reconstruct any verdict from the decision record and the input, and no model takes part in reaching it.

The mechanism is general: Decisions and ADRs are not code-specific. The shipped integrations and the benchmark focus on code. Governing generated docs, configs or prompts is a plausible extension but is not in scope today.

The repository enforces its own decisions with Mneme HQ. Read CLAUDE.md and the freeze artifact (docs/architecture/layer1-freeze-e73ff7d.md) before opening a PR. The retriever (decision_retriever.py), the enforcer (enforcer.py), the benchmark (benchmark.py) and the benchmark fixtures are frozen: changing their behavior requires the amendment procedure in the freeze document. Docs, tooling, integrations and examples follow the normal PR process. If you need to change the repository's own .mneme/project_memory.json, put [memory] at the start of the commit message and PR title.

Yes, MIT licensed. The repository is at github.com/MnemeHQ/mneme. The mechanism, the benchmark methodology, the freeze artifact, the ADR compiler and the integrations are all in it. Commercial offerings (managed governance, hosted policy packs, an enterprise audit log) are planned for Layer 2 and are not shipped; the core stays open.

Mneme HQ ships a Claude Code plugin whose hooks run at three points in a session.

PreToolUse covers Edit, Write, MultiEdit and Bash. For the three file tools, the hook reconstructs the file as it would be after the edit and runs mneme check on the lines the edit introduces, before the proposed mutation is written. In strict mode, the default, a violation blocks the write; in warn mode it is reported and the write proceeds. Bash coverage is narrower by design: only shell mutations that can be reconstructed deterministically (today, a quoted here-document redirected to a file) are checked before the command runs. Other shell commands are not blocked in advance.

SessionStart records a baseline of the repository, and Stop checks everything that changed during the session against it. That session-delta check is what catches mutations that escaped the pre-execution gate, such as files written by an arbitrary shell command.

Install in two steps: pipx install "mneme-hq>=0.9.2" for the runtime, then load the plugin from a Mneme checkout with claude --plugin-dir ./integrations/claude-code-plugin. The plugin provides four namespaced commands (/mneme:context, /mneme:check, /mneme:record, /mneme:review) and a discovery skill. A legacy flat integration with hyphenated commands (/mneme-check and its siblings) still exists, installed by python scripts/install_claude_code.py; it needs a git clone because scripts/ is not shipped in the wheel.

Mneme HQ generates a Cursor rules file from your decision corpus:

mneme cursor generate \
  --memory .mneme/project_memory.json \
  --query "working on storage layer"

The output goes to .cursor/rules/mneme.mdc by default. Cursor reads the file as context, so this path informs the agent rather than blocking a write; pair it with mneme check in CI when you need a gate. The same corpus drives the Claude Code hook, so both agents work from one source of truth.

Not through a dedicated integration. Copilot does not expose a pre-tool-use hook comparable to Claude Code's, and Mneme HQ does not generate Copilot instruction files today. Two things do work today. mneme check in CI evaluates a change the same way whichever tool wrote it, so Copilot-authored code that contradicts a recorded decision is caught there. And the decision corpus is plain JSON that you own, so you can adapt it by hand into Copilot's custom instructions. The Copilot integration page tracks the current status.

Yes, through the Python API. MemoryStore, DecisionRetriever, ContextBuilder and Pipeline can be wired into an agent's planning or tool-use loop: build the context packet, inject it as the system prompt, run the agent step, then optionally run ConflictDetector on the output. A LangChain and LangGraph integration ships as the optional langchain extra. The historical POST /complete HTTP wrapper has been separated from the active core and is not a supported endpoint.

Yes. The Claude Code hook is one integration and the rest of the system is independent of it. Run mneme check in CI against any repository, generate Cursor rules, or call Pipeline from your own code. The built-in LLM adapter that Pipeline uses currently targets Anthropic's API. Claude Code gets the deepest integration because it exposes a hook that runs before a tool call; other agents are reached through generated rules, the Python API or the CI check.

A human-editable JSON file that holds your architectural decisions. Its canonical location is .mneme/project_memory.json. It contains three top-level arrays: items (legacy rules, anti-patterns, preferences, facts, architecture_decisions and examples, auto-migrated to Decisions at load time), examples (decision examples with task, decision and rationale), and decisions (the typed Decision schema). The file is plain JSON, so no tooling is required to edit it.

{
  "id": "mneme_storage_json",
  "decision": "Use JSON storage only",
  "rationale": "Avoid infra complexity and keep local-first.",
  "scope": ["storage", "backend"],
  "constraints": ["no postgres", "no external database"],
  "anti_patterns": ["introduce ORM", "add migration layer"]
}

Only id and decision are required. The remaining fields shape retrieval scoring and the enforcement check.

Field-weighted keyword overlap, fully deterministic. With q as the query text:

score =
    1.0 * overlap(q, decision)
  + 2.0 * overlap(q, scope)
  + 1.5 * overlap(q, constraints)
  + 1.5 * overlap(q, anti_patterns)
  + 0.5 * overlap(q, rationale)

The top N decisions by score are injected (default DEFAULT_MAX_DECISIONS = 3). Rules and anti-patterns always surface regardless of query relevance. The same query and the same memory file produce a byte-identical retrieval order on every run.

Three reasons. First, determinism: same query plus same memory must produce identical output, run to run. Embeddings drift with model updates. Second, debuggability: a keyword match is reconstructable; a vector similarity is not. Third, scope: governance corpora are small (tens to low hundreds of decisions). At that size keyword scoring finds the right decision, and embeddings would cost the reproducibility the benchmark depends on.

An Architectural Decision Record. Mneme HQ's ADR format is YAML frontmatter plus a markdown body:

---
id: ADR-001
title: Use JSON file storage
status: accepted
priority: foundational
date: 2026-01-10
scope: storage
supersedes: []
---

Body markdown follows.

status is one of proposed, accepted, deprecated or superseded. priority is foundational, normal or exception. scope is a dotted path, and an empty string means global. ADRs are the source of truth; the ADR compiler is the deterministic rule for turning them into the constraints the runtime injects.

When two ADRs cover the same scope, the compiler resolves them in a strict order: first, explicit supersedes references remove ADRs from consideration (chain-aware, including N-node chains). Second, within the same scope, higher priority wins (foundational > normal > exception). Third, same scope and same priority, newer date wins. If still ambiguous, the compiler raises ADRPrecedenceError instead of picking a winner. Broader and narrower scopes coexist; output is sorted most-specific-first.

validate_corpus collects every problem it finds before raising, so one pass surfaces every error and maintainers fix the corpus once instead of discovering problems one at a time. Checks include: required fields present, ADR id format and uniqueness, valid status and priority enum values, ISO 8601 date, scope grammar (lowercase dotted path, no leading or trailing dot), supersedes references resolving to known ADRs, and no supersession cycles (self-cycles, two-node cycles and N-node cycles are all detected).

Write a new ADR for the replacement decision and list the old ADR's id in the new ADR's supersedes array, then set the old ADR to status: superseded. If a decision is retired with no replacement, set it to status: deprecated. The compiler removes deprecated and superseded ADRs from the active constraint set automatically. The history stays in the corpus; only the active set changes. See supersession.

Three properties matter. First, specificity: the decision field should be unambiguous and falsifiable ("Use JSON file storage" beats "Be careful with storage"). Second, scope: the scope array names the modules or domains where the decision applies, and the retriever uses it to surface the decision when a relevant query comes in. Third, the constraints and anti_patterns arrays should list the terms an LLM would use when violating the decision, because these are what the conflict detector matches against. A Decision with rich anti_patterns enforces; a Decision with only decision and rationale informs but cannot block.

In the Decision schema, both are flagged by the conflict detector. The distinction is editorial: constraints describe what must be true ("REST only", "no external database"); anti_patterns describe what must not be done ("introduce ORM", "add migration layer"). Both fields contribute to retrieval scoring with weight 1.5.

strict and warn. strict is the default for both mneme check and the Claude Code hook: a WARN verdict exits 1, a FAIL verdict exits 2, and the hook blocks the proposed write. In warn mode every verdict exits 0 and violations are reported without blocking, which is useful when you adopt Mneme HQ on an existing repository and want visibility before you turn enforcement on. Set the CLI's mode with --mode and the hook's with the MNEME_HOOK_MODE environment variable.

It checks one input file against your decision corpus. You give it the memory file, the file to check (a prompt, a draft, a generated file or a diff) and a query that describes the work:

mneme check \
  --memory .mneme/project_memory.json \
  --input src/storage/store.py \
  --query "storage layer" \
  --mode strict

It retrieves the decisions relevant to the query, runs the enforcer over the input, and prints each violation with the decision that matched and the term that triggered it. Rules built on unambiguous literal terms apply across the whole corpus whatever the query says. --memory, --input and --query are all required. Add --json for a machine-readable verdict, and --target-path when the input is a diff and your rules are path-scoped. The CLI reference lists every flag and exit code.

ConflictDetector scans the LLM response (or the content a proposed edit introduces) for constraint and anti-pattern terms drawn from the injected decisions. A term is flagged when it appears with a positive recommendation signal and no negation nearby. "Do not use Postgres" is not a conflict. "Switch to Postgres" is. Each conflict carries the violated decision id, the reason, and a snippet for human review.

No. The retrieval, the injection, the conflict detection and the verdict are all deterministic. The model is in the generation loop (it's the thing being governed), but the verdict itself is reconstructable without any model call. The project's charter puts deterministic over clever. The upgrade path to a model-based judge is explicit in the code (replace two functions) and remains opt-in.

No. Mneme HQ blocks the change, and the human or the model fixes it. If the tool that enforces a decision also chose how to comply, it would become another opinionated agent that needs governing.

The Claude Code hook blocks the write and names the decision that was violated. There are two legitimate responses. If the decision still stands, change the request so the output complies. If the decision itself should change, update the record first (write a new ADR that supersedes the old one), then retry. When you are part-way through an intentional architectural change that the corpus has not caught up with, you can set MNEME_HOOK_MODE=warn temporarily. There is no per-verdict override.

Very little. Retrieval is keyword scoring over a small JSON file and conflict detection is pattern matching over the proposed change. Both run locally, with no model call and no network round trip. The slow part of an agent step is the model call itself, which Mneme HQ does not make.

The core mechanism (retrieval mechanics, enforcement semantics, benchmark methodology) is pinned at commit e73ff7d. Behavior in those modules cannot change without the amendment procedure written into the freeze artifact. The freeze exists because validation needs a stable mechanism: you cannot show that a tool prevents drift if the tool itself keeps changing.

Layer 2 covers multi-repo governance, team policy synchronization, shared policy packs, org-wide policy distribution, and deeper IDE integrations (LSP, JetBrains). All of it is out of scope for Layer 1. Layer 2 opens only after the Layer 1 exit criteria are met: evidence that Mneme HQ prevents drift on real repositories, feedback from design partners, and confirmation that the narrow starting scope is the right one. Layer 1 stays narrow on purpose.

A regression and integrity instrument, not a generalization claim. It uses canned LLM responses, fixed retrieval and rule-text matching to make every change to retrieval or enforcement visible. Each scenario is scored in two stages that are recorded independently: a retrieval score (was the expected decision retrieved?) and an enforcement verdict (was the violation caught?). The WEAK_RETRIEVAL verdict flags coincidental passes, where enforcement happened to succeed without the relevant decision being retrieved. Recall@1 is reported but never optimized against.

The benchmark code and the methodology page label the two scoring stages Layer 1 and Layer 2. That numbering is unrelated to the product phases of the same name.

It is the share of benchmark scenarios in which the relevant decision appears among the top three retrieved decisions. Three is the canonical retrieval cutoff (K): Mneme HQ injects the top three decisions and applies their multi-term rules. Unambiguous literal rules are enforced across the whole corpus regardless of the cutoff. A score below the maximum means the retriever pushed at least one scenario's critical decision below the cutoff.

Recall@1 is the metric that responds most to tuning. Optimizing for it on a small fixture set leads to overfitting: you end up with a retriever that aces the suite and fails on real corpora. Reporting it without optimizing for it keeps the number visible, so a regression shows up, without rewarding suite-specific tweaks.

Cursor Rules and CLAUDE.md are unstructured text pasted into the prompt. They have no precedence semantics, validation, conflict detection or enforcement. When two rules contradict each other, the model picks one, usually whichever appears later or sounds more confident, and nothing records what was injected or whether the output followed it. Mneme HQ replaces this with a typed schema (Decisions and ADRs), deterministic retrieval, deterministic precedence resolution, a check on each proposed change before it is written, and conflict detection on model output. You can reconstruct each step from artifacts.

RAG retrieves information so the model can answer from the right source. Mneme HQ retrieves decisions so the output stays inside a constraint, then checks that it did. RAG ranks chunks by vector similarity, so results shift with the embedding model. Mneme HQ ranks by keyword overlap, so the same query and the same memory file return the same ranking.

A linter checks syntax, style and known bug patterns in source code. Mneme HQ checks a proposed change against the architectural decisions your team recorded, before the change is written. A linter has no rule for "we decided not to rebuild retrieval on embeddings" unless someone writes one. Mneme HQ matches the constraint and anti-pattern terms listed in the decision record itself.

LLM-as-judge introduces a second model to evaluate the first model's output. The judge's verdict varies run to run and shifts with model updates. Mneme HQ's evaluator is deterministic. The upgrade path to a model judge is explicit in the code (replace two functions) but is opt-in and not the default. In Layer 1, the deterministic evaluator is canonical.