mneme-cc-plugin 2.0.0__py3-none-any.whl

mneme_cc_plugin/__init__.py

@@ -0,0 +1,3 @@
+"""Claude Code plugin package for mneme."""
+
+__version__ = "2.0.0"

mneme_cc_plugin/cli.py

@@ -0,0 +1,12 @@
+"""Top-level entry point for the ``mneme`` console script.
+
+This module exists so ``project.scripts.mneme`` in ``pyproject.toml``
+can stay short. The actual CLI logic lives in
+``mneme_cc_plugin.install.cli``.
+"""
+
+from __future__ import annotations
+
+from mneme_cc_plugin.install.cli import main
+
+__all__ = ["main"]

mneme_cc_plugin/hooks/__init__.py

@@ -0,0 +1,11 @@
+"""Claude Code hook implementations for the mneme plugin.
+
+Each hook module exposes a ``main()`` entry point that reads a JSON
+event from stdin, performs its task, and writes a JSON response to
+stdout. Every hook fails closed: any exception inside the hook is
+caught and converted to a benign success response so Claude Code is
+never blocked by a mneme defect.
+
+The ``MNEME_DISABLED`` environment variable acts as a global kill
+switch. When truthy, every hook short-circuits before doing any work.
+"""

mneme_cc_plugin/hooks/lib.py

@@ -0,0 +1,152 @@
+"""Shared plumbing for Claude Code hook implementations.
+
+The functions here implement the lifecycle every hook follows:
+
+  1. ``is_disabled``    Check the kill switch first.
+  2. ``read_event``     Parse JSON from stdin, tolerating empty input.
+  3. ``resolve_vault``  Locate the VaultConfig, returning None on miss.
+  4. (do hook work)
+  5. ``emit``           Write the success/error JSON envelope.
+
+Hook handlers wrap their work in ``run_hook`` which centralizes the
+failure-soft contract: any exception inside ``handler`` is caught and
+converted to a benign success response. Claude Code never sees a hook
+crash from mneme.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import traceback
+from collections.abc import Callable
+from typing import Any
+
+from mneme_core.vault.config import VaultConfig, VaultNotFoundError
+
+KILL_SWITCH_ENV = "MNEME_DISABLED"
+SKIP_HOOKS_ENV = "MNEME_SKIP_HOOKS"
+
+_SKIP_ALL_VALUES = {"all", "1", "true"}
+
+
+def is_disabled() -> bool:
+    """Return True if the kill switch env var is set to a truthy value."""
+    raw = os.environ.get(KILL_SWITCH_ENV, "")
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def is_skipped(hook_event_name: str) -> bool:
+    """Return True if *hook_event_name* should be skipped via MNEME_SKIP_HOOKS.
+
+    ``MNEME_SKIP_HOOKS`` accepts:
+
+    * A comma-separated, case-insensitive list of hook event names, e.g.
+      ``Stop,SessionStart`` — only those events are skipped.
+    * The literal values ``all``, ``1``, or ``true`` — every event is skipped.
+    * Unset or empty string — nothing is skipped.
+    """
+    raw = os.environ.get(SKIP_HOOKS_ENV, "").strip()
+    if not raw:
+        return False
+    normalized = raw.lower()
+    if normalized in _SKIP_ALL_VALUES:
+        return True
+    skipped = {part.strip().lower() for part in raw.split(",")}
+    return hook_event_name.lower() in skipped
+
+
+def read_event() -> dict[str, Any]:
+    """Read the Claude Code hook event from stdin.
+
+    The contract: Claude Code writes a JSON object to the hook stdin
+    that contains at least ``hook_event_name``. Older or sparser
+    versions may pass an empty stdin; tolerate that by returning an
+    empty dict.
+    """
+    if sys.stdin.isatty():
+        return {}
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def emit(
+    *,
+    continue_: bool = True,
+    suppress_output: bool = True,
+    additional_context: str | None = None,
+    system_message: str | None = None,
+    hook_event_name: str | None = None,
+) -> None:
+    """Write the hook response JSON envelope to stdout.
+
+    ``additional_context`` is wrapped inside ``hookSpecificOutput`` as
+    Claude Code expects when surfacing extra context.
+    """
+    payload: dict[str, Any] = {
+        "continue": continue_,
+        "suppressOutput": suppress_output,
+    }
+    if system_message is not None:
+        payload["systemMessage"] = system_message
+    if additional_context is not None:
+        payload["hookSpecificOutput"] = {
+            "hookEventName": hook_event_name or "Unknown",
+            "additionalContext": additional_context,
+        }
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+    sys.stdout.flush()
+
+
+def resolve_vault() -> VaultConfig | None:
+    """Resolve VaultConfig, returning None if no vault could be found.
+
+    Hooks are fail-soft: a missing vault is not a crash, it is a
+    no-op. The user runs ``mneme install`` to provision one.
+    """
+    try:
+        return VaultConfig.resolve()
+    except VaultNotFoundError:
+        return None
+    except Exception:
+        return None
+
+
+def run_hook(
+    handler: Callable[[dict[str, Any], VaultConfig | None], None],
+    *,
+    hook_event_name: str,
+) -> int:
+    """Execute a hook handler with kill-switch + fail-soft semantics.
+
+    Args:
+        handler: function ``(event, vault) -> None``. It owns calling
+            ``emit`` itself (so it can attach hook-specific output).
+        hook_event_name: name reported in error envelopes for triage.
+
+    Returns:
+        Always 0. Non-zero exit codes from hooks risk being treated
+        as a block by some Claude Code versions.
+    """
+    try:
+        if is_disabled() or is_skipped(hook_event_name):
+            emit(hook_event_name=hook_event_name)
+            return 0
+        event = read_event()
+        vault = resolve_vault()
+        handler(event, vault)
+    except SystemExit:
+        raise
+    except BaseException:
+        # Surface failure to stderr for operator debugging without
+        # blocking Claude Code. stdout still gets a benign success.
+        sys.stderr.write(f"[mneme:{hook_event_name}] {traceback.format_exc()}")
+        emit(hook_event_name=hook_event_name)
+    return 0

mneme_cc_plugin/hooks/lock.py

@@ -0,0 +1,14 @@
+"""Cross-platform exclusive file lock for hook concurrency control.
+
+The canonical implementation moved to
+``mneme_core.vault.file_lock`` so it can be reused by the
+compression cost ledger (Codex Pass 2 reservation pattern). This
+module re-exports the same symbol so existing hook imports do not
+break.
+"""
+
+from __future__ import annotations
+
+from mneme_core.vault.file_lock import file_lock
+
+__all__ = ["file_lock"]

mneme_cc_plugin/hooks/post_tool_use.py

@@ -0,0 +1,99 @@
+"""PostToolUse hook: stage tool events for the FTS5 indexer.
+
+For each captured tool invocation, write a JSON staging record into
+the vault's staging directory. The indexer picks up staged records on
+its next pass and folds them into the FTS5 index. The hook itself
+performs no LLM call and writes no markdown into the vault - that is
+the Stop hook's job.
+
+The full ``capture_event`` implementation lives in
+``mneme_core.compression.staging``. This module is a thin Claude Code
+adapter that constructs a StagingConfig pointing at the resolved vault
+and forwards the event payload.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from mneme_core.compression.staging import StagingConfig, capture_event
+from mneme_core.distill.shell_compress import (
+    ShellCompressOpts,
+    compress_shell_output,
+)
+from mneme_core.kg import kg_config_from_vault, stage_event
+from mneme_core.vault.config import VaultConfig
+
+from .lib import emit, run_hook
+
+# Bash tool responses can land verbose stdout under any of these keys
+# depending on Claude Code version. Walk known keys and compress any
+# string longer than the threshold before staging. Keys not present in
+# the event are silently skipped.
+_SHELL_OUTPUT_KEYS = ("stdout", "stderr", "output", "result", "text", "content")
+_COMPRESS_MIN_BYTES = 256
+
+
+def _compress_bash_payload(event: dict[str, Any]) -> None:
+    """Apply distill.shell_compress in-place to Bash tool response strings.
+
+    Codex Pass 2 review fix: docs/HOOKS advertised PostToolUse-time
+    shell output compression but the hook forwarded raw events. This
+    function compresses long stdout/stderr fields before they reach
+    the staging JSONL, matching the documented behavior.
+    """
+    if event.get("tool_name") != "Bash":
+        return
+    resp = event.get("tool_response")
+    if not isinstance(resp, dict):
+        return
+    opts = ShellCompressOpts()
+    for key in _SHELL_OUTPUT_KEYS:
+        value = resp.get(key)
+        if not isinstance(value, str):
+            continue
+        if len(value.encode("utf-8")) < _COMPRESS_MIN_BYTES:
+            continue
+        stats = compress_shell_output(value, opts)
+        if stats.compressed_bytes < stats.original_bytes:
+            resp[key] = stats.compressed_text
+
+
+def handle(event: dict[str, Any], vault: VaultConfig | None) -> None:
+    if vault is None:
+        emit(hook_event_name="PostToolUse")
+        return
+
+    # Compress before staging so both the FTS index and any later
+    # compression call see the reduced payload.
+    try:
+        _compress_bash_payload(event)
+    except Exception as exc:
+        sys.stderr.write(f"[mneme:PostToolUse] shell compress skipped: {exc}\n")
+
+    config = StagingConfig(
+        staging_dir=vault.staging_dir,
+        audit_dir=vault.audit_log_dir,
+    )
+    try:
+        capture_event(event, config)
+    except Exception as exc:
+        sys.stderr.write(f"[mneme:PostToolUse] capture skipped: {exc}\n")
+
+    # KG staging is gated by kg_active_flag inside stage_event itself.
+    # Cheap no-op for lite/standard profiles where the flag is absent.
+    try:
+        stage_event(event, kg_config_from_vault(vault))
+    except Exception as exc:
+        sys.stderr.write(f"[mneme:PostToolUse] kg stage skipped: {exc}\n")
+
+    emit(hook_event_name="PostToolUse")
+
+
+def main() -> int:
+    return run_hook(handle, hook_event_name="PostToolUse")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mneme_cc_plugin/hooks/pre_compact.py

