@digitalforgestudios/openclaw-sulcus 3.6.0 → 3.8.0

package/README.md

@@ -51,6 +51,46 @@ Then restart: `openclaw gateway restart`
 | `memory_store` | Store with auto-detected type |
 | `memory_forget` | Delete by ID |
 
+## Hooks & Extended Tools
+
+All hooks and tools are **enabled by default**. Override in your `openclaw.json` plugin config:
+
+```json
+"openclaw-sulcus": {
+  "enabled": true,
+  "config": {
+    "apiKey": "sk-YOUR_KEY_HERE",
+    "hooks": {
+      "before_prompt_build": { "action": "inject_awareness", "enabled": true },
+      "before_agent_start": { "action": "auto_recall", "enabled": true, "limit": 5, "minScore": 0.3 },
+      "agent_end": { "action": "none", "enabled": true }
+    },
+    "tools": {
+      "memory_recall": { "enabled": true },
+      "memory_store": { "enabled": true },
+      "memory_status": { "enabled": true },
+      "consolidate": { "enabled": true },
+      "export_markdown": { "enabled": true },
+      "import_markdown": { "enabled": true },
+      "evaluate_triggers": { "enabled": true }
+    }
+  }
+}
+```
+
+| Hook | Default | Description |
+|---|---|---|
+| `before_prompt_build` | ON | Inject memory awareness context into prompts |
+| `before_agent_start` | ON | Auto-recall relevant memories each turn |
+| `agent_end` | ON | Post-turn processing |
+
+| Extended Tool | Default | Description |
+|---|---|---|
+| `consolidate` | ON | Cluster and merge similar memories |
+| `export_markdown` | ON | Export memories as markdown |
+| `import_markdown` | ON | Import memories from markdown |
+| `evaluate_triggers` | ON | Run reactive trigger evaluations |
+
 ## Features
 
 - **Auto-recall** — relevant memories injected before each agent turn

package/hooks.defaults.json

@@ -18,12 +18,16 @@
     }
   },
   "tools": {
-    "memory_recall": { "enabled": false },
-    "memory_store": { "enabled": false },
-    "memory_status": { "enabled": false },
+    "memory_recall": { "enabled": true },
+    "memory_store": { "enabled": true },
+    "memory_status": { "enabled": true },
     "consolidate": { "enabled": false },
     "export_markdown": { "enabled": false },
     "import_markdown": { "enabled": false },
-    "evaluate_triggers": { "enabled": false }
+    "evaluate_triggers": { "enabled": false },
+    "siu_label": { "enabled": false },
+    "siu_status": { "enabled": false },
+    "siu_retrain": { "enabled": false },
+    "trigger_feedback": { "enabled": false }
   }
 }

package/index.ts

