@pentatonic-ai/ai-agent-sdk 0.5.3 → 0.5.4

package/README.md

@@ -73,6 +73,8 @@ That's it. The plugin hooks automatically search memories on every prompt and st
 - **Distilled memory** -- a background LLM pass extracts atomic facts from each raw turn and stores each as its own node in the semantic layer, linked back to the source. A query like *"what does Phil drink?"* matches *"Phil drinks cortado"* more reliably than a mixed paragraph covering food, drinks, and hobbies. Default-on; the raw turn is still preserved.
 - **Decay and consolidation** -- memories fade over time; frequently accessed ones get promoted
 
+> **Store latency note (v0.5.4+):** on the local memory server, `store_memory` now awaits distillation before returning instead of running it fire-and-forget. This fixed a bug where distillation was being killed mid-flight (atoms never got embeddings, so they were unreachable by semantic search), but it means stores now take as long as your configured LLM takes to produce atoms — typically 5–30s on `llama3.2:3b`, up to the `chat()` timeout ceiling (60s default, overridable via `opts.timeout`). Cloudflare Worker deployments pass `ctx.waitUntil` and still return fast. Set `opts.distill: false` on the ingest call if you want the old fast-return behaviour at the cost of no atoms.
+
 ### Change models
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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",

package/packages/memory/src/__tests__/api-contract.test.js

@@ -366,6 +366,97 @@ describe("search options contract", () => {
     const out = await search(mockDb, mockAi, "q", { clientId: "c", minScore: 0 });
     expect(out[0].source_id).toBe("raw-1");
   });
+
+  it("hydrateAtomSources: true fetches and appends source raws for matched atoms", async () => {
+    const matchedRows = [
+      { id: "atom-1", client_id: "c", layer_id: "l", content: "Caroline went to support group",
+        confidence: 1, decay_rate: 0.05, access_count: 0, final_score: 0.9, source_id: "raw-1" },
+    ];
+    const hydratedRaw = {
+      id: "raw-1", client_id: "c", layer_id: "l", source_id: null,
+      content: "[Date: 8 May 2023] Caroline: I went to the LGBTQ support group...",
+      confidence: 1, decay_rate: 0.05, access_count: 0,
+    };
+    const mockDb = async (sql, params) => {
+      if (sql.includes("information_schema.columns")) return { rows: [{ "?column?": 1 }] };
+      if (sql.includes("final_score")) return { rows: matchedRows };
+      if (sql.includes("id = ANY") && Array.isArray(params?.[0]) && params[0].includes("raw-1")) {
+        return { rows: [hydratedRaw] };
+      }
+      return { rows: [] };
+    };
+    const mockAi = { embed: async () => ({ embedding: [0.1], dimensions: 1, model: "t" }) };
+
+    const out = await search(mockDb, mockAi, "q", {
+      clientId: "c",
+      minScore: 0,
+      dedupeBySource: false,
+      hydrateAtomSources: true,
+    });
+
+    expect(out.length).toBe(2);
+    expect(out.map((r) => r.id).sort()).toEqual(["atom-1", "raw-1"]);
+    const raw = out.find((r) => r.id === "raw-1");
+    expect(raw.content).toContain("8 May 2023");
+  });
+
+  it("hydrateAtomSources: false is a no-op (default)", async () => {
+    const rows = [
+      { id: "atom-1", client_id: "c", layer_id: "l", content: "atom",
+        confidence: 1, decay_rate: 0.05, access_count: 0, final_score: 0.9, source_id: "raw-1" },
+    ];
+    let hydrateCalled = false;
+    const mockDb = async (sql) => {
+      if (sql.includes("information_schema.columns")) return { rows: [{ "?column?": 1 }] };
+      if (sql.includes("final_score")) return { rows };
+      if (sql.includes("SELECT * FROM memory_nodes WHERE id = ANY")) {
+        hydrateCalled = true;
+        return { rows: [] };
+      }
+      return { rows: [] };
+    };
+    const mockAi = { embed: async () => ({ embedding: [0.1], dimensions: 1, model: "t" }) };
+
+    await search(mockDb, mockAi, "q", {
+      clientId: "c",
+      minScore: 0,
+      dedupeBySource: false,
+    });
+
+    expect(hydrateCalled).toBe(false);
+  });
+});
+
+describe("ingest default behavior", () => {
+  it("awaits distill when no waitUntil is passed (fixes fire-and-forget in local dev)", async () => {
+    let distillStarted = false;
+    let distillFinished = false;
+    const mockDb = async (sql) => {
+      if (sql.includes("SELECT id FROM memory_layers")) {
+        return { rows: [{ id: "layer-1" }] };
+      }
+      return { rows: [] };
+    };
+    const mockAi = { embed: async () => null };
+    const mockLlm = {
+      chat: async () => {
+        distillStarted = true;
+        // Simulate LLM latency
+        await new Promise((r) => setTimeout(r, 20));
+        distillFinished = true;
+        return "[]";
+      },
+    };
+
+    await ingest(mockDb, mockAi, mockLlm, "some content", {
+      clientId: "c",
+      // no waitUntil — distill must be awaited inline
+    });
+
+    // After ingest returns, distill must have finished
+    expect(distillStarted).toBe(true);
+    expect(distillFinished).toBe(true);
+  });
 });
 
 // --- Ingest options contract ---