@@ -0,0 +1,59 @@
+"""PreCompact hook: snapshot the vault state file.
+
+Claude Code calls PreCompact right before context compaction. The
+mneme hook responds by stamping a `last_precompact_at` field into
+``vault/.mneme/state.json`` so the next SessionStart can decide
+whether to refresh its preamble. The hook does no other work; the
+500ms budget would not survive a heavier touch.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+from mneme_core.vault.atomic_write import atomic_write_text
+from mneme_core.vault.config import VaultConfig
+
+from .lib import emit, run_hook
+
+STATE_FILENAME = "state.json"
+
+
+def handle(event: dict[str, Any], vault: VaultConfig | None) -> None:
+    if vault is None:
+        emit(hook_event_name="PreCompact")
+        return
+
+    state_path = vault.state_dir / STATE_FILENAME
+    try:
+        if state_path.exists():
+            state = json.loads(state_path.read_text(encoding="utf-8"))
+        else:
+            state = {}
+    except (OSError, json.JSONDecodeError):
+        state = {}
+
+    state["last_precompact_at"] = datetime.now(UTC).isoformat()
+    state.setdefault("schema_version", 1)
+
+    try:
+        state_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(
+            state_path,
+            json.dumps(state, indent=2, ensure_ascii=False) + "\n",
+        )
+    except OSError as exc:
+        sys.stderr.write(f"[mneme:PreCompact] write failed: {exc}\n")
+
+    emit(hook_event_name="PreCompact")
+
+
+def main() -> int:
+    return run_hook(handle, hook_event_name="PreCompact")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mneme_cc_plugin/hooks/session_end.py

@@ -0,0 +1,144 @@
+"""SessionEnd hook: flush staging buffers and (opt-in) compression.
+
+In the lite profile this is a near no-op: it stamps
+``last_session_end_at`` into the vault state file so SessionStart
+can compute the elapsed-since-last-session window. Full profile
+will later trigger an asynchronous Graphiti episode flush. That
+flush lives behind the install profile gate and is not invoked
+from here at v1.0.
+
+Background compression, when opted into by the user, is launched
+as a fire-and-forget subprocess so the hook still returns inside
+its latency budget. v1.0 ships compression OFF by default so this
+hook does not invoke any LLM unprompted. The gating is layered:
+
+  1. The compression flag must be true in the vault config.
+  2. The pause flag must not be present.
+  3. The Anthropic key (or any compatible LLM auth) must be in env.
+
+The subprocess inherits the parent env so the user does not need
+to re-export the key, and the spawn is detached so the hook
+returns immediately. Codex Pass 2 review fix: prior implementation
+documented this behavior but never spawned the subprocess.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from datetime import UTC, datetime
+from typing import Any
+
+from mneme_core.vault.atomic_write import atomic_write_text
+from mneme_core.vault.config import VaultConfig
+
+from .lib import emit, run_hook
+
+STATE_FILENAME = "state.json"
+
+# Subprocess launch flags that disconnect the child from the hook so
+# the hook returns inside its latency budget while the LLM call runs.
+if sys.platform == "win32":
+    _DETACHED_FLAGS = 0x00000008 | 0x00000200  # DETACHED | NEW_PROCESS_GROUP
+else:
+    _DETACHED_FLAGS = 0
+
+
+def _compression_enabled(vault: VaultConfig) -> bool:
+    """Read the vault compression config flag without importing LLM deps.
+
+    Returns False if the file is missing or malformed so opt-out
+    behavior survives any config-side drift.
+    """
+    cfg_path = vault.compression_config_path
+    if not cfg_path.is_file():
+        return False
+    try:
+        data = json.loads(cfg_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return bool(data.get("enabled", False))
+
+
+def _has_provider_auth() -> bool:
+    """Cheap env check so we never spawn when the LLM call would fail."""
+    for var in ("ANTHROPIC_API_KEY", "OPENAI_API_KEY", "MNEME_LLM_API_KEY"):
+        if os.environ.get(var):
+            return True
+    return False
+
+
+def _maybe_launch_compression(vault: VaultConfig) -> None:
+    """Fire-and-forget background compression run when opt-in gates pass."""
+    if not _compression_enabled(vault):
+        return
+    if vault.compression_pause_flag.is_file():
+        return
+    if not _has_provider_auth():
+        return
+    try:
+        cmd = [
+            sys.executable,
+            "-m",
+            "mneme_core.cli",
+            "compress",
+            "run",
+        ]
+        popen_kwargs: dict[str, Any] = {
+            "cwd": str(vault.root),
+            "stdout": subprocess.DEVNULL,
+            "stderr": subprocess.DEVNULL,
+            "stdin": subprocess.DEVNULL,
+            "close_fds": True,
+        }
+        if sys.platform == "win32":
+            popen_kwargs["creationflags"] = _DETACHED_FLAGS
+        else:
+            popen_kwargs["start_new_session"] = True
+        subprocess.Popen(cmd, **popen_kwargs)
+    except Exception as exc:
+        sys.stderr.write(
+            f"[mneme:SessionEnd] compression launch skipped: {exc}\n"
+        )
+
+
+def handle(event: dict[str, Any], vault: VaultConfig | None) -> None:
+    if vault is None:
+        emit(hook_event_name="SessionEnd")
+        return
+
+    state_path = vault.state_dir / STATE_FILENAME
+    try:
+        if state_path.exists():
+            state = json.loads(state_path.read_text(encoding="utf-8"))
+        else:
+            state = {}
+    except (OSError, json.JSONDecodeError):
+        state = {}
+
+    state["last_session_end_at"] = datetime.now(UTC).isoformat()
+    state.setdefault("schema_version", 1)
+
+    try:
+        state_path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(
+            state_path,
+            json.dumps(state, indent=2, ensure_ascii=False) + "\n",
+        )
+    except OSError as exc:
+        sys.stderr.write(f"[mneme:SessionEnd] write failed: {exc}\n")
+
+    # Three-layer gate enforced inside _maybe_launch_compression.
+    _maybe_launch_compression(vault)
+
+    emit(hook_event_name="SessionEnd")
+
+
+def main() -> int:
+    return run_hook(handle, hook_event_name="SessionEnd")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mneme_cc_plugin/hooks/session_start.py

@@ -0,0 +1,189 @@
+"""SessionStart hook: inject preflight vault context.
+
+Returns up to ``MAX_CHARS`` characters of markdown that Claude Code
+surfaces as conversation preamble. The bundle contains:
+
+  - Today's date.
+  - The last few headings from any session document modified today.
+  - A short git status summary if the vault is a git repository.
+  - The five most recently modified session-typed documents.
+
+Each block is optional. If any source is missing the block is
+silently omitted rather than reported as an error. The hook's job is
+to make the new session smarter, not to surface diagnostic noise.
+
+Heavy retrieval (LEANN dense + Graphiti KG) is intentionally not
+called from this hook. SessionStart has a 500ms p95 budget. We hold
+the p95 with fast SQLite reads; the optional git summary runs two
+short ``git`` execs (status + log) under a shared
+``GIT_BUDGET_SECONDS`` deadline, so a slow or hung repo degrades the
+git block rather than blowing the budget by seconds.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import subprocess
+import sys
+import time
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from mneme_core.injection import wrap_untrusted
+from mneme_core.vault.config import VaultConfig
+
+from .lib import emit, run_hook
+
+MAX_CHARS = 8_000
+RECENT_SESSION_LIMIT = 5
+GIT_STATUS_LINE_LIMIT = 10
+# Hard ceiling shared by the two git execs. The healthy-repo p95 is far
+# below this; the budget only bites when git is slow or hung, where we
+# would rather drop the git block than make every session wait.
+GIT_BUDGET_SECONDS = 1.5
+
+
+def _today_iso() -> str:
+    return date.today().isoformat()
+
+
+def _block_date() -> str:
+    return f"### Date\n{_today_iso()}\n"
+
+
+def _block_today_headings(vault: VaultConfig) -> str:
+    # The Stop hook writes the daily session log under sessions/ (its
+    # LOG_DIR_NAME), so read from there rather than the vault root.
+    today_md = vault.root / "sessions" / f"{_today_iso()}.md"
+    if not today_md.exists():
+        return ""
+    try:
+        lines = today_md.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return ""
+    headings = [ln for ln in lines if ln.startswith("##")][-5:]
+    if not headings:
+        return ""
+    out = ["### Today's recent section headings", ""]
+    out.extend(f"- {h.lstrip('# ').strip()}" for h in headings)
+    return "\n".join(out) + "\n"
+
+
+def _block_git_summary(vault_root: Path) -> str:
+    if not (vault_root / ".git").exists():
+        return ""
+    deadline = time.monotonic() + GIT_BUDGET_SECONDS
+    try:
+        status = subprocess.run(
+            ["git", "status", "--short"],
+            cwd=str(vault_root),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=GIT_BUDGET_SECONDS,
+        )
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            # status alone consumed the budget on a slow repo; drop the
+            # whole block rather than starting a second exec over budget.
+            return ""
+        log = subprocess.run(
+            ["git", "log", "--oneline", "-5"],
+            cwd=str(vault_root),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=remaining,
+        )
+    except (subprocess.TimeoutExpired, OSError, FileNotFoundError):
+        return ""
+
+    status_lines = [ln for ln in status.stdout.splitlines() if ln.strip()]
+    out = ["### Vault git status"]
+    if status_lines:
+        head = status_lines[:GIT_STATUS_LINE_LIMIT]
+        out.append(f"{len(status_lines)} changed (showing first {len(head)}):")
+        out.extend(f"  {ln}" for ln in head)
+    else:
+        out.append("Clean")
+    out.append("")
+    out.append("### Last 5 commits")
+    out.append(log.stdout.strip() if log.stdout.strip() else "(no git log)")
+    return "\n".join(out) + "\n"
+
+
+def _block_recent_sessions(vault: VaultConfig) -> str:
+    if not vault.fts5_db.exists():
+        return ""
+    try:
+        conn = sqlite3.connect(
+            f"file:{vault.fts5_db}?mode=ro",
+            uri=True,
+        )
+    except sqlite3.OperationalError:
+        # mode=ro raises OperationalError when the file is missing or
+        # cannot be opened for reading; degrade gracefully.
+        return ""
+    except sqlite3.Error:
+        return ""
+    try:
+        rows = conn.execute(
+            "SELECT path, COALESCE(title, '') AS title "
+            "FROM documents "
+            "WHERE frontmatter_type = 'session' "
+            "ORDER BY mtime DESC LIMIT ?",
+            (RECENT_SESSION_LIMIT,),
+        ).fetchall()
+    except sqlite3.Error:
+        return ""
+    finally:
+        conn.close()
+
+    if not rows:
+        return ""
+    out = ["### Most recent session documents", ""]
+    for path, title in rows:
+        label = title or path
+        out.append(f"- `{path}` -- {label}")
+    return "\n".join(out) + "\n"
+
+
+def _build_context(vault: VaultConfig) -> str:
+    # Vault-derived blocks are untrusted: a crafted note title, section
+    # heading, or commit message could carry prompt-injection text that
+    # would otherwise be surfaced as authoritative preamble. Fence them
+    # with the spotlighting guard (gap G-3) so the model treats them as
+    # data. The date block is system-generated and stays outside.
+    untrusted = "\n".join(
+        b
+        for b in (
+            _block_today_headings(vault),
+            _block_git_summary(vault.root),
+            _block_recent_sessions(vault),
+        )
+        if b
+    )
+    parts: list[str] = ["## Vault Context (mneme SessionStart)", "", _block_date()]
+    if untrusted:
+        parts.append(wrap_untrusted(untrusted, source="vault-session-start"))
+    full = "\n".join(p for p in parts if p)
+    if len(full) > MAX_CHARS:
+        full = full[:MAX_CHARS] + "\n\n[CONTEXT TRUNCATED]"
+    return full
+
+
+def handle(event: dict[str, Any], vault: VaultConfig | None) -> None:
+    if vault is None:
+        emit(hook_event_name="SessionStart")
+        return
+    context = _build_context(vault)
+    emit(hook_event_name="SessionStart", additional_context=context)
+
+
+def main() -> int:
+    return run_hook(handle, hook_event_name="SessionStart")
+
+
+if __name__ == "__main__":
+    sys.exit(main())