agentfootprint 8.7.0 → 8.8.0

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"}

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

@@ -0,0 +1,67 @@
+/**
+ * topK — the retrieval strategy agentfootprint has always used, now
+ * written down as one.
+ *
+ * Pattern: Strategy (one of {@link RetrievalStrategy}).
+ * Role:    memory/ layer. Extracted in 8.8.0 from the two numbers that
+ *          used to live loose on `defineRAG` (`topK`, `threshold`), so
+ *          that a different rule can be written without touching a stage.
+ * Emits:   N/A — the stage that calls it does the emitting.
+ *
+ * Behaviour is byte-for-byte what 8.7.0 did: take the highest-scoring
+ * candidates that clear `threshold`, at most `k` of them, and inject
+ * nothing at all when none clear it.
+ *
+ * **The threshold is strict, and strict means silent-by-design becomes
+ * loud-by-record.** When nothing clears the floor, no context is
+ * injected — a weak match in the prompt makes a confident wrong answer
+ * more likely, not less. What 8.8.0 changes is that the near-misses are
+ * now IN the record with their scores, so "the agent answered from
+ * nothing" is a readable outcome instead of an absence.
+ */
+import type { RetrievalStrategy } from './types.js';
+export interface TopKOptions {
+    /**
+     * How many chunks may reach the prompt. Default 3 — enough for more
+     * than one perspective, few enough that the middle of a long context
+     * does not swallow the answer.
+     */
+    readonly k?: number;
+    /**
+     * Minimum similarity to admit, in the store's score space ([-1, 1]
+     * cosine for every shipped store). Default 0.7.
+     *
+     * 0.7 is a high bar for some embedders. Sentence-transformer relatives
+     * (`all-MiniLM-L6-v2` and family, which `localEmbedder` uses by
+     * default) often score 0.4–0.6 on genuinely relevant chunks; OpenAI
+     * `text-embedding-3-*` sits comfortably at 0.7. If retrievals come back
+     * empty, read the `agentfootprint.memory.retrieved` event: it now
+     * carries the rejected candidates and their scores, so the right
+     * threshold is a number you can see rather than one you guess.
+     *
+     * Pass `null` for no floor — every candidate up to `k` is admitted.
+     */
+    readonly threshold?: number | null;
+    /**
+     * How many extra candidates to pull past `k` so that rejected ones can
+     * be reported. Default 10. Raising it costs one larger read and shows
+     * more near-misses; it can never change which candidates are admitted.
+     */
+    readonly rejectWindow?: number;
+}
+/**
+ * Build the top-K strategy.
+ *
+ * @example
+ * ```ts
+ * import { defineRAG } from 'agentfootprint';
+ * import { topK } from 'agentfootprint/memory';
+ *
+ * const docs = defineRAG({
+ *   id: 'product-docs',
+ *   store, embedder,
+ *   retrieval: topK({ k: 5, threshold: 0.55 }),
+ * });
+ * ```
+ */
+export declare function topK(options?: TopKOptions): RetrievalStrategy;

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

