loop-memory 0.4.12__tar.gz → 0.4.14__tar.gz

{loop_memory-0.4.12 → loop_memory-0.4.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.12
+Version: 0.4.14
 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
@@ -66,6 +66,10 @@ Dynamic: license-file
 
 ---
 
+> **What's new in 0.4.14** — **`loop-memory doctor` deep store-health check** (audit 2026-10-12). Ten diagnostic checks — `db_exists`, `db_integrity`, `schema_version`, `audit_triggers`, `audit_log_writable`, `audit_log_size`, `hooks_installed`, `version_consistent`, `wiki_no_orphans`, `recall_paths_works` — report `ok`/`info`/`warn`/`error` for the live `MemoryStore`. `--fix` auto-repairs the `audit_triggers` check. `--json` emits a stable shape for CI. `--list` prints the check function names without touching the store. `--verbose` shows `info`-level checks. Exit code `1` on any `error` status, `0` otherwise. Source: `cortexkit/magic-context doctor` auto-diagnostic pattern (MIT, 2026-10-12) + `dsh-memento` write-approval-gate pattern (Apache-2.0, 2026-10-12). Stdlib-only — we re-implement from scratch against our own `MemoryStore`. Also fixed a Python 3.14 bug: chained `store._conn().__enter__()` immediately triggers the contextmanager's `finally` and closes the connection mid-query — both call sites in `doctor.py` now use explicit `with` form. 27 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0414---2026-10-12)
+
+> **What's new in 0.4.13** — **recall token / char budget cap** + **unified `level=0|1|2` tiered-loader knob** (audit 2026-10-05). New `max_chars` parameter on `MemoryStore.recall()` / `recall_paths()` / `recall_hybrid()` / `recall_as_of()` caps the *total* payload across all returned hits — when the budget is exceeded the lowest-ranked hit shrinks first so the top-scoring hits always keep their full body. `recall()` / `recall_paths()` / `recall_as_of()` now also accept `level=0|1|2` so a caller can ask for the L0 abstract ladder rung inline (titles + tags + abstract only, never the full `text` / `body`) without routing through `recall_paths()` separately. Both knobs are wired through the HTTP routes (`GET /api/recall?max_chars=&level=`, `GET /api/recall/outline?max_chars=`), the CLI (`loop-memory recall --max-chars N --level 0|1|2`, `recall-paths --max-chars N`), the SDK (`LoopMemoryClient.recall(max_chars=, level=)`), and the MCP `tool_recall` server. Source: `vectorize-io/hindsight v0.10.2` "concise extraction by default" (Apache-2.0, 2026-09-29) + `aiming-lab/SimpleMem` ICML'26 semantic-lossless-compression (Apache-2.0, 2026-10-04) + `volcengine/OpenViking` tiered-loader (AGPLv3, 2026-10-02 — *pattern only, no code copied*). 26 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0413---2026-10-05)
+
 > **What's new in 0.4.12** — **OKF bundle import** + **DB-level audit enforcement** (audit 2026-09-27). The new `loop-memory import-okf <in_dir>` (and `POST /api/import/okf`) is the symmetric counterpart to `export-okf` (0.4.9) — bring an OKF v0.2 bundle back into Loop Memory as wiki pages, with idempotent upsert on `(scope, slug)`, optional `--dry-run` and `--skip-conflicts`. Source: `thecolourfoundation/rune` HN launch (MIT, 2026-09-25) + `okf-memory/okf-agent-memory` Issues #12-#15 + `Deja-Vu` (MIT, 2026-09-24) + Google OKF v0.2 spec (Apache-2.0, 2026-09-01). The new `MemoryStore._install_audit_triggers()` installs 12 SQLite triggers on `memories` / `wiki_pages` / `relations` / `consolidation_runs` so the `audit_log` table cannot be skipped — even a raw `sqlite3` writer that bypasses the Python wrapper still appends an audit row with `actor='db_trigger'`. New `MemoryStore.list_audit_log()` reads the log; `GET /api/stats` reports `audit_log` + `audit_triggers` counts. Source: `cogstate-eng/memory-eternal v0.4.3` `enforceAudit()` pattern (MIT, 2026-09-23). 31 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0412---2026-09-27)
 
 > **What's new in 0.4.11** — **operational probes** +

