superlocalmemory 3.6.2 → 3.6.4

package/src/superlocalmemory/optimize/proxy/openai_surface.py

@@ -1,4 +1,16 @@
-"""openai_surface.py — OpenAI /v1/chat/completions and /v1/embeddings."""
+"""openai_surface.py — OpenAI /v1/chat/completions and /v1/embeddings.
+
+BUG-FIXES (v3.6.3):
+- Streaming path previously bypassed cache AND had _safe_compress not imported
+  (NameError on any non-streaming compressed call). Same set of bugs as
+  anthropic_surface.py pre-v3.6.3. Fixed with the same pattern:
+  cache check → _stream_and_cache_forward → post-stream store.
+- _safe_compress added to imports (was missing; NameError on compress path).
+- Streaming cache: accumulate SSE, parse to JSON, store so future identical
+  calls are served from cache. OpenAI SSE format differs from Anthropic's
+  so a dedicated _parse_openai_sse_to_json / _openai_sse_from_cached helper
+  is used.
+"""
 
 from __future__ import annotations
 
@@ -6,7 +18,7 @@ import json
 import logging
 
 from fastapi.requests import Request
-from fastapi.responses import Response
+from fastapi.responses import Response, StreamingResponse
 
 from superlocalmemory.optimize.proxy._helpers import (
     _OPENAI_FORWARD_HEADERS,
@@ -18,6 +30,8 @@ from superlocalmemory.optimize.proxy._helpers import (
     _safe_cache_check,
     _safe_cache_hit_callbacks,
     _safe_cache_store,
+    _safe_compress,
+    _stream_and_cache_forward,
     _stream_forward,
 )
 from superlocalmemory.optimize.proxy.lifecycle import ProviderResponse, ProxyRequest
@@ -27,6 +41,269 @@ logger = logging.getLogger("slm.optimize.proxy.openai")
 _UPSTREAM_BASE = "https://api.openai.com"
 
 
+# ---------------------------------------------------------------------------
+# OpenAI SSE helpers (streaming cache hit/store)
+# ---------------------------------------------------------------------------
+
+def _parse_openai_sse_to_json(sse_bytes: bytes) -> bytes | None:
+    """Parse an accumulated OpenAI SSE stream into a single chat.completion JSON.
+
+    OpenAI streaming format:
+        data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[
+                 {"index":0,"delta":{"role":"assistant","content":"Hello"},...}]}
+        ...
+        data: [DONE]
+
+    Assembles into the non-streaming chat.completion format so it can be stored
+    in the cache and replayed as SSE on the next identical call.
+
+    BUG-FIX (v3.6.4): Previously returned None for responses containing
+    tool_calls, meaning OpenAI-compatible tool-bearing clients (Codex CLI,
+    Antigravity) were NEVER cached. Now accumulates tool_calls by index and
+    includes them in the stored JSON so _openai_sse_from_cached_json can
+    replay them correctly.
+
+    Returns None only for incomplete streams (no [DONE], missing id).
+    """
+    completion_id = ""
+    model = ""
+    created = 0
+    text_acc: dict[int, str] = {}  # choice_index → accumulated content
+    finish_reasons: dict[int, str] = {}
+    # tool_calls_acc[choice_idx][tc_idx] = {id, type, function: {name, args_parts}}
+    tool_calls_acc: dict[int, dict[int, dict]] = {}
+    prompt_tokens = 0
+    completion_tokens = 0
+    done_seen = False
+
+    for raw_line in sse_bytes.decode("utf-8", errors="replace").split("\n"):
+        line = raw_line.rstrip("\r")
+        if not line.startswith("data: "):
+            continue
+        data_str = line[6:].strip()
+        if data_str == "[DONE]":
+            done_seen = True
+            continue
+        try:
+            chunk = json.loads(data_str)
+        except json.JSONDecodeError:
+            continue
+
+        if not completion_id:
+            completion_id = chunk.get("id", "")
+        if not model:
+            model = chunk.get("model", "")
+        if not created:
+            created = chunk.get("created", 0)
+
+        for choice in chunk.get("choices", []):
+            idx = choice.get("index", 0)
+            delta = choice.get("delta", {})
+
+            content = delta.get("content")
+            if content:
+                text_acc[idx] = text_acc.get(idx, "") + content
+
+            for tc in delta.get("tool_calls", []):
+                tc_idx = tc.get("index", 0)
+                if idx not in tool_calls_acc:
+                    tool_calls_acc[idx] = {}
+                if tc_idx not in tool_calls_acc[idx]:
+                    tool_calls_acc[idx][tc_idx] = {
+                        "id": "",
+                        "type": "function",
+                        "function": {"name": "", "arguments_parts": []},
+                    }
+                entry = tool_calls_acc[idx][tc_idx]
+                if tc.get("id"):
+                    entry["id"] = tc["id"]
+                if tc.get("type"):
+                    entry["type"] = tc["type"]
+                fn = tc.get("function", {})
+                if fn.get("name"):
+                    entry["function"]["name"] = fn["name"]
+                if fn.get("arguments") is not None:
+                    entry["function"]["arguments_parts"].append(fn["arguments"])
+
+            fr = choice.get("finish_reason")
+            if fr:
+                finish_reasons[idx] = fr
+
+        usage = chunk.get("usage") or {}
+        if usage:
+            prompt_tokens = usage.get("prompt_tokens", prompt_tokens)
+            completion_tokens = usage.get("completion_tokens", completion_tokens)
+
+    if not done_seen or not completion_id:
+        return None
+
+    all_choice_indices = sorted(set(list(text_acc.keys()) + list(tool_calls_acc.keys())))
+    if not all_choice_indices:
+        return None
+
+    choices = []
+    for i in all_choice_indices:
+        finish_reason = finish_reasons.get(i, "stop")
+        message: dict = {"role": "assistant"}
+
+        if i in tool_calls_acc:
+            tool_calls = [
+                {
+                    "id": tool_calls_acc[i][ti]["id"],
+                    "type": tool_calls_acc[i][ti].get("type", "function"),
+                    "function": {
+                        "name": tool_calls_acc[i][ti]["function"]["name"],
+                        "arguments": "".join(
+                            tool_calls_acc[i][ti]["function"]["arguments_parts"]
+                        ),
+                    },
+                }
+                for ti in sorted(tool_calls_acc[i].keys())
+            ]
+            message["content"] = None
+            message["tool_calls"] = tool_calls
+        else:
+            message["content"] = text_acc.get(i, "")
+
+        choices.append({
+            "index": i,
+            "message": message,
+            "logprobs": None,
+            "finish_reason": finish_reason,
+        })
+
+    result = {
+        "id": completion_id,
+        "object": "chat.completion",
+        "created": created,
+        "model": model,
+        "choices": choices,
+        "usage": {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": prompt_tokens + completion_tokens,
+        },
+    }
+    return json.dumps(result, separators=(",", ":")).encode("utf-8")
+
+
+def _openai_sse_from_cached_json(cached_bytes: bytes) -> "StreamingResponse | None":
+    """Convert a stored chat.completion JSON back to an OpenAI SSE stream.
+
+    Used when an identical streaming request hits the cache — we replay the
+    stored JSON as the SSE events the OpenAI API would have emitted, preserving
+    the streaming contract with the client (e.g. Codex CLI, Antigravity).
+
+    BUG-FIX (v3.6.4): Handles tool_calls in the cached message, replaying
+    them as proper OpenAI SSE delta events with index/id/name/arguments chunks.
+
+    Returns None if the bytes are not a parseable chat.completion object.
+    """
+    try:
+        resp = json.loads(cached_bytes)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+    if resp.get("object") != "chat.completion":
+        return None
+
+    async def _generate():
+        completion_id = resp.get("id", "")
+        model = resp.get("model", "")
+        created = resp.get("created", 0)
+
+        for choice in resp.get("choices", []):
+            idx = choice.get("index", 0)
+            message = choice.get("message", {})
+            tool_calls = message.get("tool_calls")
+            content = message.get("content") or ""
+            finish_reason = choice.get("finish_reason", "stop")
+
+            if tool_calls:
+                # First chunk: role + tool_call headers (id, type, name, empty args)
+                first_delta = {
+                    "role": "assistant",
+                    "content": None,
+                    "tool_calls": [
+                        {
+                            "index": ti,
+                            "id": tc["id"],
+                            "type": tc.get("type", "function"),
+                            "function": {
+                                "name": tc["function"]["name"],
+                                "arguments": "",
+                            },
+                        }
+                        for ti, tc in enumerate(tool_calls)
+                    ],
+                }
+                first_chunk = {
+                    "id": completion_id, "object": "chat.completion.chunk",
+                    "created": created, "model": model,
+                    "choices": [{"index": idx, "delta": first_delta, "finish_reason": None}],
+                }
+                yield f"data: {json.dumps(first_chunk)}\n\n".encode()
+
+                # Argument chunks per tool call (50-char pieces)
+                chunk_size = 50
+                for ti, tc in enumerate(tool_calls):
+                    args = tc.get("function", {}).get("arguments", "")
+                    for start in range(0, max(len(args), 1), chunk_size):
+                        piece = args[start: start + chunk_size]
+                        arg_chunk = {
+                            "id": completion_id, "object": "chat.completion.chunk",
+                            "created": created, "model": model,
+                            "choices": [{
+                                "index": idx,
+                                "delta": {"tool_calls": [{"index": ti, "function": {"arguments": piece}}]},
+                                "finish_reason": None,
+                            }],
+                        }
+                        yield f"data: {json.dumps(arg_chunk)}\n\n".encode()
+
+                # Finish chunk
+                finish_chunk = {
+                    "id": completion_id, "object": "chat.completion.chunk",
+                    "created": created, "model": model,
+                    "choices": [{"index": idx, "delta": {}, "finish_reason": finish_reason}],
+                }
+                yield f"data: {json.dumps(finish_chunk)}\n\n".encode()
+
+            else:
+                # Text response replay
+                role_chunk = {
+                    "id": completion_id, "object": "chat.completion.chunk",
+                    "created": created, "model": model,
+                    "choices": [{"index": idx, "delta": {"role": "assistant", "content": ""}, "finish_reason": None}],
+                }
+                yield f"data: {json.dumps(role_chunk)}\n\n".encode()
+
+                chunk_size = 100
+                for start in range(0, max(len(content), 1), chunk_size):
+                    piece = content[start: start + chunk_size]
+                    content_chunk = {
+                        "id": completion_id, "object": "chat.completion.chunk",
+                        "created": created, "model": model,
+                        "choices": [{"index": idx, "delta": {"content": piece}, "finish_reason": None}],
+                    }
+                    yield f"data: {json.dumps(content_chunk)}\n\n".encode()
+
+                finish_chunk = {
+                    "id": completion_id, "object": "chat.completion.chunk",
+                    "created": created, "model": model,
+                    "choices": [{"index": idx, "delta": {}, "finish_reason": finish_reason}],
+                }
+                yield f"data: {json.dumps(finish_chunk)}\n\n".encode()
+
+        yield b"data: [DONE]\n\n"
+
+    return StreamingResponse(_generate(), media_type="text/event-stream")
+
+
+# ---------------------------------------------------------------------------
+# Route handlers
+# ---------------------------------------------------------------------------
+
 async def handle_chat_completions(proxy: object, request: Request) -> Response:
     request_id = await proxy.next_request_id()
     upstream_url = f"{_UPSTREAM_BASE}/v1/chat/completions"
@@ -47,14 +324,60 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
         )
 
         if stream:
