superlocalmemory 3.4.19 → 3.4.21

package/src/superlocalmemory/storage/migrations/M002_model_state_history.py

@@ -0,0 +1,132 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-07 §3.2
+
+"""M002 — rebuild learning_model_state without UNIQUE(profile_id).
+
+Enables shadow testing (old + new model live side-by-side). SQLite cannot
+drop a UNIQUE constraint directly, so we use the new-table-rename pattern
+wrapped in a single transaction. Existing rows are copied forward and
+marked ``is_active = 1``.
+
+SEC-02-02: ``bytes_sha256`` integrity column added. The daemon will
+compute and verify this on every load to block corrupted model BLOBs from
+reaching the LightGBM deserialiser.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+
+NAME = "M002_model_state_history"
+DB_TARGET = "learning"
+
+_REQUIRED_COLS = frozenset({
+    "model_version", "bytes_sha256", "trained_on_count",
+    "feature_names", "metrics_json", "is_active",
+    "trained_at", "updated_at",
+})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return True if the rebuilt model_state schema is in place."""
+    try:
+        cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(learning_model_state)"
+        ).fetchall()}
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_COLS <= cols
+
+
+# S9-W1 M-DATA-01: prior version of this migration hardcoded ``is_active=1``
+# for every copied row. v3.4.19 mainline has ``UNIQUE(profile_id)`` which
+# guarantees one row per profile so the hardcode worked — but a non-mainline
+# dev-build could have multiple rows and the partial unique index created
+# after rebuild would fail transactionally. We now mark only the row with
+# the MAX(id) per profile as active; everything else becomes history.
+DDL = """
+BEGIN IMMEDIATE;
+
+CREATE TABLE learning_model_state_new (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id        TEXT NOT NULL,
+    model_version     TEXT NOT NULL DEFAULT '3.4.21',
+    state_bytes       BLOB NOT NULL,
+    bytes_sha256      TEXT NOT NULL DEFAULT '',
+    trained_on_count  INTEGER NOT NULL DEFAULT 0,
+    feature_names     TEXT NOT NULL DEFAULT '[]',
+    metrics_json      TEXT NOT NULL DEFAULT '{}',
+    is_active         INTEGER NOT NULL DEFAULT 0,
+    trained_at        TEXT NOT NULL,
+    updated_at        TEXT NOT NULL
+);
+
+INSERT INTO learning_model_state_new
+    (profile_id, state_bytes, is_active, trained_at, updated_at)
+SELECT lms.profile_id, lms.state_bytes,
+       CASE WHEN lms.id = (
+             SELECT MAX(lms2.id)
+             FROM learning_model_state lms2
+             WHERE lms2.profile_id = lms.profile_id
+           ) THEN 1 ELSE 0 END,
+       lms.updated_at, lms.updated_at
+FROM learning_model_state lms;
+
+DROP TABLE learning_model_state;
+ALTER TABLE learning_model_state_new RENAME TO learning_model_state;
+
+CREATE UNIQUE INDEX idx_model_active
+    ON learning_model_state(profile_id)
+    WHERE is_active = 1;
+
+CREATE INDEX idx_model_profile_time
+    ON learning_model_state(profile_id, trained_at);
+
+COMMIT;
+"""
+
+
+def post_ddl_hook(conn: sqlite3.Connection) -> None:
+    """S9-W1 H-DATA-01: backfill ``bytes_sha256`` for every row copied forward.
+
+    The DDL INSERT could not list ``bytes_sha256`` because SQLite cannot
+    call a Python function inside an ``executescript`` block unless the
+    function is registered beforehand, and registering a UDF mid-DDL is
+    fragile. Instead, we run one UPDATE pass after the DDL commits.
+
+    Without this backfill, ``model_cache._parse_row`` calls
+    ``verify_sha256(state_bytes, '')`` which raises IntegrityError, the
+    parser tombstones the cache entry, and EVERY 18,000+ user who had a
+    trained model on v3.4.19 loses usable learned-ranker state on upgrade.
+
+    The fix is safe: SHA-256 of the already-persisted blob is
+    deterministic, adds <1 ms per profile, and never alters
+    ``state_bytes``. Runs inside the same connection so any UPDATE error
+    surfaces to the runner as ``post_ddl_hook`` failed.
+    """
+    try:
+        rows = conn.execute(
+            "SELECT id, state_bytes FROM learning_model_state "
+            "WHERE bytes_sha256 = '' OR bytes_sha256 IS NULL"
+        ).fetchall()
+    except sqlite3.Error:
+        return  # table empty or schema not yet present — nothing to do.
+
+    if not rows:
+        return
+
+    updates = []
+    for row_id, state_bytes in rows:
+        if state_bytes is None:
+            continue
+        sha = hashlib.sha256(state_bytes).hexdigest()
+        updates.append((sha, row_id))
+
+    if updates:
+        conn.executemany(
+            "UPDATE learning_model_state SET bytes_sha256 = ? WHERE id = ?",
+            updates,
+        )
+        conn.commit()

