@pentatonic-ai/ai-agent-sdk 0.4.8 → 0.5.0

package/packages/memory/openclaw-plugin/index.js

@@ -21,6 +21,49 @@
 
 const TES_ENDPOINT = "https://api.pentatonic.com";
 
+// Minimum local memory server version the plugin expects. Bump this when
+// the plugin starts relying on new endpoints, schema, or query params.
+// A server older than this still works for common operations — the
+// mismatch just surfaces as a stderr warning so users know to update.
+const MIN_SERVER_VERSION = "0.5.0";
+
+// Track whether we've already warned for a given server version so we
+// don't spam stderr every health check.
+const warnedServerVersions = new Set();
+
+function parseVersion(v) {
+  if (typeof v !== "string") return null;
+  const parts = v.split(".").slice(0, 3).map((n) => parseInt(n, 10));
+  if (parts.some(Number.isNaN)) return null;
+  while (parts.length < 3) parts.push(0);
+  return parts;
+}
+
+// Returns true when a >= b. Missing or unparseable versions are treated
+// as "newer than anything" to avoid false warnings when a server
+// pre-dates the /health version field.
+function versionGte(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa) return true;
+  if (!pb) return true;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return true;
+    if (pa[i] < pb[i]) return false;
+  }
+  return true;
+}
+
+function warnIfServerTooOld(serverVersion) {
+  if (warnedServerVersions.has(serverVersion)) return;
+  if (versionGte(serverVersion, MIN_SERVER_VERSION)) return;
+  warnedServerVersions.add(serverVersion);
+  console.error(
+    `[pentatonic-memory] WARNING: memory server is ${serverVersion}, plugin needs >= ${MIN_SERVER_VERSION}. ` +
+      `Some features may not work until you update — run: npx @pentatonic-ai/ai-agent-sdk@latest memory`
+  );
+}
+
 const SUCCESS_GIFS = [
   "https://media.giphy.com/media/l0MYt5jPR6QX5APm0/giphy.gif",    // brain expanding
   "https://media.giphy.com/media/3o7btNa0RUYa5E7iiQ/giphy.gif",   // elephant never forgets
@@ -55,12 +98,13 @@ async function localSearch(baseUrl, query, limit = 5, minScore = 0.3) {
       body: JSON.stringify({ query, limit, min_score: minScore }),
       signal: AbortSignal.timeout(5000),
     });
-    if (!res.ok) { stats.backendReachable = false; return []; }
+    if (!res.ok) { stats.backendReachable = false; console.error(`[pentatonic-memory] search HTTP ${res.status}`); return []; }
     stats.backendReachable = true;
     const data = await res.json();
     return data.results || [];
-  } catch {
+  } catch (err) {
     stats.backendReachable = false;
+    console.error(`[pentatonic-memory] search fetch error: ${err.message}`);
     return [];
   }
 }
@@ -71,13 +115,15 @@ async function localStore(baseUrl, content, metadata = {}) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ content, metadata }),
-      signal: AbortSignal.timeout(10000),
+      // Generous timeout — on a Pi, Ollama embed + HyDE generation can take 30-60s per message
+      signal: AbortSignal.timeout(120000),
     });
-    if (!res.ok) { stats.backendReachable = false; return null; }
+    if (!res.ok) { stats.backendReachable = false; console.error(`[pentatonic-memory] store HTTP ${res.status}`); return null; }
     stats.backendReachable = true;
     return res.json();
-  } catch {
+  } catch (err) {
     stats.backendReachable = false;
+    console.error(`[pentatonic-memory] store fetch error: ${err.message}`);
     return null;
   }
 }
@@ -86,7 +132,18 @@ async function localHealth(baseUrl) {
   try {
     const res = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(3000) });
     stats.backendReachable = res.ok;
