superlocalmemory 4.1.23 → 4.2.0

package/plugin-src/skills/slm-recall/SKILL.md

@@ -8,7 +8,7 @@ when_to_use: |
   - "Find stored information about authentication / the database / error handling"
   - "Search for what I said about Y"
   - Automatically before any non-trivial task, to surface prior context
-allowed-tools: recall, search, fetch, list_recent, get_memory_summary, run_view, report_outcome, report_feedback, Bash
+allowed-tools: recall, search, fetch, expand, list_recent, get_memory_summary, run_view, report_outcome, report_feedback, Bash
 ---
 
 # slm-recall — Search & Retrieve Memory
@@ -25,6 +25,7 @@ multi-channel retrieval. The golden rule: **recall before you remember**.
 | Conceptual or paraphrase query ("what did we agree on for auth?") | `recall` — full multi-channel retrieval + rerank |
 | Exact keyword match needed ("find facts containing BM25") | `search` — FTS5 BM25 only, lower latency |
 | You have a specific `fact_id` from a prior result | `fetch` — exact lookup, full detail |
+| One result looks right and you need what surrounds it | `expand` — source memory, session neighbours, same-entity facts, the correction that replaced it |
 | Browse newest entries without a query | `list_recent` |
 | A day, a project or a session in readable form | `get_memory_summary` |
 | A question the user saved under a name | `run_view` |
@@ -67,6 +68,7 @@ wraps the same data in a `data` envelope):
       "memory_id": "m7e19ca0",
       "content": "Decided to use JWT with 1h expiry for API auth (2026-06-10)",
       "score": 0.87,
+      "tier": "supported",
       "confidence": 0.91,
       "trust_score": 0.84,
       "fact_type": "semantic",
@@ -107,12 +109,25 @@ wraps the same data in a `data` envelope):
   "answer_confidence": null,
   "abstained": false,
   "abstention_reason": null,
