@digitalforgestudios/openclaw-sulcus 1.5.3 → 2.0.0

package/index.ts

@@ -31,7 +31,7 @@ Memories survive across sessions. They have heat (0.0–1.0) that decays over ti
 }
 
 // Legacy static string for backward compat (overwritten at register time)
-let STATIC_AWARENESS = buildStaticAwareness("unknown", "default", "unknown");
+let STATIC_AWARENESS = buildStaticAwareness("local", "default", "local");
 
 // Fallback context when build_context fails — includes the cheatsheet
 // but warns that dynamic context is unavailable.
@@ -49,33 +49,46 @@ const FALLBACK_AWARENESS = `<sulcus_context token_budget="500">
   </cheatsheet>
 </sulcus_context>`;
 
-// Simple MCP Client for sulcus-local
+// MCP-over-stdio client for sulcus-local
+// This is the ONLY communication path — no REST/network calls in this plugin.
+// If serverUrl/apiKey are configured, they are passed as env vars to the spawn()
+// call below so that sulcus-sync (a dylib loaded by sulcus-local) can pick them
+// up for cloud replication. The plugin itself never makes any HTTP calls.
 class SulcusClient {
   private child: ChildProcess | null = null;
   private nextId = 1;
   private pending = new Map<string | number, (res: any) => void>();
   private configPath: string | undefined;
+  private spawnEnv: Record<string, string>;
 
-  constructor(private binaryPath: string, configPath?: string) {
+  constructor(
+    private binaryPath: string,
+    configPath?: string,
+    spawnEnv: Record<string, string> = {}
+  ) {
     this.configPath = configPath;
+    this.spawnEnv = spawnEnv;
   }
 
-  // SECURITY NOTE: spawn() launches the sulcus-local binary (a Rust MCP server)
-  // as a child process for local-only operation. No user data is passed via argv
-  // or env vars — only RUST_LOG for log verbosity. This is the standard MCP sidecar
-  // pattern used by Claude Desktop, Cursor, etc. Only used when serverUrl is empty
-  // (local mode). When serverUrl is set, REST API is used instead (no spawn).
+  // Launches sulcus-local binary as an MCP stdio sidecar.
+  // serverUrl/apiKey (if any) are passed via environment variables so that
+  // sulcus-sync (dylib) can perform cloud replication without this plugin
+  // making any network calls itself.
   async start(configPath?: string) {
     const cfgPath = configPath || this.configPath;
     const args = cfgPath ? ["--config", cfgPath, "stdio"] : ["stdio"];
     this.child = spawn(this.binaryPath, args, {
       stdio: ["pipe", "pipe", "inherit"],
-      env: { ...process.env, RUST_LOG: "info" }  // Only passes log-level config, not secrets
+      env: {
+        ...process.env,
+        RUST_LOG: "info",
+        ...this.spawnEnv,   // SULCUS_SERVER_URL and SULCUS_API_KEY forwarded here
+      }
     });
 
     this.child.on("error", (err) => {
       // Reject all pending calls if the process dies
-      for (const [id, resolve] of this.pending) {
+      for (const [_id, resolve] of this.pending) {
         resolve({ error: { code: -1, message: `Sulcus process error: ${err.message}` } });
       }
       this.pending.clear();
@@ -83,7 +96,7 @@ class SulcusClient {
     });
 
     this.child.on("exit", (code) => {
-      for (const [id, resolve] of this.pending) {
+      for (const [_id, resolve] of this.pending) {
         resolve({ error: { code: -1, message: `Sulcus process exited with code ${code}` } });
       }
       this.pending.clear();
@@ -114,13 +127,13 @@ class SulcusClient {
         clearTimeout(timeout);
         if (res.error) reject(new Error(res.error.message));
         else {
-            // MCP result format
-            try {
-                const content = JSON.parse(res.result.content[0].text);
-                resolve(content);
-            } catch(e) {
-                resolve(res.result);
-            }
+          // MCP result format
+          try {
+            const content = JSON.parse(res.result.content[0].text);
+            resolve(content);
+          } catch (e) {
+            resolve(res.result);
+          }
         }
       });
       this.child!.stdin!.write(JSON.stringify(request) + "\n");
@@ -132,173 +145,16 @@ class SulcusClient {
   }
 }
 
-// REST API client — fallback when sulcus-local binary isn't available
-class SulcusRestClient {
-  constructor(
-    private serverUrl: string,
-    private apiKey: string,
-    private namespace: string,
-    private logger: any
-  ) {}
-
-  private async fetch(path: string, options: RequestInit = {}): Promise<any> {
-    const url = `${this.serverUrl}${path}`;
-    const headers: Record<string, string> = {
-      "Authorization": `Bearer ${this.apiKey}`,
-      "Content-Type": "application/json",
-      ...(options.headers as Record<string, string> || {}),
-    };
-    const res = await globalThis.fetch(url, { ...options, headers });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      throw new Error(`Sulcus API ${res.status}: ${text}`);
-    }
-    return res.json();
-  }
-
-  async searchMemory(query: string, limit: number = 5): Promise<any> {
-    const raw = await this.fetch("/api/v1/agent/search", {
-      method: "POST",
-      body: JSON.stringify({ query, namespace: this.namespace, limit }),
-    });
-    // Normalize: server returns {results, provenance} — ensure .results is always accessible
-    // Also handle flat array (backward compat) and .items/.nodes variants
-    const results = raw?.results ?? raw?.items ?? raw?.nodes ?? (Array.isArray(raw) ? raw : []);
-    return { results, provenance: raw?.provenance || { backend: "cloud", namespace: this.namespace } };
-  }
-
-  async recordMemory(params: any): Promise<any> {
-    const raw = await this.fetch("/api/v1/agent/nodes", {
-      method: "POST",
-      body: JSON.stringify({
-        label: params.content,
-        memory_type: params.memory_type || "episodic",
-        namespace: params.fold_name || this.namespace,
-        heat: 0.8,
-      }),
-    });
-    // Normalize: ensure node_id is accessible (server returns "id")
-    return { ...raw, node_id: raw?.id || raw?.node_id };
-  }
-
-  async getMemory(id: string): Promise<any> {
-    return this.fetch(`/api/v1/agent/nodes/${id}`);
-  }
-
-  async deleteMemory(id: string): Promise<any> {
-    return this.fetch(`/api/v1/agent/nodes/${id}`, { method: "DELETE" });
-  }
-
-  async buildContext(prompt: string, tokenBudget: number = 2000): Promise<any> {
-    // REST doesn't have a build_context endpoint — search for relevant memories instead
-    const res = await this.searchMemory(prompt, 10);
-    const results = res?.results || res || [];
-    if (!results.length) return null;
-
-    // Build a simple context string from results
-    const items = results.slice(0, 5).map((r: any) =>
-      `[${r.memory_type || "memory"}] ${r.pointer_summary || r.label || ""}`
-    ).join("\n");
-    return `<sulcus_context source="cloud" namespace="${this.namespace}">\n${items}\n</sulcus_context>`;
-  }
-
-  async getStatus(): Promise<any> {
-    return this.fetch("/api/v1/agent/memory/status");
-  }
-}
-
-// ─── CLIENT-SIDE SIU (Semantic Inference Unit) ───────────────────────────────
-// JSON weights classifier: scale → dot → sigmoid. Zero native deps.
-// Downloads model from server on first use, caches locally.
-
-interface SiuModel {
-  classes: string[];
-  scaler_mean: number[];
-  scaler_scale: number[];
-  coefficients: number[][];
-  intercepts: number[];
-  n_features: number;
-  default_threshold: number;
-}
-
-class ClientSiu {
-  private model: SiuModel | null = null;
-  private modelPath: string;
-  private serverUrl: string;
-  private apiKey: string;
-
-  constructor(cacheDir: string, serverUrl: string, apiKey: string) {
-    this.modelPath = resolve(cacheDir, "memory_classifier_multilabel.json");
-    this.serverUrl = serverUrl;
-    this.apiKey = apiKey;
-  }
-
-  // SECURITY NOTE: SIU (Semantic Intelligence Unit) model is a JSON classifier
-  // for memory type detection. Downloaded once from the configured Sulcus server,
-  // then cached locally at ~/.sulcus/cache/. File read is local cache check only —
-  // no user data is sent. The download sends only the API key for auth, not file
-  // contents. This is a standard model-caching pattern (like downloading an ONNX model).
-  async ensureModel(): Promise<SiuModel | null> {
-    if (this.model) return this.model;
-    const { existsSync, readFileSync, writeFileSync, mkdirSync } = require("node:fs");
-    const { dirname } = require("node:path");
-
-    // Try loading cached model — local file read, no network
-    if (existsSync(this.modelPath)) {
-      try {
-        this.model = JSON.parse(readFileSync(this.modelPath, "utf8"));
-        return this.model;
-      } catch { }
-    }
-
-    // Download from server
-    if (!this.serverUrl || !this.apiKey) return null;
-    try {
-      const res = await globalThis.fetch(
-        `${this.serverUrl}/api/v1/agent/siu-model`,
-        { headers: { "Authorization": `Bearer ${this.apiKey}` } }
-      );
-      if (res.ok) {
-        const data = await res.json();
-        mkdirSync(dirname(this.modelPath), { recursive: true });
-        writeFileSync(this.modelPath, JSON.stringify(data));
-        this.model = data;
-        return this.model;
-      }
-    } catch { }
-    return null;
-  }
+// NOTE: SulcusRestClient was removed — the plugin no longer makes any HTTP/REST
+// calls. All communication with sulcus-local goes through MCP over stdio via
+// SulcusClient above. If serverUrl/apiKey are provided in config, they are
+// forwarded as SULCUS_SERVER_URL / SULCUS_API_KEY environment variables to the
+// sulcus-local spawn so that sulcus-sync (dylib) can replicate to the cloud
+// without this plugin touching the network.
 
-  // Classify using pre-computed embedding (384-dim)
-  classifyEmbedding(embedding: number[]): { type: string; confidence: number; all: Record<string, number> } | null {
-    if (!this.model) return null;
-    const m = this.model;
-    if (embedding.length !== m.n_features) return null;
-
-    // Scale: (x - mean) / scale
-    const scaled = embedding.map((x, i) => (x - m.scaler_mean[i]) / m.scaler_scale[i]);
-
-    // Dot product + sigmoid for each class
-    const scores: Record<string, number> = {};
-    let bestType = "episodic";
-    let bestScore = 0;
-
-    for (let c = 0; c < m.classes.length; c++) {
-      let dot = m.intercepts[c];
-      for (let f = 0; f < m.n_features; f++) {
-        dot += scaled[f] * m.coefficients[c][f];
-      }
-      const sigmoid = 1 / (1 + Math.exp(-dot));
-      scores[m.classes[c]] = sigmoid;
-      if (sigmoid > bestScore) {
-        bestScore = sigmoid;
-        bestType = m.classes[c];
-      }
-    }
-
-    return { type: bestType, confidence: bestScore, all: scores };
-  }
-}
+// NOTE: SiuClassifier / ClientSiu / SiuModel were removed — sulcus-local
+// already has fastembed + ONNX for embeddings and handles classification
+// internally. A future PR may expose classification via an MCP tool if needed.
 
 // ─── PRE-SEND FILTER ─────────────────────────────────────────────────────────
 // Rule-based junk filter. Catches obvious noise before it hits the API.
@@ -342,63 +198,42 @@ const sulcusPlugin = {
     const namespace = api.config?.namespace === "default" && agentId
       ? agentId
       : (api.config?.namespace || agentId || "default");
+
+    // serverUrl/apiKey are NOT used by this plugin for HTTP calls.
+    // They are forwarded as env vars to sulcus-local so sulcus-sync (dylib)
+    // can replicate memories to the cloud without any network calls here.
     const serverUrl = api.config?.serverUrl || "";
     const apiKey = api.config?.apiKey || "";
-    const client = new SulcusClient(binaryPath, iniPath);
 
-    // Detect backend mode: if serverUrl is set and binaryPath doesn't exist, it's cloud-only
-    let backendMode = "local"; // default assumption
+    // Build spawn env: pass cloud config to sulcus-local via environment
+    const spawnEnv: Record<string, string> = {};
+    if (serverUrl) spawnEnv["SULCUS_SERVER_URL"] = serverUrl;
+    if (apiKey)    spawnEnv["SULCUS_API_KEY"]    = apiKey;
+
+    const client = new SulcusClient(binaryPath, iniPath, spawnEnv);
+
+    // Check binary availability
     let hasBinary = false;
     try {
       const { existsSync } = require("node:fs");
       hasBinary = existsSync(binaryPath);
-      if (!hasBinary) {
-        backendMode = serverUrl ? "cloud" : "unavailable";
-      } else {
-        backendMode = serverUrl ? "hybrid" : "local";
-      }
     } catch { }
 
-    // REST client for cloud fallback (or cloud-only mode)
-    const restClient = serverUrl && apiKey
-      ? new SulcusRestClient(serverUrl, apiKey, namespace, api.logger)
-      : null;
+    const backendMode = hasBinary ? "local" : "unavailable";
 
-    // Unified call helper: try local binary first, fall back to REST
+    // All memory calls go exclusively through MCP — no REST fallback.
+    // If the MCP client isn't connected (binary missing or crashed), we return
+    // an error rather than falling back to HTTP.
     async function memoryCall(method: string, params: any): Promise<any> {
-      if (hasBinary) {
-        try {
-          return await client.call(method, params);
-        } catch (e: any) {
-          api.logger.warn(`memory-sulcus: local binary failed (${method}): ${e.message}, falling back to REST`);
-          if (!restClient) throw e;
-        }
-      }
-      if (!restClient) throw new Error("Sulcus unavailable: no binary and no server configured");
-      // Route to appropriate REST method
-      switch (method) {
-        case "search_memory": return restClient.searchMemory(params.query, params.limit);
-        case "record_memory": return restClient.recordMemory(params);
-        case "build_context": return restClient.buildContext(params.prompt, params.token_budget);
-        default: throw new Error(`Unknown method: ${method}`);
+      if (!hasBinary) {
+        throw new Error(`Sulcus unavailable: binary not found at ${binaryPath}`);
       }
+      return client.call(method, params);
     }
 
     // Update static awareness with runtime info
     STATIC_AWARENESS = buildStaticAwareness(backendMode, namespace, serverUrl || "local");
 
-    // Initialize client-side SIU
-    const siuCacheDir = resolve(process.env.HOME || "~", ".cache/sulcus/model");
-    const clientSiu = serverUrl && apiKey ? new ClientSiu(siuCacheDir, serverUrl, apiKey) : null;
-
-    // Pre-load SIU model (non-blocking)
-    if (clientSiu) {
-      clientSiu.ensureModel().then(m => {
-        if (m) api.logger.info(`memory-sulcus: client SIU loaded (${m.classes.length} classes, ${m.n_features} features)`);
-        else api.logger.warn("memory-sulcus: client SIU model not available");
-      }).catch(() => {});
-    }
-
     api.logger.info(`memory-sulcus: registered (binary: ${binaryPath}, hasBinary: ${hasBinary}, namespace: ${namespace}, backend: ${backendMode})`);
 
     // ── Core memory tools ──
@@ -467,11 +302,11 @@ const sulcusPlugin = {
         const provenance = res?.provenance || {
           backend: backendMode,
           namespace,
-          server: serverUrl,
-          sync_available: backendMode === "hybrid",
+          server: serverUrl || "local",
+          sync_available: !!serverUrl,
           siu_classified: false,
         };
-        const provenanceStr = `[${provenance.backend}] namespace: ${provenance.namespace || namespace}, server: ${provenance.server || serverUrl}`;
+        const provenanceStr = `[${provenance.backend}] namespace: ${provenance.namespace || namespace}, server: ${provenance.server || "local"}`;
         return {
           content: [{ type: "text", text: `Stored [${params.memory_type || "episodic"}] memory: "${(params.content || "").substring(0, 80)}..." → ${provenanceStr}` }],
           details: { ...res, provenance }
@@ -485,28 +320,35 @@ const sulcusPlugin = {
       description: "Check Sulcus memory backend status: connection, namespace, capabilities, and memory count.",
       parameters: Type.Object({}),
       async execute(_id: string, _params: any) {
-        if (restClient) {
-          try {
-            const status = await restClient.getStatus();
-            return {
-              content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
-              details: status
-            };
-          } catch (e: any) {
-            return {
-              content: [{ type: "text", text: `Memory status unavailable: ${e.message}` }],
-            };
-          }
+        if (!hasBinary) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              status: "unavailable",
+              backend: backendMode,
+              namespace,
+              binary: binaryPath,
+              server: serverUrl || "none (env forwarding only)",
+            }, null, 2) }],
+          };
+        }
+        try {
+          // Ask sulcus-local for status via MCP
+          const status = await memoryCall("memory_status", {});
+          return {
+            content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+            details: status
+          };
+        } catch (e: any) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              status: "error",
+              backend: backendMode,
+              namespace,
+              server: serverUrl || "none (env forwarding only)",
+              error: e.message,
+            }, null, 2) }],
+          };
         }
-        // Fallback: return local config info
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            status: hasBinary ? "local" : "unavailable",
-            backend: backendMode,
-            namespace,
-            server: serverUrl || "none",
-          }, null, 2) }],
-        };
       }
     }, { name: "memory_status" });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalforgestudios/openclaw-sulcus",
-  "version": "1.5.3",
+  "version": "2.0.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",