superlocalmemory 4.2.2__tar.gz → 4.2.4__tar.gz

{superlocalmemory-4.2.2/src/superlocalmemory.egg-info → superlocalmemory-4.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 4.2.2
+Version: 4.2.4
 Summary: The governed memory brain for AI agents: one local memory for Claude Code, Codex, Cursor, Copilot, ChatGPT and any MCP client
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License-Expression: AGPL-3.0-or-later
@@ -148,9 +148,7 @@ In Mode A, core remember and recall make no model-provider call: no API key, no
 
 ## Install
 
-Three ways in. All three end in the same setup: your text memory on this machine, and, if you say yes, your pictures and documents too.
-
-**1. Ask your agent.** Copy this into Claude Code, Codex, Cursor or any agent that can run commands:
+> **The easiest way: let your AI agent install it.** Copy the block below into Claude Code, Codex, Cursor or any agent that can run commands. It reads the setup guide, asks you one question, sets everything up and tells you what works. No terminal commands for you to learn.
 
 ```
 Install SuperLocalMemory on this computer for me. Follow
@@ -161,7 +159,17 @@ screenshots and PDFs by describing them. Connect SuperLocalMemory to the agent
 I am using. When you finish, run slm doctor and tell me in plain words what works.
 ```
 
-**2. npm**, the primary route (Node 18+). It installs SLM into a package-owned virtual environment:
+**No AI agent? One line in Terminal** (macOS and Linux). It brings its own Python, sets everything up, connects the AI tools it finds and opens the dashboard; no Python or npm needed beforehand:
+
+```bash
+curl -fsSLo get-slm.sh https://raw.githubusercontent.com/qualixar/superlocalmemory/main/scripts/get-slm.sh && sh get-slm.sh
+```
+
+Add pictures and documents from the start with `sh get-slm.sh --media` at the end. It downloads the script first, so you can read it before it runs. Windows: use the agent prompt above, or npm or pip below.
+
+**Prefer the terminal?** Both routes end in the same setup: your text memory on this machine, and, if you say yes, your pictures and documents too.
+
+**npm**, the primary route (Node 18+). It installs SLM into a package-owned virtual environment:
 
 ```bash
 npm install -g superlocalmemory   # add --media to also turn on pictures and documents
@@ -169,7 +177,7 @@ slm setup                         # pick Mode A to keep everything on this machi
 slm connect claude-code           # or codex, cursor, windsurf, zed, claude-desktop, jetbrains, opencode ...
 ```
 
-**3. pip**, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:
+**pip**, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:
 
 ```bash
 python3 -m venv .venv

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/README.md

@@ -32,9 +32,7 @@ In Mode A, core remember and recall make no model-provider call: no API key, no
 
 ## Install
 
-Three ways in. All three end in the same setup: your text memory on this machine, and, if you say yes, your pictures and documents too.
-
-**1. Ask your agent.** Copy this into Claude Code, Codex, Cursor or any agent that can run commands:
+> **The easiest way: let your AI agent install it.** Copy the block below into Claude Code, Codex, Cursor or any agent that can run commands. It reads the setup guide, asks you one question, sets everything up and tells you what works. No terminal commands for you to learn.
 
 ```
 Install SuperLocalMemory on this computer for me. Follow
@@ -45,7 +43,17 @@ screenshots and PDFs by describing them. Connect SuperLocalMemory to the agent
 I am using. When you finish, run slm doctor and tell me in plain words what works.
 ```
 
-**2. npm**, the primary route (Node 18+). It installs SLM into a package-owned virtual environment:
+**No AI agent? One line in Terminal** (macOS and Linux). It brings its own Python, sets everything up, connects the AI tools it finds and opens the dashboard; no Python or npm needed beforehand:
+
+```bash
+curl -fsSLo get-slm.sh https://raw.githubusercontent.com/qualixar/superlocalmemory/main/scripts/get-slm.sh && sh get-slm.sh
+```
+
+Add pictures and documents from the start with `sh get-slm.sh --media` at the end. It downloads the script first, so you can read it before it runs. Windows: use the agent prompt above, or npm or pip below.
+
+**Prefer the terminal?** Both routes end in the same setup: your text memory on this machine, and, if you say yes, your pictures and documents too.
+
+**npm**, the primary route (Node 18+). It installs SLM into a package-owned virtual environment:
 
 ```bash
 npm install -g superlocalmemory   # add --media to also turn on pictures and documents
@@ -53,7 +61,7 @@ slm setup                         # pick Mode A to keep everything on this machi
 slm connect claude-code           # or codex, cursor, windsurf, zed, claude-desktop, jetbrains, opencode ...
 ```
 
-**3. pip**, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:
+**pip**, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:
 
 ```bash
 python3 -m venv .venv

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/agents/slm-governance-advisor.md

@@ -81,4 +81,4 @@ slm-scope · slm-governance · slm-profile · slm-remember · slm-recall · slm-
 # What NOT to do
 Never session_init twice; never forget without dry-run preview; never run `slm gdpr erase --yes` unasked; never store secrets; never bypass role checks; never claim an erasure succeeded without verifying via recall.
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/agents/slm-loop-runner.md

@@ -79,4 +79,4 @@ assessment. The gate is the authority.
 
 ---
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/agents/slm-memory-advisor.md

@@ -51,4 +51,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never switch the active profile unasked; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never hand a ccr_id to another agent.
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/rules/AGENTS.md

@@ -187,4 +187,4 @@ Using this memory from a web assistant or another computer: see the slm-web-acce
 - **slm-governance-advisor** — scope/role compliance, retention and lifecycle, GDPR
 - **slm-loop-runner** — bounded, gate-verified loops (the `/slm-loop` command delegates to it)
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/rules/CLAUDE.md.fragment

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v4.2.2 -->
+<!-- BEGIN SuperLocalMemory v4.2.4 -->
 
 ## SuperLocalMemory (SLM) — Agent Rules
 
@@ -51,6 +51,6 @@ slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-comp
 ### Subagents
 slm-memory-advisor (memory decisions, session hygiene, scope/profile guidance) · slm-optimize-advisor (context compression + KV cache) · slm-governance-advisor (scope/roles/compliance/GDPR) · slm-loop-runner (bounded, gate-verified loops)
 
-<!-- END SuperLocalMemory v4.2.2 -->
+<!-- END SuperLocalMemory v4.2.4 -->
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-bot-memory/SKILL.md

@@ -178,4 +178,4 @@ store every local bot on that computer can reach.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-cache/SKILL.md

@@ -144,4 +144,4 @@ These subcommands control daemon-level cache settings and bulk removal. They do
 
 ---
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-compress/SKILL.md

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-getting-started-bot/SKILL.md

@@ -194,4 +194,4 @@ quality on a shared box.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-governance/SKILL.md

@@ -274,4 +274,4 @@ Before running any destructive or state-changing operation (`forget`,
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-graph/SKILL.md

@@ -324,4 +324,4 @@ All are host-only: a remote caller cannot use them.
 
 ---
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: slm-loop
-description: Gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition and you must iterate until an INDEPENDENT gate passes — never stopping because the agent believes it is done. `slm_loop_run` (MCP) waits, under hard bounds, for a recall gate to pass; `slm loop demo` shows the control flow keyless; `slm loop history` and `slm loop show <run_id>` (or `slm_loop_history` / `slm_loop_show`) inspect past runs, whose every lap is stored as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
+description: Gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition and you must iterate until an INDEPENDENT gate passes — never stopping because the agent believes it is done. `slm_loop_run` (MCP) waits, under hard bounds, for an independently executed check registered by the operator to pass; `slm loop demo` shows the control flow keyless; `slm loop history` and `slm loop show <run_id>` (or `slm_loop_history` / `slm_loop_show`) inspect past runs, whose every lap is stored as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
 when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, wait for another agent's result"
 allowed-tools: slm_loop_run, slm_loop_history, slm_loop_show, recall, report_outcome, get_soft_prompts, skill_health, skill_lineage, evolve_skill, observe_bounded_loop_evidence, Bash
 ---
@@ -26,7 +26,7 @@ subprocess or sandbox machinery. What each surface gives you:
 
 | Surface | What it does |
 |---|---|
-| `slm_loop_run` (MCP) | A *watcher*: each lap is a recall of `gate_query`; the loop ends when a confident match appears, or a bound trips. Use it to wait for a verification or coordination memory another agent will write (for example "build passed"). |
+| `slm_loop_run` (MCP) | A *watcher* for a registered check. DONE needs `gate_contract={"job_id": ...}`: a job the operator registered with `superlocalmemory.loops.receipt_jobs.register_job` and executed with `run_registered_check`. Each lap's recall of `gate_query` only locates context; a matching memory alone never passes. Without a registered job the run ends HALT ("operator-registered job_id required"), which is the correct, honest outcome. |
 | `slm loop demo` (CLI) | A keyless convergence demo: a stub proposer, a deterministic gate that passes on lap 3, every lap recorded. Proves the engine and ledger work end to end. |
 | `slm loop history`, `slm loop show` / `slm_loop_history`, `slm_loop_show` | Read the ledger of past runs. |
 | `superlocalmemory.loops.run_bounded_loop` (Python) | The engine itself, for code that supplies its own runner and gate callables. |
@@ -62,6 +62,7 @@ slm_loop_run(
   max_tokens: int = 0,          # optional token budget; 0 disables
   no_progress_window: int = 0,  # halt after N no-change laps; leave 0 for a watcher
   require_support: bool = False,# pass only if the answer check ran and judged it sufficient
+  gate_contract: dict | None = None,  # {"job_id": <operator registration>}; required for DONE
 )
 ```
 
@@ -170,4 +171,4 @@ Guides: `docs/skill-evolution.md`, `docs/bounded-loops-bridge.md`.
 
 ---
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-media/SKILL.md

@@ -337,4 +337,4 @@ minutes (previous vectors are kept) and let them decide.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-mesh/SKILL.md

@@ -386,4 +386,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-profile/SKILL.md

@@ -161,4 +161,4 @@ anything but `core` or `mesh`.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-recall/SKILL.md

@@ -515,4 +515,4 @@ See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-remember/SKILL.md

@@ -372,4 +372,4 @@ sessions on this machine, so use it only when the user asks to move. See
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-scope/SKILL.md

@@ -180,4 +180,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-session/SKILL.md

@@ -288,4 +288,4 @@ answered. To also surface shared or global facts, call `recall` with
 
 ---
 
-*SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/plugin-src/skills/slm-status/SKILL.md

@@ -228,4 +228,4 @@ the memory-engine upgrade is pending.
 
 ---
 
-SuperLocalMemory v4.2.2 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.4 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "4.2.2"
+version = "4.2.4"
 description = "The governed memory brain for AI agents: one local memory for Claude Code, Codex, Cursor, Copilot, ChatGPT and any MCP client"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/src/superlocalmemory/__init__.py

@@ -32,7 +32,7 @@ if "OMP_NUM_THREADS" not in os.environ:
     os.environ["OMP_NUM_THREADS"] = "2"
 # ---------------------------------------------------------------------------
 
-__version__ = "4.2.2"
+__version__ = "4.2.4"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.6.1",

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/src/superlocalmemory/core/maintenance_scheduler.py

@@ -35,9 +35,12 @@ logger = logging.getLogger(__name__)
 # store creates a version and nothing used to remove them: a 5,561-memory
 # store reached 50,580 versions in 17 GB, and each vector operation then had
 # to walk that history -- the daemon in GitHub #137 held a core at 90%+ with
-# an empty queue. A week is enough to debug a bad projection and short enough
-# that the history cannot run away.
-_VECTOR_HISTORY_DAYS = float(os.environ.get("SLM_VECTOR_HISTORY_DAYS", "7"))
+# an empty queue. 4.2.4: an hour, not a week. A week still held one version
+# per memory saved that week: 7,194 versions in 5,401 files (4.1 GB for 27k
+# vectors) on a busy store after a model switch, and semantic search took
+# 2.2 s instead of 50 ms. An hour is past any in-flight read; the GDPR erase
+# path already cleans with no retention at all.
+_VECTOR_HISTORY_DAYS = float(os.environ.get("SLM_VECTOR_HISTORY_DAYS", str(1 / 24)))
 
 
 _NOT_APPLICABLE_REPORTED: set[str] = set()

superlocalmemory-4.2.4/src/superlocalmemory/encoding/entity_lookup_index.py

@@ -0,0 +1,217 @@
+# 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
+
+"""Recall's read-only entity name lookup, without scanning the tables each time.
+
+``EntityResolver.lookup`` (recall only; never saving) found each name in a
+question by an exact match, then an alias, then the closest spelling, and each
+step scanned a whole table: ``LOWER(canonical_name) = LOWER(?)`` has no index,
+and the spelling match read every name and alias and scored them all. On a
+22k-fact store that was 46 ms of a recall, every recall.
+
+This keeps those rows in memory per profile while nothing has been committed
+to the store (storage/store_signature) and answers the same way:
+
+* exact name and alias keys are lowered the way SQLite's ``LOWER`` does (ASCII
+  only), so a name matches here exactly when it matched there;
+* a key held by more than one entity is answered by the original query, so
+  which row wins never depends on a query plan;
+* the spelling match applies a save's merge rules (``entity_match``) to the
+  canonical names only (``entity_name_cache``); its answer per name is kept
+  while the rows are.
+
+Aliases written by the pre-4.1.25 whole-string fuzzy merge are not loaded:
+they may be links of a chain ("Plorth" -> "Plot" -> "Lost").
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from superlocalmemory.encoding import entity_match as em
+from superlocalmemory.storage import store_signature
+
+_ASCII_LOWER = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+
+#: The original queries the spelling match ran; their row order is reused.
+_NAMES_SQL = ("SELECT entity_id, canonical_name, entity_type FROM canonical_entities "
+              "WHERE profile_id = ?")
+_ALIASES_SQL = ("SELECT ea.entity_id, ea.alias, ea.source, ce.canonical_name "
+                "FROM entity_aliases ea "
+                "JOIN canonical_entities ce ON ce.entity_id = ea.entity_id "
+                "WHERE ce.profile_id = ?")
+
+AMBIGUOUS = object()
+
+
+def sql_lower(text: str) -> str:
+    """SQLite's built-in LOWER(): ASCII letters only."""
+    return text.translate(_ASCII_LOWER)
+
+
+def _keyed(rows: list[tuple[str, str]]) -> dict[str, object]:
+    out: dict[str, object] = {}
+    for entity_id, text in rows:
+        key = sql_lower(text)
+        prev = out.get(key)
+        if prev is None:
+            out[key] = entity_id
+        elif prev is not AMBIGUOUS and prev != entity_id:
+            out[key] = AMBIGUOUS
+    return out
+
+
+@dataclass
+class _Index:
+    names: list[tuple[str, str]]
+    aliases: list[tuple[str, str]]
+    by_name: dict[str, object]
+    by_alias: dict[str, object]
+    types: dict[str, str] = field(default_factory=dict)
+    same: dict[str, str | None] = field(default_factory=dict)
+    name_of: dict[str, str] | None = None
+
+
+#: The entity rows this index reads: a profile's names, and every alias (an
+#: alias row's own profile can differ from its entity's). A save that adds or
+#: removes one moves its count or highest rowid; touching last_seen or
+#: fact_count, which every save does, moves neither (4.2.4).
+_NAMES_STAMP_SQL = ("SELECT COUNT(*) AS n, COALESCE(MAX(rowid), 0) AS r "
+                    "FROM canonical_entities WHERE profile_id = ?")
+_ALIASES_STAMP_SQL = "SELECT COUNT(*) AS n, COALESCE(MAX(rowid), 0) AS r FROM entity_aliases"
+_NEW_NAMES_SQL = ("SELECT rowid AS rid, entity_id, canonical_name, entity_type "
+                  "FROM canonical_entities WHERE profile_id = ? AND rowid > ? ORDER BY rowid")
+_NEW_ALIASES_SQL = ("SELECT ea.rowid AS rid, ea.entity_id, ea.alias, ea.source, ce.canonical_name "
+                    "FROM entity_aliases ea "
+                    "JOIN canonical_entities ce ON ce.entity_id = ea.entity_id "
+                    "WHERE ce.profile_id = ? AND ea.rowid > ? ORDER BY ea.rowid")
+#: An in-place rename or alias repair moves no count. Maintenance that does one
+#: calls ``invalidate()``; this bounds anything else (another process) too.
+MAX_AGE_S = 600.0
+
+_generation = 0
+_generation_lock = threading.Lock()
+
+
+def invalidate() -> None:
+    """Entity names or aliases were changed in place: rebuild on next use."""
+    global _generation
+    with _generation_lock:
+        _generation += 1
+
+
+def _stamp(db: Any, profile_id: str) -> tuple[int, int, int, int]:
+    names = dict(db.execute(_NAMES_STAMP_SQL, (profile_id,))[0])
+    aliases = dict(db.execute(_ALIASES_STAMP_SQL)[0])
+    return (int(names["n"] or 0), int(names["r"] or 0),
+            int(aliases["n"] or 0), int(aliases["r"] or 0))
+
+
+def _add_keyed(keyed: dict[str, object], rows: list[tuple[str, str]]) -> None:
+    for entity_id, text in rows:
+        key = sql_lower(text)
+        prev = keyed.get(key)
+        if prev is None:
+            keyed[key] = entity_id
+        elif prev is not AMBIGUOUS and prev != entity_id:
+            keyed[key] = AMBIGUOUS
+
+
+class EntityLookupIndex:
+    """Per-profile name rows, kept while the entity rows they come from are.
+
+    Keyed on the entity tables (``_stamp``), not on the whole store: before
+    4.2.4 any commit -- a hook's note, an access count -- dropped it, so on a
+    busy store it was rebuilt on nearly every recall (16,800 names re-keyed,
+    ~0.35 s). Rows only added since are folded in; anything else rebuilds.
+    """
+
+    def __init__(self, db: Any, *, clock=time.monotonic) -> None:
+        self._db = db
+        self._clock = clock
+        self._lock = threading.Lock()
+        # profile -> (stamp, generation, built_at, index)
+        self._parts: dict[str, tuple[tuple, int, float, _Index]] = {}
+
+    def get(self, profile_id: str) -> _Index | None:
+        if store_signature.of_db(self._db) is None:  # inside a write: never reuse
+            return None
+        stamp = _stamp(self._db, profile_id)
+        now = self._clock()
+        with self._lock:
+            hit = self._parts.get(profile_id)
+        if hit is not None and hit[1] == _generation and now - hit[2] < MAX_AGE_S:
+            if hit[0] == stamp:
+                return hit[3]
+            grown = self._extend(profile_id, hit[0], stamp, hit[3])
+            if grown is not None:
+                self._keep(profile_id, (stamp, hit[1], hit[2], grown))
+                return grown
+        generation = _generation
+        index = self._build(profile_id)
+        self._keep(profile_id, (stamp, generation, now, index))
+        return index
+
+    def _keep(self, profile_id: str, entry: tuple) -> None:
+        with self._lock:
+            self._parts[profile_id] = entry
+            while len(self._parts) > 8:  # a few profiles at most
+                self._parts.pop(next(iter(self._parts)))
+
+    def _build(self, profile_id: str) -> _Index:
+        rows = [dict(r) for r in self._db.execute(_NAMES_SQL, (profile_id,))]
+        names = [(str(r["entity_id"]), str(r["canonical_name"] or "")) for r in rows]
+        types = {str(r["entity_id"]): str(r["entity_type"] or "") for r in rows}
+        aliases = [(str(r["entity_id"]), str(r["alias"] or ""))
+                   for r in map(dict, self._db.execute(_ALIASES_SQL, (profile_id,)))
+                   if em.alias_in_use(r["source"], r["alias"], r["canonical_name"])]
+        return _Index(names, aliases, _keyed(names), _keyed(aliases), types)
+
+    def _extend(self, profile_id: str, old: tuple, new: tuple, index: _Index) -> _Index | None:
+        """The index plus rows added since ``old``; None when any were removed."""
+        n0, r0, a0, ar0 = old
+        n1, r1, a1, ar1 = new
+        if n1 < n0 or r1 < r0 or a1 < a0 or ar1 < ar0:
+            return None
+        name_rows = [dict(r) for r in self._db.execute(_NEW_NAMES_SQL, (profile_id, r0))]
+        alias_rows = [dict(r) for r in self._db.execute(_NEW_ALIASES_SQL, (profile_id, ar0))]
+        if len(name_rows) != n1 - n0:
+            return None  # a removal hidden by an addition: rebuild
+        if a1 - a0 < len(alias_rows):
+            return None
+        names = [(str(r["entity_id"]), str(r["canonical_name"] or "")) for r in name_rows]
+        aliases = [(str(r["entity_id"]), str(r["alias"] or "")) for r in alias_rows
+                   if em.alias_in_use(r["source"], r["alias"], r["canonical_name"])]
+        by_name, by_alias = dict(index.by_name), dict(index.by_alias)
+        _add_keyed(by_name, names)
+        _add_keyed(by_alias, aliases)
+        types = dict(index.types)
+        types.update({str(r["entity_id"]): str(r["entity_type"] or "") for r in name_rows})
+        # A new name can be what an earlier unmatched spelling meant: forget those.
+        return _Index(index.names + names, index.aliases + aliases, by_name, by_alias, types)
+
+
+def plain_word_hit(index: _Index, word: str) -> str | None:
+    """The entity a lower-case question word spells exactly (as SQLite's
+    LOWER does), when such a word may name it at all
+    (``entity_match.plain_word_may_name``). An ambiguous spelling answers none.
+    """
+    key = sql_lower(word)
+    hit = index.by_name.get(key)
+    if hit is None:
+        hit = index.by_alias.get(key)
+    if hit is None or hit is AMBIGUOUS:
+        return None
+    if index.name_of is None:
+        index.name_of = dict(index.names)
+    entity_id = str(hit)
+    canonical = index.name_of.get(entity_id, "")
+    ok = em.plain_word_may_name(word, canonical, index.types.get(entity_id, ""))
+    return entity_id if ok else None
+
+
+__all__ = ["AMBIGUOUS", "EntityLookupIndex", "invalidate", "plain_word_hit", "sql_lower"]

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/src/superlocalmemory/encoding/entity_name_cache.py

@@ -24,6 +24,8 @@ _STAMP_SQL = ("SELECT COUNT(*) AS n, COALESCE(MAX(rowid), 0) AS r "
               "FROM canonical_entities WHERE profile_id = ?")
 _NAMES_SQL = ("SELECT entity_id, canonical_name FROM canonical_entities "
               "WHERE profile_id = ? ORDER BY rowid")
+_ADDED_SQL = ("SELECT entity_id, canonical_name FROM canonical_entities "
+              "WHERE profile_id = ? AND rowid > ? ORDER BY rowid")
 
 
 class CanonicalNames:
@@ -43,8 +45,10 @@ class CanonicalNames:
         stamp = self._stamp(profile_id)
         with self._lock:
             kept = self._kept.get(profile_id)
-            if kept is not None and kept[0] == stamp:
-                return kept[1]
+        if kept is not None and kept[0] == stamp:
+            return kept[1]
+        if kept is not None and self._grow(profile_id, kept, stamp):
+            return kept[1]
         names = em.NameIndex([(str(dict(r)["entity_id"]), str(dict(r)["canonical_name"] or ""))
                               for r in self._db.execute(_NAMES_SQL, (profile_id,))])
         with self._lock:
@@ -53,6 +57,26 @@ class CanonicalNames:
                 self._kept.pop(next(iter(self._kept)))
         return names
 
+    def _grow(self, profile_id: str, kept, stamp: tuple[int, int]) -> bool:
+        """Fold in names only added since ``kept`` (4.2.4).
+
+        A save that created one entity made the next recall rebuild all of a
+        profile's names: 2.7-5.4 s on a 16,800-entity store. Added rows are
+        read by rowid; a removal (count lower than the rows added) rebuilds.
+        """
+        (n0, r0), names = kept
+        n1, r1 = stamp
+        if n1 < n0 or r1 < r0:
+            return False
+        added = [dict(r) for r in self._db.execute(_ADDED_SQL, (profile_id, r0))]
+        if len(added) != n1 - n0:
+            return False
+        for row in added:
+            names.add(str(row["entity_id"]), str(row["canonical_name"] or ""))
+        with self._lock:
+            self._kept[profile_id] = (stamp, names)
+        return True
+
     def added(self, profile_id: str, entity_id: str, name: str) -> None:
         """This process created an entity: keep the copy current."""
         with self._lock:

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/src/superlocalmemory/mcp/profiles.py

@@ -119,9 +119,9 @@ _PROFILE_FULL: frozenset[str] = frozenset({
     # and a view is a convenience over recall, which core already has.
     "run_view", "manage_view",
     # prestage_context remains registered but deliberately raw-server-only.
-}) | _PROFILE_FULL_MESH | _PROFILE_KINDS | _media_tools_if_enabled()  # 57 (+5 while images are on)
+}) | _PROFILE_FULL_MESH | _PROFILE_KINDS | _media_tools_if_enabled()  # 58 (+5 while images are on)
 
-_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 69
+_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 70 (+5 while images are on)
     "get_version", "get_mode", "health", "consistency_check", "recall_trace",
     "get_lifecycle_status", "set_retention_policy", "compact_memories",
     "get_behavioral_patterns", "audit_trail", "quantize", "get_retention_stats",

{superlocalmemory-4.2.2 → superlocalmemory-4.2.4}/src/superlocalmemory/mcp/server.py

@@ -466,7 +466,23 @@ def _prestage_recall(query: str, limit: int, profile_id: str, as_of: str | None
         target or getattr(engine, "profile_id", "default"),
     )
     if ctx is None:
-        return _memories_from(engine.recall(query, **kwargs))
+        from superlocalmemory.core.engine_capabilities import CapabilityError
+
+        try:
+            return _memories_from(engine.recall(query, **kwargs))
+        except CapabilityError:
+            # 4.2.3: an MCP stdio process holds a light engine that may not
+            # recall in-process, so every prestage_context said recall_error.
+            # Recall through the worker pool, as session_init does. A
+            # point-in-time view is not forwarded there: refuse, never serve now.
+            if as_of is not None:
+                raise
+            from superlocalmemory.core.answer_check_scope import context_load
+            from superlocalmemory.mcp._pool_adapter import pool_recall
+
+            with context_load():
+                return _memories_from(pool_recall(
+                    query, limit=limit, **({"profile_id": target} if target else {})))
     with visibility.use(ctx):
         return _memories_from(engine.recall(query, **kwargs))