memorix 1.9.1 → 1.9.3

package/dist/vector-backfill-runner.js

@@ -580,70 +580,79 @@ function getDatabase(dataDir) {
   loadBetterSqlite3();
   fs.mkdirSync(dataDir, { recursive: true });
   const dbPath = path3.join(dataDir, "memorix.db");
-  const db2 = createDatabase(dbPath);
-  db2.pragma("journal_mode = WAL");
-  db2.pragma("busy_timeout = 5000");
-  db2.pragma("foreign_keys = ON");
-  db2.exec(CREATE_OBSERVATIONS_TABLE);
-  db2.exec(CREATE_MINI_SKILLS_TABLE);
-  db2.exec(CREATE_SESSIONS_TABLE);
-  db2.exec(CREATE_META_TABLE);
-  db2.exec(CREATE_TEAM_AGENTS_TABLE);
-  db2.exec(CREATE_TEAM_TASKS_TABLE);
-  db2.exec(CREATE_TEAM_TASK_DEPS_TABLE);
-  db2.exec(CREATE_TEAM_MESSAGES_TABLE);
-  db2.exec(CREATE_TEAM_LOCKS_TABLE);
-  db2.exec(CREATE_TEAM_ROLES_TABLE);
-  db2.exec(CREATE_GRAPH_ENTITIES_TABLE);
-  db2.exec(CREATE_GRAPH_RELATIONS_TABLE);
-  db2.exec(CREATE_CHAT_TRANSCRIPT_TABLE);
-  db2.exec(CREATE_CODE_FILES_TABLE);
-  db2.exec(CREATE_CODE_SYMBOLS_TABLE);
-  db2.exec(CREATE_CODE_EDGES_TABLE);
-  db2.exec(CREATE_OBSERVATION_CODE_REFS_TABLE);
-  db2.exec(CREATE_MAINTENANCE_JOBS_TABLE);
-  db2.exec(CREATE_MAINTENANCE_TARGETS_TABLE);
-  db2.exec(CREATE_COMPACTION_CHECKPOINTS_TABLE);
+  let db2;
   try {
-    db2.exec(`ALTER TABLE mini_skills ADD COLUMN sourceSnapshot TEXT NOT NULL DEFAULT ''`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE mini_skills ADD COLUMN updatedAt TEXT`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE observations ADD COLUMN createdByAgentId TEXT`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE observations ADD COLUMN writeGeneration INTEGER DEFAULT 0`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE team_tasks ADD COLUMN required_role TEXT`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE team_tasks ADD COLUMN preferred_role TEXT`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE team_messages ADD COLUMN to_role TEXT`);
-  } catch {
-  }
-  try {
-    db2.exec(`ALTER TABLE team_messages ADD COLUMN handoff_status TEXT`);
-  } catch {
+    db2 = createDatabase(dbPath);
+    db2.pragma("busy_timeout = 5000");
+    db2.pragma("journal_mode = WAL");
+    db2.pragma("foreign_keys = ON");
+    db2.exec(CREATE_OBSERVATIONS_TABLE);
+    db2.exec(CREATE_MINI_SKILLS_TABLE);
+    db2.exec(CREATE_SESSIONS_TABLE);
+    db2.exec(CREATE_META_TABLE);
+    db2.exec(CREATE_TEAM_AGENTS_TABLE);
+    db2.exec(CREATE_TEAM_TASKS_TABLE);
+    db2.exec(CREATE_TEAM_TASK_DEPS_TABLE);
+    db2.exec(CREATE_TEAM_MESSAGES_TABLE);
+    db2.exec(CREATE_TEAM_LOCKS_TABLE);
+    db2.exec(CREATE_TEAM_ROLES_TABLE);
+    db2.exec(CREATE_GRAPH_ENTITIES_TABLE);
+    db2.exec(CREATE_GRAPH_RELATIONS_TABLE);
+    db2.exec(CREATE_CHAT_TRANSCRIPT_TABLE);
+    db2.exec(CREATE_CODE_FILES_TABLE);
+    db2.exec(CREATE_CODE_SYMBOLS_TABLE);
+    db2.exec(CREATE_CODE_EDGES_TABLE);
+    db2.exec(CREATE_OBSERVATION_CODE_REFS_TABLE);
+    db2.exec(CREATE_MAINTENANCE_JOBS_TABLE);
+    db2.exec(CREATE_MAINTENANCE_TARGETS_TABLE);
+    db2.exec(CREATE_COMPACTION_CHECKPOINTS_TABLE);
+    try {
+      db2.exec(`ALTER TABLE mini_skills ADD COLUMN sourceSnapshot TEXT NOT NULL DEFAULT ''`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE mini_skills ADD COLUMN updatedAt TEXT`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE observations ADD COLUMN createdByAgentId TEXT`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE observations ADD COLUMN writeGeneration INTEGER DEFAULT 0`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE team_tasks ADD COLUMN required_role TEXT`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE team_tasks ADD COLUMN preferred_role TEXT`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE team_messages ADD COLUMN to_role TEXT`);
+    } catch {
+    }
+    try {
+      db2.exec(`ALTER TABLE team_messages ADD COLUMN handoff_status TEXT`);
+    } catch {
+    }
+    applySchemaMigrations(db2);
+    db2.exec(CREATE_INDEXES);
+    initializeObservationLexicalIndex(db2);
+    db2.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('storage_generation', '0')`).run();
+    db2.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('next_id', '1')`).run();
+    db2.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('mini_skills_generation', '0')`).run();
+    _dbCache.set(normalized, db2);
+    return db2;
+  } catch (error) {
+    try {
+      db2?.close();
+    } catch {
+    }
+    throw error;
   }
-  applySchemaMigrations(db2);
-  db2.exec(CREATE_INDEXES);
-  initializeObservationLexicalIndex(db2);
-  db2.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('storage_generation', '0')`).run();
-  db2.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('next_id', '1')`).run();
-  db2.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('mini_skills_generation', '0')`).run();
-  _dbCache.set(normalized, db2);
-  return db2;
 }
 function closeAllDatabases() {
   for (const [key, db2] of _dbCache) {
@@ -1633,6 +1642,74 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_maintenance_jobs_active_dedupe
   }
 });
 
