@pentatonic-ai/ai-agent-sdk 0.5.6 → 0.5.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.5.6",
-  "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
+  "version": "0.5.7",
+  "description": "TES SDK \u2014 LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -13,7 +13,8 @@
     "./memory": "./packages/memory/src/index.js",
     "./memory/server": "./packages/memory/src/server.js",
     "./memory/openclaw": "./packages/memory/src/openclaw/index.js",
-    "./doctor": "./packages/doctor/src/index.js"
+    "./doctor": "./packages/doctor/src/index.js",
+    "./memory/hosted": "./packages/memory/src/hosted.js"
   },
   "bin": {
     "ai-agent-sdk": "./bin/cli.js"
@@ -54,7 +55,9 @@
     "model-context-protocol"
   ],
   "openclaw": {
-    "extensions": ["./packages/memory/src/openclaw/index.js"],
+    "extensions": [
+      "./packages/memory/src/openclaw/index.js"
+    ],
     "hooks": {}
   },
   "license": "MIT",

package/packages/memory/openclaw-plugin/__tests__/sanitizer.test.js

@@ -0,0 +1,135 @@
+/**
+ * OpenClaw plugin — memory-content sanitization tests.
+ *
+ * Verifies the sanitizer is actually applied at the two format
+ * surfaces: the context-engine `assemble` output and the
+ * `pentatonic_memory_search` tool result.
+ */
+
+import plugin from "../index.js";
+
+const realFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+function mockSearchReturns(results) {
+  globalThis.fetch = async (_url, init) => {
+    const body = init?.body ? JSON.parse(init.body) : null;
+    const query = body?.query || "";
+    if (query.includes("semanticSearchMemories")) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ data: { semanticSearchMemories: results } }),
+      };
+    }
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ data: {} }),
+    };
+  };
+}
+
+function makeEngine(extraConfig = {}) {
+  let factory;
+  plugin.register({
+    pluginConfig: {
+      tes_endpoint: "https://x.test",
+      tes_client_id: "c",
+      tes_api_key: "tes_c_xyz",
+      ...extraConfig,
+    },
+    registerTool: () => {},
+    registerContextEngine: (_name, fn) => {
+      factory = fn;
+    },
+  });
+  if (!factory) throw new Error("no engine registered");
+  return factory();
+}
+
+describe("openclaw-plugin — assemble applies memory sanitizer", () => {
+  it("strips TES dashboard noise before injecting into systemPromptAddition", async () => {
+    const noisy = [
+      "[2026-04-21T11:47:04.826Z] I have a subaru and hyundai.",
+      "anonymous",
+      "ml_phil-h-claude_episodic",
+      "100% match",
+      "Confidence: 100%",
+      "Accessed: 2x",
+      "<1h ago",
+      "Decay: 0.05",
+    ].join("\n");
+    mockSearchReturns([{ id: "m1", content: noisy, similarity: 0.9 }]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "what car do I drive?" }],
+    });
+
+    const addition = result.systemPromptAddition || "";
+    expect(addition).toMatch(/I have a subaru and hyundai/);
+    expect(addition).not.toMatch(/ml_phil-h-claude_episodic/);
+    expect(addition).not.toMatch(/Confidence:/);
+    expect(addition).not.toMatch(/Accessed: 2x/);
+    expect(addition).not.toMatch(/Decay:/);
+    expect(addition).not.toMatch(/\[2026-04-21T/);
+  });
+
+  it("strips trailing JSON metadata blobs", async () => {
+    const content = [
+      "User said: I drive a Subaru.",
+      "{",
+      '  "event_id": "abc",',
+      '  "event_type": "CHAT_TURN"',
+      "}",
+    ].join("\n");
+    mockSearchReturns([{ id: "m1", content, similarity: 0.9 }]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "q" }],
+    });
+
+    expect(result.systemPromptAddition).toMatch(/User said: I drive a Subaru\./);
+    expect(result.systemPromptAddition).not.toMatch(/event_id/);
+    expect(result.systemPromptAddition).not.toMatch(/entity_type/);
+  });
+
+  it("caps verbose memories so a single transcript dump can't dominate", async () => {
+    // 2400-char "memory" — well over the 600-char cap
+    const long = "Phil owns a Subaru. ".repeat(120);
+    mockSearchReturns([{ id: "m1", content: long, similarity: 0.9 }]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "q" }],
+    });
+
+    const addition = result.systemPromptAddition || "";
+    // Full content would be ~2400 chars; capped version ~600 + …
+    expect(addition).toMatch(/Phil owns a Subaru\./);
+    expect(addition).toMatch(/…/);
+  });
+
+  it("keeps clean content unchanged", async () => {
+    mockSearchReturns([
+      { id: "m1", content: "Phil drinks cortado.", similarity: 0.9 },
+    ]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "q" }],
+    });
+
+    expect(result.systemPromptAddition).toMatch(/Phil drinks cortado\./);
+    expect(result.systemPromptAddition).not.toMatch(/…/); // no truncation
+  });
+});

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

