openclaw-hybrid-memory 2026.3.310 → 2026.4.11

package/backends/facts-db/fact-queries.ts

@@ -15,9 +15,13 @@ export function fetchSupersededFactTextsLower(db: DatabaseSync): string[] {
  * OR-joined quoted FTS terms (+ optional prefix terms) for classification-style lookups (#898 alignment with porter).
  */
 /** Broader OR clause for `FactsDB.search()` (min term length 1, all tokens, porter prefix). */
-export function buildFactsSearchFtsOrClause(query: string): string | null {
+export function buildFactsSearchFtsOrClause(query: string, options?: { maxOrTerms?: number }): string | null {
   const sanitized = sanitizeFts5QueryForFacts(query);
-  const terms = sanitized.split(/\s+/).filter((w) => w.length > 1);
+  let terms = sanitized.split(/\s+/).filter((w) => w.length > 1);
+  const cap = options?.maxOrTerms;
+  if (cap !== undefined && cap > 0 && terms.length > cap) {
+    terms = terms.slice(0, cap);
+  }
   if (terms.length === 0) return null;
   const parts = terms.map((w) => {
     if (/^[a-zA-Z0-9_]+$/.test(w) && w.length >= 3) {

package/backends/facts-db.ts

@@ -25,6 +25,7 @@ import { applyConsolidationRetrievalControls } from "../utils/consolidation-cont
 import { computeDynamicSalience } from "../utils/salience.js";
 import { estimateTokensForDisplay } from "../utils/text.js";
 import { capturePluginError } from "../services/error-reporter.js";
+import { INTERACTIVE_FTS_MAX_OR_TERMS } from "../utils/constants.js";
 import { getLanguageKeywordsFilePath } from "../utils/language-keywords.js";
 import { createTransaction } from "../utils/sqlite-transaction.js";
 import { tryRestrictSqliteDbFileMode } from "../utils/sqlite-file-perms.js";
@@ -1964,6 +1965,11 @@ export class FactsDB extends BaseSqliteStore {
       reinforcementBoost?: number;
       /** Weight applied to diversity score when calculating effective boost (default: 1.0). */
       diversityWeight?: number;
+      /**
+       * Interactive auto-recall hot path: cap FTS OR-term explosion and avoid loading full fact rows
+       * until top matches are chosen (reduces WhatsApp/gateway stalls from huge MATCH + wide SELECT f.*).
+       */
+      interactiveFtsFastPath?: boolean;
     } = {},
   ): SearchResult[] {
     const {
@@ -1975,9 +1981,12 @@ export class FactsDB extends BaseSqliteStore {
       scopeFilter,
       reinforcementBoost = 0.1,
       diversityWeight = 1.0,
+      interactiveFtsFastPath = false,
     } = options;
 
-    const safeQuery = buildFactsSearchFtsOrClause(query);
+    const safeQuery = interactiveFtsFastPath
+      ? buildFactsSearchFtsOrClause(query, { maxOrTerms: INTERACTIVE_FTS_MAX_OR_TERMS })
+      : buildFactsSearchFtsOrClause(query);
     if (!safeQuery) return [];
 
     const nowSec = Math.floor(Date.now() / 1000);
@@ -1993,9 +2002,70 @@ export class FactsDB extends BaseSqliteStore {
     const tierFilterClause = tierFilter === "warm" ? "AND (f.tier IS NULL OR f.tier = 'warm' OR f.tier = 'hot')" : "";
     const { clause: scopeFilterClauseStr, params: scopeParams } = this.scopeFilterClause(scopeFilter);
 
-    const rows = this.liveDb
-      .prepare(
-        `SELECT f.*, bm25(facts_fts) as fts_score,
+    const decayWindowSec = 7 * 24 * 3600;
+    const paramBag: Record<string, SQLInputValue> = {
+      "@query": safeQuery,
+      "@now": nowSec,
+      ...(asOf != null ? { "@asOf": asOf } : {}),
+      "@limit": limit * 2,
+      "@decay_window": decayWindowSec,
+      ...(tagPattern ? { "@tagPattern": tagPattern } : {}),
+      ...scopeParams,
+    };
+
+    let rows: Array<Record<string, unknown>>;
+
+    if (interactiveFtsFastPath) {
+      // node:sqlite rejects named parameters not referenced by the prepared SQL — omit @decay_window for the narrow query.
+      const narrowParamBag: Record<string, SQLInputValue> = {
+        "@query": safeQuery,
+        "@now": nowSec,
+        ...(asOf != null ? { "@asOf": asOf } : {}),
+        "@limit": limit * 2,
+        ...(tagPattern ? { "@tagPattern": tagPattern } : {}),
+        ...scopeParams,
+      };
+      const narrowSql = `SELECT f.id AS id, fts.rank AS fts_score
+         FROM facts f
+         JOIN facts_fts fts ON f.rowid = fts.rowid
+         WHERE facts_fts MATCH @query
+           ${expiryFilter}
+           ${temporalFilter}
+           ${tagFilter}
+           ${tierFilterClause}
+           ${scopeFilterClauseStr}
+         ORDER BY fts.rank
+         LIMIT @limit`;
+      const narrowRows = this.liveDb.prepare(narrowSql).all(narrowParamBag) as Array<{ id: string; fts_score: number }>;
+      if (narrowRows.length === 0) return [];
+      const ids = narrowRows.map((r) => r.id);
+      const ftsById = new Map(narrowRows.map((r) => [r.id, r.fts_score]));
+      const placeholders = ids.map(() => "?").join(",");
+      const fullRows = this.liveDb.prepare(`SELECT * FROM facts WHERE id IN (${placeholders})`).all(...ids) as Array<
+        Record<string, unknown>
+      >;
+      const byId = new Map(fullRows.map((r) => [r.id as string, r]));
+      const decayWindow = decayWindowSec;
+      rows = [];
+      for (const id of ids) {
+        const row = byId.get(id);
+        if (!row) continue;
+        const expiresAt = row.expires_at as number | null | undefined;
+        let freshness: number;
+        if (expiresAt == null) freshness = 1.0;
+        else if (expiresAt <= nowSec) freshness = 0.0;
+        else freshness = Math.min(1.0, (expiresAt - nowSec) / decayWindow);
+        rows.push({
+          ...row,
+          fts_score: ftsById.get(id) as number,
+          freshness,
+        });
+      }
+      if (rows.length === 0) return [];
+    } else {
+      rows = this.liveDb
+        .prepare(
+          `SELECT f.*, bm25(facts_fts) as fts_score,
            CASE
              WHEN f.expires_at IS NULL THEN 1.0
              WHEN f.expires_at <= @now THEN 0.0
@@ -2011,16 +2081,9 @@ export class FactsDB extends BaseSqliteStore {
            ${scopeFilterClauseStr}
          ORDER BY bm25(facts_fts)
          LIMIT @limit`,
-      )
-      .all({
-        "@query": safeQuery,
-        "@now": nowSec,
-        ...(asOf != null ? { "@asOf": asOf } : {}),
-        "@limit": limit * 2,
-        "@decay_window": 7 * 24 * 3600,
-        ...(tagPattern ? { "@tagPattern": tagPattern } : {}),
-        ...scopeParams,
-      }) as Array<Record<string, unknown>>;
+        )
+        .all(paramBag) as Array<Record<string, unknown>>;
+    }
 
     if (rows.length === 0) return [];
 

package/cli/cmd-config.ts

@@ -199,7 +199,17 @@ export function runConfigViewForCli(ctx: HandlerContext, sink: VerifyCliSink): v
     }`,
   );
   log(`  Retrieval directives: ${on(cfg.autoRecall.retrievalDirectives?.enabled ?? false)}`);
-  log(`  Entity lookup: ${on(cfg.autoRecall.entityLookup.enabled)}`);
+  const el = cfg.autoRecall.entityLookup;
+  const entityNames = Array.isArray(el?.entities) ? el.entities : [];
+  const autoFromFacts = el?.autoFromFacts !== false;
+  const maxAutoEntities = typeof el?.maxAutoEntities === "number" && el.maxAutoEntities > 0 ? el.maxAutoEntities : 500;
+  const entitySrc =
+    entityNames.length > 0
+      ? `${entityNames.length} configured name(s)`
+      : autoFromFacts
+        ? `auto from facts (cap ${maxAutoEntities})`
+        : "manual list empty (auto off)";
+  log(`  Entity lookup: ${on(el?.enabled ?? false)} — ${entitySrc}`);
   log("");
 
   log("To change a setting: openclaw hybrid-mem config-set <key> <value>");

package/config/parsers/retrieval.ts

@@ -50,6 +50,10 @@ export function parseAutoRecallConfig(cfg: Record<string, unknown>): AutoRecallC
     const preferLongTerm = ar.preferLongTerm === true;
     const useImportanceRecency = ar.useImportanceRecency === true;
     const entityLookupRaw = ar.entityLookup as Record<string, unknown> | undefined;
+    const maxAutoRaw =
+      typeof entityLookupRaw?.maxAutoEntities === "number" && entityLookupRaw.maxAutoEntities > 0
+        ? Math.max(1, Math.floor(entityLookupRaw.maxAutoEntities))
+        : 500;
     const entityLookup: EntityLookupConfig = {
       enabled: entityLookupRaw?.enabled === true,
       entities: Array.isArray(entityLookupRaw?.entities)
@@ -59,6 +63,8 @@ export function parseAutoRecallConfig(cfg: Record<string, unknown>): AutoRecallC
         typeof entityLookupRaw?.maxFactsPerEntity === "number" && entityLookupRaw.maxFactsPerEntity > 0
           ? Math.floor(entityLookupRaw.maxFactsPerEntity)
           : 2,
+      autoFromFacts: entityLookupRaw?.autoFromFacts !== false,
+      maxAutoEntities: Math.min(2000, maxAutoRaw),
     };
     const summaryThreshold =
       typeof ar.summaryThreshold === "number" && ar.summaryThreshold >= 0 ? ar.summaryThreshold : 300;
@@ -116,6 +122,13 @@ export function parseAutoRecallConfig(cfg: Record<string, unknown>): AutoRecallC
       typeof ar.progressivePinnedRecallCount === "number" && ar.progressivePinnedRecallCount >= 0
         ? Math.floor(ar.progressivePinnedRecallCount)
         : 3;
+    const VALID_ENRICHMENT = ["fast", "balanced", "full"] as const;
+    const interactiveEnrichmentRaw = ar.interactiveEnrichment;
+    const interactiveEnrichment =
+      typeof interactiveEnrichmentRaw === "string" &&
+      (VALID_ENRICHMENT as readonly string[]).includes(interactiveEnrichmentRaw)
+        ? (interactiveEnrichmentRaw as (typeof VALID_ENRICHMENT)[number])
+        : "balanced";
     const scopeFilterRaw = ar.scopeFilter as Record<string, unknown> | undefined;
     const scopeFilter =
       scopeFilterRaw && typeof scopeFilterRaw === "object" && !Array.isArray(scopeFilterRaw)
@@ -178,6 +191,7 @@ export function parseAutoRecallConfig(cfg: Record<string, unknown>): AutoRecallC
         typeof ar.degradationMaxLatencyMs === "number" && ar.degradationMaxLatencyMs >= 0
           ? Math.floor(ar.degradationMaxLatencyMs)
           : 5000,
+      interactiveEnrichment,
     };
   }
   return {
@@ -189,7 +203,7 @@ export function parseAutoRecallConfig(cfg: Record<string, unknown>): AutoRecallC
     minScore: 0.3,
     preferLongTerm: false,
     useImportanceRecency: false,
-    entityLookup: { enabled: false, entities: [], maxFactsPerEntity: 2 },
+    entityLookup: { enabled: false, entities: [], maxFactsPerEntity: 2, autoFromFacts: true, maxAutoEntities: 500 },
     retrievalDirectives: {
       enabled: true,
       entityMentioned: true,
@@ -216,6 +230,7 @@ export function parseAutoRecallConfig(cfg: Record<string, unknown>): AutoRecallC
       maxRecallsPerTarget: 1,
       includeVaultHints: true,
     },
+    interactiveEnrichment: "balanced",
   };
 }
 

package/config/types/retrieval.ts

@@ -18,6 +18,13 @@ export type EntityLookupConfig = {
   enabled: boolean;
   entities: string[]; // e.g. ["user", "owner", "decision"]; prompt matched case-insensitively
   maxFactsPerEntity: number; // max facts to merge per matched entity (default 2)
+  /**
+   * When `entities` is empty, load names from the facts table (`SELECT DISTINCT entity`).
+   * Default true. Set false to require an explicit `entities` list (legacy no-op when empty).
+   */
+  autoFromFacts: boolean;
+  /** Max distinct entity names to consider when using autoFromFacts (default 500, max 2000). */
+  maxAutoEntities: number;
 };
 
 /** Auto-recall on authentication failures (reactive memory trigger) */
@@ -82,6 +89,13 @@ export type AutoRecallConfig = {
   degradationQueueDepth?: number;
   /** Phase 2.1: Hard degradation. When recall latency (ms) exceeds this value, use FTS-only + HOT and set degraded. 0 = disabled. Default 5000. */
   degradationMaxLatencyMs?: number;
+  /**
+   * Single control for **interactive** chat-turn recall cost/latency (HyDE + ambient multi-query).
+   * - **fast** — No HyDE on the hot path, no extra ambient `runRecallPipelineQuery` calls (lowest latency/cost; still runs main FTS+vector recall when semantic is enabled).
+   * - **balanced** (default) — Respects `queryExpansion.skipForInteractiveTurns` and `ambient.enabled` / `ambient.multiQuery` as today.
+   * - **full** — When `queryExpansion.enabled`, runs HyDE on interactive turns regardless of `skipForInteractiveTurns`; allows ambient multi-query when `autoRecall.enabled` and ambient is configured.
+   */
+  interactiveEnrichment?: "fast" | "balanced" | "full";
 };
 
 /** Multi-strategy retrieval pipeline configuration (Issue #152: RRF scoring pipeline). */

package/config/utils.ts

@@ -33,7 +33,14 @@ export function isValidCategory(cat: string): boolean {
 export const PRESET_OVERRIDES: Record<ConfigMode, Record<string, unknown>> = {
   local: {
     autoCapture: true,
-    autoRecall: { enabled: true, entityLookup: { enabled: false }, authFailure: { enabled: false } },
+    /** Credentials vault on; set `credentials.encryptionKey` (16+ chars or env:VAR) for encryption at rest. */
+    credentials: { enabled: true },
+    autoRecall: {
+      enabled: true,
+      interactiveEnrichment: "fast",
+      entityLookup: { enabled: false },
+      authFailure: { enabled: false },
+    },
     autoClassify: { enabled: false, suggestCategories: false },
     store: { fuzzyDedupe: true, classifyBeforeWrite: false },
     graph: { enabled: false },
@@ -51,7 +58,13 @@ export const PRESET_OVERRIDES: Record<ConfigMode, Record<string, unknown>> = {
   /** Minimal: nano for auto-classify, default (flash) for distill — good value at low cost. Ingest paths on so occasional ingest-files gets facts. */
   minimal: {
     autoCapture: true,
-    autoRecall: { enabled: true, entityLookup: { enabled: false }, authFailure: { enabled: true } },
+    credentials: { enabled: true },
+    autoRecall: {
+      enabled: true,
+      interactiveEnrichment: "fast",
+      entityLookup: { enabled: false },
+      authFailure: { enabled: true },
+    },
     autoClassify: { enabled: true, suggestCategories: true },
     store: { fuzzyDedupe: false, classifyBeforeWrite: false },
     graph: { enabled: true, autoLink: false, useInRecall: true, strengthenOnRecall: false },
@@ -67,7 +80,12 @@ export const PRESET_OVERRIDES: Record<ConfigMode, Record<string, unknown>> = {
   },
   enhanced: {
     autoCapture: true,
-    autoRecall: { enabled: true, entityLookup: { enabled: true }, authFailure: { enabled: true } },
+    autoRecall: {
+      enabled: true,
+      interactiveEnrichment: "fast",
+      entityLookup: { enabled: true },
+      authFailure: { enabled: true },
+    },
     autoClassify: { enabled: true, suggestCategories: true },
     credentials: { autoDetect: true, autoCapture: { toolCalls: true } },
     store: { fuzzyDedupe: true, classifyBeforeWrite: true },
@@ -104,7 +122,12 @@ export const PRESET_OVERRIDES: Record<ConfigMode, Record<string, unknown>> = {
   },
   complete: {
     autoCapture: true,
-    autoRecall: { enabled: true, entityLookup: { enabled: true }, authFailure: { enabled: true } },
+    autoRecall: {
+      enabled: true,
+      interactiveEnrichment: "fast",
+      entityLookup: { enabled: true },
+      authFailure: { enabled: true },
+    },
     autoClassify: { enabled: true, suggestCategories: true },
     credentials: { autoDetect: true, autoCapture: { toolCalls: true } },
     store: { fuzzyDedupe: true, classifyBeforeWrite: true },

package/lifecycle/hooks.ts

@@ -2,7 +2,7 @@ import { getEnv } from "../utils/env-manager.js";
 /**
  * Lifecycle Hooks (Phase 2.3: staged pipeline).
  *
- * Dispatcher: registers before_agent_start, agent_end, subagent, and frustration handlers.
+ * Dispatcher: registers before_agent_start, agent_end, and frustration handlers (subagent hooks: stage-cleanup).
  * All stage logic lives in stage-*.ts and session-state.ts; this file stays <200 lines.
  */
 

package/lifecycle/resolve-agent-id.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the active agent id for lifecycle hooks (`before_agent_start`, etc.).
+ *
+ * OpenClaw should populate `api.context.agentId` for routed channels; some builds
+ * only pass identity on the event payload. This module centralizes best-effort
+ * extraction so WhatsApp and similar routes can be recognized without duplicating
+ * ad-hoc field checks across stages.
+ */
+
+import type { ClawdbotPluginApi } from "openclaw/plugin-sdk/core";
+
+function nonEmptyString(v: unknown): string | null {
+  if (typeof v !== "string") return null;
+  const t = v.trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * @returns Detected agent id, or `null` if nothing usable was found.
+ */
+export function resolveAgentIdFromHookEvent(event: unknown, api: ClawdbotPluginApi): string | null {
+  const ev = event as Record<string, unknown>;
+  const session = ev.session as Record<string, unknown> | undefined;
+  const run = ev.run as Record<string, unknown> | undefined;
+  const payloadCtx = ev.context as Record<string, unknown> | undefined;
+  const activeAgent = session?.activeAgent;
+
+  return (
+    nonEmptyString(ev.agentId) ??
+    nonEmptyString(session?.agentId) ??
+    nonEmptyString(session?.agent) ??
+    nonEmptyString(session?.activeAgentId) ??
+    nonEmptyString(session?.botId) ??
+    nonEmptyString(session?.routedAgentId) ??
+    (activeAgent && typeof activeAgent === "object"
+      ? nonEmptyString((activeAgent as Record<string, unknown>).id)
+      : null) ??
+    nonEmptyString(run?.agentId) ??
+    nonEmptyString(payloadCtx?.agentId) ??
+    nonEmptyString(api.context?.agentId)
+  );
+}

package/lifecycle/stage-auth-failure.ts

@@ -96,6 +96,7 @@ export function registerAuthFailureRecall(
         scopeFilter,
         reinforcementBoost: ctx.cfg.distill?.reinforcementBoost ?? 0.1,
         diversityWeight: ctx.cfg.reinforcement?.diversityWeight ?? 1.0,
+        interactiveFtsFastPath: true,
       });
       const vector = await ctx.embeddings.embed(query);
       let lanceResults = await ctx.vectorDb.search(vector, 5, 0.3);

package/lifecycle/stage-cleanup.ts

@@ -1,6 +1,6 @@
 /**
  * Lifecycle stage: Cleanup (Phase 2.3).
- * Subagent_start/subagent_end handlers, stale session sweep timer, dispose.
+ * OpenClaw typed hooks **subagent_spawned** / **subagent_ended** (issue #966), stale session sweep timer, dispose.
  * Exports: consumePendingTaskSignals, registerCleanupHandlers, createStaleSweepTimer, getDispose.
  */
 
@@ -26,6 +26,38 @@ import type { LifecycleContext, SessionState } from "./types.js";
 const STALE_SESSION_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const STALE_SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
 
+/** OpenClaw core dispatch shapes — see issue #966 / runSubagentSpawned */
+type SubagentSpawnedEvent = {
+  childSessionKey?: string;
+  /** Legacy / alternate field names from older handlers */
+  sessionKey?: string;
+  label?: string;
+  task?: string;
+  agentId?: string;
+  runId?: string;
+};
+
+/** OpenClaw core dispatch shapes — see issue #966 / runSubagentEnded */
+type SubagentEndedEvent = {
+  targetSessionKey?: string;
+  sessionKey?: string;
+  label?: string;
+  success?: boolean;
+  outcome?: string;
+  error?: string;
+  reason?: string;
+  runId?: string;
+};
+
+function subagentEndedIsSuccess(ev: SubagentEndedEvent): boolean {
+  if (typeof ev.success === "boolean") return ev.success;
+  const o = (ev.outcome ?? "").toLowerCase();
+  if (!o) return true;
+  if (["error", "timeout", "killed", "failed", "failure"].includes(o)) return false;
+  if (["success", "completed", "ok", "done"].includes(o)) return true;
+  return true;
+}
+
 /**
  * Read all pending task signals from `memory/task-signals/*.json` and apply
  * their status changes to ACTIVE-TASK.md. Called after subagent completes.
@@ -276,7 +308,8 @@ export function getDispose(timerRef: ReturnType<typeof setInterval> | null, sess
 }
 
 /**
- * Register subagent_start and subagent_end handlers (active-task checkpoint + signal consumption).
+ * Register **subagent_spawned** and **subagent_ended** handlers (active-task checkpoint + signal consumption).
+ * Hook names must match OpenClaw `PLUGIN_HOOK_NAMES` (issue #966).
  */
 export function registerCleanupHandlers(
   api: ClawdbotPluginApi,
@@ -287,11 +320,12 @@ export function registerCleanupHandlers(
 ): void {
   if (!ctx.cfg.activeTask.enabled || !ctx.cfg.activeTask.autoCheckpoint) return;
 
-  api.on("subagent_start", async (event: unknown) => {
+  api.on("subagent_spawned", async (event: unknown) => {
     try {
-      const ev = event as { sessionKey?: string; label?: string; task?: string; agentId?: string };
-      const label = ev.label ?? ev.sessionKey ?? `subagent-${Date.now()}`;
-      const description = ev.task ?? `Subagent task (session: ${ev.sessionKey ?? "unknown"})`;
+      const ev = event as SubagentSpawnedEvent;
+      const childOrSession = ev.childSessionKey ?? ev.sessionKey;
+      const label = ev.label ?? childOrSession ?? `subagent-${Date.now()}`;
+      const description = ev.task ?? `Subagent task (session: ${childOrSession ?? "unknown"})`;
       const taskFile = await readActiveTaskFile(
         resolvedActiveTaskPath,
         parseDuration(ctx.cfg.activeTask.staleThreshold),
@@ -304,7 +338,7 @@ export function registerCleanupHandlers(
         label,
         description,
         status: "In progress",
-        subagent: ev.sessionKey,
+        subagent: childOrSession,
         started: existing?.started ?? now,
         updated: now,
       };
@@ -316,23 +350,23 @@ export function registerCleanupHandlers(
         api.context?.sessionKey,
       );
       if (writeResult.skipped) {
-        api.logger.debug?.(`memory-hybrid: skipped ACTIVE-TASK.md write in subagent_start: ${writeResult.reason}`);
+        api.logger.debug?.(`memory-hybrid: skipped ACTIVE-TASK.md write in subagent_spawned: ${writeResult.reason}`);
       } else {
         api.logger.info?.(`memory-hybrid: auto-checkpoint — created active task [${label}] for subagent spawn`);
       }
     } catch (err) {
       capturePluginError(err instanceof Error ? err : new Error(String(err)), {
-        operation: "active-task-subagent-start",
+        operation: "active-task-subagent-spawned",
         subsystem: "active-task",
       });
-      api.logger.debug?.(`memory-hybrid: active task auto-checkpoint on subagent_start failed: ${err}`);
+      api.logger.debug?.(`memory-hybrid: active task auto-checkpoint on subagent_spawned failed: ${err}`);
     }
   });
 
-  api.on("subagent_end", async (event: unknown) => {
+  api.on("subagent_ended", async (event: unknown) => {
     try {
-      const ev = event as { sessionKey?: string; label?: string; success?: boolean; error?: string };
-      const label = ev.label ?? ev.sessionKey;
+      const ev = event as SubagentEndedEvent;
+      const label = ev.label ?? ev.targetSessionKey ?? ev.sessionKey;
       const staleMinutes = parseDuration(ctx.cfg.activeTask.staleThreshold);
       if (!label) {
         await consumePendingTaskSignals(
@@ -370,7 +404,7 @@ export function registerCleanupHandlers(
       }
 
       const now = new Date().toISOString();
-      const newStatus = ev.success === false ? "Failed" : "Done";
+      const newStatus = subagentEndedIsSuccess(ev) ? "Done" : "Failed";
 
       if (newStatus === "Done") {
         const { updated, completed } = completeTask(taskFile.active, label);
@@ -383,7 +417,7 @@ export function registerCleanupHandlers(
           );
           if (writeResult.skipped) {
             api.logger.debug?.(
-              `memory-hybrid: skipped ACTIVE-TASK.md write in subagent_end (Done): ${writeResult.reason}`,
+              `memory-hybrid: skipped ACTIVE-TASK.md write in subagent_ended (Done): ${writeResult.reason}`,
             );
           } else {
             if (ctx.cfg.activeTask.flushOnComplete) {
@@ -391,16 +425,17 @@ export function registerCleanupHandlers(
               await flushCompletedTaskToMemory(completed, memoryDir).catch(() => {});
             }
             api.logger.info?.(
-              `memory-hybrid: auto-checkpoint — updated task [${label}] to ${newStatus} on subagent_end`,
+              `memory-hybrid: auto-checkpoint — updated task [${label}] to ${newStatus} on subagent_ended`,
             );
           }
         }
       } else {
+        const errHint = ev.error ?? ev.reason;
         const updatedEntry: ActiveTaskEntry = {
           ...existingTask,
           status: "Failed",
           updated: now,
-          next: ev.error ? `Fix: ${ev.error.slice(0, 100)}` : existingTask.next,
+          next: errHint ? `Fix: ${String(errHint).slice(0, 100)}` : existingTask.next,
         };
         const updated = upsertTask(taskFile.active, updatedEntry);
         const writeResult = await writeActiveTaskFileGuarded(
@@ -411,10 +446,12 @@ export function registerCleanupHandlers(
         );
         if (writeResult.skipped) {
           api.logger.debug?.(
-            `memory-hybrid: skipped ACTIVE-TASK.md write in subagent_end (Failed): ${writeResult.reason}`,
+            `memory-hybrid: skipped ACTIVE-TASK.md write in subagent_ended (Failed): ${writeResult.reason}`,
           );
         } else {
-          api.logger.info?.(`memory-hybrid: auto-checkpoint — updated task [${label}] to ${newStatus} on subagent_end`);
+          api.logger.info?.(
+            `memory-hybrid: auto-checkpoint — updated task [${label}] to ${newStatus} on subagent_ended`,
+          );
         }
       }
 
@@ -427,10 +464,10 @@ export function registerCleanupHandlers(
       );
     } catch (err) {
       capturePluginError(err instanceof Error ? err : new Error(String(err)), {
-        operation: "active-task-subagent-end",
+        operation: "active-task-subagent-ended",
         subsystem: "active-task",
       });
-      api.logger.debug?.(`memory-hybrid: active task auto-checkpoint on subagent_end failed: ${err}`);
+      api.logger.debug?.(`memory-hybrid: active task auto-checkpoint on subagent_ended failed: ${err}`);
     }
   });
 }

package/lifecycle/stage-recall.ts

@@ -3,7 +3,7 @@
  * Owns the interactive recall path for chat turns.
  * Runs the bounded recall pipeline: degradation check, FTS+vector, ambient, directives,
  * entity lookup, scoring. Returns either degraded/empty prependContext or RecallResult for injection.
- * Config: autoRecall.enabled. Timeout: 35s.
+ * Config: autoRecall.enabled. Stage wall-clock: INTERACTIVE_RECALL_STAGE_TIMEOUT_MS (abort).
  */
 
 import type { ClawdbotPluginApi } from "openclaw/plugin-sdk/core";
@@ -19,7 +19,7 @@ import {
 import { capturePluginError } from "../services/error-reporter.js";
 import { formatNarrativeRange, recallNarrativeSummaries } from "../services/narrative-recall.js";
 import { yieldEventLoop } from "../utils/event-loop-yield.js";
-import { withTimeout } from "../utils/timeout.js";
+import { resolveEntityLookupNames } from "../utils/entity-lookup-resolve.js";
 import { estimateTokens } from "../utils/text.js";
 import { isConsolidatedDerivedFact } from "../utils/consolidation-controls.js";
 import type { LifecycleContext, RecallResult, RecallStageResult, SessionState } from "./types.js";
@@ -31,6 +31,14 @@ import {
 
 const RECALL_STAGE_TIMEOUT_MS = INTERACTIVE_RECALL_STAGE_TIMEOUT_MS;
 
+function emptyRecallStage(): RecallStageResult {
+  return { kind: "empty", prependContext: undefined };
+}
+
+function recallAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
 function clipNarrativeText(text: string, maxChars = 360): string {
   if (text.length <= maxChars) return text;
   return `${text.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
@@ -42,7 +50,22 @@ export async function runRecallStage(
   ctx: LifecycleContext,
   sessionState: SessionState,
 ): Promise<RecallStageResult | null> {
-  return withTimeout(RECALL_STAGE_TIMEOUT_MS, () => runRecall(event, api, ctx, sessionState));
+  const ac = new AbortController();
+  const { signal } = ac;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      runRecall(event, api, ctx, sessionState, signal),
+      new Promise<RecallStageResult | null>((resolve) => {
+        timer = setTimeout(() => {
+          ac.abort();
+          resolve(null);
+        }, RECALL_STAGE_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
 }
 
 async function runRecall(
@@ -50,6 +73,7 @@ async function runRecall(
   api: ClawdbotPluginApi,
   ctx: LifecycleContext,
   sessionState: SessionState,
+  signal?: AbortSignal,
 ): Promise<RecallStageResult> {
   const e = event as { prompt?: string };
   if (!e.prompt || e.prompt.length < 5) {
@@ -59,6 +83,8 @@ async function runRecall(
   ctx.recallInFlightRef.value++;
   const recallStartMs = Date.now();
   try {
+    if (recallAborted(signal)) return emptyRecallStage();
+
     const { currentAgentIdRef } = ctx;
     const { resolveSessionKey, ambientSeenFactsMap, ambientLastEmbeddingMap, pruneSessionMaps, sessionStartSeen } =
       sessionState;
@@ -67,6 +93,7 @@ async function runRecall(
 
     // Let pending gateway I/O (health RPCs, WebSocket) run before heavy sync work (#931).
     await yieldEventLoop();
+    if (recallAborted(signal)) return emptyRecallStage();
 
     const fmt = ctx.cfg.autoRecall.injectionFormat;
     const isProgressive = fmt === "progressive" || fmt === "progressive_hybrid";
@@ -102,6 +129,9 @@ async function runRecall(
       ctx.cfg.queryExpansion,
       ctx.cfg.retrieval,
     );
+    api.logger.debug?.(
+      `memory-hybrid: interactive enrichment=${interactivePolicy.interactiveEnrichment} (HyDE=${interactivePolicy.allowHyde}, ambientMulti=${interactivePolicy.allowAmbientMultiQuery})`,
+    );
     const { degradationQueueDepth, degradationMaxLatencyMs } = interactivePolicy;
     const forceDegraded = degradationQueueDepth > 0 && ctx.recallInFlightRef.value > degradationQueueDepth;
 
@@ -111,6 +141,7 @@ async function runRecall(
         scopeFilter,
         reinforcementBoost: ctx.cfg.distill?.reinforcementBoost ?? 0.1,
         diversityWeight: ctx.cfg.reinforcement?.diversityWeight ?? 1.0,
+        interactiveFtsFastPath: true,
       };
       const degradedLimit = ctx.cfg.autoRecall.limit;
       const trimmed = e.prompt.trim();
@@ -240,12 +271,14 @@ async function runRecall(
     }
 
     await yieldEventLoop();
+    if (recallAborted(signal)) return emptyRecallStage();
 
     const recallOpts = {
       tierFilter,
       scopeFilter,
       reinforcementBoost: ctx.cfg.distill?.reinforcementBoost ?? 0.1,
       diversityWeight: ctx.cfg.reinforcement?.diversityWeight ?? 1.0,
+      interactiveFtsFastPath: true,
     };
     const hydeUsedRef = { value: false };
     const pipelineDeps: RecallPipelineDeps = {
@@ -282,6 +315,8 @@ async function runRecall(
     const ambientSeenFacts = ambientSeenFactsMap.get(sessionScopeKey)!;
     const ambientLastEmbedding = ambientLastEmbeddingMap.get(sessionScopeKey) ?? null;
 
+    if (recallAborted(signal)) return emptyRecallStage();
+
     let promptEmbedding: number[] | null = null;
     if (
       interactivePolicy.allowAmbientMultiQuery &&
@@ -296,6 +331,8 @@ async function runRecall(
       }
     }
 
+    if (recallAborted(signal)) return emptyRecallStage();
+
     let candidates = await runRecallPipelineQuery(e.prompt, limit, pipelineDeps, hydeUsedRef, {
       hydeLabel: "HyDE",
       errorPrefix: "auto-recall-",
@@ -303,6 +340,8 @@ async function runRecall(
       policy: interactivePolicy,
     });
 
+    if (recallAborted(signal)) return emptyRecallStage();
+
     if (interactivePolicy.allowAmbientMultiQuery && ambientCfg.enabled && ambientCfg.multiQuery) {
       try {
         const isTopicShift =
@@ -323,6 +362,7 @@ async function runRecall(
         if (extraQueries.length > 0) {
           const extraResultSets: SearchResult[][] = [candidates];
           for (const q of extraQueries) {
+            if (recallAborted(signal)) return emptyRecallStage();
             await yieldEventLoop();
             try {
               const qResults = await runRecallPipelineQuery(q.text, Math.ceil(limit / 2), pipelineDeps, hydeUsedRef, {
@@ -408,31 +448,35 @@ async function runRecall(
     }
 
     await yieldEventLoop();
+    if (recallAborted(signal)) return emptyRecallStage();
 
     const promptLower = e.prompt.toLowerCase();
     const { entityLookup } = ctx.cfg.autoRecall;
-    if (entityLookup.enabled && entityLookup.entities.length > 0) {
-      const seenIds = new Set(candidates.map((c) => c.entry.id));
-      for (const entity of entityLookup.entities) {
-        if (!promptLower.includes(entity.toLowerCase())) continue;
-        const entityResults = ctx.factsDb
-          .lookup(entity, undefined, undefined, { scopeFilter })
-          .slice(0, entityLookup.maxFactsPerEntity);
-        for (const r of entityResults) {
-          if (!seenIds.has(r.entry.id)) {
-            seenIds.add(r.entry.id);
-            candidates.push(r);
+    if (entityLookup.enabled) {
+      const entityLookupNames = resolveEntityLookupNames(entityLookup, ctx.factsDb);
+      if (entityLookupNames.length > 0) {
+        const seenIds = new Set(candidates.map((c) => c.entry.id));
+        for (const entity of entityLookupNames) {
+          if (!promptLower.includes(entity.toLowerCase())) continue;
+          const entityResults = ctx.factsDb
+            .lookup(entity, undefined, undefined, { scopeFilter })
+            .slice(0, entityLookup.maxFactsPerEntity);
+          for (const r of entityResults) {
+            if (!seenIds.has(r.entry.id)) {
+              seenIds.add(r.entry.id);
+              candidates.push(r);
+            }
           }
         }
+        candidates.sort((a, b) => {
+          const s = b.score - a.score;
+          if (s !== 0) return s;
+          const da = a.entry.sourceDate ?? a.entry.createdAt;
+          const db = b.entry.sourceDate ?? b.entry.createdAt;
+          return db - da;
+        });
+        candidates = candidates.slice(0, limit);
       }
-      candidates.sort((a, b) => {
-        const s = b.score - a.score;
-        if (s !== 0) return s;
-        const da = a.entry.sourceDate ?? a.entry.createdAt;
-        const db = b.entry.sourceDate ?? b.entry.createdAt;
-        return db - da;
-      });
-      candidates = candidates.slice(0, limit);
     }
 
     const directivesCfg = ctx.cfg.autoRecall.retrievalDirectives;
@@ -461,23 +505,29 @@ async function runRecall(
 
     if (directivesCfg.enabled) {
       try {
-        if (directivesCfg.entityMentioned && entityLookup.enabled && entityLookup.entities.length > 0) {
-          for (const entity of entityLookup.entities) {
-            if (!promptLower.includes(entity.toLowerCase())) continue;
-            if (!canRunDirective()) break;
-            const results = await runRecallPipelineQuery(entity, directiveLimit, pipelineDeps, hydeUsedRef, {
-              entity,
-              hydeLabel: "HyDE",
-              errorPrefix: "directive-",
-              limitHydeOnce: true,
-              policy: interactivePolicy,
-            });
-            directiveCalls += 1;
-            addDirectiveResults(results, `entity:${entity}`);
+        if (recallAborted(signal)) return emptyRecallStage();
+        if (directivesCfg.entityMentioned && entityLookup.enabled) {
+          const entityLookupNames = resolveEntityLookupNames(entityLookup, ctx.factsDb);
+          if (entityLookupNames.length > 0) {
+            for (const entity of entityLookupNames) {
+              if (recallAborted(signal)) return emptyRecallStage();
+              if (!promptLower.includes(entity.toLowerCase())) continue;
+              if (!canRunDirective()) break;
+              const results = await runRecallPipelineQuery(entity, directiveLimit, pipelineDeps, hydeUsedRef, {
+                entity,
+                hydeLabel: "HyDE",
+                errorPrefix: "directive-",
+                limitHydeOnce: true,
+                policy: interactivePolicy,
+              });
+              directiveCalls += 1;
+              addDirectiveResults(results, `entity:${entity}`);
+            }
           }
         }
         if (directivesCfg.keywords.length > 0) {
           for (const keyword of directivesCfg.keywords) {
+            if (recallAborted(signal)) return emptyRecallStage();
             if (!promptLower.includes(keyword.toLowerCase())) continue;
             if (!canRunDirective()) break;
             const results = await runRecallPipelineQuery(keyword, directiveLimit, pipelineDeps, hydeUsedRef, {
@@ -491,6 +541,7 @@ async function runRecall(
           }
         }
         for (const [taskType, triggers] of Object.entries(directivesCfg.taskTypes)) {
+          if (recallAborted(signal)) return emptyRecallStage();
           const hit = triggers.some((t) => promptLower.includes(t.toLowerCase()));
           if (!hit || !canRunDirective()) continue;
           const results = await runRecallPipelineQuery(taskType, directiveLimit, pipelineDeps, hydeUsedRef, {
@@ -503,6 +554,7 @@ async function runRecall(
           addDirectiveResults(results, `taskType:${taskType}`);
         }
         if (directivesCfg.sessionStart) {
+          if (recallAborted(signal)) return emptyRecallStage();
           const sessionKey = resolveSessionKey(e, api) ?? currentAgentIdRef.value ?? "default";
           if (!sessionStartSeen.has(sessionKey) && canRunDirective()) {
             const results = await runRecallPipelineQuery("session start", directiveLimit, pipelineDeps, hydeUsedRef, {

package/lifecycle/stage-setup.ts

@@ -11,6 +11,7 @@ import { capturePluginError } from "../services/error-reporter.js";
 import { withTimeout } from "../utils/timeout.js";
 import type { LifecycleContext, SessionState } from "./types.js";
 import { pluginLogger } from "../utils/logger.js";
+import { resolveAgentIdFromHookEvent } from "./resolve-agent-id.js";
 
 const SETUP_TIMEOUT_MS = 5000;
 
@@ -50,8 +51,7 @@ async function runSetup(
     }
   }
 
-  const e = event as { prompt?: string; agentId?: string; session?: { agentId?: string } };
-  const detectedAgentId = e.agentId || e.session?.agentId || api.context?.agentId;
+  const detectedAgentId = resolveAgentIdFromHookEvent(event, api);
   if (detectedAgentId) {
     currentAgentIdRef.value = detectedAgentId;
     api.logger.debug?.(`memory-hybrid: Detected agentId: ${detectedAgentId}`);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "openclaw-hybrid-memory",
-  "version": "2026.3.310",
+  "version": "2026.4.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "openclaw-hybrid-memory",
-      "version": "2026.3.310",
+      "version": "2026.4.11",
       "hasInstallScript": true,
       "dependencies": {
         "@lancedb/lancedb": "^0.27.1",

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-hybrid-memory",
   "kind": "memory",
-  "version": "2026.3.310",
+  "version": "2026.4.11",
   "uiHints": {
     "embedding.provider": {
       "label": "Embedding Provider",
@@ -101,7 +101,15 @@
     },
     "autoRecall.entityLookup": {
       "label": "Auto-Recall entity lookup",
-      "help": "When prompt mentions an entity from the list, merge lookup(entity) facts into candidates (4.1)"
+      "help": "When the prompt mentions an entity, merge lookup(entity) facts. If `entities` is empty and `autoFromFacts` is true (default), names come from DISTINCT entity on stored facts (capped by maxAutoEntities)."
+    },
+    "autoRecall.entityLookup.autoFromFacts": {
+      "label": "Entity lookup: auto from facts DB",
+      "help": "When true (default) and `entities` is empty, use distinct `entity` values from the facts table (up to maxAutoEntities). Set false to require an explicit `entities` list."
+    },
+    "autoRecall.entityLookup.maxAutoEntities": {
+      "label": "Entity lookup: max auto names",
+      "help": "Cap for auto-loaded entity names from the DB (default 500, max 2000)."
     },
     "autoRecall.retrievalDirectives.enabled": {
       "label": "Retrieval directives",
@@ -168,6 +176,10 @@
       "label": "Progressive pinned recall count",
       "help": "In progressive_hybrid: facts with recallCount >= this or permanent decay are injected in full (default 3)"
     },
+    "autoRecall.interactiveEnrichment": {
+      "label": "Interactive recall enrichment",
+      "help": "Single knob for chat-turn cost/latency: fast = no HyDE + no ambient multi-query; balanced (default) = respect queryExpansion.skipForInteractiveTurns and ambient.*; full = HyDE when query expansion is on + ambient multi-query path when ambient is configured."
+    },
     "autoRecall.authFailure.enabled": {
       "label": "Auth failure auto-recall",
       "help": "Detect authentication failures and auto-inject relevant credentials (default: true)"
@@ -371,6 +383,10 @@
       "label": "Use in recall",
       "help": "Enable graph traversal in memory_recall (default true)"
     },
+    "graph.strengthenOnRecall": {
+      "label": "Strengthen on recall",
+      "help": "When true, strengthen RELATED_TO links between facts recalled together (default false; Phase 1 baseline off)"
+    },
     "procedures.enabled": {
       "label": "Procedural memory",
       "help": "Extract tool-call procedures from session logs, inject in recall, auto-generate skills"
@@ -609,6 +625,16 @@
                   },
                   "maxFactsPerEntity": {
                     "type": "number"
+                  },
+                  "autoFromFacts": {
+                    "type": "boolean",
+                    "description": "When true (default) and entities is empty, load names from DISTINCT entity on facts (capped by maxAutoEntities)."
+                  },
+                  "maxAutoEntities": {
+                    "type": "number",
+                    "minimum": 1,
+                    "maximum": 2000,
+                    "description": "Max distinct entity names when using autoFromFacts (default 500)."
                   }
                 }
               },
@@ -665,6 +691,11 @@
               "summarizeModel": {
                 "type": "string"
               },
+              "interactiveEnrichment": {
+                "type": "string",
+                "enum": ["fast", "balanced", "full"],
+                "description": "Unified control for interactive auto-recall: fast = lowest latency/cost (no HyDE, no ambient multi-query); balanced = default; full = richer (HyDE + ambient multi when configured)."
+              },
               "authFailure": {
                 "type": "object",
                 "additionalProperties": false,
@@ -1124,6 +1155,10 @@
           "useInRecall": {
             "type": "boolean",
             "description": "Enable graph traversal in memory_recall (default: true)"
+          },
+          "strengthenOnRecall": {
+            "type": "boolean",
+            "description": "Strengthen RELATED_TO links when facts are recalled together (default: false)"
           }
         },
         "description": "Graph-based spreading activation: typed relationships for zero-LLM recall"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-hybrid-memory",
-  "version": "2026.3.310",
+  "version": "2026.4.11",
   "type": "module",
   "description": "Give your OpenClaw agent lasting memory: structured facts, semantic search, auto-capture & recall, decay, optional credential vault. Part of Hybrid Memory v3.",
   "files": [

package/services/context-engine.ts

@@ -511,16 +511,15 @@ export class HybridMemoryContextEngine implements MinimalContextEngine {
    * Post-subagent cleanup: capture any session-scoped facts created by the sub-agent
    * and promote them to the appropriate scope.
    *
-   * Guard against double-processing: the subagent_ended hook in lifecycle/hooks.ts
-   * handles the primary fact capture pipeline. This method provides a lightweight
-   * secondary pass scoped to the ContextEngine lifecycle, and only runs on
-   * OpenClaw ≥ 2026.3.8. If a fact is already in the store it will be skipped
-   * by the hasDuplicate check.
+   * Guard against double-processing: OpenClaw's typed **`subagent_ended`** hook
+   * (`lifecycle/stage-cleanup.ts`) only performs ACTIVE-TASK.md checkpointing — not fact capture.
+   * This method provides a lightweight ContextEngine callback; primary fact capture is the
+   * child session's **agent_end** autoCapture path. If a fact is already in the store it will be
+   * skipped by the hasDuplicate check when that pipeline exists.
    *
    * NOTE: The current SDK interface does not pass the sub-agent's result text here.
-   * Full result-text capture is handled by the lifecycle/hooks.ts subagent_ended handler.
-   * When the SDK interface is extended to include result text, this method should parse
-   * it using the existing autoCapture logic (see lifecycle/hooks.ts agent_end handler).
+   * When the SDK exposes result text, parse it using the existing autoCapture logic
+   * (see lifecycle/hooks.ts agent_end handler).
    */
   async onSubagentEnded(params: { childSessionKey: string; reason: string }): Promise<void> {
     const { factsDb, logger } = this.opts;
@@ -556,7 +555,7 @@ export class HybridMemoryContextEngine implements MinimalContextEngine {
       // Until then, all sub-agent fact capture is delegated to:
       //   (a) The child session's own agent_end autoCapture hook (primary path — runs
       //       inside the child's session and writes directly to the shared FactsDB)
-      //   (b) The subagent_end hook in lifecycle/hooks.ts (active-task checkpoint only)
+      //   (b) The typed subagent_ended hook in lifecycle/stage-cleanup.ts (ACTIVE-TASK.md only; issue #966)
     } catch (err) {
       capturePluginError(err instanceof Error ? err : new Error(String(err)), {
         subsystem: "context-engine",

package/services/recall-pipeline.ts

@@ -70,6 +70,8 @@ export interface RecallSearchOpts {
   scopeFilter: ScopeFilter | undefined;
   reinforcementBoost: number;
   diversityWeight: number;
+  /** Passed to `FactsDB.search` — bounded FTS + two-phase fetch on interactive recall. */
+  interactiveFtsFastPath?: boolean;
 }
 
 /** All explicit dependencies consumed by `runRecallPipelineQuery`. */

package/services/retrieval-mode-policy.ts

@@ -19,6 +19,8 @@ export interface InteractiveRecallPolicy {
   degradationMaxLatencyMs: number;
   allowHyde: boolean;
   allowAmbientMultiQuery: boolean;
+  /** Resolved from `autoRecall.interactiveEnrichment` (default balanced). */
+  interactiveEnrichment: "fast" | "balanced" | "full";
   notes: string[];
 }
 
@@ -37,8 +39,10 @@ export interface ExplicitDeepRetrievalPolicy {
   notes: string[];
 }
 
-export const INTERACTIVE_RECALL_STAGE_TIMEOUT_MS = 35_000;
-const INTERACTIVE_RECALL_VECTOR_TIMEOUT_MS = 30_000;
+/** Wall-clock cap for the whole interactive recall stage (abort + return when exceeded). */
+export const INTERACTIVE_RECALL_STAGE_TIMEOUT_MS = 32_000;
+/** Per-vector-step cap (HyDE + embed + Lance) inside `runRecallPipelineQuery`. Kept below stage timeout to leave slack for FTS, ambient, directives. */
+const INTERACTIVE_RECALL_VECTOR_TIMEOUT_MS = 26_000;
 const DEFAULT_INTERACTIVE_RECALL_DEGRADATION_QUEUE_DEPTH = 10;
 const DEFAULT_INTERACTIVE_RECALL_DEGRADATION_MAX_LATENCY_MS = 5_000;
 
@@ -60,6 +64,7 @@ export const DEFAULT_INTERACTIVE_RECALL_POLICY: InteractiveRecallPolicy = {
   degradationMaxLatencyMs: DEFAULT_INTERACTIVE_RECALL_DEGRADATION_MAX_LATENCY_MS,
   allowHyde: false,
   allowAmbientMultiQuery: true,
+  interactiveEnrichment: "balanced",
   notes: [
     "Owns the hot path for chat turns.",
     "Falls back to bounded FTS-only/HOT recall under pressure.",
@@ -72,8 +77,22 @@ export function resolveInteractiveRecallPolicy(
   queryExpansion?: { enabled: boolean; skipForInteractiveTurns: boolean },
   retrieval?: { ambientBudgetTokens: number },
 ): InteractiveRecallPolicy {
-  // When queryExpansion.skipForInteractiveTurns is false, allow HyDE on interactive turns
-  const allowHyde = queryExpansion?.enabled === true && queryExpansion.skipForInteractiveTurns !== true;
+  const enrichment = cfg.interactiveEnrichment ?? "balanced";
+
+  // Baseline (balanced): HyDE on interactive turns only when QE is on and skipForInteractiveTurns is not true.
+  let allowHyde = queryExpansion?.enabled === true && queryExpansion.skipForInteractiveTurns !== true;
+  // Historically true whenever auto-recall is on; ambient multi-query still requires ambient.enabled && multiQuery in stage-recall.
+  let allowAmbientMultiQuery = cfg.enabled === true;
+
+  if (enrichment === "fast") {
+    allowHyde = false;
+    allowAmbientMultiQuery = false;
+  } else if (enrichment === "full") {
+    // HyDE whenever query expansion is enabled; ignore skipForInteractiveTurns for the hot path.
+    allowHyde = queryExpansion?.enabled === true;
+    allowAmbientMultiQuery = cfg.enabled === true;
+  }
+
   // Enforce retrieval.ambientBudgetTokens as a hard total-token cap.
   // autoRecall.maxTokens is a user preference; ambientBudgetTokens is the architectural
   // ceiling — the injected context must not exceed either.
@@ -83,8 +102,9 @@ export function resolveInteractiveRecallPolicy(
     contextBudgetTokens,
     degradationQueueDepth: cfg.degradationQueueDepth ?? DEFAULT_INTERACTIVE_RECALL_DEGRADATION_QUEUE_DEPTH,
     degradationMaxLatencyMs: cfg.degradationMaxLatencyMs ?? DEFAULT_INTERACTIVE_RECALL_DEGRADATION_MAX_LATENCY_MS,
-    allowAmbientMultiQuery: cfg.enabled === true,
+    allowAmbientMultiQuery,
     allowHyde,
+    interactiveEnrichment: enrichment,
   };
 }
 

package/setup/register-hooks.ts

@@ -257,31 +257,8 @@ export function registerLifecycleHooks(ctx: HooksContext, api: ClawdbotPluginApi
     api.logger.debug?.(`memory-hybrid: before_compaction hook not available (${err})`);
   }
 
-  try {
-    api.on("before_consolidation", async (event: unknown) => {
-      const ev = event as {
-        candidateCount?: number;
-        source?: string;
-        sessionFile?: string;
-      };
-
-      await runPreConsolidationFlush(
-        { wal: ctx.wal, factsDb: ctx.factsDb, vectorDb: ctx.vectorDb, embeddings: ctx.embeddings },
-        api.logger,
-        "before_consolidation",
-      );
-
-      api.logger.info?.(
-        `memory-hybrid: before_consolidation — candidates=${ev.candidateCount ?? "?"} source=${ev.source ?? "?"}`,
-      );
-    });
-  } catch (err) {
-    capturePluginError(err instanceof Error ? err : new Error(String(err)), {
-      subsystem: "lifecycle",
-      operation: "register-before_consolidation",
-    });
-    api.logger.debug?.(`memory-hybrid: before_consolidation hook not available (${err})`);
-  }
+  // Issue #966: Do not register `before_consolidation` — it is not in OpenClaw's PLUGIN_HOOK_NAMES (ignored + noisy).
+  // WAL flush before compaction-style work is handled solely by `before_compaction` above (runPreConsolidationFlush).
 
   try {
     api.on("after_compaction", async (event: unknown): Promise<undefined | { prependContext: string }> => {

package/utils/constants.ts

@@ -51,6 +51,11 @@ export const REFLECTION_TEMPERATURE = 0.2;
 export const BATCH_THROTTLE_MS = 200;
 /** SQLite busy timeout (ms). Mitigates SQLITE_BUSY under concurrent writers (#875). */
 export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
+/**
+ * Max OR-joined FTS terms for `FactsDB.search` interactive fast path.
+ * Long prompts expand to huge MATCH expressions; capping keeps FTS5 work bounded (WhatsApp / gateway latency).
+ */
+export const INTERACTIVE_FTS_MAX_OR_TERMS = 16;
 /** Seconds per day. */
 export const SECONDS_PER_DAY = 86400;
 

package/utils/entity-lookup-resolve.ts

@@ -0,0 +1,25 @@
+import type { EntityLookupConfig } from "../config/types/retrieval.js";
+
+export type FactsDbWithKnownEntities = {
+  getKnownEntities?: () => string[];
+};
+
+/**
+ * Effective entity names for auto-recall entity lookup + retrieval directives.
+ * Manual `entities` wins; when empty and `autoFromFacts`, use DISTINCT entity from facts (capped).
+ */
+export function resolveEntityLookupNames(
+  entityLookup: EntityLookupConfig,
+  factsDb: FactsDbWithKnownEntities,
+): string[] {
+  if (entityLookup.entities.length > 0) return entityLookup.entities;
+  if (!entityLookup.autoFromFacts) return [];
+  const raw = factsDb.getKnownEntities?.() ?? [];
+  const filtered = raw.filter((e) => typeof e === "string" && e.trim().length > 0);
+  // Stable order before capping so the same DB always yields the same subset under maxAutoEntities
+  // (SQL DISTINCT without ORDER BY is not guaranteed deterministic).
+  const sorted = [...filtered].sort((a, b) =>
+    a.trim().localeCompare(b.trim(), undefined, { sensitivity: "base", numeric: true }),
+  );
+  return sorted.slice(0, entityLookup.maxAutoEntities);
+}