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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.12
+Version: 0.4.13
 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,8 @@ Dynamic: license-file
 
 ---
 
+> **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.13}/README.md

@@ -22,6 +22,8 @@
 
 ---
 
+> **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.13}/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.13}/loop_memory/cli/main.py

@@ -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.",

{loop_memory-0.4.12 → loop_memory-0.4.13}/loop_memory/mcp/__init__.py

@@ -78,7 +78,27 @@ def tool_recall(arguments: dict[str, Any]) -> list[dict[str, Any]]:
         return [_err("missing 'query' argument")]
     store = _store()
     source = arguments.get("source") or _agent_context()[0]
-    r = store.recall(query, limit=limit, source=source)
+    # Audit 2026-10-05: thread ``max_chars`` (token / char budget cap)
+    # + ``level`` (tiered-loader) through the MCP tool so an MCP-aware
+    # agent loop can ask for a bounded retrieval inline. ``None`` and
+    # the default ``1`` preserve the byte-identical legacy payload.
+    raw_max = arguments.get("max_chars")
+    max_chars: int | None = None
+    if raw_max is not None:
+        try:
+            max_chars = int(raw_max)
+            if max_chars <= 0:
+                max_chars = None
+        except (TypeError, ValueError):
+            max_chars = None
+    try:
+        level = int(arguments.get("level") or 1)
+        if level not in (0, 1, 2):
+            level = 1
+    except (TypeError, ValueError):
+        level = 1
+    r = store.recall(query, limit=limit, source=source,
+                     max_chars=max_chars, level=level)
     n_mem = len(r["memories"])
     n_wiki = len(r["wiki"])
     n_ent = len(r["entities"])

{loop_memory-0.4.12 → loop_memory-0.4.13}/loop_memory/sdk.py

@@ -243,8 +243,15 @@ class MemoryClient(MemoryClientExt, AbstractContextManager):
         agent_id: str | None = None,
         user_id: str | None = None,
         include: str = "memories,wiki,entities",
+        max_chars: int | None = None,
+        level: int = 1,
     ) -> RecallResult:
-        """Unified search across the user's memory store."""
+        """Unified search across the user's memory store.
+
+        ``max_chars`` (audit 2026-10-05) caps the total payload so an
+        MCP-loop caller never has to hand-trim a giant response.
+        ``level`` (0..2) is the tiered-loader knob.
+        """
         raise NotImplementedError
 
     def forget(
@@ -351,6 +358,8 @@ class _InProcessClient(MemoryClient):
         agent_id: str | None = None,
         user_id: str | None = None,
         include: str = "memories,wiki,entities",
+        max_chars: int | None = None,
+        level: int = 1,
     ) -> RecallResult:
         # ``recall_hybrid`` is the production code path; fall back to
         # the legacy LIKE-based ``recall`` if a stale DB doesn't have
@@ -359,7 +368,8 @@ class _InProcessClient(MemoryClient):
         if hasattr(self._store, "recall_hybrid"):
             r = self._store.recall_hybrid(
                 query, limit=limit, include=wanted,
-                bump_signals=True, source=source, level=1,
+                bump_signals=True, source=source, level=level,
+                max_chars=max_chars,
             )
         else:
             r = self._store.recall(
@@ -367,6 +377,8 @@ class _InProcessClient(MemoryClient):
                 limit=limit,
                 include=wanted,
                 source=source,
+                max_chars=max_chars,
+                level=level,
             )
         # Optional post-filter: even if the store returned hits, the
         # caller may want only their agent's namespace.
@@ -661,13 +673,18 @@ class _HttpClient(MemoryClient):
         agent_id: str | None = None,
         user_id: str | None = None,
         include: str = "memories,wiki,entities",
+        max_chars: int | None = None,
+        level: int = 1,
     ) -> RecallResult:
         params = {
             "q": query,
             "limit": int(limit),
             "include": include,
             "source": source or "",
+            "level": int(level),
         }
+        if max_chars is not None:
+            params["max_chars"] = int(max_chars)
         if agent_id is not None:
             params["agent_id"] = agent_id
         if user_id is not None:

{loop_memory-0.4.12 → loop_memory-0.4.13}/loop_memory/serve/routes/system.py

