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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.14
+Version: 0.4.16
 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.16** — **subject-key logical fact slots + `latest_only` recall + the "dream" sleep-time consolidation pass** (audit 2026-10-25, weekly ecosystem sync — Mem0 v2.2.1 "Dream", arXiv 2605.27366 "In Defense of Forgotten", Zep/Graphiti temporal edges, Letta memory blocks). New nullable `subject_key` column on `memories` names the *logical slot* a fact occupies (`"editor.preference"`); `upsert_memory(subject_key=...)` makes the new row the live version and soft-supersedes the previous one with a `superseded_by` pointer, so the version history survives and `recall_as_of()` can still answer "what did we believe last week?". The content-hash dedup path is now slot-aware — two different slots holding the same text stay two rows. `SCHEMA_VERSION` bumps 12 → 13 with an idempotent in-place migration. New `latest_only=False` flag on `recall()` / `recall_hybrid()` (Mem0 v2 `SearchMemoryOptions.latest_only` parity) collapses the answer in three layers: rows outside their validity window at *now* are dropped, a subject-key slot resolves to its newest **live** row (looked up in the store, so a stale version never comes back just because it matched the query better), and near-duplicate texts cluster by token Jaccard (default 0.85) with the newest row winning. Wired through `GET /api/recall?latest_only=1`, `GET /api/v1/recall?latest_only=1`, `loop-memory recall --latest-only` and `MemoryClient.recall(latest_only=True)`. New `loop_memory/jobs/dream.py` implements the sleep-time consolidation Mem0 v2 calls the "Dream" — deterministic, zero-dep and **non-destructive**: it decays scores, then judges every row past its deadline on **utility** (`0.45 × importance + 0.30 × usage + 0.25 × recency`) so a frequently-recalled old fact is *protected* while a never-used stale row is **soft-expired** (`invalid_at` stamped, row kept, history kept) instead of deleted, and finally merges near-duplicates into a supersession chain. Run it with `loop-memory dream [--apply] [--json]` or `POST /api/v1/dream` — it is a **dry run by default** and every decision lands in `cognitive_audit` so the dashboard can show and revert it. New store primitives `expire_memory()` / `revive_memory()`, and `memory_stats()` now reports `subject_key`, `ttl`, `valid_at`, `invalid_at` and a derived `ttl_state`. **Also fixed a real defect**: the hybrid recall path (BM25 / LIKE / semantic channels) did not filter `superseded_by`, so `recall_hybrid()` — the production path behind the CLI, MCP server and dashboard — returned both versions of a superseded fact. Source: Mem0 v2.2.1 Dream + ADD-only architecture + arXiv 2605.27366 utility-aware eviction + Zep/Graphiti bi-temporal edges (pattern only, no code copied). 77 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0416---2026-10-25)
+> **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)
@@ -245,6 +247,10 @@ loop-memory serve --port 7767     # open http://127.0.0.1:7767
 # 3. Make it run on a timer
 #    (see docs/auto-capture.md for launchd / systemd / cron snippets)
 loop-memory consolidate          # rescore + GC + dedupe
