release: v6.0.1 — llamacpp embedder L2-normalization fix

perlowja · perlowja · commit 334e3b54309b · 2026-07-10T22:28:27.000-04:00
Bumps pyproject.toml / mnemos/_version.py to 6.0.1 and moves the CHANGELOG Unreleased section under a dated 6.0.1 entry alongside the new llamacpp-backend L2-normalization fix (adf01f6). Updates every operator-facing doc's current-version claim, health-JSON examples, "Tracks MNEMOS server vX" footers, and "as of vX" markers from 6.0.0 to 6.0.1 per tests/test_doc_version_pins_match_code.py.
diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md
@@ -1,7 +1,7 @@
 # MNEMOS API Documentation
 
 **Base URL**: `http://localhost:5002`
-**Version**: v6.0.0 current (release candidate; legacy GA is v5.0.1) (on top of v5.0.0 GA shipped 2026-05-02)
+**Version**: v6.0.1 current (patch release on the v6.0.0 GA line; legacy GA is v5.0.1) (on top of v5.0.0 GA shipped 2026-05-02)
 **Format**: JSON
 
 ---
@@ -63,7 +63,7 @@ Liveness + readiness check (no auth required).
   "status": "healthy",
   "timestamp": "2026-05-02T14:30:00.000Z",
   "database_connected": true,
-  "version": "6.0.0",
+  "version": "6.0.1",
   "profile": "edge",
   "distillation_worker": "idle"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -57,6 +57,45 @@ All notable changes to MNEMOS are documented here.
 
 ## [Unreleased]
 
+## [6.0.1] — 2026-07-10
+
+### Fixed — `_LlamaCppBackend` embeddings missing L2-normalization
+
+`mnemos/runtime/embedder.py`'s `_LlamaCppBackend._embed_sync` returned
+`llama_cpp.Llama.create_embedding()`'s raw output unnormalized, unlike
+`_OpenVINOBackend._embed_sync` and `_CixNpuBackend._embed_sync`, which
+both L2-normalize. Any deployment on `MNEMOS_EMBED_BACKEND=llamacpp`
+(the in-process path for AMD ROCm / NVIDIA CUDA / CPU hosts per the
+2026-05-21 in-process-embedding architecture decision) stored
+correctly-shaped but wrong-magnitude vectors.
+
+`mnemos/api/routes/memories.py`'s `score_to_similarity()` converts a
+backend's raw distance to a similarity via `sim = 1.0 - (v*v)/2.0` for
+the `euclidean_unit` metric — valid only when both vectors are unit
+length (max distance ≈ 2). Un-normalized llama.cpp vectors produced raw
+distances around 20+, so `sim` came out deeply negative, clamped to
+`0.0`, and fell below `effective_semantic_floor()` (default 0.65) on
+every query. `insert_memory` succeeded and the vector really was
+stored (confirmed via direct `VECTOR_DIMENSION_COUNT()` / raw
+`VECTOR_DISTANCE` queries) — `semantic_search` just silently returned
+zero rows, with no exception or log line anywhere in the stack.
+
+Fix: `_embed_sync` now L2-normalizes its output, matching the other
+two in-process backends.
+
+**Operator note:** any memories written under `MNEMOS_EMBED_BACKEND=llamacpp`
+before this fix have wrong-magnitude vectors permanently stored and
+will not surface in search until re-embedded/backfilled. Separately —
+not a code bug, but a deployment trap this fix's investigation
+surfaced — switching embedding *backend* is not the same as preserving
+the embedding *model*: two different models at the same dimensionality
+(e.g. bge-m3 vs bge-large-en-v1.5, both 1024-dim) produce mutually
+incompatible vector spaces, so a host with an existing corpus must
+migrate to a backend serving the *identical* model or run a full
+re-embed.
+
+Pinned by `tests/test_inprocess_embedder.py::test_real_embed_is_l2_normalized`.
+
 ### Fixed — Webhook deliveries limit cap + capabilities GIN index (#205)
 
 Two LOW audit findings (`mem_1778221719390_8cb1ba`) bundled.
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
@@ -1,6 +1,6 @@
 # MNEMOS Deployment & Configuration Guide
 
-**Status**: v6.0.0 current (release candidate; legacy GA is v5.0.1) (released on top of the v5.0.0 GA shipped 2026-05-02).
+**Status**: v6.0.1 current (patch release on the v6.0.0 GA line; legacy GA is v5.0.1) (released on top of the v5.0.0 GA shipped 2026-05-02).
 
 ---
 