{loop_memory-0.4.12 → loop_memory-0.4.14}/README.md

@@ -22,6 +22,10 @@
 
 ---
 
+> **What's new in 0.4.14** — **`loop-memory doctor` deep store-health check** (audit 2026-10-12). Ten diagnostic checks — `db_exists`, `db_integrity`, `schema_version`, `audit_triggers`, `audit_log_writable`, `audit_log_size`, `hooks_installed`, `version_consistent`, `wiki_no_orphans`, `recall_paths_works` — report `ok`/`info`/`warn`/`error` for the live `MemoryStore`. `--fix` auto-repairs the `audit_triggers` check. `--json` emits a stable shape for CI. `--list` prints the check function names without touching the store. `--verbose` shows `info`-level checks. Exit code `1` on any `error` status, `0` otherwise. Source: `cortexkit/magic-context doctor` auto-diagnostic pattern (MIT, 2026-10-12) + `dsh-memento` write-approval-gate pattern (Apache-2.0, 2026-10-12). Stdlib-only — we re-implement from scratch against our own `MemoryStore`. Also fixed a Python 3.14 bug: chained `store._conn().__enter__()` immediately triggers the contextmanager's `finally` and closes the connection mid-query — both call sites in `doctor.py` now use explicit `with` form. 27 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0414---2026-10-12)
+
+> **What's new in 0.4.13** — **recall token / char budget cap** + **unified `level=0|1|2` tiered-loader knob** (audit 2026-10-05). New `max_chars` parameter on `MemoryStore.recall()` / `recall_paths()` / `recall_hybrid()` / `recall_as_of()` caps the *total* payload across all returned hits — when the budget is exceeded the lowest-ranked hit shrinks first so the top-scoring hits always keep their full body. `recall()` / `recall_paths()` / `recall_as_of()` now also accept `level=0|1|2` so a caller can ask for the L0 abstract ladder rung inline (titles + tags + abstract only, never the full `text` / `body`) without routing through `recall_paths()` separately. Both knobs are wired through the HTTP routes (`GET /api/recall?max_chars=&level=`, `GET /api/recall/outline?max_chars=`), the CLI (`loop-memory recall --max-chars N --level 0|1|2`, `recall-paths --max-chars N`), the SDK (`LoopMemoryClient.recall(max_chars=, level=)`), and the MCP `tool_recall` server. Source: `vectorize-io/hindsight v0.10.2` "concise extraction by default" (Apache-2.0, 2026-09-29) + `aiming-lab/SimpleMem` ICML'26 semantic-lossless-compression (Apache-2.0, 2026-10-04) + `volcengine/OpenViking` tiered-loader (AGPLv3, 2026-10-02 — *pattern only, no code copied*). 26 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0413---2026-10-05)
+
 > **What's new in 0.4.12** — **OKF bundle import** + **DB-level audit enforcement** (audit 2026-09-27). The new `loop-memory import-okf <in_dir>` (and `POST /api/import/okf`) is the symmetric counterpart to `export-okf` (0.4.9) — bring an OKF v0.2 bundle back into Loop Memory as wiki pages, with idempotent upsert on `(scope, slug)`, optional `--dry-run` and `--skip-conflicts`. Source: `thecolourfoundation/rune` HN launch (MIT, 2026-09-25) + `okf-memory/okf-agent-memory` Issues #12-#15 + `Deja-Vu` (MIT, 2026-09-24) + Google OKF v0.2 spec (Apache-2.0, 2026-09-01). The new `MemoryStore._install_audit_triggers()` installs 12 SQLite triggers on `memories` / `wiki_pages` / `relations` / `consolidation_runs` so the `audit_log` table cannot be skipped — even a raw `sqlite3` writer that bypasses the Python wrapper still appends an audit row with `actor='db_trigger'`. New `MemoryStore.list_audit_log()` reads the log; `GET /api/stats` reports `audit_log` + `audit_triggers` counts. Source: `cogstate-eng/memory-eternal v0.4.3` `enforceAudit()` pattern (MIT, 2026-09-23). 31 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0412---2026-09-27)
 
 > **What's new in 0.4.11** — **operational probes** +