+
+# 4. Optional: sleep-time consolidation (soft expiry, never deletes)
+loop-memory dream                # dry run -- what would expire / merge
+loop-memory dream --apply        # write it (soft-expire + supersede)
 ```
 
 ---
@@ -446,6 +452,43 @@ User signals close the loop:
 - Every `recall()` / search bumps `recall_count` on the returned
   rows so the next Stage-1 ranks them higher.
 
+### Dream: sleep-time consolidation (0.4.16)
+
+`loop-memory dream [--apply]` is the **non-destructive** counterpart to
+`loop-memory cognitive-sleep --apply`:
+
+| | `cognitive-sleep --apply` | `dream --apply` |
+|---|---|---|
+| forgets a stale row | `DELETE` — the row is gone | **soft expiry** — `invalid_at` is stamped, the row and its history stay |
+| decides by age alone | yes | no — **utility** decides |
+| near-duplicates | merged | merged into a **supersession chain** |
+| reversible | no | yes (`revive_memory()` / `recall --as-of`) |
+
+The utility blend is `0.45 × importance + 0.30 × usage + 0.25 × recency`,
+so a rarely-stated-but-constantly-recalled fact is *protected* while a
+never-used stale row is expired. Age alone never decides — that is the
+whole point of "In Defense of Forgotten" (arXiv 2605.27366).
+
+The pass is a **dry run by default**: `--apply` (CLI) or `"apply": true`
+(HTTP) is what actually writes.
+
+```bash
+loop-memory dream --json                     # machine-readable dry run
+loop-memory dream --apply --ttl-days 60      # tighter horizon
+loop-memory dream --apply --utility 0.2      # expire more aggressively
+curl -X POST http://127.0.0.1:7767/api/v1/dream -d '{"apply": true}'
+```
+
+After a dream pass, ask for the *current* truth explicitly:
+
+```bash
+loop-memory recall "editor preference" --latest-only
+```
+
+`--latest-only` (Mem0 v2 `latest_only` parity) drops rows outside their
+validity window at *now*, collapses a subject-key slot to its newest live
+row, and collapses near-duplicate paraphrases to the newest one.
+
 ### Cognitive sleep (v7)
 
 `loop-memory cognitive-sleep [--apply]` runs an **auditable cleanup
@@ -602,7 +645,7 @@ loop_memory/
     ingest/                    # Codex / Claude / Hermes / OpenClaw / generic loaders
     wiki/                      # distillation, classifier, scope auto-promotion
     graph/                     # entity extraction + knowledge-graph build
-    jobs/                      # consolidate / evolve / cognitive-sleep / scheduler / contradiction / graph
+    jobs/                      # consolidate / evolve / cognitive-sleep / dream / scheduler / contradiction / graph
     llm/                       # provider protocol + OpenAI / Anthropic / Ollama / rule-based
     backends/                  # embedding (hashing / sentence-transformers) + vector store (memory / chroma)
     storage/                   # SQLite-backed MemoryStore + migrations

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

@@ -22,6 +22,8 @@
 
 ---
 
+> **What's new in 0.4.16** — **subject-key logical fact slots + `latest_only` recall + the "dream" sleep-time consolidation pass** (audit 2026-10-25, weekly ecosystem sync — Mem0 v2.2.1 "Dream", arXiv 2605.27366 "In Defense of Forgotten", Zep/Graphiti temporal edges, Letta memory blocks). New nullable `subject_key` column on `memories` names the *logical slot* a fact occupies (`"editor.preference"`); `upsert_memory(subject_key=...)` makes the new row the live version and soft-supersedes the previous one with a `superseded_by` pointer, so the version history survives and `recall_as_of()` can still answer "what did we believe last week?". The content-hash dedup path is now slot-aware — two different slots holding the same text stay two rows. `SCHEMA_VERSION` bumps 12 → 13 with an idempotent in-place migration. New `latest_only=False` flag on `recall()` / `recall_hybrid()` (Mem0 v2 `SearchMemoryOptions.latest_only` parity) collapses the answer in three layers: rows outside their validity window at *now* are dropped, a subject-key slot resolves to its newest **live** row (looked up in the store, so a stale version never comes back just because it matched the query better), and near-duplicate texts cluster by token Jaccard (default 0.85) with the newest row winning. Wired through `GET /api/recall?latest_only=1`, `GET /api/v1/recall?latest_only=1`, `loop-memory recall --latest-only` and `MemoryClient.recall(latest_only=True)`. New `loop_memory/jobs/dream.py` implements the sleep-time consolidation Mem0 v2 calls the "Dream" — deterministic, zero-dep and **non-destructive**: it decays scores, then judges every row past its deadline on **utility** (`0.45 × importance + 0.30 × usage + 0.25 × recency`) so a frequently-recalled old fact is *protected* while a never-used stale row is **soft-expired** (`invalid_at` stamped, row kept, history kept) instead of deleted, and finally merges near-duplicates into a supersession chain. Run it with `loop-memory dream [--apply] [--json]` or `POST /api/v1/dream` — it is a **dry run by default** and every decision lands in `cognitive_audit` so the dashboard can show and revert it. New store primitives `expire_memory()` / `revive_memory()`, and `memory_stats()` now reports `subject_key`, `ttl`, `valid_at`, `invalid_at` and a derived `ttl_state`. **Also fixed a real defect**: the hybrid recall path (BM25 / LIKE / semantic channels) did not filter `superseded_by`, so `recall_hybrid()` — the production path behind the CLI, MCP server and dashboard — returned both versions of a superseded fact. Source: Mem0 v2.2.1 Dream + ADD-only architecture + arXiv 2605.27366 utility-aware eviction + Zep/Graphiti bi-temporal edges (pattern only, no code copied). 77 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0416---2026-10-25)
+> **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)
@@ -201,6 +203,10 @@ loop-memory serve --port 7767     # open http://127.0.0.1:7767
 # 3. Make it run on a timer
 #    (see docs/auto-capture.md for launchd / systemd / cron snippets)
 loop-memory consolidate          # rescore + GC + dedupe
+
+# 4. Optional: sleep-time consolidation (soft expiry, never deletes)
+loop-memory dream                # dry run -- what would expire / merge
+loop-memory dream --apply        # write it (soft-expire + supersede)
 ```
 
 ---
