superlocalmemory 3.4.30 → 3.4.32

package/CHANGELOG.md

@@ -10,6 +10,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.4.32] - 2026-04-24
+
+Fix: concurrent remembers no longer block recalls on the shared embedder.
+
+### Fixed
+- **Daemon `/remember` is now async by default.** Writes to the pending
+  queue in under 100 ms and returns a `pending_id`; a background thread
+  drains the queue in the background. Previously, the synchronous
+  `engine.store()` on the FastAPI event loop could block `/search` and
+  `/health` for 30+ seconds while the single embedder worker processed a
+  large write. Under concurrent load the daemon could appear hung.
+- **Materializer yields to active recalls.** While any `/search` is in
+  flight the drainer sleeps between items, so user-initiated recalls
+  always get the embedder first.
+- **MCP remember tool simplified.** Writes to `pending.db` and returns;
+  the daemon's materializer completes the pipeline. Removes the
+  redundant in-process `pool.store` background task that previously
+  contended with `/search`.
+- **`pool_store` returns `["pending:<id>"]`** when the daemon is async,
+  keeping a stable identifier for callers without blocking on the
+  embedder.
+
+### Added
+- `?wait=true` query parameter on `POST /remember` for callers that
+  need synchronous behaviour and real `fact_ids` in the response.
+- `superlocalmemory.core.recall_gate` module — shared counter that lets
+  the materializer detect in-flight recalls and yield priority.
+
+### Migration notes
+- **No action required.** Existing clients continue to work; the
+  response shape is compatible (`ok`, `count` still present). Scripts
+  that depended on `fact_ids` to validate the write should switch to
+  `pending_id` or pass `?wait=true` to opt in to the legacy behaviour.
+
+---
+
+## [3.4.31] - 2026-04-24
+
+Dashboard truth, memory vs fact clarity, and self-cleaning pending queue.
+
+### Changed
+- **Dashboard now shows both memory counts honestly.** Parent memories
+  (what you stored) and atomic facts (what retrieval indexes) appear as
+  two distinct cards with their ratio. No more "Total Memories: 6,000"
+  when you actually have 2,000 memories decomposed into 6,000 facts.
+- **"Browse atomic facts"** relabeled for clarity — this view lists the
+  indexed atomic units.
+- **Visible search box** in the Memories tab — previously hidden behind
+  the Recall Lab only. Search now debounces 280 ms on input.
+
+### Added
+- **`/api/memories/{id}/detail`** — full memory + all child atomic facts
+  in one call. Powers the click-to-expand modal.
+- **`/api/facts/{id}`** — single atomic fact detail with source memory
+  content, entities, and canonical entities.
+- **Pagination UI** — Prev/Next controls show "Showing 1–50 of 6,123".
+  Previously hardcoded to 50 with no navigation.
+- **CSV export** — new `format=csv` option on `/api/export` plus a
+  dedicated "Export All (CSV)" menu item. JSON and JSONL still work.
+- **Export progress toast** — "Preparing JSON export…" notification
+  before the download starts.
+- **`total_facts` + `facts_per_memory`** in `/api/stats` response.
+- **Pending queue auto-cleanup** — the maintenance scheduler now sweeps
+  the pending queue every cycle: completed rows > 7 days, failed rows
+  over retry limit, and stuck rows > 7 days are removed; a 30-day hard
+  cap prevents runaway growth on any status.
+
+### Fixed
+- **Test isolation** — `pending_store` now honors `SLM_DATA_DIR`. Four
+  MCP remember tests were writing to the live `~/.superlocalmemory/`
+  instead of `tmp_path`. Root conftest now forces `SLM_DATA_DIR=tmp_path`
+  for every test unless explicitly opted out.
+- **Fact click popup** — was calling `/api/v3/recall/trace` with a text
+  substring (re-query by first 100 chars) and colliding with the memory
+  row click handler. Now scoped to `.fact-result-item` only, hits the
+  new `/api/facts/{fact_id}` endpoint.
+- **Memory modal ID confusion** — the modal labeled `mem.id` as "ID"
+  regardless of whether it was a memory_id or fact_id. Now displays
+  both "Memory ID" and "Fact ID" when they differ.
+- **Memory modal hydration** — fetches the full memory + fact list
+  asynchronously when opened, so source content and entity data appear
+  even for rows that arrived from the search endpoint.
+
+---
+
 ## [3.4.30] - 2026-04-24
 
 Multi-IDE shared worker, silent migration, and security hardening.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.30",
+  "version": "3.4.32",
   "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.4.30"
+version = "3.4.32"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/__init__.py

@@ -1,3 +1,3 @@
 """SuperLocalMemory — information-geometric agent memory."""
 
-__version__ = "3.4.30"
+__version__ = "3.4.32"

package/src/superlocalmemory/cli/pending_store.py

@@ -24,12 +24,21 @@ License: Elastic-2.0
 from __future__ import annotations
 
 import json
+import os
 import sqlite3
 import time
 from pathlib import Path
 
-_DEFAULT_DIR = Path.home() / ".superlocalmemory"
+
+def _default_dir() -> Path:
+    """Honor SLM_DATA_DIR so tests can isolate via tmp_path."""
+    return Path(os.environ.get("SLM_DATA_DIR") or Path.home() / ".superlocalmemory")
+
+
 _PENDING_DB = "pending.db"