+  "abstention_note": "",
+  "tier": "supported",
+  "warming_up": false,
+  "status_note": "",
   "answer_check_status": "off",
   "answerability": "unjudged",
   "answerability_reason": "disabled"
 }
 ```
 
+A result that came from a saved picture or a PDF page also carries a `media`
+block (`media_id`, `kind` of `image` or `page`, `thumbnail_uri`, `page`,
+`document_id`, `citation` such as `page 12`). Pictures and pages are searched
+by a normal `recall` while pictures and documents are on; nothing changes when
+they are off. From an app on this computer, up to three thumbnails follow the
+JSON as image blocks; `get_media(media_id)` shows any other. Look at a
+thumbnail before saying a picture shows something, and give the page when you
+quote a PDF. See `slm-media`.
+
 Other fields that can appear: `profile` (the namespace that answered),
 `project_scope` (what a `project` filter did), `tag_scope` (what a `tags`
 filter did), `temporal_frame`, `reranker_status`, and `thematic_context`.
@@ -145,6 +160,14 @@ rest come back empty.
 `empty`, `no_candidates`, `disabled` and `not_configured` are normal. `error`,
 `timeout`, `no_embedding` and `warming` mean the answer is **incomplete, not
 negative** — say so to the user rather than reporting "no memories found".
+
+**Busy is not empty.** When many agents ask at once, recall waits up to about
+twelve seconds for a free slot. If it still cannot start, it returns
+`code: "RECALL_BUSY"`, `retryable: true` and a plain sentence ("Ask again in
+about N seconds"). Wait that long and ask again; never tell the user the memory
+lacks the answer. The same question asked twice at once runs once, and an answer
+is reused for a few seconds only while nothing is written, so a `remember` you
+just made is always visible to your next `recall`.
 `incomplete_channels` lists the channels abandoned at the time limit, so two
 runs of the same question that differ only there are an incomplete answer, not
 a changed memory.
@@ -153,6 +176,15 @@ a changed memory.
 
 **`abstained` means the results shown do not answer the question.** If `abstained` is `true`, say you don't have it, or ask — never present the returned memories as the answer anyway. `abstention_reason` distinguishes why: `"judged_insufficient"` means candidates were found and scored, but none of them actually answers this question; `"evidence_floor"` / `"no_candidates"` means nothing was found at all. `answer_confidence` is a measurement, not a guarantee — treat a low number the same way you'd treat `abstained: true`. `calibration_status: "uncalibrated"` means no judge is configured for this recall; in that case `abstained` only ever reflects the older "nothing found" signal.
 
+**Scores rank results; they are not probabilities.** `score` (an alias of
+`relevance_score`) says how relevant a memory is to this query compared with
+the others. It does not say how likely an answer is to be right, so never turn
+it into a percentage, average it, or compare it across releases or
+configurations. `answer_confidence` is `null` unless an answer check ran. When
+the answer check is on and judges that the memories do not answer the
+question, `abstained` is `true` and you say you do not have it. See
+`docs/retrieval-score-contract.md`.
+
 **`abstained: false` does not mean the answer was checked.** `answerability` says
 whether it was: `supported` (the answer check ran and judged the shown memories
 sufficient), `unsupported` (it ran and judged them insufficient) or `unjudged`
@@ -163,6 +195,55 @@ or `judged_from_memo` for a verdict, and for `unjudged` one of `disabled`,
 `no_results`, which is not evidence that no answer exists (check
 `channel_status`). `answer_check_note` carries a sentence you can show a person.
 
+### 1b. Tiers: supported, related, none
+
+Every recall says which of three answers it is, in `tier` (on the response and
+on each result):
+
+| `tier` | what it means | what you do |
+|---|---|---|
+| `supported` | a memory carries the answer | use it |
+| `related` | the question is real, but nothing answers it exactly | `abstention_note` is "I don't have this exactly — here are the closest memories." Say you don't have it exactly; you may mention the closest memories (each labelled `tier: related`, a short preview), never present them as the answer |
+| `none` | nonsense, or nothing close | `abstention_note` is "That isn't in SuperLocalMemory." **Stop. Do not invent an answer**, and do not keep rephrasing the same question |
+
+The MCP `recall` returns `supported` results only. Pass `include_related=true`
+to see up to three related memories when there is no supported one (without
+it, a related answer comes back empty with "I don't have this exactly. Closer
+memories exist; ask with include_related to see them."). `search`, the CLI and
+the dashboard show related memories by default, labelled. `show_weak=true`
+shows every weak match anyway, each labelled `weak: true`.
+
+**`warming_up: true` means ask again shortly.** Right after a start, while the
+models and inputs are still loading, recall returns what keyword search found
+(as `related`) with `status_note`: "SuperLocalMemory is still warming up —
+results may be incomplete. Try again in a few minutes." Tell the user that, and
+do not conclude the memory is absent: SLM never says "That isn't in
+SuperLocalMemory." while warming up.
+
+### 1c. Depth, max_tokens and expand
+
+Recall in layers and spend context only where it pays:
+
+| `depth` | returns |
+|---|---|
+| `0` glance | ids, `tier`, score and a one-line preview — the cheapest look |
+| `1` recall | the full facts (the default) |
+| `2` context | + `context`: the source memory, up to three facts from the same session, up to three about the same entities, and `superseded_by` when a correction replaced it |
+
+`max_tokens` caps the whole result list and is never exceeded: context goes
+first, then the last memory is shortened, then memories are left out, and
+`layers` says what was trimmed. Start at `depth=0` or `1`; when one result is
+the right one, drill into it with `expand`:
+
+```
+recall(query="hub resultType fix", depth=0, max_tokens=400, session_id="<sid>")
+expand(memory_id="f8a2bc91", depth=2, max_tokens=800)
+```
+
+`expand` takes a result's `fact_id` or `memory_id` and runs the same profile,
+quarantine and visibility checks as `fetch`; every memory it adds passes them
+too.
+
 ### 2. Passing session_id
 
 Pass the `session_id` returned by `session_init`, on **every** recall in that
@@ -344,8 +425,10 @@ No benchmark numbers are cited here; performance is workload-dependent.
 ## CLI fallback (when MCP is unavailable)
 
 ```bash