package/src/superlocalmemory/storage/migrations/M003_migration_log.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-07 §3.3
+
+"""M003 — bootstrap migration_log table.
+
+Runs FIRST on both DBs. Purely idempotent ``CREATE TABLE IF NOT EXISTS``.
+No transaction needed — a single DDL statement on SQLite is atomic.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M003_migration_log"
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return True if migration_log already exists with expected columns."""
+    try:
+        cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(migration_log)"
+        ).fetchall()}
+    except sqlite3.Error:
+        return False
+    return {"name", "applied_at", "ddl_sha256",
+            "rows_affected", "status"} <= cols
+DB_TARGET = "learning"  # Also gets replicated to memory DB by the runner.
+
+DDL = """
+CREATE TABLE IF NOT EXISTS migration_log (
+    name           TEXT PRIMARY KEY,
+    applied_at     TEXT NOT NULL,
+    ddl_sha256     TEXT NOT NULL,
+    rows_affected  INTEGER NOT NULL DEFAULT 0,
+    status         TEXT NOT NULL
+);
+"""

package/src/superlocalmemory/storage/migrations/M004_cross_platform_sync_log.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-07 §3.4
+
+"""M004 — cross-platform adapter sync log (memory.db).
+
+LLD-05 requirement. SEC-05-04: stores target paths as SHA-256 digests, not
+raw strings — keeps plaintext filesystem paths out of the DB. A separate
+``target_basename`` column keeps the last path segment for the dashboard
+without exposing the full path.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M004_cross_platform_sync_log"
+DB_TARGET = "memory"
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return True if cross_platform_sync_log table is in place."""
+    try:
+        cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(cross_platform_sync_log)"
+        ).fetchall()}
+    except sqlite3.Error:
+        return False
+    return {"adapter_name", "profile_id", "target_path_sha256",
+            "target_basename", "last_sync_at", "bytes_written",
+            "content_sha256", "success"} <= cols
+
+DDL = """
+CREATE TABLE IF NOT EXISTS cross_platform_sync_log (
+    adapter_name       TEXT NOT NULL,
+    profile_id         TEXT NOT NULL,
+    target_path_sha256 TEXT NOT NULL,
+    target_basename    TEXT NOT NULL,
+    last_sync_at       TEXT NOT NULL,
+    bytes_written      INTEGER NOT NULL,
+    content_sha256     TEXT NOT NULL,
+    success            INTEGER NOT NULL,
+    error_msg          TEXT,
+    PRIMARY KEY (adapter_name, target_path_sha256)
+);
+"""

package/src/superlocalmemory/storage/migrations/M005_bandit_tables.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-07 §3.5
+
+"""M005 — Thompson-sampling bandit tables (learning.db, LLD-03).
+
+Two tables:
+  - ``bandit_arms`` — per (profile, stratum, arm) Beta-distribution state.
+    ``WITHOUT ROWID`` since primary key is a natural composite.
+  - ``bandit_plays`` — individual play events with delayed-reward settlement.
+
+All indexes are ``IF NOT EXISTS`` so reapply is a no-op.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M005_bandit_tables"
+DB_TARGET = "learning"
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return True if bandit tables exist with expected columns."""
+    try:
+        arms_cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(bandit_arms)"
+        ).fetchall()}
+        plays_cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(bandit_plays)"
+        ).fetchall()}
+    except sqlite3.Error:
+        return False
+    return (
+        {"profile_id", "stratum", "arm_id", "alpha",
+         "beta", "plays"} <= arms_cols
+        and {"play_id", "profile_id", "query_id", "stratum",
+             "arm_id", "played_at"} <= plays_cols
+    )
+
+DDL = """
+CREATE TABLE IF NOT EXISTS bandit_arms (
+    profile_id      TEXT NOT NULL,
+    stratum         TEXT NOT NULL,
+    arm_id          TEXT NOT NULL,
+    alpha           REAL NOT NULL DEFAULT 1.0,
+    beta            REAL NOT NULL DEFAULT 1.0,
+    plays           INTEGER NOT NULL DEFAULT 0,
+    last_played_at  TEXT,
+    PRIMARY KEY (profile_id, stratum, arm_id)
+) WITHOUT ROWID;
+
+CREATE INDEX IF NOT EXISTS idx_bandit_profile_strat
+    ON bandit_arms(profile_id, stratum);
+
+CREATE TABLE IF NOT EXISTS bandit_plays (
+    play_id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id       TEXT NOT NULL,
+    query_id         TEXT NOT NULL,
+    stratum          TEXT NOT NULL,
+    arm_id           TEXT NOT NULL,
+    played_at        TEXT NOT NULL,
+    reward           REAL,
+    settled_at       TEXT,
+    settlement_type  TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_plays_query
+    ON bandit_plays(query_id);
+CREATE INDEX IF NOT EXISTS idx_plays_unsettled
+    ON bandit_plays(profile_id, played_at)
+    WHERE settled_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_plays_retention
+    ON bandit_plays(settled_at);
+"""

