# Mneme HQ
**Mneme is an open decision and control layer for agentic software development.**
It turns durable engineering decisions into agent context, deterministic enforcement, and inspectable enforcement results across AI coding agents, repositories, and CI workflows. Architecture is the first supported decision domain: **Mneme prevents architectural drift** by turning architectural decisions and ADRs into deterministic guardrails across coding agents, repository mutations, generated rules, and CI gates.
[](https://github.com/MnemeHQ/mneme/actions/workflows/tests.yml)
[](https://pypi.org/project/mneme-hq/)
[](https://pypi.org/project/mneme-hq/)
[](LICENSE)
> **Where is your architecture actually enforced?** Run the [Architecture Audit](#architecture-audit) to see which decisions are protected, which can become deterministic guardrails, and which still depend on someone remembering the rules. [Try it →](https://mnemehq.com/audit/)
Mneme is the decision layer behind that drift-prevention mechanism. It keeps recorded engineering decisions active as AI coding systems propose and modify code, instead of leaving ADRs as passive documentation.
Solid surfaces ship today; dashed surfaces are planned. Support levels per integration: [integrations matrix](https://mnemehq.com/integrations/).
> **Current phase:** Layer 1 validation. Retrieval, enforcement, and benchmark semantics are governed by the accepted architecture and freeze record. See [Current Phase](docs/architecture/current-phase.md) before changing core behavior.
## What Mneme does
Mneme separates architectural guidance from deterministic enforcement:
- **Records architectural decisions** in a structured, auditable decision corpus.
- **Retrieves relevant decisions** when an agent or model needs architectural guidance.
- **Enforces governed rules deterministically** under explicit applicability semantics.
- **Integrates at the earliest reliable boundary** exposed by each coding workflow.
- **Audits bypassable mutation paths** where pre-change blocking is not technically available.
- **Runs in CI** as a final deterministic gate before incompatible changes are accepted.
The same input and governed decision state produce the same enforcement result. Mneme does not depend on an LLM judge for its core allow/warn/fail decisions.
Mneme is not a general-purpose vector store, conversational memory system, autonomous coding agent, or deployment observability platform.
## Install
Requires Python 3.11+.
```bash
pip install mneme-hq
```
Verify the CLI:
```bash
mneme --help
```
For repository development:
```bash
git clone https://github.com/MnemeHQ/mneme.git
cd mneme
pip install -e ".[dev]"
```
## Decision MCP
Mneme exposes the Decision Index over a local MCP server so MCP-capable clients can propose candidate architectural decisions and query decision state without gaining authority to change that state.
Install the optional MCP dependency:
```bash
pip install "mneme-hq[mcp]"
```
Start the local stdio server. Canonical reads come from the persisted Decision Index in `.mneme/project_memory.json` by default; the proposal store remains separate.
```bash
mneme decision-mcp
```
Use `--memory` to select another project memory file. The file must contain a valid authoritative `decision_index` section; MCP fails closed rather than reconstructing authority from the compatibility `decisions[]` snapshot.
```bash
mneme decision-mcp --memory path/to/project_memory.json
```
Memory created by `mneme init` or `mneme setup` already carries an empty `decision_index` section and needs no migration. An older file with no `decision_index` section yet makes MCP stop with an error that tells you to migrate. Preview the migration first. It writes nothing and lists the visible effects: non-active decisions leave Layer 1, and legacy `rule`/`anti_pattern` items are migrated once.
```bash
mneme decision-index migrate --memory path/to/project_memory.json
```
Then apply exactly that migration:
```bash
mneme decision-index migrate --memory path/to/project_memory.json --apply
```
Migration is lossless or it refuses. There is no force or repair mode. Memory containing legacy decision metadata that the canonical index cannot represent, such as EventCatalog-imported decisions, stays on the section-less path and is not migrated.
`--adr-dir` is now optional validation input only. Mneme still validates and precedence-resolves that corpus before startup, but ADRs do not become a second MCP authority source.
```bash
mneme decision-mcp --memory path/to/project_memory.json --adr-dir path/to/adrs
```
The MCP surface is intentionally frozen to six tools:
- `decision.propose`
- `decision.propose_batch`
- `decision.get`
- `decision.search`
- `decision.applicable_to`
- `decision.trace`
Proposal tools create non-authoritative proposals only. Read tools query proposal and canonical decision state. MCP deliberately exposes no accept, reject, activate, supersede, exception, bypass, or trusted-evidence authority.
Human authority remains explicit through `mneme decision proposals | show | accept | reject`. Accepting a proposal materializes a canonical decision; it does not activate protection or run the Architecture Audit.
See [ADR-027](docs/adr/ADR-027-decision-mcp-proposal-ingestion-and-authority-boundary.md) and the [v0.9.0 release notes](docs/releases/v0.9.0.md) for the authority boundary and release contract.
## Architecture Audit
See where your architecture is actually protected — and where it still depends on people remembering the rules.
Mneme audits your repository and shows which architectural decisions are:
- **Protected** — already enforced mechanically
- **Mneme-ready** — can be turned into a deterministic guardrail
- **Requires modelling** — important, but not yet safe to automate
- **Guidance** — useful context, but not something that should be enforced
Run an audit:
```bash
mneme audit --memory .mneme/project_memory.json --repo-root .
```
For a Mneme-ready decision, validate the proposed protection before enabling it:
```bash
mneme protect validate --memory .mneme/project_memory.json
```
Then explicitly activate it:
```bash
mneme protect activate --memory .mneme/project_memory.json
```
Mneme only reports a decision as **Protected** after it can verify that real enforcement is in place. The full activation contract is documented in [Protection Activation](docs/protect-activation.md).
[Try the Architecture Audit →](https://mnemehq.com/audit/)
## 60-second enforcement example
Initialize a project-local decision corpus:
```bash
mneme init
```
Record one architectural decision:
```bash
mneme add_decision \
--memory .mneme/project_memory.json \
--id config-format \
--decision "Use JSON for configuration files" \
--scope config \
--constraint "Use JSON only" \
--anti-pattern "Do not use YAML"
```
Create a proposed input that violates it:
```bash
python -c "import pathlib; pathlib.Path('prompt.txt').write_text('Set up a new YAML config file', encoding='utf-8')"
```
Run the deterministic check:
```bash
mneme check \
--memory .mneme/project_memory.json \
--input prompt.txt \
--query configuration
```
In strict mode, the prohibited YAML proposal returns a `FAIL` verdict and exit code `2`. A compliant JSON proposal returns `PASS` and exit code `0`.
The CLI is the common enforcement surface. Agent integrations translate their native events into the same Mneme decision and enforcement model.
For a **non-authoritative** preview of which canonical decisions would apply to
caller-asserted context labels, add an opt-in, repeatable
`--applicability-preview