{loop_memory-0.4.12 → loop_memory-0.4.14}/loop_memory/cli/commands/diag.py

@@ -133,95 +133,18 @@ def _detect_watcher() -> bool:
 
 
 def run_doctor(_args) -> int:
-    """``loop-memory doctor`` — green/red diagnostic screen.
-
-    Tells the user what's installed, what's wired, what's broken, and
-    gives copy-pasteable fix commands for anything red.
+    """`loop-memory doctor` — deep store-health check.
+
+    Audit 2026-10-12.  Delegates to :mod:`loop_memory.doctor` which runs
+    a small library of health checks against the live
+    `MemoryStore` and renders a human-readable report.  Exits
+    non-zero if any check is in 'error' state.  Source:
+    cortexkit/magic-context doctor (MIT, 2026-10-12) +
+    PerryLink/dsh-memento dsh-plugin-doctor (Apache-2.0,
+    2026-10-12) — pattern only.
     """
-    print("loop-memory doctor\n")
-    # 1) Installation
-    cli_path = shutil.which("loop-memory")
-    print(_dot(cli_path is not None,
-               f"CLI on PATH: {'yes (' + cli_path + ')' if cli_path else 'no'}"))
-    # 2) Database
-    db_path = Path(DEFAULT_DB)
-    print(_dot(db_path.exists(),
-               f"database: {db_path}" + ("" if db_path.exists() else "  (will be created on first run)")))
-    # 3) Server
-    server_running = False
-    try:
-        import urllib.request
-        with urllib.request.urlopen("http://127.0.0.1:7767/api/stats", timeout=1) as r:
-            server_running = r.status == 200
-    except Exception:
-        server_running = False
-    print(_dot(server_running,
-               "web UI server: http://127.0.0.1:7767" + (" (running)" if server_running else " (not running — start with `loop-memory serve &`)")))
-
-    # 4) Clients
-    print()
-    print("clients:")
-    clients = _detect_clients()
-    for name in ("codex", "claude", "hermes", "openclaw"):
-        info = clients[name]
-        if name == "openclaw":
-            print(_dot(info["installed"],
-                       f"  openclaw: {'installed' if info['installed'] else 'not installed'}"))
-            if info["installed"]:
-                paths = ", ".join(Path(p).name for p in info["watch_paths"]) or "no transcript paths found"
-                print(f"      {paths}")
-                print(_dot(_detect_watcher(),
-                           "      watcher running" if _detect_watcher() else "      watcher not running — start with `loop-memory openclaw-setup`"))
-        else:
-            cfg = info["config"]
-            installed = info["installed"]
-            cfg_str = f"@ {cfg}" if installed else ""
-            print(_dot(installed,
-                       f"  {name}: {'installed' if installed else 'not installed'} {cfg_str}"))
-            if installed:
-                print(_dot(info["mcp_configured"],
-                           f"      MCP server wired: {'yes' if info['mcp_configured'] else 'no — run `loop-memory install-hooks`'}"))
-
-    # 5) LLM provider
-    print()
-    print("LLM provider:")
-    try:
-        from ...storage.sqlite_store import MemoryStore
-        from ...llm.providers import default_config
-        from ...security import backend_display_name, has_secret
-        store = MemoryStore(DEFAULT_DB)
-        cfg = store.get_setting("llm_consolidator", default_config())
-        provider = cfg.get("provider") or "echo"
-        print(f"  provider: {provider}")
-        print(f"  model: {cfg.get('model', '—')}")
-        print(f"  secret backend: {backend_display_name()}")
-        if provider != "echo":
-            from ...security import account_for
-            account = cfg.get("api_key_account") or account_for(provider)
-            has = has_secret(account)
-            print(_dot(has,
-                       f"  API key: {'configured' if has else 'MISSING — open the web UI → ⚙ Model → paste your key'}"))
-    except Exception as e:
-        print(_dot(False, f"  could not read LLM config: {e}"))
-
-    # 6) Data summary
-    print()
-    print("data:")
-    try:
-        from ...storage.sqlite_store import MemoryStore
-        store = MemoryStore(DEFAULT_DB)
-        n_mem = store.count_memories()
-        n_sess = store.count_sessions()
-        n_wiki = store.count_wiki_pages()
-        n_ent = store.count_entities()
-        print(f"  {n_mem} memories · {n_sess} sessions · {n_wiki} wiki pages · {n_ent} entities")
-    except Exception as e:
-        print(f"  could not read counters: {e}")
-
-    print()
-    print(_DIM + "Tip: run `loop-memory status` for a one-screen summary, "
-          "or `loop-memory install-hooks` to auto-configure your CLIs." + _RESET)
-    return 0
+    from . import doctor as _doctor_cli
+    return _doctor_cli.run_doctor(list(_args))
 
 
 def run_status(_args) -> int:

loop_memory-0.4.14/loop_memory/cli/commands/doctor.py

@@ -0,0 +1,144 @@
+"""``loop-memory doctor`` subcommand.
+
+Audit 2026-10-12.  Wraps :mod:`loop_memory.doctor` and renders the
+result for a human or as JSON.  See ``loop_memory/doctor.py`` for
+the check library and the source attribution.
+
+Usage examples::
+
+    loop-memory doctor                       # human-readable report
+    loop-memory doctor --json                # machine-readable report
+    loop-memory doctor --verbose             # also show INFO-level checks
+    loop-memory doctor --fix                 # auto-repair auto_fixable checks
+    loop-memory doctor --db /path/to/store.db  # run against a specific DB
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from .._common import die
+from ... import doctor as _doctor
+from ...storage.sqlite_store import MemoryStore
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="loop-memory doctor",
+        description=(
+            "Run a small library of health checks against the loop-memory "
+            "store.  Reports ok / info / warn / error per check and exits "
+            "non-zero if any check is in 'error' state.  Source: cortexkit/"
+            "magic-context doctor (MIT, 2026-10-12) + PerryLink/dsh-memento "
+            "dsh-plugin-doctor (Apache-2.0, 2026-10-12) — pattern only."
+        ),
+    )
+    p.add_argument(
+        "--db",
+        default=None,
+        help="path to the SQLite file (default: $LOOP_MEMORY_DB or ~/.loop_memory/loop_memory.db)",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="emit the result as JSON for scripting",
+    )
+    p.add_argument(
+        "--verbose",
+        action="store_true",
+        help="also show INFO-level checks in human output",
+    )
+    p.add_argument(
+        "--fix",
+        action="store_true",
+        help="auto-repair any auto_fixable check that fails (idempotent; safe to re-run)",
+    )
+    p.add_argument(
+        "--list",
+        action="store_true",
+        help="list every check the doctor would run and exit (no DB access)",
+    )
+    return p
+
+
+def _resolve_db_path(arg: str | None) -> Path:
+    """Pick the store path: ``--db`` wins, else ``$LOOP_MEMORY_DB``,
+    else the default ``~/.loop_memory/loop_memory.db``."""
+    if arg:
+        return Path(arg).expanduser()
+    import os
+    env = os.environ.get("LOOP_MEMORY_DB")
+    if env:
+        return Path(env).expanduser()
+    from .._common import default_db_path
+    return Path(default_db_path())
+
+
+def run_doctor(args: list[str]) -> int:
+    parser = _build_parser()
+    parsed = parser.parse_args(args)
+
+    if parsed.list:
+        for fn in _doctor.CHECKS:
+            print(fn.__name__)
+        return 0
+
+    db_path = _resolve_db_path(parsed.db)
+    if not db_path.exists():
+        msg = (
+            f"loop-memory doctor: store file not found at {db_path}. "
+            "Run `loop-memory init` first, or pass --db to point at an existing store."
+        )
+        if parsed.json:
+            print(_doctor.render_json([
+                _doctor.DoctorCheck(
+                    name="db_exists",
+                    status=_doctor.STATUS_ERROR,
+                    message=msg,
+                    fix_hint="run `loop-memory init` to create the store",
+                ),
+            ]))
+            return 1
+        return die(msg)
+
+    # ``MemoryStore(<missing_path>)`` creates a fresh DB on open.
+    # We want doctor to FAIL when the path is missing rather than
+    # silently materialise an empty store, so the missing-path
+    # check above is the contract.
+    try:
+        store = MemoryStore(str(db_path))
+    except Exception as e:
+        msg = f"loop-memory doctor: could not open store at {db_path}: {e}"
+        if parsed.json:
+            print(_doctor.render_json([
+                _doctor.DoctorCheck(
+                    name="db_exists",
+                    status=_doctor.STATUS_ERROR,
+                    message=msg,
+                ),
+            ]))
+            return 1
+        return die(msg)
+
+    checks = _doctor.run_checks(store)
+
+    if parsed.fix:
+        # Apply auto-fixes in a single pass.  We re-run the checks
+        # so the user sees the post-fix state in the same command.
+        for c in checks:
+            if c.status in (_doctor.STATUS_ERROR, _doctor.STATUS_WARN) and c.auto_fixable:
+                post = _doctor.apply_fix(store, c.name)
+                # Replace the failing check with the post-fix result
+                # so the human / JSON output reflects reality.
+                idx = checks.index(c)
+                checks[idx] = post
+        checks = _doctor.run_checks(store)
+
+    if parsed.json:
+        sys.stdout.write(_doctor.render_json(checks))
+    else:
+        sys.stdout.write(_doctor.render_human(checks, verbose=parsed.verbose))
+
+    return _doctor.exit_code(checks)