package/packages/memory/src/ai.js

@@ -89,6 +89,9 @@ export function createAIClient(config) {
      * @param {object} [opts]
      * @param {number} [opts.maxTokens=150]
      * @param {number} [opts.temperature=0.7]
+     * @param {number} [opts.timeout=60000] - Defaults 60s. Longer chunks +
+     *   smaller/local models routinely exceed 15s; 60s keeps distill/HyDE
+     *   reliable on prod-class content without catching genuine hangs.
      * @returns {Promise<string>} The assistant's response text
      */
     async chat(messages, opts = {}) {
@@ -102,7 +105,7 @@ export function createAIClient(config) {
             max_tokens: opts.maxTokens || 150,
             temperature: opts.temperature ?? 0.7,
           }),
-          signal: AbortSignal.timeout(opts.timeout || 15000),
+          signal: AbortSignal.timeout(opts.timeout || 60000),
         });
 
         if (!res.ok) return "";

package/packages/memory/src/ingest.js

@@ -87,14 +87,20 @@ 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).
+  // Distill atomic facts — only for raw ingestions (skip if this call is
+  // already storing a distilled atom or user opted out).
+  //
+  // On Cloudflare Workers: caller passes `waitUntil` so distill runs past
+  // the handler return (without waitUntil the runtime kills unreferenced
+  // promises). On Node / local dev / test: we await inline so distill
+  // actually completes before ingest() returns.
   if (opts.distill !== false && !opts.sourceId) {
     const distillPromise = distill(db, ai, llm, memoryId, content, {
       ...opts,
       logger: log,
     }).catch((err) => log(`distill failed for ${memoryId}: ${err.message}`));
     if (typeof opts.waitUntil === "function") opts.waitUntil(distillPromise);
+    else await distillPromise;
   }
 
   return { id: memoryId, content, layerId };

package/packages/memory/src/search.js

@@ -34,6 +34,11 @@ const DEFAULT_WEIGHTS = {
  * @param {boolean} [opts.dedupeBySource=true] - When an atom matches,
  *   drop its raw source memory from the results (atoms are already
  *   distillations of the source, so returning both is redundant).
+ * @param {boolean} [opts.hydrateAtomSources=false] - Opt-in. For each
+ *   matched atom, also fetch its source raw by id and append to results
+ *   (deduped by id). Useful when downstream needs full-detail context
+ *   (dates, names, quotes) that atoms decontextualize away. Not
+ *   meaningful when dedupeBySource is also on.
  * @param {Function} [opts.logger] - Optional logger
  * @returns {Promise<Array>} Scored memory results
  */
@@ -159,6 +164,28 @@ export async function search(db, ai, query, opts = {}) {
     }
   }
 
+  // Hydrate: for each matched atom, also fetch and append its source raw
+  // (deduped by id). Atoms often drop specifics (dates, names); surfacing
+  // the raw gives the LLM consumer full context alongside the focused atom.
+  // Opt-in via opts.hydrateAtomSources. Not meaningful with dedupeBySource.
+  if (opts.hydrateAtomSources === true) {
+    const existingIds = new Set(filtered.map((r) => r.id));
+    const missingSourceIds = [
+      ...new Set(
+        filtered
+          .filter((r) => r.source_id && !existingIds.has(r.source_id))
+          .map((r) => r.source_id)
+      ),
+    ];
+    if (missingSourceIds.length > 0) {
+      const hydrated = await db(
+        `SELECT * FROM memory_nodes WHERE id = ANY($1)`,
+        [missingSourceIds]
+      );
+      filtered = filtered.concat(hydrated.rows || []);
+    }
+  }
+
   // Increment access counts
   const ids = filtered.map((r) => r.id);
   if (ids.length) {

package/packages/memory/src/server.js

@@ -347,7 +347,7 @@ async function main() {
         const health = {
           status: "ok",
           client: CLIENT_ID,
-          version: "0.5.3",
+          version: "0.5.4",
           search: "text",
           db: false,
           ollama: false,