mneme-hq 0.5.0

v0.5.0 — Directory-ready Claude Code plugin + mneme init

The repository now ships a directory-ready Claude Code plugin, and a
one-command project scaffolder.

This is the first minor release since v0.4.0 (the architectural-compiler
foundation). It adds two new backwards-compatible, user-facing capabilities and
realigns the published PyPI package with the hook-reliability fixes that were
tagged on GitHub but never reached PyPI.

---

What's new

mneme init

mneme init                     # writes .mneme/project_memory.json
mneme init --path ./mem.json   # custom location
mneme init --force             # overwrite an existing file

Scaffolds a valid, empty, neutral project_memory.json — a minimal skeleton
(meta + empty items / examples / decisions) that round-trips through
MemoryStore.load() and passes mneme check with nothing to enforce. No seeded
decisions: every decision is enforceable, so sample content would create phantom
rules. Refuses to overwrite unless --force is given.

Directory-ready Claude Code plugin

integrations/claude-code-plugin/ bundles the enforcement hook, the mneme
skill, and four namespaced slash commands (/mneme:context, /mneme:check,
/mneme:record, /mneme:review) into a single plugin directory that Claude
Code can load with --plugin-dir (or via a marketplace). The manifest declares
plugin version 0.1.0 — correct for this first directory release, and
versioned independently of the mneme-hq package — and a mode userConfig
option (strict | warn, default strict). The plugin has not yet been
publicly submitted to a marketplace.

The plugin and the package are distinct artifacts. The mneme-hq PyPI package
provides the mneme and mneme-hook runtime commands; the plugin drives
those commands and expects them already on PATH. Installing the PyPI package
does not install or enable the plugin, and loading the plugin does not
install the package.

The plugin registers a PreToolUse hook on Edit|Write|MultiEdit using Claude
Code's exec form — the bare console script, no shell:

{ "type": "command", "command": "mneme-hook", "args": [], "timeout": 30 }

No shell string, no wrapper script, no interpreter probing. Claude Code resolves
mneme-hook on PATH and spawns it directly, so the hook is
platform-independent by construction.

Enforcement-mode resolution

The Claude Code adapter resolves the enforcement mode with a fixed precedence:

MNEME_HOOK_MODE  >  CLAUDE_PLUGIN_OPTION_MODE  >  strict

The plugin's mode userConfig value reaches the hook subprocess as
CLAUDE_PLUGIN_OPTION_MODE; an explicit MNEME_HOOK_MODE overrides it. An
unrecognized value in either variable falls back to strict, so a typo can
never silently disable enforcement — and a set-but-invalid explicit override
does not fall through to the plugin option. Mode resolution stays inside the
adapter (resolve_mode() in mneme/integrations/claude_code/hook.py).

---

Fixed: PyPI metadata realignment

v0.4.1 and v0.4.2 fixed the Claude Code hook (PATH lookup + exit-code
propagation) and were tagged on GitHub — but the fixes never reached the
published PyPI package metadata. Before v0.5.0, PyPI served only 0.4.0,
which has the exit-code propagation bug: a failed check could exit 0 and let a
violating edit through in strict mode.

Publishing 0.5.0 makes pip install mneme-hq deliver the reliable hook for
the first time. The underlying fixes it carries forward:

• mneme/__main__.py so python -m mneme dispatches and sys.exit(main())
  propagates CLI exit codes (v0.4.2).
• Hook subprocess uses [sys.executable, "-m", "mneme", ...] instead of a bare
  mneme, so a missing Scripts directory on PATH (Windows Microsoft Store
  Python) no longer makes the hook fail open silently (v0.4.1).

---

Why 0.5.0 (not 0.4.3)

The repository's demonstrated versioning is Semantic Versioning under a 0.x
series: new backwards-compatible capabilities take a minor bump, pure fixes
take a patch bump.

• v0.4.0 introduced a new capability (the ADR compiler) and took a minor bump.
• v0.4.1 and v0.4.2 were pure hook fixes and took patch bumps.
• The v0.4.0 release notes' own roadmap table reserves v0.5 for the next
  feature milestone.