@@ -38,7 +38,7 @@ mnemos serve --profile dev
 ### Installation
 
 ```bash
-python -m pip install mnemos-os==6.0.0  # source-install from v6.0-rc tag
+python -m pip install mnemos-os==6.0.1  # source-install from v6.0-rc tag
 mnemos install --profile dev
 mnemos serve --profile dev
 ```
diff --git a/EVOLUTION.md b/EVOLUTION.md
@@ -2,7 +2,7 @@
 
 The version numbers on releases are tidy. The actual path was not. This
 document is the honest version — decisions, refactors, mistakes, and the
-reasoning that got us from the original prototype to the current v6.0.0 release line. If you
+reasoning that got us from the original prototype to the current v6.0.1 release line. If you
 are considering MNEMOS for your own stack, you should know where it came
 from; if you are contributing, you should know which doors have been closed
 and why.
diff --git a/QUICK_START_REQUIREMENTS.md b/QUICK_START_REQUIREMENTS.md
@@ -1,6 +1,6 @@
 # MNEMOS Quick Start Requirements
 
-**Applies to**: current v6.0.0 release line (legacy GA v5.0.1)
+**Applies to**: current v6.0.1 release line (legacy GA v5.0.1)
 **TL;DR**: Python 3.11+ for package installs; no host Python for single-binary.
 Use SQLite for `edge`/`dev`, or PostgreSQL 16 + Redis for `server`.
 **Full Details**: See `SYSTEM_REQUIREMENTS.md`
@@ -34,7 +34,7 @@ sudo apt install -y git curl build-essential libpq-dev
 # 3. MNEMOS package (2 minutes)
 python3.11 -m venv ~/.venvs/mnemos
 source ~/.venvs/mnemos/bin/activate
-pip install mnemos-os==6.0.0  # source-install from v6.0-rc tag
+pip install mnemos-os==6.0.1  # source-install from v6.0-rc tag
 
 # 4. SQLite-backed dev profile
 mnemos install --profile dev
@@ -47,7 +47,7 @@ For a production `server` profile, add PostgreSQL + pgvector and Redis:
 sudo apt install -y postgresql-16 postgresql-16-pgvector postgresql-client redis-server
 python3.11 -m venv venv
 source venv/bin/activate
-pip install mnemos-os==6.0.0  # source-install from v6.0-rc tag
+pip install mnemos-os==6.0.1  # source-install from v6.0-rc tag
 export MNEMOS_PROFILE=server
 export RATE_LIMIT_STORAGE_URI=redis://localhost:6379/1
 mnemos install --profile server
@@ -326,6 +326,6 @@ kill -9 <PID>
 
 ---
 
-**Version**: v6.0.0 (release candidate)
-**Updated**: 2026-05-08
+**Version**: v6.0.1
+**Updated**: 2026-07-10
 **Accuracy**: Production-verified
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@
 
 # MNEMOS + GRAEAE
 
