@pentatonic-ai/ai-agent-sdk 0.5.2 → 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.2",
+  "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

@@ -283,6 +283,180 @@ describe("search options contract", () => {
 
     expect(Array.isArray(results)).toBe(true);
   });
+
+  it("SQL includes atomBoost and verbosityPenalty terms", async () => {
+    const seenSqls = [];
+    const mockDb = async (sql) => {
+      seenSqls.push(sql);
+      if (sql.includes("information_schema.columns")) return { rows: [{ "?column?": 1 }] };
+      return { rows: [] };
+    };
+    const mockAi = { embed: async () => ({ embedding: [0.1], dimensions: 1, model: "t" }) };
+
+    await search(mockDb, mockAi, "q", { clientId: "c" });
+
+    const scoringSql = seenSqls.find((s) => s.includes("final_score"));
+    expect(scoringSql).toBeDefined();
+    expect(scoringSql).toMatch(/source_id IS NOT NULL/);
+    expect(scoringSql).toMatch(/length\(mn\.content\)/);
+  });
+
+  it("dedupeBySource drops raw rows whose id is a source of a matched atom", async () => {
+    const rows = [
+      { id: "raw-1", client_id: "c", layer_id: "l", content: "long raw turn",
+        confidence: 1, decay_rate: 0.05, access_count: 0, final_score: 0.9, source_id: null },
+      { id: "atom-1", client_id: "c", layer_id: "l", content: "Phil owns a Subaru",
+        confidence: 1, decay_rate: 0.05, access_count: 0, final_score: 0.8, source_id: "raw-1" },
+    ];
+    let searchCallCount = 0;
+    const mockDb = async (sql) => {
+      if (sql.includes("information_schema.columns")) return { rows: [{ "?column?": 1 }] };
+      if (sql.includes("final_score")) {
+        searchCallCount++;
+        return { rows };
+      }
+      return { rows: [] };
+    };
+    const mockAi = { embed: async () => ({ embedding: [0.1], dimensions: 1, model: "t" }) };
+
+    const out = await search(mockDb, mockAi, "q", { clientId: "c", minScore: 0 });
+
+    expect(searchCallCount).toBe(1);
+    expect(out.length).toBe(1);
+    expect(out[0].id).toBe("atom-1");
+    expect(out[0].source_id).toBe("raw-1");
+  });
+
+  it("dedupeBySource: false keeps both atom and its raw source", async () => {
+    const rows = [
+      { id: "raw-1", client_id: "c", layer_id: "l", content: "long",
+        confidence: 1, decay_rate: 0.05, access_count: 0, final_score: 0.9, source_id: null },
+      { id: "atom-1", client_id: "c", layer_id: "l", content: "short",
+        confidence: 1, decay_rate: 0.05, access_count: 0, final_score: 0.8, source_id: "raw-1" },
+    ];
+    const mockDb = async (sql) => {
+      if (sql.includes("information_schema.columns")) return { rows: [{ "?column?": 1 }] };
+      if (sql.includes("final_score")) return { rows };
+      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,
+    });
+
+    expect(out.length).toBe(2);
+    expect(out.map((r) => r.id).sort()).toEqual(["atom-1", "raw-1"]);
+  });
+
+  it("search results include source_id (null for raw, set for atoms)", 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" },
+    ];
+    const mockDb = async (sql) => {
+      if (sql.includes("information_schema.columns")) return { rows: [{ "?column?": 1 }] };
+      if (sql.includes("final_score")) return { rows };
+      return { rows: [] };
+    };
+    const mockAi = { embed: async () => ({ embedding: [0.1], dimensions: 1, model: "t" }) };
+
+    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

@@ -10,6 +10,11 @@ const DEFAULT_WEIGHTS = {
   relevance: 0.6,
   recency: 0.25,
   frequency: 0.15,
+  // Boost distilled atoms — they're high signal per token by design.
+  atomBoost: 0.15,
+  // Penalty on verbose raw turns. Short focused memories rank higher.
+  // Atoms are exempt (penalty skipped when source_id IS NOT NULL).
+  verbosityPenalty: 0.1,
 };
 
 /**
@@ -25,6 +30,15 @@ const DEFAULT_WEIGHTS = {
  * @param {number} [opts.minScore=0.5] - Minimum score threshold
  * @param {string} [opts.userId] - Optional user scope
  * @param {object} [opts.weights] - Override scoring weights
+ *   (relevance, recency, frequency, atomBoost, verbosityPenalty)
+ * @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
  */
@@ -107,7 +121,19 @@ export async function search(db, ai, query, opts = {}) {
         ${w.recency} * exp(
           -0.01 * EXTRACT(EPOCH FROM NOW() - COALESCE(mn.last_accessed, mn.created_at)) / 3600
         ) +
-        ${w.frequency} * (ln(mn.access_count + 1) / ln(ma.val + 1))
+        ${w.frequency} * (ln(mn.access_count + 1) / ln(ma.val + 1)) +
+        ${w.atomBoost} * (CASE WHEN mn.source_id IS NOT NULL THEN 1 ELSE 0 END) -
+        ${w.verbosityPenalty} * (
+          CASE WHEN mn.source_id IS NULL THEN
+            LEAST(
+              GREATEST(
+                (ln(length(mn.content) + 1) - ln(200)) / (ln(10000) - ln(200)),
+                0
+              ),
+              1
+            )
+          ELSE 0 END
+        )
       ) AS final_score
     FROM memory_nodes mn
     CROSS JOIN max_ac ma
@@ -123,10 +149,43 @@ export async function search(db, ai, query, opts = {}) {
 
   const result = await db(sql, params);
 
-  const filtered = (result.rows || []).filter(
+  let filtered = (result.rows || []).filter(
     (r) => parseFloat(r.final_score) >= threshold
   );
 
+  // De-dupe: when an atom matches, drop its raw source from the set.
+  // Default on; set opts.dedupeBySource: false to keep both.
+  if (opts.dedupeBySource !== false) {
+    const atomSources = new Set(
+      filtered.filter((r) => r.source_id).map((r) => r.source_id)
+    );
+    if (atomSources.size > 0) {
+      filtered = filtered.filter((r) => !atomSources.has(r.id));
+    }
+  }
+
+  // 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) {
@@ -182,6 +241,7 @@ function mapRow(row) {
     client_id: row.client_id,
     user_id: row.user_id || null,
     layer_id: row.layer_id,
+    source_id: row.source_id || null,
     content: row.content,
     metadata:
       typeof row.metadata === "string"

package/packages/memory/src/server.js

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