@@ -434,10 +434,61 @@ async function tesGetApiKey(accessToken, clientId) {
 
 // --- Format helpers ---
 
+// Strip TES dashboard/metadata noise from a stored memory's content
+// before we show it to the model. Same shape as the Claude Code hook's
+// sanitizer in `hooks/scripts/shared.js` — duplicated inline here to
+// keep the published openclaw-plugin package fully standalone. Update
+// both if you change this.
+const TES_META_FIELDS =
+  "event_id|event_type|entity_type|source|clientId|correlationId|timestamp|session_id|layer_id|confidence|decay_rate|user_id";
+const MEMORY_MAX_LEN = 600;
+
+function sanitizeMemoryContent(content) {
+  if (typeof content !== "string") return content;
+  let out = content;
+  // Trailing JSON metadata blob (no `m` flag — `$` = end-of-string).
+  out = out.replace(/\n\{\s*\n[\s\S]*?\n\s*\}\s*$/, "");
+  // Inline JSON metadata blobs (2+ consecutive TES metadata fields).
+  out = out.replace(
+    new RegExp(
+      `\\{\\s*\\n(\\s*"(?:${TES_META_FIELDS})"[^\\n]*\\n){2,}\\s*\\}`,
+      "g"
+    ),
+    ""
+  );
+  // Dashboard-UI standalone lines.
+  const linePatterns = [
+    /^\s*anonymous\s*$/gm,
+    /^\s*ml_[a-z0-9_-]+_(episodic|semantic|procedural|working)\s*$/gm,
+    /^\s*\d+%\s*match\s*$/gm,
+    /^\s*Confidence:\s*\d+%\s*$/gm,
+    /^\s*Accessed:\s*\d+x?\s*$/gm,
+    /^\s*<?\s*\d+[smhd]\s*ago\s*$/gm,
+    /^\s*Decay:\s*[\d.]+\s*$/gm,
+    /^\s*Metadata\s*$/gm,
+  ];
+  for (const pat of linePatterns) out = out.replace(pat, "");
+  // Leading ISO timestamps — strip prefix, keep line content.
+  out = out.replace(/^\s*\[\d{4}-\d{2}-\d{2}T[\d:.]+Z\]\s*/gm, "");
+  // Collapse consecutive blank lines.
+  out = out.replace(/\n\s*\n\s*\n+/g, "\n\n").trim();
+  // Cap verbose transcript dumps.
+  if (out.length > MEMORY_MAX_LEN) {
+    out = out.slice(0, MEMORY_MAX_LEN).trimEnd() + "…";
+  }
+  // Fallback to original if we stripped everything.
+  const wordCount = (out.match(/\b\w{2,}\b/g) || []).length;
+  if (wordCount < 2) return content;
+  return out;
+}
+
 function formatResults(results) {
   if (!results.length) return "No relevant memories found.";
   return results
-    .map((m, i) => `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`)
+    .map(
+      (m, i) =>
+        `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
+    )
     .join("\n\n");
 }
 
@@ -644,7 +695,10 @@ export default {
           stats.lastAssembleCount = results.length;
 
           const memoryText = results
-            .map((m) => `- [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`)
+            .map(
+              (m) =>
+                `- [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
+            )
             .join("\n");
 
           // Visibility marker: instruct the model to append a footer so the

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.5.2",
+  "version": "0.5.3",
   "kind": "context-engine",
   "configSchema": {
     "type": "object",

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

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/openclaw-memory-plugin",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Pentatonic Memory plugin for OpenClaw — persistent, searchable memory with multi-signal retrieval and HyDE query expansion",
   "type": "module",
   "main": "index.js",
@@ -24,7 +24,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Pentatonic-Ltd/ai-agent-sdk.git",
+    "url": "git+https://github.com/Pentatonic-Ltd/ai-agent-sdk.git",
     "directory": "packages/memory/openclaw-plugin"
   },
   "keywords": ["openclaw", "plugin", "memory", "context-engine", "pentatonic", "tes"]

package/packages/memory/src/__tests__/hosted.test.js

@@ -0,0 +1,253 @@
+/**
+ * Tests for the hosted-mode helpers (semanticSearchMemories +
+ * createModuleEvent over HTTPS with a tes_* bearer).
+ *
+ * Stub global fetch and assert request/response shape — the helpers
+ * have no other side effects, so this is sufficient.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import {
+  hostedSearch,
+  hostedEmitChatTurn,
+  hostedStoreMemory,
+  buildHostedHeaders,
+} from "../hosted.js";
+
+const CONFIG = {
+  endpoint: "https://acme.api.example.com",
+  clientId: "acme",
+  apiKey: "tes_acme_xxxxxxxxxxxxxxxx",
+};
+
+const SVC_CONFIG = {
+  endpoint: "https://acme.api.example.com",
+  clientId: "acme",
+  apiKey: "internal-service-key",
+};
+
+let originalFetch;
+let lastCall;
+
+function stubFetch(handler) {
+  originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url, init) => {
+    lastCall = {
+      url: url.toString(),
+      headers: init?.headers || {},
+      body: init?.body ? JSON.parse(init.body) : null,
+    };
+    return handler(lastCall);
+  };
+}
+
+afterEach(() => {
+  if (originalFetch) globalThis.fetch = originalFetch;
+  originalFetch = null;
+  lastCall = null;
+});
+
+// =============================================================================
+// buildHostedHeaders
+// =============================================================================
+
+describe("buildHostedHeaders", () => {
+  it("uses Bearer auth for tes_* keys", () => {
+    const headers = buildHostedHeaders(CONFIG);
+    expect(headers["Authorization"]).toBe(`Bearer ${CONFIG.apiKey}`);
+    expect(headers["x-client-id"]).toBe(CONFIG.clientId);
+    expect(headers["x-service-key"]).toBeUndefined();
+  });
+
+  it("uses x-service-key for non-tes_ keys", () => {
+    const headers = buildHostedHeaders(SVC_CONFIG);
+    expect(headers["x-service-key"]).toBe(SVC_CONFIG.apiKey);
+    expect(headers["Authorization"]).toBeUndefined();
+  });
+
+  it("accepts legacy tes_endpoint/tes_client_id/tes_api_key keys", () => {
+    const legacy = {
+      tes_endpoint: CONFIG.endpoint,
+      tes_client_id: CONFIG.clientId,
+      tes_api_key: CONFIG.apiKey,
+    };
+    const headers = buildHostedHeaders(legacy);
+    expect(headers["Authorization"]).toBe(`Bearer ${CONFIG.apiKey}`);
+  });
+
+  it("throws on incomplete config", () => {
+    expect(() => buildHostedHeaders({})).toThrow(/requires/);
+  });
+});
+
+// =============================================================================
+// hostedSearch
+// =============================================================================
+
+describe("hostedSearch", () => {
+  it("returns memories on a successful query", async () => {
+    stubFetch(() =>
+      new Response(
+        JSON.stringify({
+          data: {
+            semanticSearchMemories: [
+              { id: "m1", content: "User likes blue", similarity: 0.83 },
+            ],
+          },
+        }),
+        { status: 200 }
+      )
+    );
+
+    const out = await hostedSearch(CONFIG, "what colour", { limit: 4 });
+    expect(out.memories).toHaveLength(1);
+    expect(out.skipped).toBeUndefined();
+    expect(lastCall.body.variables.clientId).toBe("acme");
+    expect(lastCall.body.variables.limit).toBe(4);
+    expect(lastCall.headers["Authorization"]).toBe(`Bearer ${CONFIG.apiKey}`);
+  });
+
+  it("returns { memories: [], skipped: 'no_query' } when query is empty", async () => {
+    stubFetch(() => new Response("{}", { status: 200 }));
+    const out = await hostedSearch(CONFIG, "");
+    expect(out.skipped).toBe("no_query");
+  });
+
+  it("skips with tes_http_500 on 500 responses", async () => {
+    stubFetch(() => new Response("oops", { status: 500 }));
+    const out = await hostedSearch(CONFIG, "q");
+    expect(out.skipped).toBe("tes_http_500");
+    expect(out.memories).toEqual([]);
+  });
+
+  it("skips with tes_graphql:<reason> on graphql errors", async () => {
+    stubFetch(() =>
+      new Response(
+        JSON.stringify({
+          errors: [{ message: 'Module "deep-memory" is not enabled' }],
+        }),
+        { status: 200 }
+      )
+    );
+    const out = await hostedSearch(CONFIG, "q");
+    expect(out.skipped).toMatch(/^tes_graphql:/);
+  });
+
+  it("skips with tes_timeout on AbortError", async () => {
+    stubFetch(() => {
+      const err = new Error("aborted");
+      err.name = "AbortError";
+      throw err;
+    });
+    const out = await hostedSearch(CONFIG, "q", { timeoutMs: 5 });
+    expect(out.skipped).toBe("tes_timeout");
+  });
+
+  it("skips with tes_unreachable on generic fetch failure", async () => {
+    stubFetch(() => {
+      throw new Error("ECONNREFUSED");
+    });
+    const out = await hostedSearch(CONFIG, "q");
+    expect(out.skipped).toBe("tes_unreachable");
+  });
+});
+
+// =============================================================================
+// hostedEmitChatTurn
+// =============================================================================
+
+describe("hostedEmitChatTurn", () => {
+  it("emits createModuleEvent with conversation-analytics moduleId", async () => {
+    stubFetch(() =>
+      new Response(
+        JSON.stringify({
+          data: { createModuleEvent: { success: true, eventId: "evt_1" } },
+        }),
+        { status: 200 }
+      )
+    );
+
+    const out = await hostedEmitChatTurn(
+      CONFIG,
+      {
+        userMessage: "hi",
+        assistantResponse: "hello!",
+        model: "gpt-4o",
+        sessionId: "sess_1",
+      },
+      { source: "my-app" }
+    );
+
+    expect(out.ok).toBe(true);
+    expect(out.eventId).toBe("evt_1");
+    expect(lastCall.body.variables.moduleId).toBe("conversation-analytics");
+    expect(lastCall.body.variables.input.eventType).toBe("CHAT_TURN");
+    expect(lastCall.body.variables.input.data.attributes.source).toBe("my-app");
+    expect(lastCall.body.variables.input.data.attributes.user_message).toBe(
+      "hi"
+    );
+    expect(lastCall.body.variables.input.data.entity_id).toBe("sess_1");
+  });
+
+  it("skips empty turns (no user + no assistant text)", async () => {
+    stubFetch(() => new Response("{}", { status: 200 }));
+    const out = await hostedEmitChatTurn(CONFIG, {});
+    expect(out.skipped).toBe("empty_turn");
+  });
+
+  it("merges payload.extra into attributes", async () => {
+    stubFetch(() =>
+      new Response(
+        JSON.stringify({
+          data: { createModuleEvent: { success: true, eventId: "x" } },
+        }),
+        { status: 200 }
+      )
+    );
+    await hostedEmitChatTurn(CONFIG, {
+      userMessage: "u",
+      assistantResponse: "a",
+      extra: { tes_skipped_reason: "passthrough_mode", custom_flag: 1 },
+    });
+    const attrs = lastCall.body.variables.input.data.attributes;
+    expect(attrs.tes_skipped_reason).toBe("passthrough_mode");
+    expect(attrs.custom_flag).toBe(1);
+  });
+});
+
+// =============================================================================
+// hostedStoreMemory
+// =============================================================================
+
+describe("hostedStoreMemory", () => {
+  it("emits STORE_MEMORY against deep-memory", async () => {
+    stubFetch(() =>
+      new Response(
+        JSON.stringify({
+          data: { createModuleEvent: { success: true, eventId: "stored" } },
+        }),
+        { status: 200 }
+      )
+    );
+    const out = await hostedStoreMemory(
+      CONFIG,
+      "User owns a Subaru",
+      { session_id: "abc" },
+      { source: "my-app" }
+    );
+    expect(out.ok).toBe(true);
+    expect(lastCall.body.variables.moduleId).toBe("deep-memory");
+    expect(lastCall.body.variables.input.eventType).toBe("STORE_MEMORY");
+    expect(lastCall.body.variables.input.data.attributes.content).toBe(
+      "User owns a Subaru"
+    );
+    expect(lastCall.body.variables.input.data.attributes.source).toBe("my-app");
+    expect(lastCall.body.variables.input.data.entity_id).toBe("abc");
+  });
+
+  it("skips with no_content if content is empty", async () => {
+    stubFetch(() => new Response("{}", { status: 200 }));
+    const out = await hostedStoreMemory(CONFIG, "");
+    expect(out.skipped).toBe("no_content");
+  });
+});

package/packages/memory/src/__tests__/sanitize.test.js

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for the shared memory-content sanitizer.
+ *
+ * Same invariants the Claude Code hook tests already cover — we
+ * assert them here against the canonical module too so the published
+ * openclaw-plugin's inline copy and the hooks/scripts inline copy
+ * both have a reference to check against.
+ */
+
+import {
+  sanitizeMemoryContent,
+  MEMORY_MAX_LEN,
+} from "../sanitize.js";
+
+describe("sanitizeMemoryContent", () => {
+  it("strips leading ISO timestamps on each line", () => {
+    const out = sanitizeMemoryContent(
+      "[2026-04-21T11:47:04.826Z] Phil owns a Subaru."
+    );
+    expect(out).toBe("Phil owns a Subaru.");
+  });
+
+  it("strips standalone dashboard metadata lines", () => {
+    const input = [
+      "Phil owns a Subaru.",
+      "anonymous",
+      "ml_phil-h-claude_episodic",
+      "100% match",
+      "Confidence: 100%",
+      "Accessed: 2x",
+      "<1h ago",
+      "Decay: 0.05",
+      "Metadata",
+    ].join("\n");
+    expect(sanitizeMemoryContent(input)).toBe("Phil owns a Subaru.");
+  });
+
+  it("strips trailing JSON metadata blob", () => {
+    const input = [
+      "Phil has two dogs named Max and Luna.",
+      "{",
+      '  "event_id": "abc-123",',
+      '  "event_type": "CHAT_TURN"',
+      "}",
+    ].join("\n");
+    expect(sanitizeMemoryContent(input)).toBe(
+      "Phil has two dogs named Max and Luna."
+    );
+  });
+
+  it("strips inline JSON metadata blobs with TES-style fields", () => {
+    const input = [
+      "User said: I have a Subaru.",
+      "{",
+      '  "event_id": "abc",',
+      '  "event_type": "CHAT_TURN",',
+      '  "entity_type": "conversation"',
+      "}",
+      "The next turn continued...",
+    ].join("\n");
+    const out = sanitizeMemoryContent(input);
+    expect(out).toMatch(/User said: I have a Subaru\./);
+    expect(out).toMatch(/The next turn continued\.\.\./);
+    expect(out).not.toMatch(/event_id/);
+  });
+
+  it("does NOT strip legitimate JSON code samples", () => {
+    const input = [
+      "Here's how to configure the client:",
+      "{",
+      '  "apiKey": "xxx",',
+      '  "endpoint": "https://api.test"',
+      "}",
+      "Then instantiate it.",
+    ].join("\n");
+    const out = sanitizeMemoryContent(input);
+    expect(out).toMatch(/apiKey/);
+    expect(out).toMatch(/endpoint/);
+  });
+
+  it("falls back to original when stripping would leave almost nothing", () => {
+    const input = "anonymous\nml_phil-h-claude_episodic\n100% match";
+    expect(sanitizeMemoryContent(input)).toBe(input);
+  });
+
+  it("is a no-op for clean content", () => {
+    const clean = "Phil prefers espresso in the morning, tea in the afternoon.";
+    expect(sanitizeMemoryContent(clean)).toBe(clean);
+  });
+
+  it("caps verbose content at MEMORY_MAX_LEN with ellipsis", () => {
+    const long = "fact. ".repeat(200); // 1200 chars
+    const out = sanitizeMemoryContent(long);
+    expect(out.length).toBeLessThanOrEqual(MEMORY_MAX_LEN + 1);
+    expect(out.endsWith("…")).toBe(true);
+  });
+
+  it("handles non-string input safely", () => {
+    expect(sanitizeMemoryContent(undefined)).toBeUndefined();
+    expect(sanitizeMemoryContent(null)).toBeNull();
+    expect(sanitizeMemoryContent(42)).toBe(42);
+  });
+});

package/packages/memory/src/hosted.js

@@ -0,0 +1,372 @@
+/**
+ * Hosted-mode helpers for the Pentatonic memory system.
+ *
+ * These talk to a remote TES tenant over HTTPS using GraphQL, with a
+ * `tes_<clientId>_<rand>` bearer token in the Authorization header.
+ * They are deliberately thin wrappers around the GraphQL surface so
+ * any caller (the OpenClaw plugin, the LLM proxy worker, a custom
+ * integration) gets the same wire shape, the same error handling, and
+ * the same operational patterns.
+ *
+ * No `pg`, no Node-only APIs — Workers-compatible. Pure `fetch`.
+ *
+ * @example
+ *   import { hostedSearch, hostedEmitChatTurn } from
+ *     "@pentatonic-ai/ai-agent-sdk/memory/hosted";
+ *
+ *   const config = {
+ *     endpoint: "https://acme.api.pentatonic.com",
+ *     clientId: "acme",
+ *     apiKey:   "tes_acme_xxxxx",
+ *   };
+ *
+ *   const { memories } = await hostedSearch(config, "What's my name?", {
+ *     limit: 6, minScore: 0.55, timeoutMs: 800,
+ *   });
+ *
+ *   await hostedEmitChatTurn(config, {
+ *     userMessage:       "Hi",
+ *     assistantResponse: "Hello!",
+ *     model:             "gpt-4o-mini",
+ *   }, { source: "my-product" });
+ */
+
+const SEMANTIC_SEARCH_QUERY = `
+  query SemanticSearchMemories($clientId: String!, $query: String!, $limit: Int, $minScore: Float) {
+    semanticSearchMemories(clientId: $clientId, query: $query, limit: $limit, minScore: $minScore) {
+      id
+      content
+      similarity
+    }
+  }
+`;
+
+const CREATE_MODULE_EVENT_MUTATION = `
+  mutation CreateModuleEvent($moduleId: String!, $input: ModuleEventInput!) {
+    createModuleEvent(moduleId: $moduleId, input: $input) { success eventId }
+  }
+`;
+
+const DEFAULT_SEARCH_TIMEOUT_MS = 5000;
+const DEFAULT_EMIT_TIMEOUT_MS = 10000;
+const DEFAULT_SEARCH_LIMIT = 6;
+const DEFAULT_SEARCH_MIN_SCORE = 0.55;
+
+/**
+ * Normalise a config object — accepts both modern (`endpoint/clientId/apiKey`)
+ * and legacy openclaw-style (`tes_endpoint/tes_client_id/tes_api_key`) keys.
+ *
+ * @param {object} config
+ * @returns {{endpoint: string, clientId: string, apiKey: string}}
+ */
+function normalizeConfig(config) {
+  if (!config) throw new Error("hosted: config is required");
+  const endpoint = config.endpoint || config.tes_endpoint;
+  const clientId = config.clientId || config.tes_client_id;
+  const apiKey = config.apiKey || config.tes_api_key;
+  if (!endpoint || !clientId || !apiKey) {
+    throw new Error(
+      "hosted: config requires { endpoint, clientId, apiKey } (or legacy tes_* equivalents)"
+    );
+  }
+  return { endpoint, clientId, apiKey };
+}
+
+/**
+ * Build the request headers TES expects for hosted-mode calls.
+ * Bearer auth if the apiKey starts with `tes_`; otherwise treated as a
+ * service key (for internal callers).
+ */
+export function buildHostedHeaders(config) {
+  const { clientId, apiKey } = normalizeConfig(config);
+  const headers = {
+    "Content-Type": "application/json",
+    "x-client-id": clientId,
+  };
+  if (apiKey.startsWith("tes_")) {
+    headers["Authorization"] = `Bearer ${apiKey}`;
+  } else {
+    headers["x-service-key"] = apiKey;
+  }
+  return headers;
+}
+
+/**
+ * Run a semantic memory search against a remote TES tenant.
+ *
+ * @param {object} config — { endpoint, clientId, apiKey }
+ * @param {string} query  — natural-language query
+ * @param {object} [opts]
+ * @param {number} [opts.limit=6]
+ * @param {number} [opts.minScore=0.55]
+ * @param {number} [opts.timeoutMs=5000]
+ * @returns {Promise<{
+ *   memories: Array<{id: string, content: string, similarity: number}>,
+ *   skipped?: string,
+ * }>}
+ *
+ * Failure mode: any error returns `{ memories: [], skipped: <reason> }`.
+ * Callers (e.g. the LLM proxy) inspect `skipped` to set `X-TES-Skipped`
+ * on their response, then forward unmodified. We never throw — the
+ * fail-soft contract means a hosted-search call never breaks the
+ * caller's primary user-facing flow.
+ */
+export async function hostedSearch(config, query, opts = {}) {
+  if (!query) return { memories: [], skipped: "no_query" };
+
+  let cfg;
+  try {
+    cfg = normalizeConfig(config);
+  } catch (err) {
+    return { memories: [], skipped: `config_error:${err.message}` };
+  }
+
+  const limit = opts.limit ?? DEFAULT_SEARCH_LIMIT;
+  const minScore = opts.minScore ?? DEFAULT_SEARCH_MIN_SCORE;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(`${cfg.endpoint}/api/graphql`, {
+      method: "POST",
+      headers: buildHostedHeaders(cfg),
+      body: JSON.stringify({
+        query: SEMANTIC_SEARCH_QUERY,
+        variables: { clientId: cfg.clientId, query, limit, minScore },
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      memories: [],
+      skipped: err.name === "AbortError" ? "tes_timeout" : "tes_unreachable",
+    };
+  }
+  clearTimeout(timer);
+
+  if (!response.ok) {
+    return { memories: [], skipped: `tes_http_${response.status}` };
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    return { memories: [], skipped: "tes_invalid_json" };
+  }
+
+  if (payload.errors?.length) {
+    const reason = payload.errors[0].message || "tes_graphql_error";
+    return { memories: [], skipped: `tes_graphql:${shortenReason(reason)}` };
+  }
+
+  return { memories: payload.data?.semanticSearchMemories || [] };
+}
+
+/**
+ * Emit a CHAT_TURN event to the conversation-analytics module of a
+ * remote TES tenant. The deep-memory consumer also subscribes to
+ * CHAT_TURN, so a single emit lands in both pipelines via consumer
+ * fan-out at the queue layer.
+ *
+ * @param {object} config — { endpoint, clientId, apiKey }
+ * @param {object} payload
+ * @param {string} [payload.userMessage]
+ * @param {string} [payload.assistantResponse]
+ * @param {string} [payload.model]
+ * @param {object} [payload.usage]
+ * @param {Array}  [payload.toolCalls]
+ * @param {number} [payload.turnNumber]
+ * @param {string} [payload.systemPrompt]
+ * @param {string} [payload.sessionId]
+ * @param {string} [payload.userId]
+ * @param {object} [payload.extra] — additional attributes merged onto the event
+ * @param {object} [opts]
+ * @param {string} [opts.source="tes-sdk"] — attribution string written into attributes.source
+ * @param {number} [opts.timeoutMs=10000]
+ * @returns {Promise<{ ok: boolean, eventId?: string, skipped?: string }>}
+ */
+export async function hostedEmitChatTurn(config, payload, opts = {}) {
+  if (!payload) return { ok: false, skipped: "no_payload" };
+  if (!payload.userMessage && !payload.assistantResponse) {
+    return { ok: false, skipped: "empty_turn" };
+  }
+
+  let cfg;
+  try {
+    cfg = normalizeConfig(config);
+  } catch (err) {
+    return { ok: false, skipped: `config_error:${err.message}` };
+  }
+
+  const source = opts.source || "tes-sdk";
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_EMIT_TIMEOUT_MS;
+
+  const attributes = { source };
+  if (payload.userMessage !== undefined)
+    attributes.user_message = payload.userMessage;
+  if (payload.assistantResponse !== undefined)
+    attributes.assistant_response = payload.assistantResponse;
+  if (payload.model) attributes.model = payload.model;
+  if (payload.usage) attributes.usage = payload.usage;
+  if (payload.toolCalls?.length) attributes.tool_calls = payload.toolCalls;
+  if (payload.turnNumber !== undefined)
+    attributes.turn_number = payload.turnNumber;
+  if (payload.systemPrompt) attributes.system_prompt = payload.systemPrompt;
+  if (payload.userId) attributes.user_id = payload.userId;
+  if (payload.extra && typeof payload.extra === "object") {
+    Object.assign(attributes, payload.extra);
+  }
+
+  const data = { attributes };
+  if (payload.sessionId) data.entity_id = payload.sessionId;
+
+  const input = { eventType: "CHAT_TURN", data };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(`${cfg.endpoint}/api/graphql`, {
+      method: "POST",
+      headers: buildHostedHeaders(cfg),
+      body: JSON.stringify({
+        query: CREATE_MODULE_EVENT_MUTATION,
+        variables: { moduleId: "conversation-analytics", input },
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      ok: false,
+      skipped: err.name === "AbortError" ? "tes_timeout" : "tes_unreachable",
+    };
+  }
+  clearTimeout(timer);
+
+  if (!response.ok) {
+    return { ok: false, skipped: `tes_http_${response.status}` };
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, skipped: "tes_invalid_json" };
+  }
+
+  if (body.errors?.length) {
+    return {
+      ok: false,
+      skipped: `tes_graphql:${shortenReason(body.errors[0].message)}`,
+    };
+  }
+
+  return {
+    ok: !!body.data?.createModuleEvent?.success,
+    eventId: body.data?.createModuleEvent?.eventId,
+  };
+}
+
+/**
+ * Emit a STORE_MEMORY event against the deep-memory module. Used by the
+ * OpenClaw plugin for explicit memory-write tools.
+ *
+ * @param {object} config
+ * @param {string} content
+ * @param {object} [metadata]
+ * @param {object} [opts]
+ * @param {string} [opts.source="tes-sdk"]
+ * @param {number} [opts.timeoutMs=10000]
+ * @returns {Promise<{ ok: boolean, eventId?: string, skipped?: string }>}
+ */
+export async function hostedStoreMemory(
+  config,
+  content,
+  metadata = {},
+  opts = {}
+) {
+  if (!content) return { ok: false, skipped: "no_content" };
+
+  let cfg;
+  try {
+    cfg = normalizeConfig(config);
+  } catch (err) {
+    return { ok: false, skipped: `config_error:${err.message}` };
+  }
+
+  const source = opts.source || "tes-sdk";
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_EMIT_TIMEOUT_MS;
+
+  const data = {
+    entity_id: metadata.session_id || metadata.sessionId || source,
+    attributes: {
+      ...metadata,
+      content,
+      source,
+    },
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetch(`${cfg.endpoint}/api/graphql`, {
+      method: "POST",
+      headers: buildHostedHeaders(cfg),
+      body: JSON.stringify({
+        query: CREATE_MODULE_EVENT_MUTATION,
+        variables: {
+          moduleId: "deep-memory",
+          input: { eventType: "STORE_MEMORY", data },
+        },
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    return {
+      ok: false,
+      skipped: err.name === "AbortError" ? "tes_timeout" : "tes_unreachable",
+    };
+  }
+  clearTimeout(timer);
+
+  if (!response.ok) {
+    return { ok: false, skipped: `tes_http_${response.status}` };
+  }
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, skipped: "tes_invalid_json" };
+  }
+
+  if (body.errors?.length) {
+    return {
+      ok: false,
+      skipped: `tes_graphql:${shortenReason(body.errors[0].message)}`,
+    };
+  }
+
+  return {
+    ok: !!body.data?.createModuleEvent?.success,
+    eventId: body.data?.createModuleEvent?.eventId,
+  };
+}
+
+function shortenReason(msg) {
+  if (typeof msg !== "string") return "unknown";
+  return msg
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .slice(0, 60);
+}

package/packages/memory/src/openclaw/index.js

@@ -38,6 +38,40 @@
 import pg from "pg";
 import { createMemorySystem } from "../index.js";
 import { createContextEngine } from "./context-engine.js";
+import { sanitizeMemoryContent } from "../sanitize.js";
+import {
+  hostedSearch as _hostedSearch,
+  hostedEmitChatTurn as _hostedEmitChatTurn,
+  hostedStoreMemory as _hostedStoreMemory,
+} from "../hosted.js";
+
+// --- Hosted-mode adapters ---
+//
+// The OpenClaw plugin predates the public hosted-helper API (`packages/
+// memory/src/hosted.js`). The wrappers below adapt the plugin's existing
+// call shape to the public API so other consumers (the LLM proxy worker,
+// custom integrations) hit the same code path. Adapters are tiny — they
+// translate args and unwrap the result envelope. New code should import
+// from `@pentatonic-ai/ai-agent-sdk/memory/hosted` directly.
+
+async function hostedSearch(config, query, limit = 5, minScore = 0.3) {
+  const { memories } = await _hostedSearch(config, query, { limit, minScore });
+  return memories;
+}
+
+async function hostedEmitChatTurn(config, sessionId, turn) {
+  return _hostedEmitChatTurn(
+    config,
+    { ...turn, sessionId },
+    { source: "openclaw-plugin" }
+  );
+}
+
+async function hostedStore(config, content, metadata = {}) {
+  return _hostedStoreMemory(config, content, metadata, {
+    source: metadata.source || "openclaw-plugin",
+  });
+}
 
 const { Pool } = pg;
 
@@ -74,139 +108,6 @@ function getLocalMemory(config) {
   return memory;
 }
 
-// --- Hosted mode helpers ---
-
-function tesHeaders(config) {
-  const headers = {
-    "Content-Type": "application/json",
-    "x-client-id": config.tes_client_id,
-  };
-  if (config.tes_api_key?.startsWith("tes_")) {
-    headers["Authorization"] = `Bearer ${config.tes_api_key}`;
-  } else {
-    headers["x-service-key"] = config.tes_api_key;
-  }
-  return headers;
-}
-
-async function hostedSearch(config, query, limit = 5, minScore = 0.3) {
-  try {
-    const response = await fetch(`${config.tes_endpoint}/api/graphql`, {
-      method: "POST",
-      headers: tesHeaders(config),
-      body: JSON.stringify({
-        query: `query($clientId: String!, $query: String!, $limit: Int, $minScore: Float) {
-          semanticSearchMemories(clientId: $clientId, query: $query, limit: $limit, minScore: $minScore) {
-            id content similarity
-          }
-        }`,
-        variables: {
-          clientId: config.tes_client_id,
-          query,
-          limit,
-          minScore,
-        },
-      }),
-      signal: AbortSignal.timeout(5000),
-    });
-    if (!response.ok) return [];
-    const json = await response.json();
-    return json.data?.semanticSearchMemories || [];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * 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.
- *
- * Anything missing from the message metadata is omitted rather than
- * defaulted to zero — that way the dashboard can distinguish "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 response = await fetch(`${config.tes_endpoint}/api/graphql`, {
-      method: "POST",
-      headers: tesHeaders(config),
-      // Route through createModuleEvent on the conversation-analytics
-      // module rather than the top-level emitEvent. The latter requires
-      // a permission most client API keys don't have ("Access denied:
-      // You don't have permission to update emitEvent"), but the
-      // module's manifest declares CHAT_TURN as a registered event
-      // type, so the module-scoped path is both authorised and
-      // consistent with how STORE_MEMORY is emitted.
-      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 (!response.ok) return null;
-    return response.json();
-  } catch {
-    return null;
-  }
-}
-
-async function hostedStore(config, content, metadata = {}) {
-  try {
-    const response = await fetch(`${config.tes_endpoint}/api/graphql`, {
-      method: "POST",
-      headers: tesHeaders(config),
-      body: JSON.stringify({
-        query: `mutation CreateModuleEvent($moduleId: String!, $input: ModuleEventInput!) {
-          createModuleEvent(moduleId: $moduleId, input: $input) { success eventId }
-        }`,
-        variables: {
-          moduleId: "deep-memory",
-          input: {
-            eventType: "STORE_MEMORY",
-            data: {
-              entity_id: metadata.session_id || "openclaw",
-              attributes: {
-                ...metadata,
-                content,
-                source: "openclaw-plugin",
-              },
-            },
-          },
-        },
-      }),
-      signal: AbortSignal.timeout(10000),
-    });
-    if (!response.ok) return null;
-    return response.json();
-  } catch {
-    return null;
-  }
-}
-
 // --- Hosted context engine ---
 
 // Per-session turn buffer. Holds the user message until the matching
@@ -440,7 +341,7 @@ function createHostedContextEngine(config, opts = {}) {
         const memoryText = results
           .map(
             (m) =>
-              `- [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`
+              `- [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
           )
           .join("\n");
 
@@ -638,7 +539,7 @@ Tell the user to run step 1 first, then help them fill in the config with the cr
           return results
             .map(
               (m, i) =>
-                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`
+                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
             )
             .join("\n\n");
         },
@@ -705,7 +606,7 @@ Tell the user to run step 1 first, then help them fill in the config with the cr
           return results
             .map(
               (m, i) =>
-                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${m.content}`
+                `${i + 1}. [${Math.round((m.similarity || 0) * 100)}%] ${sanitizeMemoryContent(m.content)}`
             )
             .join("\n\n");
         },

package/packages/memory/src/sanitize.js

@@ -0,0 +1,61 @@
+/**
+ * Memory-content sanitizer.
+ *
+ * Stored memories from TES often contain dashboard-UI noise (leading
+ * timestamps, layer IDs, confidence/decay metadata, trailing JSON
+ * blobs). This strips them before showing content to the model — the
+ * fact-bearing text is what matters, the metadata just dilutes the
+ * signal and burns context budget.
+ *
+ * Conservative: if stripping would leave no real words, fall back to
+ * the original content. Better a noisy signal than none.
+ *
+ * Canonical implementation. The Claude Code hook (`hooks/scripts/
+ * shared.js`) and the published openclaw-plugin (`openclaw-plugin/
+ * index.js`) each inline the same logic — they're published
+ * standalone and can't cross-import. Update all three if changing.
+ */
+
+const TES_META_FIELDS =
+  "event_id|event_type|entity_type|source|clientId|correlationId|timestamp|session_id|layer_id|confidence|decay_rate|user_id";
+
+export const MEMORY_MAX_LEN = 600;
+
+export function sanitizeMemoryContent(content) {
+  if (typeof content !== "string") return content;
+  let out = content;
+  // Trailing JSON metadata blob (no `m` flag — `$` = end-of-string).
+  out = out.replace(/\n\{\s*\n[\s\S]*?\n\s*\}\s*$/, "");
+  // Inline JSON metadata blobs (2+ consecutive TES metadata fields).
+  out = out.replace(
+    new RegExp(
+      `\\{\\s*\\n(\\s*"(?:${TES_META_FIELDS})"[^\\n]*\\n){2,}\\s*\\}`,
+      "g"
+    ),
+    ""
+  );
+  // Dashboard-UI standalone lines.
+  const linePatterns = [
+    /^\s*anonymous\s*$/gm,
+    /^\s*ml_[a-z0-9_-]+_(episodic|semantic|procedural|working)\s*$/gm,
+    /^\s*\d+%\s*match\s*$/gm,
+    /^\s*Confidence:\s*\d+%\s*$/gm,
+    /^\s*Accessed:\s*\d+x?\s*$/gm,
+    /^\s*<?\s*\d+[smhd]\s*ago\s*$/gm,
+    /^\s*Decay:\s*[\d.]+\s*$/gm,
+    /^\s*Metadata\s*$/gm,
+  ];
+  for (const pat of linePatterns) out = out.replace(pat, "");
+  // Leading ISO timestamps — strip prefix, keep line content.
+  out = out.replace(/^\s*\[\d{4}-\d{2}-\d{2}T[\d:.]+Z\]\s*/gm, "");
+  // Collapse consecutive blank lines.
+  out = out.replace(/\n\s*\n\s*\n+/g, "\n\n").trim();
+  // Cap verbose transcript dumps.
+  if (out.length > MEMORY_MAX_LEN) {
+    out = out.slice(0, MEMORY_MAX_LEN).trimEnd() + "…";
+  }
+  // Fallback to original if we stripped everything meaningful.
+  const wordCount = (out.match(/\b\w{2,}\b/g) || []).length;
+  if (wordCount < 2) return content;
+  return out;
+}