+_MAX_RETRIES = 3
+_STUCK_DAYS = 7
+_DEAD_LETTER_DAYS = 30
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS pending_memories (
@@ -47,7 +56,7 @@ CREATE TABLE IF NOT EXISTS pending_memories (
 
 def _get_db(base_dir: Path | None = None) -> sqlite3.Connection:
     """Open pending.db with WAL mode. Creates if needed."""
-    d = base_dir or _DEFAULT_DIR
+    d = base_dir or _default_dir()
     d.mkdir(parents=True, exist_ok=True)
     db_path = d / _PENDING_DB
     conn = sqlite3.connect(str(db_path), timeout=5)
@@ -128,7 +137,7 @@ def mark_failed(row_id: int, error: str, base_dir: Path | None = None) -> None:
 
 def pending_count(base_dir: Path | None = None) -> int:
     """Count unprocessed pending memories."""
-    d = base_dir or _DEFAULT_DIR
+    d = base_dir or _default_dir()
     db_path = d / _PENDING_DB
     if not db_path.exists():
         return 0
@@ -156,3 +165,46 @@ def cleanup_done(days: int = 7, base_dir: Path | None = None) -> int:
         return cur.rowcount
     finally:
         conn.close()
+
+
+def cleanup_stale(base_dir: Path | None = None) -> dict[str, int]:
+    """Sweep stale rows from pending.db. Runs periodically from the daemon.
+
+    Removes:
+    - `done` rows older than 7 days (already processed)
+    - `failed` rows that exceeded max retries (moved to dead-letter via deletion)
+    - `pending` rows stuck more than 7 days (test pollution, crashed workers)
+    - Everything older than 30 days regardless of status (hard cap)
+    """
+    conn = _get_db(base_dir)
+    try:
+        done = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'done' "
+            "AND created_at < datetime('now', ?)",
+            (f"-{_STUCK_DAYS} days",),
+        ).rowcount
+        failed = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'failed' "
+            "AND retry_count >= ?",
+            (_MAX_RETRIES,),
+        ).rowcount
+        stuck = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'pending' "
+            "AND created_at < datetime('now', ?)",
+            (f"-{_STUCK_DAYS} days",),
+        ).rowcount
+        hard_cap = conn.execute(
+            "DELETE FROM pending_memories "
+            "WHERE created_at < datetime('now', ?)",
+            (f"-{_DEAD_LETTER_DAYS} days",),
+        ).rowcount
+        conn.commit()
+        return {
+            "done": done,
+            "failed_over_retries": failed,
+            "stuck_pending": stuck,
+            "hard_cap_expired": hard_cap,
+            "total": done + failed + stuck + hard_cap,
+        }
+    finally:
+        conn.close()

package/src/superlocalmemory/core/maintenance_scheduler.py

@@ -116,6 +116,14 @@ class MaintenanceScheduler:
         except Exception as exc:
             logger.debug("Auto-backup check skipped: %s", exc)
 
+        try:
+            from superlocalmemory.cli.pending_store import cleanup_stale
+            stats = cleanup_stale()
+            if stats["total"] > 0:
+                logger.info("Pending cleanup: %s", stats)
+        except Exception as exc:
+            logger.debug("Pending cleanup skipped: %s", exc)
+
         self._schedule_next()
 
     def _sync_cloud_destinations(self, manager: object) -> None:

package/src/superlocalmemory/core/recall_gate.py

@@ -0,0 +1,36 @@
+# 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
+
+"""v3.4.32: Recall-in-flight counter used to give /search priority over the
+pending materializer.
+
+Every recall handler calls ``begin_recall()`` on entry and ``end_recall()``
+in a finally block. The pending-memory materializer thread polls
+``in_flight()`` and sleeps while any recall is active, so the shared
+embedder worker never serves a materialization ahead of a user-initiated
+recall.
+"""
+from __future__ import annotations
+
+import threading
+
+_lock = threading.Lock()
+_active = 0
+
+
+def begin_recall() -> None:
+    global _active
+    with _lock:
+        _active += 1
+
+
+def end_recall() -> None:
+    global _active
+    with _lock:
+        _active = max(0, _active - 1)
+
+
+def in_flight() -> int:
+    with _lock:
+        return _active

package/src/superlocalmemory/learning/signals.py

@@ -141,12 +141,18 @@ def reset_counters() -> None:
 
 
 def _drain_queue_for_tests() -> None:
-    """Drain the module queue — TEST-ONLY."""
+    """Drain the module queue — TEST-ONLY.
+
+    Swallows AttributeError so test harnesses that swap in a minimal
+    stub queue (e.g. exploding-queue fixtures) can still clean up.
+    """
     while True:
         try:
             _Q.get_nowait()
         except queue.Empty:
             return
+        except AttributeError:
+            return
 
 
 def queue_size() -> int:

package/src/superlocalmemory/mcp/_pool_adapter.py

@@ -110,12 +110,24 @@ def pool_recall(query: str, limit: int = 10, **_: Any) -> PoolRecallResponse:
 
 
 def pool_store(content: str, metadata: dict | None = None) -> list[str]:
-    """Call pool.store and return the fact id list.
+    """Call pool.store and return fact id list (or pending tracker).
 
-    Raises :class:`PoolError` on worker death or any non-ok envelope.
+    v3.4.32: the daemon /remember endpoint is async by default — it
+    returns ``pending_id`` and queues the write. We surface this to
+    callers as ``["pending:<id>"]`` so they have a stable identifier
+    without blocking the remember on the embedder worker.
+
+    Legacy synchronous path (``?wait=true``) still returns real
+    ``fact_ids``. Worker death raises :class:`PoolError`.
     """
     raw = _pool().store(content=content, metadata=metadata or {})
     _unwrap_error(raw, "store")
-    if isinstance(raw, dict):
-        return list(raw.get("fact_ids", []))
+    if not isinstance(raw, dict):
+        return []
+    fact_ids = raw.get("fact_ids")
+    if fact_ids:
+        return list(fact_ids)
+    pending_id = raw.get("pending_id")
+    if pending_id is not None:
+        return [f"pending:{pending_id}"]
     return []

package/src/superlocalmemory/mcp/tools_core.py

@@ -113,12 +113,11 @@ def register_core_tools(server, get_engine: Callable) -> None:
         """
         import asyncio
         try:
-            # V3.3.27: Store-first pattern — write to pending.db immediately
-            # (<100ms), then process through full pipeline in background.
-            # This eliminates the 30-40s blocking that Mode B users experience.
-            # Pending memories are auto-processed on next engine.initialize()
-            # or by the daemon's background loop.
-            from superlocalmemory.cli.pending_store import store_pending, mark_done
+            # v3.4.32: Store-first pattern. Write to pending.db and return
+            # immediately. The daemon's pending-materializer thread drains
+            # the queue with recall priority, so concurrent MCP remembers
+            # no longer contend with /search on the shared embedder.
+            from superlocalmemory.cli.pending_store import store_pending
 
             pending_id = store_pending(content, tags=tags, metadata={
                 "project": project,
@@ -127,39 +126,13 @@ def register_core_tools(server, get_engine: Callable) -> None:
                 "session_id": session_id,
             })
 
-            # Fire-and-forget: process in background thread
-            async def _process_in_background():
-                try:
-                    from superlocalmemory.core.worker_pool import WorkerPool
-                    pool = WorkerPool.shared()
-                    result = await asyncio.to_thread(
-                        pool.store, content, metadata={
-                            "tags": tags, "project": project,
-                            "importance": importance, "agent_id": agent_id,
-                            "session_id": session_id,
-                        },
-                    )
-                    if result.get("ok"):
-                        mark_done(pending_id)
-                        _emit_event("memory.created", {
-                            "content_preview": content[:80],
-                            "agent_id": agent_id,
-                            "fact_count": result.get("count", 0),
-                        }, source_agent=agent_id)
-                except Exception as _bg_exc:
-                    logger.warning(
-                        "Background store failed (pending_id=%s): %s",
-                        pending_id, _bg_exc,
-                    )
-
-            asyncio.create_task(_process_in_background())
-
             return {
                 "success": True,
                 "fact_ids": [f"pending:{pending_id}"],
                 "count": 1,
                 "pending": True,
-                "message": "Stored to pending — processing in background.",
+                "pending_id": pending_id,
+                "message": "Stored — facts will appear in the dashboard shortly.",
             }
         except Exception as exc:
             logger.exception("remember failed")

package/src/superlocalmemory/server/routes/data_io.py

@@ -28,11 +28,11 @@ router = APIRouter()
 
 @router.get("/api/export")
 async def export_memories(
-    format: str = Query("json", pattern="^(json|jsonl)$"),
+    format: str = Query("json", pattern="^(json|jsonl|csv)$"),
     category: Optional[str] = None,
     project_name: Optional[str] = None,
 ):
-    """Export memories as JSON or JSONL."""
+    """Export memories as JSON, JSONL, or CSV."""
     try:
         conn = get_db_connection()
         conn.row_factory = dict_factory
