superlocalmemory 3.6.3 → 3.6.5

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.6.3",
+  "version": "3.6.5",
   "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.3"
+version = "3.6.5"
 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.3"
+__version__ = "3.6.5"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",
@@ -36,22 +36,35 @@ _REQUIRED_VERSIONS = {
 }
 
 
+# Module name -> distribution name for metadata lookup.
+_DIST_NAMES = {
+    "sentence_transformers": "sentence-transformers",
+    "onnxruntime": "onnxruntime",
+}
+
+
 def _check_critical_deps() -> None:
-    """Warn if embedding-critical packages have wrong versions."""
+    """Warn if embedding-critical packages have wrong versions.
+
+    Reads installed versions from package metadata — does NOT import the
+    packages. Importing sentence_transformers here would eagerly load torch
+    (native) into every process: a memory blow-up on Apple Silicon and, on
+    some interpreters, a source of native-heap instability at teardown.
+    """
     import warnings
+    from importlib import metadata
     for mod_name, expected in _REQUIRED_VERSIONS.items():
         try:
-            mod = __import__(mod_name)
-            actual = getattr(mod, "__version__", None)
-            if actual and actual != expected:
-                warnings.warn(
-                    f"SuperLocalMemory requires {mod_name}=={expected} but "
-                    f"{actual} is installed. This causes memory blow-up on "
-                    f"Apple Silicon. Fix: pip install {mod_name}=={expected}",
-                    stacklevel=2,
-                )
-        except ImportError:
-            pass
+            actual = metadata.version(_DIST_NAMES[mod_name])
+        except metadata.PackageNotFoundError:
+            continue
+        if actual != expected:
+            warnings.warn(
+                f"SuperLocalMemory requires {mod_name}=={expected} but "
+                f"{actual} is installed. This causes memory blow-up on "
+                f"Apple Silicon. Fix: pip install {mod_name}=={expected}",
+                stacklevel=2,
+            )
 
 
 # Only run the dep check when a full (non-LIGHT) engine is in use.

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

package/src/superlocalmemory/core/store_pipeline.py

@@ -102,6 +102,37 @@ def enrich_fact(
     )
 
 
+# ---------------------------------------------------------------------------
+# Vector dual-write helper (P1-2 / embeddings-vector-01)
+# ---------------------------------------------------------------------------
+
+def _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder=None):
+    """Dual-write a fact's embedding to the ANN index + sqlite-vec store.
+
+    Embeds on-demand when the fact has no embedding (e.g. consolidated
+    summary facts created without one), so UPDATE/SUPERSEDE and consolidated
+    facts remain visible to the semantic channel instead of having a row in
+    ``atomic_facts`` but none in the vector store.
+    """
+    if not getattr(fact, "embedding", None) and embedder is not None and fact.content:
+        try:
+            fact.embedding = embedder.embed(fact.content)
+        except Exception as _emb_exc:  # pragma: no cover - defensive
+            logger.debug("on-demand embed failed for %s: %s", fact.fact_id, _emb_exc)
+            return
+    if not getattr(fact, "embedding", None):
+        return
+    if ann_index:
+        ann_index.add(fact.fact_id, fact.embedding)
+    # V3.2: VectorStore upsert (sqlite-vec) -- dual-write (Rule 12)
+    if vector_store and getattr(vector_store, "available", False):
+        vector_store.upsert(
+            fact_id=fact.fact_id,
+            profile_id=profile_id,
+            embedding=fact.embedding,
+        )
+
+
 # ---------------------------------------------------------------------------
 # run_store  (was MemoryEngine.store)
 # ---------------------------------------------------------------------------
@@ -175,10 +206,20 @@ def run_store(
     )
     db.store_memory(record)
 
-    facts = fact_extractor.extract_facts(
-        turns=[content], session_id=session_id,
-        session_date=parsed_date, speaker_a=speaker,
-    )
+    try:
+        facts = fact_extractor.extract_facts(
+            turns=[content], session_id=session_id,
+            session_date=parsed_date, speaker_a=speaker,
+        )
+    except Exception as _extract_exc:
+        # P0-1 (remember-write-04): an extractor EXCEPTION (transient LLM/embed
+        # backend error) must NOT orphan the already-committed memory. The None
+        # guard below only handled a None *return*, not a raise. Treat a raise
+        # as "no facts" so the verbatim/raw fallback persists the content.
+        logger.warning(
+            "extract_facts() raised — falling back to raw fact: %s", _extract_exc,
+        )
+        facts = None
 
     # v3.4.38: Defensive None guard. extract_facts() returns None on transient
     # failures (embedding worker timeout, LLM call fail). Without this guard,