-# Multi-channel recall
+# Multi-channel recall (related memories are shown, labelled [related])
 slm recall "<query>" [--limit N] [--json]
+slm recall "<query>" --depth 0|1|2 [--max-tokens N]   # glance, full, with context
+slm recall "<query>" --show-weak                       # every weak match, labelled [weak]
 
 # Narrow it (all optional, combined as AND)
 slm recall "<query>" --project <name-or-path> [--project-strict] [--prefer-project <path>]
@@ -383,6 +466,10 @@ configuration. See [docs/shared-memory.md](../../../docs/shared-memory.md).
 
 ## Never fabricate a memory
 
+"That isn't in SuperLocalMemory." (`tier: none`) is final for that question:
+stop and say so; do not invent an answer. While `warming_up` is true, say SLM
+is still warming up and to try again in a few minutes instead.
+
 After re-querying with refined sub-queries (see **Refine on low confidence** above), if `no_confident_match` is still `true` or results are empty, report it plainly.
 Never construct a response as if a memory was found when it was not. The user
 trusts that what you surface came from the store.
@@ -424,7 +511,8 @@ See `slm-profile`.
 - `slm-session` — session lifecycle (must call before first recall)
 - `slm-scope` — multi-scope sharing model (personal / shared / global)
 - `slm-profile` — workspace isolation and profile switching
+- `slm-media` — pictures and PDF pages in results, and how to save them
 
 ---
 
-*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.0 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-remember/SKILL.md

@@ -28,6 +28,10 @@ sessions. One fact per call. Recall before you remember.
 - Security rules ("Rate limit all public endpoints at 100 req/min")
 
 **Do not store:**
+- Pictures or PDFs through `remember`. It stores text. A screenshot, photo or
+  PDF goes through `remember_media` or `remember_document`; see `slm-media`.
+  Add the reason it matters in the text of a normal memory if you also want a
+  fact about it.
 - Transient context that is only relevant within this conversation
 - Large blobs of code or full file contents (those belong in the project, not memory)
 - Facts the project README already captures
@@ -364,7 +368,8 @@ sessions on this machine, so use it only when the user asks to move. See
 - `slm-session` — session lifecycle; session_id is required for attribution
 - `slm-scope` — complete guide to personal / shared / global scopes
 - `slm-profile` — workspace isolation and profile switching
+- `slm-media` — saving pictures and PDFs (`remember_media`, `remember_document`)
 
 ---
 
-*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.0 · Qualixar · AGPL-3.0-or-later*

package/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.1.23 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.2.0 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-session/SKILL.md

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

package/plugin-src/skills/slm-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: slm-status
 description: Health and optimization stats for SuperLocalMemory — call slm_optimize_stats() for live compression and cache counters (compress_runs, tokens_saved_compress, cache_proxy_hits, cache_proxy_misses, cache_kv_hits, cache_kv_misses); run slm status [--json] for system state (mode, profile, DB size, fact/entity/edge counts) and slm doctor [--json] for preflight including the "Optimize (Surface B)" health line; use together to confirm optimization is actually saving tokens.
-when_to_use: "check slm status, health check, is slm working, optimize stats, tokens saved, cache hits, compress runs, slm doctor, preflight, db size, slm info, diagnose slm"
+when_to_use: "check slm status, health check, is slm working, optimize stats, tokens saved, cache hits, compress runs, slm doctor, preflight, db size, slm info, diagnose slm, slm media status, are pictures on, slm features, picture search not working, slm media repair, embedder status, memory health, slm enrich, repair memories, undo a repair"
 allowed-tools: slm_optimize_stats, get_status, get_brain_evidence_status, Bash
 ---
 
@@ -153,6 +153,49 @@ operations and, for an owner or admin, resolves them. The MCP counterpart for
 Living Brain totals is `get_brain_evidence_status(profile_id="")`; it only
 observes and does not change recall, ranking or review.
 
