superlocalmemory 3.6.2 → 3.6.4

package/CHANGELOG.md

@@ -5,6 +5,186 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.4] - 2026-06-09 — Memory-integrity & reliability hardening
+
+### Fixed
+
+- **`remember` write-path integrity:** fact storage is now idempotent across all memory
+  lifecycle states and every write path — storing the same fact twice is one fact. A transient
+  backend error during extraction or consolidation can no longer leave a memory without a
+  retrievable fact (graceful fallback).
+- **Graph & vector consistency:** edges and embeddings stay correct as memories age,
+  consolidate, and are archived (no stale or orphaned graph/vector entries influencing recall).
+- **MCP stdio stability:** resolved a connection-lifecycle edge case that could prematurely
+  end a session with strict MCP hosts.
+
+### Performance
+
+- Faster recall on large knowledge bases; tighter memory bounds in hot paths.
+
+### Internal
+
+- Expanded automated test coverage for write-path and graph integrity.
+
+## [3.6.3] - 2026-06-08 — Cache + compression now work for Claude Code, Claude Desktop, Codex CLI
+
+### Fixed
+
+- **CRITICAL — Cache permanently bypassed for ALL tool-bearing clients (Claude Code, Claude Desktop, Codex CLI):**
+  `anthropic_surface.py` and `openai_surface.py` both wrapped every cache operation with
+  `if not has_tools and proxy.hooks.cache:`. Because Claude Code ALWAYS sends a `tools` array,
+  caching was structurally impossible — zero savings regardless of how many identical prompts
+  were sent. Fix: removed all four `has_tools` guards across both surfaces. Cache now fires
+  unconditionally for every request on both streaming and non-streaming paths.
+
+- **CRITICAL — Anthropic streaming SSE parser returned `None` for tool_use responses:**
+  `_parse_sse_to_json()` only accumulated `text_delta` events. Any response containing a
+  `tool_use` content block (every Claude Code response) caused the parser to emit an empty
+  content array and return `None`, meaning the completed SSE stream was never stored even if the
+  `has_tools` guard had been removed. Full rewrite: the parser now tracks content blocks by
+  index, handles both `text_delta` and `input_json_delta` events, and assembles complete
+  `tool_use` entries (with `id`, `name`, `input` JSON object) in the stored JSON. Returns
+  `None` only on genuinely incomplete streams (missing `message_start` or `message_stop`).
+
+- **CRITICAL — Anthropic SSE cache replay did not emit tool_use blocks:**
+  `_sse_from_cached_json()` only replayed `text` content blocks. Tool-use blocks were silently
+  dropped, producing a truncated response on cache hits. Fixed: the replay function now handles
+  `tool_use` blocks — emits `content_block_start` with `{type:"tool_use", id, name, input:{}}`,
+  then `input_json_delta` chunks (50-char pieces), then `content_block_stop`. Clients receive
+  a byte-for-byte equivalent of the original SSE stream.
+
+- **CRITICAL — OpenAI SSE parser returned `None` for tool_calls responses:**
+  `_parse_openai_sse_to_json()` detected `tool_calls` in the delta and returned `None`
+  immediately. OpenAI-compatible clients (Codex CLI, Antigravity) were therefore never cached.
+  Fixed: parser now accumulates `tool_calls` by `choice_index → tc_index → {id, type, function}`
+  and stores them in the assembled `chat.completion` JSON. Tool call arguments are joined from
+  streaming `arguments` deltas.
+
+- **CRITICAL — OpenAI SSE cache replay dropped tool_calls entirely:**
+  `_openai_sse_from_cached_json()` only replayed text content. Tool calls were silently dropped.
+  Fixed: replays `tool_calls` as proper OpenAI SSE delta events — first chunk with role +
+  tool_call headers (id, type, name, empty arguments), then argument chunks (50-char pieces),
+  then finish chunk. Preserves the streaming contract with clients.
+
+- **CompressRouter never instantiated — `compress_hook=None` always:**
+  `_load_hooks()` in `server.py` had dead code: `if config.compress_enabled: pass`. The
+  `CompressRouter` singleton was never created, so compression was silently a no-op for every
+  session since v3.6.0. Fixed: `_load_hooks()` now calls `CompressRouter.get_instance()` and
+  wires it into the `HookChain`. Daemon log now correctly reports `compress_hook=CompressRouter`.
+
+- **MetricsCollector never wired to CompressRouter — `compress_runs=0` always:**
+  `CompressRouter.set_metrics()` was never called during proxy startup, so
+  `_metrics_counters=None` permanently. Result: `compress_runs` counter was always 0 in the
+  dashboard even when compression was running. Fixed: `_load_hooks()` calls
+  `compress_hook.set_metrics(MetricsCollector.get_instance())` immediately after instantiation.
+
+- **`on_compress` signature mismatch — metrics counter never incremented:**
+  `CompressRouter._compress_messages()` called `self._metrics_counters.on_compress(saved, lossy)`
+  where `saved` was bytes-saved and `lossy` was a bool. `MetricsCollector.on_compress()` expects
+  `(bytes_original, bytes_after)`. The mismatch meant `compress_runs` and `bytes_saved` were
+  always wrong even after wiring. Fixed: caller now passes `(before_tokens, after_tokens)`.
+
+- **`is_tool_msg` in `CompressRouter` skipped ALL user messages from compression:**
+  The original guard was `is_tool_msg = (role == "tool" or role == "user")`. This silently
+  skipped every `user` turn, including long tool-result messages (the main source of savings
+  in Claude Code sessions). Fixed: only OpenAI `role=="tool"` messages are skipped. Anthropic
+  `tool_result` blocks (embedded in user message content arrays) are now compressed by
+  `_compress_content_block()`, which handles the nested structure correctly.
+
+### Tests
+
+- `tests/optimize/proxy/test_openai_surface.py`: updated `test_parse_openai_sse_to_json_tool_calls_returns_none`
+  → renamed to `test_parse_openai_sse_to_json_tool_calls_cached`, asserts valid JSON returned
+  with `tool_calls` array preserved instead of `None`.
+- `tests/optimize/proxy/test_server.py`: updated `test_load_hooks_compress_enabled_placeholder`
+  → renamed to `test_load_hooks_compress_enabled_loads_router`, asserts `hooks.compress is not None`
+  and `isinstance(hooks.compress, CompressRouter)`.
+- All 83 proxy tests pass (0 failures).
+
+### Documentation
+
+- `docs/proxy-setup.md`: removed "Cache fires only for requests WITHOUT tools" caveat. Updated
+  "What Gets Cached" table — Claude Code, Claude Desktop, Codex CLI now show `✓ Yes`. Added
+  explanation of how tool-use caching works (SSE accumulate → parse → store → replay as SSE).
+  Updated troubleshooting section — removed stale "tool-bearing requests are bypassed" note,
+  added actionable checklist for diagnosing zero-savings scenarios.
+
+---
+
+## [3.6.3] - 2026-06-08 — Proxy streaming cache fix for Anthropic, OpenAI surfaces
+
+### Fixed
+
+- **CRITICAL — Anthropic streaming cache never populated (miss permanently 0 savings):**
+  `anthropic_surface.py`'s streaming path called `_stream_forward()` (no-op passthrough)
+  instead of the new `_stream_and_cache_forward()`. Claude Code, AGY, and every other
+  streaming Anthropic client could never populate the cache because the response body was
+  never accumulated. Cache was always empty, `tokens_saved` was always 0, regardless of how
+  many identical prompts were sent. Fix: streaming path now checks cache on the way in
+  (`_safe_cache_check`), runs compression on the request body, and passes a `store_callback`
+  to `_stream_and_cache_forward()` that accumulates the SSE stream, parses it via
+  `_parse_sse_to_json`, and stores the assembled JSON message after `message_stop` is seen.
+  Second identical streaming call returns a properly re-emitted SSE stream from cache
+  (verified: `msg_id` identical, no upstream call on hit).
+
+- **CRITICAL — OpenAI streaming surface: cache bypassed + `_safe_compress` NameError:**
+  `openai_surface.py` had the same streaming bypass bug AND a missing import — `_safe_compress`
+  was called on the non-streaming compression path but never imported, causing a silent
+  `NameError` on any non-streaming request with compression enabled. Both issues fixed:
+  (1) streaming path now wires `_stream_and_cache_forward` with `_parse_openai_sse_to_json`
+  and `_openai_sse_from_cached_json` helpers (OpenAI SSE format differs from Anthropic's —
+  uses `[DONE]` sentinel and `chat.completion.chunk` objects). (2) `_safe_compress` added
+  to imports. Cache hit on OpenAI streaming calls now returns a re-emitted SSE stream with
+  proper `chat.completion.chunk` events and `[DONE]` terminator.
+
+- **`_stream_and_cache_forward` completion marker was Anthropic-only:**
+  The `finally` block checked for `b"message_stop"` to detect a complete stream before
+  calling `on_complete`. OpenAI SSE streams end with `data: [DONE]\n\n` — not `message_stop`.
+  Result: OpenAI streaming responses were never stored in cache even after the fix above
+  because the `on_complete` callback was never fired. Fixed by checking both markers:
+  `b"message_stop"` (Anthropic) OR `b"[DONE]"` (OpenAI / any compatible provider).
+
+- **`_stream_and_cache_forward` redundant join:** `full = b"".join(acc)` recomputed the
+  join that `_joined` had already computed. Fixed to reuse `_joined` directly.
+
+- **`server.py` version string stuck at `"3.6.0"`:** `_PROXY_VERSION` was not updated
+  during the 3.6.1 and 3.6.2 releases. Fixed to `"3.6.3"`. The `/health` endpoint now
+  correctly reports `"version":"3.6.3"`.
+
+- **`CacheManager.get()` returned `None` on miss, discarding the cache key:** Store
+  condition `cache_result.cache_key` was always falsy on miss because `get()` returned
+  `None` (no `CachedResponse` object). Non-streaming responses after a miss were never
+  stored. Fixed: `get()` now returns `CachedResponse(hit=False, data=None, cache_key=key)`
+  so the key propagates to the store condition.
+
+- **`CacheManager.check()` never called `MetricsCollector.on_miss()`:** Miss events were
+  not counted, so `hits/(hits+misses)` was always 0 in the dashboard. Fixed: `check()`
+  calls `MetricsCollector.get_instance().on_miss()` when `result.hit is False`.
+
+### Added
+
+- `_parse_openai_sse_to_json(sse_bytes)`: assembles OpenAI streaming chunks into a
+  single `chat.completion` JSON for cache storage. Handles multi-index choices, usage
+  capture, `tool_calls` detection (never caches tool responses), and `[DONE]` sentinel.
+- `_openai_sse_from_cached_json(cached_bytes)`: replays a stored `chat.completion` as
+  a proper OpenAI SSE stream for cache-hit responses. Emits role chunk, content chunks
+  (100-char batches), finish chunk, and `[DONE]`. Preserves the streaming contract with
+  clients (Codex CLI, Antigravity, openai-python).
+- `docs/proxy-setup.md`: comprehensive per-CLI proxy activation guide covering Claude Code
+  CLI, Claude Desktop, Cursor, Windsurf, AGY/Antigravity, Gemini CLI, Codex CLI, Python
+  anthropic/openai SDK, Node.js SDK, LangChain, LlamaIndex, SDK adapter, and raw curl.
+  Includes an honest "What Gets Cached" table showing which clients benefit from caching.
+
+### Tests
+
+- `tests/optimize/proxy/test_openai_surface.py`: 9 new tests covering
+  `_parse_openai_sse_to_json` (complete stream, missing `[DONE]`, tool calls, empty bytes,
+  usage capture) and `_openai_sse_from_cached_json` (roundtrip, bad JSON, wrong object
+  type) plus an end-to-end streaming cache miss→store→hit cycle.
+- All 583 optimize tests pass (4 skipped — platform-specific).
+
+---
+
 ## [3.6.2] - 2026-06-08 — wrap dry_run fix for config-file mechanism (macOS CI)
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.6.2"
+version = "3.6.4"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/__init__.py

