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

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

@@ -0,0 +1,175 @@
+/**
+ * Distillation tests — unit tests for extractAtomicFacts and distill.
+ *
+ * Uses mock LLM/embedding clients and an in-memory db fake.
+ */
+
+import { extractAtomicFacts, distill } from "../distill.js";
+
+// --- Mock helpers ---
+
+function mockLlm(responseText) {
+  return {
+    chat: async () => responseText,
+  };
+}
+
+function mockAi() {
+  return {
+    embed: async (text) => ({
+      embedding: new Array(768).fill(0).map((_, i) => i / 768),
+      dimensions: 768,
+      model: "mock",
+    }),
+    chat: async () => "",
+  };
+}
+
+function mockDb(overrides = {}) {
+  const calls = [];
+  const db = async (sql, params) => {
+    calls.push({ sql, params });
+    // Layer lookup
+    if (sql.includes("FROM memory_layers")) {
+      return { rows: [{ id: "layer_semantic_id" }] };
+    }
+    // Handle INSERTs / UPDATEs silently
+    return { rows: [] };
+  };
+  db.calls = calls;
+  return db;
+}
+
+// --- extractAtomicFacts ---
+
+describe("extractAtomicFacts", () => {
+  it("parses a JSON array response", async () => {
+    const llm = mockLlm('["Phil loves steak", "Phil lives in Nantwich"]');
+    const facts = await extractAtomicFacts(llm, "I love steak and I live in Nantwich");
+    expect(facts).toEqual(["Phil loves steak", "Phil lives in Nantwich"]);
+  });
+
+  it("strips markdown code fences", async () => {
+    const llm = mockLlm('```json\n["Phil likes coffee"]\n```');
+    const facts = await extractAtomicFacts(llm, "I like coffee");
+    expect(facts).toEqual(["Phil likes coffee"]);
+  });
+
+  it("returns empty array when LLM returns empty", async () => {
+    const llm = mockLlm("");
+    const facts = await extractAtomicFacts(llm, "hi");
+    expect(facts).toEqual([]);
+  });
+
+  it("returns empty array when JSON is malformed", async () => {
+    const llm = mockLlm("not json at all");
+    const facts = await extractAtomicFacts(llm, "some content");
+    expect(facts).toEqual([]);
+  });
+
+  it("returns empty array when response is not an array", async () => {
+    const llm = mockLlm('{"fact": "Phil likes coffee"}');
+    const facts = await extractAtomicFacts(llm, "some content");
+    expect(facts).toEqual([]);
+  });
+
+  it("filters out non-string entries", async () => {
+    const llm = mockLlm('["valid fact", 123, null, "", "   ", "another"]');
+    const facts = await extractAtomicFacts(llm, "...");
+    expect(facts).toEqual(["valid fact", "another"]);
+  });
+
+  it("trims whitespace", async () => {
+    const llm = mockLlm('["  Phil likes tea  "]');
+    const facts = await extractAtomicFacts(llm, "...");
+    expect(facts).toEqual(["Phil likes tea"]);
+  });
+
+  it("includes userName hint in system prompt when provided", async () => {
+    let capturedMessages;
+    const llm = {
+      chat: async (messages) => {
+        capturedMessages = messages;
+        return "[]";
+      },
+    };
+    await extractAtomicFacts(llm, "I like tea", { userName: "Phil" });
+    expect(capturedMessages[0].content).toContain("Phil");
+  });
+});
+
+// --- distill ---
+
+describe("distill", () => {
+  it("returns empty array when no facts extracted", async () => {
+    const db = mockDb();
+    const llm = mockLlm("[]");
+    const ai = mockAi();
+    const result = await distill(db, ai, llm, "mem_src", "hello", {
+      clientId: "test",
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("stores each fact with source_id pointing back to the raw memory", async () => {
+    const db = mockDb();
+    const llm = mockLlm('["Phil likes coffee", "Phil lives in London"]');
+    const ai = mockAi();
+
+    const result = await distill(db, ai, llm, "mem_raw_123", "...", {
+      clientId: "test",
+    });
+
+    expect(result.length).toBe(2);
+
+    // Find the INSERTs
+    const inserts = db.calls.filter((c) =>
+      c.sql.includes("INSERT INTO memory_nodes")
+    );
+    expect(inserts.length).toBe(2);
+
+    // Each INSERT should include source_id = 'mem_raw_123'
+    inserts.forEach((call) => {
+      expect(call.params).toContain("mem_raw_123");
+    });
+  });
+
+  it("skips when no semantic layer exists for client", async () => {
+    const db = async (sql) => {
+      if (sql.includes("FROM memory_layers")) return { rows: [] };
+      return { rows: [] };
+    };
+    db.calls = [];
+    const llm = mockLlm('["Phil likes tea"]');
+    const ai = mockAi();
+
+    const result = await distill(db, ai, llm, "mem_src", "content", {
+      clientId: "test",
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("continues storing remaining facts if one fails", async () => {
+    let insertCount = 0;
+    const db = async (sql, params) => {
+      if (sql.includes("FROM memory_layers")) {
+        return { rows: [{ id: "layer_sem" }] };
+      }
+      if (sql.includes("INSERT INTO memory_nodes")) {
+        insertCount++;
+        if (insertCount === 1) throw new Error("simulated db failure");
+      }
+      return { rows: [] };
+    };
+    const llm = mockLlm('["fact one", "fact two"]');
+    const ai = mockAi();
+
+    const result = await distill(db, ai, llm, "mem_src", "...", {
+      clientId: "test",
+    });
+
+    // First INSERT fails, second succeeds
+    expect(result.length).toBe(1);
+    expect(result[0].content).toBe("fact two");
+  });
+});

package/packages/memory/src/__tests__/openclaw-chat-turn.test.js

@@ -0,0 +1,289 @@
+import {
+  _resetTurnBuffersForTest,
+} from "../openclaw/index.js";
+import plugin from "../openclaw/index.js";
+
+const realFetch = globalThis.fetch;
+
+function captureFetch() {
+  const calls = [];
+  globalThis.fetch = async (url, init) => {
+    const body = init?.body ? JSON.parse(init.body) : null;
+    calls.push({ url, body });
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ data: { emitEvent: { eventId: "e", success: true } } }),
+    };
+  };
+  return calls;
+}
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  _resetTurnBuffersForTest();
+});
+
+// Build a working hosted engine via the plugin's register(api) hook.
+// The plugin uses api.registerContextEngine(name, factory) — the factory
+// is called once with no args and returns the engine object.
+function makeEngine() {
+  let factory;
+  plugin.register({
+    config: {
+      tes_endpoint: "https://x.test",
+      tes_client_id: "c",
+      tes_api_key: "tes_c_xyz",
+    },
+    registerTool: () => {},
+    registerContextEngine: (_name, fn) => {
+      factory = fn;
+    },
+  });
+  if (!factory) {
+    throw new Error("plugin did not register a context engine");
+  }
+  return factory();
+}
+
+describe("openclaw plugin — hosted CHAT_TURN emission", () => {
+  it("emits a CHAT_TURN when an assistant message follows a user message", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.ingest({
+      sessionId: "sess-1",
+      message: { role: "user", content: "hi" },
+    });
+    await engine.ingest({
+      sessionId: "sess-1",
+      message: {
+        role: "assistant",
+        content: "hello",
+        usage: { input_tokens: 12, output_tokens: 8 },
+        model: "claude-3-5",
+      },
+    });
+
+    const chatTurnCall = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    );
+    expect(chatTurnCall).toBeDefined();
+    const attrs = chatTurnCall.body.variables.input.data.attributes;
+    expect(attrs.user_message).toBe("hi");
+    expect(attrs.assistant_response).toBe("hello");
+    expect(attrs.model).toBe("claude-3-5");
+    expect(attrs.usage).toEqual({ input_tokens: 12, output_tokens: 8 });
+    expect(attrs.turn_number).toBe(1);
+    expect(attrs.source).toBe("openclaw-plugin");
+  });
+
+  it("still emits STORE_MEMORY events alongside CHAT_TURN (existing behaviour preserved)", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.ingest({
+      sessionId: "sess-2",
+      message: { role: "user", content: "a question" },
+    });
+    await engine.ingest({
+      sessionId: "sess-2",
+      message: { role: "assistant", content: "an answer" },
+    });
+
+    const storeMemoryCalls = calls.filter((c) => {
+      const m = c.body?.query;
+      return typeof m === "string" && m.includes("createModuleEvent");
+    });
+    expect(storeMemoryCalls.length).toBeGreaterThan(0);
+  });
+
+  it("omits usage and tool_calls when the message has no metadata", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+    await engine.ingest({
+      sessionId: "sess-3",
+      message: { role: "user", content: "hi" },
+    });
+    await engine.ingest({
+      sessionId: "sess-3",
+      message: { role: "assistant", content: "ok" },
+    });
+    const turnCall = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    );
+    expect("usage" in turnCall.body.variables.input.data.attributes).toBe(false);
+    expect("tool_calls" in turnCall.body.variables.input.data.attributes).toBe(
+      false
+    );
+  });
+
+  it("extracts tool_calls from a wrapped Anthropic raw response", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+    await engine.ingest({
+      sessionId: "sess-4",
+      message: { role: "user", content: "search" },
+    });
+    await engine.ingest({
+      sessionId: "sess-4",
+      message: {
+        role: "assistant",
+        content: "looking",
+        raw: {
+          content: [
+            { type: "text", text: "looking" },
+            { type: "tool_use", name: "search", input: { q: "shoes" } },
+          ],
+        },
+      },
+    });
+    const attrs = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    ).body.variables.input.data.attributes;
+    expect(attrs.tool_calls).toEqual([
+      { tool: "search", args: { q: "shoes" } },
+    ]);
+  });
+
+  it("increments turn_number per buffered user message in the same session", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+    for (let i = 0; i < 3; i++) {
+      await engine.ingest({
+        sessionId: "sess-5",
+        message: { role: "user", content: `q${i}` },
+      });
+      await engine.ingest({
+        sessionId: "sess-5",
+        message: { role: "assistant", content: `a${i}` },
+      });
+    }
+    const turns = calls.filter(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    );
+    expect(turns.map((t) => t.body.variables.input.data.attributes.turn_number)).toEqual(
+      [1, 2, 3]
+    );
+  });
+
+  it("emits even when assistant arrives with no buffered user message", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+    await engine.ingest({
+      sessionId: "sess-6",
+      message: { role: "assistant", content: "hi without prompt" },
+    });
+    const turn = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    );
+    expect(turn).toBeDefined();
+    expect(turn.body.variables.input.data.attributes.user_message).toBeUndefined();
+  });
+
+  // Regression: OpenClaw passes content as an array of content blocks
+  // (e.g. [{type: "text", text: "..."}]) rather than a plain string.
+  // The earlier String(message.content) approach produced "[object Object]"
+  // for every Telegram-sourced turn.
+  it("handles content-block arrays from the OpenClaw runtime", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    await engine.ingest({
+      sessionId: "sess-blocks",
+      message: {
+        role: "user",
+        content: [{ type: "text", text: "what food do i like?" }],
+      },
+    });
+    await engine.ingest({
+      sessionId: "sess-blocks",
+      message: {
+        role: "assistant",
+        content: [{ type: "text", text: "you like steak" }],
+      },
+    });
+
+    const attrs = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    ).body.variables.input.data.attributes;
+    expect(attrs.user_message).toBe("what food do i like?");
+    expect(attrs.assistant_response).toBe("you like steak");
+  });
+
+  // Regression: OpenClaw wraps real user messages from external channels
+  // (Telegram, etc.) in "Conversation info (untrusted metadata)" envelopes
+  // with JSON blocks + the actual user text appended. The emit should
+  // contain just the user's real words, not the JSON wrapper.
+  it("strips OpenClaw metadata envelopes from user messages", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    const envelope = [
+      "Conversation info (untrusted metadata):",
+      "```json",
+      JSON.stringify({ message_id: "42", sender: "Phil" }, null, 2),
+      "```",
+      "",
+      "remember that i love cheese",
+    ].join("\n");
+
+    await engine.ingest({
+      sessionId: "sess-envelope",
+      message: { role: "user", content: envelope },
+    });
+    await engine.ingest({
+      sessionId: "sess-envelope",
+      message: { role: "assistant", content: "noted" },
+    });
+
+    const attrs = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    ).body.variables.input.data.attributes;
+    expect(attrs.user_message).toBe("remember that i love cheese");
+  });
+
+  // Newer OpenClaw runtimes call afterTurn instead of ingest. The plugin
+  // should behave identically via both paths.
+  it("emits CHAT_TURN via afterTurn when the runtime uses that hook", async () => {
+    const calls = captureFetch();
+    const engine = makeEngine();
+
+    // Simulate afterTurn: messages is the full conversation, prePromptMessageCount
+    // is where the pre-turn history ended.
+    await engine.afterTurn({
+      sessionId: "sess-afterTurn",
+      messages: [
+        { role: "user", content: "hello" },
+        { role: "assistant", content: "hi there", model: "claude" },
+      ],
+      prePromptMessageCount: 0,
+    });
+
+    const turn = calls.find(
+      (c) =>
+        c.body?.variables?.moduleId === "conversation-analytics" &&
+        c.body?.variables?.input?.eventType === "CHAT_TURN"
+    );
+    expect(turn).toBeDefined();
+    const attrs = turn.body.variables.input.data.attributes;
+    expect(attrs.user_message).toBe("hello");
+    expect(attrs.assistant_response).toBe("hi there");
+    expect(attrs.model).toBe("claude");
+    expect(attrs.turn_number).toBe(1);
+  });
+});

package/packages/memory/src/distill.js

@@ -0,0 +1,162 @@
+/**
+ * Distilled memory — extract atomic facts from raw content.
+ *
+ * Each turn can contain multiple distinct facts. Distilling them into
+ * standalone atoms makes semantic retrieval more precise: searching for
+ * "what does Phil drink?" matches "Phil drinks cortado" better than a
+ * mixed paragraph covering food, drinks, and hobbies.
+ *
+ * Atoms are stored in the semantic layer with source_id pointing back
+ * to the raw memory in episodic.
+ */
+
+import { generateHypotheticalQueries } from "./ingest.js";
+
+const EXTRACTION_PROMPT = `You extract atomic facts from conversations.
+
+Rules:
+- Only extract facts the user has explicitly stated about themselves, their preferences, decisions, relationships, or world.
+- Each fact must be a single standalone statement (no "and", "or", no lists).
+- Decontextualize: replace "I" / "my" with the user's name or role if known, otherwise use "the user".
+- Reject questions, jokes, small talk, meta-discussion, and speculation.
+- Reject facts about the AI or the current task.
+- If nothing qualifies, return an empty array.
+
+Output a JSON array of strings. No explanation, no markdown fences. Just the JSON array.`;
+
+/**
+ * Extract atomic facts from content using the LLM.
+ *
+ * @param {object} llm - LLM client with chat() method
+ * @param {string} content - Raw content to distil
+ * @param {object} [opts]
+ * @param {string} [opts.userName] - User's name for decontextualization
+ * @returns {Promise<string[]>} Array of atomic fact strings
+ */
+export async function extractAtomicFacts(llm, content, opts = {}) {
+  const userHint = opts.userName
+    ? `\nThe user's name is ${opts.userName}.`
+    : "";
+  const text = await llm.chat(
+    [
+      { role: "system", content: EXTRACTION_PROMPT + userHint },
+      { role: "user", content: content.substring(0, 4000) },
+    ],
+    { maxTokens: 500, temperature: 0 }
+  );
+
+  if (!text) return [];
+
+  // Try to parse as JSON array. Be lenient about markdown fences.
+  let jsonText = text.trim();
+  const fenceMatch = jsonText.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+  if (fenceMatch) jsonText = fenceMatch[1].trim();
+
+  try {
+    const parsed = JSON.parse(jsonText);
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((f) => typeof f === "string" && f.trim().length > 0)
+      .map((f) => f.trim());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Distill a raw memory into atomic facts and store each as a separate
+ * memory node in the semantic layer, linked via source_id.
+ *
+ * Fire-and-forget: call this without awaiting to avoid blocking ingest.
+ *
+ * @param {Function} db - Database query function
+ * @param {object} ai - Embedding client
+ * @param {object} llm - Chat client for extraction + HyDE
+ * @param {string} sourceId - The raw memory ID this distillation derives from
+ * @param {string} content - The raw content
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} [opts.userId]
+ * @param {string} [opts.userName]
+ * @param {Function} [opts.logger]
+ * @returns {Promise<Array<{id: string, content: string}>>}
+ */
+export async function distill(db, ai, llm, sourceId, content, opts = {}) {
+  const clientId = opts.clientId;
+  const log = opts.logger || (() => {});
+
+  const facts = await extractAtomicFacts(llm, content, opts);
+  if (!facts.length) {
+    log(`distill: no facts extracted from ${sourceId}`);
+    return [];
+  }
+
+  // Resolve semantic layer ID (create the atoms there, not in episodic)
+  const layerResult = await db(
+    `SELECT id FROM memory_layers
+     WHERE client_id = $1 AND name = 'semantic' AND is_active = TRUE
+     LIMIT 1`,
+    [clientId]
+  );
+  if (!layerResult.rows?.length) {
+    log(`distill: no semantic layer for client ${clientId}`);
+    return [];
+  }
+  const layerId = layerResult.rows[0].id;
+
+  const stored = [];
+  for (const fact of facts) {
+    try {
+      const atomId = `mem_${crypto.randomUUID()}`;
+
+      // Insert the atom linked to its source
+      await db(
+        `INSERT INTO memory_nodes (id, client_id, layer_id, source_id, content, metadata, user_id, confidence, decay_rate, access_count)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, 1.0, 0.05, 0)`,
+        [
+          atomId,
+          clientId,
+          layerId,
+          sourceId,
+          fact,
+          JSON.stringify({ distilled_from: sourceId }),
+          opts.userId || null,
+        ]
+      );
+
+      // Embed the atom (non-fatal)
+      try {
+        const embResult = await ai.embed(fact, "passage");
+        if (embResult?.embedding) {
+          await db(
+            `UPDATE memory_nodes SET embedding = $1, updated_at = NOW() WHERE id = $2`,
+            [JSON.stringify(embResult.embedding), atomId]
+          );
+        }
+      } catch (err) {
+        log(`distill: embedding failed for ${atomId}: ${err.message}`);
+      }
+
+      // HyDE (2 queries for atoms — they're already focused)
+      try {
+        const queries = await generateHypotheticalQueries(llm, fact);
+        const trimmed = queries.slice(0, 2);
+        if (trimmed.length) {
+          await db(
+            `UPDATE memory_nodes SET metadata = jsonb_set(COALESCE(metadata, '{}')::jsonb, '{hypothetical_queries}', $1::jsonb), updated_at = NOW() WHERE id = $2`,
+            [JSON.stringify(trimmed), atomId]
+          );
+        }
+      } catch (err) {
+        log(`distill: HyDE failed for ${atomId}: ${err.message}`);
+      }
+
+      stored.push({ id: atomId, content: fact });
+    } catch (err) {
+      log(`distill: failed to store fact "${fact.substring(0, 40)}": ${err.message}`);
+    }
+  }
+
+  log(`distill: ${stored.length}/${facts.length} atoms stored from ${sourceId}`);
+  return stored;
+}

package/packages/memory/src/index.js

@@ -128,6 +128,7 @@ function normalizeDb(db, schema) {
 export { createAIClient } from "./ai.js";
 export { search, textSearch } from "./search.js";
 export { ingest, generateHypotheticalQueries } from "./ingest.js";
+export { distill, extractAtomicFacts } from "./distill.js";
 export { decay } from "./decay.js";
 export { consolidate } from "./consolidate.js";
 export { ensureLayers, getLayers } from "./layers.js";

package/packages/memory/src/ingest.js

@@ -2,6 +2,8 @@
  * Memory ingestion — store content, generate embedding, generate HyDE queries.
  */
 
+import { distill } from "./distill.js";
+
 /**
  * Ingest content as a new memory node.
  *
@@ -81,6 +83,14 @@ export async function ingest(db, ai, llm, content, opts = {}) {
     log(`HyDE failed for ${memoryId}: ${err.message}`);
   }
 
+  // Distill atomic facts in the background — only for raw ingestions
+  // (skip if this call is already storing a distilled atom or user opted out).
+  if (opts.distill !== false && !opts.sourceId) {
+    distill(db, ai, llm, memoryId, content, { ...opts, logger: log }).catch(
+      (err) => log(`distill failed for ${memoryId}: ${err.message}`)
+    );
+  }
+
   return { id: memoryId, content, layerId };
 }