v0.5.0 adds two new user-facing capabilities (mneme init, the directory-ready
plugin) plus plugin mode configuration — new functionality, backwards
compatible — so it is a minor release, not a patch.

---

Tests and compatibility

• tests/test_cli_init.py — 6 tests for the scaffolder.
• tests/integrations/claude_code/test_plugin_contract.py — deterministic,
  shell-free plugin manifest + hook-wiring contract.
• tests/integrations/claude_code/test_hook_mode.py — mode precedence + strict
  fallback.
• tests/integrations/claude_code/test_hook_e2e.py — compliant/violating Write
  and Edit against the real mneme check binary (skipped without mneme on
  PATH).
• tests/test_packaging_contract.py — both console scripts present in
  [project.scripts] and (when built) in the wheel.
• No regressions. DecisionRetriever, ConflictDetector, retrieval, and
  enforcement semantics are unchanged.

---

Migration

None required. Both new capabilities are additive:

• Existing project_memory.json workflows are unchanged; mneme init only
  helps you create a new one.
• The flat integrations/claude-code/ integration still works; the plugin is a
  plugin-directory form of it (loaded via --plugin-dir), not a replacement.

---

Publishing

This release note accompanies the release-alignment change. The package is
not published by that change. The exact manual PyPI publication procedure
and the post-merge checklist live in
docs/releases/RELEASING.md. The plugin README's install
workaround stays in place until mneme-hq >= 0.5.0 is actually live on PyPI.

---

Strategic framing

Version	Theme
v0.3	Enforcement / governance checks
v0.4	Architectural compiler foundation
v0.5	Distribution: directory-ready plugin, project scaffolding, reliable published hook

v0.4.2 — Fix module execution and exit propagation

Completes the Claude Code hook reliability fix introduced in v0.4.1.

Changes:

• Added mneme/__main__.py so python -m mneme works correctly
• sys.exit(main()) propagates CLI exit codes through the module entrypoint

Why this matters:
The Claude Code hook (added in v0.3.2) now invokes Mneme via sys.executable -m mneme (fixed in v0.4.1). Without a proper __main__.py, python -m mneme check could exit 0 regardless of verdict — allowing violating edits through even in strict mode.

Impact:

• Hook enforcement now blocks writes correctly on FAIL
• Completes cross-platform reliability for Claude Code integration

Upgrade: pip install --upgrade mneme

v0.4.1 — Fix Claude Code hook PATH handling

Patch fix for the Claude Code hook on Windows (Microsoft Store Python).

Problem: mneme-hook.exe could launch successfully while the Python Scripts directory was not on PATH, causing the inner mneme check subprocess to fail with FileNotFoundError and the hook to silently fail open — edits were allowed through without being checked.

Fix: Replace ["mneme", "check", ...] with [sys.executable, "-m", "mneme", "check", ...]. sys.executable is the same interpreter that is running the hook, which always has mneme installed, regardless of PATH.

Regression test added: test_subprocess_uses_sys_executable_not_bare_mneme

Upgrade: pip install --upgrade mneme

v0.4.0 — Architectural Compiler Foundation

v0.4.0 — Architectural Compiler Foundation

Mneme is now the architectural compiler for AI-assisted development.

ADRs become the source of truth; the compiler is the deterministic rule
for turning them into the constraints the runtime injects.

---

What's new

ADR corpus  ->  parse  ->  validate  ->  resolve precedence
            ->  active constraint set  ->  Decision records  ->  runtime

• mneme/adr_schema.py — ADR dataclass, ADRStatus /
  ADRPriority enums, typed errors (ADRParseError,
  ADRValidationError, ADRPrecedenceError).
• mneme/adr_parser.py — parse_adr_file,
  parse_adr_directory. YAML frontmatter parser; structural failures
  only (missing / unterminated / malformed frontmatter).
