@pentatonic-ai/ai-agent-sdk 0.4.0-beta.2 → 0.4.1

package/README.md

@@ -27,6 +27,7 @@
 - [Local Memory (self-hosted)](#local-memory-self-hosted)
 - [Hosted TES](#hosted-tes)
 - [Claude Code Plugin](#claude-code-plugin)
+- [OpenClaw Plugin](#openclaw-plugin)
 - [SDK: Wrap Your LLM Client](#sdk-wrap-your-llm-client)
 - [Supported Providers](#supported-providers)
 - [API Reference](#api-reference)
@@ -40,7 +41,7 @@ Two ways to use the SDK:
 
 **Hosted TES** -- Connect to Pentatonic's Thing Event System for production-grade observability, higher-dimensional embeddings, conversation analytics, and team-wide shared memory.
 
-Both paths use the same Claude Code plugin. The hooks auto-search on every prompt and auto-store every conversation turn.
+Both paths work with Claude Code and OpenClaw. The plugins auto-search on every prompt and auto-store every conversation turn.
 
 ## Local Memory (self-hosted)
 
@@ -163,6 +164,79 @@ npx @pentatonic-ai/ai-agent-sdk memory
 - **Automatic memory storage** -- every turn stored with embeddings and HyDE queries
 - **Token usage** -- input, output, cache read, cache creation tokens per turn
 
+## OpenClaw Plugin
+
+Works with both local and hosted setups. Just tell OpenClaw to set it up.
+
+### Install
+
+```bash
+openclaw plugins install -l ./packages/memory/src/openclaw
+```
+
+### Set up
+
+Tell OpenClaw:
+
+```
+Set up pentatonic memory
+```
+
+The agent will ask whether you want **local** (private, Docker-based) or **hosted** (Pentatonic TES cloud), then walk you through the rest. For hosted mode, it handles account creation, email verification, and API key generation conversationally.
+
+Or use the CLI directly:
+
+```bash
+openclaw pentatonic-memory local
+```
+
+### What it does
+
+OpenClaw's context engine hooks fire on every lifecycle event:
+
+- **Ingest** -- every user and assistant message is stored with embeddings and HyDE query expansion
+- **Assemble** -- relevant memories are injected as system prompt context before every model run
+- **Compact** -- decay cycle runs when the context window fills
+- **After turn** -- high-access memories get consolidated to the semantic layer
+
+Plus agent-callable tools: `memory_search`, `memory_store`, `memory_layers`.
+
+### Configuration
+
+After setup, config lives in `~/.openclaw/pentatonic-memory.json`. To switch modes, run setup again or edit directly.
+
+You can also configure via `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": { "contextEngine": "pentatonic-memory" },
+    "entries": {
+      "pentatonic-memory": {
+        "enabled": true,
+        "config": {
+          "database_url": "postgres://memory:memory@localhost:5433/memory",
+          "embedding_url": "http://localhost:11435/v1",
+          "embedding_model": "nomic-embed-text",
+          "llm_url": "http://localhost:11435/v1",
+          "llm_model": "llama3.2:3b"
+        }
+      }
+    }
+  }
+}
+```
+
+For hosted mode, replace the config block with:
+
+```json
+{
+  "tes_endpoint": "https://your-company.api.pentatonic.com",
+  "tes_client_id": "your-company",
+  "tes_api_key": "tes_your-company_xxxxx"
+}
+```
+
 ## SDK: Wrap Your LLM Client
 
 **JavaScript**
@@ -254,21 +328,24 @@ const { content, model, usage, toolCalls } = normalizeResponse(openaiResponse);
 ## Architecture
 
 ```
-                    +-----------------------+
-                    |   Claude Code Plugin  |
-                    |   (hooks: auto-search |
-                    |    + auto-store)      |
-                    +-----------+-----------+
-                                |
-                    +-----------+-----------+
-                    |                       |
-              Local Memory            Hosted TES
-              (Docker)                (Cloud)
-                    |                       |
-         +----+----+----+          +---+----+---+
-         |    |    |    |          |   |    |   |
-        PG  Ollama MCP HTTP      PG  R2  Queue Workers
-        pgvector        API     pgvector       Modules
+        +-------------------+     +-------------------+
+        | Claude Code Plugin|     |  OpenClaw Plugin   |
+        | (hooks: auto-     |     | (context engine:   |
+        |  search + store)  |     |  ingest, assemble, |
+        +--------+----------+     |  compact, tools)   |
+                 |                +--------+----------+
+                 |                         |
+                 +------------+------------+
+                              |
+                  +-----------+-----------+
+                  |                       |
+            Local Memory            Hosted TES
+            (Docker)                (Cloud)
+                  |                       |
+       +----+----+----+          +---+----+---+
+       |    |    |    |          |   |    |   |
+      PG  Ollama MCP HTTP      PG  R2  Queue Workers
+      pgvector        API     pgvector       Modules
 ```
 
 ## License

package/bin/cli.js

@@ -190,13 +190,27 @@ async function setupLocalMemory() {
     llmSpinner.fail(`Failed to pull ${llmModel}. Run manually: docker compose exec ollama ollama pull ${llmModel}`);
   }
 
-  // Write local config
+  // Write local config (warn if hosted config exists)
   const configDir = join(homedir(), ".claude-pentatonic");
   if (!existsSync(configDir)) {
     mkdirSync(configDir, { recursive: true });
   }
 
   const configPath = join(configDir, "tes-memory.local.md");
+  if (existsSync(configPath)) {
+    const existing = readFileSync(configPath, "utf-8");
+    if (existing.includes("tes_endpoint") && !existing.includes("mode: local")) {
+      console.log("\n  ⚠ Hosted TES config detected. Switching to local mode will");
+      console.log("  disable hosted memory. To restore, run: npx @pentatonic-ai/ai-agent-sdk init\n");
+      const confirm = await ask("  Switch to local mode? (y/n): ");
+      if (confirm.toLowerCase() !== "y") {
+        console.log("  Cancelled. Hosted config unchanged.\n");
+        rl.close();
+        return;
+      }
+    }
+  }
+
   writeFileSync(
     configPath,
     `---

package/dist/index.cjs

@@ -646,6 +646,39 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
   }
 }
 
+// src/telemetry.js
+var VERSION = "0.4.0";
+var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
+function machineId() {
+  const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";
+  let hash = 0;
+  for (let i = 0; i < raw.length; i++) {
+    hash = (hash << 5) - hash + raw.charCodeAt(i) | 0;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function emitTelemetry(mode) {
+  if (typeof process !== "undefined" && process.env?.PENTATONIC_TELEMETRY === "0")
+    return;
+  const f = globalThis.fetch;
+  if (!f)
+    return;
+  f(TELEMETRY_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      machine_id: machineId(),
+      sdk_version: VERSION,
+      node_version: typeof process !== "undefined" ? process.version : "unknown",
+      platform: typeof process !== "undefined" ? process.platform : "unknown",
+      arch: typeof process !== "undefined" ? process.arch : "unknown",
+      mode: mode || "hosted"
+    }),
+    signal: AbortSignal.timeout(5e3)
+  }).catch(() => {
+  });
+}
+
 // src/client.js
 var TESClient = class {
   constructor({ clientId, apiKey, endpoint, headers, userId, captureContent = true, maxContentLength = 4096 }) {
@@ -677,6 +710,7 @@ var TESClient = class {
       enumerable: false,
       writable: false
     });
+    emitTelemetry("hosted");
   }
   get _config() {
     return {

package/dist/index.js

@@ -615,6 +615,39 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
   }
 }
 
+// src/telemetry.js
+var VERSION = "0.4.0";
+var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
+function machineId() {
+  const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";
+  let hash = 0;
+  for (let i = 0; i < raw.length; i++) {
+    hash = (hash << 5) - hash + raw.charCodeAt(i) | 0;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function emitTelemetry(mode) {
+  if (typeof process !== "undefined" && process.env?.PENTATONIC_TELEMETRY === "0")
+    return;
+  const f = globalThis.fetch;
+  if (!f)
+    return;
+  f(TELEMETRY_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      machine_id: machineId(),
+      sdk_version: VERSION,
+      node_version: typeof process !== "undefined" ? process.version : "unknown",
+      platform: typeof process !== "undefined" ? process.platform : "unknown",
+      arch: typeof process !== "undefined" ? process.arch : "unknown",
+      mode: mode || "hosted"
+    }),
+    signal: AbortSignal.timeout(5e3)
+  }).catch(() => {
+  });
+}
+
 // src/client.js
 var TESClient = class {
   constructor({ clientId, apiKey, endpoint, headers, userId, captureContent = true, maxContentLength = 4096 }) {
@@ -646,6 +679,7 @@ var TESClient = class {
       enumerable: false,
       writable: false
     });
+    emitTelemetry("hosted");
   }
   get _config() {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.4.0-beta.2",
+  "version": "0.4.1",
   "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.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,7 +29,7 @@
   "scripts": {
     "prepare": "node build.js",
     "build": "node build.js",
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --config jest.config.cjs",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --config jest.config.cjs --testPathIgnorePatterns='/e2e/'",
     "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --config jest.config.cjs --watch",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -59,10 +59,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@pentatonic-ai/ai-agent-sdk": "^0.4.0",
     "esbuild": "^0.20.0"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "pg": "^8.20.0"
   }
 }

package/packages/memory/src/migrate.js

@@ -5,22 +5,26 @@
  * in a schema_migrations table.
  */
 
-import { readFileSync, readdirSync } from "fs";
-import { resolve, dirname } from "path";
-import { fileURLToPath } from "url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MIGRATIONS_DIR = resolve(__dirname, "../migrations");
-
 /**
  * Apply all pending database migrations.
  *
+ * Note: This function uses Node.js fs/path APIs and will not work in
+ * Cloudflare Workers. TES uses its own migration system instead.
+ *
  * @param {Function} db - Database query function: (sql, params) => {rows}
  * @param {object} [opts]
  * @param {Function} [opts.logger] - Optional logger
+ * @param {string} [opts.migrationsDir] - Override migrations directory
  * @returns {Promise<{applied: string[], total: number}>}
  */
 export async function migrate(db, opts = {}) {
+  const { readFileSync, readdirSync } = await import("fs");
+  const { resolve, dirname } = await import("path");
+  const { fileURLToPath } = await import("url");
+
+  const migrationsDir =
+    opts.migrationsDir ||
+    resolve(dirname(fileURLToPath(import.meta.url)), "../migrations");
   const log = opts.logger || (() => {});
 
   // Ensure migrations tracking table exists
@@ -40,7 +44,7 @@ export async function migrate(db, opts = {}) {
   const appliedSet = new Set((applied.rows || []).map((r) => r.name));
 
   // Read migration files
-  const files = readdirSync(MIGRATIONS_DIR)
+  const files = readdirSync(migrationsDir)
     .filter((f) => f.endsWith(".sql"))
     .sort();
 
@@ -49,7 +53,7 @@ export async function migrate(db, opts = {}) {
   for (const file of files) {
     if (appliedSet.has(file)) continue;
 
-    const sql = readFileSync(resolve(MIGRATIONS_DIR, file), "utf-8");
+    const sql = readFileSync(resolve(migrationsDir, file), "utf-8");
     log(`Applying migration: ${file}`);
 
     await db(sql, []);