@@ -402,6 +408,43 @@ User signals close the loop:
 - Every `recall()` / search bumps `recall_count` on the returned
   rows so the next Stage-1 ranks them higher.
 
+### Dream: sleep-time consolidation (0.4.16)
+
+`loop-memory dream [--apply]` is the **non-destructive** counterpart to
+`loop-memory cognitive-sleep --apply`:
+
+| | `cognitive-sleep --apply` | `dream --apply` |
+|---|---|---|
+| forgets a stale row | `DELETE` — the row is gone | **soft expiry** — `invalid_at` is stamped, the row and its history stay |
+| decides by age alone | yes | no — **utility** decides |
+| near-duplicates | merged | merged into a **supersession chain** |
+| reversible | no | yes (`revive_memory()` / `recall --as-of`) |
+
+The utility blend is `0.45 × importance + 0.30 × usage + 0.25 × recency`,
+so a rarely-stated-but-constantly-recalled fact is *protected* while a
+never-used stale row is expired. Age alone never decides — that is the
+whole point of "In Defense of Forgotten" (arXiv 2605.27366).
+
+The pass is a **dry run by default**: `--apply` (CLI) or `"apply": true`
+(HTTP) is what actually writes.
+
+```bash
+loop-memory dream --json                     # machine-readable dry run
+loop-memory dream --apply --ttl-days 60      # tighter horizon
+loop-memory dream --apply --utility 0.2      # expire more aggressively
+curl -X POST http://127.0.0.1:7767/api/v1/dream -d '{"apply": true}'
+```
+
+After a dream pass, ask for the *current* truth explicitly:
+
+```bash
+loop-memory recall "editor preference" --latest-only
+```
+
+`--latest-only` (Mem0 v2 `latest_only` parity) drops rows outside their
+validity window at *now*, collapses a subject-key slot to its newest live
+row, and collapses near-duplicate paraphrases to the newest one.
+
 ### Cognitive sleep (v7)
 
 `loop-memory cognitive-sleep [--apply]` runs an **auditable cleanup
@@ -558,7 +601,7 @@ loop_memory/
     ingest/                    # Codex / Claude / Hermes / OpenClaw / generic loaders
     wiki/                      # distillation, classifier, scope auto-promotion
     graph/                     # entity extraction + knowledge-graph build
-    jobs/                      # consolidate / evolve / cognitive-sleep / scheduler / contradiction / graph
+    jobs/                      # consolidate / evolve / cognitive-sleep / dream / scheduler / contradiction / graph
     llm/                       # provider protocol + OpenAI / Anthropic / Ollama / rule-based
     backends/                  # embedding (hashing / sentence-transformers) + vector store (memory / chroma)
     storage/                   # SQLite-backed MemoryStore + migrations

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

@@ -73,8 +73,13 @@ 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
+    # Audit 2026-10-25 (loop-memory 0.4.16) -- latest-only mode.
+    latest_only = False
     qargs: list[str] = []
     i = 0
     while i < len(args):
@@ -82,6 +87,12 @@ def run_recall(args) -> int:
         if a == "--verbose":
             verbose = True
             i += 1
+        elif a == "--latest-only":
+            # Audit 2026-10-25: Mem0 v2 parity -- show one answer per
+            # logical fact (drops rows outside their validity window
+            # and collapses subject-key / near-duplicate versions).
+            latest_only = True
+            i += 1
         elif a == "--outline":
             # Audit 2026-09-13 (tigerless-labs/agent-memory v0.3.0) —
             # cheap L0 list instead of full text. Sets a flag and
@@ -106,6 +117,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
@@ -141,7 +170,7 @@ 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] [--max-chars N] [--level 0|1|2]")
+        return die("usage: loop-memory recall <query> [--verbose] [--outline] [--as-of <ISO|epoch>] [--latest-only] [--limit N] [--max-chars N] [--level 0|1|2]")
     store = MemoryStore(default_db_path())
     query = " ".join(qargs)
     if as_of is not None:
@@ -154,7 +183,14 @@ 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,
+                          # Audit 2026-10-25: one answer per fact.
+                          latest_only=latest_only)
     has = False
     if r["wiki"]:
         has = True

{loop_memory-0.4.14 → loop_memory-0.4.16}/loop_memory/cli/commands/write.py

@@ -7,7 +7,7 @@ import os
 import urllib.error
 import urllib.request
 
-from .._common import DEFAULT_DB, die, parse_int_flag
+from .._common import DEFAULT_DB, default_db_path, die, parse_int_flag
 
 
 def run_ingest(args) -> int:
@@ -115,6 +115,99 @@ def run_rescore(args) -> int:
     return 0
 
 
