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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.15
+Version: 0.4.17
 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,7 @@ 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)
 
@@ -246,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)
 ```
 
 ---
@@ -447,6 +452,46 @@ 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. A dry run changes **no memory data** --
+no expiry, no supersession, no rescore -- it only appends a
+`cognitive_audit` row per proposed action (`action="suggest"`), which
+is the reviewable plan the dashboard shows before you commit.
+
+```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
@@ -603,7 +648,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.15 → loop_memory-0.4.17}/README.md

@@ -22,6 +22,7 @@
 
 ---
 
+> **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)
 
@@ -202,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)
 ```
 
 ---
@@ -403,6 +408,46 @@ 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. A dry run changes **no memory data** --
+no expiry, no supersession, no rescore -- it only appends a
+`cognitive_audit` row per proposed action (`action="suggest"`), which
+is the reviewable plan the dashboard shows before you commit.
+
+```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
@@ -559,7 +604,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.15 → loop_memory-0.4.17}/loop_memory/cli/commands/read.py

@@ -78,6 +78,8 @@ def run_recall(args) -> int:
     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):
@@ -85,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
@@ -162,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:
@@ -180,7 +188,9 @@ def run_recall(args) -> int:
                           # to recall() so the new bi-temporal window
                           # filter applies. ``None`` keeps the legacy
                           # "everything" semantics.
-                          as_of_ts=validity_at)
+                          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.15 → loop_memory-0.4.17}/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.15 → loop_memory-0.4.17}/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.",