superlocalmemory 3.8.13 → 4.0.0

package/ATTRIBUTION.md

@@ -38,7 +38,7 @@ is_valid = QualixarSigner.verify(signed_output)
 
 ### Research Papers
 
-SuperLocalMemory is backed by three peer-reviewed research papers:
+SuperLocalMemory is backed by three public research preprints (arXiv preprints):
 
 1. **Paper 1 — Trust & Behavioral Foundations** (arXiv:2603.02240)
    Bayesian trust defense, behavioral pattern mining, OWASP-aligned memory poisoning protection.
@@ -47,7 +47,7 @@ SuperLocalMemory is backed by three peer-reviewed research papers:
    Fisher-Rao geodesic distance, cellular sheaf cohomology, Riemannian Langevin lifecycle dynamics.
 
 3. **Paper 3 — The Living Brain** (arXiv:2604.04514)
-   FRQAD mixed-precision metric, Ebbinghaus adaptive forgetting, 7-channel cognitive retrieval, memory parameterization, trust-weighted forgetting.
+   FRQAD mixed-precision metric, Ebbinghaus adaptive forgetting, five candidate producers plus entity-graph enhancement, memory parameterization, trust-weighted forgetting.
 
 ### Research Initiative
 
@@ -61,11 +61,11 @@ SuperLocalMemory uses the following open-source libraries:
 - NumPy (BSD-3-Clause) — Numerical operations
 - SciPy (BSD-3-Clause) — Numerical optimization (used by vCache MLE logistic refit)
 
-See [requirements.txt](requirements.txt) for the full dependency list.
+See [pyproject.toml](pyproject.toml) for the full dependency list.
 
 ### Optimize Module — Research Citations (v3.6)
 
-The Optimize module (LLD-03 / LLD-04) builds on peer-reviewed work.
+The Optimize module (LLD-03 / LLD-04) builds on cited public research.
 The Implementer verified each arXiv ID against arxiv.org before citation.
 
 | Component | Source | License / Note |

package/CHANGELOG.md

@@ -1,130 +1,122 @@
 # Changelog
 