+## Memory health: SLM looks after older memories
+
+While the computer is idle, Memory health describes older memories (event dates,
+names, projects, tags and kinds) by adding only — it never changes or deletes what
+was written. Repairs that move or delete anything wait for the owner's **Fix**, and
+every run that changed something can be undone.
+
+```bash
+slm enrich status              # progress, repairs waiting, the id of every run that changed something
+slm enrich pause <run>         # recall and remember keep working
+slm enrich resume <run>
+slm enrich fix entity-links    # apply a suggested repair (asks first)
+slm enrich undo                # undo the latest run that changed something (asks first)
+```
+
+`repair-saves` keeps no undo record; it says so and takes a safety copy before it
+runs. An undone repair is not suggested again until you ask with
+`--include-undone`. The dashboard shows the same state on the **Memory health**
+card at the top of the Health pane. Guide: `docs/memory-health.md`.
+
+## Pictures and documents: status and repair
+
+Pictures and documents are an optional feature, off by default. Check them with
+the CLI (the MCP `get_status` does not report them):
+
+```bash
+slm media status [--json]     # off | on, setting up (state, percent) | on | failed, with the step
+slm features [--json]         # what is on and what can be turned on: pictures and documents, folder sources, bot messages
+slm media repair --dry-run    # count pictures that cannot be found by what they show yet (owner or admin)
+slm media repair              # re-embed them; up to four minutes per run, run again if it says some are left
+slm media gc                  # report picture records without a memory, files without a record (removes nothing)
+slm embedder status           # progress of an embedding-model switch or the memory-engine upgrade
+```
+
+If `slm media status` says "set-up failed", run `slm doctor` for the step that
+failed. The five picture tools (`remember_media`, `get_media`,
+`remember_document`, `media_status`, `media_upload_link`) are listed only while
+the feature is on and only in the `full`, `power` and `whole` tool sets; a
+restart (`slm restart`) starts the picture worker. A document's own progress
+is the `media_status` MCP tool, not this command. Details, limits and the
+16 GB requirement: `slm-media`. `slm status` also prints an "Embedding switch" line while a model switch or
+the memory-engine upgrade is pending.
+
 ## Recommended Health Workflow
 
 1. Run `slm doctor --json` at session start to confirm all subsystems are up.
@@ -160,6 +203,7 @@ observes and does not change recall, ranking or review.
 3. Run `slm status --json` when you need DB size or memory counts.
 4. If `ok: false` on any MCP tool — check `note` field, then run `slm doctor` to isolate the failure.
 5. If recall seems to miss memories that were saved, run `slm db integrity` before concluding anything.
+6. If a picture will not come back for a question about what it shows, run `slm media status`, then `slm media repair --dry-run`.
 
 ## Fail-Open
 
@@ -179,7 +223,9 @@ observes and does not change recall, ranking or review.
 - `slm-profile` — workspace isolation and profile switching
 - `slm-cache` — KV cache performance metrics
 - `slm-compress` — reversible context compression
+- `slm-media` — pictures, PDFs and folders
+- `slm-web-access` — the Connected apps page and web-app connection states
 
 ---
 
-SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.2.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-web-access/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: slm-web-access
-description: Set up and troubleshoot SuperLocalMemory Web access, the optional link that lets web apps (ChatGPT, Claude on the web, Muse, Composio, other remote MCP clients) use the memory on this computer. Covers turning it on from the dashboard, adding and removing apps, read/save/session permissions, renewal, the connection states, the errors a web app can see, and the copy-paste instructions for web agents.
-when_to_use: "web access, connected apps, connect chatgpt, connect claude web, connect muse, connect composio, remote mcp, mcp.superlocalmemory.com, connector_asleep, DAILY_LIMIT_REACHED, web app cannot reach memory, instructions for web agent"
+description: Set up and troubleshoot SuperLocalMemory Web access, the optional link that lets web apps (ChatGPT, Claude on the web, Muse, Composio, other remote MCP clients) use the memory on this computer. Covers turning it on from the dashboard, adding and removing apps, read/save/session permissions, the second yes for bot messages and pictures (the Web access switches in Connected apps), one-time upload links for pictures and PDFs, what leaves the computer, renewal, the connection states, the errors a web app can see, and the copy-paste instructions for web agents.
+when_to_use: "web access, connected apps, connect chatgpt, connect claude web, connect muse, connect composio, connect grok bot, remote mcp, mcp.superlocalmemory.com, connector_asleep, DAILY_LIMIT_REACHED, web app cannot reach memory, instructions for web agent, web app bot messages, web app upload link, Let these apps message your other bots, Let these apps save and read pictures and documents, not_for_remote"
 allowed-tools: get_status, Read, Bash
 ---
 