package/src/superlocalmemory/storage/migrations/M006_action_outcomes_reward.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-07 §3.6
+
+"""M006 — action_outcomes reward + settlement columns (memory.db).
+
+Extends ``action_outcomes`` with the four columns the learning trainer
+needs in order to swap off the position proxy onto the real reward
+label:
+
+  * ``reward REAL`` — numeric reward (usually in [-1, 1]).
+  * ``settled INTEGER DEFAULT 0`` — 1 when the outcome has been settled.
+  * ``settled_at TEXT`` — ISO-8601 timestamp of settlement.
+  * ``recall_query_id TEXT`` — links the outcome back to the recall that
+    produced the candidate facts (so the trainer can join against
+    ``learning_signals.query_id``).
+
+The gate in ``learning.database.fetch_training_examples``
+(``_migration_applied("M006_action_outcomes_reward")``) already falls
+back to the position proxy when this migration hasn't completed, so a
+skipped/failed apply never crashes the trainer.
+
+Deferred: this migration is NOT in ``MIGRATIONS``. It ships via
+``DEFERRED_MIGRATIONS`` and runs from the daemon lifespan immediately
+after ``MemoryEngine.initialize()`` has bootstrapped the
+``action_outcomes`` table. Idempotent — ``verify(conn)`` returns True
+once all four columns are present, so reapply is a no-op.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M006_action_outcomes_reward"
+# action_outcomes lives in memory.db (see storage.schema).
+DB_TARGET = "memory"
+
+_REQUIRED_COLS = frozenset({"reward", "settled", "settled_at", "recall_query_id"})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    """Return True once every M006 column is present on ``action_outcomes``.
+
+    Lets the migration runner detect "already applied" state when a retry
+    would otherwise hit a duplicate-column error mid-script.
+    """
+    try:
+        cols = {
+            r[1]
+            for r in conn.execute("PRAGMA table_info(action_outcomes)").fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_COLS.issubset(cols)
+
+
+# DDL. Runs inside an explicit transaction opened by the migration runner.
+# SQLite doesn't support ``ALTER TABLE IF EXISTS`` — if the table is missing
+# this raises sqlite3.OperationalError which the runner catches and records
+# as ``failed``; the gate in ``fetch_training_examples`` keeps the trainer
+# on the position proxy in that case, so the daemon is still healthy.
+DDL = """
+ALTER TABLE action_outcomes ADD COLUMN reward REAL;
+ALTER TABLE action_outcomes ADD COLUMN settled INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE action_outcomes ADD COLUMN settled_at TEXT;
+ALTER TABLE action_outcomes ADD COLUMN recall_query_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_action_outcomes_settled_reward
+    ON action_outcomes(settled, settled_at)
+    WHERE reward IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_action_outcomes_recall_query
+    ON action_outcomes(recall_query_id)
+    WHERE recall_query_id IS NOT NULL;
+"""

package/src/superlocalmemory/storage/migrations/M007_pending_outcomes.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-00 §1.2 + LLD-08
+
+"""M007 — pending_outcomes table (memory.db).
+
+LLD-00 §1.2 makes ``pending_outcomes`` the single source of truth for
+in-flight recall outcomes awaiting reward settlement. An earlier draft
+split pending state across a cache.db table which has been retired
+(see LLD-00 §1.2 for the name of the predecessor). All pending rows
+are now crash-safe, profile-scoped, and one-row-per-recall — signals
+live in the ``signals_json`` blob, not separate rows.
+
+Target DB: memory.db. Schema follows LLD-00 §1.2 verbatim. Idempotent:
+``verify(conn)`` returns True once every required column is present on
+the ``pending_outcomes`` table.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M007_pending_outcomes"
+DB_TARGET = "memory"
+
+_REQUIRED_COLS = frozenset({
+    "outcome_id", "profile_id", "session_id", "recall_query_id",
+    "fact_ids_json", "query_text_hash", "created_at_ms", "expires_at_ms",
+    "signals_json", "status",
+})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        cols = {
+            r[1]
+            for r in conn.execute(
+                "PRAGMA table_info(pending_outcomes)"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_COLS.issubset(cols)
+
+
+DDL = """
+CREATE TABLE IF NOT EXISTS pending_outcomes (
+    outcome_id       TEXT PRIMARY KEY,
+    profile_id       TEXT NOT NULL,
+    session_id       TEXT NOT NULL,
+    recall_query_id  TEXT NOT NULL,
+    fact_ids_json    TEXT NOT NULL,
+    query_text_hash  TEXT NOT NULL,
+    created_at_ms    INTEGER NOT NULL,
+    expires_at_ms    INTEGER NOT NULL,
+    signals_json     TEXT NOT NULL DEFAULT '{}',
+    status           TEXT NOT NULL DEFAULT 'pending'
+);
+CREATE INDEX IF NOT EXISTS idx_pending_profile_expires
+    ON pending_outcomes(profile_id, expires_at_ms);
+CREATE INDEX IF NOT EXISTS idx_pending_status
+    ON pending_outcomes(status, expires_at_ms);
+"""

package/src/superlocalmemory/storage/migrations/M009_model_lineage.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-00 §1.3 + LLD-10
+
+"""M009 — learning_model_state lineage columns (learning.db).
+
+LLD-10 online retrain + shadow test + auto-rollback needs to track
+three models concurrently: the live active model, the previously
+active (for rollback), and a candidate under A/B shadow validation.
+
+This migration extends ``learning_model_state`` (created by M002) with
+six additive columns and two partial unique indexes that enforce
+single-active + single-candidate per profile. All additive — no
+existing behaviour changes.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M009_model_lineage"
+DB_TARGET = "learning"
+
+_REQUIRED_COLS = frozenset({
+    "is_previous", "is_rollback", "is_candidate",
+    "shadow_results_json", "promoted_at", "rollback_reason",
+})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        cols = {
+            r[1]
+            for r in conn.execute(
+                "PRAGMA table_info(learning_model_state)"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_COLS.issubset(cols)
+
+
+DDL = """
+ALTER TABLE learning_model_state ADD COLUMN is_previous INTEGER DEFAULT 0;
+ALTER TABLE learning_model_state ADD COLUMN is_rollback INTEGER DEFAULT 0;
+ALTER TABLE learning_model_state ADD COLUMN is_candidate INTEGER DEFAULT 0;
+ALTER TABLE learning_model_state ADD COLUMN shadow_results_json TEXT;
+ALTER TABLE learning_model_state ADD COLUMN promoted_at TEXT;
+ALTER TABLE learning_model_state ADD COLUMN rollback_reason TEXT;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_model_active_one
+    ON learning_model_state(profile_id) WHERE is_active=1;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_model_candidate_one
+    ON learning_model_state(profile_id) WHERE is_candidate=1;
+"""

package/src/superlocalmemory/storage/migrations/M010_evolution_config.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-00 §1.6 + LLD-11
+
+"""M010 — evolution_config + evolution_llm_cost_log tables (learning.db).
+
+LLD-11 skill evolution is opt-in by default (MASTER-PLAN D3). This
+migration creates the two tables the evolution subsystem needs:
+
+- ``evolution_config`` — per-profile feature flag + LLM backend choice.
+  The default row is created lazily by the installer; this migration
+  only creates the table so the installer's INSERT can land.
+- ``evolution_llm_cost_log`` — every LLM call the evolution cycle makes
+  is logged here so the cost-accounting widget on the dashboard can
+  report tokens + USD spend.
+
+Target DB: learning.db. Additive only.
+
+SEC-L2 — ``cost_usd`` is IEEE-754 REAL (double). This loses precision
+when summing thousands of sub-cent rows (rounding drift < 0.5 ¢ per
+10k rows in practice). The schema is additive and therefore locked
+for v3.4.21 — dashboards MUST compute aggregate cost as
+``SUM(cost_usd)`` with explicit ``ROUND(x, 4)`` at display time, and
+MUST NOT branch on sub-cent equality. A follow-on migration is
+scheduled to switch the column to INTEGER millicents (see FINAL
+board). The ``cost_usd >= 0`` non-negativity invariant is enforced
+application-side by ``evolution.llm_dispatch._log_cost``.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M010_evolution_config"
+DB_TARGET = "learning"
+
+_REQUIRED_TABLES = frozenset({"evolution_config", "evolution_llm_cost_log"})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        names = {
+            r[0]
+            for r in conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_TABLES.issubset(names)
+
+
+DDL = """
+CREATE TABLE IF NOT EXISTS evolution_config (
+    profile_id        TEXT PRIMARY KEY,
+    enabled           INTEGER NOT NULL DEFAULT 0,
+    llm_backend       TEXT NOT NULL DEFAULT 'haiku',
+    llm_model         TEXT NOT NULL DEFAULT 'claude-haiku-4-5',
+    last_cycle_at     TEXT,
+    cycles_this_week  INTEGER NOT NULL DEFAULT 0,
+    disabled_until    TEXT
+);
+CREATE TABLE IF NOT EXISTS evolution_llm_cost_log (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id    TEXT NOT NULL,
+    ts            TEXT NOT NULL,
+    model         TEXT NOT NULL,
+    tokens_in     INTEGER NOT NULL DEFAULT 0,
+    tokens_out    INTEGER NOT NULL DEFAULT 0,
+    cost_usd      REAL NOT NULL DEFAULT 0.0,
+    cycle_id      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_cost_profile_ts
+    ON evolution_llm_cost_log(profile_id, ts);
+"""

package/src/superlocalmemory/storage/migrations/M011_archive_and_merge.py

@@ -0,0 +1,87 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-00 §1.4 + LLD-12
+
+"""M011 — archive + merge log (memory.db, DEFERRED).
+
+LLD-12 real consolidation uses hnswlib to find near-duplicate atomic
+facts, then archives or merges them reversibly. This migration:
+
+- Extends ``atomic_facts`` with four lifecycle columns:
+    * ``archive_status`` — 'live' | 'archived' | 'merged'
+    * ``archive_reason`` — tag explaining why (cosine_dup, reward_gate, ...)
+    * ``merged_into`` — fact_id of the canonical survivor when merged
+    * ``retrieval_prior`` — reward-derived boost factor used by ranker
+- Creates ``memory_archive`` — payload-preserving archive table.
+  Consolidation NEVER deletes from atomic_facts; it only flips status
+  and writes a payload snapshot here.
+- Creates ``memory_merge_log`` — merge decisions are reversible via
+  ``slm memory unmerge <merge_id>``. Records the canonical + duplicate
+  fact_ids plus the cosine + jaccard scores that drove the merge.
+
+Deferred like M006 — ``atomic_facts`` is bootstrapped at engine init,
+not by the migration runner. DEFERRED_MIGRATIONS runs after
+``MemoryEngine.initialize()``.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M011_archive_and_merge"
+DB_TARGET = "memory"
+
+_REQUIRED_ATOMIC = frozenset({
+    "archive_status", "archive_reason", "merged_into", "retrieval_prior",
+})
+_REQUIRED_TABLES = frozenset({"memory_archive", "memory_merge_log"})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        atomic_cols = {
+            r[1]
+            for r in conn.execute(
+                "PRAGMA table_info(atomic_facts)"
+            ).fetchall()
+        }
+        names = {
+            r[0]
+            for r in conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_ATOMIC.issubset(atomic_cols) and _REQUIRED_TABLES.issubset(names)
+
+
+DDL = """
+ALTER TABLE atomic_facts ADD COLUMN archive_status TEXT DEFAULT 'live';
+ALTER TABLE atomic_facts ADD COLUMN archive_reason TEXT;
+ALTER TABLE atomic_facts ADD COLUMN merged_into TEXT;
+ALTER TABLE atomic_facts ADD COLUMN retrieval_prior REAL DEFAULT 0.0;
+
+CREATE TABLE IF NOT EXISTS memory_archive (
+    archive_id    TEXT PRIMARY KEY,
+    fact_id       TEXT NOT NULL,
+    profile_id    TEXT NOT NULL,
+    payload_json  TEXT NOT NULL,
+    archived_at   TEXT NOT NULL,
+    reason        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_archive_profile
+    ON memory_archive(profile_id, archived_at);
+
+CREATE TABLE IF NOT EXISTS memory_merge_log (
+    merge_id          TEXT PRIMARY KEY,
+    profile_id        TEXT NOT NULL,
+    canonical_fact_id TEXT NOT NULL,
+    merged_fact_id    TEXT NOT NULL,
+    cosine_sim        REAL,
+    entity_jaccard    REAL,
+    merged_at         TEXT NOT NULL,
+    reversible        INTEGER DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS idx_merge_profile ON memory_merge_log(profile_id);
+"""