+// src/store/sqlite-reliability.ts
+function isTransientSqliteError(error) {
+  const code = error?.code;
+  if (typeof code === "string") {
+    return /^SQLITE_BUSY(?:_|$)/i.test(code);
+  }
+  return error instanceof Error && /\bdatabase is locked\b|\bdatabase is busy\b/i.test(error.message);
+}
+function isSqliteUnavailableError(error) {
+  return error instanceof SqliteUnavailableError || error instanceof Error && /SQLite is not available|better-sqlite3.*failed|node:sqlite.*failed|bun:sqlite.*failed/i.test(error.message);
+}
+function degradedReadError(storeName) {
+  return new Error(`[memorix] Cannot read ${storeName}: SQLite backend unavailable (memory is not loaded)`);
+}
+function degradedWriteError(storeName) {
+  return new Error(`[memorix] Cannot write ${storeName}: SQLite backend unavailable (degraded mode; read-only)`);
+}
+function formatSqliteFailure(error) {
+  return error instanceof Error && error.message ? error.message : String(error);
+}
+function delay(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function retrySqliteBusy(operation, label) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!isTransientSqliteError(error) || attempt >= SQLITE_BUSY_RETRY_DELAYS_MS.length) throw error;
+      const waitMs = SQLITE_BUSY_RETRY_DELAYS_MS[attempt];
+      console.error(
+        `[memorix] ${label} SQLite busy (attempt ${attempt + 1}/${SQLITE_BUSY_RETRY_DELAYS_MS.length + 1}), retrying in ${waitMs}ms`
+      );
+      await delay(waitMs);
+    }
+  }
+}
+async function initializeSqliteStore(factory, dataDir, label) {
+  try {
+    loadBetterSqlite3();
+  } catch (error) {
+    throw new SqliteUnavailableError(error);
+  }
+  return retrySqliteBusy(async () => {
+    const store = factory();
+    await store.init(dataDir);
+    return store;
+  }, label);
+}
+var SQLITE_BUSY_RETRY_DELAYS_MS, SqliteUnavailableError;
+var init_sqlite_reliability = __esm({
+  "src/store/sqlite-reliability.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_sqlite_db();
+    SQLITE_BUSY_RETRY_DELAYS_MS = [50, 150, 400, 1e3, 2500];
+    SqliteUnavailableError = class extends Error {
+      code = "MEMORIX_SQLITE_UNAVAILABLE";
+      constructor(cause) {
+        super(
+          cause instanceof Error && cause.message ? cause.message : "[memorix] SQLite is unavailable (install a supported SQLite runtime)"
+        );
+        this.name = "SqliteUnavailableError";
+      }
+    };
+  }
+});
+
 // src/store/file-lock.ts
 import { promises as fs2 } from "fs";
 import { randomUUID } from "crypto";