@@ -0,0 +1,53 @@
+/**
+ * Build the top-K strategy.
+ *
+ * @example
+ * ```ts
+ * import { defineRAG } from 'agentfootprint';
+ * import { topK } from 'agentfootprint/memory';
+ *
+ * const docs = defineRAG({
+ *   id: 'product-docs',
+ *   store, embedder,
+ *   retrieval: topK({ k: 5, threshold: 0.55 }),
+ * });
+ * ```
+ */
+export function topK(options = {}) {
+    const k = options.k ?? 3;
+    if (!Number.isInteger(k) || k < 1) {
+        throw new Error(`topK: \`k\` must be a positive integer — received ${String(options.k)}.`);
+    }
+    const rejectWindow = options.rejectWindow ?? 10;
+    if (!Number.isInteger(rejectWindow) || rejectWindow < 0) {
+        throw new Error(`topK: \`rejectWindow\` must be a non-negative integer — received ${String(options.rejectWindow)}.`);
+    }
+    const threshold = options.threshold === null ? undefined : options.threshold ?? 0.7;
+    if (threshold !== undefined && !Number.isFinite(threshold)) {
+        throw new Error(`topK: \`threshold\` must be a finite number or null — received ${String(options.threshold)}.`);
+    }
+    return {
+        name: 'topK',
+        k,
+        ...(threshold !== undefined && { threshold }),
+        rejectWindow,
+        select(pool) {
+            const verdicts = [];
+            let admitted = 0;
+            for (const candidate of pool) {
+                if (threshold !== undefined && candidate.score < threshold) {
+                    verdicts.push({ admitted: false, reason: 'below-threshold' });
+                    continue;
+                }
+                if (admitted >= k) {
+                    verdicts.push({ admitted: false, reason: 'over-max-entries' });
+                    continue;
+                }
+                admitted += 1;
+                verdicts.push({ admitted: true });
+            }
+            return verdicts;
+        },
+    };
+}
+//# sourceMappingURL=topK.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"topK.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/topK.ts"],"names":[],"mappings":"AAqDA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,oEAAoE,MAAM,CACxE,OAAO,CAAC,YAAY,CACrB,GAAG,CACL,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IACpF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,kEAAkE,MAAM,CACtE,OAAO,CAAC,SAAS,CAClB,GAAG,CACL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,CAAC;QACD,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,YAAY;QACZ,MAAM,CAAC,IAAgC;YACrC,MAAM,QAAQ,GAAuB,EAAE,CAAC;YACxC,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;oBAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;oBAC9D,SAAS;gBACX,CAAC;gBACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;oBAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;oBAC/D,SAAS;gBACX,CAAC;gBACD,QAAQ,IAAI,CAAC,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,189 @@
+/**
+ * retrieval/types — the record a retrieval leaves behind, and the seam
+ * that decides which candidates reach the prompt.
+ *
+ * Pattern: Strategy (the seam) + Value objects (the record).
+ * Role:    memory/ layer. The law this folder exists to keep is stated
+ *          once, here, because every stage downstream implements a piece
+ *          of it: **a retrieval must be able to say what it considered,
+ *          not only what it used.**
+ * Emits:   N/A (types only). `loadRelevant` emits
+ *          `agentfootprint.memory.retrieved` from the record below;
+ *          `formatDefault` emits `agentfootprint.memory.attached` per
+ *          admitted chunk.
+ *
+ * Before 8.8.0 a retrieval computed a cosine score for every candidate
+ * and then threw all of them away one line later (`results.map(r =>
+ * r.entry)`). The prompt carried the passages; nothing carried the
+ * reason. "Why did the agent read this passage" had no answer in the
+ * recording, and "why did it NOT read that one" had no answer anywhere —
+ * a below-threshold candidate was filtered inside the store and never
+ * came back. {@link RetrievalEvidence} is what that answer is made of.
+ */
+import type { MemoryEntry } from '../entry/index.js';
+/**
+ * Why a candidate did not reach the prompt. Every rejected candidate
+ * names one of these — a rejection without a reason is the silence this
+ * whole record exists to remove.
+ */
+export type RetrievalRejectReason = 
+/** Scored below the retriever's `threshold`. The quality floor refused it. */
+'below-threshold'
+/** Cleared the threshold, but the context-token budget had no room left. */
+ | 'over-budget'
+/** Cleared the threshold and the budget, but the picker's `maxEntries` cap was full. */
+ | 'over-max-entries';
+/**
+ * One candidate the retrieval considered — admitted or not.
+ *
+ * `rank` is the candidate's position by SCORE (1-based, descending),
+ * which is not necessarily the order it appears in the prompt: the
+ * budget picker admits by recency (see {@link RetrievalEvidence.selectionOrder}).
+ * Recording both is the point — a reader can see that the best-scoring
+ * chunk was admitted third, and know that was the picker's doing.
+ */
+export interface RetrievedCandidate {
+    /** The store entry's id. For an indexed corpus this is the chunk id. */
+    readonly id: string;
+    /** Similarity as the store reported it. Cosine ([-1, 1]) for every shipped store. */
+    readonly score: number;
+    /** 1-based position by score, descending, across the whole candidate pool. */
+    readonly rank: number;
+    /** Did this candidate's text reach the prompt? */
+    readonly admitted: boolean;
+    /** Present exactly when `admitted` is false. */
+    readonly reason?: RetrievalRejectReason;
+    /** Source document, when the indexed value carried one in its metadata. */
+    readonly docUri?: string;
+    /** Page number, when the loader knew one (PDFs). */
+    readonly page?: number;
+    /** Section heading, when the splitter knew one. */
+    readonly heading?: string;
+    /**
+     * The exact prompt bytes this chunk contributed, set by the formatter
+     * for admitted candidates. Joining every admitted candidate's fragment
+     * **in {@link promptPosition} order** with `\n\n` reproduces the
+     * injected message exactly — which is what lets one retrieval become
+     * one `InjectionRecord` PER CHUNK without changing a single byte the
+     * model sees.
+     */
+    readonly promptFragment?: string;
+    /**
+     * Where this chunk sat in the injected message, 0-based.
+     *
+     * NOT the same as {@link rank}, and the difference is the honest part:
+     * `rank` is how well the chunk scored, `promptPosition` is where the
+     * budget picker put it. Under the default recency ordering the
+     * best-scoring chunk can land last — which is exactly the kind of thing
+     * a lost-in-the-middle investigation needs to be able to see, and which
+     * a record that only kept one of the two orders could not show.
+     */
+    readonly promptPosition?: number;
+}
+/**
+ * Everything one retrieval knows about itself. Written to the memory
+ * subflow's scope by `loadRelevant`, refined by `pickByBudget` and
+ * `formatDefault`, and lifted to the PARENT scope by the read mount so
+ * it lands in the root commit log where a slice can reach it.
+ */
+export interface RetrievalEvidence {
+    /** The retriever's id (`defineRAG({ id })`). Stamped by the read mount. */
+    readonly memoryId?: string;
+    /**
+     * A stable hash of the query text — NOT the text. The query is already
+     * in the recording once (as `userMessage`); copying it into a second
+     * key would widen the exposure surface for no new information, and any
+     * redaction policy the host configured for the first copy would not
+     * know about the second.
+     */
+    readonly queryHash: string;
+    /** How many chunks the retriever was willing to admit. */
+    readonly k: number;
+    /** The quality floor. Absent when the retriever set none. */
+    readonly threshold?: number;
+    /** The embedder id the query was produced with, when the caller declared one. */
+    readonly embedderId?: string;
+    /** Length of the query vector. Mixing two lengths in one store is a config bug. */
+    readonly dimensions?: number;
+    /** How the budget picker ordered the admitted set. See the note on `rank`. */
+    readonly selectionOrder: 'recency' | 'relevance';
+    /** How many candidates came back from the store. */
+    readonly consideredCount: number;
+    /** How many reached the prompt. */
+    readonly admittedCount: number;
+    /** `consideredCount - admittedCount`. */
+    readonly rejectedCount: number;
+    /**
+     * The candidates themselves, best-scoring first.
+     *
+     * `undefined` means this store could not tell us — see
+     * {@link candidatesOmittedReason}. It never means "there were none";
+     * that case is `[]` with `consideredCount: 0`.
+     */
+    readonly candidates?: readonly RetrievedCandidate[];
+    /**
+     * Whether {@link candidates} is the complete set of candidates that
+     * existed, or only as far as the pool we asked for reached.
+     *
+     * `false` does NOT weaken the admitted set — see the proof in
+     * `loadRelevant`. It only means the REJECTED list is a sample: there
+     * may be further below-threshold entries we never saw.
+     */
+    readonly candidatesComplete: boolean;
+    /** Present exactly when `candidates` is undefined. */
+    readonly candidatesOmittedReason?: string;
+    /**
+     * The store returned nothing at all for this namespace. Distinct from
+     * "everything scored below threshold" (`consideredCount > 0`), and the
+     * distinction is the whole diagnosis: an empty namespace almost always
+     * means the corpus was indexed somewhere else.
+     */
+    readonly corpusEmpty: boolean;
+    /** The namespace that was searched, as a plain string, for the diagnosis above. */
+    readonly namespace?: string;
+}
+/**
+ * The retrieval seam: given the candidates a store returned, decide
+ * which of them the prompt may have — and say why about each one.
+ *
+ * A strategy NEVER talks to the store and never embeds anything. It is
+ * handed a scored, score-descending pool and returns a verdict per
+ * candidate. That narrowness is what makes it composable: a re-ranker or
+ * a diversity selector is the same shape with a different body.
+ *
+ * Shipped: {@link topK}. Deliberately NOT shipped in 8.8.0, and named
+ * here so the destination is on record rather than implied — a
+ * cross-encoder `rerank(...)` and a maximal-marginal-relevance `mmr(...)`
+ * are additional adapters behind this same interface. Neither needs an
+ * engine change, a new stage, or a new event; both were left out because
+ * a re-ranker without a shipped re-ranking model is a config with nothing
+ * to configure.
+ */
+export interface RetrievalStrategy {
+    /** Stable name — appears in the recording and in refusal messages. */
+    readonly name: string;
+    /** How many candidates this strategy is willing to admit. */
+    readonly k: number;
+    /** The quality floor, when the strategy has one. */
+    readonly threshold?: number;
+    /**
+     * How many EXTRA candidates to pull past `k` purely so that rejected
+     * ones can be shown. Never affects which candidates are admitted.
+     */
+    readonly rejectWindow: number;
+    /**
+     * Rule on a score-descending pool. Return one verdict per input, in
+     * the same order. Implementations must not reorder.
+     */
+    select(pool: readonly ScoredCandidate[]): readonly RetrievalVerdict[];
+}
+/** One store result, as a strategy sees it. */
+export interface ScoredCandidate {
+    readonly entry: MemoryEntry<unknown>;
+    readonly score: number;
+}
+/** A strategy's ruling on one candidate. */
+export interface RetrievalVerdict {
+    readonly admitted: boolean;
+    readonly reason?: RetrievalRejectReason;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/types.ts"],"names":[],"mappings":""}

package/dist/esm/memory/stages/formatDefault.d.ts

@@ -1,44 +1,64 @@
 /**
  * formatDefault — render picked entries into injection-ready messages.
  *
- * Reads from scope:  `selected`
- * Writes to scope:   `formatted` (messages to inject into the LLM prompt)
+ * Reads from scope:  `selected`, `retrieved`
+ * Writes to scope:   `formatted` (messages to inject into the LLM prompt),
+ *                    `retrieved` (each admitted chunk's prompt fragment)
  *
  * Why a separate stage from the picker?
- *   Retrieval and presentation are orthogonal concerns (MemGPT-reviewer
- *   ask). A picker decides WHICH memories survive the budget; a formatter
- *   decides HOW they appear to the LLM. Consumers can swap either without
- *   touching the other. In research settings, format variations ("JSON
- *   envelope" vs "XML tags" vs "natural paragraphs") are worth ablating.
+ *   Retrieval and presentation are orthogonal concerns. A picker decides
+ *   WHICH memories survive the budget; a formatter decides HOW they appear
+ *   to the LLM. Consumers can swap either without touching the other. In
+ *   research settings, format variations ("JSON envelope" vs "XML tags" vs
+ *   "natural paragraphs") are worth ablating.
  *
- * Default format:
- *   One `system` message containing a citation-tagged block per entry:
+ * ─── Two flavors, because they are two different claims ────────────────
  *
- *     <memory source="turn:5" updated="2026-04-18T06:00:00Z">
- *     User said: I live in San Francisco.
+ *   `'memory'` (default, unchanged since 7.20.0) — recall from THIS
+ *   conversation. Each entry is a turn, so it is rendered with the turn's
+ *   role and number:
+ *
+ *     Relevant context from prior conversations. Use when it helps answer the current turn.
+ *
+ *     <memory role="user" turn="5" updated="2026-04-18T06:00:00Z">
+ *     I live in San Francisco.
  *     </memory>
  *
- *   Citation tags let the LLM reference sources in its response; the
- *   Anthropic-reviewer ask ("recall should carry source").
+ *   `'rag'` (8.8.0) — retrieval from a document corpus. An indexed chunk
+ *   has no role and no turn; it has a document, a position in it, and a
+ *   similarity score. Printing `role="unknown" turn="0"` on a page of a
+ *   PDF, which is what the memory shape did, told the model three things
+ *   that were not true and withheld the one thing it needed to cite:
+ *
+ *     Relevant passages retrieved from the document corpus. Cite the source id when you use one.
  *
- *   Role chosen: `system`. Reasoning: this is NOT the ongoing dialogue,
- *   it's context we're adding. A `user` role would confuse turn-taking;
- *   `assistant` would be a false claim. `system` matches the semantic
- *   of "context injected by the application, not part of the conversation."
+ *     <source id="refunds.md#3" doc="refunds.md" heading="Refund timing" score="0.81">
+ *     Refunds are processed within 3 business days of approval.
+ *     </source>
  *
- *   Wrapping: entries are grouped into ONE system message rather than N
- *   separate messages. One message is easier for LLMs to reason about
- *   and avoids breaking up the conversational flow.
+ *   Role chosen (both flavors): `system`. This is NOT the ongoing dialogue,
+ *   it is context the application is adding. A `user` role would confuse
+ *   turn-taking; `assistant` would be a false claim.
+ *
+ *   Wrapping: entries are grouped into ONE system message rather than N.
+ *   One message is easier for a model to reason about — and the record
+ *   still resolves to one `InjectionRecord` PER chunk, because each chunk's
+ *   exact bytes are kept on the retrieval record (`promptFragment`) and
+ *   joining them with `\n\n` reproduces this message exactly.
  */
 import type { TypedScope } from 'footprintjs';
 import type { MemoryEntry } from '../entry/index.js';
 import type { LLMMessage as Message } from '../../adapters/types.js';
 import type { MemoryState } from './types.js';
+import type { RetrievedCandidate } from '../retrieval/types.js';
+/** Which claim the injected block is making about its entries. */
+export type MemoryFormatFlavor = 'memory' | 'rag';
 export interface FormatDefaultConfig {
     /**
      * Header prepended to the injected message. Explains to the LLM what
      * follows and what it's for. Override if your app has specific phrasing
-     * guidance ("long-term memory" vs "user preferences", etc.).
+     * guidance ("long-term memory" vs "user preferences", etc.). Defaults
+     * per `flavor`.
      */
     readonly header?: string;
     /**
@@ -48,12 +68,18 @@ export interface FormatDefaultConfig {
      */
     readonly footer?: string;
     /**
-     * Custom per-entry renderer. Receives the entry; returns the block
-     * string (without outer tags — the default wrapper adds those). Use
-     * for app-specific formatting: custom source attributions, hiding
-     * tier info, etc.
+     * Which rendering the entries get. Default `'memory'` — conversation
+     * recall, byte-identical to every release before 8.8.0. `defineRAG`
+     * sets `'rag'`.
+     */
+    readonly flavor?: MemoryFormatFlavor;
+    /**
+     * Custom per-entry renderer. Receives the entry (and, for retrieval
+     * pipelines, its candidate record); returns the block string. Use for
+     * app-specific formatting: custom source attributions, hiding tier
+     * info, etc. Overrides `flavor`.
      */
-    readonly renderEntry?: (entry: MemoryEntry<Message>) => string;
+    readonly renderEntry?: (entry: MemoryEntry<Message>, candidate?: RetrievedCandidate) => string;
     /**
      * When `true`, inject even if `selected` is empty (emits only header
      * and footer). Usually NOT desired — an empty memory block is noise.