loop-memory 0.4.13__tar.gz → 0.4.15__tar.gz

{loop_memory-0.4.13 → loop_memory-0.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.13
+Version: 0.4.15
 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,9 @@ Dynamic: license-file
 
 ---
 
+> **What's new in 0.4.15** — **content-hash dedup + bi-temporal validity window + evidence chain + `@agent_memory` decorator** (audit 2026-10-18, weekly ecosystem sync). Three new columns on `memories`: `content_hash` (SHA-256 of normalised text, indexed), `valid_at` (epoch the memory becomes active), `invalid_at` (epoch it expires — NULL means still open-ended). The schema migration bumps `SCHEMA_VERSION` 11 → 12 with an idempotent backfill so legacy DBs upgrade in-place. New `upsert_memory(valid_at=, invalid_at=, dedup=)` parameters let callers schedule future-dated or expiring memories and opt out of content-hash dedup for episodic event streams. `recall()` and `recall_hybrid()` now accept an optional `as_of_ts` (float epoch or ISO-8601) — when set, both methods drop memories whose `valid_at > as_of` or `invalid_at <= as_of`, complementing the existing `recall_as_of()` supersession-chain walk. Every recall hit now carries an `evidence: [{field, value, weight}]` array — BM25 / semantic / entity / rrf_total / high_importance channels are exposed individually so a UI can render "this hit because ... [bm25 1.0] [entity 0.7]" instead of a black-box score (Cognee 1.0 / Mem0 v2 evidence-citation pattern, zero-dep). New `loop_memory.decorators` exposes `@agent_memory(store, agent_id=, limit=)` — a one-line wrapper that recalls the top-k relevant memories before the body runs and writes a fresh `kind="interaction"` memory after. Strings returned from the wrapped function are stored verbatim; dict/list returns are JSON-serialised; the recall list is injected as a `memory_context` keyword when the function declares it, otherwise attached to dict results under `memories`. Sister `remember(store, text, ...)` helper for seeding. The BM25 `_like_fallback` now falls through to per-token OR-LIKE when the whole-string match returns nothing — natural-language questions like "What is the deploy process?" now hit stored facts even when FTS5 trigram can't match quoted exact phrases. Source: Cognee 1.0 ECL pipeline + Mem0 v2 hybrid fusion + Zep/Graphiti bi-temporal validity fields + Letta block-memory (pattern only, no code copied). 59 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0415---2026-10-18)
+> **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)

{loop_memory-0.4.13 → loop_memory-0.4.15}/README.md

@@ -22,6 +22,9 @@
 
 ---
 
+> **What's new in 0.4.15** — **content-hash dedup + bi-temporal validity window + evidence chain + `@agent_memory` decorator** (audit 2026-10-18, weekly ecosystem sync). Three new columns on `memories`: `content_hash` (SHA-256 of normalised text, indexed), `valid_at` (epoch the memory becomes active), `invalid_at` (epoch it expires — NULL means still open-ended). The schema migration bumps `SCHEMA_VERSION` 11 → 12 with an idempotent backfill so legacy DBs upgrade in-place. New `upsert_memory(valid_at=, invalid_at=, dedup=)` parameters let callers schedule future-dated or expiring memories and opt out of content-hash dedup for episodic event streams. `recall()` and `recall_hybrid()` now accept an optional `as_of_ts` (float epoch or ISO-8601) — when set, both methods drop memories whose `valid_at > as_of` or `invalid_at <= as_of`, complementing the existing `recall_as_of()` supersession-chain walk. Every recall hit now carries an `evidence: [{field, value, weight}]` array — BM25 / semantic / entity / rrf_total / high_importance channels are exposed individually so a UI can render "this hit because ... [bm25 1.0] [entity 0.7]" instead of a black-box score (Cognee 1.0 / Mem0 v2 evidence-citation pattern, zero-dep). New `loop_memory.decorators` exposes `@agent_memory(store, agent_id=, limit=)` — a one-line wrapper that recalls the top-k relevant memories before the body runs and writes a fresh `kind="interaction"` memory after. Strings returned from the wrapped function are stored verbatim; dict/list returns are JSON-serialised; the recall list is injected as a `memory_context` keyword when the function declares it, otherwise attached to dict results under `memories`. Sister `remember(store, text, ...)` helper for seeding. The BM25 `_like_fallback` now falls through to per-token OR-LIKE when the whole-string match returns nothing — natural-language questions like "What is the deploy process?" now hit stored facts even when FTS5 trigram can't match quoted exact phrases. Source: Cognee 1.0 ECL pipeline + Mem0 v2 hybrid fusion + Zep/Graphiti bi-temporal validity fields + Letta block-memory (pattern only, no code copied). 59 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0415---2026-10-18)
+> **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)

{loop_memory-0.4.13 → loop_memory-0.4.15}/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.15/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.13 → loop_memory-0.4.15}/loop_memory/cli/commands/read.py

@@ -73,6 +73,9 @@ def run_recall(args) -> int:
     outline = False
     limit = 10
     as_of: float | None = None