{loop_memory-0.4.12 → loop_memory-0.4.14}/loop_memory/cli/commands/read.py

@@ -51,7 +51,7 @@ def run_stats(_args) -> int:
 
 
 def run_recall(args) -> int:
-    """Run ``loop-memory recall <query> [--verbose] [--outline] [--as-of T] [--limit N]``.
+    """Run ``loop-memory recall <query> [--verbose] [--outline] [--as-of T] [--limit N] [--max-chars N] [--level 0|1|2]``.
 
     With ``--verbose`` each memory hit is annotated with the
     ``why: [...]`` provenance labels produced by ``MemoryStore.recall``
@@ -73,6 +73,8 @@ def run_recall(args) -> int:
     outline = False
     limit = 10
     as_of: float | None = None
+    max_chars: int | None = None
+    level = 1
     qargs: list[str] = []
     i = 0
     while i < len(args):
@@ -104,6 +106,29 @@ def run_recall(args) -> int:
                         f"--as-of must be float epoch or ISO-8601; got {raw!r}"
                     )
             i += 2
+        elif a == "--max-chars" and i + 1 < len(args):
+            # Audit 2026-10-05 (vectorize-io/hindsight v0.10.2 +
+            # aiming-lab/SimpleMem ICML'26) — cap the total payload
+            # across all hits so an agent loop never has to hand-trim
+            # a giant response. ``0`` / negative = no cap.
+            try:
+                max_chars = int(args[i + 1])
+                if max_chars <= 0:
+                    max_chars = None
+            except ValueError:
+                return die(f"--max-chars must be an integer, got {args[i + 1]!r}")
+            i += 2
+        elif a == "--level" and i + 1 < len(args):
+            # Audit 2026-10-05 (volcengine/OpenViking tiered-loader
+            # pattern) — 0 = L0 abstract ladder rung, 1 = L1 default,
+            # 2 = L2 full body.
+            try:
+                level = int(args[i + 1])
+                if level not in (0, 1, 2):
+                    return die("--level must be 0, 1, or 2")
+            except ValueError:
+                return die(f"--level must be 0, 1, or 2, got {args[i + 1]!r}")
+            i += 2
         elif a == "--limit" and i + 1 < len(args):
             try:
                 limit = int(args[i + 1])