+def run_dream(args) -> int:
+    """loop-memory dream [--apply] [--json] [tuning flags]
+
+    The sleep-time consolidation pass (audit 2026-10-25, loop-memory
+    0.4.16). Runs a **dry sweep** by default and prints what it
+    *would* do; pass ``--apply`` to actually soft-expire stale rows and
+    merge near-duplicates.
+
+    Unlike ``loop-memory consolidate`` (which hard-deletes rows past
+    their TTL), the dream pass never deletes: it stamps ``invalid_at``
+    so the fact leaves the current view while its history stays
+    queryable through ``loop-memory recall --as-of``.
+    """
+    import sys
+
+    from ...jobs.dream import dream as dream_job
+    from ...storage.sqlite_store import MemoryStore
+
+    args = list(args)
+    apply_changes = False
+    as_json = False
+    half_life_days = 30.0
+    ttl_days = 90.0
+    utility_threshold = 0.30
+    similarity = 0.92
+    limit = 2000
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--apply":
+            apply_changes = True
+            i += 1
+        elif a == "--json":
+            as_json = True
+            i += 1
+        elif a in ("--half-life", "--ttl-days", "--utility", "--similarity", "--limit"):
+            if i + 1 >= len(args):
+                return die(f"{a} needs a value")
+            raw = args[i + 1]
+            try:
+                if a == "--limit":
+                    limit = int(raw)
+                else:
+                    value = float(raw)
+            except ValueError:
+                return die(f"{a} must be a number, got {raw!r}")
+            if a == "--half-life":
+                half_life_days = value
+            elif a == "--ttl-days":
+                ttl_days = value
+            elif a == "--utility":
+                utility_threshold = value
+            else:
+                similarity = value
+            i += 2
+        elif a.startswith("--"):
+            return die(f"unknown flag: {a}")
+        else:
+            return die(f"unexpected argument: {a!r}")
+
+    # ``default_db_path()`` (not the import-time constant) so a host
+    # that changes $LOOP_MEMORY_DB after import is honoured.
+    store = MemoryStore(default_db_path())
+    report = dream_job(
+        store,
+        apply=apply_changes,
+        half_life_days=half_life_days,
+        ttl_days=ttl_days,
+        utility_threshold=utility_threshold,
+        similarity=similarity,
+        limit=limit,
+    )
+    if as_json:
+        print(json.dumps(report.to_dict(), indent=2, ensure_ascii=False))
+        return 0
+
+    mode = "applied" if apply_changes else "dry-run"
+    print(
+        f"dream ({mode}) — considered {report.considered}, "
+        f"expired {report.expired}, kept {report.kept}, "
+        f"superseded {report.superseded} in {report.elapsed_ms:.0f} ms"
+    )
+    if not apply_changes and (report.expired or report.superseded):
+        print("  (dry run — re-run with --apply to write these changes)")
+    for action in report.actions:
+        if action.kind == "keep":
+            continue
+        marker = "✔" if action.action == "applied" else "•"
+        print(f"  {marker} {action.kind}: {action.target_text[:72]}")
+        print(f"      {action.reason}")
+    return 0
+
+
 def run_consolidate_now(_args) -> int:
     """Ask the running server to trigger a consolidation pass right now."""
     import json as _json

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

@@ -15,6 +15,7 @@ Usage:
     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 dream [--apply]    # sleep-time consolidation: utility-aware soft expiry + dedupe
     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 rules [--agent codex|claude|hermes|openclaw] [--write] [--force]
@@ -94,6 +95,9 @@ COMMANDS = {
     "ingest": write_cmd.run_ingest,
     "consolidate": write_cmd.run_consolidate,
     "consolidate-now": write_cmd.run_consolidate_now,
+    # Audit 2026-10-25 (loop-memory 0.4.16) -- sleep-time "dream"
+    # consolidation: utility-aware soft expiry + near-duplicate merge.
+    "dream": write_cmd.run_dream,
     "export": _run_export,
     "digest": read_cmd.run_digest,
     "ask": read_cmd.run_ask,
@@ -147,6 +151,7 @@ COMMAND_HELP: dict[str, str] = {
     "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.",
+    "dream":                  "loop-memory dream [--apply] [--json] [--ttl-days D] [--utility T]   # sleep-time consolidation: utility-aware soft expiry + near-duplicate merge (audit 2026-10-25). Dry run unless --apply.",
     "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 [--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).",
@@ -164,7 +169,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>] [--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).",
+    "recall":                 "loop-memory recall <text> [--as-of <ISO|epoch>] [--latest-only] [--max-chars N] [--level 0|1|2]   # show top memories (--as-of = bi-temporal recall; --latest-only = one answer per fact; --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.",

loop_memory-0.4.16/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"]