@byte5ai/palaia 2.3.6 → 2.7.1

package/src/context-engine.ts

@@ -1,21 +1,31 @@
 /**
- * ContextEngine adapter for deeper OpenClaw integration.
+ * ContextEngine adapter for OpenClaw integration.
  *
- * Maps the 7 ContextEngine lifecycle hooks to palaia functionality,
- * using the decomposed hooks modules as the implementation layer.
+ * Implements the OpenClaw v2026.3.24 ContextEngine interface,
+ * mapping lifecycle hooks to palaia functionality via the
+ * decomposed hooks modules.
  *
- * Phase 1.5: Created as a thin adapter over existing recall/capture logic.
+ * Supports both the modern ContextEngine interface (v2026.3.24+)
+ * and the legacy interface for backward compatibility.
  */
 
-import type { OpenClawPluginApi } from "./types.js";
+import type {
+  OpenClawPluginApi,
+  ContextEngine,
+  AgentMessage,
+} from "./types.js";
 import type { PalaiaPluginConfig } from "./config.js";
 import { run, recover, type RunnerOpts, getEmbedServerManager } from "./runner.js";
+import { getOrCreateSessionState } from "./hooks/state.js";
+import { formatBriefing } from "./hooks/session.js";
 
 import {
   extractMessageTexts,
   buildRecallQuery,
   rerankByTypeWeight,
   checkNudges,
+  formatEntryLine,
+  shouldUseCompactMode,
   type QueryResult,
 } from "./hooks/recall.js";
 