@@ -28,7 +28,7 @@ if "OMP_NUM_THREADS" not in os.environ:
     os.environ["OMP_NUM_THREADS"] = "2"
 # ---------------------------------------------------------------------------
 
-__version__ = "3.6.2"
+__version__ = "3.6.3"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/core/consolidation_engine.py

@@ -745,6 +745,14 @@ class ConsolidationEngine:
         """
         from superlocalmemory.storage.models import _new_id
 
+        # NOTE (core-promotion-02, intentionally NOT changed): the audit
+        # flagged placeholder core blocks ("No data available.") + version
+        # churn. Investigation showed BOTH the "always 5 blocks" layout and the
+        # monotonic version-on-recompile counter are intentional, tested design
+        # (see test_consolidation_engine), and the read-side injection filter
+        # already hides placeholders from agents. Suppressing or de-churning
+        # here breaks that design for a cosmetic gain — so it is left as-is.
+
         # Get existing version for increment
         existing = self._db.get_core_block(profile_id, block_type)
         version = (existing["version"] + 1) if existing else 1

package/src/superlocalmemory/core/engine.py

@@ -281,13 +281,18 @@ class MemoryEngine:
         # V3.2: ConsolidationEngine (Phase 5) -- sleep-time consolidation
         from superlocalmemory.core.summarizer import Summarizer
         summarizer = Summarizer(self._config)
+        # P1-5 (core-promotion-01): wire a real behavioral store. Previously
+        # hardcoded None → _compile_behavioral_block always returned the
+        # "No behavioral patterns detected yet." placeholder, so behavioral
+        # patterns never reached the always-injected core block (dead feature).
+        from superlocalmemory.core.recall_pipeline import _get_behavioral_tracker
         self._consolidation_engine = _init_consolidation(
             self._config, self._db,
             auto_linker=self._auto_linker,
             graph_analyzer=self._graph_analyzer,
             temporal_validator=self._temporal_validator,
             summarizer=summarizer,
-            behavioral_store=None,
+            behavioral_store=_get_behavioral_tracker(self._db),
             embedder=self._embedder,  # v3.4.7: for CCQ worker
             llm=getattr(self, "_llm", None),  # v3.4.7: for CCQ worker
         )

package/src/superlocalmemory/core/fact_consolidator.py

@@ -226,19 +226,41 @@ def _consolidate_cluster(
                 except (json.JSONDecodeError, TypeError):
                     pass
 
-        c.execute("""
-            INSERT INTO atomic_facts
-            (fact_id, memory_id, profile_id, content, fact_type,
-             entities_json, canonical_entities_json,
-             confidence, importance, evidence_count, access_count,
-             created_at, lifecycle)
-            VALUES (?, '', ?, ?, 'semantic', ?, ?, ?, 0.8, ?, 0, ?, 'active')
-        """, (
-            new_fact_id, profile_id, summary,
-            json.dumps(list(all_entities)),
-            json.dumps(list(all_entities)),
-            round(avg_confidence, 3), len(facts), now,
-        ))
+        # P0-3 (dedup-complete-01): apply the SAME content-idempotency invariant
+        # as storage.database.store_fact — but on THIS cursor so it stays inside
+        # the cluster SAVEPOINT. Previously this raw INSERT bypassed dedup, so a
+        # consolidated summary identical to an existing live fact created a
+        # duplicate row and never reinforced evidence. Now: reinforce-or-insert.
+        # (Excludes 'archived' = soft-deleted, mirroring store_fact.)
+        _existing = c.execute(
+            "SELECT fact_id FROM atomic_facts "
+            "WHERE profile_id = ? AND content = ? "
+            "AND lifecycle IN ('active', 'warm', 'cold') "
+            "ORDER BY created_at LIMIT 1",
+            (profile_id, summary),
+        ).fetchone()
+        if _existing:
+            new_fact_id = _existing["fact_id"]
+            c.execute(
+                "UPDATE atomic_facts "
+                "SET evidence_count = evidence_count + ?, access_count = access_count + 1 "
+                "WHERE fact_id = ?",
+                (len(facts), new_fact_id),
+            )
+        else:
+            c.execute("""
+                INSERT INTO atomic_facts
+                (fact_id, memory_id, profile_id, content, fact_type,
+                 entities_json, canonical_entities_json,
+                 confidence, importance, evidence_count, access_count,
+                 created_at, lifecycle)
+                VALUES (?, '', ?, ?, 'semantic', ?, ?, ?, 0.8, ?, 0, ?, 'active')
+            """, (
+                new_fact_id, profile_id, summary,
+                json.dumps(list(all_entities)),
+                json.dumps(list(all_entities)),
+                round(avg_confidence, 3), len(facts), now,
+            ))
 
         # Record the consolidation
         consolidation_id = uuid.uuid4().hex[:16]
@@ -257,6 +279,25 @@ def _consolidate_cluster(
             (*fact_ids, profile_id),
         )
 
+        # P1-4 (graph-integrity-01): archived facts must stop influencing
+        # graph-based ranking. The association_edges FK is ON DELETE CASCADE
+        # only (no ON UPDATE), so archiving via UPDATE leaves orphaned edges
+        # that spreading_activation still reads. Remove edges touching the
+        # archived facts, and set their retention zone so ForgettingFilter
+        # excludes them. Inside the SAVEPOINT for atomicity.
+        c.execute(
+            f"DELETE FROM association_edges "
+            f"WHERE profile_id = ? "
+            f"AND (source_fact_id IN ({placeholders}) "
+            f"     OR target_fact_id IN ({placeholders}))",
+            (profile_id, *fact_ids, *fact_ids),
+        )
+        c.execute(
+            f"UPDATE fact_retention SET lifecycle_zone = 'archive' "
+            f"WHERE profile_id = ? AND fact_id IN ({placeholders})",
+            (profile_id, *fact_ids),
+        )
+
         c.execute(f"RELEASE SAVEPOINT {savepoint_name}")
 
     except Exception:

package/src/superlocalmemory/core/graph_pruner.py

@@ -56,6 +56,7 @@ def prune_graph(
         "self_loops_removed": 0,
         "duplicates_removed": 0,
         "hub_edges_removed": 0,
+        "association_orphans_removed": 0,  # gi-04
         "total_before": 0,
         "total_after": 0,
     }
@@ -83,6 +84,9 @@ def prune_graph(
             stats["hub_edges_removed"] = _cap_node_degree(
                 c, profile_id, _MAX_DEGREE_PER_NODE, dry_run,
             )
+        stats["association_orphans_removed"] = _remove_orphan_association_edges(
+            c, profile_id, dry_run,
+        )
 
         if dry_run:
             c.execute("ROLLBACK")
@@ -122,6 +126,34 @@ def prune_graph(
     return stats
 
 
+def _remove_orphan_association_edges(
+    c: sqlite3.Cursor,
+    profile_id: str,
+    dry_run: bool,
+) -> int:
+    """gi-04: remove association_edges whose source/target fact no longer
+    exists in atomic_facts.
+
+    prune_graph historically only touched graph_edges despite its docstring
+    claiming "all graph pruning". Hard-deleted facts leave orphaned
+    association_edges (the FK cascade only fires under FK-on connections),
+    which spreading_activation then has to scan. Returns rows removed.
+    """
+    where = (
+        "profile_id = ? AND ("
+        "source_fact_id NOT IN (SELECT fact_id FROM atomic_facts WHERE profile_id = ?) "
+        "OR target_fact_id NOT IN (SELECT fact_id FROM atomic_facts WHERE profile_id = ?))"
+    )
+    c.execute(f"SELECT COUNT(*) AS cnt FROM association_edges WHERE {where}",
+              (profile_id, profile_id, profile_id))
+    n = c.fetchone()["cnt"]
+    if dry_run or not n:
+        return n
+    c.execute(f"DELETE FROM association_edges WHERE {where}",
+              (profile_id, profile_id, profile_id))
+    return c.rowcount
+
+
 def _remove_orphan_edges(
     c: sqlite3.Cursor,
     profile_id: str,
@@ -321,60 +353,64 @@ def _cap_node_degree(
       2. Edges with rn > max_degree are deleted in a single DELETE statement.
       Requires SQLite 3.25+ (window functions). System is on 3.53.1.
     """
+    # gi-03: cap BOTH out-degree (PARTITION BY source_id) AND in-degree
+    # (PARTITION BY target_id). Previously only out-degree was capped, so hub
+    # nodes accumulated unbounded in-degree (observed up to 1457), inflating
+    # entity-channel fan-in cost. An edge is removed if it exceeds max_degree
+    # in EITHER direction (low-weight to both its endpoints). Computed in one
+    # window-function pass, no Python loops.
     if dry_run:
         c.execute(
             """
             SELECT COUNT(*) as cnt FROM (
                 SELECT edge_id,
-                       ROW_NUMBER() OVER (
-                           PARTITION BY source_id ORDER BY weight DESC
-                       ) as rn
+                       ROW_NUMBER() OVER (PARTITION BY source_id ORDER BY weight DESC) as out_rn,
+                       ROW_NUMBER() OVER (PARTITION BY target_id ORDER BY weight DESC) as in_rn
                 FROM graph_edges
                 WHERE profile_id = ?
-            ) WHERE rn > ?
+            ) WHERE out_rn > ? OR in_rn > ?
             """,
-            (profile_id, max_degree),
+            (profile_id, max_degree, max_degree),
         )
         excess = c.fetchone()["cnt"]
         logger.info(
-            "(dry-run) _cap_node_degree: ~%d edges would be removed (max_degree=%d)",
+            "(dry-run) _cap_node_degree: ~%d edges would be removed (max_degree=%d, in+out)",
             excess, max_degree,
         )
         return excess
 
