@digitalforgestudios/openclaw-sulcus 4.2.0 → 5.3.0

package/README.md

@@ -103,4 +103,4 @@ Choose the right type — decay rates differ significantly:
 
 ## License
 
-MIT — [Digital Forge Studios](https://dforge.ca)
+MIT — [Digital Forge Studios Inc.](https://dforge.ca)

package/hooks.defaults.json

@@ -3,14 +3,17 @@
   "version": 1,
   "hooks": {
     "before_prompt_build": {
-      "action": "inject_awareness",
-      "enabled": false
+      "action": "auto_recall",
+      "enabled": false,
+      "limit": 5,
+      "minScore": 0.3
     },
     "before_agent_start": {
       "action": "auto_recall",
       "enabled": false,
       "limit": 5,
-      "minScore": 0.3
+      "minScore": 0.3,
+      "_deprecated": "Use before_prompt_build instead. Legacy compat only."
     },
     "agent_end": {
       "action": "none",

package/index.ts

@@ -91,7 +91,7 @@ const hookHandlers: Record<string, HookHandler> = {
     const { sulcusMem, namespace, logger } = ctx;
     if (!sulcusMem) return;
     const agentLabel = (event?.agentId as string) ?? "(unknown)";
-    logger.info(`sulcus: before_agent_start hook triggered for agent ${agentLabel}`);
+    logger.info(`sulcus: auto_recall hook triggered for agent ${agentLabel}`);
     const prompt = typeof event?.prompt === "string" ? event.prompt : "";
     if (!prompt) return;
     try {
@@ -410,6 +410,27 @@ class SulcusCloudClient {
     return this.request("POST", "/api/v1/triggers/evaluate", body);
   }
 
+  async embed_text(text: string, namespace?: string): Promise<{ embedding: number[]; model: string; dimensions: number } | null> {
+    // NOTE: Requires Sulcus server >= v2.4 with /api/v1/agent/embed endpoint.
+    // Falls back to null if the endpoint is not available — caller handles gracefully.
+    try {
+      const body: Record<string, unknown> = { text };
+      if (namespace) body.namespace = namespace;
+      const res = await this.request("POST", "/api/v1/agent/embed", body) as Record<string, unknown> | null;
+      if (!res || !Array.isArray(res.embedding)) return null;
+      return {
+        embedding: res.embedding as number[],
+        model: (res.model as string) ?? "bge-small-en-v1.5",
+        dimensions: (res.dimensions as number) ?? (res.embedding as number[]).length,
+      };
+    } catch (e: unknown) {
+      // 404 = endpoint not deployed yet; warn once but don't break anything
+      const msg = e instanceof Error ? e.message : String(e);
+      if (msg.includes("404")) return null; // endpoint not available on this server version
+      throw e;
+    }
+  }
+
   async probe(): Promise<boolean> {
     try {
       await this.search_memory("probe", 1);
@@ -631,8 +652,13 @@ function loadHooksConfig(apiConfig: Record<string, unknown>): HooksConfig {
     mergedTools[name] = { ...(mergedTools[name] ?? { enabled: false }), ...override };
   }
 
-  // Legacy compat: autoRecall flag → hooks.before_agent_start.enabled
+  // Legacy compat: autoRecall flag → hooks.before_prompt_build.enabled (v5.0.0+)
+  // Also keeps before_agent_start enabled for backward compat with older configs.
   if (apiConfig?.autoRecall === true) {
+    mergedHooks["before_prompt_build"] = {
+      ...(mergedHooks["before_prompt_build"] ?? { action: "auto_recall", enabled: false }),
+      enabled: true,
+    };
     mergedHooks["before_agent_start"] = {
       ...(mergedHooks["before_agent_start"] ?? { action: "auto_recall", enabled: false }),
       enabled: true,
@@ -664,7 +690,7 @@ function formatRelativeTime(isoTimestamp: string): string {
   }
 }
 
-// ─── SDK RECALL HANDLER (for before_agent_start with prependContext) ──────────
+// ─── SDK RECALL HANDLER (for before_prompt_build with prependContext) ──────────
 
 interface ProfileCache {
   preferences: Record<string, unknown>[];
@@ -1429,30 +1455,80 @@ const sulcusPlugin = {
       }
     }
 
-    // 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)");
+    // 5. before_prompt_build — recall + awareness (SDK path, v5.0.0+)
+    //    When autoRecall=true and cloud backend available: recall + inject awareness via prependContext.
+    //    When autoRecall=false but cloud backend available: inject awareness only (static context block).
+    //    Replaces legacy before_agent_start for new work; legacy hook loop handles fallback.
+    if (isCloudBackend && sulcusMem) {
+      if (autoRecall) {
+        const sdkRecallHandler = buildSdkRecallHandler(
+          sulcusMem as SulcusCloudClient,
+          namespace,
+          maxRecallResults,
+          profileFrequency,
+          logger
+        );
+        const apiOn = api.on as (event: string, handler: unknown) => void;
+        apiOn("before_prompt_build", async (event: Record<string, unknown>, ctx: unknown) => {
+          try {
+            // Recall returns prependContext with memories + awareness embedded
+            const result = await sdkRecallHandler(event, ctx);
+            // If recall returned nothing (no prompt), fall back to awareness-only
+            if (!result) return { prependSystemContext: STATIC_AWARENESS };
+            // Translate prependContext → prependSystemContext for hook shape compat
+            const r = result as { prependContext?: string; prependSystemContext?: string };
+            if (r.prependContext) return { prependSystemContext: r.prependContext };
+            return result;
+          } catch (err) {
+            logger.warn("sulcus: before_prompt_build recall hook threw: " + err);
+            return { prependSystemContext: STATIC_AWARENESS };
+          }
+        });
+        logger.info("sulcus: registered before_prompt_build (recall + awareness)");
+      } else {
+        // Awareness-only path — inject static context without recall
+        const apiOn = api.on as (event: string, handler: unknown) => void;
+        apiOn("before_prompt_build", async (_event: Record<string, unknown>, _ctx: unknown) => {
+          return { prependSystemContext: STATIC_AWARENESS };
+        });
+        logger.info("sulcus: registered before_prompt_build (awareness-only)");
+      }
+    }
+
+    // 6. registerMemoryEmbeddingProvider — Sulcus embedding adapter
+    if (typeof (api.registerMemoryEmbeddingProvider as unknown) === "function" && isCloudBackend && sulcusMem) {
+      try {
+        (api.registerMemoryEmbeddingProvider as (adapter: unknown) => void)({
+          id: "sulcus",
+          label: "Sulcus (BGE-small-en-v1.5)",
+          transport: "remote",
+          autoSelectPriority: 50,
+          embed: async (texts: string[]) => {
+            // Route through Sulcus cloud API for embeddings
+            let warned = false;
+            const results = await Promise.all(
+              texts.map(async (text) => {
+                const res = await (sulcusMem as SulcusCloudClient).embed_text(text, namespace);
+                if (!res) {
+                  if (!warned) {
+                    warned = true;
+                    logger.warn("sulcus: embed_text returned null — /api/v1/agent/embed not available on this server version; embedding provider will return empty vectors");
+                  }
+                  return [];
+                }
+                return res.embedding;
+              })
+            );
+            return { embeddings: results, model: "bge-small-en-v1.5", dimensions: 384 };
+          },
+        });
+        logger.info("sulcus: registered memory embedding provider (BGE-small-en-v1.5)");
+      } catch (e: unknown) {
+        logger.warn(`sulcus: registerMemoryEmbeddingProvider failed: ${e instanceof Error ? e.message : e}`);
+      }
     }
 
-    // 6. auto-capture on agent_end
+    // 7. auto-capture on agent_end
     if (autoCapture) {
       const agentEndCaptureConfig: HookConfig = {
         action: "sivu_auto_capture",
@@ -1479,8 +1555,10 @@ const sulcusPlugin = {
     for (const [hookName, hookConfig] of Object.entries(hooksConfig.hooks)) {
       if (!hookConfig.enabled) continue;
 
-      // Skip before_agent_start if we already registered the SDK path
+      // Skip before_agent_start if we already registered the SDK path (v5: SDK uses before_prompt_build)
       if (hookName === "before_agent_start" && autoRecall && isCloudBackend) continue;
+      // Skip before_prompt_build if we already registered the SDK handler above
+      if (hookName === "before_prompt_build" && isCloudBackend && sulcusMem) continue;
       // Skip agent_end if autoCapture SDK path already registered
       if (hookName === "agent_end" && autoCapture && hookConfig.action === "sivu_auto_capture") continue;
 

package/openclaw.plugin.json

@@ -2,7 +2,10 @@
   "id": "openclaw-sulcus",
   "kind": "memory",
   "name": "Sulcus",
-  "description": "Thermodynamic memory + Apache AGE knowledge graph for AI agents. SIU v2 pipeline (SIVU/SICU/SILU/SITU) auto-classifies and scores every memory. Interaction-based decay (Time-only, Interaction-only, Hybrid). Curator sleep-cycle reclassifies and consolidates. Relevance-weighted recall (similarity × 0.7 + heat × 0.3). Confidence levels and conflict detection (v2.3.0). 52 API routes, 32 server modules. Runs locally via WASM + native dylibs; optional cloud sync via serverUrl/apiKey.",
+  "description": "Thermodynamic memory + Apache AGE knowledge graph for AI agents. v5: before_prompt_build hook (replaces before_agent_start), registerMemoryEmbeddingProvider (BGE-small-en-v1.5 via cloud API). SIU v2 pipeline (SIVU/SICU/SILU/SITU) auto-classifies and scores every memory. Interaction-based decay (Time-only, Interaction-only, Hybrid). Curator sleep-cycle reclassifies and consolidates. Relevance-weighted recall (similarity × 0.7 + heat × 0.3). Confidence levels and conflict detection (v2.3.0). 52 API routes, 32 server modules. Runs locally via WASM + native dylibs; optional cloud sync via serverUrl/apiKey.",
+  "contracts": {
+    "memoryEmbeddingProviders": ["sulcus"]
+  },
   "privacy": {
     "consentModel": "local-first",
     "consentNote": "Plugin runs entirely in-process. No network calls. All data stays local in ~/.sulcus/. Cloud sync is opt-in via serverUrl/apiKey config, handled by sulcus-sync dylib loaded by sulcus.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "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.",
+  "version": "5.3.0",
+  "description": "Sulcus — thermodynamic memory + Apache AGE knowledge graph for OpenClaw agents. v5: before_prompt_build hook migration (replaces before_agent_start), registerMemoryEmbeddingProvider (BGE-small-en-v1.5 via cloud API), 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",
     "openclaw-plugin",