@digitalforgestudios/openclaw-sulcus 3.12.0 → 4.2.0

package/index.ts

@@ -6,11 +6,8 @@ import { URL } from "node:url";
 import { Type } from "@sinclair/typebox";
 
 // ─── STATIC AWARENESS ───────────────────────────────────────────────────────
-// Injected via before_prompt_build on EVERY turn, unconditionally.
-// This is the absolute minimum the LLM needs to know Sulcus exists.
-// It fires even if build_context crashes, times out, or returns empty.
-// Build static awareness with runtime backend info
-function buildStaticAwareness(backendMode: string, namespace: string) {
+
+function buildStaticAwareness(backendMode: string, namespace: string): string {
   return `## Persistent Memory (Sulcus)
 You have Sulcus — a persistent, reactive, thermodynamic memory system with reactive triggers.
 Memories survive across sessions. They have heat (0.0–1.0) that decays over time.
@@ -29,19 +26,15 @@ Memories survive across sessions. They have heat (0.0–1.0) that decays over ti
 **Memory types:** episodic (events, fast decay) · semantic (knowledge, slow) · preference (opinions, slower) · procedural (how-tos, slowest) · fact (data, slow)`;
 }
 
-// Legacy static string for backward compat (overwritten at register time)
 let STATIC_AWARENESS = buildStaticAwareness("local", "default");
 
-// Fallback context when build_context fails — includes the cheatsheet
-// but warns that dynamic context is unavailable.
 const FALLBACK_AWARENESS = `<sulcus_context token_budget="500">
   <cheatsheet>
     You have Sulcus — persistent memory with reactive triggers.
     STORE:    memory_store (content, memory_type)
     FIND:     memory_recall (query, limit)
     TYPES:    episodic (fast fade), semantic (slow), preference, procedural (slowest), fact
-    ⚠️ Context build failed this turn — use memory_recall to search manually.
-    Below is your active context. Search for deeper recall. Unlimited storage.
+    Context build failed this turn — use memory_recall to search manually.
   </cheatsheet>
 </sulcus_context>`;
 
@@ -52,12 +45,12 @@ interface HookConfig {
   enabled: boolean;
   limit?: number;
   minScore?: number;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 interface ToolConfig {
   enabled: boolean;
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
 interface HooksConfig {
@@ -68,162 +61,255 @@ interface HooksConfig {
 }
 
 interface HookHandlerCtx {
-  sulcusMem: any;
+  sulcusMem: SulcusCloudClient | null;
   backendMode: string;
   namespace: string;
-  logger: any;
+  logger: PluginLogger;
   nativeError?: string | null;
   storeLibPath?: string;
   vectorsLibPath?: string;
   wasmDir?: string;
 }
 
-type HookHandler = (event: any, config: HookConfig, ctx: HookHandlerCtx) => Promise<any>;
+interface PluginLogger {
+  debug?: (msg: string) => void;
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}
+
+type HookHandler = (event: Record<string, unknown>, config: HookConfig, ctx: HookHandlerCtx) => Promise<unknown>;
 
 // ─── HOOK HANDLERS ───────────────────────────────────────────────────────────
 
 const hookHandlers: Record<string, HookHandler> = {
-  /**
-   * inject_awareness — inject static Sulcus awareness into every prompt build.
-   * No network call — just a static string describing available tools.
-   */
-  inject_awareness: async (_event: any, _config: HookConfig, _ctx: HookHandlerCtx) => {
+  inject_awareness: async (_event, _config, _ctx) => {
     return { appendSystemContext: STATIC_AWARENESS };
   },
 
-  /**
-   * auto_recall — search Sulcus memory for context relevant to the incoming prompt.
-   * Only runs when enabled. Falls back to FALLBACK_AWARENESS on error.
-   */
-  auto_recall: async (event: any, config: HookConfig, ctx: HookHandlerCtx) => {
+  auto_recall: async (event, config, ctx) => {
     const { sulcusMem, namespace, logger } = ctx;
     if (!sulcusMem) return;
-    const agentLabel = event?.agentId ?? "(unknown)";
+    const agentLabel = (event?.agentId as string) ?? "(unknown)";
     logger.info(`sulcus: before_agent_start hook triggered for agent ${agentLabel}`);
     const prompt = typeof event?.prompt === "string" ? event.prompt : "";
     if (!prompt) return;
     try {
-      const limit = config.limit ?? 5;
-      logger.debug(`sulcus: searching context for prompt: ${prompt.substring(0, 50)}... (namespace: ${namespace})`);
+      const limit = (config.limit as number) ?? 5;
+      logger.debug?.(`sulcus: searching context for prompt: ${prompt.substring(0, 50)}... (namespace: ${namespace})`);
       const res = await sulcusMem.search_memory(prompt, limit, namespace);
       const results = res?.results ?? [];
       if (!results || results.length === 0) {
         return { prependSystemContext: FALLBACK_AWARENESS };
       }
-      // Format results as a concise XML context block
-      const items = results.map((r: any) =>
-        `    <memory id="${r.id}" heat="${(r.current_heat ?? r.score ?? 0).toFixed(2)}" type="${r.memory_type ?? "unknown"}">${r.label ?? r.pointer_summary ?? ""}</memory>`
-      ).join("\n");
+      const items = results.map((r: Record<string, unknown>) => {
+        const heat = ((r.current_heat as number) ?? (r.score as number) ?? 0).toFixed(2);
+        const mtype = (r.memory_type as string) ?? "unknown";
+        const label = (r.label as string) ?? (r.pointer_summary as string) ?? "";
+        return `    <memory id="${r.id}" heat="${heat}" type="${mtype}">${label}</memory>`;
+      }).join("\n");
       const context = `<sulcus_context token_budget="500" namespace="${namespace}">\n${items}\n</sulcus_context>`;
       logger.info(`sulcus: injecting ${results.length} recalled memories (${context.length} chars)`);
       return { prependSystemContext: context };
     } catch (e) {
-      // build_context failed — inject fallback so the LLM isn't flying blind
       logger.warn(`sulcus: context build failed: ${e} — injecting fallback awareness`);
       return { prependSystemContext: FALLBACK_AWARENESS };
     }
   },
 
-  /**
-   * none — no-op handler. Used for hooks that are enabled but should do nothing
-   * (e.g., agent_end where we want to log but not auto-record).
-   */
-  none: async (event: any, _config: HookConfig, ctx: HookHandlerCtx) => {
-    ctx.logger.debug(`sulcus: hook fired (action=none) for agent ${event.agentId ?? "(unknown)"} (no-op)`);
+  none: async (event, _config, ctx) => {
+    ctx.logger.debug?.(`sulcus: hook fired (action=none) for agent ${(event.agentId as string) ?? "(unknown)"} (no-op)`);
   },
 
-  /**
-   * sivu_auto_capture — SIU v2 quality-gated auto-capture on agent_end.
-   *
-   * When fired after each turn, extracts the user message from the event,
-   * runs it through SIVU (store/reject gate) and SICU (type classifier),
-   * and stores the memory only if SIVU approves. Falls back to basic
-   * junk-filtering + episodic capture if SIU v2 endpoint is unavailable.
-   *
-   * Config options:
-   *   min_store_confidence: number (default 0.5) — minimum SIVU confidence to store
-   *   fallback_on_error: boolean (default true) — store as episodic if SIU unavailable
-   */
-  sivu_auto_capture: async (event: any, config: HookConfig, ctx: HookHandlerCtx) => {
+  sivu_auto_capture: async (event, config, ctx) => {
     const { sulcusMem, logger } = ctx;
     if (!sulcusMem) return;
 
-    // Extract user message from the event
-    const userMessage = event?.userMessage ?? event?.prompt ?? event?.text ?? "";
+    // Skip captures from system/automated event sources
+    const eventTrigger = (event?.trigger as string) ?? "";
+    const skippedTriggers = ["exec-event", "cron-event", "heartbeat"];
+    if (skippedTriggers.some((t) => eventTrigger === t)) {
+      logger.debug?.(`sulcus: sivu_auto_capture — skipping trigger="${eventTrigger}"`);
+      return;
+    }
+
+    const userMessage = (event?.userMessage ?? event?.prompt ?? event?.text ?? "") as string;
     if (!userMessage || typeof userMessage !== "string") {
-      logger.debug("sulcus: sivu_auto_capture — no user message in event, skipping");
+      logger.debug?.("sulcus: sivu_auto_capture — no user message in event, skipping");
       return;
     }
 
-    // Pre-filter obvious junk before hitting the API
     if (isJunkMemory(userMessage)) {
-      logger.debug(`sulcus: sivu_auto_capture — pre-filtered junk: "${userMessage.substring(0, 50)}..."`);
+      logger.debug?.(`sulcus: sivu_auto_capture — pre-filtered junk: "${userMessage.substring(0, 50)}..."`);
       return;
     }
 
-    const minConfidence = config.min_store_confidence ?? 0.5;
-    const fallbackOnError = config.fallback_on_error !== false; // default true
+    if (!shouldCapture(userMessage)) {
+      logger.debug?.("sulcus: sivu_auto_capture — dedup skip");
+      return;
+    }
+
+    const minConfidence = (config.min_store_confidence as number) ?? 0.5;
+    const fallbackOnError = config.fallback_on_error !== false;
 
-    // Try SIU v2 endpoint for quality-gated classification
     if (sulcusMem instanceof SulcusCloudClient) {
       try {
-        const siuResult = await (sulcusMem as SulcusCloudClient).request("POST", "/api/v2/siu/label", {
-          text: userMessage,
-        });
-
-        const shouldStore = siuResult?.store === true && (siuResult?.store_confidence ?? 0) >= minConfidence;
-        const memoryType = siuResult?.memory_type ?? "episodic";
-        const modelVersion = siuResult?.model_version ?? "unknown";
+        const siuResult = await sulcusMem.request("POST", "/api/v2/siu/label", { text: userMessage }) as Record<string, unknown>;
+        const storeConf = (siuResult?.store_confidence as number) ?? 0;
+        const shouldStore = siuResult?.store === true && storeConf >= minConfidence;
+        const memoryType = (siuResult?.memory_type as string) ?? "episodic";
+        const modelVersion = (siuResult?.model_version as string) ?? "unknown";
 
         if (!shouldStore) {
-          logger.info(`sulcus: sivu_auto_capture — SIVU rejected (confidence: ${siuResult?.store_confidence?.toFixed(3) ?? "?"}, model: ${modelVersion}): "${userMessage.substring(0, 60)}..."`);
+          logger.info(`sulcus: sivu_auto_capture — SIVU rejected (confidence: ${storeConf.toFixed(3)}, model: ${modelVersion}): "${userMessage.substring(0, 60)}..."`);
           return;
         }
 
-        // SIVU approved — store with SICU-predicted type
         const res = await sulcusMem.add_memory(userMessage, memoryType);
-        logger.info(`sulcus: sivu_auto_capture — stored [${memoryType}] (id: ${res?.id ?? "?"}, sivu_conf: ${siuResult?.store_confidence?.toFixed(3)}, sicu_conf: ${siuResult?.type_confidence?.toFixed(3)}, model: ${modelVersion}): "${userMessage.substring(0, 60)}..."`);
+        const typeConf = ((siuResult?.type_confidence as number) ?? 0).toFixed(3);
+        logger.info(`sulcus: sivu_auto_capture — stored [${memoryType}] (id: ${res?.id ?? "?"}, sivu_conf: ${storeConf.toFixed(3)}, sicu_conf: ${typeConf}, model: ${modelVersion}): "${userMessage.substring(0, 60)}..."`);
         return;
-      } catch (e: any) {
-        logger.warn(`sulcus: sivu_auto_capture — SIU v2 endpoint error: ${e.message}`);
+      } catch (e: unknown) {
+        const msg = e instanceof Error ? e.message : String(e);
+        logger.warn(`sulcus: sivu_auto_capture — SIU v2 endpoint error: ${msg}`);
         if (!fallbackOnError) return;
-        // Fall through to basic capture
       }
     }
 
-    // Fallback: store as episodic (no SIU gating available)
     try {
       const res = await sulcusMem.add_memory(userMessage, "episodic");
       logger.info(`sulcus: sivu_auto_capture — fallback stored [episodic] (id: ${res?.id ?? "?"}): "${userMessage.substring(0, 60)}..."`);
-    } catch (e: any) {
-      logger.warn(`sulcus: sivu_auto_capture — fallback store failed: ${e.message}`);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      logger.warn(`sulcus: sivu_auto_capture — fallback store failed: ${msg}`);
+    }
+  },
+
+  /**
+   * auto_error_capture — stores tool errors as episodic memories with boosted heat.
+   *
+   * Fires on after_tool_call when a tool returns an error.
+   * Stores the error context so the agent learns from past failures.
+   * Skips errors from Sulcus's own tools to avoid self-referential loops.
+   */
+  auto_error_capture: async (event: any, _config: HookConfig, ctx: HookHandlerCtx) => {
+    const { sulcusMem, logger } = ctx;
+    const errorText = event?.error?.trim?.();
+    if (!errorText || !sulcusMem) return; // No error or no backend — nothing to capture
+
+    const toolName = event?.toolName ?? event?.tool_name ?? "unknown";
+
+    // Skip errors from our own tools to prevent capture loops
+    if (typeof toolName === "string" && (
+      toolName.startsWith("memory_") ||
+      toolName.startsWith("sulcus_") ||
+      toolName === "consolidate" ||
+      toolName === "evaluate_triggers" ||
+      toolName === "export_markdown" ||
+      toolName === "import_markdown" ||
+      toolName === "siu_label" ||
+      toolName === "siu_retrain"
+    )) {
+      return;
+    }
+
+    // Normalize + truncate error text
+    const normalized = errorText.replace(/\s+/g, " ").trim();
+    const truncated = normalized.length > 500 ? normalized.slice(0, 500) + " [truncated]" : normalized;
+    const memoryContent = `Tool '${toolName}' failed: ${truncated}`;
+
+    try {
+      const res = await sulcusMem.add_memory(memoryContent, "episodic");
+      // Boost heat so error memories persist longer — failures are high-value learnings
+      if (res?.id && sulcusMem instanceof SulcusCloudClient) {
+        await sulcusMem.request("PATCH", `/api/v1/agent/memory/${res.id}`, {
+          current_heat: 0.8,
+        }).catch(() => {}); // best-effort boost
+      }
+      logger.info(`sulcus: auto_error_capture — stored tool error [episodic] (id: ${res?.id ?? "?"}): "${memoryContent.substring(0, 80)}..."`);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      logger.debug?.(`sulcus: auto_error_capture — failed to store: ${msg}`);
+    }
+  },
+
+  pre_compaction_capture: async (event: Record<string, unknown>, _config: HookConfig, ctx: HookHandlerCtx) => {
+    const { sulcusMem, logger } = ctx;
+    if (!sulcusMem) return;
+
+    const messages = Array.isArray(event?.messages) ? event.messages as Record<string, unknown>[] : [];
+    if (messages.length === 0) return;
+
+    const firstUser = messages.find((m) => m.role === "user" || m.type === "human");
+    const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant" || m.type === "ai");
+
+    const firstUserText = typeof firstUser?.content === "string"
+      ? firstUser.content.substring(0, 200)
+      : typeof firstUser?.text === "string"
+        ? (firstUser.text as string).substring(0, 200)
+        : "(none)";
+
+    const lastAssistantText = typeof lastAssistant?.content === "string"
+      ? lastAssistant.content.substring(0, 200)
+      : typeof lastAssistant?.text === "string"
+        ? (lastAssistant.text as string).substring(0, 200)
+        : "(none)";
+
+    const filesModified: string[] = [];
+    for (const msg of messages) {
+      const toolCalls = Array.isArray(msg.tool_calls) ? msg.tool_calls as Record<string, unknown>[] : [];
+      for (const tc of toolCalls) {
+        const name = (tc.name ?? tc.function) as string | undefined;
+        if (name === "Write" || name === "Edit" || name === "write" || name === "edit") {
+          const input = (tc.input ?? tc.arguments ?? {}) as Record<string, unknown>;
+          const fp = input?.file_path ?? input?.path;
+          if (fp && typeof fp === "string" && !filesModified.includes(fp)) filesModified.push(fp);
+        }
+      }
+    }
+
+    const summaryParts = [
+      `Session compaction — ${messages.length} messages`,
+      `First user message: ${firstUserText}`,
+      `Last assistant message: ${lastAssistantText}`,
+    ];
+    if (filesModified.length > 0) summaryParts.push(`Files modified: ${filesModified.join(", ")}`);
+    const summary = summaryParts.join("\n");
+
+    if (!shouldCapture(summary)) {
+      logger.debug?.("sulcus: pre_compaction_capture — dedup skip");
+      return;
+    }
+
+    try {
+      const res = await sulcusMem.add_memory(summary, "episodic");
+      logger.info(`sulcus: pre_compaction_capture — stored session summary (id: ${res?.id ?? "?"})`);
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      logger.debug?.(`sulcus: pre_compaction_capture — store failed: ${msg}`);
     }
   },
 };
 
 // ─── CLOUD HTTP CLIENT ───────────────────────────────────────────────────────
-// Lightweight fallback client for users without local dylibs/WASM.
-// Uses Node.js built-in https/http — ZERO external dependencies.
-// Activates only when serverUrl + apiKey are configured and local libs are absent.
 
 class SulcusCloudClient {
   private serverUrl: string;
   private apiKey: string;
 
   constructor(serverUrl: string, apiKey: string) {
-    // Strip trailing slash for clean path concatenation
     this.serverUrl = serverUrl.replace(/\/+$/, "");
     this.apiKey = apiKey;
   }
 
-  /** Low-level HTTP helper. Returns parsed JSON response body. */
-  request(method: string, path: string, body?: any): Promise<any> {
-    return new Promise((resolve, reject) => {
+  request(method: string, path: string, body?: unknown): Promise<unknown> {
+    return new Promise((resolveP, rejectP) => {
       let parsedUrl: URL;
       try {
         parsedUrl = new URL(this.serverUrl + path);
-      } catch (e: any) {
-        return reject(new Error(`SulcusCloudClient: invalid URL ${this.serverUrl}${path}: ${e.message}`));
+      } catch (e: unknown) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return rejectP(new Error(`SulcusCloudClient: invalid URL ${this.serverUrl}${path}: ${msg}`));
       }
 
       const isHttps = parsedUrl.protocol === "https:";
@@ -253,129 +339,96 @@ class SulcusCloudClient {
         res.on("end", () => {
           const raw = Buffer.concat(chunks).toString("utf-8");
           if (!res.statusCode || res.statusCode >= 400) {
-            return reject(new Error(`SulcusCloudClient: HTTP ${res.statusCode} for ${method} ${path}: ${raw.substring(0, 200)}`));
-          }
-          if (!raw || raw.trim() === "") {
-            return resolve(null);
+            return rejectP(new Error(`SulcusCloudClient: HTTP ${res.statusCode} for ${method} ${path}: ${raw.substring(0, 200)}`));
           }
+          if (!raw || raw.trim() === "") return resolveP(null);
           try {
-            resolve(JSON.parse(raw));
+            resolveP(JSON.parse(raw));
           } catch (_e) {
-            // Some endpoints return plain text (e.g. markdown export)
-            resolve(raw);
+            resolveP(raw);
           }
         });
       });
 
-      req.on("error", (e: Error) => reject(new Error(`SulcusCloudClient: network error for ${method} ${path}: ${e.message}`)));
-
-      if (bodyStr !== undefined) {
-        req.write(bodyStr);
-      }
+      req.on("error", (e: Error) => rejectP(new Error(`SulcusCloudClient: network error for ${method} ${path}: ${e.message}`)));
+      if (bodyStr !== undefined) req.write(bodyStr);
       req.end();
     });
   }
 
-  /**
-   * search_memory — maps to POST /agent/search
-   * Server returns { results: [...] }; we normalise to the results array.
-   */
-  async search_memory(query: string, limit?: number, namespace?: string): Promise<{ results: any[] }> {
-    const body: any = { query };
+  async search_memory(query: string, limit?: number, namespace?: string): Promise<{ results: Record<string, unknown>[] }> {
+    const body: Record<string, unknown> = { query };
     if (limit !== undefined) body.limit = limit;
     if (namespace !== undefined) body.namespace = namespace;
-    const res = await this.request("POST", "/api/v1/agent/search", body);
-    const results = res?.results ?? res?.items ?? res?.nodes ?? (Array.isArray(res) ? res : []);
+    const res = await this.request("POST", "/api/v1/agent/search", body) as Record<string, unknown> | null;
+    const results = (res?.results ?? res?.items ?? res?.nodes ?? (Array.isArray(res) ? res : [])) as Record<string, unknown>[];
     return { results };
   }
 
-  /**
-   * add_memory — maps to POST /agent/nodes
-   * Server returns { id, ... }; pass through.
-   */
-  async add_memory(content: string, memoryType?: string | null): Promise<{ id: string; [key: string]: any }> {
-    const body: any = { label: content };
+  async add_memory(content: string, memoryType?: string | null): Promise<{ id: string; [key: string]: unknown }> {
+    const body: Record<string, unknown> = { label: content };
     if (memoryType) body.memory_type = memoryType;
-    const res = await this.request("POST", "/api/v1/agent/nodes", body);
-    return res ?? { id: "unknown" };
+    const res = await this.request("POST", "/api/v1/agent/nodes", body) as Record<string, unknown> | null;
+    return (res ?? { id: "unknown" }) as { id: string; [key: string]: unknown };
   }
 
-  /**
-   * list_hot_nodes — maps to GET /agent/hot_nodes
-   * Returns hot_nodes list; normalised for memory_status tool.
-   * Note: was incorrectly calling /agent/memory/status which doesn't return hot_nodes.
-   */
-  async list_hot_nodes(limit?: number): Promise<{ nodes: any[] }> {
+  async list_hot_nodes(limit?: number): Promise<{ nodes: Record<string, unknown>[] }> {
     const q = limit ? `?limit=${limit}` : "";
-    const res = await this.request("GET", `/api/v1/agent/hot_nodes${q}`);
-    // Server returns an array directly from this endpoint
-    const nodes = Array.isArray(res) ? res : (res?.hot_nodes ?? res?.nodes ?? []);
+    const res = await this.request("GET", `/api/v1/agent/hot_nodes${q}`) as Record<string, unknown> | unknown[] | null;
+    const nodes = (Array.isArray(res) ? res : ((res as Record<string, unknown>)?.hot_nodes ?? (res as Record<string, unknown>)?.nodes ?? [])) as Record<string, unknown>[];
     return { nodes };
   }
 
-  /**
-   * consolidate — maps to POST /agent/consolidate
-   */
-  async consolidate(minHeat?: number): Promise<any> {
-    const body: any = {};
+  async consolidate(minHeat?: number): Promise<unknown> {
+    const body: Record<string, unknown> = {};
     if (minHeat !== undefined) body.min_heat = minHeat;
     return this.request("POST", "/api/v1/agent/consolidate", body);
   }
 
-  /**
-   * delete_memory — maps to DELETE /agent/nodes/:id?train=true|false
-   * If train=true, snapshots content before deletion and records a 'reject' training signal for SIVU.
-   */
-  async delete_memory(id: string, train?: boolean): Promise<any> {
+  async delete_memory(id: string, train?: boolean): Promise<unknown> {
     const trainParam = train ? "true" : "false";
     return this.request("DELETE", `/api/v1/agent/nodes/${encodeURIComponent(id)}?train=${trainParam}`);
   }
 
-  /**
-   * export_markdown — maps to GET /agent/export?format=markdown
-   * Returns raw markdown string.
-   */
   async export_markdown(): Promise<string> {
     const res = await this.request("GET", "/api/v1/agent/export?format=markdown");
-    // Server may return { content: "..." } or raw string
     if (typeof res === "string") return res;
-    return res?.content ?? res?.markdown ?? JSON.stringify(res, null, 2);
+    const r = res as Record<string, unknown>;
+    return (r?.content ?? r?.markdown ?? JSON.stringify(res, null, 2)) as string;
   }
 
-  /**
-   * import_markdown — maps to POST /agent/import
-   */
-  async import_markdown(text: string): Promise<any> {
+  async import_markdown(text: string): Promise<unknown> {
     return this.request("POST", "/api/v1/agent/import", { format: "markdown", content: text });
   }
 
-  /**
-   * evaluate_triggers — maps to POST /triggers/evaluate
-   */
-  async evaluate_triggers(event: any, contextJson?: string): Promise<any> {
-    const body: any = { event };
+  async evaluate_triggers(event: unknown, contextJson?: string): Promise<unknown> {
+    const body: Record<string, unknown> = { event };
     if (contextJson) {
-      try {
-        body.context = JSON.parse(contextJson);
-      } catch (_e) {
-        body.context = contextJson;
-      }
+      try { body.context = JSON.parse(contextJson); }
+      catch (_e) { body.context = contextJson; }
     }
     return this.request("POST", "/api/v1/triggers/evaluate", body);
   }
+
+  async probe(): Promise<boolean> {
+    try {
+      await this.search_memory("probe", 1);
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }
 
 // ─── NATIVE LIB LOADER ──────────────────────────────────────────────────────
-// Loads libsulcus_store.dylib (embedded PG) and libsulcus_vectors.dylib (embeddings)
-// via koffi FFI. Provides queryFn and embedFn callbacks for SulcusMem.create().
 
 class NativeLibLoader {
-  private koffi: any = null;
-  private storeLib: any = null;
-  private vectorsLib: any = null;
-  private vectorsHandle: any = null;
-
-  // koffi function handles
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private koffi: unknown = null;
+  private storeLib: unknown = null;
+  private vectorsLib: unknown = null;
+  private vectorsHandle: unknown = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private fn_store_init: any = null;
   private fn_store_query: any = null;
   private fn_store_free: any = null;
@@ -386,22 +439,18 @@ class NativeLibLoader {
   public loaded = false;
   public error: string | null = null;
 
-  constructor(
-    private storeLibPath: string,
-    private vectorsLibPath: string
-  ) {}
+  constructor(private storeLibPath: string, private vectorsLibPath: string) {}
 
-  init(logger: any): void {
+  init(logger: PluginLogger): void {
     try {
-      // koffi is a pure-JS FFI library — no native compilation needed
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
       this.koffi = require("koffi");
-    } catch (e: any) {
-      this.error = `koffi not available: ${e.message}`;
+    } catch (e: unknown) {
+      this.error = `koffi not available: ${e instanceof Error ? e.message : e}`;
       logger.warn(`sulcus: ${this.error}`);
       return;
     }
 
-    // ── Load libsulcus_store.dylib ──
     if (!existsSync(this.storeLibPath)) {
       this.error = `libsulcus_store not found at ${this.storeLibPath}`;
       logger.warn(`sulcus: ${this.error}`);
@@ -414,48 +463,47 @@ class NativeLibLoader {
     }
 
     try {
-      this.storeLib = this.koffi.load(this.storeLibPath);
-      this.fn_store_init  = this.storeLib.func("sulcus_store_init", "int",    ["str", "uint16"]);
-      this.fn_store_query = this.storeLib.func("sulcus_store_query", "char*", ["str"]);
-      this.fn_store_free  = this.storeLib.func("sulcus_store_free_string", "void", ["char*"]);
-    } catch (e: any) {
-      this.error = `Failed to load libsulcus_store: ${e.message}`;
+      const k = this.koffi as any;
+      this.storeLib = k.load(this.storeLibPath);
+      this.fn_store_init  = (this.storeLib as any).func("sulcus_store_init", "int", ["str", "uint16"]);
+      this.fn_store_query = (this.storeLib as any).func("sulcus_store_query", "char*", ["str"]);
+      this.fn_store_free  = (this.storeLib as any).func("sulcus_store_free_string", "void", ["char*"]);
+    } catch (e: unknown) {
+      this.error = `Failed to load libsulcus_store: ${e instanceof Error ? e.message : e}`;
       logger.warn(`sulcus: ${this.error}`);
       return;
     }
 
     try {
-      this.vectorsLib = this.koffi.load(this.vectorsLibPath);
-      this.fn_vectors_create = this.vectorsLib.func("sulcus_vectors_create", "void*",  []);
-      this.fn_vectors_text   = this.vectorsLib.func("sulcus_vectors_text",   "char*",  ["void*", "str"]);
-      this.fn_vectors_free   = this.vectorsLib.func("sulcus_vectors_free_string", "void", ["char*"]);
-    } catch (e: any) {
-      this.error = `Failed to load libsulcus_vectors: ${e.message}`;
+      const k = this.koffi as any;
+      this.vectorsLib = k.load(this.vectorsLibPath);
+      this.fn_vectors_create = (this.vectorsLib as any).func("sulcus_vectors_create", "void*", []);
+      this.fn_vectors_text   = (this.vectorsLib as any).func("sulcus_vectors_text",   "char*", ["void*", "str"]);
+      this.fn_vectors_free   = (this.vectorsLib as any).func("sulcus_vectors_free_string", "void", ["char*"]);
+    } catch (e: unknown) {
+      this.error = `Failed to load libsulcus_vectors: ${e instanceof Error ? e.message : e}`;
       logger.warn(`sulcus: ${this.error}`);
       return;
     }
 
-    // ── Initialise embedded PG store ──
     try {
       const dataDir = resolve(process.env.HOME || "~", ".sulcus/data");
-      const port = 15432;
-      const rc = this.fn_store_init(dataDir, port);
+      const rc = this.fn_store_init(dataDir, 15432);
       if (rc !== 0) {
         this.error = `sulcus_store_init returned ${rc}`;
         logger.warn(`sulcus: ${this.error}`);
         return;
       }
-    } catch (e: any) {
-      this.error = `sulcus_store_init failed: ${e.message}`;
+    } catch (e: unknown) {
+      this.error = `sulcus_store_init failed: ${e instanceof Error ? e.message : e}`;
       logger.warn(`sulcus: ${this.error}`);
       return;
     }
 
-    // ── Create embed handle ──
     try {
       this.vectorsHandle = this.fn_vectors_create();
-    } catch (e: any) {
-      this.error = `sulcus_vectors_create failed: ${e.message}`;
+    } catch (e: unknown) {
+      this.error = `sulcus_vectors_create failed: ${e instanceof Error ? e.message : e}`;
       logger.warn(`sulcus: ${this.error}`);
       return;
     }
@@ -464,29 +512,17 @@ class NativeLibLoader {
     logger.info(`sulcus: native libs loaded (store: ${this.storeLibPath}, vectors: ${this.vectorsLibPath})`);
   }
 
-  // queryFn: async (sql: string, params: any[]) => any[]
-  // Calls sulcus_store_query which accepts plain SQL (params inlined by caller or
-  // passed as a JSON payload — the store lib handles parameterisation internally).
-  makeQueryFn(): (sql: string, params: any[]) => Promise<any[]> {
-    return async (sql: string, _params: any[]): Promise<any[]> => {
+  makeQueryFn(): (sql: string, params: unknown[]) => Promise<unknown[]> {
+    return async (sql: string, params: unknown[]): Promise<unknown[]> => {
       if (!this.loaded) throw new Error("Sulcus store not available");
-      // The store lib's query function takes a single JSON-encoded request
-      const payload = JSON.stringify({ sql, params: _params });
-      const raw: string = this.fn_store_query(payload);
+      const raw: string = this.fn_store_query(JSON.stringify({ sql, params }));
       if (!raw) return [];
-      try {
-        const parsed = JSON.parse(raw);
-        return Array.isArray(parsed) ? parsed : (parsed?.rows ?? [parsed]);
-      } finally {
-        // NOTE: koffi manages string memory automatically for char* returns;
-        // no manual free needed with koffi's default charset handling.
-        // If the ABI requires explicit free, call fn_store_free here.
-      }
+      const parsed = JSON.parse(raw);
+      const p = parsed as Record<string, unknown>;
+      return Array.isArray(parsed) ? (parsed as unknown[]) : ((Array.isArray(p?.rows) ? p.rows as unknown[] : [parsed as unknown]));
     };
   }
 
-  // embedFn: async (text: string) => Float32Array
-  // Calls sulcus_vectors_text which returns a JSON float array string.
   makeEmbedFn(): (text: string) => Promise<Float32Array> {
     return async (text: string): Promise<Float32Array> => {
       if (!this.loaded) throw new Error("Sulcus vectors not available");
@@ -499,9 +535,8 @@ class NativeLibLoader {
 }
 
 // ─── PRE-SEND FILTER ─────────────────────────────────────────────────────────
-// Rule-based junk filter. Catches obvious noise before it hits the API.
 
-const JUNK_PATTERNS = [
+const JUNK_PATTERNS: RegExp[] = [
   /^(HEARTBEAT_OK|NO_REPLY|NOOP)$/i,
   /^\s*$/,
   /^system:\s/i,
@@ -514,18 +549,15 @@ const JUNK_PATTERNS = [
   /^<<<EXTERNAL_UNTRUSTED_CONTENT/i,
   /^Runtime:/i,
   /tool_call|function_call|<function_calls>/i,
-  // Subagent completion events — internal runtime artifacts, not memories
   /\[Inter-session message\]\s*sourceSession=/i,
   /<<<BEGIN_UNTRUSTED_CHILD_RESULT>>>/,
   /<<<END_UNTRUSTED_CHILD_RESULT>>>/,
   /\[Internal task completion event\]/i,
   /^source:\s*subagent/im,
   /session_key:\s*agent:main:subagent:/i,
-  // Cron task payloads — system prompts, not meaningful content
   /^Sulcus validation cycle\./i,
   /^Heartbeat prompt:/i,
   /OpenClaw runtime context \(internal\)/i,
-  // Credential patterns — should never be stored
   /\b(sk-[a-f0-9]{40,}|Bearer\s+[A-Za-z0-9._~+/=-]{20,})\b/,
   /\b(api[_-]?key|secret|password|token)\s*[:=]\s*["']?[A-Za-z0-9._~+/=-]{16,}/i,
 ];
@@ -539,27 +571,39 @@ function isJunkMemory(text: string): boolean {
   return false;
 }
 
+// ─── CAPTURE DEDUP ───────────────────────────────────────────────────────────
+
+const captureDedup = new Map<string, number>();
+const DEDUP_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+
+function shouldCapture(content: string): boolean {
+  const key = content.substring(0, 120) + "|" + content.length;
+  const now = Date.now();
+  for (const [k, ts] of captureDedup.entries()) {
+    if (now - ts > DEDUP_WINDOW_MS) captureDedup.delete(k);
+  }
+  if (captureDedup.has(key)) return false;
+  captureDedup.set(key, now);
+  return true;
+}
+
 // ─── HOOKS CONFIG LOADER ─────────────────────────────────────────────────────
 
-/**
- * Load and merge hooks config.
- * Precedence: user config (api.config.hooks/tools) > defaults from hooks.defaults.json
- * Legacy `autoRecall` flag maps to hooks.before_agent_start.enabled for backward compat.
- */
-function loadHooksConfig(apiConfig: any): HooksConfig {
-  // Load defaults
+function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
   const defaultsPath = resolve(__dirname, "hooks.defaults.json");
   let defaults: HooksConfig;
   try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     defaults = JSON.parse(require("fs").readFileSync(defaultsPath, "utf-8")) as HooksConfig;
   } catch (_e) {
-    // Fallback inline defaults if file is missing (safety net)
     defaults = {
       version: 1,
       hooks: {
         before_prompt_build: { action: "inject_awareness", enabled: true },
         before_agent_start: { action: "auto_recall", enabled: false, limit: 5, minScore: 0.3 },
         agent_end: { action: "none", enabled: true },
+        after_tool_call: { action: "auto_error_capture", enabled: true },
+        before_compaction: { action: "pre_compaction_capture", enabled: true },
       },
       tools: {
         memory_recall: { enabled: true },
@@ -569,13 +613,13 @@ function loadHooksConfig(apiConfig: any): HooksConfig {
         export_markdown: { enabled: false },
         import_markdown: { enabled: false },
         evaluate_triggers: { enabled: false },
+        __sulcus_workflow__: { enabled: true },
       },
     };
   }
 
-  // Deep-merge user hook overrides (per-hook object merge, not replace)
-  const userHooks: Record<string, Partial<HookConfig>> = apiConfig?.hooks ?? {};
-  const userTools: Record<string, Partial<ToolConfig>> = apiConfig?.tools ?? {};
+  const userHooks = (apiConfig?.hooks ?? {}) as Record<string, Partial<HookConfig>>;
+  const userTools = (apiConfig?.tools ?? {}) as Record<string, Partial<ToolConfig>>;
 
   const mergedHooks: Record<string, HookConfig> = { ...defaults.hooks };
   for (const [name, override] of Object.entries(userHooks)) {
@@ -587,7 +631,7 @@ function loadHooksConfig(apiConfig: any): HooksConfig {
     mergedTools[name] = { ...(mergedTools[name] ?? { enabled: false }), ...override };
   }
 
-  // ── Legacy compat: autoRecall flag → hooks.before_agent_start.enabled ──
+  // Legacy compat: autoRecall flag → hooks.before_agent_start.enabled
   if (apiConfig?.autoRecall === true) {
     mergedHooks["before_agent_start"] = {
       ...(mergedHooks["before_agent_start"] ?? { action: "auto_recall", enabled: false }),
@@ -598,26 +642,206 @@ function loadHooksConfig(apiConfig: any): HooksConfig {
   return { version: defaults.version, hooks: mergedHooks, tools: mergedTools };
 }
 
-// ─── TOOL DEFINITIONS ────────────────────────────────────────────────────────
+// ─── RELATIVE TIME FORMATTER ─────────────────────────────────────────────────
 
-interface ToolDefinition {
-  schema: any;
-  options: { name: string };
-  makeExecute: (deps: ToolDeps) => (id: string, params: any) => Promise<any>;
+function formatRelativeTime(isoTimestamp: string): string {
+  try {
+    const dt = new Date(isoTimestamp);
+    const now = new Date();
+    const seconds = (now.getTime() - dt.getTime()) / 1000;
+    const minutes = seconds / 60;
+    const hours = seconds / 3600;
+    const days = seconds / 86400;
+    if (minutes < 2) return "just now";
+    if (minutes < 60) return `${Math.floor(minutes)}m ago`;
+    if (hours < 24) return `${Math.floor(hours)}h ago`;
+    if (days < 7) return `${Math.floor(days)}d ago`;
+    const month = dt.toLocaleString("en", { month: "short" });
+    if (dt.getFullYear() === now.getFullYear()) return `${dt.getDate()} ${month}`;
+    return `${dt.getDate()} ${month}, ${dt.getFullYear()}`;
+  } catch {
+    return "";
+  }
+}
+
+// ─── SDK RECALL HANDLER (for before_agent_start with prependContext) ──────────
+
+interface ProfileCache {
+  preferences: Record<string, unknown>[];
+  facts: Record<string, unknown>[];
+  cachedAt: number;
+}
+
+function buildSdkRecallHandler(
+  sulcusMem: SulcusCloudClient,
+  namespace: string,
+  maxResults: number,
+  profileFrequency: number,
+  logger: PluginLogger
+) {
+  let turnCount = 0;
+  let profileCache: ProfileCache | null = null;
+
+  return async (event: Record<string, unknown>, _ctx: unknown): Promise<{ prependContext: string } | undefined> => {
+    const prompt = typeof event?.prompt === "string" ? event.prompt : "";
+    if (!prompt || prompt.length < 5) return undefined;
+
+    turnCount++;
+    const includeProfile = turnCount === 1 || turnCount % profileFrequency === 0;
+
+    try {
+      const searchRes = await sulcusMem.search_memory(prompt, maxResults, namespace);
+      const searchResults = searchRes?.results ?? [];
+
+      let preferences: Record<string, unknown>[] = [];
+      let facts: Record<string, unknown>[] = [];
+
+      if (includeProfile) {
+        try {
+          const prefRes = await sulcusMem.search_memory("user preference", Math.min(maxResults, 5), namespace);
+          const factRes = await sulcusMem.search_memory("fact data knowledge", Math.min(maxResults, 5), namespace);
+          preferences = (prefRes?.results ?? []).filter((r) => r.memory_type === "preference");
+          facts = (factRes?.results ?? []).filter((r) => r.memory_type === "fact");
+          profileCache = { preferences, facts, cachedAt: Date.now() };
+        } catch {
+          // profile fetch failed — continue without
+        }
+      } else if (profileCache) {
+        preferences = profileCache.preferences;
+        facts = profileCache.facts;
+      }
+
+      const profileIds = new Set([
+        ...preferences.map((r) => r.id as string),
+        ...facts.map((r) => r.id as string),
+      ]);
+      const dedupedSearch = searchResults.filter((r) => !profileIds.has(r.id as string));
+
+      const sections: string[] = [];
+
+      if (includeProfile && (preferences.length > 0 || facts.length > 0)) {
+        const profileLines: string[] = [];
+        for (const r of preferences) {
+          const label = (r.label ?? r.pointer_summary ?? r.id ?? "") as string;
+          profileLines.push(`- [preference] ${label}`);
+        }
+        for (const r of facts) {
+          const label = (r.label ?? r.pointer_summary ?? r.id ?? "") as string;
+          profileLines.push(`- [fact] ${label}`);
+        }
+        if (profileLines.length > 0) {
+          sections.push(`## User Profile (from preferences + facts)\n${profileLines.join("\n")}`);
+        }
+      }
+
+      if (dedupedSearch.length > 0) {
+        const memLines = dedupedSearch.slice(0, maxResults).map((r) => {
+          const heat = ((r.current_heat as number) ?? (r.score as number) ?? 0);
+          const pct = `[${Math.round(heat * 100)}%]`;
+          const updatedAt = r.updated_at as string | undefined;
+          const timeStr = updatedAt ? `[${formatRelativeTime(updatedAt)}]` : "";
+          const label = (r.label ?? r.pointer_summary ?? r.id ?? "") as string;
+          return `- ${pct} ${timeStr} ${label}`.trim();
+        });
+        sections.push(`## Relevant Memories (with relevance %)\n${memLines.join("\n")}`);
+      }
+
+      if (sections.length === 0) return undefined;
+
+      const intro =
+        "The following is background context from long-term memory. Use it silently to inform your understanding — only reference it when the conversation naturally calls for it.";
+      const context = `<sulcus_context token_budget="500" namespace="${namespace}">\n${intro}\n\n${sections.join("\n\n")}\n</sulcus_context>`;
+
+      logger.info(`sulcus: SDK recall injecting context (${context.length} chars, turn ${turnCount})`);
+      return { prependContext: context };
+    } catch (err) {
+      logger.warn(`sulcus: SDK recall failed: ${err}`);
+      return undefined;
+    }
+  };
+}
+
+// ─── MEMORY RUNTIME BUILDER ───────────────────────────────────────────────────
+
+function buildMemoryRuntime(sulcusMem: SulcusCloudClient, backendMode: string) {
+  const searchManager = {
+    status() {
+      return {
+        backend: "builtin" as const,
+        provider: "sulcus",
+        model: backendMode === "cloud" ? "sulcus-cloud" : "sulcus-local",
+        custom: { backendMode, transport: backendMode === "cloud" ? "remote" : "local" },
+      };
+    },
+    async probeEmbeddingAvailability() {
+      try {
+        const ok = await sulcusMem.probe();
+        return { ok };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : "sulcus unreachable" };
+      }
+    },
+    async probeVectorAvailability() { return true; },
+    async sync() { /* cloud sync is continuous */ },
+    async close() { /* no-op for HTTP client */ },
+  };
+
+  return {
+    async getMemorySearchManager() { return { manager: searchManager }; },
+    resolveMemoryBackendConfig() { return { backend: "builtin" as const }; },
+    async closeAllMemorySearchManagers() { /* no-op */ },
+  };
+}
+
+// ─── PROMPT SECTION BUILDER ───────────────────────────────────────────────────
+
+function buildPromptSection(params: { availableTools: Set<string> }): string[] {
+  const hasRecall = params.availableTools.has("memory_recall");
+  const hasStore = params.availableTools.has("memory_store");
+  if (!hasRecall && !hasStore) return [];
+
+  const lines: string[] = [
+    "## Memory (Sulcus)",
+    "",
+    "You have persistent thermodynamic memory powered by Sulcus.",
+    "Relevant memories are automatically injected at the start of each conversation.",
+    "",
+  ];
+
+  if (hasRecall) lines.push("- Use `memory_recall` to search prior conversations, preferences, and facts.");
+  if (hasStore) lines.push("- Use `memory_store` to save information the user asks you to remember.");
+  if (params.availableTools.has("memory_delete")) lines.push("- Use `memory_delete` to remove incorrect or stale memories.");
+  if (params.availableTools.has("memory_status")) lines.push("- Use `memory_status` to check backend connection and hot nodes.");
+  if (params.availableTools.has("consolidate")) lines.push("- Use `consolidate` to prune cold memories below a heat threshold.");
+  if (params.availableTools.has("export_markdown")) lines.push("- Use `export_markdown` to export all memories as Markdown.");
+  if (params.availableTools.has("import_markdown")) lines.push("- Use `import_markdown` to import memories from a Markdown document.");
+  if (params.availableTools.has("evaluate_triggers")) lines.push("- Use `evaluate_triggers` to evaluate reactive memory triggers.");
+
+  lines.push("");
+  lines.push("Memory types: episodic (events, fast decay), semantic (knowledge, slow), preference (opinions, slower), procedural (how-tos, slowest), fact (data, slow)");
+
+  return lines;
 }
 
+// ─── TOOL DEFINITIONS ────────────────────────────────────────────────────────
+
 interface ToolDeps {
-  sulcusMem: any;
+  sulcusMem: SulcusCloudClient | null;
   backendMode: string;
   namespace: string;
   nativeLoader: NativeLibLoader;
   storeLibPath: string;
   vectorsLibPath: string;
   wasmDir: string;
-  logger: any;
+  logger: PluginLogger;
   isAvailable: boolean;
-  /** HTTP request helper for SIU v2 endpoints — null when cloud backend is not configured. */
-  siuRequest: ((method: string, path: string, body?: any) => Promise<any>) | null;
+  siuRequest: ((method: string, path: string, body?: unknown) => Promise<unknown>) | null;
+}
+
+interface ToolDefinition {
+  schema: Record<string, unknown>;
+  options: { name: string };
+  makeExecute: (deps: ToolDeps) => (id: string, params: Record<string, unknown>) => Promise<{ content: { type: string; text: string }[]; details?: Record<string, unknown> }>;
 }
 
 const toolDefinitions: Record<string, ToolDefinition> = {
@@ -629,23 +853,19 @@ const toolDefinitions: Record<string, ToolDefinition> = {
       parameters: Type.Object({
         query: Type.String({ description: "Search query string." }),
         limit: Type.Optional(Type.Number({ default: 5, description: "Maximum number of results to return (1-10)." })),
-        namespace: Type.Optional(Type.String({ description: "Namespace to search. Defaults to your own namespace. Specify another to cross-search (ACL enforced)." }))
+        namespace: Type.Optional(Type.String({ description: "Namespace to search. Defaults to your own namespace." })),
       }),
     },
     options: { name: "memory_recall" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
-      async (_id: string, params: any) => {
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        // Default to agent's own namespace to prevent cross-namespace bleed.
-        // Agent can explicitly pass namespace to search another (ACL enforced server-side).
-        const searchNamespace = params.namespace ?? namespace;
-        const res = await sulcusMem.search_memory(params.query, params.limit ?? 5, searchNamespace);
-        const results = res?.results ?? res?.items ?? res?.nodes ?? res ?? [];
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const searchNamespace = (params.namespace as string | undefined) ?? namespace;
+        const res = await sulcusMem.search_memory(params.query as string, (params.limit as number | undefined) ?? 5, searchNamespace);
+        const results = res?.results ?? [];
         return {
           content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
-          details: { results, backend: backendMode, namespace: searchNamespace }
+          details: { results: results as unknown as Record<string, unknown>[], backend: backendMode, namespace: searchNamespace },
         };
       },
   },
@@ -658,54 +878,41 @@ const toolDefinitions: Record<string, ToolDefinition> = {
       parameters: Type.Object({
         content: Type.String({ description: "Memory content. Supports Markdown formatting for structured content." }),
         memory_type: Type.Optional(Type.Union([
-          Type.Literal("episodic"),
-          Type.Literal("semantic"),
-          Type.Literal("preference"),
-          Type.Literal("procedural"),
-          Type.Literal("fact")
-        ], { description: "Memory type. preference=user preferences, procedural=how-to/processes, fact=stable knowledge, semantic=concepts/relationships, episodic=events/experiences. Default: episodic" })),
-        train: Type.Optional(Type.Boolean({ description: "Signal the SIU to learn from this manual store. When true, this memory+type becomes a positive training example for both SIVU (store=yes) and SICU (type=<memory_type>). Default: false" })),
+          Type.Literal("episodic"), Type.Literal("semantic"), Type.Literal("preference"),
+          Type.Literal("procedural"), Type.Literal("fact"),
+        ], { description: "Memory type. Default: episodic" })),
+        train: Type.Optional(Type.Boolean({ description: "Signal the SIU to learn from this manual store. Default: false" })),
       }),
     },
     options: { name: "memory_store" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable, logger }) =>
-      async (_id: string, params: any) => {
-        // Pre-send junk filter
-        if (isJunkMemory(params.content)) {
-          logger.debug(`sulcus: filtered junk memory: "${(params.content || "").substring(0, 50)}..."`);
-          return {
-            content: [{ type: "text", text: `Filtered: content looks like system noise, not a meaningful memory.` }],
-            details: { filtered: true, reason: "junk_pattern" }
-          };
+      async (_id, params) => {
+        const content = params.content as string;
+        if (isJunkMemory(content)) {
+          logger.debug?.(`sulcus: filtered junk memory: "${content.substring(0, 50)}..."`);
+          return { content: [{ type: "text", text: "Filtered: content looks like system noise, not a meaningful memory." }], details: { filtered: true } };
         }
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        const res = await sulcusMem.add_memory(params.content, params.memory_type ?? null);
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const mtype = (params.memory_type as string | undefined) || "episodic";
+        const res = await sulcusMem.add_memory(content, mtype);
         const nodeId = res?.id ?? "unknown";
-        const mtype = params.memory_type || "episodic";
-        // If train=true, submit a training signal to the SIU
         let trainResult: string | null = null;
-        if (params.train && (sulcusMem as any).request) {
+        if (params.train === true) {
           try {
-            await (sulcusMem as any).request("POST", "/api/v2/siu/signal", {
-              memory_id: nodeId,
-              signal_type: "accept",
-              corrected_store: true,
-              corrected_type: mtype,
-              content_snapshot: params.content,
-              source: "plugin",
+            await sulcusMem.request("POST", "/api/v2/siu/signal", {
+              memory_id: nodeId, signal_type: "accept", corrected_store: true,
+              corrected_type: mtype, content_snapshot: content, source: "plugin",
             });
             trainResult = "training signal submitted";
             logger.info(`sulcus: SIU training signal sent for memory ${nodeId} (store, ${mtype})`);
-          } catch (e: any) {
-            trainResult = `training signal failed: ${e.message}`;
-            logger.warn(`sulcus: SIU training signal failed: ${e.message}`);
+          } catch (e: unknown) {
+            trainResult = `training signal failed: ${e instanceof Error ? e.message : e}`;
+            logger.warn(`sulcus: SIU training signal failed: ${trainResult}`);
           }
         }
         return {
           content: [{ type: "text", text: `Stored [${mtype}] memory (id: ${nodeId}) → backend: ${backendMode}, namespace: ${namespace}${trainResult ? ` | SIU: ${trainResult}` : ""}` }],
-          details: { id: nodeId, memory_type: mtype, backend: backendMode, namespace, train: trainResult, ...res }
+          details: { ...res, id: nodeId, memory_type: mtype, backend: backendMode, namespace, train: trainResult as unknown as Record<string, unknown> },
         };
       },
   },
@@ -719,75 +926,40 @@ const toolDefinitions: Record<string, ToolDefinition> = {
     },
     options: { name: "memory_status" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, storeLibPath, vectorsLibPath, wasmDir, isAvailable }) =>
-      async (_id: string, _params: any) => {
-        if (!isAvailable) {
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              status: "unavailable",
-              backend: backendMode,
-              namespace,
-              error: nativeLoader.error || "WASM not loaded",
-              storeLib: storeLibPath,
-              vectorsLib: vectorsLibPath,
-              wasmDir,
-            }, null, 2) }],
-          };
+      async (_id, _params) => {
+        if (!isAvailable || !sulcusMem) {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "unavailable", backend: backendMode, namespace, error: nativeLoader.error || "not loaded", storeLib: storeLibPath, vectorsLib: vectorsLibPath, wasmDir }, null, 2) }] };
         }
         try {
-          // Fetch both status info and hot nodes in parallel
           const [statusInfo, hotNodes] = await Promise.all([
             sulcusMem.request("GET", "/api/v1/agent/memory/status").catch(() => null),
             sulcusMem.list_hot_nodes(20),
           ]);
-          const nodeList = hotNodes?.nodes ?? hotNodes ?? [];
-          const count = Array.isArray(nodeList) ? nodeList.length : 0;
-          return {
-            content: [{ type: "text", text: JSON.stringify({
-              status: "ok",
-              backend: backendMode,
-              namespace,
-              ...(statusInfo?.capabilities ? { capabilities: statusInfo.capabilities } : {}),
-              ...(statusInfo?.stats ? { stats: statusInfo.stats } : {}),
-              hot_node_count: count,
-              hot_nodes: nodeList,
-            }, null, 2) }],
-            details: { status: "ok", backend: backendMode, namespace, count, ...(statusInfo?.stats ?? {}) }
-          };
-        } catch (e: any) {
+          const nodeList = hotNodes?.nodes ?? [];
+          const si = statusInfo as Record<string, unknown> | null;
           return {
-            content: [{ type: "text", text: JSON.stringify({
-              status: "error",
-              backend: backendMode,
-              namespace,
-              error: e.message,
-            }, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify({ status: "ok", backend: backendMode, namespace, ...(si?.capabilities ? { capabilities: si.capabilities } : {}), ...(si?.stats ? { stats: si.stats } : {}), hot_node_count: nodeList.length, hot_nodes: nodeList }, null, 2) }],
+            details: { status: "ok", backend: backendMode, namespace, count: nodeList.length },
           };
+        } catch (e: unknown) {
+          return { content: [{ type: "text", text: JSON.stringify({ status: "error", backend: backendMode, namespace, error: e instanceof Error ? e.message : String(e) }, null, 2) }] };
         }
       },
   },
 
-  // ── New WASM-capability tools (disabled by default) ──
-
   consolidate: {
     schema: {
       name: "consolidate",
       label: "Memory Consolidate",
       description: "Consolidate cold memories: merges, prunes, or archives nodes below the given heat threshold.",
-      parameters: Type.Object({
-        min_heat: Type.Optional(Type.Number({ default: 0.1, description: "Nodes with heat below this value are candidates for consolidation (0.0–1.0)." }))
-      }),
+      parameters: Type.Object({ min_heat: Type.Optional(Type.Number({ default: 0.1, description: "Heat threshold (0.0–1.0)." })) }),
     },
     options: { name: "consolidate" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
-      async (_id: string, params: any) => {
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        const res = await sulcusMem.consolidate(params.min_heat ?? 0.1);
-        return {
-          content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }],
-          details: { result: res, backend: backendMode, namespace }
-        };
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const res = await sulcusMem.consolidate((params.min_heat as number | undefined) ?? 0.1);
+        return { content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }], details: { result: res as Record<string, unknown>, backend: backendMode, namespace } };
       },
   },
 
@@ -800,15 +972,10 @@ const toolDefinitions: Record<string, ToolDefinition> = {
     },
     options: { name: "export_markdown" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
-      async (_id: string, _params: any) => {
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        const markdown: string = await sulcusMem.export_markdown();
-        return {
-          content: [{ type: "text", text: markdown }],
-          details: { backend: backendMode, namespace, length: markdown.length }
-        };
+      async (_id, _params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const markdown = await sulcusMem.export_markdown();
+        return { content: [{ type: "text", text: markdown }], details: { backend: backendMode, namespace, length: markdown.length } };
       },
   },
 
@@ -817,21 +984,14 @@ const toolDefinitions: Record<string, ToolDefinition> = {
       name: "import_markdown",
       label: "Import Memory (Markdown)",
       description: "Import memories from a Markdown document into the current namespace.",
-      parameters: Type.Object({
-        text: Type.String({ description: "Markdown content to import into Sulcus memory." })
-      }),
+      parameters: Type.Object({ text: Type.String({ description: "Markdown content to import." }) }),
     },
     options: { name: "import_markdown" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
-      async (_id: string, params: any) => {
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        const res = await sulcusMem.import_markdown(params.text);
-        return {
-          content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }],
-          details: { result: res, backend: backendMode, namespace }
-        };
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const res = await sulcusMem.import_markdown(params.text as string);
+        return { content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }], details: { result: res as Record<string, unknown>, backend: backendMode, namespace } };
       },
   },
 
@@ -842,20 +1002,15 @@ const toolDefinitions: Record<string, ToolDefinition> = {
       description: "Evaluate reactive memory triggers against an event and context.",
       parameters: Type.Object({
         event: Type.String({ description: "Event name to evaluate triggers against (e.g. 'agent_end', 'user_message')." }),
-        context_json: Type.Optional(Type.String({ description: "JSON string of additional context to pass to trigger evaluation." }))
+        context_json: Type.Optional(Type.String({ description: "JSON string of additional context." })),
       }),
     },
     options: { name: "evaluate_triggers" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
-      async (_id: string, params: any) => {
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        const res = await sulcusMem.evaluate_triggers(params.event, params.context_json ?? "{}");
-        return {
-          content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }],
-          details: { result: res, backend: backendMode, namespace }
-        };
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const res = await sulcusMem.evaluate_triggers(params.event, (params.context_json as string | undefined) ?? "{}");
+        return { content: [{ type: "text", text: JSON.stringify({ result: res, backend: backendMode, namespace }, null, 2) }], details: { result: res as Record<string, unknown>, backend: backendMode, namespace } };
       },
   },
 
@@ -863,65 +1018,46 @@ const toolDefinitions: Record<string, ToolDefinition> = {
     schema: {
       name: "memory_delete",
       label: "Delete Memory",
-      description: "Delete a memory node by ID. With train=true (default), the deleted content trains SIVU to reject similar content in the future. Use this to clean up junk, duplicates, or noise memories.",
+      description: "Delete a memory node by ID. With train=true (default), trains SIVU to reject similar content.",
       parameters: Type.Object({
         id: Type.String({ description: "Memory node ID to delete." }),
-        train: Type.Optional(Type.Boolean({ default: true, description: "Train SIVU to reject similar content (default true). Set false to delete without training." })),
+        train: Type.Optional(Type.Boolean({ default: true, description: "Train SIVU to reject similar content (default true)." })),
       }),
     },
     options: { name: "memory_delete" },
     makeExecute: ({ sulcusMem, backendMode, namespace, nativeLoader, isAvailable }) =>
-      async (_id: string, params: any) => {
-        if (!isAvailable) {
-          throw new Error(`Sulcus unavailable: ${nativeLoader.error || "WASM not loaded"}`);
-        }
-        const train = params.train !== false; // default true
-        const res = await (sulcusMem as SulcusCloudClient).delete_memory(params.id, train);
+      async (_id, params) => {
+        if (!isAvailable || !sulcusMem) throw new Error(`Sulcus unavailable: ${nativeLoader.error || "not loaded"}`);
+        const train = params.train !== false;
+        const res = await sulcusMem.delete_memory(params.id as string, train);
         return {
-          content: [{ type: "text", text: `Deleted memory ${params.id}${train ? " (trained SIVU to reject similar)" : ""}. Backend: ${backendMode}, namespace: ${namespace}` }],
-          details: { id: params.id, trained: train, result: res, backend: backendMode, namespace }
+          content: [{ type: "text", text: `Deleted memory ${params.id as string}${train ? " (trained SIVU to reject similar)" : ""}. Backend: ${backendMode}, namespace: ${namespace}` }],
+          details: { id: params.id as string, trained: train, result: res as Record<string, unknown>, backend: backendMode, namespace },
         };
       },
   },
 
-  // ── SIU v2 Tools ───────────────────────────────────────────────────────────
-  // These tools call the SIU v2 server endpoints for text classification.
-  // Requires cloud backend (serverUrl + apiKey). Uses /api/v2/siu/* endpoints.
-
   siu_label: {
     schema: {
       name: "siu_label",
       label: "SIU Label",
-      description: "Classify text using SIU v2 — returns SIVU store/reject decision and SICU memory type classification with confidence scores.",
+      description: "Classify text using SIU v2 — returns SIVU store/reject decision and SICU memory type classification.",
       parameters: Type.Object({
         text: Type.String({ description: "Text to classify." }),
         classify_only: Type.Optional(Type.Boolean({ description: "Skip SIVU quality gate, only run SICU type classification." })),
       }),
     },
     options: { name: "siu_label" },
-    makeExecute: ({ backendMode, siuRequest, logger }) =>
-      async (_id: string, params: any) => {
-        if (!siuRequest) {
-          return {
-            content: [{ type: "text", text: "SIU label requires cloud backend (serverUrl + apiKey)." }],
-            details: { error: "cloud_required" },
-          };
-        }
+    makeExecute: ({ siuRequest, logger }) =>
+      async (_id, params) => {
+        if (!siuRequest) return { content: [{ type: "text", text: "SIU label requires cloud backend (serverUrl + apiKey)." }] };
         try {
-          const res = await siuRequest("POST", "/api/v2/siu/label", {
-            text: params.text,
-            classify_only: params.classify_only ?? false,
-          });
-          return {
-            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
-            details: res,
-          };
-        } catch (e: any) {
-          logger.warn(`sulcus: siu_label failed: ${e.message}`);
-          return {
-            content: [{ type: "text", text: `SIU label failed: ${e.message}` }],
-            details: { error: e.message },
-          };
+          const res = await siuRequest("POST", "/api/v2/siu/label", { text: params.text as string, classify_only: params.classify_only ?? false });
+          return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }], details: res as Record<string, unknown> };
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          logger.warn(`sulcus: siu_label failed: ${msg}`);
+          return { content: [{ type: "text", text: `SIU label failed: ${msg}` }] };
         }
       },
   },
@@ -935,25 +1071,15 @@ const toolDefinitions: Record<string, ToolDefinition> = {
     },
     options: { name: "siu_status" },
     makeExecute: ({ siuRequest, logger }) =>
-      async (_id: string, _params: any) => {
-        if (!siuRequest) {
-          return {
-            content: [{ type: "text", text: "SIU status requires cloud backend (serverUrl + apiKey)." }],
-            details: { error: "cloud_required" },
-          };
-        }
+      async (_id, _params) => {
+        if (!siuRequest) return { content: [{ type: "text", text: "SIU status requires cloud backend." }] };
         try {
           const res = await siuRequest("GET", "/api/v2/siu/status");
-          return {
-            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
-            details: res,
-          };
-        } catch (e: any) {
-          logger.warn(`sulcus: siu_status failed: ${e.message}`);
-          return {
-            content: [{ type: "text", text: `SIU status failed: ${e.message}` }],
-            details: { error: e.message },
-          };
+          return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }], details: res as Record<string, unknown> };
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          logger.warn(`sulcus: siu_status failed: ${msg}`);
+          return { content: [{ type: "text", text: `SIU status failed: ${msg}` }] };
         }
       },
   },
@@ -962,44 +1088,31 @@ const toolDefinitions: Record<string, ToolDefinition> = {
     schema: {
       name: "siu_retrain",
       label: "SIU Retrain",
-      description: "Trigger an async retrain of SIU v2 models using accumulated training signals. Returns job status.",
+      description: "Trigger an async retrain of SIU v2 models using accumulated training signals.",
       parameters: Type.Object({}),
     },
     options: { name: "siu_retrain" },
     makeExecute: ({ siuRequest, logger }) =>
-      async (_id: string, _params: any) => {
-        if (!siuRequest) {
-          return {
-            content: [{ type: "text", text: "SIU retrain requires cloud backend (serverUrl + apiKey)." }],
-            details: { error: "cloud_required" },
-          };
-        }
+      async (_id, _params) => {
+        if (!siuRequest) return { content: [{ type: "text", text: "SIU retrain requires cloud backend." }] };
         try {
           const res = await siuRequest("POST", "/api/v2/siu/retrain");
-          return {
-            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
-            details: res,
-          };
-        } catch (e: any) {
-          logger.warn(`sulcus: siu_retrain failed: ${e.message}`);
-          return {
-            content: [{ type: "text", text: `SIU retrain failed: ${e.message}` }],
-            details: { error: e.message },
-          };
+          return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }], details: res as Record<string, unknown> };
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          logger.warn(`sulcus: siu_retrain failed: ${msg}`);
+          return { content: [{ type: "text", text: `SIU retrain failed: ${msg}` }] };
         }
       },
   },
+
   trigger_feedback: {
     schema: {
       name: "trigger_feedback",
       label: "Trigger Feedback",
-      description:
-        "Record feedback on a trigger fire (for SITU training). Use to report false positives (fired but shouldn't have), false negatives (should have fired but didn't), or confirm correct fires.",
+      description: "Record feedback on a trigger fire (for SITU training).",
       parameters: Type.Object({
-        feedback_type: Type.String({
-          description:
-            'One of: "false_positive" (fired wrongly), "false_negative" (missed fire), "correct" (good fire), "wrong_action" (fired but wrong action)',
-        }),
+        feedback_type: Type.String({ description: 'One of: "false_positive", "false_negative", "correct", "wrong_action"' }),
         trigger_id: Type.Optional(Type.String({ description: "UUID of the trigger rule" })),
         trigger_log_id: Type.Optional(Type.String({ description: "UUID of the trigger fire log entry" })),
         event_type: Type.Optional(Type.String({ description: "Event type: memory_created, heat_threshold, recall, etc." })),
@@ -1010,30 +1123,111 @@ const toolDefinitions: Record<string, ToolDefinition> = {
     },
     options: { name: "trigger_feedback" },
     makeExecute: ({ siuRequest, logger }) =>
-      async (_id: string, params: any) => {
-        if (!siuRequest) {
-          return {
-            content: [{ type: "text", text: "Trigger feedback requires cloud backend (serverUrl + apiKey)." }],
-            details: { error: "cloud_required" },
-          };
-        }
+      async (_id, params) => {
+        if (!siuRequest) return { content: [{ type: "text", text: "Trigger feedback requires cloud backend." }] };
         try {
           const res = await siuRequest("POST", "/api/v1/triggers/feedback", params);
-          return {
-            content: [{ type: "text", text: JSON.stringify(res, null, 2) }],
-            details: res,
-          };
-        } catch (e: any) {
-          logger.warn(`sulcus: trigger_feedback failed: ${e.message}`);
-          return {
-            content: [{ type: "text", text: `Trigger feedback failed: ${e.message}` }],
-            details: { error: e.message },
-          };
+          return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }], details: res as Record<string, unknown> };
+        } catch (e: unknown) {
+          const msg = e instanceof Error ? e.message : String(e);
+          logger.warn(`sulcus: trigger_feedback failed: ${msg}`);
+          return { content: [{ type: "text", text: `Trigger feedback failed: ${msg}` }] };
         }
       },
   },
+
+  __sulcus_workflow__: {
+    schema: {
+      name: "__sulcus_workflow__",
+      label: "Sulcus Workflow",
+      description: "Call this when you are unsure what to do next with Sulcus memory tools. Returns a step-by-step workflow checklist so you always know the right action.",
+      parameters: Type.Object({}),
+    },
+    options: { name: "__sulcus_workflow__" },
+    makeExecute: (_deps: ToolDeps) =>
+      async (_id: string, _params: Record<string, unknown>) => {
+        const workflow = [
+          { step: 1, action: "search first", tool: "memory_recall", description: "Before starting work, search memory for relevant context from prior sessions." },
+          { step: 2, action: "store decisions/patterns/learnings", tool: "memory_store", description: "After significant work, store important decisions, patterns, corrections, or learnings." },
+          { step: 3, action: "boost important memories", tool: "PATCH /api/v1/agent/memory/:id", description: "Use PATCH to set current_heat=0.9 on memories that should persist longer (memory_boost not yet exposed as a tool)." },
+          { step: 4, action: "check triggers", tool: "evaluate_triggers", description: "Evaluate reactive rules to see if any triggers should fire based on current context." },
+          { step: 5, action: "export if needed", tool: "export_markdown", description: "Export all memories as Markdown for backup or review." },
+        ];
+        return {
+          content: [{ type: "text", text: JSON.stringify(workflow, null, 2) }],
+          details: { workflow: workflow as unknown as Record<string, unknown> },
+        };
+      },
+  },
 };
 
+// ─── FIRST-INSTALL HISTORY IMPORT ────────────────────────────────────────────
+
+async function importOpenClawHistory(sulcusMem: SulcusCloudClient, logger: PluginLogger): Promise<void> {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const fs = require("fs") as {
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string, enc: string) => string;
+    readdirSync: (p: string) => string[];
+    statSync: (p: string) => { mtimeMs: number };
+    writeFileSync: (p: string, d: string, enc: string) => void;
+  };
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const path = require("path") as { join: (...args: string[]) => string };
+
+  const workspaceDir = process.env.OPENCLAW_WORKSPACE
+    ? resolve(process.env.OPENCLAW_WORKSPACE)
+    : resolve(process.env.HOME || "~", ".openclaw/workspace");
+  const markerPath = path.join(workspaceDir, ".sulcus-imported");
+
+  if (fs.existsSync(markerPath)) return;
+
+  logger.info("sulcus: first-install history import starting...");
+
+  const memories: string[] = [];
+
+  const memoryMdPath = path.join(workspaceDir, "MEMORY.md");
+  if (fs.existsSync(memoryMdPath)) {
+    try {
+      const text = fs.readFileSync(memoryMdPath, "utf-8");
+      const entries = text.split(/\n(?:---+|\s*\n\s*\n)/g).map((s) => s.trim()).filter((s) => s.length > 20);
+      memories.push(...entries);
+    } catch (_e) { /* best-effort */ }
+  }
+
+  const memDir = path.join(workspaceDir, "memory");
+  if (fs.existsSync(memDir)) {
+    try {
+      const files = fs.readdirSync(memDir);
+      const now = Date.now();
+      const thirtyDaysMs = 30 * 24 * 60 * 60 * 1000;
+      for (const file of files) {
+        if (!/^\d{4}-\d{2}-\d{2}\.md$/.test(file)) continue;
+        try {
+          const stat = fs.statSync(path.join(memDir, file));
+          if (now - stat.mtimeMs > thirtyDaysMs) continue;
+          const text = fs.readFileSync(path.join(memDir, file), "utf-8");
+          const entries = text.split(/\n---\n/g).map((s) => s.trim()).filter((s) => s.length > 20);
+          memories.push(...entries);
+        } catch (_e) { /* best-effort */ }
+      }
+    } catch (_e) { /* best-effort */ }
+  }
+
+  let stored = 0;
+  for (const mem of memories) {
+    try {
+      await sulcusMem.add_memory(mem, "episodic");
+      stored++;
+    } catch (_e) { /* best-effort */ }
+  }
+
+  try {
+    fs.writeFileSync(markerPath, new Date().toISOString(), "utf-8");
+    logger.info(`sulcus: history import complete — stored ${stored} memories from OpenClaw workspace`);
+  } catch (_e) { /* best-effort */ }
+}
+
 // ─── PLUGIN ──────────────────────────────────────────────────────────────────
 
 const sulcusPlugin = {
@@ -1042,106 +1236,106 @@ const sulcusPlugin = {
   description: "Sulcus-backed vMMU memory for OpenClaw — thermodynamic decay, reactive triggers, local-first",
   kind: "memory" as const,
 
-  register(api: any) {
+  register(api: Record<string, unknown>) {
+    const logger = api.logger as PluginLogger;
+    const pluginConfig = (api.pluginConfig ?? {}) as Record<string, unknown>;
+
     // ── Configuration ──
-    const libDir = api.pluginConfig?.libDir
-      ? resolve(api.pluginConfig.libDir)
+    const libDir = pluginConfig?.libDir
+      ? resolve(pluginConfig.libDir as string)
       : resolve(process.env.HOME || "~", ".sulcus/lib");
 
-    const storeLibPath = api.pluginConfig?.storeLibPath
-      ? resolve(api.pluginConfig.storeLibPath)
+    const storeLibPath = pluginConfig?.storeLibPath
+      ? resolve(pluginConfig.storeLibPath as string)
       : resolve(libDir, process.platform === "darwin" ? "libsulcus_store.dylib" : "libsulcus_store.so");
 
-    const vectorsLibPath = api.pluginConfig?.vectorsLibPath
-      ? resolve(api.pluginConfig.vectorsLibPath)
+    const vectorsLibPath = pluginConfig?.vectorsLibPath
+      ? resolve(pluginConfig.vectorsLibPath as string)
       : resolve(libDir, process.platform === "darwin" ? "libsulcus_vectors.dylib" : "libsulcus_vectors.so");
 
-    const wasmDir = api.pluginConfig?.wasmDir
-      ? resolve(api.pluginConfig.wasmDir)
+    const wasmDir = pluginConfig?.wasmDir
+      ? resolve(pluginConfig.wasmDir as string)
       : resolve(__dirname, "wasm");
 
-    // Cloud fallback credentials (used when local libs unavailable)
-    const serverUrl: string | undefined = api.pluginConfig?.serverUrl;
-    const apiKey: string | undefined = api.pluginConfig?.apiKey;
+    const serverUrl = pluginConfig?.serverUrl as string | undefined;
+    const apiKey = pluginConfig?.apiKey as string | undefined;
 
-    // Default namespace = agent name (prevents everything landing in "default")
-    const agentId = api.pluginConfig?.agentId;
-    const namespace = api.pluginConfig?.namespace === "default" && agentId
+    const agentId = pluginConfig?.agentId as string | undefined;
+    const namespace = pluginConfig?.namespace === "default" && agentId
       ? agentId
-      : (api.pluginConfig?.namespace || agentId || "default");
+      : ((pluginConfig?.namespace as string | undefined) || agentId || "default");
+
+    // New config options (v4.0.0)
+    const autoRecall: boolean = (pluginConfig?.autoRecall as boolean | undefined) ?? false;
+    const autoCapture: boolean = (pluginConfig?.autoCapture as boolean | undefined) ?? false;
+    const maxRecallResults: number = Math.min(20, Math.max(1, (pluginConfig?.maxRecallResults as number | undefined) ?? 5));
+    const profileFrequency: number = Math.min(500, Math.max(1, (pluginConfig?.profileFrequency as number | undefined) ?? 10));
 
-    // ── Load hooks config (config-driven dispatch) ──
-    const hooksConfig = loadHooksConfig(api.pluginConfig);
+    // ── Load hooks config ──
+    const hooksConfig = loadHooksConfig(pluginConfig);
 
-    // ── Backend init: cloud-first, then local ──
-    let sulcusMem: any = null;
+    // ── Backend init ──
+    let sulcusMem: SulcusCloudClient | null = null;
     let backendMode = "unavailable";
     const nativeLoader = new NativeLibLoader(storeLibPath, vectorsLibPath);
 
-    // Priority 1: Cloud mode — if serverUrl + apiKey are configured, use HTTP.
-    // No local dylibs needed. This is the path for cloud-only users.
     if (serverUrl && apiKey) {
       try {
-        const cloudClient = new SulcusCloudClient(serverUrl, apiKey);
-        sulcusMem = cloudClient;
+        sulcusMem = new SulcusCloudClient(serverUrl, apiKey);
         backendMode = "cloud";
-        api.logger.info(`sulcus: using cloud backend (server: ${serverUrl})`);
-      } catch (e: any) {
-        api.logger.warn(`sulcus: cloud client init failed: ${e.message}`);
+        logger.info(`sulcus: using cloud backend (server: ${serverUrl})`);
+      } catch (e: unknown) {
+        logger.warn(`sulcus: cloud client init failed: ${e instanceof Error ? e.message : e}`);
       }
     }
 
-    // Priority 2: Local WASM+native — if cloud isn't configured or failed,
-    // try loading native dylibs + WASM module for fully local operation.
     if (sulcusMem === null) {
-      nativeLoader.init(api.logger);
+      nativeLoader.init(logger);
       if (nativeLoader.loaded) {
         const wasmJsPath = resolve(wasmDir, "sulcus_wasm.js");
         if (existsSync(wasmJsPath)) {
           try {
-            const { SulcusMem, on_init } = require(wasmJsPath);
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { SulcusMem, on_init } = require(wasmJsPath) as { SulcusMem: { create: (q: unknown, e: unknown) => SulcusCloudClient }; on_init?: () => void };
             if (typeof on_init === "function") on_init();
-
-            const queryFn = nativeLoader.makeQueryFn();
-            const embedFn = nativeLoader.makeEmbedFn();
-            sulcusMem = SulcusMem.create(queryFn, embedFn);
+            sulcusMem = SulcusMem.create(nativeLoader.makeQueryFn(), nativeLoader.makeEmbedFn());
             backendMode = "wasm";
-            api.logger.info(`sulcus: SulcusMem created via WASM (wasm: ${wasmJsPath})`);
-          } catch (e: any) {
-            api.logger.warn(`sulcus: WASM load failed: ${e.message}`);
+            logger.info(`sulcus: SulcusMem created via WASM (wasm: ${wasmJsPath})`);
+          } catch (e: unknown) {
+            logger.warn(`sulcus: WASM load failed: ${e instanceof Error ? e.message : e}`);
           }
         } else {
-          api.logger.warn(`sulcus: WASM module not found at ${wasmJsPath}`);
+          logger.warn(`sulcus: WASM module not found at ${wasmJsPath}`);
         }
       } else {
-        api.logger.info(`sulcus: local mode skipped — ${nativeLoader.error || "dylibs not found"}`);
+        logger.info(`sulcus: local mode skipped — ${nativeLoader.error || "dylibs not found"}`);
       }
     }
 
     const isAvailable = sulcusMem !== null;
+    const isCloudBackend = backendMode === "cloud" && sulcusMem instanceof SulcusCloudClient;
 
     // Update static awareness with runtime info
     STATIC_AWARENESS = buildStaticAwareness(backendMode, namespace);
 
     // ── Startup summary ──
     if (isAvailable) {
-      api.logger.info(`sulcus: ✓ registered (backend: ${backendMode}, namespace: ${namespace})`);
+      logger.info(`sulcus: registered (backend: ${backendMode}, namespace: ${namespace}, autoRecall: ${autoRecall}, autoCapture: ${autoCapture})`);
     } else {
       const hints: string[] = [];
       if (!serverUrl && !apiKey) hints.push("no serverUrl/apiKey for cloud mode");
-      if (serverUrl && !apiKey) hints.push("serverUrl set but apiKey missing");
-      if (!serverUrl && apiKey) hints.push("apiKey set but serverUrl missing");
+      else if (serverUrl && !apiKey) hints.push("serverUrl set but apiKey missing");
+      else if (!serverUrl && apiKey) hints.push("apiKey set but serverUrl missing");
       if (nativeLoader.error) hints.push(`local: ${nativeLoader.error}`);
-      api.logger.warn(`sulcus: ✗ unavailable — ${hints.join("; ") || "unknown reason"}. Configure serverUrl+apiKey for cloud, or install native dylibs for local.`);
+      logger.warn(`sulcus: unavailable — ${hints.join("; ") || "unknown reason"}`);
     }
 
-    // ── SIU v2 request helper (bound to cloud client if available) ──
-    // SIU endpoints live on the same server as the Sulcus API.
-    const siuRequestFn = (backendMode === "cloud" && sulcusMem instanceof SulcusCloudClient)
-      ? (method: string, path: string, body?: any) => (sulcusMem as SulcusCloudClient).request(method, path, body)
+    // ── SIU v2 request helper ──
+    const siuRequestFn = isCloudBackend && sulcusMem
+      ? (method: string, path: string, body?: unknown) => (sulcusMem as SulcusCloudClient).request(method, path, body)
       : null;
 
-    // ── Shared deps for tool executors ──
+    // ── Shared deps ──
     const toolDeps: ToolDeps = {
       sulcusMem,
       backendMode,
@@ -1150,62 +1344,189 @@ const sulcusPlugin = {
       storeLibPath,
       vectorsLibPath,
       wasmDir,
-      logger: api.logger,
+      logger,
       isAvailable,
       siuRequest: siuRequestFn,
     };
 
-    // ── Shared context for hook handlers ──
     const handlerCtx: HookHandlerCtx = {
       sulcusMem,
       backendMode,
       namespace,
-      logger: api.logger,
+      logger,
       nativeError: nativeLoader.error,
       storeLibPath,
       vectorsLibPath,
       wasmDir,
     };
 
-    // ── Config-driven hook registration ──
-    // Each handler is wrapped in a defensive try-catch to prevent plugin errors
-    // from crashing the host agent's startup pipeline (OpenClaw bug workaround:
-    // normalizeResolvedModel() doesn't guard params.model being undefined).
+    // ─────────────────────────────────────────────────────────────────────────
+    // SDK INTEGRATIONS (v4.0.0)
+    // ─────────────────────────────────────────────────────────────────────────
+
+    // 1. registerMemoryRuntime — Sulcus becomes the OpenClaw memory backend
+    if (isCloudBackend && sulcusMem && typeof (api.registerMemoryRuntime as unknown) === "function") {
+      try {
+        (api.registerMemoryRuntime as (r: unknown) => void)(buildMemoryRuntime(sulcusMem as SulcusCloudClient, backendMode));
+        logger.info("sulcus: registered as memory runtime (MemoryPluginRuntime)");
+      } catch (e: unknown) {
+        logger.warn(`sulcus: registerMemoryRuntime failed: ${e instanceof Error ? e.message : e}`);
+      }
+    }
+
+    // 2. registerMemoryPromptSection — dynamic system prompt guidance
+    if (typeof (api.registerMemoryPromptSection as unknown) === "function") {
+      try {
+        (api.registerMemoryPromptSection as (b: unknown) => void)(buildPromptSection);
+        logger.info("sulcus: registered memory prompt section");
+      } catch (e: unknown) {
+        logger.warn(`sulcus: registerMemoryPromptSection failed: ${e instanceof Error ? e.message : e}`);
+      }
+    }
+
+    // 3. registerMemoryFlushPlan — no custom compaction flush
+    if (typeof (api.registerMemoryFlushPlan as unknown) === "function") {
+      try {
+        (api.registerMemoryFlushPlan as (r: unknown) => void)(() => null);
+        logger.info("sulcus: registered memory flush plan (no-op)");
+      } catch (e: unknown) {
+        logger.warn(`sulcus: registerMemoryFlushPlan failed: ${e instanceof Error ? e.message : e}`);
+      }
+    }
+
+    // 4. registerService — lifecycle management
+    if (typeof (api.registerService as unknown) === "function") {
+      try {
+        (api.registerService as (s: unknown) => void)({
+          id: "openclaw-sulcus",
+          start: async (ctx: Record<string, unknown>) => {
+            const svcLogger = (ctx?.logger ?? logger) as PluginLogger;
+            if (!isAvailable || !sulcusMem) {
+              svcLogger.warn("sulcus: service start — backend unavailable, running in degraded mode");
+              return;
+            }
+            if (isCloudBackend) {
+              try {
+                const ok = await (sulcusMem as SulcusCloudClient).probe();
+                if (ok) svcLogger.info(`sulcus: service started — cloud backend connected (${serverUrl}, namespace: ${namespace})`);
+                else svcLogger.warn(`sulcus: service started — cloud backend unreachable (${serverUrl})`);
+              } catch (e
+: unknown) {
+                svcLogger.warn("sulcus: service start probe failed");
+              }
+            } else {
+              svcLogger.info("sulcus: service started (backend: " + backendMode + ", namespace: " + namespace + ")");
+            }
+          },
+          stop: async (ctx: Record<string, unknown>) => {
+            const svcLogger = (ctx?.logger ?? logger) as PluginLogger;
+            svcLogger.info("sulcus: service stopped");
+          },
+        });
+        logger.info("sulcus: registered service lifecycle");
+      } catch (e: unknown) {
+        logger.warn("sulcus: registerService failed: " + (e instanceof Error ? e.message : String(e)));
+      }
+    }
+
+    // 5. Enhanced before_agent_start with prependContext (SDK path)
+    //    When autoRecall=true and cloud backend available, use prependContext SDK pattern.
+    //    Falls back to legacy hook-based path when SDK is not available.
+    if (autoRecall && isCloudBackend && sulcusMem) {
+      const sdkRecallHandler = buildSdkRecallHandler(
+        sulcusMem as SulcusCloudClient,
+        namespace,
+        maxRecallResults,
+        profileFrequency,
+        logger
+      );
+      const apiOn = api.on as (event: string, handler: unknown) => void;
+      apiOn("before_agent_start", async (event: Record<string, unknown>, ctx: unknown) => {
+        try {
+          return await sdkRecallHandler(event, ctx);
+        } catch (err) {
+          logger.warn("sulcus: SDK recall hook threw: " + err);
+          return undefined;
+        }
+      });
+      logger.info("sulcus: registered SDK auto-recall (prependContext path)");
+    }
+
+    // 6. auto-capture on agent_end
+    if (autoCapture) {
+      const agentEndCaptureConfig: HookConfig = {
+        action: "sivu_auto_capture",
+        enabled: true,
+        min_store_confidence: 0.5,
+        fallback_on_error: true,
+      };
+      const apiOn = api.on as (event: string, handler: unknown) => void;
+      apiOn("agent_end", async (event: Record<string, unknown>, _ctx: unknown) => {
+        try {
+          return await hookHandlers.sivu_auto_capture(event, agentEndCaptureConfig, handlerCtx);
+        } catch (err) {
+          logger.warn("sulcus: auto-capture hook threw: " + err);
+          return undefined;
+        }
+      });
+      logger.info("sulcus: registered auto-capture (agent_end)");
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // LEGACY HOOK REGISTRATION (config-driven, backward compat)
+    // ─────────────────────────────────────────────────────────────────────────
+
     for (const [hookName, hookConfig] of Object.entries(hooksConfig.hooks)) {
       if (!hookConfig.enabled) continue;
+
+      // Skip before_agent_start if we already registered the SDK path
+      if (hookName === "before_agent_start" && autoRecall && isCloudBackend) continue;
+      // Skip agent_end if autoCapture SDK path already registered
+      if (hookName === "agent_end" && autoCapture && hookConfig.action === "sivu_auto_capture") continue;
+
       const handler = hookHandlers[hookConfig.action];
       if (handler) {
-        api.on(hookName, async (event: any) => {
+        const apiOn = api.on as (event: string, handler: unknown) => void;
+        apiOn(hookName, async (event: Record<string, unknown>) => {
           try {
             return await handler(event, hookConfig, handlerCtx);
           } catch (err) {
-            api.logger.warn(`sulcus: hook "${hookName}" (action=${hookConfig.action}) threw: ${err} — returning empty result`);
+            logger.warn("sulcus: hook " + hookName + " (action=" + hookConfig.action + ") threw: " + err);
             return undefined;
           }
         });
       } else {
-        api.logger.warn(`sulcus: unknown hook action "${hookConfig.action}" for hook "${hookName}"`);
+        logger.warn("sulcus: unknown hook action " + hookConfig.action + " for hook " + hookName);
       }
     }
 
-    // ── Config-driven tool registration ──
+    // ─────────────────────────────────────────────────────────────────────────
+    // TOOL REGISTRATION
+    // ─────────────────────────────────────────────────────────────────────────
+
     for (const [toolName, toolConfig] of Object.entries(hooksConfig.tools)) {
       if (!toolConfig.enabled) continue;
       const toolDef = toolDefinitions[toolName];
       if (toolDef) {
         const schema = {
           ...toolDef.schema,
-          async execute(id: string, params: any) {
+          async execute(id: string, params: Record<string, unknown>) {
             return toolDef.makeExecute(toolDeps)(id, params);
           },
         };
-        api.registerTool(schema, toolDef.options);
+        const registerTool = api.registerTool as (schema: unknown, opts: unknown) => void;
+        registerTool(schema, toolDef.options);
       } else {
-        api.logger.warn(`sulcus: unknown tool "${toolName}" in config — skipping`);
+        logger.warn("sulcus: unknown tool " + toolName + " in config — skipping");
       }
     }
 
-    // No service registration needed — no background process to manage
+    // Fire-and-forget first-install history import
+    if (isAvailable && sulcusMem instanceof SulcusCloudClient) {
+      importOpenClawHistory(sulcusMem, logger).catch((e: unknown) => {
+        logger.warn(`sulcus: history import failed: ${e instanceof Error ? e.message : String(e)}`);
+      });
+    }
   }
 };