@@ -257,58 +298,77 @@ def run_store(
         )
 
         if consolidator:
-            action = consolidator.consolidate(fact, profile_id)
-            if action.action_type.value == "noop":
-                continue
-
-            # Opinion confidence tracking: reinforce or decay
-            if fact.fact_type == FactType.OPINION and action.action_type.value == "update":
-                try:
-                    existing = db.get_fact(action.new_fact_id)
-                    if existing and existing.fact_type == FactType.OPINION:
-                        new_conf = min(1.0, existing.confidence + 0.1)
-                        db.update_fact(action.new_fact_id, {"confidence": new_conf})
-                except Exception:
-                    pass
-            elif fact.fact_type == FactType.OPINION and action.action_type.value == "supersede":
-                try:
-                    old_id = getattr(action, "old_fact_id", None)
-                    if old_id:
-                        old_fact = db.get_fact(old_id)
-                        if old_fact:
-                            new_conf = max(0.0, old_fact.confidence - 0.2)
-                            db.update_fact(old_id, {"confidence": new_conf})
-                except Exception:
-                    pass
-
-            if action.action_type.value in ("update", "supersede"):
-                updated_fact = db.get_fact(action.new_fact_id)
-                if updated_fact:
-                    if graph_builder:
-                        graph_builder.build_edges(updated_fact, profile_id)
-                    if observation_builder:
-                        for eid in updated_fact.canonical_entities:
-                            observation_builder.update_profile(
-                                eid, updated_fact, profile_id,
-                            )
-                stored_ids.append(action.new_fact_id)
-                continue
-            # ADD case: consolidator already stored the fact (F8 fix)
-            # Fall through to post-processing below
+            try:
+                action = consolidator.consolidate(fact, profile_id)
+            except Exception as _consolidate_exc:
+                # P0-1 (remember-write-03): a consolidate failure (e.g. LLM
+                # timeout) must NOT orphan the already-committed memory. Fall
+                # back to storing the raw enriched fact so the content stays
+                # retrievable across all channels.
+                logger.warning(
+                    "consolidate() failed for fact %s — storing raw fact as "
+                    "fallback: %s", fact.fact_id, _consolidate_exc,
+                )
+                action = None
+
+            if action is not None:
+                if action.action_type.value == "noop":
+                    continue
+
+                # Opinion confidence tracking: reinforce or decay
+                if fact.fact_type == FactType.OPINION and action.action_type.value == "update":
+                    try:
+                        existing = db.get_fact(action.new_fact_id)
+                        if existing and existing.fact_type == FactType.OPINION:
+                            new_conf = min(1.0, existing.confidence + 0.1)
+                            db.update_fact(action.new_fact_id, {"confidence": new_conf})
+                    except Exception:
+                        pass
+                elif fact.fact_type == FactType.OPINION and action.action_type.value == "supersede":
+                    try:
+                        old_id = getattr(action, "old_fact_id", None)
+                        if old_id:
+                            old_fact = db.get_fact(old_id)
+                            if old_fact:
+                                new_conf = max(0.0, old_fact.confidence - 0.2)
+                                db.update_fact(old_id, {"confidence": new_conf})
+                    except Exception:
+                        pass
+
+                if action.action_type.value in ("update", "supersede"):
+                    updated_fact = db.get_fact(action.new_fact_id)
+                    if updated_fact:
+                        # P1-2 (embeddings-vector-01): the merged/superseding
+                        # fact must reach the vector store (embed on-demand if
+                        # it has none) — otherwise it is invisible to the
+                        # semantic channel despite living in atomic_facts.
+                        _upsert_fact_vectors(
+                            updated_fact, profile_id, ann_index, vector_store, embedder,
+                        )
+                        if graph_builder:
+                            graph_builder.build_edges(updated_fact, profile_id)
+                        if observation_builder:
+                            for eid in updated_fact.canonical_entities:
+                                observation_builder.update_profile(
+                                    eid, updated_fact, profile_id,
+                                )
+                    stored_ids.append(action.new_fact_id)
+                    continue
+                # ADD case: consolidator already stored the fact (F8 fix)
+                # Fall through to post-processing below
+            else:
+                # Consolidate failed → store the raw fact ourselves so the
+                # memory is never left without a retrievable fact, then fall
+                # through to post-processing (embeddings, graph, context).
+                db.store_fact(fact)
         else:
             db.store_fact(fact)
 
         stored_ids.append(fact.fact_id)
 