+            # BUG-FIX (v3.6.3): streaming path previously bypassed cache
+            # entirely — same bug as anthropic_surface.py pre-fix. OpenAI
+            # clients (Codex CLI, Antigravity, openai-python) use stream=True
+            # by default, so savings were permanently 0.
+
+            # 1. Cache check
+            if proxy.hooks.cache:
+                cache_result = await _safe_cache_check(proxy.hooks, ctx)
+                if cache_result and cache_result.hit and cache_result.data:
+                    logger.debug(
+                        "[%s] OpenAI streaming cache HIT key=%s",
+                        request_id, cache_result.cache_key,
+                    )
+                    await _safe_cache_hit_callbacks(
+                        proxy.hooks, ctx, cache_result.data, tokens_saved=0
+                    )
+                    sse_resp = _openai_sse_from_cached_json(cache_result.data)
+                    if sse_resp is not None:
+                        return sse_resp
+
+            # 2. Compression on request body
+            outbound_bytes = body_bytes
+            if proxy.hooks.compress:
+                compress_result = await _safe_compress(proxy.hooks, ctx)
+                if compress_result.body_bytes != body_bytes:
+                    outbound_bytes = compress_result.body_bytes
+
             fwd_headers = _build_forward_headers(request, _OPENAI_FORWARD_HEADERS)
