@unblocklabs/unblock-memory 0.10.0 → 0.10.1

package/dist/src/emotion-baselines.d.ts

@@ -4,6 +4,8 @@ export declare const INSIDE_OUT_EMOTIONS: readonly ["joy", "sadness", "fear", "a
 export declare const PURGED_GRADE = "Purged by operator";
 type Emotion = typeof INSIDE_OUT_EMOTIONS[number];
 type Row = Record<string, SQLOutputValue>;
+export declare const hash: (value: unknown) => string;
+export declare const tableExists: (db: DatabaseSync, name: string) => boolean;
 type Statistics = {
     count: number;
     mean: number | null;
@@ -89,7 +91,10 @@ export declare function deviationReader(db: DatabaseSync): (row: Row, history?:
     }[];
     status: "not_compared";
 };
-/** Weekly snapshots, newest first; cumulative statistics are prefix sums of each population's stored weeks. */
+/**
+ * Weekly snapshots, newest first; cumulative statistics are prefix sums of each population's stored weeks.
+ * `since` keeps weeks whose last day is on or after that UTC date (`week_end` is the exclusive next Monday).
+ */
 export declare function emotionBaselineHistory(db: DatabaseSync, options?: {
     personId?: string;
     since?: number;
@@ -106,6 +111,14 @@ export declare function emotionBaselineHistory(db: DatabaseSync, options?: {
     weekly: Summary;
     cumulative: Summary;
 }[];
+/**
+ * Changes whenever a refresh input could: grades, links, people, stored results, the current week,
+ * grades crossing `now`, or settings. Equal fingerprints mean a refresh would write nothing.
+ */
+export declare function baselineFingerprint(db: DatabaseSync, options: {
+    minInteractions: number;
+    now: number;
+}): string;
 /**
  * Delete one person's baselines and assessment history. With `grades`, also erase their six
  * probabilities and person link, keeping a tombstone so the reply is never sent to Jev again.

package/dist/src/emotion-baselines.js

@@ -10,10 +10,11 @@ const STEPS = 100;
 // Writers on the shared store wait for at most one short batch, never a whole refresh.
 const BATCH = 500;
 const PAGE = 2000;
-const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const weekStart = (time) => MONDAY + Math.floor((time - MONDAY) / WEEK) * WEEK;
 const bin = (value) => Math.round(value * STEPS);
-const tableExists = (db, name) => Boolean(db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(name));
+export const tableExists = (db, name) => Boolean(db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(name));
+const GRADE = `interaction_id,rubric,model,person_id,target_at,reviewed_at,error,${INSIDE_OUT_EMOTIONS.join(",")}`;
 const VALID = INSIDE_OUT_EMOTIONS.map(e => `e.${e} BETWEEN 0 AND 1`).join(" AND ");
 // Comparable grades: successful, timed, not after `now`. Callers add the People join.
 const COMPARABLE = `e.reviewed_at<=? AND e.error IS NULL AND e.target_at IS NOT NULL AND e.target_at<=? AND ${VALID}`;
@@ -186,12 +187,14 @@ export function refreshEmotionBaselines(db, options) {
     initializeEmotionBaselines(db);
     let snapshots = 0, comparisons = 0;
     const queue = batches(db), people = tableExists(db, "people");
-    const prior = db.prepare(`SELECT id,result_json FROM inside_out_deviations WHERE interaction_id=? AND rubric=? AND grade_signature=?
-    ORDER BY assessed_at DESC,rowid DESC LIMIT 1`);
+    const prior = db.prepare(`SELECT id,result_json,json_extract(result_json,'$.status') status FROM inside_out_deviations
+    WHERE interaction_id=? AND rubric=? AND grade_signature=? ORDER BY assessed_at DESC,rowid DESC LIMIT 1`);
     const save = db.prepare("INSERT OR IGNORE INTO inside_out_deviations VALUES (?,?,?,?,?,?,?,?)");
+    const grade = db.prepare(`SELECT ${GRADE} FROM inside_out WHERE interaction_id=? AND rubric=?`);
     const assess = (row, signature, decide) => {
         const previous = prior.get(row.interaction_id, row.rubric, signature);
-        if (!options.recompare && previous)
+        // An existing assessment stands for its grade, except future_time: that only described the clock.
+        if (!options.recompare && previous && previous.status !== "future_time")
             return;
         const result = { version: VERSION, status: "insufficient_history", personId: row.person_id === null ? null : String(row.person_id),
             baselineId: null, baselineEnd: null, assessedAt: now, minInteractions: minimum, cumulative: null, weekly: null };
@@ -203,6 +206,10 @@ export function refreshEmotionBaselines(db, options) {
         // selecting an obsolete intervening assessment or losing either observation.
         const id = hash([key(result), previous?.id ?? null]);
         queue.write(() => {
+            // Rechecked under the write lock: a purge, regrade or relink committed since the read wins.
+            const current = grade.get(row.interaction_id, row.rubric);
+            if (!current || gradeSignature(current) !== signature)
+                return;
             comparisons += Number(save.run(id, row.interaction_id, row.rubric, signature, now, result.baselineId, result.personId, JSON.stringify(result)).changes);
         });
     };
@@ -213,8 +220,8 @@ export function refreshEmotionBaselines(db, options) {
       ON CONFLICT(person_id,rubric,model,week_start) DO UPDATE SET id=excluded.id,version=excluded.version,
       week_end=excluded.week_end,computed_at=excluded.computed_at,weekly_json=excluded.weekly_json`);
         const remove = db.prepare("DELETE FROM person_emotion_baselines WHERE person_id=? AND rubric=? AND model=? AND week_start=? AND id=?");
-        const page = db.prepare(`SELECT interaction_id,rubric,model,person_id,target_at,reviewed_at,error,${INSIDE_OUT_EMOTIONS.join(",")}
-      FROM inside_out e WHERE e.person_id=? AND e.rubric=? AND e.model=? AND ${COMPARABLE}
+        const populated = db.prepare("SELECT 1 FROM inside_out WHERE person_id=? AND rubric=? AND model=? LIMIT 1");
+        const page = db.prepare(`SELECT ${GRADE} FROM inside_out e WHERE e.person_id=? AND e.rubric=? AND e.model=? AND ${COMPARABLE}
       AND (? IS NULL OR e.target_at>? OR (e.target_at=? AND e.interaction_id>?)) ORDER BY e.target_at,e.interaction_id LIMIT ?`);
         const groups = db.prepare(`SELECT DISTINCT e.person_id,e.rubric,e.model FROM inside_out e JOIN people p ON p.id=e.person_id
       WHERE ${COMPARABLE}`).all(now, now);
@@ -266,7 +273,9 @@ export function refreshEmotionBaselines(db, options) {
                 current.add(start);
                 if (existing.get(start) !== id)
                     queue.write(() => {
-                        snapshots += Number(upsert.run(person, rubric, model, start, id, VERSION, end, now, json).changes);
+                        // A purge of this person since the read leaves no linked grades: never restore their distribution.
+                        if (populated.get(person, rubric, model))
+                            snapshots += Number(upsert.run(person, rubric, model, start, id, VERSION, end, now, json).changes);
                     });
                 previous = { id, end, weekly };
             }
@@ -325,15 +334,28 @@ export function deviationReader(db) {
             }) } : current;
     };
 }
-/** Weekly snapshots, newest first; cumulative statistics are prefix sums of each population's stored weeks. */
+/**
+ * Weekly snapshots, newest first; cumulative statistics are prefix sums of each population's stored weeks.
+ * `since` keeps weeks whose last day is on or after that UTC date (`week_end` is the exclusive next Monday).
+ */
 export function emotionBaselineHistory(db, options = {}) {
     const limit = options.limit ?? 100;
     if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
         throw new Error("Baseline limit must be between 1 and 1000");
     if (schemaVersion(db) !== 2)
         return [];
+    // One read snapshot: a concurrent refresh may replace or drop weeks between the two queries.
+    db.exec("BEGIN");
+    try {
+        return readBaselineHistory(db, options, limit);
+    }
+    finally {
+        db.exec("COMMIT");
+    }
+}
+function readBaselineHistory(db, options, limit) {
     const selected = db.prepare(`SELECT person_id,rubric,model,week_start FROM person_emotion_baselines
-    WHERE (? IS NULL OR person_id=?) AND (? IS NULL OR week_end>=?) ORDER BY week_end DESC,person_id,rubric,model LIMIT ?`)
+    WHERE (? IS NULL OR person_id=?) AND (? IS NULL OR week_end>?) ORDER BY week_end DESC,person_id,rubric,model LIMIT ?`)
         .all(options.personId ?? null, options.personId ?? null, options.since ?? null, options.since ?? null, limit);
     const wanted = new Map();
     for (const row of selected) {
@@ -358,6 +380,25 @@ export function emotionBaselineHistory(db, options = {}) {
     }
     return selected.map(row => snapshots.get(JSON.stringify([JSON.stringify([row.person_id, row.rubric, row.model]), row.week_start])));
 }
+/**
+ * Changes whenever a refresh input could: grades, links, people, stored results, the current week,
+ * grades crossing `now`, or settings. Equal fingerprints mean a refresh would write nothing.
+ */
+export function baselineFingerprint(db, options) {
+    const digest = createHash("sha256").update(JSON.stringify([VERSION, schemaVersion(db) ?? null, weekStart(options.now), options.minInteractions]));
+    for (const table of ["people", "person_emotion_baselines", "inside_out_deviations"]) {
+        digest.update(`|${tableExists(db, table) ? Number(db.prepare(`SELECT count(*) n FROM ${table}`).get().n) : -1}`);
+    }
+    if (tableExists(db, "inside_out")) {
+        const timing = db.prepare("SELECT count(*) n,sum(target_at<=?) due,sum(reviewed_at<=?) reviewed FROM inside_out").get(options.now, options.now);
+        digest.update(`|${timing.n},${timing.due},${timing.reviewed}`);
+        // Regrades rewrite reviewed_at; links and purges rewrite person_id and error.
+        for (const row of db.prepare("SELECT rowid,person_id,reviewed_at,error IS NULL ok FROM inside_out ORDER BY rowid").iterate()) {
+            digest.update(`|${row.rowid},${row.person_id},${row.reviewed_at},${row.ok}`);
+        }
+    }
+    return digest.digest("hex");
+}
 /**
  * Delete one person's baselines and assessment history. With `grades`, also erase their six
  * probabilities and person link, keeping a tombstone so the reply is never sent to Jev again.

package/dist/src/inside-out-store.d.ts

@@ -2,7 +2,10 @@ import type { DatabaseSync } from "node:sqlite";
 import { refreshEmotionBaselines } from "./emotion-baselines.js";
 export declare const PERSON_MATCH = "SELECT min(i.person_id) person_id FROM person_identities i\n  WHERE i.provider=e.channel AND i.external_id=e.sender_id\n  AND (i.account_scope=json_extract(e.human_key,'$[1]') OR substr(json_extract(e.human_key,'$[1]'),1,8)='session:')\n  HAVING count(DISTINCT i.person_id)=1";
 export declare function openInsideOutStore(path: string): DatabaseSync;
-/** Refresh People links without loading transcripts or calling Jev. Known accounts stay exact. Purged grades stay unlinked. */
+/**
+ * Refresh People links without loading transcripts or calling Jev. Known accounts stay exact.
+ * Purged grades stay unlinked. Matching is a read; only changed links are written, in short batches.
+ */
 export declare function linkInsideOutPeople(path: string): {
     updated: number;
     linked: number;
@@ -18,9 +21,30 @@ type BaselineResult = ReturnType<typeof refreshEmotionBaselines>;
 /** Rebuild local statistics from existing grades, refreshing exact People links first unless the caller just did. */
 export declare function refreshInsideOutBaselines(path: string, options?: BaselineOptions): BaselineResult;
 /**
- * Keep historical aggregation off the Gateway event loop; serialize refreshes per store.
- * Aborting skips queued work and terminates a running worker: SQLite rolls back its open
- * batch, committed batches are idempotent, and the next refresh resumes.
+ * Worker entry, also behind the synchronous API. `unless`: the fingerprint left by this store's
+ * previous refresh; unchanged inputs skip the pass.
+ * @public loaded by name from the worker thread
+ */
+export declare function refreshWithFingerprint(path: string, options: BaselineOptions & {
+    unless?: string;
+}): {
+    result: {
+        snapshots: number;
+        comparisons: number;
+    };
+    fingerprint?: undefined;
+} | {
+    result: {
+        snapshots: number;
+        comparisons: number;
+    };
+    fingerprint: string;
+};
+/**
+ * Keep historical aggregation off the Gateway event loop; serialize refreshes per store, and skip
+ * one whose inputs have not changed since this process's previous refresh of that store.
+ * Aborting skips queued work and terminates a running worker. Its connection closes with the
+ * worker, so SQLite rolls back the open batch; committed batches are idempotent and the next refresh resumes.
  */
 export declare function refreshInsideOutBaselinesAsync(path: string, options?: BaselineOptions, signal?: AbortSignal): Promise<{
     snapshots: number;

package/dist/src/inside-out-store.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { Worker } from "node:worker_threads";
 import { openMemoryDatabase } from "./memory-database.js";
-import { PURGED_GRADE, purgeEmotionProfile, refreshEmotionBaselines } from "./emotion-baselines.js";
+import { PURGED_GRADE, baselineFingerprint, purgeEmotionProfile, refreshEmotionBaselines, tableExists } from "./emotion-baselines.js";
 // Imported by the baseline worker with plain Node resolution: host SDK aliases do not
 // reach worker threads, so this module and its imports must stay free of `openclaw`.
 const SCHEMA = `CREATE TABLE IF NOT EXISTS inside_out (
@@ -38,15 +38,31 @@ export function openInsideOutStore(path) {
         throw error;
     }
 }
-/** Refresh People links without loading transcripts or calling Jev. Known accounts stay exact. Purged grades stay unlinked. */
+/**
+ * Refresh People links without loading transcripts or calling Jev. Known accounts stay exact.
+ * Purged grades stay unlinked. Matching is a read; only changed links are written, in short batches.
+ */
 export function linkInsideOutPeople(path) {
     const db = openInsideOutStore(path);
     try {
         let updated = 0;
-        if (db.prepare("SELECT 1 FROM sqlite_schema WHERE name='person_identities'").get()) {
+        if (tableExists(db, "person_identities")) {
             const person = `(${PERSON_MATCH})`;
-            updated = Number(db.prepare(`UPDATE inside_out AS e SET person_id=${person}
-        WHERE person_id IS NOT ${person} AND error IS NOT ?`).run(PURGED_GRADE).changes);
+            const changes = db.prepare(`SELECT e.rowid id,${person} person_id FROM inside_out e
+        WHERE e.person_id IS NOT ${person} AND e.error IS NOT ?`).all(PURGED_GRADE);
+            const link = db.prepare("UPDATE inside_out SET person_id=? WHERE rowid=? AND error IS NOT ?");
+            for (let start = 0; start < changes.length; start += 500) {
+                db.exec("BEGIN IMMEDIATE");
+                try {
+                    for (const change of changes.slice(start, start + 500))
+                        updated += Number(link.run(change.person_id, change.id, PURGED_GRADE).changes);
+                    db.exec("COMMIT");
+                }
+                catch (error) {
+                    db.exec("ROLLBACK");
+                    throw error;
+                }
+            }
         }
         const counts = db.prepare(`SELECT count(person_id) linked,count(*)-count(person_id) unlinked FROM inside_out`).get();
         return { updated, linked: Number(counts.linked), unlinked: Number(counts.unlinked) };
@@ -57,52 +73,70 @@ export function linkInsideOutPeople(path) {
 }
 /** Rebuild local statistics from existing grades, refreshing exact People links first unless the caller just did. */
 export function refreshInsideOutBaselines(path, options = {}) {
+    return refreshWithFingerprint(path, options).result;
+}
+/**
+ * Worker entry, also behind the synchronous API. `unless`: the fingerprint left by this store's
+ * previous refresh; unchanged inputs skip the pass.
+ * @public loaded by name from the worker thread
+ */
+export function refreshWithFingerprint(path, options) {
     if (!existsSync(path))
-        return { snapshots: 0, comparisons: 0 };
+        return { result: { snapshots: 0, comparisons: 0 } };
     if (options.link !== false)
         linkInsideOutPeople(path);
     const db = openInsideOutStore(path);
     try {
-        return refreshEmotionBaselines(db, { ...options, minInteractions: options.minInteractions ?? 20 });
+        const settings = { ...options, minInteractions: options.minInteractions ?? 20, now: options.now ?? Date.now() };
+        if (!options.recompare && options.unless && baselineFingerprint(db, settings) === options.unless) {
+            return { result: { snapshots: 0, comparisons: 0 }, fingerprint: options.unless };
+        }
+        const result = refreshEmotionBaselines(db, settings);
+        return { result, fingerprint: baselineFingerprint(db, settings) };
     }
     finally {
         db.close();
     }
 }
 const baselineJobs = new Map();
+const fingerprints = new Map();
 /**
- * Keep historical aggregation off the Gateway event loop; serialize refreshes per store.
- * Aborting skips queued work and terminates a running worker: SQLite rolls back its open
- * batch, committed batches are idempotent, and the next refresh resumes.
+ * Keep historical aggregation off the Gateway event loop; serialize refreshes per store, and skip
+ * one whose inputs have not changed since this process's previous refresh of that store.
+ * Aborting skips queued work and terminates a running worker. Its connection closes with the
+ * worker, so SQLite rolls back the open batch; committed batches are idempotent and the next refresh resumes.
  */
 export function refreshInsideOutBaselinesAsync(path, options = {}, signal) {
-    const settings = { ...options, now: options.now ?? Date.now() };
     const job = (baselineJobs.get(path) ?? Promise.resolve()).catch(() => { }).then(() => {
         signal?.throwIfAborted();
         if (!existsSync(path))
             return { snapshots: 0, comparisons: 0 };
+        const settings = { ...options, now: options.now ?? Date.now(), unless: fingerprints.get(path) };
         return new Promise((resolve, reject) => {
             const worker = new Worker(`
         const { parentPort, workerData } = require("node:worker_threads");
         // tsx's CLI preload only registers on the main thread. Source-mode
         // development needs explicit registration; compiled installs do not.
         if (workerData.module.endsWith(".ts")) require("node:module").createRequire(workerData.module)("tsx/esm/api").register();
-        import(workerData.module).then(({ refreshInsideOutBaselines }) => {
-          parentPort.postMessage(refreshInsideOutBaselines(workerData.path, workerData.options));
+        import(workerData.module).then(({ refreshWithFingerprint }) => {
+          parentPort.postMessage(refreshWithFingerprint(workerData.path, workerData.options));
         }).catch(error => { throw error; });
       `, { eval: true, workerData: { module: import.meta.url, path, options: settings } });
-            let result, aborted = false;
+            let outcome, aborted = false;
             const abort = () => { aborted = true; void worker.terminate(); };
             signal?.addEventListener("abort", abort, { once: true });
-            worker.once("message", (value) => { result = value; });
+            worker.once("message", (value) => { outcome = value; });
             worker.once("error", reject);
             // Settle only after the worker closes its database and exits.
             worker.once("exit", code => {
                 signal?.removeEventListener("abort", abort);
                 if (aborted)
                     reject(signal.reason);
-                else if (code === 0 && result)
-                    resolve(result);
+                else if (code === 0 && outcome) {
+                    if (outcome.fingerprint)
+                        fingerprints.set(path, outcome.fingerprint);
+                    resolve(outcome.result);
+                }
                 else
                     reject(new Error(`Inside Out baseline worker exited without a result (code ${code})`));
             });
@@ -121,12 +155,15 @@ export function purgeInsideOutPerson(path, personId, options = {}) {
     // Never create Inside Out tables in a store that has none.
     const probe = openMemoryDatabase(path);
     try {
-        if (!probe.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='inside_out'").get())
+        if (!tableExists(probe, "inside_out"))
             return { baselines: 0, assessments: 0, grades: 0 };
     }
     finally {
         probe.close();
     }
+    // Erasing grades must cover replies linked to this person since the last refresh.
+    if (options.grades)
+        linkInsideOutPeople(path);
     const db = openInsideOutStore(path);
     try {
         return purgeEmotionProfile(db, personId, options);

package/dist/src/inside-out.js

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { stripReasoningTagsFromText } from "openclaw/plugin-sdk/text-chunking";
@@ -6,7 +5,7 @@ import { messageText } from "./whisperer-context.js";
 import { conversationUserText } from "./response-text.js";
 import { estimateJevTokens, requestTypeSafe, resolveTypeSafeApiKey, TYPESAFE_MODEL } from "./typesafe-client.js";
 import { readInsideOutSources } from "./inside-out-sources.js";
-import { INSIDE_OUT_EMOTIONS, PURGED_GRADE, deviationReader, emotionBaselineHistory } from "./emotion-baselines.js";
+import { INSIDE_OUT_EMOTIONS, PURGED_GRADE, deviationReader, emotionBaselineHistory, hash, tableExists } from "./emotion-baselines.js";
 import { PERSON_MATCH, openInsideOutStore, refreshInsideOutBaselinesAsync } from "./inside-out-store.js";
 export { linkInsideOutPeople, purgeInsideOutPerson, refreshInsideOutBaselines, refreshInsideOutBaselinesAsync } from "./inside-out-store.js";
 const RUBRIC = "emotion-presence-v2";
@@ -52,7 +51,6 @@ export function resolveInsideOut(value) {
     return { enabled, intervalMinutes: integer("intervalMinutes", 0, 10080), maxInteractions: integer("maxInteractions", 1, 10000),
         maxContextTokens: integer("maxContextTokens", 256, 30000), baselineMinInteractions: integer("baselineMinInteractions", 1, 10000) };
 }
-const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 function humanIdentity(source, message) {
     const meta = message.__openclaw, identity = meta?.senderIdentity;
     const channel = meta?.transport?.channel ?? identity?.pluginId ?? message.sourceChannel ?? source.channel;
@@ -176,7 +174,7 @@ export async function runInsideOut(options) {
     const result = { reviewed: 0, cached: 0, failed: 0, sources: 0, skippedSources: 0, errors: [] };
     try {
         store = openInsideOutStore(storePath);
-        const person = store.prepare("SELECT 1 FROM sqlite_schema WHERE name='person_identities'").get()
+        const person = tableExists(store, "person_identities")
             ? store.prepare(`SELECT (${PERSON_MATCH}) person_id FROM (SELECT ? channel,? human_key,? sender_id) e`)
             : undefined;
         const existing = store.prepare("SELECT 1 FROM inside_out WHERE interaction_id=? AND rubric=?");
@@ -315,7 +313,7 @@ export function reportInsideOut(path, options = {}) {
         return [];
     const db = new DatabaseSync(path, { readOnly: true });
     try {
-        if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE name='inside_out'").get())
+        if (!tableExists(db, "inside_out"))
             return [];
         if (options.personId && !db.prepare("SELECT 1 FROM pragma_table_info('inside_out') WHERE name='person_id'").get())
             return [];

package/dist/src/plugin.js

@@ -494,6 +494,11 @@ export function registerUnblockMemory(api) {
         api.on("gateway_stop", () => peopleStores.closeAll());
     }
     const diagnostics = WhispererDiagnostics.shared();
+    // The manifest sets no default for `enabled`, so true here was written by the operator.
+    const skillSettings = api.pluginConfig?.skillWhisperer;
+    if (skillSettings?.enabled === true && !config.skillWhisperer.enabled) {
+        api.logger.warn('unblock-memory skillWhisperer.enabled is true but no corpus has kind "skills"; Skill Whisperer is inactive');
+    }
     registerWhispererPrompt(api, {
         memory: registerMemoryWhisperer(api, runtime, config.memoryWhisperer, config.typesafe, diagnostics),
         skill: registerSkillWhisperer(api, runtime, config.skillWhisperer, config.typesafe, diagnostics),

package/docs/configuration.md

@@ -220,7 +220,7 @@ contract; these tables explain their effects.
 | `typesafe.apiKey` | Unset | Explicit inline key; mutually exclusive with key file; prefer file |
 | `typesafe.apiKeyFile` | Unset | Absolute raw-key or dotenv file, reread at credential resolution; explicit missing file never falls back to a different key |
 | `typesafe.timeoutMs` | `1500` | 1–10,000 per request for Skill/Memory Whisperer, quality/claim/cluster review and response audit; **primer and dossier save use `peoplePrimer.timeoutMs` and Safety Whisperer uses `safetyWhisperer.timeoutMs` instead** |
-| `skillWhisperer.enabled` | `true` | Active only with a `skills` corpus (otherwise resolved to `false`, with no hook or host warning) and appropriate host hook access; fixed 3-second total deadline; `false` opts out |
+| `skillWhisperer.enabled` | `true` with a `skills` corpus, else `false` | Needs appropriate host hook access; fixed 3-second total deadline; `false` opts out. An explicit `true` without a skills corpus logs a warning and stays inactive |
 | `skillWhisperer.historyMessages` | `5` | Nonnegative integer; prior visible messages used for routing |
 | `skillWhisperer.minScore` | `0.5` | 0–1, **local vector fallback only**, ignored for TypeSafe shortlist admission |
 | `skillWhisperer.cooldownTurns` | `10` | Nonnegative user-turn count; no fallback to weaker cooling-down alternatives |
@@ -706,12 +706,17 @@ Historical aggregation runs in a worker thread and commits in short batches, so
 Gateway event loop stays responsive and other writers to `unblock-memory.sqlite`
 wait for one batch at most, never a whole refresh. Gateway shutdown cancels an
 active refresh; the next one resumes, and repeating a refresh never duplicates
-records. If the refresh after grading fails, `run` still returns its counts with a
+records. The Gateway skips a refresh when nothing it reads (grades, links, people,
+stored results, the current week or settings) has changed since its previous one.
+People links are matched with a read, and only changed links are written, in short
+batches. If the refresh after grading fails, `run` still returns its counts with a
 `baselineError` (the Gateway logs a warning); saved grades are unaffected.
 `link-people` also refreshes analytics. `baseline-refresh` does this without loading
 transcripts, calling Jev, or requiring TypeSafe credentials. `baselines` reads
 weekly snapshots, newest first, with optional `--person`, `--since YYYY-MM-DD`
-(inclusive UTC week-end) and `--limit` (1–1,000 weeks, default 100).
+(weeks whose last day, a Sunday, is on or after that UTC date) and `--limit`
+(1–1,000 weeks, default 100). It reads from one consistent snapshot, even while a
+refresh is writing.
 
 Snapshots always reflect the currently linked grades. A late historical grade, a
 retry, a relink or removed identity evidence rewrites the affected week and every
@@ -725,8 +730,9 @@ grades change snapshots but do not silently rewrite earlier comparisons.
 Use `baseline-refresh --recompare` to append changed assessments after backfill,
 identity or sample-policy changes; `export --deviation-history` includes the earlier
 results and marks which match the current grade. Repeating an unchanged refresh
-adds no duplicate records. Previously sparse or future-dated assessments also need
-explicit re-comparison when their circumstances change.
+adds no duplicate records. A `future_time` assessment is redone automatically once
+the reply's time has passed. Previously sparse assessments need explicit
+re-comparison after backfill adds earlier history.
 
 `computed_at` and `assessedAt` record when these calculations actually occurred.
 A backfilled comparison uses retained evidence from earlier interaction weeks, but
@@ -751,8 +757,12 @@ removed. It makes no Jev calls.
 - **With `--grades`**, it also erases the six probabilities of every reply currently
   linked to that person and unlinks it. Each row stays as a tombstone with the error
   `Purged by operator`, so `run` (including `--retry`) never sends that reply to Jev
-  again, `link-people` never relinks it, and refreshes skip it. This cannot be
-  undone; run `link-people` first so every reply from that person is linked.
+  again, `link-people` never relinks it, and refreshes skip it. Purge refreshes
+  People links first, so replies linked since the last refresh are included. This
+  cannot be undone.
+
+A refresh already running when `purge` commits rechecks every grade before writing,
+so it cannot restore the purged data.
 
 Purging removes existing data only. While Inside Out stays enabled and the person's
 identity remains in PeopleSQL, their new replies are graded and start a new

package/docs/retrieval.md

@@ -472,7 +472,8 @@ Skill Whisperer is a semantic reminder for user turns. It turns on by default on
 you configure one isolated `skills` corpus and authorize
 `plugins.entries.unblock-memory.hooks.allowConversationAccess`. Without a skills
 corpus it stays inactive: no prompt hook is registered and diagnostics report it
-disabled. Set `skillWhisperer.enabled` to `false` to opt out. It
+disabled; an explicit `skillWhisperer.enabled: true` without one logs a warning.
+Set `skillWhisperer.enabled` to `false` to opt out. It
 embeds the current prompt plus the configured number of prior user/assistant
 messages, compares it with each configured skill's frontmatter `name` and
 `description`. With TypeSafe enabled and a key available, the top three valid

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": true },
@@ -349,13 +349,12 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "enabled": { "type": "boolean", "default": true, "description": "Takes effect only when a corpus with kind \"skills\" is configured." },
+          "enabled": { "type": "boolean", "description": "Defaults to true when a corpus with kind \"skills\" is configured, otherwise false. An explicit true without one is ignored with a warning." },
           "historyMessages": { "type": "integer", "minimum": 0, "default": 5 },
           "minScore": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 },
           "cooldownTurns": { "type": "integer", "minimum": 0, "default": 10 }
         },
         "default": {
-          "enabled": true,
           "historyMessages": 5,
           "minScore": 0.5,
           "cooldownTurns": 10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",