agentfootprint 8.7.0 → 8.9.0

package/dist/esm/memory/embedding/loadRelevant.d.ts

@@ -1,29 +1,54 @@
 /**
  * loadRelevant — read-side stage that embeds a query and fetches the
- * top-k most similar entries from a vector-capable `MemoryStore`.
+ * most similar entries from a vector-capable `MemoryStore`.
  *
- * Reads from scope:   `identity`, `newMessages` (or custom queryFrom)
- * Writes to scope:    `loaded` (MemoryEntry[], ordered best-first — to be
- *                     narrowed by `pickByBudget` downstream)
+ * Reads from scope:   `identity`, `messages` (or `newMessages`, or custom queryFrom)
+ * Writes to scope:    `loaded` (MemoryEntry[], ordered best-first — narrowed
+ *                     by `pickByBudget` downstream)
+ *                     `retrieved` (RetrievalEvidence — what was considered,
+ *                     what was admitted, and why about each one)
  *
  * Query derivation:
- *   Default: the last user message in `newMessages`. That's the natural
- *   "what is the user asking about?" signal. Override with `queryFrom`
- *   for custom retrieval (e.g., compose user + assistant content,
- *   pull a summary, etc.).
+ *   Default: the last user message. That's the natural "what is the user
+ *   asking about?" signal. Override with `queryFrom` for custom retrieval.
  *
  * Empty behavior:
- *   No query text → no search → `loaded = []`. Downstream
- *   `pickByBudget` picks nothing and the formatter emits nothing — safe.
+ *   No query text → no search → `loaded = []`. Downstream `pickByBudget`
+ *   picks nothing and the formatter emits nothing — safe, and now
+ *   RECORDED: the evidence still lands, saying the query was empty.
  *
  * Feature detection:
- *   Throws at stage build time if the store doesn't implement
- *   `search()`. Fail-loud — a semantic pipeline configured against a
- *   non-vector store is a config bug, not a runtime condition.
+ *   Throws at stage build time if the store doesn't implement `search()`.
+ *   Fail-loud — a semantic pipeline configured against a non-vector store
+ *   is a config bug, not a runtime condition.
+ *
+ * ─── Why the threshold moved out of the store (8.8.0) ──────────────────
+ *
+ * Until 8.8.0 the quality floor was passed to `store.search({ minScore })`,
+ * so every candidate that failed it was filtered INSIDE the store and never
+ * came back. The consequence was not a small one: a retrieval that injected
+ * nothing left no trace of what it nearly injected, and "why did the agent
+ * not read that passage" had no answer anywhere in the recording.
+ *
+ * The floor is now applied here, over a pool of `k + rejectWindow`. **This
+ * does not change which entries are admitted, ever.** Proof: `search`
+ * returns score-descending, and the pool is at least `k`. Either
+ *
+ *   (a) every entry in the pool clears the floor — then the admitted set is
+ *       the first `k` of them, which is exactly what `{ minScore, k }` would
+ *       have returned; or
+ *   (b) some entry at position p fails the floor — then every entry after p
+ *       fails it too, so the pool already contains EVERY entry in the
+ *       namespace that clears the floor, and admitting all of them (capped
+ *       at `k`) is again exactly what `{ minScore, k }` would have returned.
+ *
+ * `rejectWindow` therefore only controls how many near-misses we can SHOW.
+ * It cannot change what the model sees.
  */
 import type { TypedScope } from 'footprintjs';
 import type { MemoryStore } from '../store/index.js';
 import type { MemoryState } from '../stages/index.js';