@@ -3556,10 +3633,10 @@ async function fetchWithRetry(url, apiKey, body, options = {}, attempt = 0, nati
       );
     }
     if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES2) {
-      const delay2 = BASE_DELAY_MS * Math.pow(2, attempt);
+      const delay3 = BASE_DELAY_MS * Math.pow(2, attempt);
       const retryAfter = response.headers.get("retry-after");
       const parsedRetryAfter = retryAfter ? parseInt(retryAfter, 10) * 1e3 : NaN;
-      const waitMs = Number.isFinite(parsedRetryAfter) ? parsedRetryAfter : delay2;
+      const waitMs = Number.isFinite(parsedRetryAfter) ? parsedRetryAfter : delay3;
       console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES2} in ${waitMs}ms`);
       await waitForRetry(waitMs, options.signal);
       return fetchWithRetry(url, apiKey, body, options, attempt + 1, nativeGemini);
@@ -5591,6 +5668,7 @@ var init_sqlite_store = __esm({
     "use strict";
     init_esm_shims();
     init_sqlite_db();
+    init_sqlite_reliability();
     init_sqlite_fts();
     SqliteBackend = class {
       db = null;
@@ -5868,7 +5946,9 @@ var init_sqlite_store = __esm({
       // ── Compound atomic operation ────────────────────────────────────
       async atomic(fn) {
         const run = this._atomicQueue.catch(() => void 0).then(async () => {
-          this.db.prepare("BEGIN IMMEDIATE").run();
+          await retrySqliteBusy(async () => {
+            this.db.prepare("BEGIN IMMEDIATE").run();
+          }, "Observation atomic write");
           try {
             const tx = {
               loadAll: async () => this.rawLoadAll(),
@@ -5967,15 +6047,15 @@ function resetObservationStore() {
 async function createObservationStore(dataDir) {
   try {
     const { SqliteBackend: SqliteBackend2 } = await Promise.resolve().then(() => (init_sqlite_store(), sqlite_store_exports));
-    const store2 = new SqliteBackend2();
-    await store2.init(dataDir);
-    return store2;
+    return await initializeSqliteStore(() => new SqliteBackend2(), dataDir, "Observation store");
   } catch (err) {
-    console.error(`[memorix] SQLite backend unavailable \u2014 degraded mode (read-only): ${err instanceof Error ? err.message : err}`);
+    if (!isSqliteUnavailableError(err)) throw err;
+    const reason = formatSqliteFailure(err);
+    console.error(`[memorix] SQLite module unavailable \u2014 degraded mode (reads/writes disabled): ${reason}`);
+    const degraded = new DegradedBackend(reason);
+    await degraded.init(dataDir);
+    return degraded;
   }
-  const store = new DegradedBackend();
-  await store.init(dataDir);
-  return store;
 }
 async function initObservationStore(dataDir) {
   if (_store2 && _storeDataDir === dataDir) {
@@ -5999,36 +6079,44 @@ var init_obs_store = __esm({
   "src/store/obs-store.ts"() {
     "use strict";
     init_esm_shims();
+    init_sqlite_reliability();
     _store2 = null;
     _storeDataDir = null;
     DegradedBackend = class {
+      constructor(reason = "SQLite runtime unavailable") {
+        this.reason = reason;
+      }
+      reason;
       dataDir = "";
+      unavailableRead() {
+        return degradedReadError("observations");
+      }
       async init(dataDir) {
         this.dataDir = dataDir;
       }
       async loadAll() {
-        return [];
+        throw this.unavailableRead();
       }
       async loadByProject(_projectId, _options) {
-        return [];
+        throw this.unavailableRead();
       }
       async countByProject(_projectId, _options) {
-        return 0;
+        throw this.unavailableRead();
       }
       async getById(_id) {
-        return void 0;
+        throw this.unavailableRead();
       }
       async loadIdCounter() {
-        return 1;
+        throw this.unavailableRead();
       }
       async countAll() {
-        return 0;
+        throw this.unavailableRead();
       }
       async listProjectIds() {
-        return [];
+        throw this.unavailableRead();
       }
       async searchLexical(_options) {
-        return [];
+        throw this.unavailableRead();
       }
       hasLexicalIndex() {
         return false;
@@ -6037,25 +6125,25 @@ var init_obs_store = __esm({
         return false;
       }
       async insert(_obs) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async update(_obs) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async remove(_id) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async bulkReplace(_obs) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async bulkRemoveByIds(_ids) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async saveIdCounter(_nextId) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async atomic(_fn) {
-        throw new Error("[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)");
+        throw degradedWriteError("observations");
       }
       async ensureFresh() {
         return false;
@@ -6068,6 +6156,9 @@ var init_obs_store = __esm({
       getBackendName() {
         return "degraded";
       }
+      getBackendReason() {
+        return this.reason;
+      }
     };
   }
 });
@@ -11716,7 +11807,8 @@ function clampCursor(afterId) {
 }
 async function loadConsolidationPage(projectId, options) {
   const limit2 = clampBatchSize(options.limit);
-  const page = await getObservationStore().loadByProject(projectId, {
+  const store = options.store ?? getObservationStore();
+  const page = await store.loadByProject(projectId, {
     status: "active",
     afterId: clampCursor(options.afterId),
     limit: limit2 + 1
@@ -11776,7 +11868,7 @@ async function findConsolidationCandidates(_projectDir, projectId, opts) {
   return findClusters(page.observations, threshold);
 }
 async function executeConsolidation(_projectDir, projectId, opts) {
-  const store = getObservationStore();
+  const store = opts?.store ?? getObservationStore();
   const page = await loadConsolidationPage(projectId, opts ?? {});
   const clusters = findClusters(page.observations, opts?.threshold ?? DEFAULT_SIMILARITY_THRESHOLD);
   if (clusters.length === 0) {
@@ -57602,10 +57694,10 @@ var require_retry3 = __commonJS({
       if (!await shouldRetryFn(err)) {
         return { shouldRetry: false, config: err.config };
       }
-      const delay2 = getNextRetryDelay(config);
+      const delay3 = getNextRetryDelay(config);
       err.config.retryConfig.currentRetryAttempt += 1;
-      const backoff = config.retryBackoff ? config.retryBackoff(err, delay2) : new Promise((resolve2) => {
-        setTimeout(resolve2, delay2);
+      const backoff = config.retryBackoff ? config.retryBackoff(err, delay3) : new Promise((resolve2) => {
+        setTimeout(resolve2, delay3);
       });
       if (config.onRetryAttempt) {
         await config.onRetryAttempt(err);
@@ -99391,7 +99483,7 @@ async function retryBackoff(fn, strategy) {
         retryInterval = initialInterval * Math.pow(x2, exponent) + Math.random() * 1e3;
       }
       const d = Math.min(retryInterval, maxInterval);
-      await delay(d);
+      await delay2(d);
       x2++;
     }
   }
@@ -99412,8 +99504,8 @@ function retryIntervalFromResponse(res) {
   }
   return 0;
 }
-async function delay(delay2) {
-  return new Promise((resolve2) => setTimeout(resolve2, delay2));
+async function delay2(delay3) {
+  return new Promise((resolve2) => setTimeout(resolve2, delay3));
 }
 var defaultBackoff, PermanentError, TemporaryError, codeRangeRE2;
 var init_retries = __esm({
@@ -148353,7 +148445,7 @@ __export(lite_provider_exports, {
   refreshProjectLite: () => refreshProjectLite
 });
 import { createHash as createHash10 } from "crypto";
-import { readdirSync as readdirSync2, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
+import { existsSync as existsSync11, readdirSync as readdirSync2, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
 import { join as join4, relative as relative2 } from "path";
 function hashText2(text2) {
   return createHash10("sha256").update(text2).digest("hex");
@@ -148370,6 +148462,9 @@ function resolveMaxFileBytes(value) {
   if (!Number.isFinite(value)) return DEFAULT_CODEGRAPH_MAX_FILE_BYTES;
   return Math.max(1, Math.floor(value));
 }
+function isPythonVirtualenvDir(dir) {
+  return existsSync11(join4(dir, "pyvenv.cfg"));
+}
 function walk(root, exclude, maxFiles) {
   const out = [];
   const visit = (dir) => {
@@ -148387,6 +148482,7 @@ function walk(root, exclude, maxFiles) {
       if (entry.isDirectory()) {
         if (entry.name === ".git" || entry.name === ".worktrees" || entry.name === ".tmp" || entry.name === "node_modules") continue;
         if (rel === ".claude/worktrees" || rel.startsWith(".claude/worktrees/")) continue;
+        if (isPythonVirtualenvDir(abs)) continue;
         visit(abs);
         if (out.length >= maxFiles) return;
         continue;
@@ -151749,7 +151845,7 @@ __export(vector_backfill_runner_exports, {
 import { spawn as spawn3 } from "child_process";
 import {
   closeSync,
-  existsSync as existsSync11,
+  existsSync as existsSync12,
   mkdirSync as mkdirSync2,
   openSync,
   readFileSync as readFileSync9,
@@ -151877,7 +151973,7 @@ function releaseVectorBackfillLock(lockPath = process.env.MEMORIX_VECTOR_BACKFIL
 }
 function launchDetachedVectorBackfill(request, options = {}) {
   const runnerPath = options.runnerPath ?? resolveVectorBackfillRunnerPath();
-  const exists = options.exists ?? existsSync11;
+  const exists = options.exists ?? existsSync12;
   if (!exists(runnerPath)) return false;
   const lock = acquireVectorBackfillLock(request.dataDir, request.projectId, options.lockPath);
   if (!lock) return false;

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -792,6 +792,21 @@ not a memory-loss condition. If Memorix instead reports that SQLite is
 unavailable, confirm the installed Node version satisfies the package engine
 and include the exact error when filing an issue.
 
+## 10. Does `doctor` report degraded or unavailable storage?
+
+Treat this as a real storage failure, not as an empty project. The active
+SQLite backend is the source of truth for observations, sessions, and
+mini-skills; derived search indexes may fall back, but they must not hide a
+database failure.
+
+Run `memorix doctor --json` and keep the reported error. A transient
+cross-process `SQLITE_BUSY` is retried automatically. A persistent runtime
+error is surfaced instead of returning empty memory. Stop or pause a long
+maintenance operation and retry after the database is writable. For several
+agent harnesses sharing one local store, prefer one `memorix background start`
+control plane so writes are serialized by one owner; WAL does not allow
+multiple simultaneous writers.
+
 ---
 
 ## 11. What Not to Do

package/docs/ARCHITECTURE.md

@@ -150,6 +150,29 @@ Responsibilities:
 - curate long-lived episodes, facts, and procedures with source evidence,
   qualification, approval, archival, and supersession
 
+### Persistence Contract
+
+SQLite is the canonical local record for observations, sessions, mini-skills,
+knowledge, coordination, and CodeGraph metadata. Search indexes and in-memory
+structures are derived views and may be rebuilt; they must never decide that a
+failed database is an empty project.
+
+All SQLite-backed stores share the same startup semantics:
+
+1. A missing SQLite runtime is reported as an explicit degraded backend.
+2. Cross-process `SQLITE_BUSY` contention is retried with bounded backoff.
+3. Persistent runtime failures are thrown and surfaced to the operator.
+4. Degraded business reads and writes fail clearly instead of returning empty
+   data or a fake success.
+5. A connection that fails during schema/index initialization is closed before
+   a retry, so a failed startup cannot retain a file lock.
+
+WAL improves reader/writer overlap but still permits one writer per database
+file. Long maintenance work is therefore isolated and paged, while write
+transactions stay short. Multi-agent installations should prefer one local
+HTTP control plane as the database owner; stdio remains useful for a single
+agent or a deliberately isolated project store.
+
 ### Intelligence and Quality Layer
 
 This layer improves memory quality and retrieval quality.

package/docs/DEVELOPMENT.md

@@ -13,7 +13,7 @@ Memorix is a TypeScript project built around:
 
 ## Current Development Baseline
 
-The current release line is **1.9.1** and package metadata is kept synchronized
+The current release line is **1.9.3** and package metadata is kept synchronized
 with the root package and MCP Registry manifest.
 
 Contributors should assume the following areas are part of the current release line:

package/docs/INTEGRATIONS.md

@@ -122,6 +122,10 @@ If an agent only needs a raw stdio MCP entry:
 
 Avoid `npx` in persistent MCP configs. Use the globally installed `memorix` binary so startup is predictable.
 
+For npm-based MCP clients or registry testers, the complete package command is
+`npx -y memorix serve`. Do not omit `serve`: bare `memorix` is the interactive
+memcode entry in a human terminal.
+
 For HTTP mode:
 
 ```bash

