@digitalforgestudios/openclaw-sulcus 4.0.0 → 4.2.0

package/hooks.defaults.json

@@ -15,6 +15,14 @@
     "agent_end": {
       "action": "none",
       "enabled": false
+    },
+    "after_tool_call": {
+      "action": "auto_error_capture",
+      "enabled": true
+    },
+    "before_compaction": {
+      "action": "pre_compaction_capture",
+      "enabled": true
     }
   },
   "tools": {
@@ -28,6 +36,7 @@
     "siu_label": { "enabled": false },
     "siu_status": { "enabled": false },
     "siu_retrain": { "enabled": false },
-    "trigger_feedback": { "enabled": false }
+    "trigger_feedback": { "enabled": false },
+    "__sulcus_workflow__": { "enabled": true }
   }
 }

package/index.ts

@@ -144,6 +144,11 @@ const hookHandlers: Record<string, HookHandler> = {
       return;
     }
 
+    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;
 
@@ -179,6 +184,111 @@ const hookHandlers: Record<string, HookHandler> = {
       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 ───────────────────────────────────────────────────────
@@ -461,6 +571,22 @@ 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 ─────────────────────────────────────────────────────
 
 function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
@@ -476,6 +602,8 @@ function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
         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 },
@@ -485,6 +613,7 @@ function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
         export_markdown: { enabled: false },
         import_markdown: { enabled: false },
         evaluate_triggers: { enabled: false },
+        __sulcus_workflow__: { enabled: true },
       },
     };
   }
@@ -1006,8 +1135,99 @@ const toolDefinitions: Record<string, ToolDefinition> = {
         }
       },
   },
+
+  __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 = {
@@ -1300,6 +1520,13 @@ const sulcusPlugin = {
         logger.warn("sulcus: unknown tool " + toolName + " in config — skipping");
       }
     }
+
+    // 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)}`);
+      });
+    }
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Sulcus — thermodynamic memory + Apache AGE knowledge graph for OpenClaw agents. v4: registerMemoryRuntime, prependContext recall, registerMemoryPromptSection, registerService lifecycle, uiHints, provider-filtered auto-capture. SIU v2 pipeline auto-classifies and scores memories. Interaction-based decay (3 modes). Curator sleep-cycle. Relevance-weighted recall. Cross-agent sync.",
   "keywords": [
     "openclaw",