+import type { RetrievalStrategy } from '../retrieval/types.js';
 import type { Embedder } from './types.js';
 export interface LoadRelevantConfig {
     /** The vector-capable store. Must implement `search()`. */
@@ -43,9 +68,18 @@ export interface LoadRelevantConfig {
     /** Filter results by tier. */
     readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
     /**
-     * Extract the query text from scope. Default: the last user message
-     * in `newMessages`. Override for custom retrieval signals.
+     * The rule that decides which candidates reach the prompt. Defaults to
+     * `topK({ k, threshold: minScore })` — i.e. `k` and `minScore` above are
+     * the shorthand, and this is the same rule spelled out. Pass a strategy
+     * to replace the rule entirely.
+     */
+    readonly retrieval?: RetrievalStrategy;
+    /**
+     * Extract the query text from scope. Default: the last user message.
+     * Override for custom retrieval signals.
      */
     readonly queryFrom?: (scope: TypedScope<MemoryState>) => string;
 }
 export declare function loadRelevant(config: LoadRelevantConfig): (scope: TypedScope<MemoryState>) => Promise<void>;
+/** Test seam — the once-per-process warning is per PROCESS, which tests must be able to reset. */
+export declare function __resetEmptyCorpusWarnings(): void;

package/dist/esm/memory/embedding/loadRelevant.js

@@ -1,3 +1,8 @@
+import { identityNamespace } from '../identity/index.js';
+import { fnv1a } from '../../lib/fnv1a.js';
+import { chunkProvenance } from '../retrieval/provenance.js';
+import { topK } from '../retrieval/topK.js';
+import { emitEmbedding } from './emitEmbedding.js';
 /**
  * Default query extractor — last user message.
  *
@@ -19,6 +24,12 @@ function defaultQueryFrom(scope) {
     }
     return '';
 }
+/** Emit through the scope's emit channel when there is one (there always is under an Agent). */
+function emit(scope, type, payload) {
+    const emitter = scope.$emit;
+    if (typeof emitter === 'function')
+        emitter.call(scope, type, payload);
+}
 export function loadRelevant(config) {
     const { store, embedder } = config;
     if (!store.search) {
@@ -26,31 +37,163 @@ export function loadRelevant(config) {
             'Use a vector-capable adapter (InMemoryStore, pgvector, Pinecone, ...).');
     }
     const queryFrom = config.queryFrom ?? defaultQueryFrom;
-    const k = config.k ?? 20;
+    // The shorthand and the strategy are two spellings of one rule; the
+    // strategy wins when both are present, and `defineMemory` refuses the
+    // contradiction before it ever gets here.
+    const strategy = config.retrieval ??
+        topK({
+            k: config.k ?? 20,
+            threshold: config.minScore === undefined ? null : config.minScore,
+            // With no explicit strategy there is no explicit reject window
+            // either; 10 near-misses is enough to diagnose a threshold without
+            // making every retrieval read a large page.
+        });
+    const poolSize = strategy.k + strategy.rejectWindow;
     return async (scope) => {
         const identity = scope.identity;
+        const namespace = identityNamespace(identity);
         const text = queryFrom(scope).trim();
+        const baseEvidence = {
+            queryHash: fnv1a(text),
+            k: strategy.k,
+            ...(strategy.threshold !== undefined && { threshold: strategy.threshold }),
+            ...(config.embedderId !== undefined && { embedderId: config.embedderId }),
+            selectionOrder: 'recency',
+            namespace,
+        };
         if (text.length === 0) {
             scope.loaded = [];
+            const emptyQuery = {
+                ...baseEvidence,
+                consideredCount: 0,
+                admittedCount: 0,
+                rejectedCount: 0,
+                candidates: [],
+                candidatesComplete: true,
+                // The corpus was never asked, so it cannot be reported empty.
+                corpusEmpty: false,
+            };
+            scope.retrieved = emptyQuery;
             return;
         }
         const signal = scope.$getEnv?.()?.signal;
+        const embedStartedAt = Date.now();
         const queryVec = (await embedder.embed({
             text,
             ...(signal ? { signal } : {}),
         }));
+        // The QUERY-time half of the two-phase cost model (8.9.0): one embedding
+        // per retrieval, scaling with traffic rather than with corpus size. Paired
+        // with the `'document'` side in `embedMessages`, this is what makes the
+        // cost of a corpus a number you can read rather than one you estimate.
+        emitEmbedding(scope, {
+            model: config.embedderId ?? embedder.id ?? 'unknown',
+            provider: 'custom',
+            inputKind: 'query',
+            dimension: queryVec.length,
+            count: 1,
+            durationMs: Date.now() - embedStartedAt,
+        });
         // store.search optional on MemoryStore but required when an embedder
         // is configured (validated upstream by defineMemory).
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const results = await store.search(identity, queryVec, {
-            k,
-            ...(config.minScore !== undefined && { minScore: config.minScore }),
+        const results = (await store.search(identity, queryVec, {
+            k: poolSize,
+            // `minScore` is deliberately NOT forwarded — see the header proof.
             ...(config.tiers && { tiers: config.tiers }),
             ...(config.embedderId !== undefined && { embedderId: config.embedderId }),
+            text,
+        }));
+        // A store that ranks server-side may return entries without a usable
+        // score. We report that rather than printing a number we did not get.
+        const scoresUsable = results.every((r) => typeof r.score === 'number' && Number.isFinite(r.score));
+        const verdicts = scoresUsable
+            ? strategy.select(results.map((r) => ({ entry: r.entry, score: r.score })))
+            : // No comparable scores to rule on. The store already ranked, so we
+                // honour its order and take the first `k` — and say in the record
+                // that we could not see the candidates ourselves.
+                results.map((_, i) => ({ admitted: i < strategy.k }));
+        const admitted = [];
+        const candidates = [];
+        results.forEach((result, i) => {
+            // `verdicts` is built from `results` above, one per element.
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const verdict = verdicts[i];
+            if (verdict.admitted)
+                admitted.push(result);
+            candidates.push({
+                id: result.entry.id,
+                score: result.score,
+                rank: i + 1,
+                admitted: verdict.admitted,
+                ...(verdict.reason !== undefined && { reason: verdict.reason }),
+                ...chunkProvenance(result.entry.value),
+            });
+        });
+        const evidence = {
+            ...baseEvidence,
+            ...(queryVec.length > 0 && { dimensions: queryVec.length }),
+            consideredCount: results.length,
+            admittedCount: admitted.length,
+            rejectedCount: results.length - admitted.length,
+            ...(scoresUsable
+                ? { candidates }
+                : {
+                    candidatesOmittedReason: 'the store ranked this query server-side and returned no comparable scores',
+                }),
+            // The pool came back full, so there may be further below-threshold
+            // entries we never saw. This never weakens the ADMITTED set (see
+            // the header proof) — only the rejected list is a sample.
+            candidatesComplete: results.length < poolSize,
+            corpusEmpty: results.length === 0,
+        };
+        scope.loaded = admitted.map((r) => r.entry);
+        scope.retrieved = evidence;
+        // Telemetry rides the emit channel, never a commit payload. The
+        // memory bridge (`memoryRecorder`) is attached on every Agent run, so
+        // this reaches `agent.on('agentfootprint.memory.retrieved')` with no
+        // extra wiring. Which retriever fired is `meta.runtimeStageId`
+        // (`sf-memory-read-<id>/load-relevant#N`) — the house correlation model.
+        emit(scope, 'agentfootprint.memory.retrieved', {
+            queryHash: evidence.queryHash,
+            k: evidence.k,
+            ...(evidence.threshold !== undefined && { threshold: evidence.threshold }),
+            ...(evidence.embedderId !== undefined && { embedderId: evidence.embedderId }),
+            ...(evidence.dimensions !== undefined && { dimensions: evidence.dimensions }),
+            consideredCount: evidence.consideredCount,
+            admittedCount: evidence.admittedCount,
+            rejectedCount: evidence.rejectedCount,
+            ...(evidence.candidates !== undefined && { candidates: evidence.candidates }),
+            ...(evidence.candidatesOmittedReason !== undefined && {
+                candidatesOmittedReason: evidence.candidatesOmittedReason,
+            }),
+            candidatesComplete: evidence.candidatesComplete,
+            corpusEmpty: evidence.corpusEmpty,
+            namespace: evidence.namespace,
         });
-        // Write loaded entries to scope in best-first order — downstream
-        // pickByBudget further narrows by the token budget.
-        scope.loaded = results.map((r) => r.entry);
+        // An empty namespace is almost never "the corpus has nothing to say".
+        // It is almost always "the corpus was indexed under a different
+        // identity than the one being queried" — the failure that used to be
+        // completely silent. Say it once per process, naming both sides.
+        if (evidence.corpusEmpty)
+            warnEmptyCorpus(namespace);
     };
 }
+const warnedNamespaces = new Set();
+function warnEmptyCorpus(namespace) {
+    if (warnedNamespaces.has(namespace))
+        return;
+    warnedNamespaces.add(namespace);
+    console.warn(`[agentfootprint] Semantic retrieval found NO entries at all in namespace '${namespace}'.\n` +
+        `  Nothing was injected, and the answer will come from the model alone.\n` +
+        `  The usual cause is that the corpus was indexed under a different identity than the one\n` +
+        `  being queried: indexDocuments() defaults to { conversationId: '_global' }, and a memory\n` +
+        `  reads under the identity passed to agent.run() unless the retriever declares its own\n` +
+        `  \`corpus\`. defineRAG() defaults \`corpus\` to { conversationId: '_global' } so the two\n` +
+        `  sides meet; pass \`corpus\` explicitly when you index per tenant.`);
+}
+/** Test seam — the once-per-process warning is per PROCESS, which tests must be able to reset. */
+export function __resetEmptyCorpusWarnings() {
+    warnedNamespaces.clear();
+}
 //# sourceMappingURL=loadRelevant.js.map

package/dist/esm/memory/embedding/loadRelevant.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadRelevant.js","sourceRoot":"","sources":["../../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"AA2DA;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,KAA8B;IACtD,MAAM,QAAQ,GAAG,KAAqD,CAAC;IACvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC;IACzC,MAAM,MAAM,GACV,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAwB,CAAC;IAErF,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QAChC,IAAI,CAAC,CAAC,OAAO;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IAClC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IACnC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,kEAAkE;YAChE,wEAAwE,CAC3E,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,gBAAgB,CAAC;IACvD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzB,OAAO,KAAK,EAAE,KAA8B,EAAiB,EAAE;QAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC;QACzC,MAAM,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC;YACrC,IAAI;YACJ,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAa,CAAC;QAEhB,qEAAqE;QACrE,sDAAsD;QACtD,oEAAoE;QACpE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE;YACtD,CAAC;YACD,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;YACnE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;SAC1E,CAAC,CAAC;QAEH,iEAAiE;QACjE,oDAAoD;QACpD,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAA0B,CAAC;IACtE,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"loadRelevant.js","sourceRoot":"","sources":["../../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/embedding/mockEmbedder.js

@@ -17,6 +17,10 @@ export function mockEmbedder(options = {}) {
     }
     return {
         dimensions,
+        // Named like the others so a store can refuse the swap between a mock
+        // index and a real one — which is a swap worth refusing, since a corpus
+        // indexed by letter frequency and queried by meaning scores nothing.
+        id: 'mock',
         async embed({ text }) {
             return charFrequency(text, dimensions);
         },

package/dist/esm/memory/embedding/mockEmbedder.js.map

@@ -1 +1 @@
-{"version":3,"file":"mockEmbedder.js","sourceRoot":"","sources":["../../../../src/memory/embedding/mockEmbedder.ts"],"names":[],"mappings":"AAeA,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,SAAS,aAAa,CAAC,IAAY,EAAE,IAAY;IAC/C,MAAM,GAAG,GAAG,IAAI,KAAK,CAAS,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAMD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAC5D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,4DAA4D,UAAU,GAAG,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,UAAU;QACV,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAa;YAC7B,OAAO,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,EAAkB;YACxC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QAC9D,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mockEmbedder.js","sourceRoot":"","sources":["../../../../src/memory/embedding/mockEmbedder.ts"],"names":[],"mappings":"AAeA,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,SAAS,aAAa,CAAC,IAAY,EAAE,IAAY;IAC/C,MAAM,GAAG,GAAG,IAAI,KAAK,CAAS,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAMD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAC5D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,4DAA4D,UAAU,GAAG,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,UAAU;QACV,sEAAsE;QACtE,wEAAwE;QACxE,qEAAqE;QACrE,EAAE,EAAE,MAAM;QACV,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAa;YAC7B,OAAO,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,EAAkB;YACxC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QAC9D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/memory/embedding/types.d.ts

@@ -35,6 +35,30 @@ export interface EmbedBatchArgs {
 export interface Embedder {
     /** Vector length. Constant per embedder instance. */
     readonly dimensions: number;
+    /**
+     * Stable name of the embedding space this instance produces (8.9.0).
+     *
+     * Together with `dimensions` it forms the fingerprint a durable store
+     * records per vector — `'<id>@<dims>'` — and refuses on when it changes.
+     * Cosine similarity between two embedding spaces is not a weak signal; it
+     * is not a signal, and it comes back as a confident number in the same
+     * range as a real one. A store that can name the space can refuse the mix;
+     * one that cannot has to let it through.
+     *
+     * Optional, because an `Embedder` is a structural interface and every
+     * hand-written one predates this field. When it is absent the store falls
+     * back to comparing `dimensions` alone, which catches the arithmetically
+     * impossible case and not the merely wrong one.
+     *
+     * Every shipped embedder sets it, and it is what you pass as `embedderId`:
+     *
+     * ```ts
+     * const embedder = staticEmbedder();
+     * await indexDocuments(store, embedder, docs, { embedderId: embedder.id });
+     * defineRAG({ id: 'docs', store, embedder, embedderId: embedder.id });
+     * ```
+     */
+    readonly id?: string;
     /** Embed a single text into a vector of length `dimensions`. */
     embed(args: EmbedArgs): Promise<number[]>;
     /**

package/dist/esm/memory/index.d.ts

@@ -15,7 +15,8 @@ export * from './pipeline/index.js';
 export * from './stages/index.js';
 export * from './store/index.js';
 export * from './wire/index.js';
-export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryWindowStrategy, type BudgetStrategy, type SummarizeStrategy, type TopKStrategy, type ExtractStrategy, type DecayStrategy, type HybridStrategy, type MemoryDefinition, type DefineMemoryOptions, type DefineEpisodicOptions, type DefineSemanticOptions, type DefineNarrativeOptions, type DefineCausalOptions, type MemoryRedactionPolicy, } from './define.types.js';
+export * from './retrieval/index.js';
+export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, RETRIEVAL_EVIDENCE_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, retrievalEvidenceKey, isRetrievalEvidenceKey, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryWindowStrategy, type BudgetStrategy, type SummarizeStrategy, type TopKStrategy, type TopKShorthandStrategy, type TopKRetrievalStrategy, type MemoryFlavor, type ExtractStrategy, type DecayStrategy, type HybridStrategy, type MemoryDefinition, type DefineMemoryOptions, type DefineEpisodicOptions, type DefineSemanticOptions, type DefineNarrativeOptions, type DefineCausalOptions, type MemoryRedactionPolicy, } from './define.types.js';
 /**
  * @deprecated Since 7.27.1 — use `MemoryWindowStrategy`.
  *

package/dist/esm/memory/index.js

@@ -15,7 +15,8 @@ export * from './pipeline/index.js';
 export * from './stages/index.js';
 export * from './store/index.js';
 export * from './wire/index.js';
+export * from './retrieval/index.js';
 // Consumer-facing factory + const-objects for memory configuration.
-export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, } from './define.types.js';
+export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, RETRIEVAL_EVIDENCE_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, retrievalEvidenceKey, isRetrievalEvidenceKey, } from './define.types.js';
 export { defineMemory } from './define.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/memory/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,oEAAoE;AACpE,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,GAoBrB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAErC,oEAAoE;AACpE,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,GAuBvB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/esm/memory/pipeline/semantic.d.ts

@@ -1,3 +1,5 @@
+import { type MemoryFormatFlavor } from '../stages/formatDefault.js';
+import type { RetrievalStrategy } from '../retrieval/types.js';
 import type { MemoryStore } from '../store/index.js';
 import type { MemoryPipeline } from './types.js';
 import type { Embedder } from '../embedding/types.js';
@@ -29,6 +31,19 @@ export interface SemanticPipelineConfig {
     /** Forwarded to `formatDefault`. */
     readonly formatHeader?: string;
     readonly formatFooter?: string;
+    /**
+     * The retrieval rule (8.8.0). Replaces `k` + `minScore` above; see
+     * {@link RetrievalStrategy}. When absent, `topK({ k, threshold: minScore })`
+     * is built from those two — the same rule, spelled the old way.
+     */
+    readonly retrieval?: RetrievalStrategy;
+    /**
+     * Which claim the injected block makes (8.8.0). `'rag'` renders each
+     * entry as a citable `<source>` with its document, page and score;
+     * `'memory'` (default) keeps the conversation-recall `<memory>` shape
+     * byte for byte.
+     */
+    readonly flavor?: MemoryFormatFlavor;
 }
 /**
  * Build the semantic read + write pipelines sharing a single store.

package/dist/esm/memory/pipeline/semantic.js

@@ -37,7 +37,7 @@
  */
 import { flowChart } from 'footprintjs';
 import { pickByBudget } from '../stages/pickByBudget.js';
-import { formatDefault } from '../stages/formatDefault.js';
+import { formatDefault, } from '../stages/formatDefault.js';
 import { writeMessages } from '../stages/writeMessages.js';
 import { loadRelevant } from '../embedding/loadRelevant.js';
 import { embedMessages, } from '../embedding/embedMessages.js';
@@ -57,6 +57,7 @@ export function semanticPipeline(config) {
         ...(config.k !== undefined && { k: config.k }),
         ...(config.minScore !== undefined && { minScore: config.minScore }),
         ...(config.tiers && { tiers: config.tiers }),
+        ...(config.retrieval !== undefined && { retrieval: config.retrieval }),
     };
     const pickConfig = {
         ...(config.reserveTokens !== undefined && { reserveTokens: config.reserveTokens }),
@@ -66,6 +67,7 @@ export function semanticPipeline(config) {
     const formatConfig = {
         ...(config.formatHeader !== undefined && { header: config.formatHeader }),
         ...(config.formatFooter !== undefined && { footer: config.formatFooter }),
+        ...(config.flavor !== undefined && { flavor: config.flavor }),
     };
     const embedConfig = {
         embedder: config.embedder,

package/dist/esm/memory/pipeline/semantic.js.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../../../src/memory/pipeline/semantic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../../../src/memory/pipeline/semantic.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/retrieval/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * memory/retrieval — what a retrieval considered, and the seam that
+ * decides what it keeps.
+ *
+ * @see ./types.ts   the record + the strategy interface
+ * @see ./topK.ts    the strategy 8.7.0 had, now written down as one
+ */
+export type { RetrievalEvidence, RetrievalRejectReason, RetrievalStrategy, RetrievalVerdict, RetrievedCandidate, ScoredCandidate, } from './types.js';
+export { topK, type TopKOptions } from './topK.js';
+export { chunkProvenance, chunkText, type ChunkProvenance } from './provenance.js';

package/dist/esm/memory/retrieval/index.js

@@ -0,0 +1,3 @@
+export { topK } from './topK.js';
+export { chunkProvenance, chunkText } from './provenance.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/memory/retrieval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAwB,MAAM,iBAAiB,CAAC"}

package/dist/esm/memory/retrieval/provenance.d.ts

@@ -0,0 +1,43 @@
+/**
+ * provenance — read a stored entry's coordinates back out of it.
+ *
+ * Pattern: pure projection.
+ * Role:    memory/ layer. One place that knows which metadata keys mean
+ *          "which document", "which page", "which section", so the
+ *          retrieval record and the citation the model sees can never
+ *          disagree about a chunk's origin.
+ * Emits:   N/A.
+ *
+ * The keys are the ones `indexDocuments` already accepts on
+ * `RagDocument.metadata`, and the ones a document splitter will write.
+ * Nothing is invented: an entry that carries no metadata simply has no
+ * coordinates, and the record says so by omitting the fields rather than
+ * by guessing a filename from an id.
+ */
+/** The document coordinates a chunk can carry. All optional — absence is honest. */
+export interface ChunkProvenance {
+    /** Which document this text came from. Read from `docUri`, else `source`. */
+    readonly docUri?: string;
+    /** Which page, for paginated formats. */
+    readonly page?: number;
+    /** Which section heading the splitter cut under. */
+    readonly heading?: string;
+}
+/**
+ * Pull the coordinates out of a stored value.
+ *
+ * Accepts metadata at the value's `metadata` key (where `indexDocuments`
+ * puts it) or directly on the value, so a hand-built entry works too.
+ */
+export declare function chunkProvenance(value: unknown): ChunkProvenance;
+/**
+ * The text a stored value carries.
+ *
+ * Two shapes reach the formatter through the same pipeline: a chat
+ * `Message` (`{ role, content }`) from conversation memory, and a
+ * document (`{ id, content, metadata }`) from `indexDocuments`. Both
+ * keep their text on `content`, which is why one accessor serves both —
+ * but only the message shape has a meaningful `role`, which is why the
+ * corpus formatter does not print one.
+ */
+export declare function chunkText(value: unknown): string;

package/dist/esm/memory/retrieval/provenance.js

@@ -0,0 +1,60 @@
+/**
+ * provenance — read a stored entry's coordinates back out of it.
+ *
+ * Pattern: pure projection.
+ * Role:    memory/ layer. One place that knows which metadata keys mean
+ *          "which document", "which page", "which section", so the
+ *          retrieval record and the citation the model sees can never
+ *          disagree about a chunk's origin.
+ * Emits:   N/A.
+ *
+ * The keys are the ones `indexDocuments` already accepts on
+ * `RagDocument.metadata`, and the ones a document splitter will write.
+ * Nothing is invented: an entry that carries no metadata simply has no
+ * coordinates, and the record says so by omitting the fields rather than
+ * by guessing a filename from an id.
+ */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null
+        ? value
+        : undefined;
+}
+/**
+ * Pull the coordinates out of a stored value.
+ *
+ * Accepts metadata at the value's `metadata` key (where `indexDocuments`
+ * puts it) or directly on the value, so a hand-built entry works too.
+ */
+export function chunkProvenance(value) {
+    const root = asRecord(value);
+    if (!root)
+        return {};
+    const meta = asRecord(root['metadata']) ?? root;
+    const rawDoc = meta['docUri'] ?? meta['source'];
+    const docUri = typeof rawDoc === 'string' && rawDoc.length > 0 ? rawDoc : undefined;
+    const rawPage = meta['page'];
+    const page = typeof rawPage === 'number' && Number.isFinite(rawPage) ? rawPage : undefined;
+    const rawHeading = meta['heading'];
+    const heading = typeof rawHeading === 'string' && rawHeading.length > 0 ? rawHeading : undefined;
+    return {
+        ...(docUri !== undefined && { docUri }),
+        ...(page !== undefined && { page }),
+        ...(heading !== undefined && { heading }),
+    };
+}
+/**
+ * The text a stored value carries.
+ *
+ * Two shapes reach the formatter through the same pipeline: a chat
+ * `Message` (`{ role, content }`) from conversation memory, and a
+ * document (`{ id, content, metadata }`) from `indexDocuments`. Both
+ * keep their text on `content`, which is why one accessor serves both —
+ * but only the message shape has a meaningful `role`, which is why the
+ * corpus formatter does not print one.
+ */
+export function chunkText(value) {
+    const root = asRecord(value);
+    const content = root?.['content'];
+    return typeof content === 'string' ? content : '';
+}
+//# sourceMappingURL=provenance.js.map

package/dist/esm/memory/retrieval/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAChD,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC;IAEhD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAEpF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3F,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAEjG,OAAO;QACL,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;QACvC,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;QACnC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC;IAClC,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC"}