@@ -29,7 +29,8 @@ named keys, for tools on another computer in your own network.
    app** (reading is always included). **Allow saving memories** adds the
    `remember` tool and **Allow session tools** adds `session_init`,
    `close_session`, `report_feedback` and `report_outcome`; both are separate
-   opt-ins.
+   opt-ins. Bot messages and pictures are two more opt-ins that the app asks
+   for on its own approval page; see "The second yes" below.
 4. Select **Link this computer with GitHub** and finish sign-in in the page
    that opens. Wait until the row reads "On. Apps you approve can reach your
    memory while this computer is online."
@@ -52,12 +53,88 @@ setup. `scope` must be personal, `shared_with` is refused, and `replaces` is
 refused (`CORRECTION_DENIED`): corrections, deletes and sharing stay on this
 computer.
 
+Two more groups need the second yes (next section):
+
+- **Bot messages:** `mesh_peers`, `mesh_send`, `mesh_inbox`, `mesh_wait`,
+  `mesh_state` (read only). See `slm-mesh`.
+- **Pictures and documents:** `get_media`, `media_status`; with Save also
+  `remember_media`, `remember_document` and `media_upload_link`. See
+  `slm-media`.
+
+Everything else (`mesh_lock`, `mesh_summary`, `mesh_events`, `mesh_status`,
+`switch_profile`, maintenance, code graph, loops, `forget`) stays on this
+computer.
+
+## The second yes: Web access switches
+
+Bot messages and pictures need two yeses. Without both, the call is refused.
+
+1. **The app's approval page.** Tick **Allow talking to your other bots** and
+   **Allow images and documents**. Both start unticked and appear only when the
+   app asks for them. Saving files also needs **Allow saving memories**.
+2. **This computer.** In **Connected apps**, the **Web access** row has two
+   switches: **Let these apps message your other bots (SLM Mesh)** and **Let
+   these apps save and read pictures and documents**. They apply to every app on
+   that connection on its next request. From a terminal the same switches are
+   on the connection's remote key, named `web-<connection id>`:
+
+```bash
+slm remote keys list
+slm remote keys allow web-<connection id> mesh
+slm remote keys allow web-<connection id> media
+slm remote keys disallow web-<connection id> mesh
+```
+
+Turning pictures off also ends any upload link the connection has not used.
+The owner flips these; an agent must not. Pictures also need the feature
+itself to be on (`slm media status`; see `slm-media`).
+
+ChatGPT keeps the permissions it saw when the app was created: after a new
+permission, uninstall the app and add it again. Composio needs a manual
+toolkit re-sync to see new tools.
+
+## Adding a picture or PDF from a web app
+
+A chat cannot type a file into a tool call. The app asks for an upload link
+(`media_upload_link`, kind `image` or `document`) and shows it to the person.
+The person opens it in any browser, picks the file and presses Save; the page
+says "Saved to your memory" when this computer has it. The file streams to this
+computer through the gateway, which keeps no copy. A link belongs to the app
+that asked for it, works once, expires in 10 minutes, and must not be shared.
+Each connection can have 3 open links and 20 uploads a day. Pictures can be up
+to 25 MB (PNG, JPEG, GIF, WebP), PDFs up to 100 MB. This computer must be awake
+and running SLM. If SLM was updated, links made before the update stop working:
+ask the app for a new one.
+
+ChatGPT can instead hand over a file attached to the chat. This computer
+downloads it only from ChatGPT's own file hosts plus hosts in
+`SLM_MEDIA_URL_HOSTS`, which is empty by default; a refusal such as "That host
+is not on the allowed list" means the owner must add the host. Per-app steps
+are in `docs/remote-access/hosts.md`.
+
+## What leaves the computer
+
+The memory database never leaves the computer. Each tool call and its result
+pass through SuperLocalMemory's connection gateway and the app that made the
+call. Memory text the app recalls is visible to that app. Bot messages and peer
+summaries are secret-redacted before a web app sees them; a picture or page
+whose text held a secret or personal data is not shown to web apps at all, and
+connected folders are never shown to them.
+Uploaded files travel through the gateway to this computer and are not stored
+there. An app cannot change, delete, pin or replace a memory it is not allowed
+to see; it is answered as if that memory did not exist.
+
 ## Instructions for the web agent
 
 The app also needs to know when to use the tools. Give the owner