@@ -98,12 +98,14 @@ const hookHandlers: Record<string, HookHandler> = {
   auto_recall: async (event: any, config: HookConfig, ctx: HookHandlerCtx) => {
     const { sulcusMem, namespace, logger } = ctx;
     if (!sulcusMem) return;
-    logger.info(`sulcus: before_agent_start hook triggered for agent ${event.agentId}`);
-    if (!event.prompt) return;
+    const agentLabel = event?.agentId ?? "(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: ${event.prompt.substring(0, 50)}...`);
-      const res = await sulcusMem.search_memory(event.prompt, limit);
+      logger.debug(`sulcus: searching context for prompt: ${prompt.substring(0, 50)}...`);
+      const res = await sulcusMem.search_memory(prompt, limit);
       const results = res?.results ?? [];
       if (!results || results.length === 0) {
         return { prependSystemContext: FALLBACK_AWARENESS };
@@ -129,6 +131,74 @@ const hookHandlers: Record<string, HookHandler> = {
   none: async (event: any, _config: HookConfig, ctx: HookHandlerCtx) => {
     ctx.logger.debug(`sulcus: hook fired (action=none) for agent ${event.agentId ?? "(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) => {
+    const { sulcusMem, logger } = ctx;
+    if (!sulcusMem) return;
+
+    // Extract user message from the event
+    const userMessage = event?.userMessage ?? event?.prompt ?? event?.text ?? "";
+    if (!userMessage || typeof userMessage !== "string") {
+      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)}..."`);
+      return;
+    }
+
+    const minConfidence = config.min_store_confidence ?? 0.5;
+    const fallbackOnError = config.fallback_on_error !== false; // default true
+
+    // 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";
+
+        if (!shouldStore) {
+          logger.info(`sulcus: sivu_auto_capture — SIVU rejected (confidence: ${siuResult?.store_confidence?.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)}..."`);
+        return;
+      } catch (e: any) {
+        logger.warn(`sulcus: sivu_auto_capture — SIU v2 endpoint error: ${e.message}`);
+        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}`);
+    }
+  },
 };
 
 // ─── CLOUD HTTP CLIENT ───────────────────────────────────────────────────────
@@ -147,7 +217,7 @@ class SulcusCloudClient {
   }
 
   /** Low-level HTTP helper. Returns parsed JSON response body. */
-  private request(method: string, path: string, body?: any): Promise<any> {
+  request(method: string, path: string, body?: any): Promise<any> {
     return new Promise((resolve, reject) => {
       let parsedUrl: URL;
       try {
@@ -519,6 +589,8 @@ interface ToolDeps {
   wasmDir: string;
   logger: any;
   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;
 }
 
 const toolDefinitions: Record<string, ToolDefinition> = {
@@ -729,6 +801,155 @@ const toolDefinitions: Record<string, ToolDefinition> = {
         };
       },
   },
+
+  // ── 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.",
+      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" },
+          };
+        }
+        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 },
+          };
+        }
+      },
+  },
+
+  siu_status: {
+    schema: {
+      name: "siu_status",
+      label: "SIU Status",
+      description: "Check SIU v2 model availability, deployed versions, and training signal statistics.",
+      parameters: Type.Object({}),
+    },
+    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" },
+          };
+        }
+        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 },
+          };
+        }
+      },
+  },
+
+  siu_retrain: {
+    schema: {
+      name: "siu_retrain",
+      label: "SIU Retrain",
+      description: "Trigger an async retrain of SIU v2 models using accumulated training signals. Returns job status.",
+      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" },
+          };
+        }
+        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 },
+          };
+        }
+      },
+  },
+  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.",
+      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)',
+        }),
+        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." })),
+        memory_id: Type.Optional(Type.String({ description: "UUID of the memory involved" })),
+        expected_action: Type.Optional(Type.String({ description: "What should have happened: fire, no_fire, different_action" })),
+        notes: Type.Optional(Type.String({ description: "Free-text explanation of the feedback" })),
+      }),
+    },
+    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" },
+          };
+        }
+        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 },
+          };
+        }
+      },
+  },
 };
 
 // ─── PLUGIN ──────────────────────────────────────────────────────────────────
@@ -832,6 +1053,12 @@ const sulcusPlugin = {
       api.logger.warn(`sulcus: ✗ unavailable — ${hints.join("; ") || "unknown reason"}. Configure serverUrl+apiKey for cloud, or install native dylibs for local.`);
     }
 
+    // ── 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)
+      : null;
+
     // ── Shared deps for tool executors ──
     const toolDeps: ToolDeps = {
       sulcusMem,
@@ -843,6 +1070,7 @@ const sulcusPlugin = {
       wasmDir,
       logger: api.logger,
       isAvailable,
+      siuRequest: siuRequestFn,
     };
 
     // ── Shared context for hook handlers ──
@@ -858,11 +1086,21 @@ const sulcusPlugin = {
     };
 
     // ── 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).
     for (const [hookName, hookConfig] of Object.entries(hooksConfig.hooks)) {
       if (!hookConfig.enabled) continue;
       const handler = hookHandlers[hookConfig.action];
       if (handler) {
-        api.on(hookName, (event: any) => handler(event, hookConfig, handlerCtx));
+        api.on(hookName, async (event: any) => {
+          try {
+            return await handler(event, hookConfig, handlerCtx);
+          } catch (err) {
+            api.logger.warn(`sulcus: hook "${hookName}" (action=${hookConfig.action}) threw: ${err} — returning empty result`);
+            return undefined;
+          }
+        });
       } else {
         api.logger.warn(`sulcus: unknown hook action "${hookConfig.action}" for hook "${hookName}"`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Sulcus — reactive, thermodynamic memory plugin for OpenClaw. Opt-in persistent memory with heat-based decay, semantic search, and cross-agent sync. Auto-recall and auto-capture disabled by default.",
   "keywords": [
     "openclaw",