openclaw-hybrid-memory 2026.3.310 → 2026.4.10

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,12 @@ 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 } },
+    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 +56,12 @@ 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 } },
+    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 +77,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 +119,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/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;
 
@@ -240,6 +270,7 @@ async function runRecall(
     }
 
     await yieldEventLoop();
+    if (recallAborted(signal)) return emptyRecallStage();
 
     const recallOpts = {
       tierFilter,
@@ -282,6 +313,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 +329,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 +338,8 @@ async function runRecall(
       policy: interactivePolicy,
     });
 
+    if (recallAborted(signal)) return emptyRecallStage();
+
     if (interactivePolicy.allowAmbientMultiQuery && ambientCfg.enabled && ambientCfg.multiQuery) {
       try {
         const isTopicShift =
@@ -323,6 +360,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 +446,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 +503,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 +539,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 +552,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/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "openclaw-hybrid-memory",
-  "version": "2026.3.310",
+  "version": "2026.4.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "openclaw-hybrid-memory",
-      "version": "2026.3.310",
+      "version": "2026.4.10",
       "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.10",
   "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)"
@@ -609,6 +621,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 +687,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-hybrid-memory",
-  "version": "2026.3.310",
+  "version": "2026.4.10",
   "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/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/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);
+}