+    # Audit 2026-10-18: bi-temporal *validity* window (distinct
+    # from ``as_of`` which routes through the supersession chain).
+    validity_at: float | None = None
     max_chars: int | None = None
     level = 1
     qargs: list[str] = []
@@ -106,6 +109,24 @@ def run_recall(args) -> int:
                         f"--as-of must be float epoch or ISO-8601; got {raw!r}"
                     )
             i += 2
+        elif a == "--validity-at" and i + 1 < len(args):
+            # Audit 2026-10-18 (loop-memory 0.4.15) -- cheaper
+            # validity-window filter (vs --as-of which walks the
+            # supersession chain). Accepts the same float-or-ISO.
+            raw = args[i + 1].strip()
+            try:
+                validity_at = float(raw)
+            except ValueError:
+                try:
+                    from datetime import datetime
+                    validity_at = datetime.fromisoformat(
+                        raw.replace("Z", "+00:00")
+                    ).timestamp()
+                except Exception:
+                    return die(
+                        f"--validity-at 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
@@ -154,7 +175,12 @@ def run_recall(args) -> int:
         r = store.recall_paths(query, limit=limit, max_chars=max_chars)
     else:
         r = store.recall(query, limit=limit,
-                          max_chars=max_chars, level=level)
+                          max_chars=max_chars, level=level,
+                          # Audit 2026-10-18: pass validity_at through
+                          # to recall() so the new bi-temporal window
+                          # filter applies. ``None`` keeps the legacy
+                          # "everything" semantics.
+                          as_of_ts=validity_at)
     has = False
     if r["wiki"]:
         has = True

{loop_memory-0.4.13 → loop_memory-0.4.15}/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.",

loop_memory-0.4.15/loop_memory/decorators.py