-    # Step 1: build temp keep-list in one pass (ROW_NUMBER ranks by weight DESC)
-    c.execute("CREATE TEMP TABLE IF NOT EXISTS _slm_keep_edges (edge_id TEXT PRIMARY KEY)")
-    c.execute("DELETE FROM _slm_keep_edges")  # idempotent if called twice
+    # Step 1: collect edges exceeding the cap in either direction (one pass).
+    c.execute("DROP TABLE IF EXISTS _slm_cap_del")
+    c.execute("CREATE TEMP TABLE _slm_cap_del (edge_id TEXT PRIMARY KEY)")
     c.execute(
         """
-        INSERT INTO _slm_keep_edges (edge_id)
+        INSERT OR IGNORE INTO _slm_cap_del (edge_id)
         SELECT edge_id FROM (
             SELECT edge_id,
-                   ROW_NUMBER() OVER (
-                       PARTITION BY source_id ORDER BY weight DESC
-                   ) as rn
+                   ROW_NUMBER() OVER (PARTITION BY source_id ORDER BY weight DESC) as out_rn,
+                   ROW_NUMBER() OVER (PARTITION BY target_id ORDER BY weight DESC) as in_rn
             FROM graph_edges
             WHERE profile_id = ?
-        ) WHERE rn <= ?
+        ) WHERE out_rn > ? OR in_rn > ?
         """,
-        (profile_id, max_degree),
+        (profile_id, max_degree, max_degree),
     )
 