package/docs/PERFORMANCE.md

@@ -43,6 +43,34 @@ user is allowed to remember.
   memory, and the V8 heap limit so a real saturation report can distinguish
   JavaScript retention from native/model memory.
 
+## SQLite Storage Reliability Contract
+
+SQLite is the durable source of truth. FTS5, Orama, vector indexes, and other
+search structures are derived working indexes; an index failure must never turn
+the durable store into an empty project.
+
+- A missing SQLite runtime may use the explicit read-only degraded backend.
+- A runtime lock (`SQLITE_BUSY`) is retried with bounded backoff. A persistent
+  runtime error is surfaced to the caller; it is never converted into a fake
+  successful read or write.
+- Observations, sessions, and mini-skills follow the same initialization rule.
+  Degraded writes fail loudly so an agent cannot believe a session or promotion
+  was saved when it was not.
+- SQLite connections configure `busy_timeout` before WAL setup. A connection
+  that fails during schema or index initialization is closed before retrying,
+  so a failed startup cannot leave an orphan lock behind.
+- WAL permits concurrent readers but still has one writer. Maintenance and
+  migration work must use short, bounded transactions and must not perform
+  network or LLM work while holding a write transaction. For several agent
+  harnesses, prefer one local `serve-http` control plane so writes are queued
+  by one owner instead of many stdio processes competing for one file.
+- `memorix doctor` reports the active backend. It reports read-only or
+  unavailable storage as an error and never presents the backend's synthetic
+  zero count as an empty project.
+
+This is an integrity boundary, not a corpus quota. The product does not lower
+the number of durable memories to hide lock contention or resource problems.
+
 ## Retrieval Profiles
 
 | Profile | Default? | Network work | Best fit |