-    return res.ok;
+    if (!res.ok) return false;
+    // Check for server version mismatch. Warns loudly (but non-fatal)
+    // when the server is older than what this plugin expects — the
+    // common case is a user who updated the plugin but forgot to
+    // re-run `npx @pentatonic-ai/ai-agent-sdk@latest memory`.
+    try {
+      const data = await res.json();
+      if (data?.version) {
+        warnIfServerTooOld(data.version);
+      }
+    } catch { /* health body missing version — older server, no-op */ }
+    return true;
   } catch {
     stats.backendReachable = false;
     return false;
@@ -164,6 +221,108 @@ async function hostedStore(config, content, metadata = {}) {
   }
 }
 
+/**
+ * Emit a CHAT_TURN event to TES so the conversation-analytics dashboard
+ * (Token Universe + Tools tabs) can render. Without this, the dashboard
+ * filters on eventType=CHAT_TURN and shows nothing for OpenClaw users
+ * because the only events emitted are STORE_MEMORY.
+ *
+ * Missing metadata is omitted rather than zeroed — the dashboard
+ * distinguishes "no data" from "zero usage".
+ */
+async function hostedEmitChatTurn(config, sessionId, turn) {
+  const attributes = {
+    source: "openclaw-plugin",
+    user_message: turn.userMessage,
+    assistant_response: turn.assistantResponse,
+  };
+  if (turn.model) attributes.model = turn.model;
+  if (turn.usage) attributes.usage = turn.usage;
+  if (turn.toolCalls?.length) attributes.tool_calls = turn.toolCalls;
+  if (turn.turnNumber !== undefined) attributes.turn_number = turn.turnNumber;
+  if (turn.systemPrompt) attributes.system_prompt = turn.systemPrompt;
+
+  try {
+    const res = await fetch(`${config.tes_endpoint}/api/graphql`, {
+      method: "POST",
+      headers: tesHeaders(config),
+      body: JSON.stringify({
+        query: `mutation Cme($moduleId: String!, $input: ModuleEventInput!) {
+          createModuleEvent(moduleId: $moduleId, input: $input) { success eventId }
+        }`,
+        variables: {
+          moduleId: "conversation-analytics",
+          input: {
+            eventType: "CHAT_TURN",
+            data: { entity_id: sessionId, attributes },
+          },
+        },
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+    if (!res.ok) return null;
+    return res.json();
+  } catch {
+    return null;
+  }
+}
+
+// Pull model/usage/tool_calls from whatever shape the runtime hands us.
+// Different OpenClaw versions wrap provider responses differently — we
+// check the obvious places and silently omit fields we can't find.
+function extractAssistantMetadata(message) {
+  const meta = {};
+  if (message?.model) meta.model = message.model;
+  if (message?.usage) meta.usage = message.usage;
+  if (Array.isArray(message?.tool_calls) && message.tool_calls.length) {
+    meta.toolCalls = message.tool_calls;
+  } else if (Array.isArray(message?.toolCalls) && message.toolCalls.length) {
+    meta.toolCalls = message.toolCalls;
+  }
+  const raw = message?.raw || message?.response || message?._raw;
+  if (raw && typeof raw === "object") {
+    if (!meta.model && raw.model) meta.model = raw.model;
+    if (!meta.usage && raw.usage) meta.usage = raw.usage;
+    if (!meta.toolCalls) {
+      if (Array.isArray(raw.content)) {
+        const tc = raw.content
+          .filter((b) => b?.type === "tool_use")
+          .map((b) => ({ tool: b.name, args: b.input || {} }));
+        if (tc.length) meta.toolCalls = tc;
+      }
+      if (!meta.toolCalls && Array.isArray(raw.choices) && raw.choices[0]?.message?.tool_calls) {
+        meta.toolCalls = raw.choices[0].message.tool_calls.map((tc) => ({
+          tool: tc.function?.name || tc.name,
+          args: tc.function?.arguments,
+        }));
+      }
+    }
+  }
+  return meta;
+}
+
+// Per-session turn buffer for CHAT_TURN emission. User message waits
+// for the next assistant message in the same session, then emits as
+// a paired turn. Capped to avoid unbounded growth.
+const MAX_SESSIONS = 500;
+const turnBuffers = new Map();
+const turnCounters = new Map();
+
+function capSessionMaps() {
+  while (turnBuffers.size > MAX_SESSIONS) {
+    turnBuffers.delete(turnBuffers.keys().next().value);
+  }
+  while (turnCounters.size > MAX_SESSIONS) {
+    turnCounters.delete(turnCounters.keys().next().value);
+  }
+}
+
+/** Test helper — clear turn buffers and counters between tests. */
+export function _resetTurnBuffersForTest() {
+  turnBuffers.clear();
+  turnCounters.clear();
+}
+
 // --- TES account setup via HTTP ---
 
 async function tesLogin(email, password, clientId) {
@@ -264,12 +423,12 @@ export default {
   kind: "context-engine",
 
   register(api) {
-    const config = api.config || {};
+    const config = api.pluginConfig || api.config?.plugins?.entries?.["pentatonic-memory"]?.config || api.config || {};
     const hosted = !!(config.tes_endpoint && config.tes_api_key);
     const baseUrl = config.memory_url || "http://localhost:3333";
     const searchLimit = config.search_limit || 5;
     const minScore = config.min_score || 0.3;
-    const log = (msg) => process.stderr.write(`[pentatonic-memory] ${msg}\n`);
+    const log = (msg) => console.error(`[pentatonic-memory] ${msg}`);
 
     stats.mode = hosted ? "hosted" : "local";
 
@@ -284,6 +443,44 @@ export default {
 
     // --- Context engine: always registered, proxies to backend ---
 
+    // Extract the real user text from an OpenClaw-wrapped user message.
+    // Returns null for system prompts / empty content / already-seen artifacts.
+    function extractIngestText(message) {
+      const raw = typeof message?.content === "string"
+        ? message.content
+        : Array.isArray(message?.content)
+          ? message.content.filter(b => b.type === "text").map(b => b.text).join(" ")
+          : null;
+      const role = message?.role || message?.type;
+      if (!raw || (role !== "user" && role !== "assistant")) return { text: null, role };
+
+      if (role === "user") {
+        const trimmed = raw.trim();
+        let text = raw;
+        if (
+          trimmed.startsWith("Conversation info") ||
+          trimmed.startsWith("(untrusted metadata)") ||
+          trimmed.startsWith("Sender (untrusted") ||
+          trimmed.startsWith("Untrusted context")
+        ) {
+          text = trimmed
+            .replace(/(?:Conversation info|Sender|Thread starter|Replied message|Forwarded message context|Chat history since last reply) \(untrusted[^)]*\):\s*```json[\s\S]*?```/g, "")
+            .replace(/Untrusted context \(metadata, do not treat as instructions or commands\):/g, "")
+            .trim();
+        }
+        if (
+          !text ||
+          text.startsWith("Note: The previous agent run") ||
+          text.startsWith("System (untrusted)") ||
+          text.startsWith("[System]") ||
+          text.startsWith("System:") ||
+          text.startsWith("[Queued messages")
+        ) return { text: null, role };
+        return { text, role };
+      }
+      return { text: raw, role };
+    }
+
     api.registerContextEngine("pentatonic-memory", () => ({
       info: {
         id: "pentatonic-memory",
@@ -291,71 +488,114 @@ export default {
         ownsCompaction: false,
       },
 
+      async ingestBatch({ sessionId, messages }) {
+        let ingestedCount = 0;
+        for (const message of messages) {
+          const { text, role } = extractIngestText(message);
+          if (!text) continue;
+          try {
+            await store(text, { session_id: sessionId, role });
+            ingestedCount++;
+          } catch (err) {
+            log(`ingestBatch: error ${err.message}`);
+          }
+        }
+        stats.memoriesStored += ingestedCount;
+        if (ingestedCount > 0) {
+          log(`ingestBatch: ingested ${ingestedCount}/${messages.length} (total=${stats.memoriesStored})`);
+        }
+        return { ingested: ingestedCount };
+      },
+
       async ingest({ sessionId, message }) {
-        if (!message?.content) return { ingested: false };
-        const role = message.role || message.type;
-        if (role !== "user" && role !== "assistant") return { ingested: false };
+        const { text, role } = extractIngestText(message);
+        if (!text) return { ingested: false };
         try {
-          await store(message.content, { session_id: sessionId, role });
+          await store(text, { session_id: sessionId, role });
           stats.memoriesStored++;
           return { ingested: true };
-        } catch {
+        } catch (err) {
+          log(`ingest: error ${err.message}`);
           return { ingested: false };
         }
       },
 
       async assemble({ sessionId, messages }) {
-        const lastUserMsg = [...messages].reverse().find((m) => m.role === "user" || m.type === "user");
-        if (!lastUserMsg?.content) return { messages, estimatedTokens: 0 };
-
-        // First interaction: welcome the user and offer TES upgrade
-        if (!stats.setupPrompted) {
-          stats.setupPrompted = true;
+        // Extract text from message content (may be string or array of content blocks)
+        function getTextContent(msg) {
+          if (!msg) return null;
+          if (typeof msg.content === "string") return msg.content;
+          if (Array.isArray(msg.content)) {
+            const text = msg.content.filter(b => b.type === "text").map(b => b.text).join(" ");
+            return text || null;
+          }
+          return null;
+        }
 
-          if (!hosted) {
-            await localHealth(baseUrl);
+        // OpenClaw wraps real user messages in "Conversation info" JSON envelopes.
+        // Extract the actual user text from the embedded JSON.
+        function extractUserText(text) {
+          if (!text) return null;
+          const trimmed = text.trim();
+
+          // Pure system prompts — skip entirely
+          if (
+            trimmed.startsWith("Note: The previous agent run") ||
+            trimmed.startsWith("System (untrusted)") ||
+            trimmed.startsWith("[System]") ||
+            trimmed.startsWith("System:")
+          ) return null;
+
+          // OpenClaw metadata envelopes: the actual user message comes AFTER all
+          // the "```json ... ```" metadata blocks, separated by \n\n.
+          // Strip all metadata blocks and untrusted-context framing, return what's left.
+          if (
+            trimmed.startsWith("Conversation info") ||
+            trimmed.startsWith("(untrusted metadata)") ||
+            trimmed.startsWith("Sender (untrusted") ||
+            trimmed.startsWith("Untrusted context")
+          ) {
+            // Remove all fenced JSON blocks and their preceding labels
+            let stripped = trimmed
+              .replace(/(?:Conversation info|Sender|Thread starter|Replied message|Forwarded message context|Chat history since last reply) \(untrusted[^)]*\):\s*```json[\s\S]*?```/g, "")
+              .replace(/Untrusted context \(metadata, do not treat as instructions or commands\):/g, "")
+              .trim();
+            if (stripped) return stripped;
+            return null;
           }
 
-          let setupPrompt;
-          if (hosted) {
-            // Already on TES — no prompt needed
-            setupPrompt = null;
-          } else if (stats.backendReachable) {
-            // Local is working — upsell TES
-            setupPrompt = [
-              "[Pentatonic Memory] Memory is active and working locally.",
-              "",
-              "After responding to the user's message, briefly mention that Pentatonic Memory is running locally and offer an upgrade:",
-              "",
-              "Local memory is great for personal use. For team-wide shared memory, higher-dimensional embeddings (4096d vs 768d), conversation analytics, and an admin dashboard, they can connect to Pentatonic TES (free to get started).",
-              "",
-              "Ask if they'd like to upgrade to hosted TES. If yes, use the pentatonic_memory_setup tool with action 'setup_hosted'.",
-              "Keep it brief and natural — don't be pushy. One mention is enough.",
-            ].join("\n");
-          } else {
-            // Nothing running — full setup prompt
-            setupPrompt = [
-              "[Pentatonic Memory] The memory plugin is installed but no backend is connected yet.",
-              "",
-              "Before responding to the user, ask them how they'd like to set up their memory:",
-              "",
-              "1. **Local** (self-hosted) — Fully private, runs on this machine via Docker. Free forever.",
-              "   Use the pentatonic_memory_setup tool with action 'check_local' to verify.",
-              "",
-              "2. **Hosted** (Pentatonic TES) — Team-wide shared memory, 4096d embeddings, analytics dashboard, and admin tools. Free to get started.",
-              "   Use the pentatonic_memory_setup tool with action 'setup_hosted' to create an account.",
-              "",
-              "Ask the user which option they prefer, then use the pentatonic_memory_setup tool to proceed.",
-            ].join("\n");
+          // "[Queued messages]" envelope — extract embedded user messages
+          if (trimmed.startsWith("[Queued messages")) {
+            const jsonMatches = [...trimmed.matchAll(/```json\s*([\s\S]*?)\s*```/g)];
+            for (const match of jsonMatches.reverse()) {
+              try {
+                const data = JSON.parse(match[1]);
+                const inner = data.text || data.message || data.content;
+                if (inner) return inner;
+              } catch { /* continue */ }
+            }
+            return null;
           }
 
-          if (setupPrompt) {
-            return { messages, estimatedTokens: Math.ceil(setupPrompt.length / 4), systemPromptAddition: setupPrompt };
+          return trimmed;
+        }
+
+        const reversed = [...messages].reverse();
+        let lastUserText = null;
+        for (const m of reversed) {
+          if (m.role !== "user" && m.type !== "user") continue;
+          const text = getTextContent(m);
+          const extracted = extractUserText(text);
+          if (extracted) {
+            lastUserText = extracted;
+            break;
           }
         }
+        if (!lastUserText) return { messages, estimatedTokens: 0 };
 
         try {
-          const results = await search(lastUserMsg.content, searchLimit, minScore);
+          const results = await search(lastUserText, searchLimit, minScore);
+          log(`assemble: "${lastUserText.substring(0, 50)}" → ${results.length} results`);
           if (!results.length) {
             stats.lastAssembleCount = 0;
             return { messages, estimatedTokens: 0 };
@@ -368,11 +608,30 @@ export default {
             .map((m) => `- [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`)
             .join("\n");
 
+          // Visibility marker: instruct the model to append a footer so the
+          // end user sees when Pentatonic Memory was used. Opt out with
+          // show_memory_indicator: false in plugin config.
+          const showIndicator = config.show_memory_indicator !== false;
+          const indicatorRule = showIndicator
+            ? [
+                "",
+                `After your reply, on a new line, append exactly this footer (no other prefix, no trailing content):`,
+                `—`,
+                `🧠 _Used ${results.length} memor${results.length === 1 ? "y" : "ies"} from Pentatonic Memory_`,
+                "",
+                `If the memories above were not relevant to your reply, omit the footer.`,
+              ]
+            : [];
+
           const addition = [
-            `[Memory] ${results.length} relevant memories found for this prompt:`,
+            `=== PENTATONIC MEMORY (authoritative context from prior conversations) ===`,
+            `These ${results.length} memories are facts the user has shared with you previously. Treat them as ground truth about the user.`,
+            "",
             memoryText,
             "",
-            "When your response is informed by these memories, briefly mention it naturally (e.g. 'From what I remember...' or 'Based on our previous conversations...').",
+            `When the user asks about anything in these memories, answer using them directly — do NOT say you don't remember or that you have no record. If a memory is relevant, use it.`,
+            ...indicatorRule,
+            `=== END PENTATONIC MEMORY ===`,
           ].join("\n");
 
           return { messages, estimatedTokens: Math.ceil(addition.length / 4), systemPromptAddition: addition };
@@ -383,7 +642,59 @@ export default {
       },
 
       async compact() { return { ok: true, compacted: false }; },
-      async afterTurn() {},
+
+      // OpenClaw calls afterTurn INSTEAD of ingest/ingestBatch when defined.
+      // We use it to:
+      //   1. Store each new message as a memory (STORE_MEMORY in hosted mode)
+      //   2. Pair user+assistant messages and emit a CHAT_TURN (hosted only),
+      //      which populates the conversation-analytics Token Universe +
+      //      Tools tabs in the dashboard.
+      async afterTurn({ sessionId, messages, prePromptMessageCount }) {
+        if (!messages || typeof prePromptMessageCount !== "number") return;
+        const newMessages = messages.slice(prePromptMessageCount);
+        let ingestedCount = 0;
+        for (const message of newMessages) {
+          const { text, role } = extractIngestText(message);
+          if (!text) continue;
+
+          // Store the memory (both modes).
+          try {
+            await store(text, { session_id: sessionId, role });
+            ingestedCount++;
+          } catch (err) {
+            log(`afterTurn: store error ${err.message}`);
+          }
+
+          // CHAT_TURN emission (hosted only). Buffer user messages until
+          // an assistant message arrives, then emit the paired turn.
+          if (!hosted) continue;
+          try {
+            if (role === "user") {
+              turnBuffers.set(sessionId, { userMessage: text });
+              capSessionMaps();
+            } else if (role === "assistant") {
+              const buf = turnBuffers.get(sessionId);
+              const turnNumber = (turnCounters.get(sessionId) || 0) + 1;
+              turnCounters.set(sessionId, turnNumber);
+              capSessionMaps();
+              const meta = extractAssistantMetadata(message);
+              await hostedEmitChatTurn(config, sessionId, {
+                userMessage: buf?.userMessage,
+                assistantResponse: text,
+                turnNumber,
+                ...meta,
+              });
+              turnBuffers.delete(sessionId);
+            }
+          } catch (err) {
+            log(`afterTurn: CHAT_TURN emit error ${err.message}`);
+          }
+        }
+        stats.memoriesStored += ingestedCount;
+        if (ingestedCount > 0) {
+          log(`afterTurn: ingested ${ingestedCount}/${newMessages.length} (total=${stats.memoriesStored})`);
+        }
+      },
     }));
 
     // --- Tools ---

package/packages/memory/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "pentatonic-memory",
   "name": "Pentatonic Memory",
   "description": "Persistent, searchable memory with multi-signal retrieval and HyDE query expansion. Local (Docker + Ollama) or hosted (Pentatonic TES).",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "kind": "context-engine",
   "configSchema": {
     "type": "object",
@@ -14,6 +14,11 @@
         "default": "local",
         "description": "Local (Docker + Ollama) or hosted (Pentatonic TES)"
       },
+      "memory_url": {
+        "type": "string",
+        "default": "http://localhost:3333",
+        "description": "Memory server HTTP URL (local mode, default: http://localhost:3333)"
+      },
       "database_url": {
         "type": "string",
         "description": "PostgreSQL connection string (local mode)"
@@ -60,6 +65,11 @@
         "type": "number",
         "default": 0.3,
         "description": "Minimum relevance threshold"
+      },
+      "show_memory_indicator": {
+        "type": "boolean",
+        "default": true,
+        "description": "Tell the LLM to append a footer to replies informed by memory, so the user sees when Pentatonic Memory was used"
       }
     }
   },

package/packages/memory/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/openclaw-memory-plugin",
-  "version": "0.5.3",
+  "version": "0.8.0",
   "description": "Pentatonic Memory plugin for OpenClaw — persistent, searchable memory with multi-signal retrieval and HyDE query expansion",
   "type": "module",
   "main": "index.js",