@@ -76,6 +76,25 @@ async def export_memories(
         if format == "jsonl":
             content = "\n".join(json.dumps(m) for m in memories)
             media_type = "application/x-ndjson"
+        elif format == "csv":
+            import csv
+            import io as _io
+            if memories:
+                buf = _io.StringIO()
+                fieldnames = list(memories[0].keys())
+                writer = csv.DictWriter(
+                    buf, fieldnames=fieldnames, extrasaction="ignore",
+                )
+                writer.writeheader()
+                for m in memories:
+                    writer.writerow({
+                        k: (json.dumps(v) if isinstance(v, (dict, list)) else v)
+                        for k, v in m.items()
+                    })
+                content = buf.getvalue()
+            else:
+                content = ""
+            media_type = "text/csv"
         else:
             content = json.dumps({
                 "version": "3.0.0",

package/src/superlocalmemory/server/routes/memories.py

@@ -398,7 +398,12 @@ async def get_graph(
 
 @router.post("/api/search")
 async def search_memories(request: Request, body: SearchRequest):
-    """Semantic search via subprocess worker pool (memory-isolated)."""
+    """Semantic search via subprocess worker pool (memory-isolated).
+
+    v3.4.32: marks recall in-flight so the pending materializer yields.
+    """
+    from superlocalmemory.core.recall_gate import begin_recall, end_recall
+    begin_recall()
     try:
         from superlocalmemory.core.worker_pool import WorkerPool
         pool = WorkerPool.shared()
@@ -435,6 +440,8 @@ async def search_memories(request: Request, body: SearchRequest):
 
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Search error: {str(e)}")
+    finally:
+        end_recall()
 
 
 @router.get("/api/clusters")
@@ -607,6 +614,97 @@ async def get_memory_facts(request: Request, memory_id: str):
         raise HTTPException(status_code=500, detail=f"Error: {str(e)}")
 
 
+@router.get("/api/memories/{memory_id}/detail")
+async def get_memory_detail(request: Request, memory_id: str):
+    """Full memory row + all child atomic facts (for dashboard modal)."""
+    try:
+        conn = get_db_connection()
+        conn.row_factory = dict_factory
+        cursor = conn.cursor()
+        active_profile = get_active_profile()
+
+        cursor.execute(
+            "SELECT memory_id, content, session_id, speaker, role, "
+            "session_date, created_at, metadata_json "
+            "FROM memories WHERE memory_id = ? AND profile_id = ?",
+            (memory_id, active_profile),
+        )
+        mem = cursor.fetchone()
+        if not mem:
+            conn.close()
+            raise HTTPException(status_code=404, detail="Memory not found")
+
+        cursor.execute(
+            "SELECT fact_id, content, fact_type, confidence, importance, "
+            "access_count, created_at, entities_json "
+            "FROM atomic_facts WHERE memory_id = ? AND profile_id = ? "
+            "ORDER BY created_at ASC",
+            (memory_id, active_profile),
+        )
+        facts = cursor.fetchall()
+        conn.close()
+
+        try:
+            mem["metadata"] = json.loads(mem.pop("metadata_json") or "{}")
+        except Exception:
+            mem["metadata"] = {}
+        for f in facts:
+            try:
+                f["entities"] = json.loads(f.pop("entities_json") or "[]")
+            except Exception:
+                f["entities"] = []
+
+        return {
+            "memory": mem,
+            "facts": facts,
+            "fact_count": len(facts),
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Detail error: {str(e)}")
+
+
+@router.get("/api/facts/{fact_id}")
+async def get_fact_detail(request: Request, fact_id: str):
+    """Single atomic fact detail (for fact popup)."""
+    try:
+        conn = get_db_connection()
+        conn.row_factory = dict_factory
+        cursor = conn.cursor()
+        active_profile = get_active_profile()
+
+        cursor.execute(
+            "SELECT f.fact_id, f.memory_id, f.content, f.fact_type, "
+            "f.confidence, f.importance, f.access_count, f.created_at, "
+            "f.entities_json, f.canonical_entities_json, f.session_id, "
+            "m.content AS source_memory_content "
+            "FROM atomic_facts f "
+            "LEFT JOIN memories m ON f.memory_id = m.memory_id "
+            "WHERE f.fact_id = ? AND f.profile_id = ?",
+            (fact_id, active_profile),
+        )
+        row = cursor.fetchone()
+        conn.close()
+        if not row:
+            raise HTTPException(status_code=404, detail="Fact not found")
+        try:
+            row["entities"] = json.loads(row.pop("entities_json") or "[]")
+        except Exception:
+            row["entities"] = []
+        try:
+            row["canonical_entities"] = json.loads(
+                row.pop("canonical_entities_json") or "[]"
+            )
+        except Exception:
+            row["canonical_entities"] = []
+        return row
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Fact detail error: {str(e)}")
+
+
 @router.delete("/api/memories/{fact_id}")
 async def delete_memory(request: Request, fact_id: str):
     """Delete a specific memory (atomic fact) by ID."""

package/src/superlocalmemory/server/routes/stats.py

@@ -40,6 +40,12 @@ async def get_stats():
                 "SELECT COUNT(*) as total FROM atomic_facts WHERE profile_id = ?",
                 (active_profile,),
             )
+            total_facts = cursor.fetchone()['total']
+
+            cursor.execute(
+                "SELECT COUNT(*) as total FROM memories WHERE profile_id = ?",
+                (active_profile,),
+            )
             total_memories = cursor.fetchone()['total']
 
             total_sessions = 0
@@ -52,7 +58,7 @@ async def get_stats():
             except Exception:
                 pass
 
-            total_graph_nodes = total_memories
+            total_graph_nodes = total_facts
             total_graph_edges = 0
             try:
                 cursor.execute(
@@ -121,12 +127,13 @@ async def get_stats():
             importance_dist = []
 
         else:
-            # V2 fallback
+            # V2 fallback — no atomic_facts; facts == memories
             cursor.execute(
                 "SELECT COUNT(*) as total FROM memories WHERE profile = ?",
                 (active_profile,),
             )
             total_memories = cursor.fetchone()['total']
+            total_facts = total_memories
 
             try:
                 cursor.execute("SELECT COUNT(*) as total FROM sessions")
@@ -201,9 +208,16 @@ async def get_stats():
 
         conn.close()
 
+        facts_per_memory = (
+            round(total_facts / total_memories, 1)
+            if total_memories > 0 else 0.0
+        )
+
         return {
             "overview": {
                 "total_memories": total_memories,
+                "total_facts": total_facts,
+                "facts_per_memory": facts_per_memory,
                 "total_sessions": total_sessions,
                 "total_clusters": total_clusters,
                 "graph_nodes": total_graph_nodes,

package/src/superlocalmemory/server/unified_daemon.py

@@ -66,6 +66,20 @@ class ObserveRequest(BaseModel):
     content: str
 
 
+# ---------------------------------------------------------------------------
+# v3.4.32: Recall-priority gate for the pending materializer.
+# All /remember writes go to pending.db and return fast; a background
+# thread drains pending while yielding to any in-flight /search.
+# See ``superlocalmemory.core.recall_gate``.
+# ---------------------------------------------------------------------------
+
+from superlocalmemory.core.recall_gate import (
+    begin_recall as _begin_recall,
+    end_recall as _end_recall,
+    in_flight as _recalls_in_flight,
+)
+
+
 # ---------------------------------------------------------------------------
 # Observation debounce buffer (migrated from daemon.py)
 # ---------------------------------------------------------------------------
@@ -949,6 +963,8 @@ def _register_daemon_routes(application: FastAPI) -> None:
         if not effective_sid:
             import time as _t
             effective_sid = f"http:{int(_t.time() * 1000)}"
+        # v3.4.32: mark recall in-flight so the pending materializer pauses
+        _begin_recall()
         try:
             response = engine.recall(
                 search_query, limit=limit, session_id=effective_sid,
@@ -1006,18 +1022,47 @@ def _register_daemon_routes(application: FastAPI) -> None:
             }
         except Exception as exc:
             raise HTTPException(500, detail=str(exc))
+        finally:
+            _end_recall()
 
     @application.post("/remember")
-    async def remember(req: RememberRequest):
+    async def remember(req: RememberRequest, wait: bool = False):
+        """v3.4.32: Async by default — writes to pending.db, returns pending_id
+        in <100ms. Materializer thread drains at low priority, yielding to
+        /search. Pass ``?wait=true`` for legacy synchronous behavior (blocks
+        on the embedder until facts are written).
+        """
         _update_activity()
         engine = _get_engine_or_503()
+
+        if wait:
+            try:
+                metadata = {"tags": req.tags} if req.tags else {}
+                extra = getattr(req, "metadata", None)
+                if isinstance(extra, dict):
+                    metadata.update(extra)
+                fact_ids = engine.store(req.content, metadata=metadata)
+                return {"ok": True, "fact_ids": fact_ids, "count": len(fact_ids)}
+            except Exception as exc:
+                raise HTTPException(500, detail=str(exc))
+
         try:
-            metadata = {"tags": req.tags} if req.tags else {}
+            from superlocalmemory.cli.pending_store import store_pending
+            meta = {}
+            if req.tags:
+                meta["tags"] = req.tags
             extra = getattr(req, "metadata", None)
             if isinstance(extra, dict):
-                metadata.update(extra)
-            fact_ids = engine.store(req.content, metadata=metadata)
-            return {"ok": True, "fact_ids": fact_ids, "count": len(fact_ids)}
+                meta.update(extra)
+            pending_id = store_pending(
+                req.content, tags=req.tags or "", metadata=meta,
+            )
+            return {
+                "ok": True,
+                "pending_id": pending_id,
+                "status": "queued",
+                "note": "materialized async; pass ?wait=true for legacy sync",
+            }
         except Exception as exc:
             raise HTTPException(500, detail=str(exc))
 
@@ -1189,6 +1234,70 @@ def _start_memory_watchdog() -> None:
     logger.info("Memory watchdog started (limit: %d MB per worker)", MAX_WORKER_MB)
 
 
+_materializer_stop = threading.Event()
+_materializer_thread: threading.Thread | None = None
+
+
+def _start_pending_materializer() -> None:
+    """Background thread: drains pending.db, yields to active /search calls.
+
+    Poll loop:
+    1. Fetch up to 5 pending rows.
+    2. For each row: if any /search is in flight, sleep 500ms (yield priority).
+    3. Call engine.store(), mark_done or mark_failed.
+    4. Sleep 2s between polls when idle (empty queue).
+    """
+    global _materializer_thread
+
+    def _loop():
+        from superlocalmemory.cli.pending_store import (
+            get_pending, mark_done, mark_failed,
+        )
+        while not _materializer_stop.is_set():
+            try:
+                engine = _engine  # may be None briefly at startup
+                if engine is None:
+                    time.sleep(2.0)
+                    continue
+                pending = get_pending(limit=5)
+                if not pending:
+                    time.sleep(2.0)
+                    continue
+                for item in pending:
+                    if _materializer_stop.is_set():
+                        break
+                    # Yield to recalls: wait until none in flight
+                    waits = 0
+                    while _recalls_in_flight() > 0 and waits < 60:
+                        time.sleep(0.5)
+                        waits += 1
+                    try:
+                        import json as _json
+                        md_str = item.get("metadata") or "{}"
+                        try:
+                            md = _json.loads(md_str)
+                        except Exception:
+                            md = {}
+                        if item.get("tags"):
+                            md.setdefault("tags", item["tags"])
+                        engine.store(item["content"], metadata=md)
+                        mark_done(item["id"])
+                    except Exception as exc:
+                        logger.warning(
+                            "Pending %d failed: %s", item["id"], exc,
+                        )
+                        mark_failed(item["id"], str(exc))
+            except Exception as exc:
+                logger.warning("materializer loop error: %s", exc)
+                time.sleep(5.0)
+
+    _materializer_thread = threading.Thread(
+        target=_loop, daemon=True, name="pending-materializer",
+    )
+    _materializer_thread.start()
+    logger.info("Pending materializer started (recall-priority)")
+
+
 def start_server(port: int = _DEFAULT_PORT) -> None:
     """Start the unified daemon. Blocks until stopped."""
     global _start_time
@@ -1223,6 +1332,9 @@ def start_server(port: int = _DEFAULT_PORT) -> None:
     # v3.4.7: Start memory watchdog to prevent runaway workers
     _start_memory_watchdog()
 
+    # v3.4.32: Continuous pending-queue materializer with recall priority.
+    _start_pending_materializer()
+
     log_dir = Path.home() / ".superlocalmemory" / "logs"
     log_dir.mkdir(parents=True, exist_ok=True)
 

package/src/superlocalmemory/ui/index.html

@@ -53,15 +53,17 @@
                     <div class="stat-bg"></div>
                     <i class="bi bi-journal-text stat-icon text-primary"></i>
                     <h3 class="mt-2 mb-0 stat-value" id="stat-memories">-</h3>
-                    <small class="text-muted">Total Memories</small>
+                    <small class="text-muted">Memories</small>
+                    <small class="text-muted d-block mt-1" id="stat-memories-sub" style="font-size: 0.75rem;">&nbsp;</small>
                 </div>
             </div>
             <div class="col-md-3 col-6 mb-3">
-                <div class="card stat-card stat-card-clusters text-center p-3">
+                <div class="card stat-card stat-card-facts text-center p-3">
                     <div class="stat-bg"></div>
-                    <i class="bi bi-collection stat-icon text-success"></i>
-                    <h3 class="mt-2 mb-0 stat-value" id="stat-clusters">-</h3>
-                    <small class="text-muted">Clusters</small>
+                    <i class="bi bi-diagram-3 stat-icon text-info"></i>
+                    <h3 class="mt-2 mb-0 stat-value" id="stat-facts">-</h3>
+                    <small class="text-muted">Atomic Facts</small>
+                    <small class="text-muted d-block mt-1" id="stat-facts-sub" style="font-size: 0.75rem;">&nbsp;</small>
                 </div>
             </div>
             <div class="col-md-3 col-6 mb-3">
@@ -477,27 +479,34 @@
                     <div id="recall-lab-results"></div>
                 </div>
 
-                <input type="hidden" id="search-query" value="" aria-hidden="true">
-
                 <div class="card p-3 mb-3">
-                    <div class="d-flex justify-content-between align-items-center mb-3">
-                        <h5 class="mb-0"><i class="bi bi-list-ul"></i> Browse all memories</h5>
-                        <div class="dropdown export-dropdown">
-                            <button class="btn btn-sm btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
-                                <i class="bi bi-download"></i> Export
-                            </button>
-                            <ul class="dropdown-menu dropdown-menu-end">
-                                <li><a class="dropdown-item" href="#" onclick="exportAll('json'); return false;">
-                                    <i class="bi bi-filetype-json"></i> Export All (JSON)
-                                </a></li>
-                                <li><a class="dropdown-item" href="#" onclick="exportAll('jsonl'); return false;">
-                                    <i class="bi bi-file-text"></i> Export All (JSONL)
-                                </a></li>
-                                <li><hr class="dropdown-divider"></li>
-                                <li><a class="dropdown-item" href="#" id="export-search-btn" onclick="exportSearchResults(); return false;" style="display:none;">
-                                    <i class="bi bi-funnel"></i> Export Search Results
-                                </a></li>
-                            </ul>
+                    <div class="d-flex justify-content-between align-items-center mb-3 flex-wrap gap-2">
+                        <h5 class="mb-0"><i class="bi bi-list-ul"></i> Browse atomic facts</h5>
+                        <div class="d-flex align-items-center gap-2 flex-wrap">
+                            <div class="input-group input-group-sm" style="width: 280px;">
+                                <span class="input-group-text"><i class="bi bi-search"></i></span>
+                                <input type="search" class="form-control" id="search-query" placeholder="Search memories..." autocomplete="off">
+                            </div>
+                            <div class="dropdown export-dropdown">
+                                <button class="btn btn-sm btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
+                                    <i class="bi bi-download"></i> Export
+                                </button>
+                                <ul class="dropdown-menu dropdown-menu-end">
+                                    <li><a class="dropdown-item" href="#" onclick="exportAll('json'); return false;">
+                                        <i class="bi bi-filetype-json"></i> Export All (JSON)
+                                    </a></li>
+                                    <li><a class="dropdown-item" href="#" onclick="exportAll('jsonl'); return false;">
+                                        <i class="bi bi-file-text"></i> Export All (JSONL)
+                                    </a></li>
+                                    <li><a class="dropdown-item" href="#" onclick="exportAll('csv'); return false;">
+                                        <i class="bi bi-filetype-csv"></i> Export All (CSV)
+                                    </a></li>
+                                    <li><hr class="dropdown-divider"></li>
+                                    <li><a class="dropdown-item" href="#" id="export-search-btn" onclick="exportSearchResults(); return false;" style="display:none;">
+                                        <i class="bi bi-funnel"></i> Export Search Results
+                                    </a></li>
+                                </ul>
+                            </div>
                         </div>
                     </div>
                     <div class="row g-2 mb-3">
@@ -543,6 +552,7 @@
                             <div>Loading memories...</div>
                         </div>
                     </div>
+                    <div id="memories-pagination"></div>
                 </div>
 
                 <div class="card p-3 mt-3">

package/src/superlocalmemory/ui/js/core.js

@@ -274,16 +274,32 @@ async function loadStats() {
         var response = await slmFetch('/api/stats');
         var data = await response.json();
         var ov = data.overview || {};
-        animateCounter('stat-memories', ov.total_memories || 0);
-        animateCounter('stat-clusters', ov.total_clusters || 0);
+        var memories = ov.total_memories || 0;
+        var facts = ov.total_facts || 0;
+        var ratio = ov.facts_per_memory || 0;
+
+        animateCounter('stat-memories', memories);
+        animateCounter('stat-facts', facts);
         animateCounter('stat-nodes', ov.graph_nodes || 0);
         animateCounter('stat-edges', ov.graph_edges || 0);
+
+        var mSub = document.getElementById('stat-memories-sub');
+        if (mSub) {
+            mSub.textContent = memories > 0
+                ? 'what you stored'
+                : '\u00a0';
+        }
+        var fSub = document.getElementById('stat-facts-sub');
+        if (fSub) {
+            fSub.textContent = memories > 0
+                ? 'avg ' + ratio + ' per memory'
+                : '\u00a0';
+        }
         populateFilters(data.categories || [], data.projects || []);
     } catch (error) {
         console.error('Error loading stats:', error);
-        // On error (fresh install, server starting), show 0 instead of "-"
         animateCounter('stat-memories', 0);
-        animateCounter('stat-clusters', 0);
+        animateCounter('stat-facts', 0);
         animateCounter('stat-nodes', 0);
         animateCounter('stat-edges', 0);
     }

package/src/superlocalmemory/ui/js/fact-detail.js

@@ -1,92 +1,81 @@
 // SuperLocalMemory V3 — Fact Detail View
-// Adds click-to-expand on memory list items to show channel scores and trust data.
+// v3.4.31: scoped click listener, real fact_id lookup, no text-based re-query.
+//
+// Scope: only `.fact-result-item` elements (search results view), NEVER
+// fires on the main memories table rows (those use openMemoryDetail via
+// memories.js). This prevents the two listeners from colliding.
 
 document.addEventListener('click', function(e) {
-    var item = e.target.closest('[data-fact-id]');
+    var item = e.target.closest('.fact-result-item[data-fact-id]');
     if (!item) return;
 
-    // Toggle: if detail panel already exists, remove it
+    // Don't interfere if the click was on an action button/link inside the row
+    if (e.target.closest('button, a, [data-bs-toggle]')) return;
+
     var existingDetail = item.querySelector('.fact-detail-panel');
     if (existingDetail) {
         existingDetail.remove();
         return;
     }
 
-    // Extract query text from the item (first 100 chars)
-    var queryText = (item.textContent || '').substring(0, 100).trim();
-    if (!queryText) return;
-
-    fetch('/api/v3/recall/trace', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ query: queryText, limit: 1 })
-    }).then(function(r) {
-        return r.json();
-    }).then(function(data) {
-        var result = (data.results || [])[0];
-        if (!result) return;
-
-        var panel = document.createElement('div');
-        panel.className = 'fact-detail-panel card mt-2 mb-2 border-info';
-
-        var cardBody = document.createElement('div');
-        cardBody.className = 'card-body small';
-
-        // Score / Trust / Confidence row
-        var row1 = document.createElement('div');
-        row1.className = 'row';
+    var factId = item.getAttribute('data-fact-id');
+    if (!factId) return;
 
-        var col1 = document.createElement('div');
-        col1.className = 'col-md-4';
-        var col1Label = document.createElement('strong');
-        col1Label.textContent = 'Score: ';
-        col1.appendChild(col1Label);
-        col1.appendChild(document.createTextNode(result.score || 0));
-        row1.appendChild(col1);
+    fetch('/api/facts/' + encodeURIComponent(factId))
+        .then(function(r) { return r.ok ? r.json() : null; })
+        .then(function(data) {
+            if (!data || !data.fact_id) return;
 
-        var col2 = document.createElement('div');
-        col2.className = 'col-md-4';
-        var col2Label = document.createElement('strong');
-        col2Label.textContent = 'Trust: ';
-        col2.appendChild(col2Label);
-        col2.appendChild(document.createTextNode(result.trust_score || 0));
-        row1.appendChild(col2);
+            var panel = document.createElement('div');
+            panel.className = 'fact-detail-panel card mt-2 mb-2 border-info';
+            var body = document.createElement('div');
+            body.className = 'card-body small';
 
-        var col3 = document.createElement('div');
-        col3.className = 'col-md-4';
-        var col3Label = document.createElement('strong');
-        col3Label.textContent = 'Confidence: ';
-        col3.appendChild(col3Label);
-        col3.appendChild(document.createTextNode(result.confidence || 0));
-        row1.appendChild(col3);
+            var head = document.createElement('div');
+            head.className = 'mb-2';
+            var h = document.createElement('strong');
+            h.textContent = 'Atomic fact';
+            head.appendChild(h);
+            head.appendChild(document.createTextNode(
+                ' · ' + (data.fact_type || '-') +
+                ' · confidence ' + (data.confidence || 0) +
+                ' · importance ' + (data.importance || 0)
+            ));
+            body.appendChild(head);
 
-        cardBody.appendChild(row1);
+            if (data.source_memory_content) {
+                var src = document.createElement('div');
+                src.className = 'text-muted small mt-2';
+                var srcLabel = document.createElement('strong');
+                srcLabel.textContent = 'From memory: ';
+                src.appendChild(srcLabel);
+                var srcText = String(data.source_memory_content);
+                src.appendChild(document.createTextNode(
+                    srcText.length > 200 ? srcText.substring(0, 200) + '...' : srcText
+                ));
+                body.appendChild(src);
+            }
 
-        // Channel scores section
-        var channels = result.channel_scores || {};
-        var channelKeys = Object.keys(channels);
-        if (channelKeys.length > 0) {
-            var label = document.createElement('div');
-            label.className = 'mt-2';
-            var labelStrong = document.createElement('strong');
-            labelStrong.textContent = 'Channel Scores:';
-            label.appendChild(labelStrong);
-            cardBody.appendChild(label);
+            var ids = document.createElement('div');
+            ids.className = 'text-muted mt-2';
+            ids.style.fontSize = '0.75rem';
+            ids.textContent = 'Fact ID: ' + data.fact_id + ' · Memory ID: ' + (data.memory_id || '-');
+            body.appendChild(ids);
 
-            var row2 = document.createElement('div');
-            row2.className = 'row text-muted';
-            channelKeys.forEach(function(chKey) {
-                var chCol = document.createElement('div');
-                chCol.className = 'col-md-3';
-                chCol.textContent = chKey + ': ' + channels[chKey];
-                row2.appendChild(chCol);
-            });
-            cardBody.appendChild(row2);
-        }
+            if (data.entities && data.entities.length > 0) {
+                var ent = document.createElement('div');
+                ent.className = 'mt-2';
+                var entLabel = document.createElement('strong');
+                entLabel.textContent = 'Entities: ';
+                ent.appendChild(entLabel);
+                ent.appendChild(document.createTextNode(data.entities.join(', ')));
+                body.appendChild(ent);
+            }
 
-        panel.appendChild(cardBody);
-        item.appendChild(panel);
-    }).catch(function(e) {
-        console.log('Fact detail error:', e);
-    });
+            panel.appendChild(body);
+            item.appendChild(panel);
+        })
+        .catch(function(err) {
+            console.warn('Fact detail error:', err);
+        });
 });

package/src/superlocalmemory/ui/js/memories.js

@@ -20,10 +20,18 @@ function setMemoryFilter(name) {
     loadMemories();
 }
 
-async function loadMemories() {
+// v3.4.31 pagination state
+var _slmPage = 0;
+var _slmPageSize = 50;
+var _slmLastTotal = 0;
+
+async function loadMemories(page) {
+    if (typeof page === 'number') _slmPage = Math.max(0, page);
     var category = document.getElementById('filter-category').value;
     var project = document.getElementById('filter-project').value;
-    var url = '/api/memories?limit=50';
+    var limit = _slmPageSize;
+    var offset = _slmPage * limit;
+    var url = '/api/memories?limit=' + limit + '&offset=' + offset;
     if (category) url += '&category=' + encodeURIComponent(category);
     if (project) url += '&project_name=' + encodeURIComponent(project);
     if (_slmMemoryFilter) {
@@ -37,13 +45,37 @@ async function loadMemories() {
         lastSearchResults = null;
         var exportBtn = document.getElementById('export-search-btn');
         if (exportBtn) exportBtn.style.display = 'none';
+        _slmLastTotal = data.total || 0;
         renderMemoriesTable(data.memories, false);
+        renderPaginationControls(data);
     } catch (error) {
         console.error('Error loading memories:', error);
         showEmpty('memories-list', 'exclamation-triangle', 'Failed to load memories');
     }
 }
 
+function renderPaginationControls(data) {
+    var el = document.getElementById('memories-pagination');
+    if (!el) return;
+    var total = data.total || 0;
+    var limit = data.limit || _slmPageSize;
+    var offset = data.offset || 0;
+    var showing = Math.min(offset + limit, total);
+    var firstIdx = total === 0 ? 0 : offset + 1;
+    var lastPage = Math.max(0, Math.ceil(total / limit) - 1);
+    var prevDisabled = _slmPage <= 0 ? 'disabled' : '';
+    var nextDisabled = _slmPage >= lastPage ? 'disabled' : '';
+    el.innerHTML =
+        '<div class="d-flex justify-content-between align-items-center mt-3 small">' +
+          '<span class="text-muted">Showing ' + firstIdx + '\u2013' + showing + ' of ' + total + ' memories</span>' +
+          '<div class="btn-group btn-group-sm">' +
+            '<button type="button" class="btn btn-outline-secondary" ' + prevDisabled + ' onclick="loadMemories(' + (_slmPage - 1) + ')"><i class="bi bi-chevron-left"></i> Prev</button>' +
+            '<button type="button" class="btn btn-outline-secondary disabled">Page ' + (_slmPage + 1) + ' / ' + (lastPage + 1) + '</button>' +
+            '<button type="button" class="btn btn-outline-secondary" ' + nextDisabled + ' onclick="loadMemories(' + (_slmPage + 1) + ')">Next <i class="bi bi-chevron-right"></i></button>' +
+          '</div>' +
+        '</div>';
+}
+
 function renderMemoriesTable(memories, showScores) {
     var container = document.getElementById('memories-list');
     if (!memories || memories.length === 0) {

package/src/superlocalmemory/ui/js/modal.js

@@ -40,11 +40,18 @@ function openMemoryDetail(mem, source) {
     var dl = document.createElement('dl');
     dl.className = 'memory-detail-meta row';
 
+    // v3.4.31: disambiguate Fact ID (the atomic unit) from Memory ID (the parent).
+    var factId = mem.fact_id || mem.id || '';
+    var memoryId = mem.memory_id || mem.id || '';
+
     // Left column
     var col1 = document.createElement('div');
     col1.className = 'col-md-6';
-    addDetailRow(col1, 'ID', String(mem.id || '-'));
-    addDetailBadgeRow(col1, 'Category', mem.category || 'None', 'bg-primary');
+    addDetailRow(col1, 'Memory ID', String(memoryId || '-'));
+    if (factId && factId !== memoryId) {
+        addDetailRow(col1, 'Fact ID', String(factId));
+    }
+    addDetailBadgeRow(col1, 'Category', mem.category || mem.fact_type || 'None', 'bg-primary');
     addDetailRow(col1, 'Project', mem.project_name || '-');
     addDetailTagsRow(col1, 'Tags', tags);
     dl.appendChild(col1);
@@ -65,6 +72,38 @@ function openMemoryDetail(mem, source) {
 
     body.appendChild(dl);
 
+    // v3.4.31: hydrate with full memory + fact list from /api/memories/{id}/detail
+    if (memoryId) {
+        fetch('/api/memories/' + encodeURIComponent(memoryId) + '/detail')
+            .then(function(r) { return r.ok ? r.json() : null; })
+            .then(function(data) {
+                if (!data || !data.memory) return;
+                var hydration = document.getElementById('memory-detail-hydration');
+                if (hydration) hydration.remove();
+                var block = document.createElement('div');
+                block.id = 'memory-detail-hydration';
+                block.className = 'mt-3';
+                var h = document.createElement('h6');
+                h.innerHTML = '<i class="bi bi-diagram-3"></i> Atomic facts extracted from this memory (' + (data.fact_count || 0) + ')';
+                block.appendChild(h);
+                var list = document.createElement('div');
+                list.className = 'list-group list-group-flush';
+                (data.facts || []).forEach(function(f) {
+                    var row = document.createElement('div');
+                    row.className = 'list-group-item list-group-item-action small fact-result-item';
+                    row.setAttribute('data-fact-id', f.fact_id);
+                    row.style.cursor = 'pointer';
+                    var badge = '<span class="badge bg-secondary me-2">' + (f.fact_type || '-') + '</span>';
+                    var confText = ' · confidence ' + (f.confidence || 0).toFixed(2);
+                    row.innerHTML = badge + escapeHtml(String(f.content || '')) + '<small class="text-muted">' + escapeHtml(confText) + '</small>';
+                    list.appendChild(row);
+                });
+                block.appendChild(list);
+                body.appendChild(block);
+            })
+            .catch(function(err) { console.warn('Hydration error:', err); });
+    }
+
     // Context-aware action buttons
     if (mem.id) {
         body.appendChild(document.createElement('hr'));

package/src/superlocalmemory/ui/js/search.js

@@ -41,9 +41,36 @@ function exportAll(format) {
     var project = document.getElementById('filter-project').value;
     if (category) url += '&category=' + encodeURIComponent(category);
     if (project) url += '&project_name=' + encodeURIComponent(project);
+    if (typeof showToast === 'function') {
+        showToast('Preparing ' + format.toUpperCase() + ' export...');
+    }
     window.location.href = url;
 }
 
+(function wireSearchInput() {
+    function init() {
+        var el = document.getElementById('search-query');
+        if (!el || el._slmWired) return;
+        el._slmWired = true;
+        var timer = null;
+        el.addEventListener('input', function() {
+            clearTimeout(timer);
+            timer = setTimeout(searchMemories, 280);
+        });
+        el.addEventListener('keydown', function(e) {
+            if (e.key === 'Enter') {
+                clearTimeout(timer);
+                searchMemories();
+            }
+        });
+    }
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', init);
+    } else {
+        init();
+    }
+})();
+
 function exportSearchResults() {
     if (!lastSearchResults || lastSearchResults.length === 0) {
         showToast('No search results to export');