@@ -116,18 +141,20 @@ def run_recall(args) -> int:
             qargs.append(a)
             i += 1
     if not qargs:
-        return die("usage: loop-memory recall <query> [--verbose] [--outline] [--as-of <ISO|epoch>] [--limit N]")
+        return die("usage: loop-memory recall <query> [--verbose] [--outline] [--as-of <ISO|epoch>] [--limit N] [--max-chars N] [--level 0|1|2]")
     store = MemoryStore(default_db_path())
     query = " ".join(qargs)
     if as_of is not None:
         try:
-            r = store.recall_as_of(query, as_of, limit=limit)
+            r = store.recall_as_of(query, as_of, limit=limit,
+                                    max_chars=max_chars, level=level)
         except ValueError as e:
             return die(str(e))
     elif outline:
-        r = store.recall_paths(query, limit=limit)
+        r = store.recall_paths(query, limit=limit, max_chars=max_chars)
     else:
-        r = store.recall(query, limit=limit)
+        r = store.recall(query, limit=limit,
+                          max_chars=max_chars, level=level)
     has = False
     if r["wiki"]:
         has = True
@@ -458,6 +485,7 @@ def run_recall_paths(args) -> int:
     if not args:
         return die("usage: loop-memory recall-paths <query> [--limit N]")
     limit = 12