-    # Step 2: delete everything not in keep-list (single DELETE)
+    # Step 2: delete the over-cap edges (single DELETE).
     c.execute(
         """
         DELETE FROM graph_edges
         WHERE profile_id = ?
-          AND edge_id NOT IN (SELECT edge_id FROM _slm_keep_edges)
+          AND edge_id IN (SELECT edge_id FROM _slm_cap_del)
         """,
         (profile_id,),
     )
     deleted = c.rowcount
 
-    c.execute("DROP TABLE IF EXISTS _slm_keep_edges")
+    c.execute("DROP TABLE IF EXISTS _slm_cap_del")
 
     logger.info(
-        "_cap_node_degree: deleted %d low-weight edges (max_degree=%d)",
+        "_cap_node_degree: deleted %d low-weight edges (max_degree=%d, in+out capped)",
         deleted, max_degree,
     )
     return deleted

package/src/superlocalmemory/core/maintenance.py

@@ -107,8 +107,17 @@ def run_maintenance(
         "fisher_coupled": 0,
         "sheaf_checked": 0,
         "entity_summaries_consolidated": 0,  # V3.4.40
+        "orphan_metadata_gc": 0,             # v3.6.4 (P1-3)
     }
 
+    # P1-3 (embeddings-vector-02): sweep orphaned embedding_metadata left by
+    # any FK-off delete path, so the semantic channel never maps to dead facts.
+    # Runs before the early-return so it sweeps even for empty profiles.
+    try:
+        counts["orphan_metadata_gc"] = db.gc_orphaned_embedding_metadata()
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("orphan metadata GC skipped: %s", exc)
+
     facts = db.get_all_facts(profile_id)
     if not facts:
         return counts