@theokit/sdk 4.61.0 → 4.62.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 4.62.0
+
+### Minor Changes
+
+- 36bb21f: Memory recall is scored with BM25 instead of Jaccard, and rank fusion is damped for stores of
+  tens rather than hundreds.
+
+  **What changes for you:** which memories are selected when several are plausible. The store, the
+  budget and the API are unchanged; the ordering is not.
+
+  Measured on LongMemEval-S — 500 questions, 54 sessions each — through a public eval harness, with
+  its tokenised-substring `grep` adapter as the floor:
+
+  |                         | hit@5     | P@5       | R@5       | p50      |
+  | ----------------------- | --------- | --------- | --------- | -------- |
+  | Jaccard (4.61.0)        | 80.0%     | 0.236     | 0.670     | 205ms    |
+  | `grep` (floor)          | 89.0%     | 0.295     | 0.807     | 2ms      |
+  | **BM25 (this release)** | **96.8%** | **0.329** | **0.904** | **20ms** |
+
+  Jaccard lost to a naive substring match. The mechanism was isolated before it was fixed: on a
+  preference query, the term that discriminates appeared in 2 of 15 documents while a noise term
+  appeared in 14 — and Jaccard weighted them identically. Almost every document scored above zero,
+  fusion flattened what ordering remained, and recency decided a relevance question. IDF is the
+  whole fix, and the gain concentrates where that predicts:
+
+  ```
+  single-session-preference   46.7% -> 86.7%   (+40.0)
+  single-session-assistant    89.3% -> 100.0%  (+10.7)
+  temporal-reasoning          85.7% ->  96.2%  (+10.5)
+  multi-session               94.7% ->  96.2%   (+1.5)
+  ```
+
+  Also **10x faster**: the previous implementation called its scoring function from inside sort
+  comparators, re-tokenising every fact O(n log n) times per query.
+
+  Rank fusion damping moves from k = 60 to k = 5. Swept rather than chosen — the 500-question corpus
+  is insensitive to k once terms are IDF-weighted, while a 15-session corpus goes from 14/15 to
+  15/15. The sweep cannot separate 5 from 1, so the tie is broken on the principle that at k = 1
+  damping is nearly gone and fusion stops fusing.
+
+  **This improves the reliability of memory poisoning as well as of recall**, and the two cannot be
+  separated: the property that makes a planted entry work is the property that makes a real one
+  useful. See the accompanying patch note for the re-measured figures.
+
+### Patch Changes
+
+- Corrects a security figure published with 4.61.0, and adds the rule that produced the error.
+
+  The 4.61.0 notes said a planted memory entry made the agent perform the action it described in
+  **2 of 6 runs**. Re-measured against the published 4.61.0 itself, it is **6 of 6**. Registering
+  the permission engine still blocks it — 6 of 6, with zero errors.
+
+  The old figure was not a smaller version of the same risk; it was a measurement of a different
+  thing. It was taken against a retrieval path that did not recall the planted entry at all: on
+  4.60.0 the agent answered "Done." and never saw it, while on 4.61.0 it recites the entry
+  verbatim. Nothing about the attack changed between those runs — the recall path did.
+
+  **A poisoning rate measured against a retrieval path that does not recall the plant is a
+  measurement of how often the attack reached the model, not of how often the model resisted it.**
+  Any such figure has to record whether the plant was recalled, or it cannot be compared across
+  versions.
+
+  The consequence for anyone depending on this: improving recall is a change to the threat model,
+  not something orthogonal to it. The property that makes a planted memory work is the property
+  that makes a real one useful. **If anything other than your agent's own deliberate writes can
+  reach the memory directory, register the permission engine.**
+
+  Separately, the original proof constructed the engine as `new PermissionEngine({ rules: [] })`.
+  The constructor takes the rules positionally, so that was never a rule list, and nothing checked
+  because the script was JavaScript. A crash inside the engine and a gated call produce the same
+  observation. Re-run in TypeScript with `new PermissionEngine([])`, it gates: 6 of 6 blocked, 0
+  runs threw.
+
 ## 4.61.0
 
 ### Minor Changes