+    max_chars: int | None = None
     qargs: list[str] = []
     i = 0
     while i < len(args):
@@ -468,16 +496,25 @@ def run_recall_paths(args) -> int:
             except ValueError:
                 return die(f"--limit must be an integer, got {args[i + 1]!r}")
             i += 2
+        elif a == "--max-chars" and i + 1 < len(args):
+            # Audit 2026-10-05 — cap the abstract chip-stream size.
+            try:
+                max_chars = int(args[i + 1])
+                if max_chars <= 0:
+                    max_chars = None
+            except ValueError:
+                return die(f"--max-chars must be an integer, got {args[i + 1]!r}")
+            i += 2
         elif a.startswith("--"):
             return die(f"unknown flag: {a}")
         else:
             qargs.append(a)
             i += 1
     if not qargs:
-        return die("usage: loop-memory recall-paths <query> [--limit N]")
+        return die("usage: loop-memory recall-paths <query> [--limit N] [--max-chars N]")
     store = MemoryStore(default_db_path())
     query = " ".join(qargs)
-    r = store.recall_paths(query, limit=limit)
+    r = store.recall_paths(query, limit=limit, max_chars=max_chars)
     has = False
     if r["memories"]:
         has = True

{loop_memory-0.4.12 → loop_memory-0.4.14}/loop_memory/cli/main.py

@@ -149,7 +149,7 @@ COMMAND_HELP: dict[str, str] = {
     "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).",
+    "doctor":                 "loop-memory doctor [--json] [--verbose] [--fix] [--db PATH]   # deep store-health check (db integrity + audit triggers + hooks + version + wiki orphans). Auto-repair with --fix (audit 2026-10-12; pattern adopted from cortexkit/magic-context + dsh-memento).",
     "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.",
@@ -164,7 +164,7 @@ COMMAND_HELP: dict[str, str] = {
     "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> [--as-of <ISO|epoch>]   # show top memories (--as-of = bi-temporal recall).",
+    "recall":                 "loop-memory recall <text> [--as-of <ISO|epoch>] [--max-chars N] [--level 0|1|2]   # show top memories (--as-of = bi-temporal recall; --max-chars = total payload cap; --level 0 = L0 abstract ladder rung; audit 2026-10-05).",
     "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.",
@@ -178,7 +178,7 @@ COMMAND_HELP: dict[str, str] = {
     "import-okf":             "loop-memory import-okf <in_dir> [--scope S] [--dry-run] [--skip-conflicts]   # ingest an OKF v0.2 bundle as wiki pages (audit 2026-09-27).",
     "restore":                "loop-memory restore <in.memory.sqlite>   # re-hydrate a portable SQLite snapshot.",
     # Audit 2026-09-13 — L0 outline recall (tigerless-labs/agent-memory v0.3.0).
-    "recall-paths":           "loop-memory recall-paths <query> [--limit N]   # cheap L0 outline (id+abstract+score) instead of full text (audit 2026-09-13).",
+    "recall-paths":           "loop-memory recall-paths <query> [--limit N] [--max-chars N]   # cheap L0 outline (id+abstract+score) instead of full text (audit 2026-09-13; --max-chars caps the chip stream, audit 2026-10-05).",
     # Audit 2026-09-13 — per-agent identity bootstrap (Mem0 CLI init --agent pattern).
     "init":                   "loop-memory init --agent <name> [--install-hooks]   # register an agent + (optionally) install hooks.",
     "rules":                 "loop-memory rules [--agent codex|claude|hermes|openclaw] [--write] [--force]\n  Print, or append into the agent's rule file, the three-phase memory discipline (task start / mid-task / wrap-up). Never overwrites user content.",