How Mneme works, precisely
Technical deep dives into the enforcement path: retrieval scoring, rule evaluation, decision memory, and the design choices behind them. Enforcement is deterministic, with no embeddings or model judgment in the verdict path.
An autonomous agent system is not one layer. Models produce candidate output. Harnesses coordinate execution, retries, and tool use. Execution systems maintain long-running loops, sessions, and memory. Governance infrastructure defines and enforces the architectural constraints the output must satisfy. Verification confirms the resulting system still passes its objective checks. Mneme operates in the governance infrastructure layer as the decision and control layer. It stays logically separate from harnesses and execution systems and connects to them at supported mutation, model-middleware, and CI boundaries.
Harnesses coordinate execution; governance defines constraints; verification enforces invariants. None of those layers can do the others' jobs. The argument in full: Harness Engineering Still Needs Governance. The concept page that anchors this stack: Governance Infrastructure.
Layer 4 above answers what has been decided and whether it applies. A separate class of tooling — code review, PR prioritization, change-management systems — answers what changed and whether it is safe to ship. Both are necessary. Neither can do the other's job.
Decision plane · Mneme
- What architecture has been decided?
- Which decision applies here?
- Is it authoritative?
- What constraint follows?
- Can this action proceed?
Change plane · review & change management
- What changed?
- Is the implementation correct?
- What risk does it introduce?
- Which PR deserves attention?
- Is it ready to merge?
The two planes compose over MCP rather than merge: a change-management system could ask Mneme's Decision Index which decisions govern a proposed change, while keeping full ownership of review, risk scoring, and merge readiness. MCP is the interoperability boundary that would make that composition possible; the local Decision MCP server, introduced in 0.9.0, runs as a stdio process. See the MCP integration overview for how that boundary is defined.
mneme check loads project_memory.json, scores each decision against the query with fixed field weights, resolves which rules apply to the target path, and evaluates the proposed content. It returns PASS, WARN, or FAIL and makes no model call. Typed literal rules and single-term rules run against the whole decision corpus. The top three ranked decisions also have their multi-term rules checked. If Mneme cannot resolve path applicability for a scoped rule, the run reports INCOMPLETE, an operational state that sits outside the three policy verdicts. Same query, same content, same memory file, same result.
The DecisionRetriever walkthrough: tokenization, field weights (decision ×1.0, scope ×2.0, constraints ×1.5, anti-patterns ×1.5, rationale ×0.5), ranking and tie order, the two enforcement tiers, and the three reasons Mneme uses no embeddings.
→The three-tier model — documentation (prose, wikis, ADR bodies), prompt memory (CLAUDE.md, rules files, RAG injection), and decision memory (typed schema with scope, status, precedence, constraint fields). Why documentation retrieval ends in suggestion. Why decision memory enables enforcement.
→Architectural Governance, Deterministic Enforcement, Architectural Compiler, Decision Continuity, and more across the concepts index. Systems-level explanations of why each concept exists in AI-native software delivery.
Read the source
DecisionRetriever, MemoryStore, ContextBuilder, and the benchmark harness are all open source under MIT.