@@ -163,6 +191,28 @@ Results are machine-specific and should be compared on the same OS and Node
 version. The release gate is an integrity and regression check, not a public
 latency guarantee.
 
+### 1.9.3 Release Evidence (2026-09-14)
+
+The 40,000-record gate passed on Windows with Node `v22.22.3`, SQLite-backed
+storage, and embeddings disabled:
+
+| Measurement | Result |
+| --- | ---: |
+| Seed and index | 48.9 s |
+| Steady-state write p50 / p95 | 0.78 / 1.49 ms |
+| SDK lexical search | 22.8 ms |
+| HTTP ready | 1.87 s |
+| MCP initialize / bind | 116 / 229 ms |
+| MCP context / search / store | 605 / 322 / 595 ms |
+| Hook write | 3.36 s |
+| SDK reopen | 134 ms |
+| Service peak RSS | 412.7 MiB |
+| Durable records after MCP and hook writes | 40,002 |
+
+The planted record was searchable, the MCP and hook writes were durable, and
+the reopened SDK observed the project-visible records. These values are local
+acceptance evidence, not cross-machine performance promises.
+
 ## 1.9.1 Large-Scale Retrieval Contract
 
 The 1.9.1 line improves retrieval latency without shrinking the user's durable

package/docs/README.md

