loop-memory 0.4.0__tar.gz → 0.4.1__tar.gz

{loop_memory-0.4.0 → loop_memory-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.0
+Version: 0.4.1
 Summary: A general-purpose, local memory system for every AI agent you run. Loop Memory auto-captures conversations from Codex / Claude / Hermes / OpenClaw, scores them by importance × recency × usage × feedback, distils them into a curated wiki, and serves everything from a single web UI.
 Author: Loop Memory contributors <loop-memory@users.noreply.github.com>
 License-Expression: MIT
@@ -48,11 +48,14 @@ Dynamic: license-file
 
 # Loop Memory
 
-> **A general-purpose memory system for every AI agent you run locally.**
+> **A general-purpose, local-first memory system that closes the agent loop for every AI agent you run.**
 >
-> Auto-captures every Codex / Claude / Hermes / OpenClaw conversation,
-> distils them into a tight wiki of stable knowledge, and lets the
-> agent recall what matters on demand.
+> Point Loop Memory at any agent's transcript directory and it
+> quietly catches every conversation, scores it, distils the long
+> tail into a tight wiki of stable knowledge, and re-injects the
+> relevant pieces into the next session. Out of the box: hooks for
+> Codex, Claude, Hermes, and OpenClaw; an SDK + generic watcher
+> CLI cover everything else.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/smartfind/loop-memory/tests.yml?branch=main&style=flat-square)](https://github.com/smartfind/loop-memory/actions)
 [![PyPI](https://img.shields.io/pypi/v/loop-memory.svg?style=flat-square)](https://pypi.org/project/loop-memory/)
@@ -66,11 +69,14 @@ Dynamic: license-file
 ## What it does
 
 **Loop Memory** gives every agent you use a single, persistent brain
-that outlives any one conversation. Each agent (Codex CLI, Claude
-Code, Hermes, OpenClaw / clawx, …) drops its transcripts onto disk;
-Loop Memory quietly catches them, scores every fragment by *importance
-× recency × usage × feedback*, distils the long tail into a curated
-wiki, and re-injects the relevant pieces into the next session.
+that outlives any one conversation. Any agent that drops transcripts
+on disk — Codex CLI, Claude Code, Hermes, OpenClaw / clawx, Aider,
+Cursor, … — works; the shipped hooks cover the popular ones and a
+generic watcher CLI (`loop-memory hook --source <name> --watch <dir>`)
+accepts anything else. Loop Memory quietly catches every fragment,
+scores it by *importance × recency × usage × feedback*, distils the
+long tail into a curated wiki, and re-injects the relevant pieces
+into the next session.
 
 ```mermaid
 flowchart LR
@@ -142,7 +148,7 @@ following — every other project we looked at lacks at least one:
 
 | Capability | **Loop Memory** | Mem0 v3 | Hindsight | OpenViking | A-MEM |
 | --- | --- | --- | --- | --- | --- |
-| Multi-source capture (Codex / Claude / Hermes / OpenClaw) | ✅ out of the box | ⚠ requires plugin per client | ⚠ hosted only | ⚠ SDK + companion app | ❌ |
+| Multi-source capture (any agent with on-disk transcripts) | ✅ generic watcher CLI; hooks shipped for Codex / Claude / Hermes / OpenClaw | ⚠ requires plugin per client | ⚠ hosted only | ⚠ SDK + companion app | ❌ |
 | Local-first SQLite (zero external services) | ✅ | ❌ Postgres + Qdrant | ❌ Postgres + Qdrant | ⚠ file-system + cloud | ⚠ ChromaDB |
 | Hybrid recall: BM25 + semantic + entity (RRF) | ✅ | ✅ | ✅ | ✅ | ⚠ entity-only |
 | Temporal reasoning in retrieval (boost / suppress by date intent) | ✅ | ✅ | ❌ | ❌ | ❌ |

{loop_memory-0.4.0 → loop_memory-0.4.1}/README.md

@@ -4,11 +4,14 @@
 
 # Loop Memory
 
-> **A general-purpose memory system for every AI agent you run locally.**
+> **A general-purpose, local-first memory system that closes the agent loop for every AI agent you run.**
 >
-> Auto-captures every Codex / Claude / Hermes / OpenClaw conversation,
-> distils them into a tight wiki of stable knowledge, and lets the
-> agent recall what matters on demand.
+> Point Loop Memory at any agent's transcript directory and it
+> quietly catches every conversation, scores it, distils the long
+> tail into a tight wiki of stable knowledge, and re-injects the
+> relevant pieces into the next session. Out of the box: hooks for
+> Codex, Claude, Hermes, and OpenClaw; an SDK + generic watcher
+> CLI cover everything else.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/smartfind/loop-memory/tests.yml?branch=main&style=flat-square)](https://github.com/smartfind/loop-memory/actions)
 [![PyPI](https://img.shields.io/pypi/v/loop-memory.svg?style=flat-square)](https://pypi.org/project/loop-memory/)
@@ -22,11 +25,14 @@
 ## What it does
 
 **Loop Memory** gives every agent you use a single, persistent brain
-that outlives any one conversation. Each agent (Codex CLI, Claude
-Code, Hermes, OpenClaw / clawx, …) drops its transcripts onto disk;
-Loop Memory quietly catches them, scores every fragment by *importance
-× recency × usage × feedback*, distils the long tail into a curated
-wiki, and re-injects the relevant pieces into the next session.
+that outlives any one conversation. Any agent that drops transcripts
+on disk — Codex CLI, Claude Code, Hermes, OpenClaw / clawx, Aider,
+Cursor, … — works; the shipped hooks cover the popular ones and a
+generic watcher CLI (`loop-memory hook --source <name> --watch <dir>`)
+accepts anything else. Loop Memory quietly catches every fragment,
+scores it by *importance × recency × usage × feedback*, distils the
+long tail into a curated wiki, and re-injects the relevant pieces
+into the next session.
 
 ```mermaid
 flowchart LR
@@ -98,7 +104,7 @@ following — every other project we looked at lacks at least one:
 
 | Capability | **Loop Memory** | Mem0 v3 | Hindsight | OpenViking | A-MEM |
 | --- | --- | --- | --- | --- | --- |
-| Multi-source capture (Codex / Claude / Hermes / OpenClaw) | ✅ out of the box | ⚠ requires plugin per client | ⚠ hosted only | ⚠ SDK + companion app | ❌ |
+| Multi-source capture (any agent with on-disk transcripts) | ✅ generic watcher CLI; hooks shipped for Codex / Claude / Hermes / OpenClaw | ⚠ requires plugin per client | ⚠ hosted only | ⚠ SDK + companion app | ❌ |
 | Local-first SQLite (zero external services) | ✅ | ❌ Postgres + Qdrant | ❌ Postgres + Qdrant | ⚠ file-system + cloud | ⚠ ChromaDB |
 | Hybrid recall: BM25 + semantic + entity (RRF) | ✅ | ✅ | ✅ | ✅ | ⚠ entity-only |
 | Temporal reasoning in retrieval (boost / suppress by date intent) | ✅ | ✅ | ❌ | ❌ | ❌ |

loop_memory-0.4.1/loop_memory/cli/main.py

@@ -0,0 +1,184 @@
+"""CLI for Loop Memory.
+
+Usage:
+
+    loop-memory chat              # REPL with echo LLM
+    loop-memory stats             # counters
+    loop-memory recall <text>     # show top memories
+    loop-memory ingest codex      # ingest local Codex transcripts
+    loop-memory ingest claude     # ingest local Claude Code transcripts
+    loop-memory ingest hermes     # ingest Hermes transcripts
+    loop-memory consolidate       # rescore + GC + dedupe
+    loop-memory rescore [--half-life 30]
+    loop-memory serve [--port 7767] # start the local web UI
+    loop-memory mcp                # stdio MCP server (for codex/claude/hermes)
+    loop-memory inject [query]     # dump long-term context block (for SessionStart hooks)
+    loop-memory install-hooks      # auto-write MCP + SessionStart hooks for known clients
+    loop-memory consolidate-now    # ask the running server to trigger a pass right now
+    loop-memory export             # legacy markdown export (no positional path)
+    loop-memory digest [--out PATH] # compact knowledge digest for AGENTS.md (≤ max-chars bytes)
+    loop-memory ask "what about…"  # print a paste-ready context block for any LLM client
+    loop-memory cognitive-sleep [--apply]  # dry-run / apply cognitive sweep (v7)
+    loop-memory audit [--kind X] [--action Y]  # read the cognitive audit trail
+    loop-memory export <out_dir>  # write a MEMORY.md bundle (v7)
+    loop-memory export-bundle <out_dir>  # explicit v7 bundle alias
+    loop-memory import <in_dir>   # re-hydrate a bundle
+    loop-memory fork [--branch-tag T]  # snapshot every wiki page
+    loop-memory graph-edge <src> <dst> [--kind K] [--weight W]  # push a relation
+    loop-memory subgraph <query>  # print a small subgraph
+    loop-memory graph-rebuild  # rebuild entities + entity_mentions
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .commands import cognitive as cognitive_cmd
+from .commands import diag as diag_cmd
+from .commands import graph as graph_cmd
+from .commands import hooks as hooks_cmd
+from .commands import read as read_cmd
+from .commands import serve as serve_cmd
+from .commands import write as write_cmd
+
+# Backwards-compatible re-exports. Earlier tests imported these
+# private symbols from this module; keep the names available so
+# external code doesn't break after the 0.3.0 split.
+_upsert_block = hooks_cmd._upsert_block
+cmd_inject = read_cmd.run_inject
+
+
+def _run_export(args: list[str]) -> int:
+    """Keep the legacy markdown export and expose the v7 bundle export.
+
+    A positional output directory selects the v7 bundle. The historical
+    ``--out`` / ``--q`` form remains available so existing scripts keep
+    producing a single markdown file.
+    """
+    if not args or any(flag in args for flag in ("--out", "--q")):
+        return read_cmd.run_export(args)
+    return cognitive_cmd.run_export(args)
+
+
+def _run_version(_args: list[str]) -> int:
+    """Print the installed distribution version.
+
+    Resolved through :mod:`importlib.metadata` so the answer comes from
+    whatever wheel or sdist the user actually has installed, including
+    editable installs (``pip install -e .``). Falls back to ``"unknown"``
+    if the package metadata is missing (which would itself indicate a
+    broken install).
+    """
+    from importlib import metadata as _ilmd
+    try:
+        ver = _ilmd.version("loop-memory")
+    except _ilmd.PackageNotFoundError:
+        ver = "unknown"
+    print(f"loop-memory {ver}")
+    return 0
+
+
+# Dispatch table: command name -> (callable, optional module doc).
+# Each module's ``run_<name>`` function takes ``args: list[str]`` and
+# returns an integer exit code. Keep the keys matching the docstring
+# at the top of this file.
+COMMANDS = {
+    "chat": read_cmd.run_chat,
+    "stats": read_cmd.run_stats,
+    "recall": read_cmd.run_recall,
+    "ingest": write_cmd.run_ingest,
+    "consolidate": write_cmd.run_consolidate,
+    "consolidate-now": write_cmd.run_consolidate_now,
+    "export": _run_export,
+    "digest": read_cmd.run_digest,
+    "ask": read_cmd.run_ask,
+    "rescore": write_cmd.run_rescore,
+    "serve": serve_cmd.run_serve,
+    "hook": serve_cmd.run_hook,
+    "mcp": serve_cmd.run_mcp,
+    "inject": read_cmd.run_inject,
+    "install-hooks": hooks_cmd.run_install_hooks,
+    "flush": write_cmd.run_flush,
+    "graph": graph_cmd.run_graph,
+    "doctor": diag_cmd.run_doctor,
+    "status": diag_cmd.run_status,
+    "openclaw-setup": diag_cmd.run_openclaw_setup,
+    # Universal Agent Memory v7 — graph, cognitive, export, fork
+    "cognitive-sleep": cognitive_cmd.run_cognitive_sleep,
+    "audit": cognitive_cmd.run_audit,
+    "export-bundle": cognitive_cmd.run_export,
+    "import": cognitive_cmd.run_import,
+    "fork": cognitive_cmd.run_fork,
+    "graph-edge": cognitive_cmd.run_graph_edge,
+    "subgraph": cognitive_cmd.run_subgraph,
+    "graph-rebuild": cognitive_cmd.run_graph_rebuild,
+    "wiki-reclassify-legacy": cognitive_cmd.run_wiki_reclassify_legacy,
+    "version": _run_version,
+}
+
+
+# Per-command usage lines. The dispatcher prints these on
+# ``<subcommand> --help`` *without* invoking the handler, so missing
+# optional deps (e.g. ``[serve]`` for fastapi) and missing required
+# positional args never crash the help path.
+COMMAND_HELP: dict[str, str] = {
+    "ask":                    "loop-memory ask '<question>'   # print a paste-ready context block for any LLM client.",
+    "audit":                  "loop-memory audit [--kind X] [--action Y]   # read the cognitive audit trail.",
+    "chat":                   "loop-memory chat   # REPL with echo LLM.",
+    "cognitive-sleep":        "loop-memory cognitive-sleep [--apply]   # dry-run / apply cognitive sweep.",
+    "consolidate":            "loop-memory consolidate   # rescore + GC + dedupe.",
+    "consolidate-now":        "loop-memory consolidate-now   # ask the running server to trigger a pass right now.",
+    "digest":                 "loop-memory digest [--out PATH]   # compact knowledge digest for AGENTS.md.",
+    "doctor":                 "loop-memory doctor   # diagnose local install (db, hooks, optional deps).",
+    "export":                 "loop-memory export [--out FILE | <out_dir>]   # markdown dump or v7 bundle export.",
+    "export-bundle":          "loop-memory export-bundle <out_dir>   # explicit v7 bundle alias.",
+    "flush":                  "loop-memory flush   # drop volatile caches; keep persisted data.",
+    "fork":                   "loop-memory fork [--branch-tag T]   # snapshot every wiki page.",
+    "graph":                  "loop-memory graph   # print the entities + relations table.",
+    "graph-edge":             "loop-memory graph-edge <src> <dst> [--kind K] [--weight W]   # push a relation.",
+    "graph-rebuild":          "loop-memory graph-rebuild   # rebuild entities + entity_mentions.",
+    "hook":                   "loop-memory hook --source <codex|claude|hermes|openclaw> --watch <path> [--idle SECONDS]\n  Watch a directory for new transcripts and ingest them.",
+    "import":                 "loop-memory import <in_dir>   # re-hydrate a v7 bundle.",
+    "ingest":                 "loop-memory ingest {codex|claude|hermes|openclaw}\n  Ingest transcripts from a local source into the SQLite store.",
+    "inject":                 "loop-memory inject [query]   # dump long-term context block (for SessionStart hooks).",
+    "install-hooks":          "loop-memory install-hooks   # auto-write MCP + SessionStart hooks for known clients.",
+    "mcp":                    "loop-memory mcp   # stdio MCP server (for codex/claude/hermes). Requires ``[serve]`` for HTTP transport.",
+    "openclaw-setup":         "loop-memory openclaw-setup   # install the openclaw/clawx auto-ingest watcher (launchd on macOS).",
+    "recall":                 "loop-memory recall <text>   # show top memories.",
+    "rescore":                "loop-memory rescore [--half-life 30]   # recompute memory scores.",
+    "serve":                  "loop-memory serve [--port 7767] [--no-browser]   # start the local web UI. Requires the ``[serve]`` extra (fastapi + uvicorn).",
+    "stats":                  "loop-memory stats   # counters.",
+    "status":                 "loop-memory status   # one-shot summary of ingest / recall / serve / hook state.",
+    "subgraph":               "loop-memory subgraph <query>   # print a small subgraph.",
+    "version":                "loop-memory version   # print the installed distribution version.",
+    "wiki-reclassify-legacy": "loop-memory wiki-reclassify-legacy   # back-fill scope + scope_filter for H4+H5 pages.",
+}
+
+
+
+def main(argv: list | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help"}:
+        print(__doc__)
+        return 0
+    if args[0] in {"-V", "--version"}:
+        return _run_version(args[1:])
+    cmd, rest = args[0], args[1:]
+    # Per-subcommand --help / -h: print the static help line and exit 0
+    # *without* invoking the handler. Avoids ValueError on ingest (when
+    # ``--help`` would be treated as a source name) and ModuleNotFoundError
+    # on serve (when [serve] is not installed). Each handler that wants
+    # richer help can still implement it locally — our interceptor is a
+    # fallback.
+    if rest and rest[0] in {"-h", "--help"} and cmd in COMMAND_HELP:
+        print(COMMAND_HELP[cmd])
+        return 0
+    fn = COMMANDS.get(cmd)
+    if fn is None:
+        print(f"unknown command: {cmd}", file=sys.stderr)
+        return 2
+    return fn(rest)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{loop_memory-0.4.0 → loop_memory-0.4.1}/loop_memory/serve/static/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>循环记忆 · Loop Memory</title>
-  <meta name="description" content="Loop Memory — local-first memory loop for Codex, Claude, Hermes and OpenClaw. Capture, distill and recall your AI conversation knowledge." />
+  <meta name="description" content="Loop Memory — local-first memory system that closes the agent loop for every AI agent. Hooks for Codex / Claude / Hermes / OpenClaw; SDK + generic watcher CLI for the rest." />
   <link rel="stylesheet" href="static/css/app.css" />
   <link rel="stylesheet" href="static/css/layout.css" />
 </head>

{loop_memory-0.4.0 → loop_memory-0.4.1}/loop_memory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.0
+Version: 0.4.1
 Summary: A general-purpose, local memory system for every AI agent you run. Loop Memory auto-captures conversations from Codex / Claude / Hermes / OpenClaw, scores them by importance × recency × usage × feedback, distils them into a curated wiki, and serves everything from a single web UI.
 Author: Loop Memory contributors <loop-memory@users.noreply.github.com>
 License-Expression: MIT
@@ -48,11 +48,14 @@ Dynamic: license-file
 
 # Loop Memory
 
-> **A general-purpose memory system for every AI agent you run locally.**
+> **A general-purpose, local-first memory system that closes the agent loop for every AI agent you run.**
 >
-> Auto-captures every Codex / Claude / Hermes / OpenClaw conversation,
-> distils them into a tight wiki of stable knowledge, and lets the
-> agent recall what matters on demand.
+> Point Loop Memory at any agent's transcript directory and it
+> quietly catches every conversation, scores it, distils the long
+> tail into a tight wiki of stable knowledge, and re-injects the
+> relevant pieces into the next session. Out of the box: hooks for
+> Codex, Claude, Hermes, and OpenClaw; an SDK + generic watcher
+> CLI cover everything else.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/smartfind/loop-memory/tests.yml?branch=main&style=flat-square)](https://github.com/smartfind/loop-memory/actions)
 [![PyPI](https://img.shields.io/pypi/v/loop-memory.svg?style=flat-square)](https://pypi.org/project/loop-memory/)
@@ -66,11 +69,14 @@ Dynamic: license-file
 ## What it does
 
 **Loop Memory** gives every agent you use a single, persistent brain
-that outlives any one conversation. Each agent (Codex CLI, Claude
-Code, Hermes, OpenClaw / clawx, …) drops its transcripts onto disk;
-Loop Memory quietly catches them, scores every fragment by *importance
-× recency × usage × feedback*, distils the long tail into a curated
-wiki, and re-injects the relevant pieces into the next session.
+that outlives any one conversation. Any agent that drops transcripts
+on disk — Codex CLI, Claude Code, Hermes, OpenClaw / clawx, Aider,
+Cursor, … — works; the shipped hooks cover the popular ones and a
+generic watcher CLI (`loop-memory hook --source <name> --watch <dir>`)
+accepts anything else. Loop Memory quietly catches every fragment,
+scores it by *importance × recency × usage × feedback*, distils the
+long tail into a curated wiki, and re-injects the relevant pieces
+into the next session.
 
 ```mermaid
 flowchart LR
@@ -142,7 +148,7 @@ following — every other project we looked at lacks at least one:
 
 | Capability | **Loop Memory** | Mem0 v3 | Hindsight | OpenViking | A-MEM |
 | --- | --- | --- | --- | --- | --- |
-| Multi-source capture (Codex / Claude / Hermes / OpenClaw) | ✅ out of the box | ⚠ requires plugin per client | ⚠ hosted only | ⚠ SDK + companion app | ❌ |
+| Multi-source capture (any agent with on-disk transcripts) | ✅ generic watcher CLI; hooks shipped for Codex / Claude / Hermes / OpenClaw | ⚠ requires plugin per client | ⚠ hosted only | ⚠ SDK + companion app | ❌ |
 | Local-first SQLite (zero external services) | ✅ | ❌ Postgres + Qdrant | ❌ Postgres + Qdrant | ⚠ file-system + cloud | ⚠ ChromaDB |
 | Hybrid recall: BM25 + semantic + entity (RRF) | ✅ | ✅ | ✅ | ✅ | ⚠ entity-only |
 | Temporal reasoning in retrieval (boost / suppress by date intent) | ✅ | ✅ | ❌ | ❌ | ❌ |

{loop_memory-0.4.0 → loop_memory-0.4.1}/loop_memory.egg-info/SOURCES.txt

@@ -90,6 +90,7 @@ tests/test_agent_memory_api.py
 tests/test_agent_memory_sdk.py
 tests/test_auth_token_rotate.py
 tests/test_cli_v7.py
+tests/test_cli_version.py
 tests/test_contradictions.py
 tests/test_evolution.py
 tests/test_evolution_quality.py
@@ -106,6 +107,7 @@ tests/test_mcp.py
 tests/test_memories_pagination.py
 tests/test_openclaw_loader.py
 tests/test_reflection.py
+tests/test_repo_framing.py
 tests/test_score_api.py
 tests/test_scoring_v2.py
 tests/test_secrets.py

{loop_memory-0.4.0 → loop_memory-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loop-memory"
-version = "0.4.0"
+version = "0.4.1"
 description = "A general-purpose, local memory system for every AI agent you run. Loop Memory auto-captures conversations from Codex / Claude / Hermes / OpenClaw, scores them by importance × recency × usage × feedback, distils them into a curated wiki, and serves everything from a single web UI."
 readme = "README.md"
 requires-python = ">=3.10"

loop_memory-0.4.1/tests/test_cli_version.py

@@ -0,0 +1,130 @@
+"""Regression tests for the ``loop-memory --version`` family of flags.
+
+Before this fix, ``loop-memory --version`` returned ``unknown command:
+--version`` which tripped users on the most basic operation a CLI
+must support. These tests pin all three forms (``--version``, ``-V``,
+``version``) and assert the printed value matches the installed
+distribution's metadata.
+"""
+from __future__ import annotations
+
+import io
+import sys
+import unittest
+from contextlib import redirect_stdout
+from importlib import metadata as importlib_metadata
+
+from loop_memory.cli.main import main
+
+
+def _run(args: list[str]) -> tuple[int, str]:
+    """Run ``loop-memory <args>`` and return ``(rc, stdout)``."""
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = main(args)
+    return rc, buf.getvalue()
+
+
+class CliVersionTests(unittest.TestCase):
+    def test_dash_dash_version_prints_distribution_version(self) -> None:
+        expected = importlib_metadata.version("loop-memory")
+        rc, out = _run(["--version"])
+        self.assertEqual(rc, 0, out)
+        self.assertIn(expected, out.strip(), out)
+        # The output should be human-friendly: at minimum include the package name.
+        self.assertIn("loop-memory", out)
+
+    def test_dash_V_short_flag_also_works(self) -> None:
+        rc, out = _run(["-V"])
+        self.assertEqual(rc, 0, out)
+        self.assertIn(importlib_metadata.version("loop-memory"), out.strip(), out)
+
+    def test_version_subcommand_also_works(self) -> None:
+        rc, out = _run(["version"])
+        self.assertEqual(rc, 0, out)
+        self.assertIn(importlib_metadata.version("loop-memory"), out.strip(), out)
+
+    def test_version_does_not_require_a_database(self) -> None:
+        """``version`` must work even when ``$LOOP_MEMORY_DB`` points
+        somewhere nonexistent — it is a metadata-only probe.
+        """
+        # Save and unset
+        prev = sys.modules.pop("loop_memory.storage.sqlite_store", None)
+        try:
+            rc, out = _run(["version"])
+            self.assertEqual(rc, 0, out)
+        finally:
+            if prev is not None:
+                sys.modules["loop_memory.storage.sqlite_store"] = prev
+
+
+
+
+
+class CliSubcommandHelpTests(unittest.TestCase):
+    """Pin dispatcher behaviour for ``<subcommand> --help`` / ``-h``.
+
+    The install smoke test caught three real bugs against the
+    published 0.4.0 wheel:
+
+    * ``ingest --help`` crashed with ``ValueError: unknown source:
+      '--help'`` because the handler treated ``--help`` as a source name.
+    * ``serve --help`` crashed with ``ModuleNotFoundError: No module
+      named 'fastapi'`` because the [serve] extra wasn't installed
+      (the handler lazy-imports fastapi). Users on a base install
+      couldn't read serve's help text.
+    * ``hook --help`` returned rc=2 from the ``die()`` helper even
+      though it printed the correct usage line.
+
+    The dispatcher now intercepts ``-h`` / ``--help`` AFTER the
+    subcommand name and prints a static help line, never invoking
+    the handler — so all three forms exit cleanly with rc=0 even on
+    a ``pip install loop-memory`` (no [serve] extra) install.
+    """
+
+    def _run(self, args: list[str]) -> tuple[int, str]:
+        import io
+        from contextlib import redirect_stdout
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            rc = main(args)
+        return rc, buf.getvalue()
+
+    def test_ingest_help_does_not_crash_with_value_error(self) -> None:
+        rc, out = self._run(["ingest", "--help"])
+        self.assertEqual(rc, 0, out)
+        self.assertIn("ingest", out.lower())
+
+    def test_serve_help_works_without_serve_extra(self) -> None:
+        """Must not require the [serve] extra to be installed."""
+        rc, out = self._run(["serve", "--help"])
+        self.assertEqual(rc, 0, out)
+        self.assertIn("serve", out.lower())
+
+    def test_hook_help_returns_zero(self) -> None:
+        rc, out = self._run(["hook", "--help"])
+        self.assertEqual(rc, 0, out)
+        self.assertIn("hook", out.lower())
+
+    def test_short_form_dash_h_also_works(self) -> None:
+        rc, _ = self._run(["ingest", "-h"])
+        self.assertEqual(rc, 0)
+
+    def test_unknown_subcommand_still_returns_2(self) -> None:
+        """Make sure the help interceptor doesn't swallow real
+        unknown-command errors.
+        """
+        rc, _ = self._run(["totally-not-a-command", "--help"])
+        self.assertEqual(rc, 2)
+
+    def test_every_registered_subcommand_has_help_text(self) -> None:
+        """Every COMMANDS entry MUST have a corresponding help string
+        so a fresh user can ``--help`` any subcommand without surprises.
+        """
+        from loop_memory.cli import main as cli_main
+        missing = sorted(c for c in cli_main.COMMANDS if c not in cli_main.COMMAND_HELP)
+        self.assertEqual(missing, [], f"missing COMMAND_HELP for: {missing}")
+
+
+if __name__ == "__main__":
+    unittest.main()