-            fwd_headers["content-length"] = str(len(body_bytes))
-            return await _stream_forward(
-                proxy, request_id, fwd_headers, body_bytes, upstream_url
+            fwd_headers["content-length"] = str(len(outbound_bytes))
+
+            # 3. Stream + accumulate for cache store
+            store_callback = None
+            if proxy.hooks.cache:
+                _hooks = proxy.hooks
+                _ctx = ctx
+                async def _store_from_openai_sse(sse_bytes: bytes) -> None:
+                    parsed = _parse_openai_sse_to_json(sse_bytes)
+                    if parsed is None:
+                        return
+                    prov = ProviderResponse(
+                        modified=False, body={}, body_bytes=parsed,
+                        tokens_before=0, tokens_after=0, strategy="none",
+                    )
+                    await _safe_cache_store(_hooks, _ctx, prov)
+                store_callback = _store_from_openai_sse
+
+            return await _stream_and_cache_forward(
+                proxy, request_id, fwd_headers, outbound_bytes, upstream_url,
+                on_complete=store_callback,
             )
 
+        # --- Non-streaming path ---
         cache_result = None
-        if not has_tools and proxy.hooks.cache:
+        if proxy.hooks.cache:
             cache_result = await _safe_cache_check(proxy.hooks, ctx)
             if cache_result.hit and cache_result.data:
                 await _safe_cache_hit_callbacks(
@@ -82,7 +405,6 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
 
         if (
             upstream_resp.status_code == 200
-            and not has_tools
             and proxy.hooks.cache
             and cache_result is not None
             and cache_result.cache_key

package/src/superlocalmemory/optimize/proxy/server.py

@@ -17,7 +17,7 @@ from superlocalmemory.optimize.proxy.lifecycle import HookChain
 
 logger = logging.getLogger("slm.optimize.proxy")
 
-_PROXY_VERSION = "3.6.0"
+_PROXY_VERSION = "3.6.3"
 _REQUEST_TIMEOUT_S = 300.0
 _CONNECT_TIMEOUT_S = 10.0
 _MAX_CONNECTIONS = 100
@@ -145,7 +145,14 @@ def _load_hooks(config: OptimizeConfig) -> HookChain:
             )
 
     if config.compress_enabled:
-        # Compress is Phase 2; not wired in P1. P1 keeps the slot for the seam.
-        pass
+        try:
+            from superlocalmemory.optimize.compress.router import CompressRouter
+            from superlocalmemory.optimize.metrics.counters import MetricsCollector
+            compress_hook = CompressRouter.get_instance()
+            compress_hook.set_metrics(MetricsCollector.get_instance())
+        except Exception as exc:
+            logger.warning(
+                "compress hook load failed (proxy continues without compress): %s", exc
+            )
 
     return HookChain(cache=cache_hook, compress=compress_hook)

package/src/superlocalmemory/retrieval/engine.py

@@ -182,16 +182,26 @@ class RetrievalEngine:
         # V3.3.19: Only bridge.discover() (86ms). Removed bridge.spreading_activation()
         # which did per-node SQL queries across 254K edges → 78s latency.
         # The SYNAPSE SA channel already provides proper SA with in-memory caching.
+        # recall-retrieval-01: O(1) membership/score lookups instead of repeated
+        # O(N) `any(...)`/`next(...)` scans inside the bridge + scene loops
+        # (was O(N^2) per recall, ~400 ms on large sessions). Kept in sync as
+        # `fused` grows so behaviour is identical.
+        fused_ids = {fr.fact_id for fr in fused}
+        fused_scores = {fr.fact_id: fr.fused_score for fr in fused}
+
         if self._bridge is not None and strat.query_type in ("multi_hop", "entity", "factual", "general"):
             try:
                 seed_ids = [fr.fact_id for fr in fused[:10]]
                 bridges = self._bridge.discover(seed_ids, profile_id, max_bridges=10)
                 for fid, score in bridges:
-                    if not any(fr.fact_id == fid for fr in fused):
+                    if fid not in fused_ids:
+                        new_score = score * 0.8
                         fused.append(FusionResult(
-                            fact_id=fid, fused_score=score * 0.8,
+                            fact_id=fid, fused_score=new_score,
                             channel_ranks={}, channel_scores={},
                         ))
+                        fused_ids.add(fid)
+                        fused_scores[fid] = new_score
             except Exception as exc:
                 logger.warning("Bridge discovery: %s", exc)
 
@@ -206,14 +216,15 @@ class RetrievalEngine:
                 for fid in top_ids:
                     for scene in scenes_map.get(fid, [])[:2]:
                         for sfid in scene.fact_ids:
-                            if not any(f.fact_id == sfid for f in fused) and sfid not in expanded_ids:
+                            if sfid not in fused_ids and sfid not in expanded_ids:
                                 expanded_ids.add(sfid)
+                                new_score = fused_scores.get(fid, 0.5) * 0.8
                                 fused.append(FusionResult(
-                                    fact_id=sfid, fused_score=(
-                                        next((f.fused_score for f in fused if f.fact_id == fid), 0.5) * 0.8
-                                    ),
+                                    fact_id=sfid, fused_score=new_score,
                                     channel_ranks={}, channel_scores={},
                                 ))
+                                fused_ids.add(sfid)
+                                fused_scores[sfid] = new_score
             except Exception as exc:
                 logger.warning("Scene expansion: %s", exc)
 

package/src/superlocalmemory/retrieval/entity_channel.py

@@ -118,9 +118,17 @@ class EntityGraphChannel:
         """
         # Check staleness: profile changed or new edges added since last load
         current_count = self._get_edge_count(profile_id)
+        # memory-bounding-01: also reload if the cache is older than the TTL,
+        # even when the edge COUNT is unchanged. Edge weights/pruning can mutate
+        # the graph without changing the count (e.g. store_edge MAX-merge), and a
+        # count-stable window would otherwise serve a stale adjacency map.
+        import time as _t_ec
+        _now_ec = _t_ec.monotonic()
+        _fresh = (_now_ec - getattr(self, "_adj_loaded_at", 0.0)) < 300.0
         if (self._adj_profile == profile_id
                 and self._adj
-                and self._adj_edge_count == current_count):
+                and self._adj_edge_count == current_count
+                and _fresh):
             return
         adj: dict[str, list[tuple[str, float]]] = defaultdict(list)
         try:
@@ -138,6 +146,7 @@ class EntityGraphChannel:
         self._adj = dict(adj)  # Convert defaultdict to regular dict (no accidental growth)
         self._adj_profile = profile_id
         self._adj_edge_count = current_count
+        self._adj_loaded_at = _now_ec  # memory-bounding-01: TTL reference
         # Also load entity maps (same staleness lifecycle)
         self._load_entity_maps(profile_id)
         # v3.4.1: Load graph intelligence metrics (P0)

package/src/superlocalmemory/retrieval/hopfield_channel.py

@@ -302,7 +302,9 @@ class HopfieldChannel:
             return (self._cached_matrix, self._cached_fact_ids)
 
         # Step 2: Load facts (V3.3.12: cap to most recent 5000 to bound memory)
-        facts = self._db.get_all_facts(profile_id)[:5000]
+        # memory-bounding-02: push the cap into SQL (LIMIT) so we don't
+        # deserialize the whole table just to slice it.
+        facts = self._db.get_all_facts(profile_id, limit=5000)
         if not facts:
             return (None, [])
 

package/src/superlocalmemory/storage/database.py

@@ -188,7 +188,47 @@ class DatabaseManager:
         return ""
 
     def store_fact(self, fact: AtomicFact) -> str:
-        """Persist an atomic fact. Returns fact_id."""
+        """Persist an atomic fact. Returns fact_id.
+
+        v3.6.4 — idempotent on content. If an ACTIVE fact with identical
+        content already exists for this profile, reinforce it (bump
+        evidence_count + access_count) and return its fact_id instead of
+        inserting a duplicate row. The passed fact's ``fact_id`` is rewritten
+        to the canonical id so downstream writes keyed on it (embeddings,
+        graph edges, context) target the real fact rather than orphaning.
+
+        This enforces the memory-system invariant "storing the same fact
+        twice is one fact" — preventing the duplicate explosion that poisons
+        importance ranking and core-memory promotion. Empty/whitespace
+        content is exempt (handled by placeholder filtering, not dedup).
+        """
+        if fact.content and fact.content.strip():
+            # Dedup across all LIVE lifecycle zones (active/warm/cold). Excludes
+            # 'archived' — that is soft-deleted/forgotten, so re-storing the same
+            # content correctly re-learns it as a fresh fact. Matching only
+            # 'active' (pre-3.6.4) re-opened the duplication window for every
+            # fact that aged to warm/cold (the bulk of the KB).
+            existing = self.execute(
+                "SELECT fact_id FROM atomic_facts "
+                "WHERE profile_id = ? AND content = ? "
+                "AND lifecycle IN ('active', 'warm', 'cold') "
+                "ORDER BY created_at LIMIT 1",
+                (fact.profile_id, fact.content),
+            )
+            if existing:
+                canonical_id = dict(existing[0])["fact_id"]
+                self.execute(
+                    "UPDATE atomic_facts "
+                    "SET evidence_count = evidence_count + 1, "
+                    "    access_count = access_count + 1 "
+                    "WHERE fact_id = ?",
+                    (canonical_id,),
+                )
+                # Rewrite caller's id so downstream embedding/graph/context
+                # writes target the canonical fact (idempotent), not an
+                # orphaned id that was never inserted.
+                fact.fact_id = canonical_id
+                return canonical_id
         self.execute(
             """INSERT OR REPLACE INTO atomic_facts
                (fact_id, memory_id, profile_id, content, fact_type,
@@ -259,12 +299,26 @@ class DatabaseManager:
         )
         return [self._row_to_fact(r) for r in rows]
 
-    def get_all_facts(self, profile_id: str) -> list[AtomicFact]:
-        """All facts for a profile, newest first."""
-        rows = self.execute(
-            "SELECT * FROM atomic_facts WHERE profile_id = ? ORDER BY created_at DESC",
-            (profile_id,),
-        )
+    def get_all_facts(
+        self, profile_id: str, limit: int | None = None,
+    ) -> list[AtomicFact]:
+        """All facts for a profile, newest first.
+
+        memory-bounding-02: optional SQL LIMIT so callers needing only the
+        most-recent N (e.g. the Hopfield channel's 5000 cap) don't deserialize
+        the entire table into AtomicFact objects. Default (None) = all facts.
+        """
+        if limit is not None:
+            rows = self.execute(
+                "SELECT * FROM atomic_facts WHERE profile_id = ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (profile_id, int(limit)),
+            )
+        else:
+            rows = self.execute(
+                "SELECT * FROM atomic_facts WHERE profile_id = ? ORDER BY created_at DESC",
+                (profile_id,),
+            )
         return [self._row_to_fact(r) for r in rows]
 
     _MAX_FACTS_PER_ENTITY_LOOKUP: int = 100
@@ -325,9 +379,38 @@ class DatabaseManager:
         )
 
     def delete_fact(self, fact_id: str) -> None:
-        """Hard-delete a fact."""
+        """Hard-delete a fact.
+
+        DatabaseManager connections enforce FKs (PRAGMA foreign_keys=ON), so
+        embedding_metadata / fact_retention / edges cascade. The explicit
+        embedding_metadata delete below is belt-and-suspenders for the case a
+        future caller routes through a connection without FK enforcement.
+        """
+        self.execute("DELETE FROM embedding_metadata WHERE fact_id = ?", (fact_id,))
         self.execute("DELETE FROM atomic_facts WHERE fact_id = ?", (fact_id,))
 
+    def gc_orphaned_embedding_metadata(self) -> int:
+        """Remove embedding_metadata rows whose parent atomic_fact is gone.
+
+        P1-3 (embeddings-vector-02): orphans accumulate when facts are deleted
+        through a connection that has FK enforcement OFF (the ON DELETE CASCADE
+        never fires). Vector search maps a vec0 rowid → fact_id via this table;
+        orphans return stale fact_ids that fail downstream fetch. This
+        maintenance sweep removes them regardless of how they were created.
+        Returns the number of rows deleted.
+        """
+        rows = self.execute(
+            "SELECT COUNT(*) AS c FROM embedding_metadata "
+            "WHERE fact_id NOT IN (SELECT fact_id FROM atomic_facts)"
+        )
+        n = int(rows[0]["c"]) if rows else 0
+        if n:
+            self.execute(
+                "DELETE FROM embedding_metadata "
+                "WHERE fact_id NOT IN (SELECT fact_id FROM atomic_facts)"
+            )
+        return n
+
     def get_fact_count(self, profile_id: str) -> int:
         """Total fact count for a profile."""
         rows = self.execute(
@@ -408,7 +491,28 @@ class DatabaseManager:
         return [self._row_to_fact(r) for r in rows]
 
     def store_edge(self, edge: GraphEdge) -> str:
-        """Persist a graph edge. Returns edge_id."""
+        """Persist a graph edge. Returns edge_id.
+
+        graph-integrity-02: dedup on the LOGICAL edge identity
+        (profile, source, target, type). The PK is a random edge_id, so
+        without this every re-link created a duplicate row, and NetworkX
+        builds read last-weight-wins — corrupting PageRank/centrality. On a
+        duplicate we keep the MAX weight (strongest association wins) and
+        return the existing edge_id.
+        """
+        existing = self.execute(
+            "SELECT edge_id FROM graph_edges "
+            "WHERE profile_id = ? AND source_id = ? AND target_id = ? AND edge_type = ? "
+            "LIMIT 1",
+            (edge.profile_id, edge.source_id, edge.target_id, edge.edge_type.value),
+        )
+        if existing:
+            canonical_id = dict(existing[0])["edge_id"]
+            self.execute(
+                "UPDATE graph_edges SET weight = MAX(weight, ?) WHERE edge_id = ?",
+                (edge.weight, canonical_id),
+            )
+            return canonical_id
         self.execute(
             """INSERT OR REPLACE INTO graph_edges
                (edge_id, profile_id, source_id, target_id, edge_type, weight, created_at)

package/src/superlocalmemory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.6.0
+Version: 3.6.4
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later