@@ -0,0 +1,243 @@
+"""Lightweight decorators for one-line agent memory integration.
+
+Audit 2026-10-18 (loop-memory 0.4.15): the decorator pattern is the
+adoption-shortcut inspired by LangChain ``@tool`` / Mem0 v2's
+``@remember`` -- a single line of boilerplate turns any plain Python
+function into an "agent-callable" that reads from long-term memory
+before it runs and writes a fresh memory after it returns.
+
+Two decorators ship here:
+
+* :func:`agent_memory` -- wraps a callable so every invocation:
+  - **recalls** the top-k relevant memories for the function's first
+    string argument (the "query") *before* running the body, and
+    - either exposes the recall as a ``memory_context`` keyword
+      argument (when the wrapped function's signature declares it),
+      OR surfaces it on the return value as ``result["memories"]``;
+  - **stores** the (query, return-value) pair as a single
+    ``kind="interaction"`` memory row *after* the body finishes, so
+    the next invocation can recall it.
+
+* :func:`remember` -- a tiny sugar that just calls
+  ``store.upsert_memory(kind="fact", text=text, ...)`` once at
+  definition time. Useful for facts the agent wants to hard-code into
+  memory at import time ("I am a code assistant", "My user prefers
+  dark mode", etc.).
+
+Both decorators are intentionally zero-dep and free of any LLM/agent
+framework dependency -- they sit on top of the public
+``MemoryStore`` API only.
+"""
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from .storage.sqlite_store import MemoryStore
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def _stringify(value: Any, *, max_len: int = 2000) -> str:
+    """Coerce a Python return value to a memory-friendly string.
+
+    * ``str``  -> as-is (truncated to ``max_len``).
+    * ``dict`` / ``list`` -> JSON-serialised then truncated.
+    * ``bytes``-> hex preview.
+    * everything else -> ``repr(value)``.
+
+    The truncation is the only place this helper swallows information;
+    downstream recall still works because the original ``text`` is on
+    the row, and the full structured payload is also stored verbatim
+    in ``tags`` when the caller passes a dict/list.
+    """
+    if isinstance(value, str):
+        return value if len(value) <= max_len else value[: max_len - 1] + "\u2026"
+    if isinstance(value, (dict, list)):
+        s = json.dumps(value, ensure_ascii=False, default=str)
+        return s if len(s) <= max_len else s[: max_len - 1] + "\u2026"
+    if isinstance(value, bytes):
+        return value[:64].hex() + (f" (len={len(value)})" if len(value) > 64 else "")
+    return repr(value)
+
+
+def _first_string_arg(
+    args: tuple, kwargs: dict, signature: inspect.Signature
+) -> str | None:
+    """Return the first positional str argument from the call.
+
+    Falls back to ``None`` when the call carries no string-y input
+    (e.g. ``@agent_memory`` wrapping an internal ``tick()`` that
+    takes only objects).
+    """
+    if args:
+        first = args[0]
+        if isinstance(first, str) and first.strip():
+            return first
+        return None
+    for name, p in signature.parameters.items():
+        if name in kwargs:
+            v = kwargs[name]
+            if isinstance(v, str) and v.strip():
+                return v
+            return None
+    return None
+
+
+def agent_memory(
+    store: MemoryStore,
+    *,
+    agent_id: str | None = None,
+    user_id: str | None = None,
+    kind: str = "interaction",
+    limit: int = 5,
+    recall_kwargs_name: str = "memory_context",
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Wrap ``fn`` so every call reads + writes persistent memory.
+
+    Parameters
+    ----------
+    store:
+        An open :class:`~loop_memory.storage.sqlite_store.MemoryStore`.
+        Required -- the decorator has nowhere to put memory otherwise.
+    agent_id, user_id:
+        Optional identity columns. When ``None`` the wrapped call
+        pushes a memory that is global to the store (the same scope
+        that pre-0.4.15 callers used).
+    kind:
+        Memory row kind. Default ``"interaction"`` matches the
+        dashboard's existing tag.
+    limit:
+        Number of top-k memories to recall *before* the body runs.
+        Capped at 50 to keep the prompt tiny.
+    recall_kwargs_name:
+        Name of the optional kwarg the wrapped function can declare to
+        receive the recall as a string. Defaults to ``"memory_context"``.
+        If the function does NOT declare that kwarg the recall is
+        silently dropped (the body still runs) but the row is still
+        stored after the call returns.
+
+    Example
+    -------
+    >>> store = MemoryStore("loop.db")
+    >>> @agent_memory(store, agent_id="codex")
+    ... def ask(question: str, memory_context: str = "") -> str:
+    ...     # memory_context arrives pre-formatted from the recall
+    ...     return f"{question} -> {memory_context[:40]}"
+    >>> ask("What is the deploy process?")
+    """
+    if not isinstance(store, MemoryStore):
+        raise TypeError(
+            f"@agent_memory requires a MemoryStore, got {type(store).__name__}"
+        )
+    if limit <= 0 or limit > 50:
+        raise ValueError(f"limit must be in [1, 50], got {limit}")
+
+    def _decorator(fn: Callable[P, R]) -> Callable[P, R]:
+        sig = inspect.signature(fn)
+        _ = sig  # pre-bound for _first_string_arg
+        recall_kw = recall_kwargs_name
+
+        @functools.wraps(fn)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            query = _first_string_arg(args, kwargs, sig)
+            # --- pre-call: recall ---------------------------------
+            recall_hits: list[dict] = []
+            context_text = ""
+            if query:
+                try:
+                    res = store.recall_hybrid(
+                        query, limit=limit, as_of_ts=None,
+                    )
+                    recall_hits = list(res.get("memories", []))
+                except Exception:
+                    recall_hits = []
+                if recall_hits:
+                    lines = []
+                    for h in recall_hits:
+                        prev = (h.get("text") or h.get("preview") or "").strip()
+                        if prev:
+                            lines.append(f"- {prev[:240]}")
+                    context_text = "\n".join(lines)
+
+            # Inject memory_context only when the function actually
+            # declares the kwarg -- otherwise the decorator stays
+            # invisible to legacy callables that don't know about it.
+            injected = False
+            if recall_kw in sig.parameters and context_text:
+                kwargs = {**kwargs, recall_kw: context_text}
+                injected = True
+
+            # --- body ----------------------------------------------
+            result = fn(*args, **kwargs)
+
+            # --- post-call: store ----------------------------------
+            if query:
+                try:
+                    text = _stringify(result)
+                    tags = ["agent_memory"]
+                    if isinstance(result, (dict, list)):
+                        tags.append("structured")
+                    store.upsert_memory(
+                        kind=kind,
+                        text=text,
+                        importance=0.6,
+                        agent_id=agent_id,
+                        user_id=user_id,
+                        tags=tags,
+                        source=f"agent_memory:{fn.__name__}",
+                    )
+                except Exception:
+                    # Never let a store failure break the wrapped call.
+                    pass
+
+            # Attach the recall to a dict result so callers can
+            # surface "I knew this because ..." in the UI. Plain
+            # string/int/float returns stay untouched.
+            if isinstance(result, dict) and recall_hits and not injected:
+                result.setdefault("memories", recall_hits)
+            return result
+
+        # Friendly metadata on the wrapper so ``help()`` is useful.
+        _wrapper.__wrapped_agent_memory__ = True  # type: ignore[attr-defined]
+        return _wrapper
+
+    return _decorator
+
+
+def remember(
+    store: MemoryStore,
+    text: str,
+    *,
+    kind: str = "fact",
+    importance: float = 0.7,
+    tags: list[str] | None = None,
+    agent_id: str | None = None,
+    user_id: str | None = None,
+) -> str:
+    """Insert ``text`` into the store as a single memory and return its id.
+
+    Sugar for callers that want to seed memory at import time without
+    having to instantiate ``StoredMemory`` / ``upsert_memory``:
+
+    >>> store = MemoryStore("loop.db")
+    >>> remember(store, "User prefers dark mode",
+    ...          tags=["ui", "preference"], agent_id="codex")
+    """
+    if not isinstance(store, MemoryStore):
+        raise TypeError(
+            f"remember() requires a MemoryStore, got {type(store).__name__}"
+        )
+    item = store.upsert_memory(
+        kind=kind, text=text, importance=importance,
+        tags=tags or ["remember"], agent_id=agent_id, user_id=user_id,
+        source="remember",
+    )
+    return item.id
+
+
+__all__ = ["agent_memory", "remember"]