-**MNEMOS v6.0.0 is the memory operating system for
+**MNEMOS v6.0.1 is the memory operating system for
 serious agentic work: a packaged FastAPI runtime, **EPIMONE** — the six-backend
 persistence layer (SQLite + sqlite-vec by default, PostgreSQL + pgvector,
 Oracle Database 26ai HNSW INMEMORY NEIGHBOR GRAPH, IBM Db2 12.1.5 (EAP) DiskANN
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -6,10 +6,11 @@ This document is kept intentionally narrow. It lists what the next release will
 
 ---
 
-## Current status — v6.0.0 GA (split-distribution release; legacy GA v5.0.1 shipped 2026-05-08)
+## Current status — v6.0.1 GA (patch release on the v6.0.0 split-distribution line; legacy GA v5.0.1 shipped 2026-05-08)
 
-**v6.0.0 (split-distribution GA)** makes MNEMOS a modular, multi-backend,
-portability-first memory platform. New in v6.0.0:
+**v6.0.1** is a patch release on top of **v6.0.0 (split-distribution GA)**,
+which made MNEMOS a modular, multi-backend, portability-first memory
+platform. New in v6.0.0:
 
 - ✅ **MIF 1.0 as the native portability format** — CHARON native adapter with
   lossless round-trip export/import, MIF bundles (concept files + manifest), and a
diff --git a/SYSTEM_REQUIREMENTS.md b/SYSTEM_REQUIREMENTS.md
@@ -1,7 +1,7 @@
 # System Requirements
 
 Reference for operators planning a MNEMOS deployment. Covers the
-resource floor for each of the operating modes that the current v6.0.0 release line supports
+resource floor for each of the operating modes that the current v6.0.1 release line supports
 today, plus what drops off at each tier.
 
 Profiles are descriptive sizing tiers. The feature set is controlled by
diff --git a/docs/GRAEAE_FEATURES.md b/docs/GRAEAE_FEATURES.md
@@ -1,6 +1,6 @@
 # GRAEAE Feature Surface
 
-**Status:** current v6.0.0 documentation (on top of v5.0.0 GA shipped 2026-05-02).
+**Status:** current v6.0.1 documentation (patch release on the v6.0.0 line; on top of v5.0.0 GA shipped 2026-05-02).
 
 GRAEAE is MNEMOS's multi-provider reasoning bus. It fans a prompt out to live
 LLM providers, scores the responses, persists consultations, and writes a
diff --git a/docs/MEMORY_ARCHITECTURE.md b/docs/MEMORY_ARCHITECTURE.md
@@ -272,7 +272,7 @@ fleet without bloating the install.
 ### 5.4 Hot-path expansion
 
 The compression read paths preferring compressed variants over raw
-content is incremental. As of v6.0.0:
+content is incremental. As of v6.0.1:
 
 * `/v1/memories/search` honors `include_compressed` to swap
   variants into the response.
@@ -605,4 +605,4 @@ round-trip on the native subset.
 
 ---
 
-*v1.0 — 2026-05-08. Tracks MNEMOS server v6.0.0*
+*v1.0 — 2026-05-08. Tracks MNEMOS server v6.0.1*
diff --git a/docs/OBSERVABILITY.md b/docs/OBSERVABILITY.md
@@ -90,7 +90,7 @@ Drop to 10s only if you're actively debugging a latency spike.
 
 ## 3. The shipped metrics
 
-As of v6.0.0 the stable metric surface is:
+As of v6.0.1 the stable metric surface is:
 
 ### 3.1 HTTP request rate
 
@@ -354,4 +354,4 @@ versions.
 
 ---
 
-*v1.0 — 2026-05-08. Tracks MNEMOS server v6.0.0*
+*v1.0 — 2026-05-08. Tracks MNEMOS server v6.0.1*
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
@@ -1,6 +1,6 @@
 # MNEMOS Operations — Multi-Node Deployment & Maintenance
 
-**Status:** Canonical (v6.0.0 production line, updated 2026-05-08)
+**Status:** Canonical (v6.0.1 production line, updated 2026-07-10)
 **Audience:** Operators, SREs, release engineers
 **Scope:** Continuous operation and maintenance of MNEMOS production + staging + test clusters
 
@@ -462,7 +462,7 @@ Response (JSON):
 ```json
 {
   "status": "healthy",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "profile": "server",
   "database_connected": true,
   "distillation_worker": "healthy"
@@ -918,6 +918,6 @@ sudo journalctl -u mnemos -f
 ---
 
 **Document version:** 1.0
-**Last updated:** 2026-05-08
+**Last updated:** 2026-07-10
 **Maintained by:** Operations team
-**Status:** Active, current for v6.0.0 production line
+**Status:** Active, current for v6.0.1 production line
diff --git a/docs/SPECIFICATION.md b/docs/SPECIFICATION.md
@@ -1,6 +1,6 @@
 # MNEMOS Specification
 
-**Version**: v6.0.0 current (split-distribution release; supersedes the v5.0.1 / v5.0.0
+**Version**: v6.0.1 current (patch release on the v6.0.0 split-distribution line; supersedes the v5.0.1 / v5.0.0
 GA line from 2026-05-02). Adds Oracle Database 26ai + IBM Db2 12.1.5 backends behind
 the EPIMONE `PersistenceBackend` ABC.
 
@@ -803,7 +803,7 @@ Plus non-`MNEMOS_`-prefixed standards: `GPU_PROVIDER_HOST`,
   application visibility after
   `db/migrations_v3_5_rls_group_select_unix_bits.sql`.
 
-### 10.4 Known gaps (as of v6.0.0)
+### 10.4 Known gaps (as of v6.0.1)
 
 - GDPR deletion requests can still hit the documented final-verify race or
   sweep-verifying exhaustion under sustained target writes; see
diff --git a/docs/STREAMING_REPLICATION.md b/docs/STREAMING_REPLICATION.md
@@ -206,7 +206,7 @@ the Patroni/HAProxy writer endpoint, not at individual PostgreSQL nodes.
 
 ## Live deployment: pg-host primary → gpu-host standby
 
-This section is the operator runbook for the **deployed fleet** as of v6.0.0
+This section is the operator runbook for the **deployed fleet** as of v6.0.1
 The sections above describe the generic pattern; this section names the actual
 hosts, ports, slot names, and commands.
 
diff --git a/docs/connectors/README.md b/docs/connectors/README.md
@@ -360,7 +360,7 @@ to it, we ship the fix as a PR. That's the contract.
 
 While `experimental`:
 
-- Endpoints under `/admin/tunnels/*` are **not implemented as of v6.0.0**;
+- Endpoints under `/admin/tunnels/*` are **not implemented as of v6.0.1**;
   the `mnemos-tunnel-setup` script that calls them is aspirational. They
   may be implemented, renamed, restructured, or withdrawn in any minor
   release. The manual `mnemos serve mcp-http` + ngrok path documented in
diff --git a/docs/connectors/chatgpt-pro-developer-mode.md b/docs/connectors/chatgpt-pro-developer-mode.md
@@ -180,7 +180,7 @@ conversation. Same memory is visible from your other agents.
 The `mnemos-tunnel-setup` helper (`scripts/mnemos_tunnel_setup.py`) is
 checked in as an aspirational contract. It expects a daemon-side
 `/admin/tunnels/*` REST surface plus a `mnemos.tunnels.ngrok_bridge`
-module; **neither has shipped as of v6.0.0** (verified in the repo).
+module; **neither has shipped as of v6.0.1** (verified in the repo).
 Use the manual path above. The snippet below describes the eventual
 flow:
 
diff --git a/docs/connectors/claude-code.md b/docs/connectors/claude-code.md
@@ -30,7 +30,7 @@ Merge into `~/.claude.json`. The MCP process runs on the remote host; `MNEMOS_BA
 
 ## Notes
 
-- Port 5002 is the unified API port (MNEMOS + GRAEAE) as of v6.0.0.x. Port 5001 is retired.
+- Port 5002 is the unified API port (MNEMOS + GRAEAE) as of v6.0.1. Port 5001 is retired.
 - `PYTHONPATH=/opt/mnemos` is required — the package is editable, not installed in venv site-packages.
 - `MNEMOS_API_KEY` must be in the SSH args via `/usr/bin/env`; Claude Code's `env` block is local-only and does not cross the SSH boundary.
 - GRAEAE MCP tool not yet registered — use `POST http://<mnemos-host>:5002/graeae/consult` with Bearer token as fallback.
diff --git a/docs/history/EVOLUTION.md b/docs/history/EVOLUTION.md
@@ -417,7 +417,7 @@ The settlement, landed in the v3.2 tail:
 
 - **APOLLO** (gpu_optional) — schema-aware dense encoding for
   LLM-to-LLM wire use. Portfolio, decision, person, event, code, and
-  commit schemas as of v6.0.0 LLM-fallback path covers anything that
+  commit schemas as of v6.0.1 LLM-fallback path covers anything that
   doesn't match a schema.
 - **ARTEMIS** (cpu_only) — extractive with identifier preservation,
   labeled-block handling, evidence-based self-scoring. Replaces
diff --git a/docs/observability/grafana/mnemos-overview.json b/docs/observability/grafana/mnemos-overview.json
@@ -1,5 +1,5 @@
 {
-  "__comment": "Grafana dashboard for the MNEMOS HTTP surface. Import via Grafana → Dashboards → Import → paste this JSON. Built against the metric names shipped by mnemos/core/observability.py as of v6.0.0 As more metrics land (compression queue, federation lag, NATS consumer pending), additional panels go in the dashboard via panel append; the layout reserves the right column for future surface coverage.",
+  "__comment": "Grafana dashboard for the MNEMOS HTTP surface. Import via Grafana → Dashboards → Import → paste this JSON. Built against the metric names shipped by mnemos/core/observability.py as of v6.0.1 As more metrics land (compression queue, federation lag, NATS consumer pending), additional panels go in the dashboard via panel append; the layout reserves the right column for future surface coverage.",
   "title": "MNEMOS — Overview",
   "uid": "mnemos-overview",
   "schemaVersion": 38,
diff --git a/mnemos/_version.py b/mnemos/_version.py
@@ -11,4 +11,4 @@
 caller imports — no install-state coupling.
 """
 
-__version__ = "6.0.0"
+__version__ = "6.0.1"
diff --git a/pyproject.toml b/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # Intentional split rename: the deploy unit is the built image, not a PyPI mnemos-os dist.
 name = "mnemos-core"
-version = "6.0.0"
+version = "6.0.1"
 description = "MNEMOS core: agent memory OS base with GDPR right-to-be-forgotten, PERSEPHONE archival, KRONOS recall observability, multi-backend persistence, and multi-worker support"
 readme = "README.md"
 requires-python = ">=3.11"