• mneme/adr_compiler.py — three public stages plus an
  orchestrator and a Decision bridge:
  • validate_corpus(adrs) — aggregates required-field, enum, id /
    date / scope grammar, supersedes reference resolution, and
    cycle-detection errors into a single ADRValidationError. One
    pass, every error.
  • resolve_precedence(adrs) — returns the active constraint set:
    status filter → explicit supersedes (chain-aware) → same-scope
    priority → newer date → ADRPrecedenceError if still ambiguous.
    The compiler never silently picks a winner.
  • compile_adrs(adr_dir) — end-to-end: parse → validate →
    precedence; output ordered most-specific-first.
  • adrs_to_decisions(adrs) — bridge into the existing Decision
    schema so the v0.3.x runtime pipeline (DecisionRetriever,
    ConflictDetector, ContextBuilder) consumes ADR-driven corpora
    without code changes.

ADR frontmatter

---
id: ADR-001
title: Use JSON file storage
status: accepted          # proposed | accepted | deprecated | superseded
priority: foundational    # foundational | normal | exception
date: 2026-01-10
scope: storage            # dotted path; empty string = global
supersedes: []
---

Body markdown follows.

Usage

from mneme.adr_compiler import compile_adrs, adrs_to_decisions
from mneme.decision_retriever import DecisionRetriever

decisions = adrs_to_decisions(compile_adrs("docs/adr"))
retriever = DecisionRetriever(decisions)

---

Why this matters

Until v0.4.0, Mneme was a retrieval + enforcement layer on top of a
hand-edited JSON file. Useful, but not a foundation: nothing told you
what the correct set of constraints was at any given point in time.

v0.4.0 makes the corpus declarative and the resolution deterministic.
The same ADR set always compiles to the same active constraint set;
conflicts surface as compile errors rather than as silent drift in
behavior. That is the foundation the rest of the governance roadmap
(retry/remediation, drift detection, cross-project memory) builds on.

---

Migration

No migration needed. ADR ingestion is opt-in and additive:

• Existing project_memory.json workflows are unchanged.
• MemoryStore, Pipeline, the v0.3.x enforcement modes, and the
  Claude Code hook all keep working as-is.
• Adopt ADRs by wiring compile_adrs → adrs_to_decisions into your
  retriever construction; mix freely with JSON-backed decisions.

---

Tests and compatibility

• 47 new tests across parser, validator, precedence, integration.
• Full suite: 217 passed, 2 skipped (same e2e skips as v0.3.2).
• Zero regressions; MemoryStore / Pipeline / DecisionRetriever
  unchanged.

---

Deferred (not in this release)

• mneme adr compile <dir> CLI subcommand (library API is sufficient
  for v1; CLI is a v0.5 candidate).
• Pipeline.from_adr_dir() classmethod (callers can wire
  adrs_to_decisions(compile_adrs(dir)) themselves).
• Structured constraints: / anti_patterns: frontmatter fields.
• Hyphenated scope segments and multi-scope lists.
• Body-section parsing.
• The formal docs/adr/ADR-003-architectural-constraint-metadata-schema.md
  spec doc — schema is described in the README, CHANGELOG, and code;
  authoring the canonical ADR is queued for v0.5.

---

Strategic framing

Version	Theme
v0.3	Enforcement / governance checks
v0.4	Architectural compiler foundation
v0.5+	Advanced precedence / drift detection / structured constraint fields

v0.3.2 — Mneme for Claude Code

Architectural governance for Claude Code, packaged.

No engine changes — shells out to existing `mneme check` v0.3.x CLI.

What's new

• `mneme-hook` — Claude Code `PreToolUse` hook. Intercepts every Edit / Write / MultiEdit, reconstructs the full post-edit file, and blocks on decision violations. Fails open on all execution errors (binary missing, IO error, timeout).
• Installer — `python scripts/install_claude_code.py` writes `.claude/settings.json`, slash commands, and a discovery skill. Idempotent.
• Slash commands — `/mneme-check`, `/mneme-context`, `/mneme-record`, `/mneme-review`
• SKILL.md — discovery front door for Claude Code sessions
• Modes — `MNEME_HOOK_MODE=strict` (default) blocks; `warn` surfaces without blocking

Quick install

```bash
pip install mneme
python scripts/install_claude_code.py
```

Notes

Retrieval is keyword-based. The hook query is derived from the target file path — decisions whose scope tokens overlap with file names are retrieved. Use `/mneme-context` before large edits to confirm coverage. See docs/integrations/claude-code.md for details.