-`docs/web-agents/instructions.md` (full and short blocks) or the Agent Skill
-folder `docs/web-agents/superlocalmemory-web/`. The dashboard's **How to add an
-app** panel has a **Copy instructions** button with the short block.
+`docs/web-agents/setup-prompt.md` (paste it into a chat with the app once
+connected), `docs/web-agents/instructions.md` (full and short blocks) or the
+Agent Skill folder `docs/web-agents/superlocalmemory-web/`. The dashboard's
+**How to add an app** panel has a **Copy instructions** button with the short
+block. All of them cover recall, saving, upload links for pictures, bot
+messages with `mesh_wait` and `ack`, and what to do on errors.
+Exact per-app steps (ChatGPT, ChatGPT dots, Grok Bot, Composio, Muse) are in
+`docs/remote-access/hosts.md`.
 
 ## Renewal
 
@@ -77,6 +154,8 @@ affected.
 | `relay_busy` | Too many calls in flight at once | Make calls one at a time |
 | `DAILY_LIMIT_REACHED` (HTTP 429) | The free daily allowance is used up | Resets at midnight UTC (`Retry-After` says when) |
 | `TOOL_DENIED`, `INSUFFICIENT_SCOPE` | The app was not given that permission | Remove its access and add it again with the permission ticked |
