@pentatonic-ai/ai-agent-sdk 0.4.9 → 0.5.1

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

@@ -0,0 +1,142 @@
+/**
+ * Memory-used indicator tests.
+ *
+ * When the assemble hook injects memories into the system prompt, the
+ * plugin appends an instruction telling the LLM to add a visible footer
+ * to its reply so the end user sees when Pentatonic Memory was used.
+ *
+ * Opt out with show_memory_indicator: false in plugin config.
+ */
+
+import plugin from "../index.js";
+
+const realFetch = globalThis.fetch;
+
+function mockFetch(searchResults) {
+  globalThis.fetch = async (url, init) => {
+    const body = init?.body ? JSON.parse(init.body) : null;
+    const query = body?.query || "";
+    // Return search results for hosted search; empty for anything else.
+    if (query.includes("semanticSearchMemories")) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: { semanticSearchMemories: searchResults },
+        }),
+      };
+    }
+    if (url.endsWith("/search")) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ results: searchResults }),
+      };
+    }
+    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("plugin did not register a context engine");
+  return factory();
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe("memory-used indicator — hosted mode", () => {
+  it("injects a footer instruction into systemPromptAddition when memories are found", async () => {
+    mockFetch([
+      { id: "m1", content: "Phil likes cheese", similarity: 0.9 },
+      { id: "m2", content: "Phil drinks cortado", similarity: 0.8 },
+    ]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "what do I like?" }],
+    });
+
+    expect(result.systemPromptAddition).toMatch(/🧠/);
+    expect(result.systemPromptAddition).toMatch(/Used 2 memories from Pentatonic Memory/);
+    expect(result.systemPromptAddition).toMatch(/append exactly this footer/);
+  });
+
+  it("pluralises correctly for a single memory", async () => {
+    mockFetch([{ id: "m1", content: "only one", similarity: 0.9 }]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "query" }],
+    });
+
+    expect(result.systemPromptAddition).toMatch(/Used 1 memory from Pentatonic Memory/);
+    expect(result.systemPromptAddition).not.toMatch(/Used 1 memories/);
+  });
+
+  it("omits the indicator instruction when show_memory_indicator is false", async () => {
+    mockFetch([{ id: "m1", content: "fact", similarity: 0.9 }]);
+    const engine = makeEngine({ show_memory_indicator: false });
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "query" }],
+    });
+
+    expect(result.systemPromptAddition).toBeDefined();
+    expect(result.systemPromptAddition).not.toMatch(/🧠/);
+    expect(result.systemPromptAddition).not.toMatch(/Pentatonic Memory_/);
+    // Still contains the memory content itself
+    expect(result.systemPromptAddition).toMatch(/fact/);
+  });
+
+  it("does not inject anything when no memories are found", async () => {
+    mockFetch([]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "query" }],
+    });
+
+    // No memories → no systemPromptAddition at all (so nothing to indicate)
+    expect(result.systemPromptAddition).toBeUndefined();
+  });
+
+  it("instructs the LLM to omit the footer if memories weren't relevant", async () => {
+    // The prompt tells the model to skip the footer when the memories
+    // didn't influence the reply, so unrelated questions don't get a
+    // spurious "used 3 memories" footer.
+    mockFetch([{ id: "m1", content: "Phil likes cheese", similarity: 0.4 }]);
+    const engine = makeEngine();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "query" }],
+    });
+
+    expect(result.systemPromptAddition).toMatch(
+      /If the memories above were not relevant to your reply, omit the footer/
+    );
+  });
+});

package/packages/memory/openclaw-plugin/__tests__/query-expansion.test.js

@@ -0,0 +1,193 @@
+/**
+ * Query expansion fallback tests.
+ *
+ * When the raw user prompt returns no memories, the plugin retries once
+ * with a keyword-distilled form. This recovers matches for verbose
+ * natural-language prompts that fall below the semantic threshold.
+ */
+
+import plugin, { extractSearchKeywords } from "../index.js";
+
+const realFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+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("plugin did not register a context engine");
+  return factory();
+}
+
+describe("extractSearchKeywords", () => {
+  it("strips stopwords from verbose prompts", () => {
+    const out = extractSearchKeywords(
+      "when I was working in the thing-event-system, I copied migrations, what were they?"
+    );
+    expect(out).toMatch(/thing-event-system/);
+    expect(out).toMatch(/migrations/);
+    expect(out).not.toMatch(/\bwhen\b/);
+    expect(out).not.toMatch(/\bwhat\b/);
+  });
+
+  it("preserves hyphenated compounds", () => {
+    expect(extractSearchKeywords("where is thing-event-system?")).toMatch(
+      /thing-event-system/
+    );
+  });
+
+  it("returns null when the distilled form equals the input", () => {
+    expect(extractSearchKeywords("deep-memory migrations")).toBeNull();
+  });
+
+  it("returns null when the prompt is only stopwords", () => {
+    expect(extractSearchKeywords("what were they?")).toBeNull();
+  });
+
+  it("returns null for non-string input", () => {
+    expect(extractSearchKeywords(null)).toBeNull();
+    expect(extractSearchKeywords(undefined)).toBeNull();
+  });
+});
+
+describe("assemble — keyword retry fallback (hosted mode)", () => {
+  it("retries with distilled keywords when raw prompt misses", async () => {
+    const queries = [];
+    globalThis.fetch = async (_url, init) => {
+      const body = JSON.parse(init.body);
+      const q = body.variables.query;
+      queries.push(q);
+      const isFirst = queries.length === 1;
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            semanticSearchMemories: isFirst
+              ? []
+              : [{ id: "m1", content: "matched on retry", similarity: 0.7 }],
+          },
+        }),
+      };
+    };
+
+    const engine = makeEngine();
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [
+        {
+          role: "user",
+          content:
+            "when I was working in the thing-event-system, what were those migration changes again?",
+        },
+      ],
+    });
+
+    expect(queries).toHaveLength(2);
+    expect(queries[0]).toMatch(/when I was working/);
+    expect(queries[1]).not.toMatch(/\bwhen\b/);
+    expect(queries[1]).toMatch(/thing-event-system/);
+    expect(queries[1]).toMatch(/migration/);
+    expect(result.systemPromptAddition).toMatch(/matched on retry/);
+  });
+
+  it("does not retry when the raw prompt already returns results", async () => {
+    const queries = [];
+    globalThis.fetch = async (_url, init) => {
+      queries.push(JSON.parse(init.body).variables.query);
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            semanticSearchMemories: [
+              { id: "m1", content: "hit", similarity: 0.9 },
+            ],
+          },
+        }),
+      };
+    };
+
+    const engine = makeEngine();
+    await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "thing-event-system migrations" }],
+    });
+
+    expect(queries).toHaveLength(1);
+  });
+
+  it("does not retry when distilled query equals the raw query", async () => {
+    const queries = [];
+    globalThis.fetch = async (_url, init) => {
+      queries.push(JSON.parse(init.body).variables.query);
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ data: { semanticSearchMemories: [] } }),
+      };
+    };
+
+    const engine = makeEngine();
+    await engine.assemble({
+      sessionId: "s",
+      messages: [{ role: "user", content: "deep-memory migrations" }],
+    });
+
+    expect(queries).toHaveLength(1);
+  });
+});
+
+describe("assemble — keyword retry fallback (local mode)", () => {
+  it("retries via /search endpoint when raw query returns nothing", async () => {
+    const queries = [];
+    globalThis.fetch = async (_url, init) => {
+      const body = JSON.parse(init.body);
+      queries.push(body.query);
+      const isFirst = queries.length === 1;
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          results: isFirst
+            ? []
+            : [{ id: "m1", content: "local hit", similarity: 0.6 }],
+        }),
+      };
+    };
+
+    let factory;
+    plugin.register({
+      pluginConfig: {}, // no tes_* creds → local mode
+      registerTool: () => {},
+      registerContextEngine: (_name, fn) => {
+        factory = fn;
+      },
+    });
+    const engine = factory();
+
+    const result = await engine.assemble({
+      sessionId: "s",
+      messages: [
+        { role: "user", content: "what were the migration changes again?" },
+      ],
+    });
+
+    expect(queries).toHaveLength(2);
+    expect(queries[1]).toMatch(/migration/);
+    expect(result.systemPromptAddition).toMatch(/local hit/);
+  });
+});

package/packages/memory/openclaw-plugin/__tests__/version-check.test.js

@@ -0,0 +1,136 @@
+/**
+ * Server-version mismatch warning — plugin checks the local memory
+ * server's /health payload and warns loudly (stderr) when the server
+ * is older than MIN_SERVER_VERSION. Catches the common footgun of
+ * updating the plugin without re-running `npx ... memory` to rebuild
+ * the Docker stack.
+ */
+
+import plugin from "../index.js";
+
+const realFetch = globalThis.fetch;
+
+// Capture console.error so tests can assert on warnings.
+function captureWarnings() {
+  const warnings = [];
+  const orig = console.error;
+  console.error = (...args) => warnings.push(args.join(" "));
+  return {
+    warnings,
+    restore: () => {
+      console.error = orig;
+    },
+  };
+}
+
+function mockHealth(body, ok = true) {
+  globalThis.fetch = async (url) => {
+    if (url.endsWith("/health")) {
+      return {
+        ok,
+        status: ok ? 200 : 500,
+        json: async () => body,
+      };
+    }
+    return { ok: true, status: 200, json: async () => ({}) };
+  };
+}
+
+function makeEngine(extraConfig = {}) {
+  let factory;
+  plugin.register({
+    pluginConfig: {
+      memory_url: "http://localhost:3333",
+      ...extraConfig,
+    },
+    registerTool: () => {},
+    registerContextEngine: (_n, fn) => {
+      factory = fn;
+    },
+  });
+  return factory();
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe("memory server version check", () => {
+  it("warns when server is older than MIN_SERVER_VERSION", async () => {
+    mockHealth({ status: "ok", version: "0.4.5" });
+    const cap = captureWarnings();
+    const engine = makeEngine();
+    // register schedules a localHealth() call asynchronously — await it
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    cap.restore();
+
+    const warning = cap.warnings.find((w) =>
+      w.includes("memory server is 0.4.5")
+    );
+    expect(warning).toBeDefined();
+    expect(warning).toMatch(/npx @pentatonic-ai\/ai-agent-sdk@latest memory/);
+  });
+
+  it("does NOT warn when server is at MIN_SERVER_VERSION", async () => {
+    mockHealth({ status: "ok", version: "0.5.0" });
+    const cap = captureWarnings();
+    makeEngine();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    cap.restore();
+
+    const warning = cap.warnings.find((w) => w.includes("memory server is"));
+    expect(warning).toBeUndefined();
+  });
+
+  it("does NOT warn when server is newer than MIN_SERVER_VERSION", async () => {
+    mockHealth({ status: "ok", version: "1.2.3" });
+    const cap = captureWarnings();
+    makeEngine();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    cap.restore();
+
+    const warning = cap.warnings.find((w) => w.includes("memory server is"));
+    expect(warning).toBeUndefined();
+  });
+
+  it("does NOT warn when health payload lacks a version field", async () => {
+    // Older servers that predate the version field in /health — silent,
+    // don't spam warnings on something the user can't diagnose.
+    mockHealth({ status: "ok" });
+    const cap = captureWarnings();
+    makeEngine();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    cap.restore();
+
+    const warning = cap.warnings.find((w) => w.includes("memory server is"));
+    expect(warning).toBeUndefined();
+  });
+
+  it("does NOT warn when server is unreachable", async () => {
+    globalThis.fetch = async () => {
+      throw new Error("connection refused");
+    };
+    const cap = captureWarnings();
+    makeEngine();
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    cap.restore();
+
+    const warning = cap.warnings.find((w) => w.includes("memory server is"));
+    expect(warning).toBeUndefined();
+  });
+
+  it("only warns once per server version (deduplicates)", async () => {
+    mockHealth({ status: "ok", version: "0.4.0" });
+    const cap = captureWarnings();
+    // Register twice — simulates multiple context-engine factory calls.
+    makeEngine();
+    makeEngine();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    cap.restore();
+
+    const warnings = cap.warnings.filter((w) =>
+      w.includes("memory server is 0.4.0")
+    );
+    expect(warnings).toHaveLength(1);
+  });
+});