-All notable changes to SuperLocalMemory V3 will be documented in this file.
+All notable changes to SuperLocalMemory will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.8.13] - 2026-08-03 — Stale-process detection
-
-### Fixed
-- A running process can now tell when it is serving superseded code. Python
-  imports a module once, so `__version__` is frozen at process start and
-  upgrading the package underneath a long-lived `slm mcp` server changes
-  nothing for that server — it keeps serving the code it read at startup,
-  indefinitely. Nothing detected this. The stale process did not error; it
-  returned confident, plausible, wrong answers and reported a
-  `serverInfo.version` matching the code it had loaded, which is
-  self-consistent and therefore useless as a staleness signal. During the
-  3.8.12 work one machine had eighteen `slm mcp` processes alive at once
-  spanning four days and two releases, and one of them made issue #106 look
-  unfixed across two debugging sessions. (#107)
-
-  The existing process reaper does not cover this: it kills *orphans*, whose
-  parent has died. A server whose IDE is still running is never an orphan.
-
-  Staleness is now reported by `slm doctor` (as a warning, with a restart
-  hint), on the loopback `/health` payload as `version_integrity`, and in the
-  `slm mcp` startup log. The MCP path logs to stderr only — that transport is
-  JSON-RPC over stdio, where a printed warning would corrupt the protocol and
-  turn a cosmetic problem into a dead session.
-
-  Running *ahead* of the installed distribution — normal for an editable
-  checkout — is deliberately reported separately and does not warn. A warning
-  that fires on every developer machine is one everybody learns to ignore, and
-  then it goes unread on the day it matters. Every failure path resolves to
-  `unknown` rather than to a false `current`.
-
-## [3.8.12] - 2026-08-03 — Canonical learning signals, clock-independent daemon identity, remote reranker
-
-### Fixed
-- Explicit feedback now reaches the store every consumer actually reads.
-  Three tables carry a "feedback" name: `feedback_records` (memory.db, read by
-  nothing), `learning_feedback` (the pre-v3.4.22 legacy table that
-  `legacy_migration` copies forward), and `learning_signals` +
-  `learning_features` (canonical — read by the dashboard Living Brain panel,
-  the ranker-phase card, and the LightGBM retrainer). The 3.8.11 fix wrote to
-  the legacy table, so it moved a counter nothing consumes. `record_explicit`
-  now writes the legacy row and the canonical signal/feature pair in one
-  transaction, flagged `is_synthetic=1` so the LightGBM trainer's
-  `WHERE is_synthetic=0` filter excludes them from training. (#106)
-- The recall phase gate and the dashboard no longer read different tables.
-  The gate counted `learning_feedback` while every user-visible surface counted
-  `learning_signals`, so the phase a user was shown and the phase that actually
-  ranked their results could disagree without limit. Both now resolve from the
-  canonical store, with thresholds imported from `learning.ranker` rather than
-  duplicated as literals — duplicated literals are how the two surfaces drifted
-  apart in the first place. (#106)
-- `report_feedback` no longer reports success for a write that did not happen.
-  It fell back to the `feedback_records` count when the canonical read failed,
-  and that table increments on every call regardless, so total write failure was
-  indistinguishable from success. The cross-store fallback is removed; a failed
-  durable write returns `success: false` with `durable: false`. (#106)
-- The CLI no longer disowns a healthy daemon after a few minutes on WSL2.
-  psutil derives `create_time` as boot time plus start ticks and re-reads
-  `/proc/stat` `btime` on every call; WSL2 resyncs its VM clock mid-session, so
-  `btime` moves and every process's computed creation time moves with it,
-  retroactively. The recorded value stopped matching the same live PID while
-  `/health` still answered in milliseconds. Ownership now compares a
-  clock-independent process token — `boot_id` plus raw start ticks on
-  Linux/WSL2, psutil's monotonic creation time elsewhere — as exact equality,
-  with no tolerance constant left to silently expire. PID-reuse protection is
-  strengthened: a creation-time mismatch no longer condemns a process outright,
-  it falls through to cryptographic identity proof over loopback. (#104)
-- `DAEMON_UNAVAILABLE` now names one of eight specific reasons with an
-  actionable hint instead of "owned daemon is unavailable; retry later". (#104)
-- `slm setup` no longer wipes the `retrieval` config block on every re-run.
+## [4.0.0] - 2026-08-01 — Verifiable memory transactions
+
+Version 4.0 hardens the full lifecycle of a memory operation — admission,
+canonical commit, projection to every store, migration, backup, and erasure —
+so each step is authorized and verifiable. Existing memories and
+configuration are preserved; M038 (eager) and M039 (deferred) migrations are
+automatically applied at startup — no manual migration is normally required
+(see `src/superlocalmemory/storage/migration_runner.py`; `slm db migrate` is
+forward-only: `status`/`--dry-run`/apply, no rollback). Schema downgrade is
+unsupported — restore a verified pre-upgrade backup instead.
+
+### Changed
+- **MCP SDK 2.0.0 (fully-stateless Streamable HTTP).** Pinned `mcp==2.0.0`.
+  Replaced deleted `mcp.server.fastmcp.FastMCP` with
+  `mcp.server.mcpserver.MCPServer` (same `@tool` decorator and
+  `run(transport="stdio")`). Transport knobs
+  (`stateless_http`, `json_response`, `streamable_http_path`,
+  `transport_security`) are now kwargs to `streamable_http_app()` —
+  `_configure_mcp_transport_settings()` returns that kwargs dict.
+  **Stateless is the default** (opt out with `SLM_MCP_STATEFUL=1`). Session
+  idle-timeout and EventStore SSE resumability are unused under
+  `stateless_http=True`. Application-level `session_init` / `close_session`
+  are unchanged (orthogonal to transport sessions). SDK lowlevel already
+  registers `server/discover` — not hand-written. Product version is passed
+  as `MCPServer(version=...)` (no private `_mcp_server.version` poke).
 
 ### Added
-- Remote and custom reranker endpoints, mirroring the remote embedding support
-  added in v3.4.24. Setting `cross_encoder_backend` to `openai` (or `remote`)
-  with a `cross_encoder_endpoint` routes reranking to an OpenAI-compatible
-  `/v1/rerank` service instead of the local subprocess worker. The built-in
-  cross-encoder is English-only, silently degrading recall for non-English
-  users; this lets them bring a multilingual model. Failure degrades to fusion
-  order with `applied=False` and an error log — never a silent fall back to the
-  local English model, which would recreate the very problem this solves. The
-  new outbound HTTP surface enforces an http/https allow-list, rejects 3xx and
-  does not follow redirects, refuses credentials embedded in the URL, and
-  bounds response reads at 8 MB. (#105)
-- `cross_encoder_endpoint` is now a real config field. It was previously
-  accepted and silently ignored — the remaining half of #103.
-
-## [3.8.11] - 2026-08-02 — Learning-signal integrity and honest reranker diagnostics
-
-### Fixed
-- Explicit feedback reported through `report_feedback` now writes to the
-  canonical learning store (`learning.db`), which every learning consumer
-  reads: the adaptive-ranking phase gate, `pattern_miner`, and the dashboard
-  Living Brain. Previously it wrote only to a table nothing else read, so
-  feedback returned success and a rising counter while the ranker never
-  advanced past Phase 1 (#102).
-- `learning_feedback` now has the `channel` column `pattern_miner` has always
-  queried but no schema ever defined. Every fresh database raised
-  `no such column: channel` on the first mining pass — caught, logged at
-  debug, and silently disabled both channel-performance mining and the
-  co-retrieval mining that shared its error handler. Migration `M033`
-  backfills existing databases without touching existing rows (#102).
-- The cross-encoder reranker now reports the real reason a model load
-  failed instead of a generic timeout message, and no longer retries a
-  configuration error five times (~7.5 minutes) before giving up. An
-  unrecognized `cross_encoder_backend` value is now rejected by name;
-  SuperLocalMemory has no remote/OpenAI-compatible reranker backend, so a
-  `cross_encoder_endpoint` config key was previously accepted and silently
-  ignored (#103).
-- `slm recall` no longer crashes when a daemon response's
-  `retrieval_time_ms` or a result's `score` is present but `null` — the
-  keyword-fallback recall path now includes `retrieval_time_ms` in every
-  response, matching every other recall path's contract.
-- The MagicMock artifact guard (`.gitignore` and its CI test) now also
-  catches the directory-shaped leak (`MagicMock/mock/<id>/`) produced when
-  a mock-derived path reaches `mkdir()`, not just the file-shaped leak
-  (`<MagicMock id='...'>`) produced by `os.open()`.
+- A unified admission gateway resolves one authenticated actor, active profile,
+  and policy decision for every write across the CLI, MCP, HTTP, WebSocket, and
+  hook surfaces.
+- Every completed operation carries a durable receipt and a hash-verifiable
+  completion manifest spanning all representations.
+- **BackupCoordinator** is available as a coherent, checksum-verified backup
+  set primitive (`src/superlocalmemory/infra/backup.py`: `BackupCoordinator.create_backup_set()` /
+  `restore_from_manifest()` — shared epoch, per-store SHA-256, manifest hash,
+  atomic publish, pre-restore snapshot + rollback). Production backup,
+  dashboard, cloud, and export routes currently use the **legacy
+  `BackupManager`** independent per-file SQLite `sqlite3.backup()` snapshots
+  (one file at a time); companion-store failures are logged as non-critical
+  and do not fail the primary `memory.db` snapshot (`_backup_all_dbs`). See
+  correction note below.
+- **SLM-Mesh** remains the peer-coordination plane (cross-session / cross-machine
+  messages, locks, shared state, inbox/outbox) with mesh MCP tools on the
+  `full` / `power` / `mesh` profiles.
+- Documented MCP profile counts for the V4 surface: `full` 42 (default everyday),
+  `power` 54, `whole` 87 registered tools; `core` 14, `code` 24, `mesh` 8.
+- Product documentation reframes the release as V4: multi-scope memory and
+  profiles, cache/compress context optimization, Entity Explorer and skill
+  evolution, Modes A/B/C locality choices, GDPR export/erasure/retention and
+  hash-chained audit controls, and the seven-layer retrieval/operations stack.
 
-### Documentation
-- `docs/auto-memory.md` no longer references `slm patterns` / `slm useful`,
-  which do not exist in V3; documents the `report_feedback` MCP tool as the
-  supported path instead.
+### Security
+- Outbound provider requests are validated against server-side request forgery,
+  blocking internal metadata endpoints and unresolved hosts.
+- Secrets are scrubbed from content before it is persisted or indexed, on both
+  the canonical write path and import.
+- Profile erasure removes every representation — main store, projections,
+  full-text and semantic indexes, and the context cache — and reports each count.
+- Mesh peers receive server-assigned identities bound to tenant and project;
+  production remote transport rejects plaintext, and shared state rejects
+  secret-looking values.
+
+### Fixed
+- A corrected fact is re-indexed everywhere, so semantic and keyword recall
+  reflect the new content instead of a stale copy.
+- Archived facts are excluded from every read path, including keyword search
+  and direct fetch.
+- Schema migrations refuse to run against a database written by a newer build,
+  and a migration whose dependency did not complete is held back.
+- In-memory configuration changes are preserved across a save, and unknown or
+  externally tuned settings survive a load/save cycle.
+
+### Backup scope and offline guidance (correction)
+
+*Correction 2026-08-08 — the 2026-08-01 text “Backups are captured as a
+coherent, checksum-verified set and restored atomically …” described the
+`BackupCoordinator` primitive, not the wired production path. The production
+path ( `BackupManager.create_backup()` / `server/routes/backup.py` /
+`maintenance_scheduler` auto-backup / cloud sync / dashboard **Export**
+) remains independent per-file `sqlite3.backup()` snapshots; this entry is
+preserved with this pointer rather than silently rewritten.*
+
+- Included stores (legacy path): `memory.db`, `learning.db`, `audit_chain.db`,
+  `code_graph.db`, `pending.db`, `audit.db` — only those present on disk; no
+  other files are backed up. `memory-*.db` is the primary snapshot;
+  `_backup_all_dbs()` copies remaining managed DBs one-by-one.
+  Companion-copy exceptions are caught and logged at `warning` as non-critical.
+  `lance/` (LanceDB directory) is **not** included by the legacy path; the
+  coherent primitive handles it as an out-of-manifest companion.
+- Exclusions: nothing outside `MANAGED_DATABASES`; no coherent epoch or
+  cross-store manifest/rollback claim for the production path.
+- Dashboard **Export** (`POST /api/backup/export`) creates a single compressed
+  `.db.gz` from the latest `memory.db` snapshot only (`memory-*.db` → gzip).
+  It is not a coherent whole-root export.
+- No `BackupCoordinator` epoch/atomic-set / whole-root backup is wired to
+  production routes or `slm` subcommands in this release.
+- Legacy backup destination files follow the process **umask**, not source-file
+  permission inheritance; there is no unwired whole-root restore route. For
+  offline whole-root backup/restore, `slm serve stop` (stop the daemon) first
+  so WAL/SHM are checkpointed, then copy the complete data-root store set
+  (all present `*.db` plus `-wal`/`-shm` sidecars and `lance/` if present)
+  with the destination directory on an encrypted/private volume; verify
+  resulting files are owner-only (`0600`/`0700`) after copy.
+- Legacy backup destination follows process umask; do not claim source
+  permission inheritance.
+
+### Notes
+- Existing memories and configuration are preserved. V4.0.0 M038 (eager) and
+  M039 (deferred) are auto-applied at startup; no manual `slm db migrate` is
+  normally required. Downgrade requires a verified pre-upgrade complete backup
+  (stop daemon before offline copy, include WAL/SHM). No `slm db migrate
+  --rollback`; use restore of that backup instead.
 
 ## [3.8.10] - 2026-07-29 — Reliable startup and MCP writes
 
@@ -2387,7 +2379,7 @@ Hardening release — correctness, stability, and security fixes.
 **Varun Pratap Bhardwaj**
 *Solution Architect*
 
-SuperLocalMemory V3 - Intelligent local memory system for AI coding assistants.
+SuperLocalMemory V4 - Intelligent local memory system for AI coding assistants.
 
 ---
 
@@ -2825,7 +2817,7 @@ We use [Semantic Versioning](https://semver.org/):
 - **MINOR:** New features (backward compatible, e.g., 2.0.0 → 2.1.0)
 - **PATCH:** Bug fixes (backward compatible, e.g., 2.1.0 → 2.1.1)
 
-**Current Version:** v3.3.0
+**Current Version:** v4.0.0 (see top of this file for the active release entry)
 **Website:** [superlocalmemory.com](https://superlocalmemory.com)
 **npm:** `npm install -g superlocalmemory`
 
@@ -2833,7 +2825,7 @@ We use [Semantic Versioning](https://semver.org/):
 
 ## License
 
-SuperLocalMemory V3 is released under the [Elastic License 2.0](LICENSE).
+Early SuperLocalMemory V3 packaging used the [Elastic License 2.0](LICENSE); the current public project license is AGPL-3.0-or-later (see LICENSE at the repository root).
 
 ---
 

package/README.md

@@ -5,22 +5,41 @@
   </picture>
 </p>
 
-<h1 align="center">SuperLocalMemory V3.8.13</h1>
-<p align="center"><strong>Enterprise-grade, local-first memory for AI agents and teams.</strong><br/>
-<em>A persistent, auditable long-term brain for your agents that runs on your own infrastructure — with multi-workspace isolation, role-based access, and GDPR + EU AI Act governance controls built in.</em></p>
-<p align="center"><code>v3.8.13</code> — one control plane: auditable retrieval · multi-scope memory (personal / shared / global) · Cache · Compress · trusted-peer Mesh · bounded loops — across CLI, MCP, dashboard, the <strong>Claude plugin</strong>, the <strong>Codex add-on</strong>, and documented IDE integrations.<br/>
+<h1 align="center">SuperLocalMemory V4.0.0</h1>
+
+<h2 align="center">Rent the LLM. Own the memory.</h2>
+
+<p align="center"><em>Rent an LLM — but own the memory, for your company and for your industry.</em></p>
+
+<p align="center"><strong>The governed memory layer for AI agents: local-first, auditable, and built for the compliance obligations teams now actually carry.</strong><br/>
+Models are interchangeable and rented by the token. What your agents <em>remember</em> is
+yours — it is your customers' data, your retention obligations, and your audit trail. SLM
+keeps that layer on infrastructure you control, with multi-workspace isolation, role-based
+access, and GDPR + EU AI Act governance controls built in.</p>
+
+<p align="center"><strong>The boundary.</strong> SuperLocalMemory starts with a local runtime;
+provider-backed enrichment, cloud backup, connectors, and proxy use are explicit choices.
+Different products solve different boundaries. Published benchmark evidence carried into V4
+comes from the published V3 research architecture; it is not a claim of a newly rerun V4 package benchmark.</p>
+
+<p align="center"><strong>How to check that, rather than believe it.</strong> Every reliability
+guarantee here is stated as a falsifiable invariant, tested under an adversarial condition with a
+negative control, and shipped with the harness that regenerates the evidence:
+<code>python benchmark/run_all.py --trials 200 --output-dir results/</code>. What each experiment
+does <em>not</em> exercise is stated too.</p>
+<p align="center"><code>v4.0.0</code> — one control plane: <strong>SLM-Mesh</strong> peer coordination · multi-scope memory (personal / shared / global) · profiles · Cache · Compress · 7-layer retrieval · code graph · Entity Explorer · skill evolution · Modes A/B/C · GDPR retention &amp; audit chain · bounded loops — across CLI, MCP, dashboard, the <strong>Claude plugin</strong>, the <strong>Codex add-on</strong>, and documented IDE integrations.<br/>
 Proxy: <code>slm wrap claude</code> &nbsp;·&nbsp; MCP: add <code>slm_compress</code> to your config &nbsp;·&nbsp; Skill: zero-config</p>
 <p align="center"><strong>3 public research preprints</strong> (arXiv + Zenodo archives) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/v3.8.13-Current_Release-2ea44f?style=for-the-badge&logo=checkmarx&logoColor=white" alt="v3.8.13 — Current Release"/></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/v4.0.0-Current_Release-2ea44f?style=for-the-badge&logo=checkmarx&logoColor=white" alt="v4.0.0 — Current Release"/></a>
   <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv Paper"/></a>
   <a href="#three-surfaces-proxy--mcp-tools--skill"><img src="https://img.shields.io/badge/Proxy_|_MCP_|_Skill-22c55e?style=for-the-badge" alt="Three Surfaces: Proxy, MCP Tools, Skill"/></a>
   <a href="https://pypi.org/project/superlocalmemory/"><img src="https://img.shields.io/pypi/v/superlocalmemory?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"/></a>
   <a href="https://www.npmjs.com/package/superlocalmemory"><img src="https://img.shields.io/npm/v/superlocalmemory?style=for-the-badge&logo=npm&logoColor=white" alt="npm"/></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL_v3-blue.svg?style=for-the-badge" alt="AGPL v3"/></a>
   <a href="#privacy-controls-and-operating-modes"><img src="https://img.shields.io/badge/Privacy-Deployment_Assessed-brightgreen?style=for-the-badge" alt="Privacy controls require deployment assessment"/></a>
-  <a href="#teams-and-enterprise-memory-v380"><img src="https://img.shields.io/badge/Enterprise-GDPR_%7C_EU_AI_Act-0b5394?style=for-the-badge" alt="Enterprise governance: GDPR and EU AI Act controls"/></a>
+  <a href="#teams-and-enterprise-memory-v4"><img src="https://img.shields.io/badge/Enterprise-GDPR_%7C_EU_AI_Act-0b5394?style=for-the-badge" alt="Enterprise governance: GDPR and EU AI Act controls"/></a>
   <a href="https://superlocalmemory.com"><img src="https://img.shields.io/badge/Web-superlocalmemory.com-ff6b35?style=for-the-badge" alt="Website"/></a>
   <a href="#dual-interface-mcp--cli"><img src="https://img.shields.io/badge/MCP-Native-blue?style=for-the-badge" alt="MCP Native"/></a>
   <a href="#dual-interface-mcp--cli"><img src="https://img.shields.io/badge/CLI-Agent--Native-green?style=for-the-badge" alt="CLI Agent-Native"/></a>
@@ -35,21 +54,24 @@ SuperLocalMemory is an enterprise-grade, local-first memory control plane for AI
 
 Agent-memory systems make different storage, model-provider, and deployment trade-offs. SuperLocalMemory starts with a local runtime and makes provider-backed enrichment, cloud backup, connectors, and proxy use explicit choices.
 
-Different products solve different boundaries. The published benchmark evidence carried into V3.8.0 is protocol-scoped evidence from the published V3 research, not a claim of a newly rerun V3.8.0 package benchmark.
+Different products solve different boundaries. The published LoCoMo benchmark evidence in this README is protocol-scoped evidence from the published V3 research architecture; it is carried forward for continuity and is not a claim of a newly rerun V4 package benchmark.
 
-SuperLocalMemory V3 combines conventional dense and lexical retrieval with graph, temporal, associative, and statistical relevance scoring. The default local runtime does not require Docker, a separately operated graph database, or an API key.
+SuperLocalMemory V4 combines conventional dense and lexical retrieval with graph, temporal, associative, and statistical relevance scoring in a **7-layer** control plane (admission → queryable core → enrichment → brain → multi-channel retrieval → context safety → operations). The default local runtime does not require Docker, a separately operated graph database, or an API key.
 
 **Memory with a sense of time.** SLM does not only store *what* an agent learned — it records *when*. Every fact carries ingestion timing and provenance; recall runs a dedicated temporal candidate channel alongside semantic, lexical, and associative retrieval; scenes and entity timelines reconstruct sequence; and the lifecycle lets neglected memory decay and self-archive instead of growing without bound. Time is a first-class ranking and lifecycle signal rather than a timestamp column an agent never reads — which is what lets a long-lived agent reason about how its context changed, not only what it currently holds.
 
-**What V3.8.0 added.** The 3.8.0 capability release introduced the following
-foundation; 3.8.1 is the existing-install stability patch for it:
+**What V4.0.0 ships.** V4 is a *governed* local-first control plane — every canonical write is admitted, policy-authorized, tracked as durable per-store obligations (lexical, temporal, vector), and sealed by a completion manifest, so it is either fully applied or explicitly marked degraded, never silently half-done. Flagship surfaces in this release:
 
-- **Temporal depth** — the time-aware retrieval and lifecycle described above.
-- **Governance & EU compliance** — [team roles, workspace isolation, a login gate, multi-scope memory, GDPR access/erasure/portability rights, a hash-chained audit trail, and per-mode EU AI Act self-assessment](#teams-and-enterprise-memory-v380).
-- **Framework adapters** — [drop-in, engine-backed memory for nine agent frameworks](#framework-adapters-v380).
-- **Bounded loops** — [gate-verified agent loops where an independent check, not the agent's own claim, decides when a task is done](#bounded-loops-v380).
-- **Stronger cache and compression** — exact-match caching with tagged invalidation plus opt-in reversible compression, across proxy, MCP, and skill surfaces.
-- **Stability** — a long defect-and-audit sweep across ingestion, retrieval, mesh, and the dashboard hardens the everyday path.
+- **[SLM-Mesh](#slm-mesh-cross-session--cross-machine-coordination)** — authenticated cross-session and cross-machine peer coordination (messages, locks, shared state, inbox/outbox, optional discovery). Coordination only — not automatic replicated memory.
+- **Multi-scope memory & profiles** — workspaces (profiles) plus `personal` / `shared` / `global` scopes; cross-profile recall is default-deny.
+- **Cache & compression (context optimization)** — exact-match cache with tagged invalidation, safe compression, and opt-in reversible/aggressive paths across proxy, MCP, and skill surfaces.
+- **Entity Explorer & skill evolution** — compiled entity summaries/timelines; opt-in skill lineage, budgets, and verification outcomes.
+- **Modes A / B / C** — local-only (A), on-device LLM enrichment (B), provider-assisted (C). An operating mode records technical locality facts; it does **not** determine EU AI Act legal compliance (that is deployment-context assessment — see [Privacy controls](#privacy-controls-and-operating-modes)).
+- **GDPR posture, retention & audit chain** — export, fail-closed cross-store erasure, retention policies, and a hash-chained audit trail. Engineering controls for compliance programs, not a legal certification.
+- **7-layer retrieval/recall stack & code graph** — multi-channel candidates (semantic, BM25, temporal, Hopfield, spreading activation) plus optional code-graph tools for blast radius and review context.
+- **MCP profiles** — `full` exposes **42** tools (default everyday surface); `power` **54**; `whole` **87** (all registered). Also `core` (14), `code` (24), and `mesh` (8).
+- **Governed write path & verifiable transactions** — admission + policy control, a per-owner obligation ledger, and a hash-sealed completion manifest with a reconciler that redrives unmet obligations.
+- **Self-healing lifecycle & admin remediation** — stale locks cleared on restart; list/resolve stuck operations from CLI, MCP, or the dashboard.
 
 SLM is one strand of Qualixar's work on AI reliability engineering: making agent behavior observable, bounded, and reproducible instead of best-effort.
 
@@ -60,7 +82,7 @@ The architecture evaluated in the V3 paper remains the foundation of this releas
 Different products solve different boundaries. SLM is for developers who want
 one local-first operating control plane—not only an SDK, managed context API,
 or agent runtime. It combines dated evidence, graph-aware retrieval, cache and
-compression controls, trusted-peer Mesh, and MCP/CLI/hooks/dashboard/IDE
+compression controls, **SLM-Mesh**, and MCP/CLI/hooks/dashboard/IDE
 surfaces in one install.
 
 | If your primary need is… | Product boundary to evaluate |
@@ -78,24 +100,24 @@ for current primary sources and protocol-scoped benchmark evidence. A LoCoMo
 percentage is comparable only when the dataset scope, answer model, judge,
 retrieval stack, and release artifact match.
 
-### The V3.8.0 capability architecture
+### The V4 capability architecture
 
 SuperLocalMemory is one local control plane for persistent agent context. It is
 not just a vector store: the same runtime can accept evidence, build and govern
 memory, retrieve bounded evidence for an agent, and expose cache, compression,
-and peer-coordination controls through a CLI, MCP, dashboard, and supported
+and **SLM-Mesh** peer-coordination controls through a CLI, MCP, dashboard, and supported
 IDE integrations.
 
-![SuperLocalMemory V3 capability architecture: modes, seven operating layers, Scale Engine, Mesh, delivery surfaces, and opt-in adapters](docs/assets/slm-v37-capability-architecture.png)
+![SuperLocalMemory V4 capability architecture: modes, seven operating layers, Scale Engine, SLM-Mesh, delivery surfaces, and opt-in adapters](docs/assets/slm-v37-capability-architecture.png)
 
 *Architecture boundary: SQLite + sqlite-vec remain canonical; CozoDB and
-LanceDB are parity-gated projections; Mesh coordinates trusted peers rather
+LanceDB are parity-gated projections; **SLM-Mesh** coordinates trusted peers rather
 than replicating a distributed memory database; connectors are opt-in.*
 
 **Memory boundaries:** profiles isolate workspaces by default. Every memory is
 `personal`, `shared` with named profile readers, or `global`; cross-profile
 recall is default-deny and must be explicitly enabled. This scoped sharing is
-local authorization, not SLM Mesh synchronization. See
+local authorization, not **SLM-Mesh** synchronization. See
 [shared-memory.md](docs/shared-memory.md).
 
 ```text
@@ -130,7 +152,7 @@ health surfaces expose the stages actually completed by the installed runtime.
 | **Knowledge graph and entities** | Canonical entities, aliases, entity profiles, graph edges, scenes, timelines, explorer and graph APIs | Stored/derived graph data is evidence, not an instruction authority. |
 | **Scale Engine** | SQLite + sqlite-vec are canonical. CozoDB graph and LanceDB vector projections are managed with prepare → verify → promote → rollback; a structurally detected pre-v3.7 projection can be explicitly adopted. | Promotion is parity-gated and crash-recoverable. Legacy adoption preserves the prior projection as a rollback backup; repeated physical edge rows normalize to one logical edge with the strongest weight. |
 | **Optimize** | Exact cache, tagged invalidation, safe compression, opt-in aggressive prose compression, CCR originals, proxy/MCP/skill surfaces | Only proxy intercepts a primary provider turn. MCP/skill cache results explicitly routed through SLM. |
-| **Mesh** | Authenticated peer messages, inbox/outbox, locks, offline queue, optional discovery and mesh MCP tools | Mesh is coordination, not automatic replicated memory or conflict resolution. |
+| **SLM-Mesh** | Authenticated peer messages, inbox/outbox, locks, offline queue, optional discovery and mesh MCP tools | SLM-Mesh is coordination, not automatic replicated memory or conflict resolution. |
 | **Governance and operations** | Provenance, audit/retention/policy surfaces, export/erasure controls, diagnostics, health, backups and daemon lifecycle | These are engineering controls, not a legal certification. |
 | **Integrations** | CLI, Python SDK, MCP HTTP/stdio, Claude plugin, Codex add-on, supported IDE configurations, Gmail/Calendar/transcript adapters | Hooks, IDE edits, connectors, and networked adapters require explicit operator activation. |
 
@@ -146,7 +168,7 @@ health surfaces expose the stages actually completed by the installed runtime.
 | Operations | ingestion-operation state, traces, maintenance and lifecycle work |
 | Entity Explorer and Skill Evolution | compiled entity summaries/timelines; opt-in skill lineage, budgets and verification outcomes |
 | Multi-Agent Memory | per-agent write activity and attribution; memories stamped by `SLM_AGENT_ID`, agent write counts, and trust signals |
-| Mesh Peers | configured peers, inbox/outbox, pending coordination and locks |
+| SLM-Mesh Peers | configured peers, inbox/outbox, pending coordination and locks |
 | Settings and Optimize | mode/provider/configuration; cache, compression and savings telemetry |
 
 Dashboard visibility is not a substitute for runtime proof: use `slm doctor`,
@@ -159,9 +181,9 @@ deployment.
 
 **[Watch the SuperLocalMemory demo on YouTube](https://www.youtube.com/watch?v=PMWW_ypsL60)** — a five-minute walkthrough of installation, setup, recall, cache, and compression. The video shows a product walkthrough; use the commands and release notes in this README as the current release contract.
 
-### Published LoCoMo evidence (V3 architecture, carried into V3.8.0)
+### Published LoCoMo evidence (V3 architecture, carried into V4)
 
-The V3 paper evaluates the architecture carried into V3.8.0. Every figure below
+The V3 paper evaluates the multi-channel architecture that V4 still runs. Every figure below
 is protocol-scoped, so a reader can distinguish local retrieval, answer
 construction, and cloud-assisted evaluation rather than treating unlike runs as
 one score.
@@ -182,7 +204,7 @@ information-geometric layers versus **58.9%** without them: **+12.7pp**.
 See [arXiv:2603.14588](https://arxiv.org/abs/2603.14588) and the [official
 LoCoMo paper](https://arxiv.org/abs/2402.17753) for the full protocol,
 ablation table, and limitations. These are published V3 architecture results
-carried into V3.8.0—not a substitute for a newly rerun release-artifact benchmark.
+carried into V4—not a substitute for a newly rerun release-artifact benchmark.
 
 ---
 
@@ -294,10 +316,6 @@ quality must be evaluated for the target client and workload; V3.8.0 publishes n
 
 **Multilingual models:** configure an OpenAI-compatible embedding endpoint such as Ollama, vLLM, LiteLLM, `bge-m3`, `multilingual-e5`, or `Qwen3-Embedding`. Language coverage and retrieval quality depend on the selected model and should be evaluated for the deployment corpus.
 
-<a id="remote-embedding-and-rerank-endpoints"></a>
-
-**Remote embedding + rerank endpoints.** The bundled reranker `cross-encoder/ms-marco-MiniLM-L-12-v2` is **English-only**, so a Chinese, Japanese, or Arabic corpus is scored by a model that cannot read it. Set `retrieval.cross_encoder_backend: "openai"` plus `retrieval.cross_encoder_endpoint` to route reranking to any Cohere-shaped `POST /v1/rerank` service — llama-server, text-embeddings-inference, Infinity — running a multilingual model such as `BAAI/bge-reranker-v2-m3` (v3.8.12, [#105](https://github.com/qualixar/superlocalmemory/issues/105); the same escape hatch embeddings got in v3.4.24, [#16](https://github.com/qualixar/superlocalmemory/issues/16)). No subprocess and no local model download. An unreachable, slow, or malformed endpoint logs an error and returns fusion-ranked results — SLM never silently substitutes the local English model. Keys, auth, and failure semantics: **[docs/configuration.md](docs/configuration.md#remote-embedding-and-rerank-endpoints)**.
-
 ### Cache + Compress
 
 <a id="three-surfaces-proxy--mcp-tools--skill"></a>
@@ -327,11 +345,12 @@ actual cost and latency savings depend on the intercepted surface and provider.
 
 **Savings dashboard:** `slm optimize savings --since 7` — live USD/INR/tokens saved. Hot-reload config, fail-open.
 
-### Mesh
+### SLM-Mesh (cross-session / cross-machine coordination)
 
 <a id="multi-machine-mesh-coordination"></a>
+<a id="slm-mesh-cross-session--cross-machine-coordination"></a>
 
-Mesh provides authenticated coordination messages between configured peers, with an offline queue and optional mDNS discovery (`SLM_MESH_DISCOVERY=on`). It is not a replicated or conflict-resolving distributed-memory database.
+**SLM-Mesh** is the V4 peer-coordination plane: authenticated messages, locks, shared lightweight state, inbox/outbox, and an offline queue between configured peers (same machine sessions or cross-machine). Optional mDNS discovery (`SLM_MESH_DISCOVERY=on`). It is **not** a replicated or conflict-resolving distributed-memory database — multi-scope memory sharing is a separate local-authorization feature.
 
 ```bash
 # Machine A (broker)
@@ -345,7 +364,7 @@ export SLM_MESH_SHARED_SECRET=my-secret-key
 slm init
 ```
 
-8 mesh MCP tools: `mesh_summary`, `mesh_peers`, `mesh_send`, `mesh_inbox`, `mesh_state`, `mesh_lock`, `mesh_events`, `mesh_status`.
+Eight **SLM-Mesh** MCP tools: `mesh_summary`, `mesh_peers`, `mesh_send`, `mesh_inbox`, `mesh_state`, `mesh_lock`, `mesh_events`, `mesh_status`.
 
 Full docs: [docs/multi-machine.md](docs/multi-machine.md) · [docs/distributed-deployment.md](docs/distributed-deployment.md)
 
@@ -353,6 +372,8 @@ Full docs: [docs/multi-machine.md](docs/multi-machine.md) · [docs/distributed-d
 
 ## Install Paths
 
+> **V4 platform support:** Apple Silicon macOS, 64-bit Windows, and 64-bit Linux. Intel Mac and 32-bit Windows are not supported by the patched `cryptography` 50 runtime.
+
 | Path | Command | When |
 |:-----|:--------|:-----|
 | **npm global CLI** (primary) | `npm install -g superlocalmemory` | Node 18+; package-owned virtual environment; system Python is not modified; run `slm setup` explicitly afterward |
@@ -398,10 +419,10 @@ Control tool surface via `SLM_MCP_PROFILE`:
 |:--------|:-----:|:---------|
 | `core` | 14 | Memory, session, and optimize core |
 | `code` | 24 | Core + code-graph tools + profile switching + bounded loops |
-| `mesh` | 8 | Mesh-only — multi-machine coordination |
+| `mesh` | 8 | SLM-Mesh only — multi-session / multi-machine coordination |
 | `full` | 42 | Memory + optimize + evolution + mesh + bounded loops |
 | `power` | 54 | Full + administration, lifecycle, and diagnostics |
-| `whole` | all registered | Every registered MCP tool |
+| `whole` | 87 | Every registered MCP tool |
 
 **Precedence:** `ALL` > `TOOLS` > `PROFILE` > `default`
 
@@ -514,9 +535,9 @@ Available controls include local export and erasure commands, hash-chained audit
 
 ---
 
-## Teams and Enterprise Memory (v3.8.0)
+## Teams and Enterprise Memory (V4)
 
-V3.8.0 adds multi-user, multi-workspace controls for teams and organizations. These are opt-in — personal single-user installs work exactly as before with no required login.
+V4 includes multi-user, multi-workspace controls for teams and organizations (introduced on the 3.8 line and retained). These are opt-in — personal single-user installs work exactly as before with no required login.
 
 ### Users and roles
 
@@ -570,12 +591,9 @@ These are engineering controls. Compliance depends on deployment configuration,
 
 ### EU AI Act mode verification
 
-SLM includes a per-mode EU AI Act self-assessment. The `EUAIActChecker` produces a compliance report for the active operating mode — risk category, whether data stays local, whether generative AI is used, and transparency / human-oversight signals:
+SLM includes a per-mode EU AI Act *technical posture* report (`EUAIActChecker`). It records facts the runtime can know — whether data is configured to stay local, whether generative AI is used, and that transparency / human-oversight need deployment evidence.
 
-- **Mode A (Local Guardian)** and **Mode B (Smart Local)** — assessed as compliant: memory processing stays local and uses no generative AI.
-- **Mode C (Provider-assisted)** — flagged non-compliant, because query or enrichment content is sent to a cloud model provider.
-
-This is operator self-assessment tooling, not a legal certification or conformity assessment; actual EU AI Act obligations depend on your system, deployment, and role. See [docs/compliance.md](docs/compliance.md).
+**An operating mode does not establish legal compliance under the EU AI Act.** Legal risk classification and conformity assessment depend on intended purpose, affected persons, sector, deployment context, and operator controls. The checker therefore returns `compliant=None` / risk category `undetermined` for every mode and always requires deployment-context review. Mode A/B/C only change technical locality and enrichment options (for example Mode C may send content to a configured provider). See [docs/compliance.md](docs/compliance.md) and `src/superlocalmemory/core/modes.py`.
 
 ### Deployment tiers
 
@@ -594,7 +612,7 @@ Full reference: [docs/rbac-teams.md](docs/rbac-teams.md) · [docs/deployment-tie
 
 ---
 
-## Bounded Loops (v3.8.0)
+## Bounded Loops (V4)
 
 A bounded loop terminates only when an **independent gate** passes — a test
 suite exit code, a linter, a JSON-schema check, or an SLM-recall condition.
@@ -625,7 +643,7 @@ Multi-Agent Memory workspace.
 
 ---
 
-## Framework Adapters (v3.8.0)
+## Framework Adapters (V4)
 
 SLM ships nine framework adapters under `ide/integrations/`. Each adapter
 wires SLM as the memory and history provider for the respective framework
@@ -687,32 +705,16 @@ SuperLocalMemory is backed by three preprints by Varun Pratap Bhardwaj (2026):
 Use the citation metadata on the linked arXiv or Zenodo records.
 
 ## Support / License / Qualixar
-
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. [Wiki](https://github.com/qualixar/superlocalmemory/wiki) for detailed documentation.
-
 GNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](LICENSE).
-
 For commercial licensing (closed-source, proprietary, or hosted use), see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md) or contact varun.pratap.bhardwaj@gmail.com.
-
 Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar.
-
 Part of [Qualixar](https://qualixar.com) · Author: [Varun Pratap Bhardwaj](https://varunpratap.com)
-
-### Acknowledgments
-
-- **[Everything Claude Code (ECC)](https://github.com/affaan-m/everything-claude-code)** inspired SLM's skill-observation patterns; SLM can ingest ECC observations with `slm ingest --source ecc`.
-- **[HKUDS/OpenSpace](https://github.com/HKUDS/OpenSpace)** informed the skill-evolution verification design (arXiv:2604.01687).
-
-### Qualixar AI Agent Reliability Platform
-
-Qualixar builds open-source infrastructure for AI reliability engineering.
-Start at **[qualixar.com](https://qualixar.com)** or browse the
-[Qualixar research archive](https://huggingface.co/Qualixar).
+Acknowledgments: [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) informed skill observation; [HKUDS/OpenSpace](https://github.com/HKUDS/OpenSpace) informed skill-evolution verification.
+Qualixar builds open-source infrastructure for AI reliability engineering. Start at [qualixar.com](https://qualixar.com) or browse the [research archive](https://huggingface.co/Qualixar).
 
 ## Star This Project
 
 If this project solves a real problem for you, **please star the repo** — it helps other developers discover Qualixar and signals that the AI agent reliability community is growing.
 
 [![Star SuperLocalMemory on GitHub](https://img.shields.io/github/stars/qualixar/superlocalmemory?style=for-the-badge&logo=github&label=Star%20on%20GitHub)](https://github.com/qualixar/superlocalmemory)
-
-The live Star History chart is intentionally not embedded: its upstream service timed out during release validation. The link above is the stable, direct way to star and follow the repository.