superlocalmemory 4.2.1__tar.gz → 4.2.3__tar.gz

{superlocalmemory-4.2.1/src/superlocalmemory.egg-info → superlocalmemory-4.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 4.2.1
+Version: 4.2.3
 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,18 +148,51 @@ In Mode A, core remember and recall make no model-provider call: no API key, no
 
 ## Install
 
-> **AI agents: installing a memory system for your user?** Follow [SETUP_FOR_AGENTS.md](https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md) — numbered, non-interactive steps with the expected output of each: install, `slm init --auto`, `slm serve start`, `slm warmup`, connect the host, then call `session_init` at the start of every session and `remember` / `recall` as you work.
+> **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
+https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md
+step by step and show me what each step printed. Ask me only one question,
+before turning on anything optional: whether I also want to find my pictures,
+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.
+```
+
+**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   # primary route; or: pipx install superlocalmemory   (Python 3.12+, Node 18+ for npm)
+npm install -g superlocalmemory   # add --media to also turn on pictures and documents
 slm setup                         # pick Mode A to keep everything on this machine
-slm connect cursor                # or codex, windsurf, zed, claude-desktop, jetbrains, opencode ...
+slm connect claude-code           # or codex, cursor, windsurf, zed, claude-desktop, jetbrains, opencode ...
 ```
 
-**Claude Code:** `claude plugin marketplace add qualixar/superlocalmemory`, then `claude plugin install superlocalmemory@qualixar`.
+**pip**, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate         # Windows: .venv\Scripts\activate
+python -m pip install superlocalmemory   # or, without a venv: pipx install superlocalmemory
+slm setup
+slm connect claude-code
+slm media enable                  # optional: pictures and documents (about 1.5 GB; needs 16 GB of memory)
+```
+
+**Claude Code plugin:** `claude plugin marketplace add qualixar/superlocalmemory`, then `claude plugin install superlocalmemory@qualixar`. **Codex:** `slm connect codex`, then `slm codex install`.
+
+**Two models, one memory.** Text is searched with a small local text model (nomic). If you turn on pictures and documents, a second local model (Google's EmbeddingGemma 2) reads them, and one recall returns both. The picture model unloads after 30 minutes without use, so it holds no memory while you only work with text. Details: [pictures and documents](https://github.com/qualixar/superlocalmemory/blob/main/docs/pictures-and-documents.md), [getting started](https://github.com/qualixar/superlocalmemory/blob/main/docs/getting-started.md), [agent setup steps](https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md).
 
-npm is the primary route: it installs SLM into a package-owned virtual environment (pipx does the same). The other primary route is pip in a Python virtual environment you activate: `python3 -m venv .venv`, activate it, then `python -m pip install superlocalmemory`. Repository clone: `./scripts/install.sh install` (macOS, Linux) or `.\scripts\install.ps1 -Action Install` (Windows). Runs on Windows, Linux and Apple Silicon macOS ([platforms](#platform-support)).
+Repository clone: `./scripts/install.sh install` (macOS, Linux) or `.\scripts\install.ps1 -Action Install` (Windows). Runs on Windows, Linux and Apple Silicon macOS ([platforms](#platform-support)).
 
 ## 30-second example
 

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/README.md

@@ -32,18 +32,51 @@ In Mode A, core remember and recall make no model-provider call: no API key, no
 
 ## Install
 
-> **AI agents: installing a memory system for your user?** Follow [SETUP_FOR_AGENTS.md](https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md) — numbered, non-interactive steps with the expected output of each: install, `slm init --auto`, `slm serve start`, `slm warmup`, connect the host, then call `session_init` at the start of every session and `remember` / `recall` as you work.
+> **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
+https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md
+step by step and show me what each step printed. Ask me only one question,
+before turning on anything optional: whether I also want to find my pictures,
+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.
+```
+
+**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   # primary route; or: pipx install superlocalmemory   (Python 3.12+, Node 18+ for npm)
+npm install -g superlocalmemory   # add --media to also turn on pictures and documents
 slm setup                         # pick Mode A to keep everything on this machine
-slm connect cursor                # or codex, windsurf, zed, claude-desktop, jetbrains, opencode ...
+slm connect claude-code           # or codex, cursor, windsurf, zed, claude-desktop, jetbrains, opencode ...
 ```
 
-**Claude Code:** `claude plugin marketplace add qualixar/superlocalmemory`, then `claude plugin install superlocalmemory@qualixar`.
+**pip**, the other primary route (Python 3.12 to 3.14), in a Python virtual environment you activate:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate         # Windows: .venv\Scripts\activate
+python -m pip install superlocalmemory   # or, without a venv: pipx install superlocalmemory
+slm setup
+slm connect claude-code
+slm media enable                  # optional: pictures and documents (about 1.5 GB; needs 16 GB of memory)
+```
+
+**Claude Code plugin:** `claude plugin marketplace add qualixar/superlocalmemory`, then `claude plugin install superlocalmemory@qualixar`. **Codex:** `slm connect codex`, then `slm codex install`.
+
+**Two models, one memory.** Text is searched with a small local text model (nomic). If you turn on pictures and documents, a second local model (Google's EmbeddingGemma 2) reads them, and one recall returns both. The picture model unloads after 30 minutes without use, so it holds no memory while you only work with text. Details: [pictures and documents](https://github.com/qualixar/superlocalmemory/blob/main/docs/pictures-and-documents.md), [getting started](https://github.com/qualixar/superlocalmemory/blob/main/docs/getting-started.md), [agent setup steps](https://github.com/qualixar/superlocalmemory/blob/main/SETUP_FOR_AGENTS.md).
 
-npm is the primary route: it installs SLM into a package-owned virtual environment (pipx does the same). The other primary route is pip in a Python virtual environment you activate: `python3 -m venv .venv`, activate it, then `python -m pip install superlocalmemory`. Repository clone: `./scripts/install.sh install` (macOS, Linux) or `.\scripts\install.ps1 -Action Install` (Windows). Runs on Windows, Linux and Apple Silicon macOS ([platforms](#platform-support)).
+Repository clone: `./scripts/install.sh install` (macOS, Linux) or `.\scripts\install.ps1 -Action Install` (Windows). Runs on Windows, Linux and Apple Silicon macOS ([platforms](#platform-support)).
 
 ## 30-second example
 

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/agents/slm-loop-runner.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/rules/CLAUDE.md.fragment

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v4.2.1 -->
+<!-- BEGIN SuperLocalMemory v4.2.3 -->
 
 ## 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.1 -->
+<!-- END SuperLocalMemory v4.2.3 -->
 
-SuperLocalMemory v4.2.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-bot-memory/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

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

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-governance/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-graph/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-media/SKILL.md

@@ -315,8 +315,14 @@ Settings) re-reads existing memories with the same on-device model that reads
 pictures, so text and pictures share one search space. It runs in the
 background, recall keeps working, the previous engine's data stays until the
 owner frees it (`slm embedder forget-previous`), and `slm embedder rollback`
-goes back. It is opt-in and never starts on its own. If it cannot run, the
-command prints the reason. Offer it; do not run it unasked.
+goes back. If it cannot run, the command prints the reason.
+
+It is not available for text yet: recall's answer check is not calibrated for
+EmbeddingGemma 2 (the best fit so far answered questions that have no answer),
+so the command refuses with that reason. Do not offer it, and never pass `--force` for the user.
+If `slm doctor` reports "Answer check fit" as a warning, the user's text already
+moved in an earlier version: tell them `slm embedder rollback` goes back in
+minutes (previous vectors are kept) and let them decide.
 
 ---
 
@@ -331,4 +337,4 @@ command prints the reason. Offer it; do not run it unasked.
 
 ---
 
-*SuperLocalMemory v4.2.1 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-mesh/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-profile/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-recall/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/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.1 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.3 · Qualixar · AGPL-3.0-or-later*

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/plugin-src/skills/slm-status/SKILL.md

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

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "4.2.1"
+version = "4.2.3"
 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.1 → superlocalmemory-4.2.3}/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.1"
+__version__ = "4.2.3"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.6.1",

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/src/superlocalmemory/cli/commands.py

@@ -4010,6 +4010,16 @@ def _cmd_doctor_checks(args: Namespace, state: dict) -> None:
                 f"enabled [{_surface_str}] {_stats}",
             )
 
+    _stage("Answer check fit")
+    # The text model this store runs on must be one recall's answer check was
+    # fitted for (core/support_fit_guard.py). "Upgrade memory engine" (4.1.25 to
+    # 4.2.1) moved text to the managed model; such a store refuses answers it has.
+    try:
+        from superlocalmemory.cli.doctor_models import answer_check_fit_finding
+        _check("Answer check fit", *answer_check_fit_finding(slm_home / "memory.db"))
+    except Exception as exc:  # noqa: BLE001 - one check never stops the doctor
+        _check("Answer check fit", "WARN", f"could not read: {type(exc).__name__}")
+
     _stage("Memory answer-ability")
     # Memory answer-ability.
     #

superlocalmemory-4.2.3/src/superlocalmemory/cli/doctor_models.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later
+"""Guidance on which extraction model to use. It only reads; it recommends and never changes models on its own."""
+
+from __future__ import annotations
+
+from superlocalmemory.core.model_catalog import best_local_llm
+
+
+def local_model_finding(config, installed: list[str], ram_gb: float | None = None):
+    chosen = config.llm.model
+    have = {name.removesuffix(":latest") for name in installed if ":cloud" not in name}
+    base = chosen.removesuffix(":latest")
+    if base not in have:
+        return (
+            "WARN",
+            f"{chosen} is not installed at the configured endpoint",
+            "Choose an installed model with slm setup; no model was changed.",
+        )
+    best = best_local_llm(ram_gb, list(have))
+    if best != base and best in have:
+        return (
+            "WARN",
+            f"{chosen} is configured; {best} is the recommended installed model",
+            f"Choose {best} explicitly with slm setup; no model was changed.",
+        )
+    return ("PASS", f"{chosen} is installed; no better installed recommendation", "")
+
+
+def answer_check_fit_finding(db_path) -> tuple[str, str, str]:
+    """Is recall's answer check fitted for the text model this store runs on?
+
+    A store moved to the managed model by "Upgrade memory engine" (4.1.25 to
+    4.2.1) runs a check fitted on another model and can refuse
+    answers it has (core/support_fit_guard.py). Read-only; never raises.
+    """
+    import json
+    import sqlite3
+    from pathlib import Path
+    from types import SimpleNamespace
+
+    from superlocalmemory.core.support_fit_guard import live_advice
+
+    path = Path(db_path)
+    if not path.is_file():
+        return "PASS", "no memory store yet", ""
+    try:
+        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        try:
+            row = conn.execute("SELECT live_config FROM embedding_space WHERE id = 1").fetchone()
+        finally:
+            conn.close()
+        live = json.loads(row[0]) if row and row[0] else {}
+    except (sqlite3.Error, ValueError):
+        return "PASS", "embedding space not recorded", ""
+    advice = live_advice(SimpleNamespace(**live)) if live else None
+    if advice:
+        return "WARN", advice, "slm embedder rollback"
+    return "PASS", f"fitted for {live.get('model_name') or 'the configured model'}", ""

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/src/superlocalmemory/cli/embedder_cmd.py

@@ -130,6 +130,8 @@ def _switch(args: Namespace) -> None:
             _fail(args, "switch", str(exc), "INVALID")
     if args.endpoint:
         body["api_endpoint"] = args.endpoint
+    if getattr(args, "force", False):
+        body["force"] = True  # past the answer-support fit check (core/support_fit_guard.py)
     data = _request(args, "switch", "POST", "", body)
     job = data["job"]
     if not getattr(args, "json", False) and not args.no_wait:
@@ -309,9 +311,11 @@ def register_embedder_parser(sub: Any) -> None:
     )
     s.add_argument("--endpoint", default="", help="OpenAI-compatible endpoint URL")
     s.add_argument("--no-wait", action="store_true", help="return as soon as it is queued")
+    s.add_argument("--force", action="store_true",
+                   help="switch text to a managed model the answer check is not yet fitted for")
     _json_flag(s)
     u = esub.add_parser(
-        "upgrade", help="move your memories to the newer memory engine (rolls back)"
+        "upgrade", help="not offered in this release: text stays on the text model (see docs)"
     )
     u.add_argument("--yes", "-y", action="store_true", help="do not ask")
     u.add_argument("--no-wait", action="store_true", help="return as soon as it is queued")

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/src/superlocalmemory/core/calibration_candidates.py

@@ -9,7 +9,11 @@ from superlocalmemory.retrieval.query_embedding import embed_as_query
 
 def raw_semantic(engine, question, top_k):
     retrieval = engine._retrieval_engine
-    channel = retrieval._channels.get("semantic")
+    # RetrievalEngine holds its channels as named attributes (_semantic, _bm25,
+    # ...); it has never had a `_channels` dict. 4.2.1 read one, and every
+    # calibration on a real install died at 40/48 on the first absent-answer
+    # sample because the stand-in engines in its tests invented the dict.
+    channel = retrieval._semantic
     embedder = getattr(engine, "_embedder", None)
     if channel is None or embedder is None:
         return [], []
@@ -17,10 +21,10 @@ def raw_semantic(engine, question, top_k):
     if not vector:
         return [], []
     hits = channel.search(
-        vector, engine._config.profile_id, top_k=top_k, include_global=False, include_shared=False
+        vector, engine.profile_id, top_k=top_k, include_global=False, include_shared=False
     )
     facts = engine._db.get_facts_by_ids(
-        [fact_id for fact_id, _ in hits], profile_id=engine._config.profile_id
+        [fact_id for fact_id, _ in hits], profile_id=engine.profile_id
     )
     by_id = {fact.fact_id: fact for fact in facts}
     visible = [(by_id[fact_id], score) for fact_id, score in hits if fact_id in by_id]
@@ -31,7 +35,7 @@ def source_score(engine, question, source_id):
     """A positive label belongs to its source vector, never the best noise hit."""
     import numpy as np
 
-    facts = engine._db.get_facts_by_ids([source_id], profile_id=engine._config.profile_id)
+    facts = engine._db.get_facts_by_ids([source_id], profile_id=engine.profile_id)
     fact = next((f for f in facts if f.fact_id == source_id), None)
     if fact is None or not fact.embedding:
         return []

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/src/superlocalmemory/core/calibration_control.py

@@ -23,7 +23,7 @@ class CancelToken:
         self._progress = progress
         from superlocalmemory.storage.embedding_spaces import signature_of
 
-        self._snapshot = (signature_of(engine._config.embedding), engine._config.profile_id)
+        self._snapshot = (signature_of(engine._config.embedding), engine.profile_id)
         self._judge = engine._retrieval_engine._sufficiency_judge
 
     @contextmanager
@@ -44,7 +44,7 @@ class CancelToken:
         engine = self._engine
         return (
             self._current_engine() is not engine
-            or (signature_of(engine._config.embedding), engine._config.profile_id) != self._snapshot
+            or (signature_of(engine._config.embedding), engine.profile_id) != self._snapshot
             or engine._retrieval_engine._sufficiency_judge is not self._judge
         )
 

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/src/superlocalmemory/core/calibration_examples.py

@@ -56,7 +56,7 @@ def local_question(model: str, fact: str, absent_subject: str = "", stop=None) -
 def build_examples(engine, model, samples, stop):
     from superlocalmemory.core.calibration_control import await_idle
 
-    profile = engine._config.profile_id
+    profile = engine.profile_id
     with stop.operation():
         facts = engine._db.get_all_facts(profile, limit=samples * 4)
     import random

{superlocalmemory-4.2.1 → superlocalmemory-4.2.3}/src/superlocalmemory/core/calibration_measure.py

@@ -35,7 +35,7 @@ def _sample(engine, judge, example, stop, *, baseline=None):
         from superlocalmemory.storage.models import Mode
 
         response = engine._retrieval_engine.recall(
-            example["question"], engine._config.profile_id, mode=Mode.A, limit=judge.top_k
+            example["question"], engine.profile_id, mode=Mode.A, limit=judge.top_k
         )  # local channels only: no LLM expansion, bandit plays, hooks or outcomes
         raw_facts, scores = raw_semantic(engine, example["question"], judge.top_k)
         if example["answered"]: