@unblocklabs/unblock-memory 0.3.19 → 0.3.21

package/README.md

@@ -1,5 +1,28 @@
 # Unblock Memory
 
+## Hybrid search (`memory_xsearch`, opt-in)
+
+`memory_search` remains vector-only. Enable `memory_xsearch` to combine vector
+and BM25 retrieval, then independently score complete source excerpts with
+TypeSafe. It is disabled by default and requires shared TypeSafe credentials
+plus an explicit approved corpus list:
+
+```json
+{
+  "xsearch": {
+    "enabled": true,
+    "corpora": ["memory"],
+    "timeoutMs": 10000
+  }
+}
+```
+
+Place this under `plugins.entries.unblock-memory.config`. Enabling it approves
+sending the query and selected excerpts from those corpora to TypeSafe. Skills
+are excluded. Unapproved corpora are rejected; session filters apply to both
+retrieval methods. `minScore` is final usefulness (0–1), not vector similarity.
+The tool returns existing source spans with normal `memory_get` citations.
+
 ## Response quality tracking (opt-in)
 
 `responseAudit` evaluates bounded human-agent exchanges in the background. It is
@@ -154,8 +177,9 @@ Choice confidence from Noul yes-probability. Multiple supported reasons can coex
 `reportVersion` identifies composition/reporting semantics independently of the
 judge rubric, allowing cached judgments to be re-reported without re-inference.
 
-Results live in the agent's private `unblock-memory/response-audit.sqlite`, outside
-the memory index. It stores judgments and source event references/hashes, not copies
+Results live in operator-only tables in the agent's private
+`unblock-memory/unblock-memory.sqlite`, outside the memory index. These tables
+are not searched or injected into agent prompts. They store judgments and source event references/hashes, not copies
 of conversations. Identical successful inputs are cached; source rewrites invalidate
 in-scope results on the next scan. Reports partition by fixed judge/rubric/context
 configuration, UTC week, task type and agent model. They expose eligible/assessed
@@ -599,7 +623,7 @@ For optional read-only diagnostics, `memory_people_prime({ personId, agentName?,
 draft: { blurb, citations: [{ path, from, lines }] } })` still reviews a snippet
 without writing. Agents do not need this extra call in the normal update workflow.
 
-Judgments are cached privately in `people.sqlite` (maximum 2,000 entries), keyed
+Judgments are cached privately in `unblock-memory.sqlite` (maximum 2,000 entries), keyed
 by person, agent, exact evidence/context, questions,
 and judge version. No source text or credentials are stored in the cache.
 Retrieval reruns against the current index; unchanged judgments are reused.
@@ -758,10 +782,38 @@ explicit intervals remain unchanged on upgrade; set them to `60` for hourly chec
 
 Indexes live at `~/.openclaw/agents/<agentId>/unblock-memory/index.sqlite` (or the
 equivalent configured OpenClaw state directory). Durable agent-supplied event
-dates and maintenance proposals live separately in `curation.sqlite`, so a QMD
+dates, maintenance proposals, people/dossiers and response audits live separately
+in `unblock-memory.sqlite`, so a QMD
 index rebuild does not discard them. The first lookup builds the index;
 Markdown filesystem changes queue a debounced, serialized background refresh.
 
+### Durable database migration (v0.3.20)
+
+Each agent has two active plugin databases: rebuildable `index.sqlite` and durable
+`unblock-memory.sqlite`. The latter uses WAL, private permissions and component
+schema versions. Store modules and tool access remain separate: consolidating files
+does not expose operator response audits to memory searches or whisperers.
+
+**Stop the Gateway and any plugin CLI writers before upgrading.** On first
+durable-store access, the plugin imports existing `curation.sqlite`, `people.sqlite`
+and `response-audit.sqlite` files, including disabled features, in one transaction.
+It includes committed WAL data, verifies row counts/values, integrity and foreign
+keys, and records completion. Missing stores are normal. Unsupported or invalid
+data aborts the import without a partial cutover; the next access retries.
+QMD and transcript databases are not migrated.
+
+Old files remain untouched as **inert recovery copies**, not active stores.
+Completed migration never reimports or writes to them. Do not run old and new
+plugin versions together: old writers can keep changing their separate files.
+Back up the new database with SQLite's online backup API, or stop all writers
+and safely checkpoint WAL first. Copying only a live `.sqlite` file is unsafe.
+
+To roll back before any new writes, stop all writers, preserve the new database
+and its WAL/SHM sidecars, and restore the old plugin against the retained files.
+**After new writes, the legacy files are stale:** rollback requires an explicit
+reverse data migration or accepting the loss of post-upgrade changes.
+Retain recovery files until the upgrade is verified; cleanup is a separate step.
+
 ## Memory quality audit
 
 `memory_audit_quality` is an on-demand, source-read-only audit. TypeSafe flags likely