@@ -386,7 +386,8 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
     def recall(query: str, limit: int = 10, include: str = "memories,wiki,entities",
               bump: int = 1, source: str | None = None,
               mode: str = "hybrid", level: int = 1,
-              as_of: str | None = None):
+              as_of: str | None = None,
+              max_chars: int | None = None):
         """Unified recall — wiki + memories + entities in one ranked stream.
 
         ``mode`` is 'hybrid' (default) for BM25+semantic+entity RRF,
@@ -406,10 +407,33 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
         When unset (default) the call returns the latest answer
         (preserves the pre-0.4.9 contract). When set, the call
         routes through ``MemoryStore.recall_as_of``.
+
+        ``level`` (audit 2026-10-05) is the OpenViking-style
+        tiered-loader knob: 0 = L0 abstract ladder rung (titles +
+        tags + abstract only, never the full ``text`` / ``body``),
+        1 = L1 default (full ``text``, ``body`` capped at 800),
+        2 = L2 (full body, full text).
+
+        ``max_chars`` (audit 2026-10-05) caps the total payload
+        (sum of ``text`` + ``body`` across all hits) so an agent
+        loop can ask for a bounded retrieval. ``None`` (default)
+        preserves the byte-identical legacy payload. Source:
+        vectorize-io/hindsight v0.10.2 "concise extraction by
+        default" + aiming-lab/SimpleMem ICML'26 semantic-lossless-
+        compression.
         """
         wanted = tuple(s.strip() for s in include.split(",") if s.strip())
         if not wanted:
             wanted = ("memories", "wiki", "entities")
+        # Coerce max_chars to ``int | None`` so the route accepts
+        # ``?max_chars=`` (empty) and ``?max_chars=0`` as "no cap".
+        if max_chars is not None:
+            try:
+                max_chars = int(max_chars)
+            except (TypeError, ValueError):
+                max_chars = None
+            if max_chars is not None and max_chars <= 0:
+                max_chars = None
         if as_of is not None and str(as_of).strip():
             try:
                 r = store.recall_as_of(
@@ -419,6 +443,8 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
                     include=wanted,
                     bump_signals=bool(bump),
                     source=source,
+                    max_chars=max_chars,
+                    level=level,
                 )
                 recall_mode = "as_of"
             except ValueError as e:
@@ -430,12 +456,15 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
                 include=wanted,
                 bump_signals=bool(bump),
                 source=source,
+                max_chars=max_chars,
+                level=level,
             )
             recall_mode = mode
         else:
             r = store.recall_hybrid(
                 query, limit=limit, include=wanted,
                 bump_signals=bool(bump), source=source, level=level,
+                max_chars=max_chars,
             )
             recall_mode = mode
         return {
@@ -448,6 +477,7 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
             "source": source,
             "level": level,
             "as_of": as_of,
+            "max_chars": max_chars,
         }
 
 
@@ -531,7 +561,8 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
     @app.get("/api/recall/outline")
     def recall_outline(query: str = "", limit: int = 12,
                        include: str = "memories,wiki,entities",
-                       bump: int = 0, source: str | None = None):
+                       bump: int = 0, source: str | None = None,
+                       max_chars: int | None = None):
         """Audit 2026-09-13 — L0 outline recall (tigerless-labs/agent-memory
         v0.3.0 recall ladder pattern).
 
@@ -546,18 +577,32 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
         ``recall_count`` before the agent has actually decided to read
         the body. Set ``bump=1`` only when the agent commits to the
         candidate set.
+
+        ``max_chars`` (audit 2026-10-05) caps the total payload of
+        the *abstracts* across all returned hits so a downstream UI
+        never has to hand-trim a giant chip stream. ``None``
+        (default) keeps the legacy byte-identical abstract ladder
+        rung.
         """
         if not query:
             raise HTTPException(status_code=400, detail="query is required")
         wanted = tuple(s.strip() for s in include.split(",") if s.strip())
         if not wanted:
             wanted = ("memories", "wiki", "entities")
+        if max_chars is not None:
+            try:
+                max_chars = int(max_chars)
+            except (TypeError, ValueError):
+                max_chars = None
+            if max_chars is not None and max_chars <= 0:
+                max_chars = None
         r = store.recall_paths(
             query,
             limit=limit,
             include=wanted,
             bump_signals=bool(bump),
             source=source,
+            max_chars=max_chars,
         )
         return {
             "query": query,
@@ -567,6 +612,7 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
             "entities": r.get("entities", []),
             "mode": "outline",
             "source": source,
+            "max_chars": max_chars,
         }