@@ -23,20 +33,17 @@ import {
   extractWithLLM,
   shouldAttemptCapture,
   extractSignificance,
-  stripPalaiaInjectedContext,
+  strippalaiaInjectedContext,
+  stripPrivateBlocks,
   trimToRecentExchanges,
   parsePalaiaHints,
   loadProjects,
-  resolveCaptureModel,
-  type ExtractionResult,
 } from "./hooks/capture.js";
 
 import {
   loadPluginState,
   savePluginState,
-  resolvePerAgentContext,
   sanitizeScope,
-  isValidScope,
 } from "./hooks/state.js";
 
 import {
@@ -46,17 +53,24 @@ import {
 } from "./priorities.js";
 
 /**
- * ContextEngine adapter for deeper OpenClaw integration.
- * Maps the 7 ContextEngine lifecycle hooks to palaia functionality.
+ * Resolve the effective capture scope from priorities (per-agent override)
+ * falling back to plugin config, then to "team".
  */
-export interface PalaiaContextEngine {
-  bootstrap(): Promise<void>;
-  ingest(messages: unknown[]): Promise<void>;
-  assemble(budget: { maxTokens: number }): Promise<{ content: string; tokenEstimate: number }>;
-  compact(): Promise<void>;
-  afterTurn(turn: unknown): Promise<void>;
-  prepareSubagentSpawn(parentContext: unknown): Promise<unknown>;
-  onSubagentEnded(result: unknown): Promise<void>;
+async function getEffectiveCaptureScope(config: PalaiaPluginConfig): Promise<string> {
+  try {
+    const prio = await loadPriorities(config.workspace || "");
+    const agentId = process.env.PALAIA_AGENT || undefined;
+    const resolved = resolvePriorities(prio, {
+      recallTypeWeight: config.recallTypeWeight,
+      recallMinScore: config.recallMinScore,
+      maxInjectedChars: config.maxInjectedChars,
+      tier: config.tier,
+    }, agentId);
+    if (resolved.captureScope) return resolved.captureScope;
+  } catch {
+    // Fall through to config default
+  }
+  return config.captureScope || "team";
 }
 
 function buildRunnerOpts(config: PalaiaPluginConfig, overrides?: { workspace?: string }): RunnerOpts {
@@ -72,28 +86,320 @@ function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
+/**
+ * Build the memory context string from recall results.
+ * Used by the ContextEngine assemble() method.
+ */
+async function buildMemoryContext(
+  config: PalaiaPluginConfig,
+  opts: RunnerOpts,
+  messages: unknown[],
+  maxChars: number,
+): Promise<{ text: string; recallOccurred: boolean; recallMinScore: number }> {
+  // Load and resolve priorities (Issue #121)
+  const prio = await loadPriorities(config.workspace || "");
+  const agentId = process.env.PALAIA_AGENT || undefined;
+  const project = config.captureProject || undefined;
+  const resolvedPrio = resolvePriorities(prio, {
+    recallTypeWeight: config.recallTypeWeight,
+    recallMinScore: config.recallMinScore,
+    maxInjectedChars: config.maxInjectedChars,
+    tier: config.tier,
+  }, agentId, project);
+
+  const effectiveMaxChars = Math.min(resolvedPrio.maxInjectedChars || 4000, maxChars);
+  const limit = Math.min(config.maxResults || 10, 20);
+  let entries: QueryResult["results"] = [];
+
+  if (config.recallMode === "query" && messages.length > 0) {
+    const userMessage = buildRecallQuery(messages);
+    if (userMessage && userMessage.length >= 5) {
+      // Try embed server first
+      let serverQueried = false;
+      if (config.embeddingServer) {
+        try {
+          const mgr = getEmbedServerManager(opts);
+          const resp = await mgr.query({
+            text: userMessage,
+            top_k: limit,
+            include_cold: resolvedPrio.tier === "all",
+            ...(resolvedPrio.scopeVisibility ? { scope_visibility: resolvedPrio.scopeVisibility } : {}),
+          }, config.timeoutMs || 3000);
+          if (resp?.result?.results && Array.isArray(resp.result.results)) {
+            entries = resp.result.results;
+            serverQueried = true;
+          }
+        } catch {
+          // Fall through to CLI
+        }
+      }
+
+      if (!serverQueried) {
+        try {
+          const { runJson } = await import("./runner.js");
+          const queryArgs: string[] = ["query", userMessage, "--limit", String(limit)];
+          if (resolvedPrio.tier === "all") queryArgs.push("--all");
+          const result = await runJson<QueryResult>(queryArgs, { ...opts, timeoutMs: 15000 });
+          if (result && Array.isArray(result.results)) {
+            entries = result.results;
+          }
+        } catch {
+          // Fall through to list
+        }
+      }
+    }
+  }
+
+  // List fallback
+  if (entries.length === 0) {
+    try {
+      const { runJson } = await import("./runner.js");
+      const listArgs: string[] = ["list"];
+      if (resolvedPrio.tier === "all") {
+        listArgs.push("--all");
+      } else {
+        listArgs.push("--tier", resolvedPrio.tier || "hot");
+      }
+      const result = await runJson<QueryResult>(listArgs, opts);
+      if (result && Array.isArray(result.results)) {
+        entries = result.results;
+      }
+    } catch {
+      return { text: "", recallOccurred: false, recallMinScore: resolvedPrio.recallMinScore };
+    }
+  }
+
+  if (entries.length === 0) {
+    return { text: "", recallOccurred: false, recallMinScore: resolvedPrio.recallMinScore };
+  }
+
+  // Apply type-weighted reranking and blocked filtering (Issue #121)
+  const rankedRaw = rerankByTypeWeight(entries, resolvedPrio.recallTypeWeight, config.recallRecencyBoost, config.manualEntryBoost);
+  const ranked = filterBlocked(rankedRaw, resolvedPrio.blocked);
+
+  // Build context string — progressive disclosure for large stores
+  const compact = shouldUseCompactMode(ranked.length);
+  let text = "## Active Memory (palaia)\n\n";
+  if (compact) {
+    text += "_Compact mode — use `memory_get <id>` for full details._\n\n";
+  }
+  let chars = text.length;
+
+  for (const entry of ranked) {
+    const line = formatEntryLine(entry, compact);
+    if (chars + line.length > effectiveMaxChars) break;
+    text += line;
+    chars += line.length;
+  }
+
+  // Build nudge text and check remaining budget before appending
+  const USAGE_NUDGE = "[palaia] auto-capture=on. Manual writes rank higher in recall. Use --type process for reusable workflows, --type task for sticky-note reminders (auto-deleted when done), --type memory for important facts.";
+  let agentNudges = "";
+  try {
+    const pluginState = await loadPluginState(config.workspace);
+    pluginState.successfulRecalls++;
+    if (!pluginState.firstRecallTimestamp) {
+      pluginState.firstRecallTimestamp = new Date().toISOString();
+    }
+    const { nudges } = checkNudges(pluginState);
+    if (nudges.length > 0) {
+      agentNudges = "\n\n## Agent Nudge (palaia)\n\n" + nudges.join("\n\n");
+    }
+    await savePluginState(pluginState, config.workspace);
+  } catch {
+    // Non-fatal
+  }
+
+  // --- Isolation workflow nudges (#148) ---
+  let isolationNudges = "";
+
+  // 1. missing_agent_identity: scopeVisibility configured but no PALAIA_AGENT
+  if (resolvedPrio.scopeVisibility && !process.env.PALAIA_AGENT) {
+    isolationNudges += "\n\n⚠️ scopeVisibility is configured but PALAIA_AGENT is not set. " +
+      "Scope filtering cannot work without agent identity. Set PALAIA_AGENT env var.";
+  }
+
+  // 2. recall_noise_ratio: >80% auto-capture entries for isolated agents
+  if (resolvedPrio.scopeVisibility && ranked.length >= 5) {
+    const autoCaptureCount = ranked.filter(e =>
+      (e.tags || []).includes("auto-capture")
+    ).length;
+    if (autoCaptureCount / ranked.length > 0.8) {
+      isolationNudges += "\n\n[palaia] Most recall results are auto-captured session data. " +
+        "Ask the orchestrator to run: palaia prune --agent " +
+        (process.env.PALAIA_AGENT || "<agent>") +
+        " --tags auto-capture --protect-type process";
+    }
+  }
+
+  const nudgeText = USAGE_NUDGE + "\n\n" + agentNudges + isolationNudges;
+  if (chars + nudgeText.length <= effectiveMaxChars) {
+    text += nudgeText;
+  }
+
+  const recallOccurred = entries.some(
+    (e) => typeof e.score === "number" && e.score >= resolvedPrio.recallMinScore,
+  );
+
+  return { text, recallOccurred, recallMinScore: resolvedPrio.recallMinScore };
+}
+
+/**
+ * Run auto-capture logic on a set of messages.
+ * Used by the ContextEngine afterTurn() method.
+ */
+async function runAutoCapture(
+  messages: unknown[],
+  api: OpenClawPluginApi,
+  config: PalaiaPluginConfig,
+  logger: { info(...a: unknown[]): void; warn(...a: unknown[]): void },
+): Promise<boolean> {
+  if (!config.autoCapture) return false;
+  if (!messages || messages.length === 0) {
+    logger.info("[palaia] Auto-capture skipped: no messages");
+    return false;
+  }
+
+  const allTexts = extractMessageTexts(messages);
+  const userTurns = allTexts.filter((t) => t.role === "user").length;
+  if (userTurns < config.captureMinTurns) {
+    logger.info(`[palaia] Auto-capture skipped: ${userTurns} user turns < captureMinTurns=${config.captureMinTurns}`);
+    return false;
+  }
+
+  // Parse capture hints
+  const collectedHints: { project?: string; scope?: string }[] = [];
+  for (const t of allTexts) {
+    const { hints } = parsePalaiaHints(t.text);
+    collectedHints.push(...hints);
+  }
+
+  // Strip injected context and private blocks, then trim to recent
+  const cleanedTexts = allTexts.map(t => ({
+    ...t,
+    text: stripPrivateBlocks(
+      t.role === "user" ? strippalaiaInjectedContext(t.text) : t.text
+    ),
+  }));
+  const recentTexts = trimToRecentExchanges(cleanedTexts);
+  const exchangeParts: string[] = [];
+  for (const t of recentTexts) {
+    const { cleanedText } = parsePalaiaHints(t.text);
+    exchangeParts.push(`[${t.role}]: ${cleanedText}`);
+  }
+  const exchangeText = exchangeParts.join("\n");
+
+  if (!shouldAttemptCapture(exchangeText)) {
+    logger.info(`[palaia] Auto-capture skipped: content did not pass significance filter (${exchangeText.length} chars)`);
+    return false;
+  }
+
+  const hookOpts = buildRunnerOpts(config);
+  const knownProjects = await loadProjects(hookOpts);
+  const agentName = process.env.PALAIA_AGENT || undefined;
+  const effectiveCaptureScope = await getEffectiveCaptureScope(config);
+
+  // LLM-based extraction (primary)
+  let llmHandled = false;
+  try {
+    const results = await extractWithLLM(messages, api.config, {
+      captureModel: config.captureModel,
+      workspace: config.workspace,
+    }, knownProjects);
+
+    for (const r of results) {
+      if (r.significance >= config.captureMinSignificance) {
+        const hintProject = collectedHints.find((h) => h.project)?.project;
+        const hintScope = collectedHints.find((h) => h.scope)?.scope;
+        const effectiveProject = hintProject || r.project;
+        const scope = effectiveCaptureScope !== "team"
+          ? sanitizeScope(effectiveCaptureScope, "team", true)
+          : sanitizeScope(hintScope || r.scope, "team", false);
+        const tags = [...r.tags];
+        if (!tags.includes("auto-capture")) tags.push("auto-capture");
+
+        const args: string[] = [
+          "write", r.content,
+          "--type", r.type,
+          "--tags", tags.join(",") || "auto-capture",
+          "--scope", scope,
+        ];
+        const project = config.captureProject || effectiveProject;
+        if (project) args.push("--project", project);
+        if (agentName) args.push("--agent", agentName);
+
+        await run(args, { ...hookOpts, timeoutMs: 10_000 });
+      }
+    }
+    llmHandled = true;
+  } catch {
+    // Fall through to rule-based
+  }
+
+  // Rule-based fallback
+  if (!llmHandled) {
+    if (config.captureFrequency === "significant") {
+      const significance = extractSignificance(exchangeText);
+      if (!significance) {
+        logger.info("[palaia] Auto-capture skipped: rule-based extraction found no significance (need ≥2 distinct tags)");
+        return false;
+      }
+      const tags = [...significance.tags];
+      if (!tags.includes("auto-capture")) tags.push("auto-capture");
+      const scope = effectiveCaptureScope !== "team"
+        ? sanitizeScope(effectiveCaptureScope, "team", true)
+        : "team";
+      const args: string[] = [
+        "write", significance.summary,
+        "--type", significance.type,
+        "--tags", tags.join(","),
+        "--scope", scope,
+      ];
+      if (agentName) args.push("--agent", agentName);
+      await run(args, { ...hookOpts, timeoutMs: 10_000 });
+    } else {
+      const summary = exchangeParts.slice(-4).map(p => p.slice(0, 200)).join(" | ").slice(0, 500);
+      const args: string[] = [
+        "write", summary,
+        "--type", "memory",
+        "--tags", "auto-capture",
+        "--scope", effectiveCaptureScope,
+      ];
+      if (agentName) args.push("--agent", agentName);
+      await run(args, { ...hookOpts, timeoutMs: 10_000 });
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Create a palaia ContextEngine implementing OpenClaw v2026.3.24 interface.
+ */
 export function createPalaiaContextEngine(
   api: OpenClawPluginApi,
   config: PalaiaPluginConfig,
-): PalaiaContextEngine {
+): ContextEngine {
   const logger = api.logger;
   const opts = buildRunnerOpts(config);
 
   /** Last messages seen via ingest(), used by assemble() for query building. */
-  let _lastMessages: unknown[] = [];
+  let _lastMessages: AgentMessage[] = [];
 
-  /** State from the last assemble() call, used by afterTurn(). */
-  let _lastAssembleState: {
-    recallOccurred: boolean;
-    capturedInThisTurn: boolean;
-  } = { recallOccurred: false, capturedInThisTurn: false };
+  /** Whether the last assemble() call found relevant memories. */
+  let _lastRecallOccurred = false;
+
+  const engine: ContextEngine = {
+    info: {
+      id: "palaia",
+      name: "palaia Memory",
+      version: "2.3",
+    },
 
-  return {
     /**
      * Bootstrap: WAL recovery + embed-server start.
-     * Maps to the palaia-recovery service from runner.ts.
      */
-    async bootstrap(): Promise<void> {
+    async bootstrap(_params) {
       try {
         const result = await recover(opts);
         if (result.replayed > 0) {
@@ -116,326 +422,176 @@ export function createPalaiaContextEngine(
           logger.info(`[palaia] Embed server pre-start skipped: ${err}`);
         }
       }
+
+      return { bootstrapped: true };
     },
 
     /**
-     * Ingest: auto-capture logic from hooks/capture.ts.
-     * Called with the turn's messages after the agent responds.
+     * Ingest: process a single message for auto-capture.
+     * Called per-message by the ContextEngine lifecycle.
+     * Accumulates messages; capture runs in afterTurn().
      */
-    async ingest(messages: unknown[]): Promise<void> {
-      _lastMessages = messages;
+    async ingest(params) {
+      if (params.message) {
+        _lastMessages.push(params.message);
+      }
+      return { ingested: true };
+    },
 
-      if (!config.autoCapture) return;
-      if (!messages || messages.length === 0) return;
+    /**
+     * AfterTurn: run auto-capture on accumulated messages.
+     */
+    async afterTurn(params) {
+      // Use params.messages if available (richer), else fall back to accumulated
+      const messages = params?.messages?.length ? params.messages : _lastMessages;
 
       try {
-        const allTexts = extractMessageTexts(messages);
-        const userTurns = allTexts.filter((t) => t.role === "user").length;
-        if (userTurns < config.captureMinTurns) return;
-
-        // Parse capture hints
-        const collectedHints: { project?: string; scope?: string }[] = [];
-        for (const t of allTexts) {
-          const { hints } = parsePalaiaHints(t.text);
-          collectedHints.push(...hints);
-        }
-
-        // Strip injected context and trim to recent
-        const cleanedTexts = allTexts.map(t =>
-          t.role === "user"
-            ? { ...t, text: stripPalaiaInjectedContext(t.text) }
-            : t
-        );
-        const recentTexts = trimToRecentExchanges(cleanedTexts);
-        const exchangeParts: string[] = [];
-        for (const t of recentTexts) {
-          const { cleanedText } = parsePalaiaHints(t.text);
-          exchangeParts.push(`[${t.role}]: ${cleanedText}`);
-        }
-        const exchangeText = exchangeParts.join("\n");
-
-        if (!shouldAttemptCapture(exchangeText)) return;
-
-        const hookOpts = buildRunnerOpts(config);
-        const knownProjects = await loadProjects(hookOpts);
-        const agentName = process.env.PALAIA_AGENT || undefined;
-
-        // LLM-based extraction (primary)
-        let llmHandled = false;
-        try {
-          const results = await extractWithLLM(messages, api.config, {
-            captureModel: config.captureModel,
-          }, knownProjects);
-
-          for (const r of results) {
-            if (r.significance >= config.captureMinSignificance) {
-              const hintProject = collectedHints.find((h) => h.project)?.project;
-              const hintScope = collectedHints.find((h) => h.scope)?.scope;
-              const effectiveProject = hintProject || r.project;
-              const scope = config.captureScope
-                ? sanitizeScope(config.captureScope, "team", true)
-                : sanitizeScope(hintScope || r.scope, "team", false);
-              const tags = [...r.tags];
-              if (!tags.includes("auto-capture")) tags.push("auto-capture");
-
-              const args: string[] = [
-                "write", r.content,
-                "--type", r.type,
-                "--tags", tags.join(",") || "auto-capture",
-                "--scope", scope,
-              ];
-              const project = config.captureProject || effectiveProject;
-              if (project) args.push("--project", project);
-              if (agentName) args.push("--agent", agentName);
-
-              await run(args, { ...hookOpts, timeoutMs: 10_000 });
-            }
-          }
-          llmHandled = true;
-        } catch {
-          // Fall through to rule-based
-        }
-
-        // Rule-based fallback
-        if (!llmHandled) {
-          if (config.captureFrequency === "significant") {
-            const significance = extractSignificance(exchangeText);
-            if (!significance) return;
-            const tags = [...significance.tags];
-            if (!tags.includes("auto-capture")) tags.push("auto-capture");
-            const scope = config.captureScope
-              ? sanitizeScope(config.captureScope, "team", true)
-              : "team";
-            const args: string[] = [
-              "write", significance.summary,
-              "--type", significance.type,
-              "--tags", tags.join(","),
-              "--scope", scope,
-            ];
-            if (agentName) args.push("--agent", agentName);
-            await run(args, { ...hookOpts, timeoutMs: 10_000 });
-          } else {
-            const summary = exchangeParts.slice(-4).map(p => p.slice(0, 200)).join(" | ").slice(0, 500);
-            const args: string[] = [
-              "write", summary,
-              "--type", "memory",
-              "--tags", "auto-capture",
-              "--scope", config.captureScope || "team",
-            ];
-            if (agentName) args.push("--agent", agentName);
-            await run(args, { ...hookOpts, timeoutMs: 10_000 });
-          }
-        }
-
-        _lastAssembleState.capturedInThisTurn = true;
+        await runAutoCapture(messages, api, config, logger);
       } catch (error) {
-        logger.warn(`[palaia] ContextEngine ingest failed: ${error}`);
+        logger.warn(`[palaia] ContextEngine afterTurn capture failed: ${error}`);
       }
+
+      // Reset for next turn
+      _lastRecallOccurred = false;
+      _lastMessages = [];
     },
 
     /**
-     * Assemble: recall logic with token budget awareness from hooks/recall.ts.
-     * Returns memory context string and token estimate, respecting the budget.
+     * Assemble: recall logic with token budget awareness.
+     * Returns memory context via systemPromptAddition.
      */
-    async assemble(budget: { maxTokens: number }): Promise<{ content: string; tokenEstimate: number }> {
-      _lastAssembleState = { recallOccurred: false, capturedInThisTurn: _lastAssembleState.capturedInThisTurn };
+    async assemble(params) {
+      _lastRecallOccurred = false;
 
       if (!config.memoryInject) {
-        return { content: "", tokenEstimate: 0 };
+        return {
+          messages: params.messages || [],
+          estimatedTokens: 0,
+        };
       }
 
       try {
-        // Load and resolve priorities (Issue #121)
-        const prio = await loadPriorities(config.workspace || "");
-        const agentId = process.env.PALAIA_AGENT || undefined;
-        const project = config.captureProject || undefined;
-        const resolvedPrio = resolvePriorities(prio, {
-          recallTypeWeight: config.recallTypeWeight,
-          recallMinScore: config.recallMinScore,
-          maxInjectedChars: config.maxInjectedChars,
-          tier: config.tier,
-        }, agentId, project);
-
-        // Convert token budget to char budget (~4 chars per token)
-        const maxChars = Math.min(resolvedPrio.maxInjectedChars || 4000, budget.maxTokens * 4);
-        const limit = Math.min(config.maxResults || 10, 20);
-        let entries: QueryResult["results"] = [];
-
-        if (config.recallMode === "query" && _lastMessages.length > 0) {
-          const userMessage = buildRecallQuery(_lastMessages);
-          if (userMessage && userMessage.length >= 5) {
-            // Try embed server first
-            let serverQueried = false;
-            if (config.embeddingServer) {
-              try {
-                const mgr = getEmbedServerManager(opts);
-                const resp = await mgr.query({
-                  text: userMessage,
-                  top_k: limit,
-                  include_cold: resolvedPrio.tier === "all",
-                }, config.timeoutMs || 3000);
-                if (resp?.result?.results && Array.isArray(resp.result.results)) {
-                  entries = resp.result.results;
-                  serverQueried = true;
-                }
-              } catch {
-                // Fall through to CLI
-              }
-            }
+        const tokenBudget = params.tokenBudget || 4000;
+        const maxChars = tokenBudget * 4;
 
-            if (!serverQueried) {
-              try {
-                const { runJson } = await import("./runner.js");
-                const queryArgs: string[] = ["query", userMessage, "--limit", String(limit)];
-                if (resolvedPrio.tier === "all") queryArgs.push("--all");
-                const result = await runJson<QueryResult>(queryArgs, { ...opts, timeoutMs: 15000 });
-                if (result && Array.isArray(result.results)) {
-                  entries = result.results;
-                }
-              } catch {
-                // Fall through to list
-              }
-            }
-          }
-        }
+        // Use params.messages for query building (richer than accumulated)
+        const queryMessages = params.messages?.length ? params.messages : _lastMessages;
+
+        const { text, recallOccurred } = await buildMemoryContext(
+          config, opts, queryMessages, maxChars,
+        );
 
-        // List fallback
-        if (entries.length === 0) {
-          try {
-            const { runJson } = await import("./runner.js");
-            const listArgs: string[] = ["list"];
-            if (resolvedPrio.tier === "all") {
-              listArgs.push("--all");
-            } else {
-              listArgs.push("--tier", resolvedPrio.tier || "hot");
+        _lastRecallOccurred = recallOccurred;
+
+        // Inject session briefing if pending (session_start or model switch)
+        let briefingText = "";
+        if (config.sessionBriefing && params.sessionKey) {
+          const sessionState = getOrCreateSessionState(params.sessionKey);
+          if (sessionState.pendingBriefing && !sessionState.briefingDelivered) {
+            // Wait for briefing to be ready (with timeout)
+            if (sessionState.briefingReady) {
+              await Promise.race([
+                sessionState.briefingReady,
+                new Promise<void>(r => setTimeout(r, 3000)),
+              ]);
             }
-            const result = await runJson<QueryResult>(listArgs, opts);
-            if (result && Array.isArray(result.results)) {
-              entries = result.results;
+            if (sessionState.pendingBriefing) {
+              const remainingChars = maxChars - (text?.length || 0);
+              briefingText = formatBriefing(
+                sessionState.pendingBriefing,
+                Math.min(config.sessionBriefingMaxChars || 1500, remainingChars),
+              );
+              if (briefingText) {
+                sessionState.briefingDelivered = true;
+              }
             }
-          } catch {
-            return { content: "", tokenEstimate: 0 };
-          }
-        }
-
-        if (entries.length === 0) {
-          return { content: "", tokenEstimate: 0 };
-        }
-
-        // Apply type-weighted reranking and blocked filtering (Issue #121)
-        const rankedRaw = rerankByTypeWeight(entries, resolvedPrio.recallTypeWeight);
-        const ranked = filterBlocked(rankedRaw, resolvedPrio.blocked);
-
-        // Build context string
-        const SCOPE_SHORT: Record<string, string> = { team: "t", private: "p", public: "pub" };
-        const TYPE_SHORT: Record<string, string> = { memory: "m", process: "pr", task: "tk" };
-
-        let text = "## Active Memory (Palaia)\n\n";
-        let chars = text.length;
-
-        for (const entry of ranked) {
-          const scopeKey = SCOPE_SHORT[entry.scope] || entry.scope;
-          const typeKey = TYPE_SHORT[entry.type] || entry.type;
-          const prefix = `[${scopeKey}/${typeKey}]`;
-
-          let line: string;
-          if (entry.body.toLowerCase().startsWith(entry.title.toLowerCase())) {
-            line = `${prefix} ${entry.body}\n\n`;
-          } else {
-            line = `${prefix} ${entry.title}\n${entry.body}\n\n`;
           }
-
-          if (chars + line.length > maxChars) break;
-          text += line;
-          chars += line.length;
         }
 
-        // Build nudge text and check remaining budget before appending
-        const USAGE_NUDGE = "[palaia] auto-capture=on. Manual write: --type process (SOPs/checklists) or --type task (todos with assignee/deadline) only. Conversation knowledge is auto-captured — do not duplicate with manual writes.";
-        let agentNudges = "";
-        try {
-          const pluginState = await loadPluginState(config.workspace);
-          pluginState.successfulRecalls++;
-          if (!pluginState.firstRecallTimestamp) {
-            pluginState.firstRecallTimestamp = new Date().toISOString();
-          }
-          const { nudges } = checkNudges(pluginState);
-          if (nudges.length > 0) {
-            agentNudges = "\n\n## Agent Nudge (Palaia)\n\n" + nudges.join("\n\n");
-          }
-          await savePluginState(pluginState, config.workspace);
-        } catch {
-          // Non-fatal
-        }
+        const combined = [briefingText, text].filter(Boolean).join("\n\n");
 
-        // Before adding nudges, check remaining budget
-        const nudgeText = USAGE_NUDGE + "\n\n" + agentNudges;
-        if (chars + nudgeText.length <= maxChars) {
-          text += nudgeText;
+        if (!combined) {
+          return {
+            messages: params.messages || [],
+            estimatedTokens: 0,
+          };
         }
-        // If nudges don't fit, skip them — the recall content is more important
-
-        _lastAssembleState.recallOccurred = entries.some(
-          (e) => typeof e.score === "number" && e.score >= resolvedPrio.recallMinScore,
-        );
 
         return {
-          content: text,
-          tokenEstimate: estimateTokens(text),
+          messages: params.messages || [],
+          estimatedTokens: estimateTokens(combined),
+          systemPromptAddition: combined,
         };
       } catch (error) {
         logger.warn(`[palaia] ContextEngine assemble failed: ${error}`);
-        return { content: "", tokenEstimate: 0 };
+        return {
+          messages: params.messages || [],
+          estimatedTokens: 0,
+        };
       }
     },
 
     /**
      * Compact: trigger `palaia gc` via runner.
      */
-    async compact(): Promise<void> {
+    async compact(_params) {
       try {
         await run(["gc"], { ...opts, timeoutMs: 30_000 });
         logger.info("[palaia] GC compaction completed");
+        return { ok: true, compacted: true };
       } catch (error) {
         logger.warn(`[palaia] GC compaction failed: ${error}`);
+        return { ok: false, compacted: false, reason: String(error) };
       }
     },
 
     /**
-     * AfterTurn: state save + emoji reactions.
-     * Called after each agent turn completes.
+     * PrepareSubagentSpawn: load session summary for sub-agent context.
      */
-    async afterTurn(turn: unknown): Promise<void> {
-      // State save is handled implicitly by assemble() nudge logic.
-      // Reset for next turn.
-      _lastAssembleState = { recallOccurred: false, capturedInThisTurn: false };
-      _lastMessages = [];
+    async prepareSubagentSpawn(_params) {
+      // Sub-agents share the same palaia store via workspace,
+      // so no explicit context passing is needed.
+      // Future: use OpenClaw's extraSystemPrompt to pass session summary.
+      return undefined;
     },
 
     /**
-     * PrepareSubagentSpawn: pass workspace + agent identity.
-     * Returns context for the sub-agent to inherit.
+     * OnSubagentEnded: capture sub-agent result as memory.
      */
-    async prepareSubagentSpawn(parentContext: unknown): Promise<unknown> {
-      const workspace = typeof api.workspace === "string"
-        ? api.workspace
-        : api.workspace?.dir;
-      const agentId = process.env.PALAIA_AGENT || undefined;
-
-      return {
-        palaiaWorkspace: workspace || config.workspace,
-        palaiaAgentId: agentId,
-        parentContext,
-      };
-    },
-
-    /**
-     * OnSubagentEnded: placeholder for future sub-agent memory merge.
-     * Will eventually merge sub-agent captures into parent context.
-     */
-    async onSubagentEnded(_result: unknown): Promise<void> {
-      // Future: merge sub-agent memory captures into parent agent's context.
-      // For now, sub-agents write to the same palaia store, so no merge needed.
+    async onSubagentEnded(params) {
+      if (!config.autoCapture) return;
+      // Only capture results for successfully completed sub-agents
+      if (params?.reason !== "completed") return;
+      try {
+        // Try to get sub-agent's last messages for summary
+        if (api.runtime?.subagent?.getSessionMessages && params?.childSessionKey) {
+          const result = await api.runtime.subagent.getSessionMessages({
+            sessionKey: params.childSessionKey,
+            limit: 10,
+          });
+          if (result?.messages?.length) {
+            const texts = extractMessageTexts(result.messages);
+            const summaryParts = texts.slice(-4).map(
+              (t: { role: string; text: string }) => `[${t.role}]: ${t.text.slice(0, 200)}`
+            );
+            if (summaryParts.length > 0) {
+              const summaryText = `Sub-agent result:\n${summaryParts.join("\n")}`.slice(0, 500);
+              const subagentScope = await getEffectiveCaptureScope(config);
+              await run([
+                "write", summaryText,
+                "--type", "memory",
+                "--tags", "subagent-result,auto-capture",
+                "--scope", subagentScope,
+              ], { ...opts, timeoutMs: 10_000 });
+              logger.info(`[palaia] Sub-agent result captured (${summaryText.length} chars)`);
+            }
+          }
+        }
+      } catch (error) {
+        logger.warn(`[palaia] Sub-agent result capture failed: ${error}`);
+      }
     },
   };
+
+  return engine;
 }