package/dist/src/config.d.ts

@@ -42,6 +42,11 @@ export type UnblockMemoryConfig = {
         enabled: boolean;
         corpora: readonly string[];
     };
+    xsearch: {
+        enabled: boolean;
+        corpora: readonly string[];
+        timeoutMs: number;
+    };
     responseAudit: ResponseAuditConfig;
     peoplePrimer: PeoplePrimerConfig;
     people: {

package/dist/src/config.js

@@ -264,6 +264,7 @@ export function resolveConfig(value) {
             typesafe: { ...DEFAULT_TYPESAFE_CONFIG },
             qualityAudit: { ...DEFAULT_QUALITY_AUDIT },
             evidenceReview: { enabled: false, corpora: [] },
+            xsearch: { enabled: false, corpora: [], timeoutMs: 10000 },
             responseAudit: resolveResponseAudit(undefined, DEFAULT_CORPORA),
             peoplePrimer: resolvePeoplePrimer(undefined, DEFAULT_CORPORA, false),
             people: DEFAULT_PEOPLE_CONFIG,
@@ -275,10 +276,28 @@ export function resolveConfig(value) {
         throw new Error("unblock-memory config must be an object");
     }
     const config = value;
-    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "peoplePrimer", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit"], "config");
+    assertOnlyKeys(config, ["corpora", "keepEmbeddingModelWarm", "analysis", "people", "peoplePrimer", "skillWhisperer", "memoryWhisperer", "typesafe", "qualityAudit", "evidenceReview", "responseAudit", "xsearch"], "config");
     const corpora = resolveCorpora(config.corpora);
     const people = resolvePeople(config.people);
     const peoplePrimer = resolvePeoplePrimer(config.peoplePrimer, corpora, people.enabled);
+    let xsearch = { enabled: false, corpora: [], timeoutMs: 10000 };
+    if (config.xsearch !== undefined) {
+        const value = config.xsearch;
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("xsearch must be an object");
+        const options = value;
+        assertOnlyKeys(options, ["enabled", "corpora", "timeoutMs"], "xsearch");
+        try {
+            const approved = resolveQualityAudit({ enabled: options.enabled, corpora: options.corpora }, corpora);
+            xsearch = { enabled: approved.enabled, corpora: approved.corpora,
+                timeoutMs: positiveInteger(options.timeoutMs, 10000, "xsearch.timeoutMs", 30000) };
+        }
+        catch (error) {
+            if (error instanceof Error)
+                throw new Error(error.message.replaceAll("qualityAudit", "xsearch"));
+            throw error;
+        }
+    }
     let evidenceReview = { enabled: false, corpora: [] };
     if (config.evidenceReview !== undefined) {
         const value = config.evidenceReview;
@@ -349,7 +368,7 @@ export function resolveConfig(value) {
     if (skillWhisperer.enabled && !corpora.some((corpus) => corpus.kind === "skills")) {
         throw new Error('unblock-memory enabled skillWhisperer requires a corpus named "skills" with kind "skills"');
     }
-    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, peoplePrimer, skillWhisperer,
+    return { corpora, keepEmbeddingModelWarm, analysis: analysisConfig, people, peoplePrimer, skillWhisperer, xsearch,
         qualityAudit: resolveQualityAudit(config.qualityAudit, corpora),
         evidenceReview,
         responseAudit: resolveResponseAudit(config.responseAudit, corpora),

package/dist/src/contracts.d.ts

@@ -24,7 +24,7 @@ export type SessionSearchFilter = {
 export type MemoryRequestContext = Pick<OpenClawPluginToolContext, "sessionKey" | "sessionId" | "messageChannel" | "agentAccountId" | "nativeChannelId" | "deliveryContext">;
 export type CorpusSearchOptions = NonNullable<Parameters<MemorySearchManagerContract["search"]>[1]> & {
     corpora?: readonly string[];
-    /** Internal vector-hint budget; oversized matched chunks are omitted, never sliced. */
+    /** Internal hint/reranking budget; oversized matched chunks are omitted, never sliced. */
     maxSnippetChars?: number;
     sessionFilter?: SessionSearchFilter;
     requestContext?: MemoryRequestContext;

package/dist/src/curation.js

@@ -1,7 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { openMemoryDatabase } from "./memory-database.js";
 const TEMPORAL_BASES = ["path", "frontmatter", "session", "agent_verified"];
 const MAINTENANCE_TASK_TYPES = ["ambiguous_event_time", "exact_duplicate", "quality_review"];
 const MAINTENANCE_STATUSES = ["pending", "resolved", "deferred", "irrelevant"];
@@ -42,35 +40,41 @@ export function chunkFingerprint(text) {
 export class CurationStore {
     #db;
     constructor(path) {
-        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        this.#db = new DatabaseSync(path);
-        chmodSync(path, 0o600);
-        this.#db.exec(`
-      PRAGMA journal_mode = WAL;
-      PRAGMA busy_timeout = 5000;
-
-      CREATE TABLE IF NOT EXISTS temporal_annotations (
-        corpus TEXT NOT NULL,
-        collection TEXT NOT NULL,
-        path TEXT NOT NULL,
-        content_fingerprint TEXT NOT NULL DEFAULT '',
-        event_time TEXT NOT NULL,
-        basis TEXT NOT NULL CHECK (basis IN ('path', 'frontmatter', 'session', 'agent_verified')),
-        evidence TEXT NOT NULL,
-        qmd_hash TEXT,
-        qmd_seq INTEGER,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL,
-        PRIMARY KEY (corpus, collection, path, content_fingerprint)
-      );
+        this.#db = openMemoryDatabase(path);
+        try {
+            this.#db.exec("BEGIN IMMEDIATE");
+            const version = this.#db.prepare("SELECT version FROM memory_schema WHERE component='curation'").get()?.version;
+            if (version !== undefined && version !== 1)
+                throw new Error("Unsupported curation schema version");
+            this.#db.exec(`
+        CREATE TABLE IF NOT EXISTS temporal_annotations (
+          corpus TEXT NOT NULL,
+          collection TEXT NOT NULL,
+          path TEXT NOT NULL,
+          content_fingerprint TEXT NOT NULL DEFAULT '',
+          event_time TEXT NOT NULL,
+          basis TEXT NOT NULL CHECK (basis IN ('path', 'frontmatter', 'session', 'agent_verified')),
+          evidence TEXT NOT NULL,
+          qmd_hash TEXT,
+          qmd_seq INTEGER,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          PRIMARY KEY (corpus, collection, path, content_fingerprint)
+        );
 
-    `);
-        this.#ensureMaintenanceSchema();
-        this.#db.exec(`CREATE TABLE IF NOT EXISTS quality_judgments (
-      cache_key TEXT PRIMARY KEY,
-      noise REAL NOT NULL CHECK (noise BETWEEN 0 AND 1),
-      evidence REAL NOT NULL CHECK (evidence BETWEEN 0 AND 1)
-    )`);
+      `);
+            this.#ensureMaintenanceSchema();
+            this.#db.exec(`CREATE TABLE IF NOT EXISTS quality_judgments (
+        cache_key TEXT PRIMARY KEY,
+        noise REAL NOT NULL CHECK (noise BETWEEN 0 AND 1),
+        evidence REAL NOT NULL CHECK (evidence BETWEEN 0 AND 1)
+      )`);
+            this.#db.exec("INSERT OR IGNORE INTO memory_schema VALUES ('curation',1); COMMIT");
+        }
+        catch (error) {
+            this.#db.close();
+            throw error;
+        }
     }
     #ensureMaintenanceSchema() {
         this.#db.exec(`
@@ -93,19 +97,11 @@ export class CurationStore {
         const schema = this.#db.prepare("SELECT sql FROM sqlite_master WHERE name = 'maintenance_tasks'")
             .get();
         if (!schema.sql.includes("'quality_review'")) {
-            this.#db.exec("BEGIN IMMEDIATE");
-            try {
-                this.#db.exec(schema.sql.replace("maintenance_tasks", "maintenance_tasks_quality")
-                    .replace("'exact_duplicate'", "'exact_duplicate', 'quality_review'"));
-                this.#db.exec(`INSERT INTO maintenance_tasks_quality SELECT * FROM maintenance_tasks;
-          DROP TABLE maintenance_tasks;
-          ALTER TABLE maintenance_tasks_quality RENAME TO maintenance_tasks;`);
-                this.#db.exec("COMMIT");
-            }
-            catch (error) {
-                this.#db.exec("ROLLBACK");
-                throw error;
-            }
+            this.#db.exec(schema.sql.replace("maintenance_tasks", "maintenance_tasks_quality")
+                .replace("'exact_duplicate'", "'exact_duplicate', 'quality_review'"));
+            this.#db.exec(`INSERT INTO maintenance_tasks_quality SELECT * FROM maintenance_tasks;
+        DROP TABLE maintenance_tasks;
+        ALTER TABLE maintenance_tasks_quality RENAME TO maintenance_tasks;`);
         }
         this.#db.exec(`
       CREATE INDEX IF NOT EXISTS maintenance_tasks_status_created

package/dist/src/manager.d.ts

@@ -194,6 +194,7 @@ export declare class QmdMemoryManager implements MemorySearchManagerContract {
         };
     }): MaintenanceTask | undefined;
     search(query: string, opts?: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
+    searchBm25(query: string, opts: CorpusSearchOptions): Promise<CorpusMemorySearchResult[]>;
     searchSkills(query: string, minScore: number, limit: number): Promise<SkillSearchCandidate[]>;
     readFile(params: {
         relPath: string;

package/dist/src/manager.js

@@ -14,6 +14,7 @@ import { qualityTaskPresence } from "./quality-triage.js";
 import { reviewIndexedClaim } from "./evidence-review.js";
 import { reviewClusterIngestion } from "./cluster-review.js";
 import { abortable } from "./abortable.js";
+import { xsearchBm25 } from "./xsearch-bm25.js";
 const DEFAULT_READ_LINES = 120;
 const MAX_READ_CHARS = 12_000;
 const WATCH_DEBOUNCE_MS = 250;
@@ -412,34 +413,34 @@ export class QmdMemoryManager {
                 ])),
             },
         });
-        enableSecureDelete(store);
-        ensureMemoryAnalysisSchema(store.internal.db);
-        markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
-        const configuredCollections = new Set(this.#qmdSources().map((source) => source.collection));
-        const staleCollections = (await store.getStatus()).collections
-            .map((collection) => collection.name)
-            .filter((collection) => !configuredCollections.has(collection));
-        const appearsInAnalysis = store.internal.db.prepare(`
-      SELECT 1
-      FROM memory_analysis_memberships membership
-      JOIN documents document ON document.hash = membership.hash
-      WHERE membership.run_id = (
-        SELECT id FROM memory_analysis_runs
-        WHERE completed_at IS NOT NULL
-        ORDER BY completed_at DESC, created_at DESC, id DESC
-        LIMIT 1
-      ) AND document.collection = ?
-      LIMIT 1
-    `);
-        const prunedAnalysisInput = staleCollections.some((collection) => appearsInAnalysis.get(collection));
-        const prunedDocuments = await pruneStaleCollections(store, configuredCollections);
-        if (prunedDocuments > 0 && prunedAnalysisInput)
-            markMemoryAnalysisStale(store.internal.db);
         try {
+            enableSecureDelete(store);
+            ensureMemoryAnalysisSchema(store.internal.db);
+            markStaleForAnalysisCollectionChange(store.internal.db, this.#analysisCollectionNames(), this.#skillCollectionNames().length > 0);
+            const configuredCollections = new Set(this.#qmdSources().map((source) => source.collection));
+            const staleCollections = (await store.getStatus()).collections
+                .map((collection) => collection.name)
+                .filter((collection) => !configuredCollections.has(collection));
+            const appearsInAnalysis = store.internal.db.prepare(`
+        SELECT 1
+        FROM memory_analysis_memberships membership
+        JOIN documents document ON document.hash = membership.hash
+        WHERE membership.run_id = (
+          SELECT id FROM memory_analysis_runs
+          WHERE completed_at IS NOT NULL
+          ORDER BY completed_at DESC, created_at DESC, id DESC
+          LIMIT 1
+        ) AND document.collection = ?
+        LIMIT 1
+      `);
+            const prunedAnalysisInput = staleCollections.some((collection) => appearsInAnalysis.get(collection));
+            const prunedDocuments = await pruneStaleCollections(store, configuredCollections);
+            if (prunedDocuments > 0 && prunedAnalysisInput)
+                markMemoryAnalysisStale(store.internal.db);
             await ensureSemanticChunking(store);
         }
         catch (error) {
-            await store.close();
+            await store.close().catch(() => undefined);
             throw error;
         }
         this.#cleanupRemovedDocuments = (changedDocuments) => {
@@ -834,10 +835,13 @@ export class QmdMemoryManager {
             expand: false,
         });
         opts?.signal?.throwIfAborted();
+        return this.#searchResults(hits, store, opts);
+    }
+    async #searchResults(hits, store, opts, method = "vector") {
         const tokenizer = store.internal?.llm;
         const results = [];
         for (const hit of hits) {
-            // Proactive hints must retain the entire matched chunk, even when expanded
+            // Hints and reranking must retain the entire matched chunk, even when expanded
             // turn/message context exceeds their budget. Ordinary search is unchanged.
             if (hit.bestChunk.length > (opts?.maxSnippetChars ?? Infinity))
                 continue;
@@ -861,7 +865,7 @@ export class QmdMemoryManager {
                 path: hit.file,
                 ...span,
                 score: hit.score,
-                vectorScore: hit.score,
+                ...(method === "vector" ? { vectorScore: hit.score } : { textScore: hit.score }),
                 snippet: selected.text,
                 source: "memory",
                 corpus,
@@ -871,6 +875,22 @@ export class QmdMemoryManager {
         }
         return results;
     }
+    async searchBm25(query, opts) {
+        if (opts.sources && !opts.sources.includes("memory"))
+            return [];
+        const collections = this.#collectionNames(opts.corpora);
+        opts.signal?.throwIfAborted();
+        await abortable(this.#operationChain ?? Promise.resolve(), opts.signal);
+        const sessions = this.#sessions;
+        if (opts.sessionFilter && sessions && collections.includes(sessions.collection))
+            await this.#refreshSessionMetadata();
+        const allowedPaths = opts.sessionFilter && sessions && collections.includes(sessions.collection)
+            ? sessionAllowedPaths(this.#sessionMetadata, sessions.collection, opts.sessionFilter) : undefined;
+        const store = await this.#getAnalysisStore();
+        opts.signal?.throwIfAborted();
+        const hits = xsearchBm25(store.internal.db, query, collections, opts.maxResults ?? 5, allowedPaths);
+        return this.#searchResults(hits, store, opts, "bm25");
+    }
     async searchSkills(query, minScore, limit) {
         const collections = this.#skillCollectionNames();
         if (collections.length === 0)

package/dist/src/memory-database.d.ts

@@ -0,0 +1,6 @@
+import { DatabaseSync } from "node:sqlite";
+export declare const MEMORY_DATABASE = "unblock-memory.sqlite";
+/** Separate domain stores share settings, not a monolithic data-access API. */
+export declare function openMemoryDatabase(path: string): DatabaseSync;
+/** File existence no longer tells us which feature has initialized its tables. */
+export declare function hasMemoryTable(path: string, table: string): boolean;

package/dist/src/memory-database.js

@@ -0,0 +1,174 @@
+import { closeSync, constants, existsSync, fchmodSync, lstatSync, mkdirSync, openSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+export const MEMORY_DATABASE = "unblock-memory.sqlite";
+const legacyStores = [
+    { file: "curation.sqlite", component: "curation", tables: [
+            "temporal_annotations", "maintenance_tasks", "quality_judgments",
+        ] },
+    { file: "people.sqlite", component: "people", tables: [
+            "companies", "people", "person_identities", "person_dossiers", "people_todos",
+            "person_whisper_receipts", "person_evidence_receipts", "person_dossier_changes", "person_primer_judgments",
+        ] },
+    { file: "response-audit.sqlite", component: "responses", tables: [
+            "response_lease", "response_results", "response_scans", "response_checkpoints", "response_cursors",
+            "response_schedule", "response_stages", "response_stage_links", "response_review_tasks",
+            "response_review_evidence", "response_review_decisions", "response_review_versions", "response_annotations",
+        ] },
+];
+function identifier(name) { return `"${name.replaceAll('"', '""')}"`; }
+function requireRegularFile(path) {
+    const file = lstatSync(path, { throwIfNoEntry: false });
+    if (file && !file.isFile())
+        throw new Error("Memory database must be a regular file, not a symlink");
+}
+function enableWal(db) {
+    // Switching journal modes can return SQLITE_BUSY without invoking busy_timeout.
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        try {
+            db.exec("PRAGMA journal_mode=WAL");
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !("errcode" in error) || error.errcode !== 5 || Date.now() >= deadline)
+                throw error;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(25, Math.max(0, deadline - Date.now())));
+        }
+    }
+}
+/** Separate domain stores share settings, not a monolithic data-access API. */
+export function openMemoryDatabase(path) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    requireRegularFile(path);
+    const descriptor = openSync(path, constants.O_CREAT | constants.O_APPEND | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    try {
+        fchmodSync(descriptor, 0o600);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    const db = new DatabaseSync(path);
+    try {
+        db.exec("PRAGMA busy_timeout=5000");
+        enableWal(db);
+        db.exec(`PRAGMA foreign_keys=ON;
+      PRAGMA trusted_schema=OFF;
+      CREATE TABLE IF NOT EXISTS memory_schema (component TEXT PRIMARY KEY, version INTEGER NOT NULL) STRICT;`);
+        // Explicit standalone store paths remain useful to tests and offline tools.
+        // Only the production filename opts into sibling-file consolidation.
+        if (basename(path) === MEMORY_DATABASE)
+            consolidate(db, dirname(path));
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+function consolidate(db, directory) {
+    const completed = () => {
+        const version = db.prepare("SELECT version FROM memory_schema WHERE component='storage'").get()?.version;
+        if (version !== undefined && version !== 1)
+            throw new Error("Unsupported durable storage version");
+        return version === 1;
+    };
+    if (completed())
+        return;
+    const sources = legacyStores.filter(source => lstatSync(join(directory, source.file), { throwIfNoEntry: false }));
+    const attached = [];
+    try {
+        for (const source of sources) {
+            const path = join(directory, source.file);
+            requireRegularFile(path);
+            const alias = `legacy_${source.component}`;
+            db.prepare(`ATTACH DATABASE ? AS ${identifier(alias)}`).run(path);
+            attached.push(alias);
+        }
+        // Attached legacy writer locks cover the entire snapshot/copy/verification.
+        // They cannot stop old binaries writing again later: upgrade with writers stopped.
+        db.exec("PRAGMA foreign_keys=OFF; BEGIN IMMEDIATE");
+        try {
+            if (!completed()) {
+                const existing = db.prepare("SELECT name FROM main.sqlite_schema WHERE type='table' AND name!='memory_schema'").get();
+                if (existing)
+                    throw new Error("Unmarked durable database is not empty; refusing to overwrite it");
+                for (const source of sources) {
+                    const schema = identifier(`legacy_${source.component}`);
+                    const version = Number(db.prepare(`PRAGMA ${schema}.user_version`).get()?.user_version);
+                    if (source.component === "people" ? version < 0 || version > 4 : version !== 0) {
+                        throw new Error(`Unsupported legacy ${source.component} schema version`);
+                    }
+                    const integrity = db.prepare(`PRAGMA ${schema}.integrity_check`).all();
+                    if (integrity.length !== 1 || integrity[0]?.integrity_check !== "ok")
+                        throw new Error(`Invalid legacy ${source.component} database`);
+                    const objects = db.prepare(`SELECT type,name,tbl_name,sql FROM ${schema}.sqlite_schema WHERE name NOT LIKE 'sqlite_%'`).all();
+                    if (source.component === "people" && version === 0 && objects.length)
+                        throw new Error("Unversioned legacy people schema");
+                    for (const object of objects) {
+                        if ((object.type !== "table" && object.type !== "index") || typeof object.sql !== "string" ||
+                            !source.tables.some(name => name === object.tbl_name) || /CREATE\s+VIRTUAL\s+TABLE/i.test(object.sql)) {
+                            throw new Error(`Unsupported legacy ${source.component} schema object`);
+                        }
+                    }
+                    const tables = objects.filter(object => object.type === "table");
+                    if (source.component === "people" && version > 0) {
+                        const required = ["companies", "people", "person_identities", "person_dossiers", "people_todos",
+                            ...(version >= 2 ? ["person_whisper_receipts"] : []),
+                            ...(version === 2 ? ["person_evidence_receipts"] : []),
+                            ...(version === 4 ? ["person_dossier_changes"] : [])];
+                        if (required.some(name => !tables.some(table => table.name === name)))
+                            throw new Error("Incomplete legacy people schema");
+                    }
+                    for (const table of tables)
+                        db.exec(String(table.sql));
+                    for (const table of tables) {
+                        const name = identifier(String(table.name));
+                        db.exec(`INSERT INTO main.${name} SELECT * FROM ${schema}.${name}`);
+                        const counts = db.prepare(`SELECT (SELECT count(*) FROM main.${name}) AS actual,
+              (SELECT count(*) FROM ${schema}.${name}) AS expected`).get();
+                        const different = db.prepare(`SELECT * FROM ${schema}.${name} EXCEPT SELECT * FROM main.${name}`).get();
+                        const extra = db.prepare(`SELECT * FROM main.${name} EXCEPT SELECT * FROM ${schema}.${name}`).get();
+                        if (counts?.actual !== counts?.expected || different || extra)
+                            throw new Error(`Legacy ${source.component} copy verification failed`);
+                    }
+                    for (const index of objects.filter(object => object.type === "index"))
+                        db.exec(String(index.sql));
+                    if (source.component === "people")
+                        db.prepare("INSERT INTO memory_schema VALUES ('people',?)").run(version);
+                }
+                if (db.prepare("PRAGMA main.foreign_key_check").get())
+                    throw new Error("Migrated memory has broken foreign keys");
+                const integrity = db.prepare("PRAGMA main.integrity_check").all();
+                if (integrity.length !== 1 || integrity[0]?.integrity_check !== "ok")
+                    throw new Error("Migrated memory integrity check failed");
+                db.prepare("INSERT INTO memory_schema VALUES ('storage',1)").run();
+            }
+            db.exec("COMMIT");
+        }
+        catch (error) {
+            db.exec("ROLLBACK");
+            throw error;
+        }
+        finally {
+            db.exec("PRAGMA foreign_keys=ON");
+        }
+    }
+    finally {
+        for (const alias of attached.reverse())
+            db.exec(`DETACH DATABASE ${identifier(alias)}`);
+    }
+}
+/** File existence no longer tells us which feature has initialized its tables. */
+export function hasMemoryTable(path, table) {
+    if (!existsSync(path) && !(basename(path) === MEMORY_DATABASE &&
+        legacyStores.some(source => existsSync(join(dirname(path), source.file)))))
+        return false;
+    const db = openMemoryDatabase(path);
+    try {
+        return Boolean(db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(table));
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/src/people-store.js

@@ -1,8 +1,7 @@
 import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
-import { chmodSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+import { MEMORY_DATABASE, openMemoryDatabase } from "./memory-database.js";
 import { resolveStateDir } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
 import { normalizeAgentIdStrict } from "openclaw/plugin-sdk/routing";
 import { Type } from "typebox";
@@ -138,13 +137,10 @@ export class PeopleStore {
     #maxOpenTodos;
     #maxBlurbChars;
     constructor(path, options) {
-        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        this.#db = new DatabaseSync(path);
+        this.#db = openMemoryDatabase(path);
         this.#maxOpenTodos = options.maxOpenTodos;
         this.#maxBlurbChars = options.maxBlurbChars;
         try {
-            chmodSync(path, 0o600);
-            this.#db.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON");
             this.#migrate();
         }
         catch (error) {
@@ -740,23 +736,24 @@ export class PeopleStore {
         }
     }
     #migrate() {
-        const current = this.#db.prepare("PRAGMA user_version").get();
-        if (current.user_version === 4)
-            return;
-        if (current.user_version !== 0 &&
-            current.user_version !== 1 &&
-            current.user_version !== 2 &&
-            current.user_version !== 3) {
-            throw new Error(`unsupported PeopleSQL schema version: ${current.user_version}`);
-        }
         this.#db.exec("BEGIN IMMEDIATE");
         try {
-            if (current.user_version === 2) {
+            // Re-read under the write lock so concurrent first opens cannot both migrate.
+            const version = this.#db.prepare("SELECT version FROM memory_schema WHERE component='people'").get()?.version
+                ?? this.#db.prepare("PRAGMA user_version").get()?.user_version ?? 0;
+            if (![0, 1, 2, 3, 4].includes(Number(version)))
+                throw new Error(`unsupported PeopleSQL schema version: ${version}`);
+            if (version === 4) {
+                this.#db.prepare("INSERT OR IGNORE INTO memory_schema VALUES ('people',4)").run();
+                this.#db.exec("COMMIT");
+                return;
+            }
+            if (version === 2) {
                 this.#db.exec(`
           DROP TABLE person_evidence_receipts;
         `);
             }
-            else if (current.user_version === 1) {
+            else if (version === 1) {
                 this.#db.exec(`
           DROP INDEX people_policy_seen;
           ALTER TABLE people DROP COLUMN refinement_enabled;
@@ -772,7 +769,7 @@ export class PeopleStore {
           ) STRICT;
         `);
             }
-            else if (current.user_version === 0) {
+            else if (version === 0) {
                 this.#db.exec(`
         CREATE TABLE companies (
           id TEXT PRIMARY KEY,
@@ -859,7 +856,8 @@ export class PeopleStore {
 
         CREATE INDEX person_dossier_changes_person_changed
           ON person_dossier_changes(person_id, changed_at DESC);
-        PRAGMA user_version = 4;
+        INSERT INTO memory_schema VALUES ('people',4)
+          ON CONFLICT(component) DO UPDATE SET version=excluded.version;
       `);
             this.#db.exec("COMMIT");
         }
@@ -884,7 +882,7 @@ export class PeopleStores {
         const canonicalAgentId = normalized.value;
         let store = this.#stores.get(canonicalAgentId);
         if (!store) {
-            store = new PeopleStore(join(this.#stateRoot, "agents", canonicalAgentId, "unblock-memory", "people.sqlite"), this.#options);
+            store = new PeopleStore(join(this.#stateRoot, "agents", canonicalAgentId, "unblock-memory", MEMORY_DATABASE), this.#options);
             this.#stores.set(canonicalAgentId, store);
         }
         return store;