package/dist/{agent-P42GA6RM.js → agent-NVBFTY5H.js}

@@ -1,4 +1,4 @@
-export { Agent } from './chunk-GQZKDGZM.js';
+export { Agent } from './chunk-SKOCYA55.js';
 import './chunk-SUKXXLWD.js';
 import './chunk-YEXA3PGR.js';
 import './chunk-K2BQQ445.js';
@@ -51,5 +51,5 @@ import './chunk-3OR54XG4.js';
 import './chunk-IDCKSLYH.js';
 import './chunk-T7XEKOVW.js';
 import './chunk-T7O6K6PX.js';
-//# sourceMappingURL=agent-P42GA6RM.js.map
-//# sourceMappingURL=agent-P42GA6RM.js.map
+//# sourceMappingURL=agent-NVBFTY5H.js.map
+//# sourceMappingURL=agent-NVBFTY5H.js.map

package/dist/{agent-P42GA6RM.js.map → agent-NVBFTY5H.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-P42GA6RM.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-NVBFTY5H.js"}

package/dist/{agent-M53C3PAA.cjs → agent-VYPUO4UB.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkR7YIVL3K_cjs = require('./chunk-R7YIVL3K.cjs');
+var chunkAH6WD7JR_cjs = require('./chunk-AH6WD7JR.cjs');
 require('./chunk-NGESVVJN.cjs');
 require('./chunk-2DG7KW4L.cjs');
 require('./chunk-BUUUWQMB.cjs');
@@ -58,7 +58,7 @@ require('./chunk-NUKRL3I6.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkR7YIVL3K_cjs.Agent; }
+  get: function () { return chunkAH6WD7JR_cjs.Agent; }
 });
-//# sourceMappingURL=agent-M53C3PAA.cjs.map
-//# sourceMappingURL=agent-M53C3PAA.cjs.map
+//# sourceMappingURL=agent-VYPUO4UB.cjs.map
+//# sourceMappingURL=agent-VYPUO4UB.cjs.map

package/dist/{agent-M53C3PAA.cjs.map → agent-VYPUO4UB.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-M53C3PAA.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-VYPUO4UB.cjs"}

package/dist/{chunk-R7YIVL3K.cjs → chunk-AH6WD7JR.cjs}

@@ -3439,7 +3439,7 @@ var HISTOGRAM_NAMES = {
 };
 function safeRequire(moduleName) {
   try {
-    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-R7YIVL3K.cjs', document.baseURI).href)));
+    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-AH6WD7JR.cjs', document.baseURI).href)));
     return r(moduleName);
   } catch {
     return void 0;
@@ -3667,7 +3667,7 @@ var cachedOtel;
 function loadOtel() {
   if (cachedOtel === void 0) {
     try {
-      const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-R7YIVL3K.cjs', document.baseURI).href)));
+      const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-AH6WD7JR.cjs', document.baseURI).href)));
       const mod = r("@opentelemetry/api");
       cachedOtel = mod;
     } catch {
@@ -9139,17 +9139,7 @@ function terms(text) {
     text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 3 && !STOPWORDS.has(w))
   );
 }
-function relevance(fact, queryTerms) {
-  if (queryTerms.size === 0) return 0;
-  const factTerms = terms(fact.text);
-  if (factTerms.size === 0) return 0;
-  let shared = 0;
-  for (const w of queryTerms) if (factTerms.has(w)) shared += 1;
-  if (shared === 0) return 0;
-  const union = (/* @__PURE__ */ new Set([...queryTerms, ...factTerms])).size;
-  return shared / union;
-}
-var RRF_K = 60;
+var RRF_K = 5;
 function corroborationRank(fact) {
   if (fact.observations === void 0) return 1;
   return fact.observations > 1 ? 2 : 0;
@@ -9157,13 +9147,55 @@ function corroborationRank(fact) {
 function sortByCorroboration(facts) {
   return [...facts].sort((a, b) => corroborationRank(b) - corroborationRank(a));
 }
-function rankForQuery(facts, queryTerms) {
-  const scored = facts.map((f) => ({ f, score: relevance(f, queryTerms) }));
-  const matching = scored.filter((s) => s.score > 0).map((s) => s.f);
-  const rest = scored.filter((s) => s.score === 0).map((s) => s.f);
-  const byRelevance = [...matching].sort(
-    (a, b) => relevance(b, queryTerms) - relevance(a, queryTerms)
-  );
+var BM25_K1 = 1.2;
+var BM25_B = 0.75;
+function docTerms(text) {
+  const counts = /* @__PURE__ */ new Map();
+  let length = 0;
+  for (const w of text.toLowerCase().split(/[^a-z0-9]+/).filter((x) => x.length >= 3 && !STOPWORDS.has(x))) {
+    counts.set(w, (counts.get(w) ?? 0) + 1);
+    length += 1;
+  }
+  return { counts, length };
+}
+function documentFrequencies(docs, queryTerms) {
+  const df = /* @__PURE__ */ new Map();
+  for (const term of queryTerms) {
+    let count = 0;
+    for (const d of docs) if (d.terms.counts.has(term)) count += 1;
+    df.set(term, count);
+  }
+  return df;
+}
+function scoreDoc(doc, queryTerms, df, n, avgLength) {
+  let score = 0;
+  for (const term of queryTerms) {
+    const tf = doc.terms.counts.get(term);
+    if (tf === void 0) continue;
+    const frequency = df.get(term) ?? 0;
+    const idf = Math.log(1 + (n - frequency + 0.5) / (frequency + 0.5));
+    const norm = tf + BM25_K1 * (1 - BM25_B + BM25_B * doc.terms.length / avgLength);
+    score += idf * (tf * (BM25_K1 + 1)) / norm;
+  }
+  return score;
+}
+function bm25Scores(facts, queryTerms) {
+  const scores = /* @__PURE__ */ new Map();
+  if (queryTerms.size === 0 || facts.length === 0) return scores;
+  const docs = facts.map((f) => ({ fact: f, terms: docTerms(f.text) }));
+  const n = docs.length;
+  const avgLength = docs.reduce((sum, d) => sum + d.terms.length, 0) / n || 1;
+  const df = documentFrequencies(docs, queryTerms);
+  for (const d of docs) {
+    const score = scoreDoc(d, queryTerms, df, n, avgLength);
+    if (score > 0) scores.set(d.fact, score);
+  }
+  return scores;
+}
+function rankForQuery(facts, scores) {
+  const matching = facts.filter((f) => (scores.get(f) ?? 0) > 0);
+  const rest = facts.filter((f) => (scores.get(f) ?? 0) <= 0);
+  const byRelevance = [...matching].sort((a, b) => (scores.get(b) ?? 0) - (scores.get(a) ?? 0));
   const byRecency = [...matching].sort(
     (a, b) => (b.modified ?? "").localeCompare(a.modified ?? "")
   );
@@ -9191,9 +9223,10 @@ function rankBuckets(facts, query) {
     dated.sort((a, b) => b.modified.localeCompare(a.modified));
     return { dated, undated };
   }
+  const scores = bm25Scores(facts, queryTerms);
   return {
-    dated: rankForQuery(dated, queryTerms),
-    undated: [...undated].sort((a, b) => relevance(b, queryTerms) - relevance(a, queryTerms))
+    dated: rankForQuery(dated, scores),
+    undated: [...undated].sort((a, b) => (scores.get(b) ?? 0) - (scores.get(a) ?? 0))
   };
 }
 function selectFactsForInjection(facts, options = {}) {
@@ -10755,5 +10788,5 @@ exports.computeCost = computeCost;
 exports.generateCronId = generateCronId;
 exports.getPricingEntry = getPricingEntry;
 exports.openRouterMemoryEmbeddingProviderAdapter = openRouterMemoryEmbeddingProviderAdapter;
-//# sourceMappingURL=chunk-R7YIVL3K.cjs.map
-//# sourceMappingURL=chunk-R7YIVL3K.cjs.map
+//# sourceMappingURL=chunk-AH6WD7JR.cjs.map
+//# sourceMappingURL=chunk-AH6WD7JR.cjs.map