-        if fact.embedding and ann_index:
-            ann_index.add(fact.fact_id, fact.embedding)
-        # V3.2: VectorStore upsert (sqlite-vec) -- dual-write (Rule 12)
-        if fact.embedding and vector_store and vector_store.available:
-            vector_store.upsert(
-                fact_id=fact.fact_id,
-                profile_id=profile_id,
-                embedding=fact.embedding,
-            )
+        # Dual-write embedding to ANN index + vector store (embed on-demand if
+        # a consolidated ADD fact arrived without one). See _upsert_fact_vectors.
+        _upsert_fact_vectors(fact, profile_id, ann_index, vector_store, embedder)
         # Phase 2: Generate contextual description (after consolidator, before graph_builder)
         if context_generator:
             try:
@@ -489,6 +549,15 @@ def run_store_fact_direct(
     and graph edges are all populated — even for auxiliary data.
     Creates a parent memory record to satisfy FK constraint.
     """
+    # remember-write-02: gate low-quality content (empty, bare category tags,
+    # placeholder/template leakage) at the WRITE boundary, matching run_store's
+    # gate. Previously this direct path had no filter, so junk entered the KB
+    # and polluted evidence/stats/embeddings (the read-side filter only hid it).
+    from superlocalmemory.core.injection import is_low_quality
+    if is_low_quality(fact.content):
+        logger.debug("run_store_fact_direct: skipping low-quality content")
+        return fact.fact_id
+
     # Create parent memory record (FK: atomic_facts.memory_id → memories.memory_id)
     if not fact.memory_id:
         record = MemoryRecord(

package/src/superlocalmemory/mcp/_stdin_guard.py

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Pure decision logic for the MCP stdin-EOF self-termination monitor.
+
+Isolated here (no imports, no side effects) so the kqueue ``EV_EOF``
+handling contract is unit-testable without importing the FastMCP server
+module, which starts daemon threads and auto-starts the SLM daemon at
+import time.
+
+Background (v3.6.4 fix)
+-----------------------
+The stdin-EOF monitor (``superlocalmemory.mcp.server._stdin_eof_monitor``)
+exists to reap orphaned ``slm mcp`` processes when an IDE/agent abandons the
+stdio pipe without quitting. It registers ``EVFILT_READ | EV_EOF`` on stdin
+and terminates the process when the write-end closes.
+
+On macOS, ``EVFILT_READ`` reports ``EV_EOF`` *together with* still-readable
+bytes (``ev.data > 0``) when the write-end is closed while a final request
+is still buffered in the pipe. The original monitor exited on the EOF flag
+alone — dropping that buffered request and tearing down a session that
+still had a pending in-flight call. Under strict MCP hosts whose transport
+half-closes stdin around reconnect/teardown, this surfaced as the server
+self-terminating mid-request, which the host then logged as a keepalive
+failure and respawned (observed against the Hermes agent).
+
+The guard defers termination until the buffer is genuinely drained
+(``ev.data <= 0``), letting the FastMCP reader consume the last request
+first. Genuine disconnects (EOF with an empty buffer) still terminate
+immediately — behaviour identical to before for the common case.
+"""
+
+from __future__ import annotations
+
+__all__ = ["eof_action"]
+
+
+def eof_action(flags: int, data: int, eof_flag: int) -> str:
+    """Decide how the stdin-EOF monitor should react to one kqueue event.
+
+    Args:
+        flags: ``kevent.flags`` bitmask returned by ``kqueue.control``.
+        data: ``kevent.data`` — for ``EVFILT_READ`` this is the number of
+            bytes still readable on the descriptor.
+        eof_flag: the platform ``select.KQ_EV_EOF`` constant (injected so
+            this function stays import-free and trivially testable).
+
+    Returns:
+        - ``"exit"``   — genuine end-of-stream: write-end closed and the
+          buffer is drained (``data <= 0``). Safe to self-terminate.
+        - ``"drain"``  — write-end closed but unread bytes remain
+          (``data > 0``). Must NOT terminate yet; let the reader consume
+          the buffered request first, otherwise it is silently dropped.
+        - ``"ignore"`` — no EOF on this event (ordinary readability or a
+          spurious wake); nothing to do.
+    """
+    if not (flags & eof_flag):
+        return "ignore"
+    return "drain" if data > 0 else "exit"

package/src/superlocalmemory/mcp/server.py

@@ -288,11 +288,26 @@ _watchdog_thread.start()
 # closes WITHOUT consuming any bytes, so it cannot race with FastMCP's asyncio
 # stdin reader. On Linux (no kqueue), the watchdog alone provides coverage.
 def _stdin_eof_monitor() -> None:
-    """Exit when the IDE closes our stdin pipe (kqueue — macOS only)."""
-    import select as _sel, os as _os_eof
+    """Exit when the IDE closes our stdin pipe (kqueue — macOS only).
+
+    V3.6.4: kqueue ``EVFILT_READ`` reports ``EV_EOF`` *together with*
+    still-readable bytes (``ev.data > 0``) when the write-end closes while a
+    final request is buffered. Exiting on the EOF flag alone (pre-3.6.4)
+    dropped that in-flight request and self-terminated a session that still
+    had work to deliver — strict MCP hosts (e.g. the Hermes agent) then
+    logged a keepalive failure and respawned the process. We now defer
+    termination until the buffer is genuinely drained (see ``_stdin_guard``).
+    """
+    import select as _sel, os as _os_eof, time as _time
+    from superlocalmemory.mcp._stdin_guard import eof_action
     _mlog = logging.getLogger(__name__ + ".stdin_monitor")
     if not hasattr(_sel, "kqueue"):
         return  # Linux / non-macOS: watchdog covers process death
+    # Bounded grace for the FastMCP reader to drain a buffered final request
+    # before we tear down. ~2 s ceiling (40 × 50 ms): a genuine EOF means the
+    # session is ending regardless, so we never wait indefinitely.
+    _DRAIN_POLL_S = 0.05
+    _DRAIN_MAX_POLLS = 40
     try:
         fd = sys.stdin.fileno()
         kq = _sel.kqueue()
@@ -301,9 +316,23 @@ def _stdin_eof_monitor() -> None:
         while True:
             evs = kq.control(None, 4, 30.0)  # 30 s poll — low cost
             for ev in evs:
-                if ev.flags & _sel.KQ_EV_EOF:
-                    _mlog.info("stdin write-end closed (kqueue EOF), self-terminating")
-                    _os_eof._exit(0)
+                action = eof_action(ev.flags, ev.data, _sel.KQ_EV_EOF)
+                if action == "ignore":
+                    continue
+                if action == "drain":
+                    # Write-end closed but unread bytes remain. Let the
+                    # FastMCP reader consume the final request(s); poll until
+                    # drained or the grace ceiling elapses.
+                    for _ in range(_DRAIN_MAX_POLLS):
+                        _time.sleep(_DRAIN_POLL_S)
+                        recheck = kq.control(None, 4, 0)  # non-blocking
+                        if not recheck:
+                            break
+                        ev = recheck[0]
+                        if eof_action(ev.flags, ev.data, _sel.KQ_EV_EOF) != "drain":
+                            break
+                _mlog.info("stdin write-end closed (kqueue EOF, drained), self-terminating")
+                _os_eof._exit(0)
     except Exception as exc:
         _mlog.debug("stdin EOF monitor error: %s — watchdog will cover", exc)
 

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.3
+Version: 3.6.5
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later

package/src/superlocalmemory.egg-info/SOURCES.txt

@@ -268,6 +268,7 @@ src/superlocalmemory/math/turbo_quant.py
 src/superlocalmemory/mcp/__init__.py
 src/superlocalmemory/mcp/_daemon_proxy.py
 src/superlocalmemory/mcp/_pool_adapter.py
+src/superlocalmemory/mcp/_stdin_guard.py
 src/superlocalmemory/mcp/resources.py
 src/superlocalmemory/mcp/server.py
 src/superlocalmemory/mcp/shared.py
@@ -503,6 +504,7 @@ tests/test_engine_hooks.py
 tests/test_event_bus.py
 tests/test_features.py
 tests/test_final_locomo_mini.py
+tests/test_graph_integrity.py
 tests/test_hook_handlers.py
 tests/test_ide_connector.py
 tests/test_infra.py