memgit 0.3.1__tar.gz → 0.4.0__tar.gz

{memgit-0.3.1 → memgit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memgit
-Version: 0.3.1
+Version: 0.4.0
 Summary: Git for AI memory — version-controlled context persistence across Claude, GPT, Gemini, Cursor, Windsurf, and more
 License: MIT
 Project-URL: Homepage, https://memgit.dev
@@ -212,13 +212,22 @@ memgit resume --plain    # plain text, for piping into an AI context
 memgit resume --json     # for tooling
 ```
 
-Wire it into Claude Code so every new session **starts** with this digest in context — no tool call, no judgment required:
+Wire it into Claude Code so memory becomes **automatic** — no tool call, no judgment required:
 
 ```bash
-memgit setup hooks       # installs a SessionStart hook (~/.claude/settings.json)
+memgit setup hooks       # installs all four hooks (~/.claude/settings.json)
 ```
 
-The digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one `get_memory` call away.
+| Hook | What it enforces |
+|---|---|
+| `SessionStart` | every session opens with the resume digest in context |
+| `UserPromptSubmit` | each prompt is BM25-matched against the store; relevant memories are injected (silent when nothing clears the relevance bar; never repeats within a session) — `--no-recall` to skip |
+| `Stop` (guard) | a session that did real work but saved nothing gets ONE nudge to save durable facts before finishing — `--no-guard` to skip |
+| `Stop` (sync) | markdown memories are checkpointed asynchronously at session end |
+
+Why hooks and not just good tool descriptions? We measured it: across 166 real sessions, hook-injected context was delivered in **100%** of them while voluntary memory-tool calls happened in **6%**. What a hook enforces happens.
+
+The resume digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one `get_memory` call away.
 
 ---
 
@@ -322,7 +331,8 @@ memgit setup windsurf
 memgit setup cline
 memgit setup continue
 memgit setup gemini-cli
-memgit setup hooks                # Claude Code SessionStart hook → auto-inject resume digest
+memgit setup hooks                # Claude Code hooks: resume at start, per-prompt recall,
+                                  # capture guard + auto-sync at stop (--no-recall / --no-guard)
 
 # Server
 memgit serve                      # MCP stdio (Claude Code, Cursor, Windsurf, Cline)

{memgit-0.3.1 → memgit-0.4.0}/README.md

@@ -178,13 +178,22 @@ memgit resume --plain    # plain text, for piping into an AI context
 memgit resume --json     # for tooling
 ```
 
-Wire it into Claude Code so every new session **starts** with this digest in context — no tool call, no judgment required:
+Wire it into Claude Code so memory becomes **automatic** — no tool call, no judgment required:
 
 ```bash
-memgit setup hooks       # installs a SessionStart hook (~/.claude/settings.json)
+memgit setup hooks       # installs all four hooks (~/.claude/settings.json)
 ```
 
-The digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one `get_memory` call away.
+| Hook | What it enforces |
+|---|---|
+| `SessionStart` | every session opens with the resume digest in context |
+| `UserPromptSubmit` | each prompt is BM25-matched against the store; relevant memories are injected (silent when nothing clears the relevance bar; never repeats within a session) — `--no-recall` to skip |
+| `Stop` (guard) | a session that did real work but saved nothing gets ONE nudge to save durable facts before finishing — `--no-guard` to skip |
+| `Stop` (sync) | markdown memories are checkpointed asynchronously at session end |
+
+Why hooks and not just good tool descriptions? We measured it: across 166 real sessions, hook-injected context was delivered in **100%** of them while voluntary memory-tool calls happened in **6%**. What a hook enforces happens.
+
+The resume digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one `get_memory` call away.
 
 ---
 
@@ -288,7 +297,8 @@ memgit setup windsurf
 memgit setup cline
 memgit setup continue
 memgit setup gemini-cli
-memgit setup hooks                # Claude Code SessionStart hook → auto-inject resume digest
+memgit setup hooks                # Claude Code hooks: resume at start, per-prompt recall,
+                                  # capture guard + auto-sync at stop (--no-recall / --no-guard)
 
 # Server
 memgit serve                      # MCP stdio (Claude Code, Cursor, Windsurf, Cline)

{memgit-0.3.1 → memgit-0.4.0}/memgit/__init__.py

@@ -1,3 +1,3 @@
 """memgit — git for AI memory."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"

{memgit-0.3.1 → memgit-0.4.0}/memgit/cli.py

@@ -29,11 +29,10 @@ def _require_repo() -> Repository:
 
 # ── Root group ────────────────────────────────────────────────────────────────
 
-try:
-    from importlib.metadata import version as _pkg_version
-    _version = _pkg_version('memgit')
-except Exception:
-    _version = '0.1.2'
+# Source of truth is the code, not dist metadata: editable installs keep
+# whatever metadata version existed at `pip install -e` time (observed: a
+# 0.3.1 checkout reporting 0.1.0 via importlib.metadata).
+from . import __version__ as _version
 
 
 @click.group()
@@ -127,7 +126,8 @@ def init(directory):
 @click.option('--body', '-b', default=None,
               help='Full long-form detail (multi-line ok, or "-" to read stdin)')
 @click.option('--project', '-P', default=None,
-              help='Project this memory belongs to (see `memgit list`)')
+              help='Project this memory belongs to (default: derived from the '
+                   'current directory; pass "" for a global memory)')
 def add(slug, rule, type_code, why, when, tags, priority, body, project):
     """Add or update a mnemonic.
 
@@ -138,6 +138,13 @@ def add(slug, rule, type_code, why, when, tags, priority, body, project):
     tag_list = [t.strip() for t in tags.split(',')] if tags else []
     if body == '-':
         body = sys.stdin.read().strip() or None
+    # Same scoping semantics as MCP save_memory: absent → this workspace,
+    # explicit empty → deliberately global.
+    if project is None:
+        from .project import project_label_from_path
+        project = project_label_from_path(Path.cwd())
+    elif not project.strip():
+        project = None
 
     m = Mnemonic(
         type_code=type_code,
@@ -152,7 +159,8 @@ def add(slug, rule, type_code, why, when, tags, priority, body, project):
         project=project,
     )
     sha = repo.add(m)
-    console.print(f'[green]staged[/green]  {slug} [{sha[:8]}]')
+    from rich.markup import escape as _mesc
+    console.print(f'[green]staged[/green]  {_mesc(m.slug)} {_mesc("[" + sha[:8] + "]")}')
 
 
 # ── remove ────────────────────────────────────────────────────────────────────
@@ -355,12 +363,42 @@ def _format_resume_plain(ctx: dict) -> str:
     if ctx.get('maintenance'):
         lines.append('')
         lines.append(f'## Maintenance needed\n- {ctx["maintenance"]}')
+    if ctx.get('project_is_new'):
+        lines.append('')
+        lines.append(
+            f'## This project has no memories yet ({ctx["project"]})\n'
+            '- memgit was adopted mid-project: nothing above is specific to this '
+            'workspace. Bootstrap it once — run `memgit onboard` for a repo '
+            'digest + seeding brief, then save 10-20 durable facts '
+            '(purpose, architecture, conventions, state, gotchas) via save_memory.'
+        )
     lines.append('')
     lines.append('(Check work-in-flight and the last checkpoints before assuming state; '
                  'use memgit search for anything task-specific.)')
     return '\n'.join(lines)
 
 
+# ── hook handlers (invoked by AI-tool hosts, not humans) ─────────────────────
+
+@cli.group(name='hook')
+def hook():
+    """Hook handlers for AI-tool hosts (installed by `memgit setup hooks`)."""
+
+
+@hook.command('prompt-recall')
+def hook_prompt_recall():
+    """UserPromptSubmit: inject memories relevant to the prompt (stdin JSON)."""
+    from .hooks import prompt_recall
+    sys.exit(prompt_recall())
+
+
+@hook.command('stop-guard')
+def hook_stop_guard():
+    """Stop: nudge once if a substantive session saved nothing (stdin JSON)."""
+    from .hooks import stop_guard
+    sys.exit(stop_guard())
+
+
 # ── onboard ───────────────────────────────────────────────────────────────────
 
 ONBOARD_BRIEF = """\
@@ -602,35 +640,40 @@ def show(slug, toon, fmt_markdown):
     elif toon:
         print(serialize_mnemonic(m))
     else:
+        # User content and shas go through markup escaping — `[pj]`,
+        # `[[wikilinks]]`, or a sha like [fadc1234] would otherwise be
+        # eaten as rich tags and silently altered on screen.
+        from rich.markup import escape as _mesc
         sha_s = m.sha[:8] if m.sha else '?'
         p_label = {1: 'low', 2: 'medium', 3: '[bold red]CRITICAL[/bold red]'}[m.priority]
-        proj = f'  project={m.project}' if m.project else ''
-        console.print(f'[bold cyan]{m.slug}[/bold cyan]  [{m.type_code}]  priority={p_label}{proj}  sha={sha_s}')
+        proj = f'  project={_mesc(m.project)}' if m.project else ''
+        console.print(f'[bold cyan]{_mesc(m.slug)}[/bold cyan]  {_mesc("[" + m.type_code + "]")}  '
+                      f'priority={p_label}{proj}  sha={_mesc(sha_s)}')
         console.print(f'')
-        console.print(f'[bold]RULE[/bold] {m.rule}')
+        console.print(f'[bold]RULE[/bold] {_mesc(m.rule)}')
         if m.why:
-            console.print(f'[bold]WHY[/bold]  {m.why}')
+            console.print(f'[bold]WHY[/bold]  {_mesc(m.why)}')
         if m.when:
-            console.print(f'[bold]WHEN[/bold] {m.when}')
+            console.print(f'[bold]WHEN[/bold] {_mesc(m.when)}')
         if m.desc:
-            console.print(f'[bold]DESC[/bold] {m.desc}')
+            console.print(f'[bold]DESC[/bold] {_mesc(m.desc)}')
         if m.body:
             console.print(f'\n[bold]BODY[/bold]')
-            console.print(m.body)
+            console.print(m.body, markup=False)
         if m.who:
-            console.print(f'[bold]WHO[/bold]  {m.who}')
+            console.print(f'[bold]WHO[/bold]  {_mesc(m.who)}')
         if m.where:
-            console.print(f'[bold]WHERE[/bold] {m.where}')
+            console.print(f'[bold]WHERE[/bold] {_mesc(m.where)}')
         if m.inc:
-            console.print(f'[bold]INC[/bold]  {m.inc}')
+            console.print(f'[bold]INC[/bold]  {_mesc(m.inc)}')
         if m.cost:
-            console.print(f'[bold]COST[/bold] {m.cost}')
+            console.print(f'[bold]COST[/bold] {_mesc(m.cost)}')
         if m.tags:
-            console.print(f'[dim]Tags: {", ".join(m.tags)}[/dim]')
+            console.print(f'[dim]Tags: {_mesc(", ".join(m.tags))}[/dim]')
         if m.related:
-            console.print(f'[dim]Related: {", ".join(m.related)}[/dim]')
+            console.print(f'[dim]Related: {_mesc(", ".join(m.related))}[/dim]')
         if m.supersedes:
-            console.print(f'[dim]Supersedes: {", ".join(m.supersedes)}[/dim]')
+            console.print(f'[dim]Supersedes: {_mesc(", ".join(m.supersedes))}[/dim]')
 
 
 # ── list ──────────────────────────────────────────────────────────────────────
@@ -864,6 +907,7 @@ def lint():
         console.print(f'[green]OK[/green] — {len(mnemonics)} mnemonics, no issues')
     else:
         console.print(f'[yellow]{issues} issue{"s" if issues != 1 else ""}[/yellow]')
+        sys.exit(1)  # let scripts/CI gate on lint
 
 
 import re  # noqa: E402 — needed for lint command
@@ -1002,6 +1046,15 @@ def sync(message, dry_run):
     mnemonics = from_claude_code()
 
     if not mnemonics:
+        # No markdown sources on this machine — but anything already staged
+        # (MCP saves, CLI adds) must still be checkpointed, or it lingers
+        # uncommitted forever on stores fed purely through MCP.
+        if not dry_run:
+            msg = message or _staged_diff_message(repo)
+            sha = repo.commit(message=msg, trigger='session_end') if msg else None
+            if sha:
+                console.print(f'[green]sync[/green]  {sha[:8]}  {msg}')
+                return
         console.print('[dim]No Claude Code memories found.[/dim]')
         return
 
@@ -1926,15 +1979,41 @@ def setup_gemini_cli(dry_run):
     _run_target('Gemini CLI', path, _patch_mcp_servers, dry_run)
 
 
+#: substrings identifying a hook command as one of ours (any generation)
+_MEMGIT_HOOK_SIGNS = ('resume --plain', 'hook prompt-recall', 'hook stop-guard', ' sync')
+
+
+def _is_memgit_hook_entry(h: dict) -> bool:
+    return any(
+        'memgit' in inner.get('command', '') and
+        any(sign in inner.get('command', '') for sign in _MEMGIT_HOOK_SIGNS)
+        for inner in h.get('hooks', []) if isinstance(inner, dict)
+    )
+
+
 @setup.command('hooks')
-@click.option('--remove', is_flag=True, help='Uninstall the memgit SessionStart hook')
+@click.option('--remove', is_flag=True, help='Uninstall all memgit hooks')
+@click.option('--no-recall', is_flag=True,
+              help='Skip the per-prompt auto-recall hook (UserPromptSubmit)')
+@click.option('--no-guard', is_flag=True,
+              help='Skip the end-of-session capture guard (Stop)')
 @click.option('--dry-run', is_flag=True, help='Show the change without writing')
-def setup_hooks(remove, dry_run):
-    """Install a Claude Code SessionStart hook that injects `memgit resume`.
+def setup_hooks(remove, no_recall, no_guard, dry_run):
+    """Install the Claude Code hooks that make memory automatic.
+
+    Four hooks, one principle: what a hook enforces happens, what a tool
+    description suggests mostly doesn't (measured: 6% voluntary engagement
+    vs 100% hook delivery).
 
-    After this, every new Claude Code session (including /clear and resume)
-    automatically starts with your last checkpoints, work in flight, and
-    critical rules in context — the model doesn't have to remember to look.
+    \b
+      SessionStart      inject `memgit resume` — last checkpoints, work in
+                        flight, critical rules
+      UserPromptSubmit  inject memories relevant to each prompt (BM25,
+                        silent when nothing clears the relevance bar)
+      Stop              capture guard — a substantive session ending with
+                        zero memory writes gets ONE nudge to save durable
+                        facts; plus async `memgit sync` to checkpoint
+                        markdown memories
 
     Hooks live in ~/.claude/settings.json (unlike MCP servers, which live
     in ~/.claude.json).
@@ -1942,8 +2021,10 @@ def setup_hooks(remove, dry_run):
     import shlex
     settings_path = Path.home() / '.claude' / 'settings.json'
     base = ' '.join(shlex.quote(p) for p in _memgit_base_cmd())
-    # `|| true`: a broken store must never block session start
-    hook_command = f'{base} resume --plain 2>/dev/null || true'
+
+    from .repo import default_store_candidates
+    store = next((c for c in default_store_candidates() if (c / '.memgit').is_dir()),
+                 Path.home() / '.claude' / 'memgit-store')
 
     if settings_path.exists():
         try:
@@ -1955,43 +2036,55 @@ def setup_hooks(remove, dry_run):
         data = {}
 
     hooks = data.setdefault('hooks', {})
-    session_start = hooks.setdefault('SessionStart', [])
 
-    def _is_memgit_hook(h: dict) -> bool:
-        return any('memgit resume' in inner.get('command', '')
-                   for inner in h.get('hooks', []) if isinstance(inner, dict))
+    # `|| true` + stderr silenced everywhere: a broken store must never
+    # block the user's session.
+    plan: dict[str, list[dict]] = {
+        'SessionStart': [
+            {'type': 'command',
+             'command': f'{base} resume --plain 2>/dev/null || true'},
+        ],
+        'UserPromptSubmit': [] if no_recall else [
+            {'type': 'command',
+             'command': f'{base} hook prompt-recall 2>/dev/null || true'},
+        ],
+        'Stop': ([] if no_guard else [
+            {'type': 'command',
+             'command': f'{base} hook stop-guard 2>/dev/null || true'},
+        ]) + [
+            {'type': 'command',
+             'command': f'cd {shlex.quote(str(store))} && {base} sync 2>/dev/null || true',
+             'async': True},
+        ],
+    }
+
+    changed = []
+    for event in ('SessionStart', 'UserPromptSubmit', 'Stop'):
+        entries = hooks.setdefault(event, [])
+        had = [h for h in entries if isinstance(h, dict) and _is_memgit_hook_entry(h)]
+        entries[:] = [h for h in entries if h not in had]
+        if not remove and plan[event]:
+            entries.append({'hooks': plan[event]})
+            changed.append(event)
+        if not entries:
+            hooks.pop(event, None)
+    if not hooks:
+        data.pop('hooks', None)
 
-    existing = [h for h in session_start if isinstance(h, dict) and _is_memgit_hook(h)]
+    if not dry_run:
+        _write_json_safe(settings_path, data)
 
+    suffix = ' [dim](dry run)[/dim]' if dry_run else ''
     if remove:
-        if not existing:
-            console.print('[dim]No memgit SessionStart hook installed.[/dim]')
-            return
-        session_start[:] = [h for h in session_start if h not in existing]
-        if not session_start:
-            hooks.pop('SessionStart', None)
-        if not hooks:
-            data.pop('hooks', None)
-        if not dry_run:
-            _write_json_safe(settings_path, data)
-        console.print(f'[yellow]removed[/yellow] memgit SessionStart hook from {settings_path}'
-                      + (' [dim](dry run)[/dim]' if dry_run else ''))
+        console.print(f'[yellow]removed[/yellow] all memgit hooks from {settings_path}{suffix}')
         return
-
-    entry = {'hooks': [{'type': 'command', 'command': hook_command}]}
-    if existing:
-        if existing[0] == entry and len(existing) == 1:
-            console.print(f'[green]✓[/green] already installed in {settings_path}')
-            return
-        session_start[:] = [h for h in session_start if h not in existing]
-    session_start.append(entry)
-
-    if not dry_run:
-        _write_json_safe(settings_path, data)
-    console.print(f'[green]✓[/green] SessionStart hook installed in {settings_path}'
-                  + (' [dim](dry run)[/dim]' if dry_run else ''))
-    console.print(f'  [dim]{hook_command}[/dim]')
-    console.print('[dim]Every new Claude Code session now starts with your memgit resume digest.[/dim]')
+    console.print(f'[green]✓[/green] memgit hooks installed in {settings_path}{suffix}')
+    for event in changed:
+        for inner in plan[event]:
+            tag = ' [dim](async)[/dim]' if inner.get('async') else ''
+            console.print(f'  [cyan]{event}[/cyan]  [dim]{inner["command"]}[/dim]{tag}')
+    console.print('[dim]Resume at session start, relevant memories per prompt, '
+                  'capture guard + sync at stop.[/dim]')
 
 
 @setup.command('print-config')

memgit-0.4.0/memgit/hooks.py

@@ -0,0 +1,212 @@
+"""Claude Code hook handlers — guardrail-grade recall and capture.
+
+Voluntary tool calls are not enough: measured across 166 real sessions,
+Claude engaged the memory tools in 6% of them while the SessionStart
+injection worked in 100%. What a hook enforces happens; what a tool
+description suggests mostly doesn't. These handlers close the two gaps
+that don't survive on model discipline alone:
+
+- prompt-recall (UserPromptSubmit): BM25-match the user's prompt against
+  the store and inject the top hits as context. Recall stops depending on
+  the model thinking to search.
+- stop-guard (Stop): when a substantive session is about to end with zero
+  memory writes, block the stop ONCE with instructions to save durable
+  facts (or finish if nothing qualifies). Capture stops depending on the
+  model remembering unprompted.
+
+Both read the hook payload from stdin, never write to stdout unless they
+have something to inject, and fail silent — a broken store must never
+break the user's session.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Prompts shorter than this can't carry enough signal to search on.
+MIN_PROMPT_CHARS = 20
+# BM25 score below which a match is noise, not recall (empirically, real
+# hits on a ~165-memory store score 8-32; near-misses land around 7).
+MIN_RECALL_SCORE = 8.0
+# Max memories injected per prompt.
+RECALL_TOP_K = 3
+# A session is "substantive" — worth a capture nudge — past this many
+# tool uses. Small sessions rarely produce durable facts.
+GUARD_MIN_TOOL_USES = 25
+
+
+def _find_repo():
+    from .repo import Repository, default_store_candidates
+    for candidate in default_store_candidates():
+        memgit_dir = candidate / '.memgit'
+        if memgit_dir.is_dir():
+            return Repository(memgit_dir)
+    return None
+
+
+def _read_payload() -> dict:
+    try:
+        return json.loads(sys.stdin.read() or '{}')
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _session_cache_dir(repo, kind: str) -> Path:
+    d = repo.path / 'cache' / kind
+    d.mkdir(parents=True, exist_ok=True)
+    try:
+        entries = list(d.iterdir())
+        if len(entries) > 512:  # one file per session; prune the oldest half
+            entries.sort(key=lambda p: p.stat().st_mtime)
+            for old in entries[: len(entries) // 2]:
+                old.unlink(missing_ok=True)
+    except OSError:
+        pass
+    return d
+
+
+def prompt_recall() -> int:
+    """UserPromptSubmit: inject memories relevant to this prompt.
+
+    stdout from a UserPromptSubmit hook is appended to the model's context,
+    so printing IS injecting. Silent (no output) when nothing clears the
+    relevance bar — an empty recall block on every prompt would train the
+    model to ignore the real ones.
+    """
+    payload = _read_payload()
+    prompt = (payload.get('prompt') or '').strip()
+    if len(prompt) < MIN_PROMPT_CHARS or prompt.startswith('/'):
+        return 0
+
+    repo = _find_repo()
+    if repo is None:
+        return 0
+
+    from .project import project_label_from_path
+    from .scorer import score as bm25_score
+
+    cwd = payload.get('cwd') or '.'
+    project = project_label_from_path(Path(cwd))
+
+    try:
+        mnemonics = repo.list()
+        results = bm25_score(prompt, mnemonics, top_k=RECALL_TOP_K,
+                             boost_project=project)
+    except Exception:
+        return 0
+    # BM25 IDF collapses on small corpora (a term found in most of 5 docs
+    # scores near zero), so an absolute bar tuned on a mature store would
+    # silence recall entirely for exactly the users who just adopted.
+    # Ramp the bar up with store size instead.
+    threshold = max(1.0, MIN_RECALL_SCORE * min(1.0, len(mnemonics) / 50))
+    results = [r for r in results if r.score >= threshold]
+    if not results:
+        return 0
+
+    # Don't re-inject what this session has already seen: repeated blocks
+    # burn tokens and dull the signal.
+    seen: set[str] = set()
+    seen_file: Optional[Path] = None
+    session_id = payload.get('session_id')
+    if session_id:
+        try:
+            seen_file = _session_cache_dir(repo, 'recall') / str(session_id)
+            if seen_file.exists():
+                seen = set(seen_file.read_text().split())
+        except OSError:
+            seen_file = None
+    results = [r for r in results if r.mnemonic.slug not in seen]
+    if not results:
+        return 0
+
+    lines = ['<memgit-recall># Saved memories relevant to this request:']
+    for r in results:
+        m = r.mnemonic
+        rule = m.rule if len(m.rule) <= 220 else m.rule[:219] + '…'
+        detail = ' (full detail: get_memory)' if m.body else ''
+        lines.append(f'- [{m.slug}] {rule}{detail}')
+    lines.append('</memgit-recall>')
+    print('\n'.join(lines))
+
+    if seen_file is not None:
+        try:
+            seen.update(r.mnemonic.slug for r in results)
+            seen_file.write_text('\n'.join(sorted(seen)))
+        except OSError:
+            pass
+    return 0
+
+
+# Markers in a transcript that count as "this session captured memory".
+# Anchored to tool_use JSON shapes: the plain tool NAME appears as text in
+# every transcript (the host embeds the tool list), so bare substrings
+# would match always and the guard would never fire.
+import re as _re
+
+_CAPTURE_RES = (
+    _re.compile(r'"name"\s*:\s*"mcp__memgit__save_memory"'),      # MCP save
+    _re.compile(r'"file_path"\s*:\s*"[^"]*/memory/[^"]*\.md'),    # md auto-memory write
+    _re.compile(r'memgit (add|sync)\b'),                          # CLI save/sync
+)
+_TOOL_USE_RE = _re.compile(r'"type"\s*:\s*"tool_use"')
+
+
+def stop_guard() -> int:
+    """Stop: block ending a substantive session that captured nothing.
+
+    Emits {"decision": "block", "reason": ...} at most ONCE per session
+    (marker file + stop_hook_active double-guard), and only when the
+    transcript shows real work with zero memory writes. The reason text
+    explicitly allows finishing without saving when nothing durable was
+    learned — this is a checkpoint, not a shakedown.
+    """
+    payload = _read_payload()
+    if payload.get('stop_hook_active'):
+        return 0
+    transcript_path = payload.get('transcript_path')
+    if not transcript_path:
+        return 0
+
+    repo = _find_repo()
+    if repo is None:
+        return 0
+
+    session_id = payload.get('session_id') or Path(transcript_path).stem
+    try:
+        marker = _session_cache_dir(repo, 'stop-guard') / str(session_id)
+        if marker.exists():
+            return 0
+    except OSError:
+        return 0
+
+    try:
+        text = Path(transcript_path).read_text(encoding='utf-8', errors='replace')
+    except OSError:
+        return 0
+
+    if len(_TOOL_USE_RE.findall(text)) < GUARD_MIN_TOOL_USES:
+        return 0
+    if any(rx.search(text) for rx in _CAPTURE_RES):
+        return 0
+
+    try:
+        marker.write_text('nudged')
+    except OSError:
+        return 0  # if we can't record the nudge, don't risk nudging forever
+
+    print(json.dumps({
+        'decision': 'block',
+        'reason': (
+            'memgit capture check — this session did substantial work but '
+            'saved no memories. Before finishing: if you learned anything '
+            'durable (a decision made, a root cause found, a preference or '
+            'correction from the user, a gotcha in this codebase), save each '
+            'one now with the memgit save_memory tool — one-line rule, full '
+            'detail in body. If genuinely nothing durable was learned, just '
+            'finish your response; this check will not repeat.'
+        ),
+    }))
+    return 0