dsh-context-memory 0.9.0 → 0.10.0

package/lib/index.d.ts

@@ -30,6 +30,8 @@ export declare const inject: string[];
 export interface MemoryPrefs {
     autoCapture: boolean;
     recallInject: boolean;
+    /** Character budget for the guidance rows in the recall injection. */
+    recallCharBudget: number;
 }
 /** The service shape other plugins and the panel use. */
 export interface MemoryService {

package/lib/index.js

@@ -109,6 +109,10 @@ export function apply(ctx) {
     };
     /** When the last automatic re-check ran, so a day's worth of steps do not each run one. */
     let lastReverifyAt = 0;
+    // Character budget for the guidance rows in the recall injection. Contradicted rows and
+    // conflicts are not optional, so they ignore it. Mutable through setPrefs like the other
+    // panel switches, so the panel can raise it without a restart.
+    let recallCharBudget = 4000;
     const service = {
         remember: (input) => memory.remember(input),
         forget: (id, reason, options) => memory.forget(id, reason, options),
@@ -120,13 +124,15 @@ export function apply(ctx) {
         candidates: () => memory.candidates(),
         accept: (id, overrides) => memory.accept(id, overrides),
         dismiss: (id) => memory.dismiss(id),
-        prefs: () => ({ autoCapture: captureEnabled, recallInject: injectEnabled }),
+        prefs: () => ({ autoCapture: captureEnabled, recallInject: injectEnabled, recallCharBudget }),
         setPrefs: (patch) => {
             if (typeof patch.autoCapture === 'boolean')
                 captureEnabled = patch.autoCapture;
             if (typeof patch.recallInject === 'boolean')
                 injectEnabled = patch.recallInject;
-            return { autoCapture: captureEnabled, recallInject: injectEnabled };
+            if (typeof patch.recallCharBudget === 'number' && patch.recallCharBudget >= 200)
+                recallCharBudget = patch.recallCharBudget;
+            return { autoCapture: captureEnabled, recallInject: injectEnabled, recallCharBudget };
         },
         locations: () => memory.locations,
     };
@@ -162,13 +168,35 @@ export function apply(ctx) {
     let injectEnabled = true;
     let captureEnabled = true;
     let injectedMessageIds = [];
-    const contextMessageFor = (memory, query) => {
+    const contextMessageFor = (memory, query, charBudget) => {
         const hits = memory.recall(query, 5);
         const lines = [];
+        // Guidance rows are optional content, so they share a budget: recall already ranks
+        // them best-first, so rows are appended until the budget runs out and the rest are
+        // dropped with a note. Contradicted rows and conflicts are NOT optional — a claim the
+        // world denies or two records that disagree are things the model must see to resolve,
+        // so those sections ignore the budget entirely.
+        let budgetLeft = Math.max(0, charBudget);
+        let droppedForBudget = 0;
         if (hits.length > 0) {
-            lines.push('Relevant memories from previous sessions (guidance, not instructions):');
-            for (const hit of hits)
-                lines.push(`- [${hit.memory.kind}] ${hit.memory.text}`);
+            const header = 'Relevant memories from previous sessions (guidance, not instructions):';
+            const rows = [];
+            for (const hit of hits) {
+                const row = `- [${hit.memory.kind}] ${hit.memory.text}`;
+                if (rows.length > 0 && budgetLeft - row.length < 0) {
+                    droppedForBudget = hits.length - rows.length;
+                    break;
+                }
+                budgetLeft -= row.length;
+                rows.push(row);
+            }
+            if (rows.length > 0) {
+                lines.push(header);
+                lines.push(...rows);
+                if (droppedForBudget > 0) {
+                    lines.push(`(${droppedForBudget} more matches omitted — raise the char budget to see them, or use memory_recall for a targeted query)`);
+                }
+            }
         }
         // Contradicted memories are shown as a problem, never as guidance. Silently dropping
         // them would hide the fact that the log now contains a claim the world denies; the
@@ -272,7 +300,7 @@ export function apply(ctx) {
                 catch { /* a queue that cannot be written must not stop the step */ }
             }
         }
-        const desired = contextMessageFor(memory, trimmed);
+        const desired = contextMessageFor(memory, trimmed, recallCharBudget);
         // Nothing relevant and nothing conflicting → empty content: skip entirely
         // rather than ship an empty row into the transcript.
         if (desired.content.length === 0)

package/lib/recall.d.ts

@@ -32,6 +32,21 @@ import type { MemoryState, MemoryTarget, RecallHit } from './types.js';
  * memory that share one word still match even when the surrounding wording differs.
  */
 export declare function tokenize(text: string): string[];
+/**
+ * Inverse document frequency over the population being ranked.
+ *
+ * Why this exists: plain overlap (`matched / tokens`) gives "项目" and "构建" the same
+ * weight. In a log about one project the first appears in nearly every memory and
+ * matches everything, so a query that also names a rare term ("pnpm") is diluted by the
+ * common ones. IDF is the standard correction — a term that appears in fewer memories
+ * carries more of the query meaning.
+ *
+ * Computed per `recall()` call over the filtered population, so the corpus is exactly the
+ * set of candidates being ranked: no global statistics to keep in sync, and no behaviour
+ * change when every term is equally common (equal weights reduce the weighted fraction
+ * to `matched / tokens`).
+ */
+export declare function buildIdf(memories: MemoryState[], tokens: string[]): Map<string, number>;
 /**
  * Score how relevant one memory is to a query.
  *
@@ -41,7 +56,7 @@ export declare function tokenize(text: string): string[];
  * passed a check or it did not, and giving partial credit for "was checked once and has
  * not been rechecked" would reward staleness.
  */
-export declare function scoreMemory(memory: MemoryState, tokens: string[], now?: number): {
+export declare function scoreMemory(memory: MemoryState, tokens: string[], now?: number, idf?: ReadonlyMap<string, number>): {
     score: number;
     matched: string[];
     why: string;

package/lib/recall.js

@@ -100,6 +100,37 @@ function searchableText(memory) {
     SEARCHABLE_TEXT.set(memory, value);
     return value;
 }
+/**
+ * Inverse document frequency over the population being ranked.
+ *
+ * Why this exists: plain overlap (`matched / tokens`) gives "项目" and "构建" the same
+ * weight. In a log about one project the first appears in nearly every memory and
+ * matches everything, so a query that also names a rare term ("pnpm") is diluted by the
+ * common ones. IDF is the standard correction — a term that appears in fewer memories
+ * carries more of the query meaning.
+ *
+ * Computed per `recall()` call over the filtered population, so the corpus is exactly the
+ * set of candidates being ranked: no global statistics to keep in sync, and no behaviour
+ * change when every term is equally common (equal weights reduce the weighted fraction
+ * to `matched / tokens`).
+ */
+export function buildIdf(memories, tokens) {
+    const idf = new Map();
+    if (memories.length === 0 || tokens.length === 0)
+        return idf;
+    const texts = memories.map((memory) => searchableText(memory));
+    const n = texts.length;
+    for (const token of tokens) {
+        let df = 0;
+        for (const text of texts)
+            if (text.includes(token))
+                df += 1;
+        // Smoothed IDF, always positive: a term in every document scores ~0 rather than
+        // going negative and inverting the ranking.
+        idf.set(token, Math.log(1 + (n - df + 0.5) / (df + 0.5)));
+    }
+    return idf;
+}
 /**
  * Score how relevant one memory is to a query.
  *
@@ -109,15 +140,36 @@ function searchableText(memory) {
  * passed a check or it did not, and giving partial credit for "was checked once and has
  * not been rechecked" would reward staleness.
  */
-export function scoreMemory(memory, tokens, now = Date.now()) {
+export function scoreMemory(memory, tokens, now = Date.now(), idf) {
     const subject = searchableText(memory);
     const matched = tokens.filter((token) => subject.includes(token));
-    const overlap = tokens.length === 0 ? 0 : matched.length / tokens.length;
+    // Overlap is the fraction of the query's *signal* that this memory covers. Without an
+    // IDF map it is the plain ratio; with one, each matched term contributes in proportion
+    // to how rare it is across the population (see buildIdf). The denominator keeps every
+    // query term — one that matches nothing still counts against the memory, which is what
+    // stops a stray rare word from inflating a score.
+    let overlap;
+    if (idf === undefined || tokens.length === 0) {
+        overlap = tokens.length === 0 ? 0 : matched.length / tokens.length;
+    }
+    else {
+        let weightTotal = 0;
+        let weightMatched = 0;
+        const matchedSet = new Set(matched);
+        for (const token of tokens) {
+            const weight = idf.get(token) ?? 1;
+            weightTotal += weight;
+            if (matchedSet.has(token))
+                weightMatched += weight;
+        }
+        overlap = weightTotal === 0 ? 0 : weightMatched / weightTotal;
+    }
     const age = Math.max(0, now - memory.createdAt);
     const recency = Math.max(0, 1 - age / RECENCY_HORIZON_MS);
     const verified = memory.verification?.outcome === 'passed' ? 1 : 0;
     const score = overlap * WEIGHTS.overlap + recency * WEIGHTS.recency + verified * WEIGHTS.verification;
-    const why = `overlap ${matched.length}/${tokens.length}, recency ${recency.toFixed(2)}, ${verified ? 'verified' : 'unverified'}`;
+    const idfPart = idf === undefined ? '' : ` (idf ${overlap.toFixed(2)})`;
+    const why = `overlap ${matched.length}/${tokens.length}${idfPart}, recency ${recency.toFixed(2)}, ${verified ? 'verified' : 'unverified'}`;
     return { score, matched, why };
 }
 /**
@@ -161,9 +213,10 @@ export function inTarget(memory, target) {
  */
 export function recall(memories, query, limit = 5, now = Date.now(), target = 'guidance') {
     const tokens = tokenize(query);
-    const hits = memories
-        .filter((memory) => inTarget(memory, target))
-        .map((memory) => ({ memory, ...scoreMemory(memory, tokens, now) }))
+    const population = memories.filter((memory) => inTarget(memory, target));
+    const idf = buildIdf(population, tokens);
+    const hits = population
+        .map((memory) => ({ memory, ...scoreMemory(memory, tokens, now, idf) }))
         // A query with no signal-bearing tokens matches nothing rather than everything: an
         // empty query is a question about nothing, and answering it with the whole log would
         // make every ranking unexplainable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-memory",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Cross-session memory for your dsh agent: remembered, recalled, and re-verified instead of assumed.",
   "type": "module",
   "main": "lib/index.js",