+| `not_for_remote`, `not_allowed` (pictures) or a refused mesh call | The app has the box but the Web access switch (or the key's `mesh`/`media` opt-in) is off, or the key is not a write key | Turn the switch on in **Connected apps**, or `slm remote keys allow web-<connection id> mesh\|media` |
+| `MESH_SEND_LIMIT` | The app sent its 200 bot messages for today | Stop sending until the daily count resets |
 | `CORRECTION_DENIED`, `SHARING_DENIED`, `PROFILE_DENIED` | The app tried something only this computer may do | Do it locally |
 | `REVOKED` | The owner removed the app | Add it again if wanted |
 | `ENTITLEMENT_REQUIRED` | Web access has ended | Turn it on again in **Connected apps** |
@@ -89,3 +168,12 @@ To check from this computer, call `get_status` and run `slm status`; the
 **Connected apps** → the app's row → **Remove access**. The gateway refuses its
 next call.
 Memory and local configuration are kept.
+
+---
+
+## Related skills
+
+- `slm-media` — pictures, PDFs and upload links in detail
+- `slm-mesh` — bot messages, `mesh_wait` and `ack`
+- `slm-bot-memory` and `slm-getting-started-bot` — bots that share one computer
+- `slm-governance` — roles and company mode

package/scripts/postinstall/engine-upgrade.js

@@ -0,0 +1,112 @@
+/**
+ * The "Upgrade memory engine" offer at install time.
+ *
+ * For someone who already has memories, the installer can offer to move them to the
+ * newer memory engine. Like the images-and-documents request, it only records a request
+ * in <data root>/features.json; the SLM daemon acts on it at its next start, once the
+ * images-and-documents environment is ready. Nothing is downloaded here.
+ *
+ * Off until the memory check on the Mac passes (UPGRADE_PROMPT_ENABLED): the explicit
+ * command (slm embedder upgrade) and the dashboard button work before that, an
+ * unsolicited prompt does not. Never asks off a terminal or in CI; the default is No.
+ *
+ * Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+ * Licensed under AGPL-3.0-or-later.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const { FEATURES_FILE, resolveDataRoot, recordMediaRequest } = require('./media-request.js');
+
+const UPGRADE_PROMPT_ENABLED = false;
+const MANAGED_PROVIDER = 'slm-media';
+
+function printUpgradeOffer(log = console.log) {
+  log('');
+  log('SLM: you can move your memories to the newer memory engine (it also reads pictures and documents).');
+  log('  Your memories are re-read in the background. Recall keeps working meanwhile, nothing is deleted,');
+  log('  and you can roll back. It needs images and documents turned on (about 1.5 GB of models).');
+  log('  Any time: slm embedder upgrade');
+}
+
+/** True for an existing store (memory.db present) that is not already on the managed model. */
+function shouldOffer(slmDir) {
+  if (!fs.existsSync(path.join(slmDir, 'memory.db'))) return false;
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(slmDir, 'config.json'), 'utf8'));
+    return !(config && config.embedding && config.embedding.provider === MANAGED_PROVIDER);
+  } catch (_e) {
+    return true;
+  }
+}
+
+/** Merge {"engine_upgrade": {"requested": true, ...}} into features.json (mode 0600). Never throws. */
+function recordUpgradeRequest(slmDir, now = new Date()) {
+  const file = path.join(slmDir, FEATURES_FILE);
+  try {
+    let data = { schema: 1 };
+    if (fs.existsSync(file)) {
+      data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
+    }
+    data.engine_upgrade = { requested: true, requested_at: now.toISOString(), choice_source: 'npm' };
+    const tmp = file + '.tmp';
+    const fd = fs.openSync(tmp, 'w', 0o600);
+    try {
+      fs.writeSync(fd, JSON.stringify(data), 0, 'utf8');
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, file);
+    if (process.platform !== 'win32') {
+      try { fs.chmodSync(file, 0o600); } catch (_e) { /* best-effort */ }
+    }
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^\s*y(es)?\s*$/i.test(answer || ''));
+    });
+  });
+}
+
+/**
+ * Offer (when enabled, on a terminal, outside CI, for an existing store) and record on a yes.
+ * Returns true when a request was recorded. Never downloads, never throws.
+ */
+async function runUpgradeStep({ enabled = UPGRADE_PROMPT_ENABLED, env = process.env, tty, ask,
+  log = console.log, slmDir } = {}) {
+  try {
+    if (!enabled) return false;
+    const isTty = tty !== undefined ? tty : Boolean(process.stdout.isTTY && process.stdin.isTTY);
+    const ci = env.CI === 'true' || env.CI === '1';
+    const dir = slmDir || resolveDataRoot(env);
+    if (!isTty || ci || !shouldOffer(dir)) return false;
+    printUpgradeOffer(log);
+    const yes = await (ask || askYesNo)('Upgrade the memory engine after install? [y/N] ');
+    if (!yes) return false;
+    const media = recordMediaRequest(dir);
+    if (!media.ok || !recordUpgradeRequest(dir)) {
+      log('SLM: could not record the request. Run later: slm embedder upgrade');
+      return false;
+    }
+    log('SLM: the upgrade will start the next time SLM starts, once images and documents are ready.');
+    return true;
+  } catch (e) {
+    log('SLM: could not record the upgrade choice (' + e.message + '). Run later: slm embedder upgrade');
+    return false;
+  }
+}
+
+module.exports = { UPGRADE_PROMPT_ENABLED, printUpgradeOffer, recordUpgradeRequest, runUpgradeStep, shouldOffer };