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