@@ -125,7 +125,7 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The current product line is **1.9.1**. Multi-device store sync is opt-in and
+The current product line is **1.9.3**. Multi-device store sync is opt-in and
 keeps local SQLite canonical; existing users do not upload anything until they
 configure a relay provider explicitly.
 The authoritative acceptance contract for the current implementation is

package/docs/SETUP.md

@@ -170,6 +170,11 @@ Generic stdio MCP config:
 
 Avoid `npx` in persistent MCP configs. Use the globally installed `memorix` binary so startup is predictable.
 
+When an npm-based MCP client or registry tester must launch the package
+directly, use `npx -y memorix serve`. The explicit `serve` argument selects
+the stdio MCP server; a human running bare `memorix` in a terminal gets the
+bundled memcode agent instead.
+
 ### Option C: memcode terminal agent
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -77,7 +77,6 @@
     "benchmark:codegraph:scale": "node scripts/benchmark-codegraph-scale.mjs",
     "benchmark:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
     "gate:large-store": "npm run build && node scripts/large-store-gate.mjs",
-    "generate:star-history": "node scripts/generate-star-history.mjs",
     "sync:mcp-registry": "node scripts/sync-mcp-registry-manifest.mjs",
     "check:mcp-registry": "node scripts/check-mcp-registry-manifest.mjs",
     "sync:plugin-release": "node scripts/sync-plugin-release-manifests.mjs",

package/plugins/antigravity/memorix/plugin.json

@@ -1,4 +1,4 @@
 {
   "name": "memorix",
-  "version": "1.9.1"
+  "version": "1.9.3"
 }

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",