agentfootprint 9.13.0 → 9.14.0

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

@@ -145,16 +145,64 @@ export interface BudgetStrategy {
     readonly maxEntries?: number;
 }
 /**
- * Summarize — when the conversation grows long, an LLM compresses older
- * turns into a paragraph; recent N turns stay raw. The standard answer
- * to "long conversations blow context."
+ * Summarize — when recall grows long, one LLM call compresses the older
+ * entries into a summary that is STORED, while the most recent `recent`
+ * entries stay raw. The standard answer to "long conversations blow context".
+ *
+ * Wired in 9.14.0. Through 9.13.0 this type existed, `llm` was required, and
+ * the pipeline `defineMemory` built loaded the last `recent` entries and
+ * stopped — a strategy that named a summarizer and never called it. What runs
+ * now:
+ *
+ *   1. load up to `size` entries (default 20);
+ *   2. keep the last `recent` verbatim, seam rounded outward to a whole turn;
+ *   3. fold everything older into ONE summary entry — one call, over the span;
+ *   4. WRITE that entry back to the same store under
+ *      `msg-summary-{fromTurn}-{toTurn}`, so the next turn reads it instead of
+ *      paying for it again;
+ *   5. recall is `[summary, ...recent verbatim]`.
+ *
+ * The folded originals are NOT deleted. They stay in the store and are
+ * excluded from recall by the summary's coverage metadata — delete the
+ * summary entry and recall is verbatim again.
  */
 export interface SummarizeStrategy {
     readonly kind: typeof MEMORY_STRATEGIES.SUMMARIZE;
-    /** Keep this many most-recent turns uncompressed. */
+    /**
+     * Keep this many most-recent entries uncompressed. The seam is rounded
+     * outward to a whole turn, so a question is never summarized while its
+     * answer stays raw.
+     */
     readonly recent: number;
+    /**
+     * How much history to load per turn — the pool the fold is taken from.
+     * Default 20 (`loadRecent`'s own default). Must be greater than `recent`:
+     * a window no larger than the verbatim tail never has anything older to
+     * compress, which is `window` with a summarizer bolted on.
+     */
+    readonly size?: number;
     /** LLM that does the compression — recommend a cheap model (haiku). */
     readonly llm: LLMProvider;
+    /**
+     * Which model `llm` is called with. REQUIRED (9.14.0), and there is no
+     * fall back to the agent's own model — the same law `.compaction()` has
+     * enforced since 8.14.0. A default here had no correct case: the same
+     * provider family quietly bills your MAIN model for compression, and a
+     * different vendor is sent a model id it has never heard of.
+     *
+     * `Agent.memory()` additionally refuses a summarizer that is the agent's own
+     * provider INSTANCE at the agent's own model: those two calls look identical
+     * and are not — the agent's runs through reliability, decorators and the
+     * cache, and this one runs through none of them.
+     */
+    readonly model: string;
+    /**
+     * Override the instruction the summarizer is given (the transcript
+     * delimiters and the authored label on the stored summary stay the
+     * library's). Use it for domain summaries: "preserve every refund-related
+     * number".
+     */
+    readonly systemPrompt?: string;
 }
 /**
  * Top-K — embed the user's query, retrieve top-K by cosine similarity.
@@ -333,6 +381,23 @@ export interface MemoryDefinition<T = unknown> {
     readonly store?: MemoryStore;
     /** When `read` runs. Default `TURN_START`. */
     readonly timing: MemoryTiming;
+    /**
+     * What this memory's OWN LLM work bills to (9.14.0) — present only for a
+     * strategy that calls a model on the host's behalf, which today is
+     * `SUMMARIZE`.
+     *
+     * Carried in the open for one reason: `Agent.memory()` is where the agent's
+     * own provider and model are known, and it refuses a summarizer that is that
+     * exact instance at that exact model (the 8.14.0 rule `.compaction()` and
+     * `.window()` already enforce). `defineMemory` cannot make that check — it
+     * has never heard of an agent — so it declares the billing and the builder
+     * checks it. Same field name and same shape as `WindowStrategy.billing`, so
+     * one refusal serves both.
+     */
+    readonly billing?: {
+        readonly provider: LLMProvider;
+        readonly model: string;
+    };
     /** Reserved for a future release — patterns to redact before write. */
     readonly redact?: MemoryRedactionPolicy;
     /** Snapshot projection — only meaningful when `type === CAUSAL`. */

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

@@ -1 +1 @@
-{"version":3,"file":"define.types.js","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAQH,uEAAuE;AAEvE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe,EAAE,iBAAiB;IAClC,UAAU,EAAE,YAAY;CAChB,CAAC;AAGX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;CACJ,CAAC;AAqXX,uEAAuE;AAEvE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,YAAY,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAQ,MAAM,CAAC,MAAM,CAAC,aAAa,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAA2B,CAAC;AAEvE,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,OAAO,GAAG,2BAA2B,GAAG,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAA6B,CAAC;AAE3E,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,GAAG,6BAA6B,GAAG,EAAE,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,OAAO,GAAG,CAAC,UAAU,CAAC,6BAA6B,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"define.types.js","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAQH,uEAAuE;AAEvE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;CACR,CAAC;AAGX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe,EAAE,iBAAiB;IAClC,UAAU,EAAE,YAAY;CAChB,CAAC;AAGX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;CACJ,CAAC;AAubX,uEAAuE;AAEvE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,YAAY,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAQ,MAAM,CAAC,MAAM,CAAC,aAAa,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAQ,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,uEAAuE;AAEvE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAA2B,CAAC;AAEvE,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,OAAO,GAAG,2BAA2B,GAAG,EAAE,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,oBAA6B,CAAC;AAE3E,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,OAAO,GAAG,6BAA6B,GAAG,EAAE,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,OAAO,GAAG,CAAC,UAAU,CAAC,6BAA6B,CAAC,CAAC;AACvD,CAAC"}

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

@@ -1,4 +1,5 @@
 import { type FilterByDecayConfig } from '../stages/filterByDecay.js';
+import { type SummarizeConfig } from '../stages/summarize.js';
 import type { MemoryStore } from '../store/index.js';
 import type { MemoryPipeline } from './types.js';
 export interface DefaultPipelineConfig {
@@ -50,6 +51,27 @@ export interface DefaultPipelineConfig {
      * pipeline level so it composes with `loadCount` / the budget knobs.
      */
     readonly decay?: FilterByDecayConfig;
+    /**
+     * Compress what falls out of the verbatim tail (9.14.0). When present, a
+     * `Summarize` stage is composed directly after the load: the oldest loaded
+     * entries become ONE summary entry written back to this same store, and
+     * recall becomes `[summary, ...recent verbatim]`.
+     *
+     * The stage's `store` and `ttlMs` are filled from THIS config — the summary
+     * lands in the same namespace as the turns it stands for, and under the same
+     * retention window, because a summary that outlived the messages it
+     * compressed is the leak `writeTtlMs` exists to prevent.
+     *
+     * Absent — the historical behaviour — means no summarize stage is compiled
+     * at all, not a summarize stage that never fires. What is not in the chart
+     * cannot cost anything or appear in the narrative.
+     *
+     * `defineMemory({ strategy: { kind: MEMORY_STRATEGIES.SUMMARIZE, recent,
+     * llm, model } })` is the door most consumers use; this is the same thing,
+     * spelled at the pipeline level so it composes with `loadCount` and the
+     * budget knobs.
+     */
+    readonly summarize?: Omit<SummarizeConfig, 'store' | 'ttlMs'>;
     /**
      * Override for the formatter's header text. Omit to use the default
      * "Relevant context from prior conversations..." phrasing.

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

@@ -4,9 +4,14 @@
  * Composes Layer 2-3 stages into two flowchart subflows that the wire
  * layer mounts inside the agent's main flowchart:
  *
- *   READ  :  LoadRecent → PickByBudget → FormatDefault
+ *   READ  :  LoadRecent → [Summarize] → [FilterByDecay] → PickByBudget →
+ *            FormatDefault
  *   WRITE :  WriteMessages
  *
+ * The two bracketed stages are compiled only when their config is present
+ * (`summarize`, `decay`) — an absent option means an absent stage, never a
+ * stage that runs and does nothing.
+ *
  * Why this particular composition?
  *   - Load-then-pick-then-format matches the cognitive sequence:
  *     retrieve candidates, choose what fits, present it.
@@ -50,6 +55,7 @@
 import { flowChart } from 'footprintjs';
 import { loadRecent } from '../stages/loadRecent.js';
 import { filterByDecay } from '../stages/filterByDecay.js';
+import { summarize } from '../stages/summarize.js';
 import { pickByBudget } from '../stages/pickByBudget.js';
 import { formatDefault } from '../stages/formatDefault.js';
 import { writeMessages } from '../stages/writeMessages.js';
@@ -79,14 +85,24 @@ export function defaultPipeline(config) {
         ...(config.writeTier && { tier: config.writeTier }),
         ...(config.writeTtlMs !== undefined && { ttlMs: config.writeTtlMs }),
     };
-    // Compose: LoadRecent → [FilterByDecay] → [PickDecider → skip-empty |
-    //          skip-no-budget | pick] → Format
+    // Compose: LoadRecent → [Summarize] → [FilterByDecay] → [PickDecider →
+    //          skip-empty | skip-no-budget | pick] → Format
     // pickByBudget is a builder-extension — it appends a decider + 3
     // branches to the pipeline so "why did / didn't we inject memory?" is
     // answerable via FlowRecorder.onDecision evidence, not just emit events.
     let readBuilder = flowChart('LoadRecent', loadRecent(loadConfig), 'load-recent', {
         description: 'Read N most-recent entries from storage into scope.loaded',
     });
+    if (config.summarize !== undefined) {
+        // Directly after the load, and before every stage that trims: decay and
+        // the budget picker both decide against what recall CONTAINS, and what
+        // recall contains is not settled until the fold has happened.
+        readBuilder = readBuilder.addFunction('Summarize', summarize({
+            ...config.summarize,
+            store: config.store,
+            ...(config.writeTtlMs !== undefined && { ttlMs: config.writeTtlMs }),
+        }), 'summarize', 'Fold entries older than the verbatim tail into one stored summary entry');
+    }
     if (config.decay !== undefined) {
         // Before the picker: what has faded is not a budget question, and the
         // budget is better spent on entries that are still worth something.

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

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

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

@@ -1,87 +1,226 @@
 /**
- * summarize — stage that compresses old loaded entries into a single
- * summary entry, preserving the most-recent N verbatim.
+ * summarize — the stage that makes the SUMMARIZE strategy summarize (9.14.0).
  *
- * Reads from scope:  `loaded`
- * Writes to scope:   `loaded` (mutated: oldest entries replaced by one
- *                     synthetic summary entry)
+ * Reads from scope:  `loaded`, `identity`
+ * Writes to scope:   `loaded` (older entries replaced by ONE summary entry)
+ * Writes to store:   the summary entry, under a deterministic id
+ * Emits:             agentfootprint.memory.strategy_applied (every visit that
+ *                    changes recall or decides not to), carrying the reason,
+ *                    the model, and the token usage the call reported.
+ *
+ *                    NOT `cost.tick`, and that is a limit worth knowing: the
+ *                    USD channel needs a `pricingTable` and the run's
+ *                    cumulative counters, both of which live on the AGENT's
+ *                    scope, and a memory pipeline is a subflow with neither.
+ *                    Emitting a tick with `estimatedUsd: 0` would be a
+ *                    cheaper-looking lie than saying nothing, so the tokens
+ *                    ride the memory event instead and the fold is never
+ *                    silent.
  *
  * Where this fits in the pipeline:
  *
- *   loadRecent → summarize → pickByBudget → formatDefault
+ *   loadRecent → summarize → [filterByDecay] → pickByBudget → formatDefault
+ *
+ * ## What it does, and what that costs
+ *
+ * Recall arrives from `loadRecent` oldest-first. This stage keeps the last
+ * `preserveRecent` entries VERBATIM and folds everything older into a single
+ * summary entry — **one LLM call over the span**, not one per entry and not
+ * one per recall. The summary is then WRITTEN BACK to the store under the id
+ * `msg-summary-{fromTurn}-{toTurn}`, so the next turn LOADS it instead of
+ * paying for it again. That write-back is the whole cost model: a span is
+ * summarized once in the life of a conversation, by whichever turn first saw
+ * it fall out of the verbatim tail.
  *
- * After `summarize` runs, `loaded` is smaller (fewer entries, one of
- * which is a synthetic summary). The picker then selects from this
- * reduced set using the standard budget logic.
+ * ## The originals are never deleted
  *
- * ## Determinism contract (Anthropic-reviewer ask)
+ * A summary is a CLAIM ABOUT the conversation, not the conversation. The
+ * entries it covers stay in the store byte-identical; they are excluded from
+ * recall by the summary's own coverage metadata ({@link SummaryCoverage}) and
+ * by nothing else. Delete the summary entry and the next recall is verbatim
+ * again. This is the same law `.compaction()` follows in the live window —
+ * the fold edits what is SENT, never what was said.
  *
- * For prompt caching to stay stable across runs, the summary content
- * MUST be the same each time for the same input. This requires:
+ * ## Two summarizer shapes
  *
- *   1. Temperature = 0 on the provided LLM.
- *   2. A stable seed if the provider supports it (Anthropic: omit;
- *      OpenAI: pass a fixed `seed` in the request).
- *   3. Same system prompt + message set produces same output.
+ *   • `llm: LLMProvider` + `model` — the library composes the call. The span
+ *     is rendered as DATA between delimiters the authored instruction names,
+ *     so a message inside the conversation cannot re-instruct the summarizer
+ *     by looking like an instruction. `model` is REQUIRED here: naming it is
+ *     what keeps the summarizer's bill separate from the agent's own (the
+ *     `.compaction()` law, 8.14.0). Token usage is reported on the event.
+ *   • `llm: (messages) => Promise<string>` — the caller's own call, unchanged
+ *     since 2.x. The caller composed the request, so the caller named the
+ *     model; the stage reports usage as unknown rather than inventing one.
  *
- * The stage CANNOT enforce this — it just calls the caller-supplied
- * `llm` function. Callers are responsible for configuring determinism.
- * Non-deterministic summarizers still work but invalidate prompt caches
- * on every turn (~5× token-cost increase on cache-enabled providers).
+ * ## What comes back is DATA
  *
- * ## When summarize does NOT fire
+ * The summary text is appended after an authored label this file writes, and
+ * the label always comes first. A summarizer that returns "IGNORE ALL
+ * PREVIOUS INSTRUCTIONS" produces an entry that still says, in the library's
+ * own words and first, that what follows is a summary written by a model and
+ * that the originals are retained.
  *
- * - `loaded.length < triggerMinEntries` → no-op (not enough history).
- * - `loaded.length <= preserveRecent` → no-op (nothing to summarize; all
- *    entries would be preserved verbatim anyway).
- * - LLM call throws → error propagates to the pipeline's executor
- *    (fail-loud, per loadRecent / writeMessages convention).
+ * ## Three ways it declines, all of them out loud
  *
- * ## Config guidance
+ *   • **not worth a call** — fewer than `minFoldEntries` foldable entries, or
+ *     fewer than `triggerMinEntries` loaded. No call. Recall still changes if
+ *     an EARLIER turn's summary is covering entries (that is the cheap turn
+ *     the write-back bought), and then the event says so; a turn where
+ *     nothing at all happened writes nothing and emits nothing.
+ *   • **summarizer failed** — the provider threw. ONE `console.warn` per
+ *     stage instance plus an event, and recall proceeds VERBATIM: a broken
+ *     summarizer degrades this strategy to `window`, it does not fail the
+ *     turn. (Through 9.13.0 the stage re-threw; a memory that cannot recall
+ *     because its optional compressor is down is a worse answer than an
+ *     uncompressed one.)
+ *   • **replacement not smaller** — the summary plus its label is no shorter
+ *     than the span it would replace. Folding then spends a call to GROW
+ *     recall and lose detail at the same time, so the fold is dropped and the
+ *     span is LATCHED: the same span is never re-asked, because the same
+ *     inputs give the same answer and re-asking is a paid call whose result
+ *     is already known (the 8.14.0 latch, keyed by the span's own ids). A
+ *     span that has GROWN is a different key and is asked again on purpose.
  *
- * Choose `triggerMinEntries - preserveRecent >= 2`. Below that, a firing
- * summarizer would compress just one entry — wasted LLM call with no
- * real compression. Defaults (trigger 20, preserve 5) summarize 15
- * entries when firing, which is a meaningful compression ratio.
+ * ## Determinism contract
  *
- * ## Summary entry shape
+ * For prompt caching to stay stable, the same span should produce the same
+ * summary. Configure `temperature: 0` (and a seed where the provider has
+ * one) on the summarizer you pass. The stage cannot enforce it — but note
+ * that write-back makes it matter far less than it did: a span is summarized
+ * once and then read back from the store.
  *
- * The synthetic entry replaces the summarized range. It has:
- *   - `id`: `summary-{earliest_turn}-to-{latest_turn}`
- *   - `value`: a `{role: 'system', content: summaryText}` message
- *   - `source.turn`: the LATEST turn that was summarized (for sorting)
- *   - `tier`: 'cold' (marks it as "condensed, may not be recent")
- *   - `source.identity`: carried over from the summarized range's first entry
+ * @see ../define.ts  the `SUMMARIZE` strategy arm that wires this
+ * @see ../../core/agent/window/strategies/summarizeOldest.ts  the same laws
+ *      applied to the LIVE window instead of to recall
  */
 import type { TypedScope } from 'footprintjs';
-import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { MemoryEntry } from '../entry/index.js';
+import type { LLMMessage as Message, LLMProvider } from '../../adapters/types.js';
+import type { MemoryStore } from '../store/index.js';
 import type { MemoryState } from './types.js';
+/**
+ * The 2.x summarizer shape: the caller makes the call and returns the text.
+ * Kept because a hand-composed pipeline that already owns its provider does
+ * not need the library to own it too.
+ */
+export type SummarizeCallback = (messages: readonly Message[]) => Promise<string>;
 export interface SummarizeConfig {
     /**
-     * LLM callback. Receives the chronological messages to summarize;
-     * must return the summary text. Caller is responsible for configuring
-     * the underlying model (temperature=0, seed, system prompt, etc.) to
-     * keep the output deterministic — see "Determinism contract" above.
+     * Who writes the summary — a provider (preferred; pair with {@link model})
+     * or the legacy callback that makes its own call.
+     *
+     * Recommend a cheap model. The point of naming a summarizer at all is that
+     * compression is not worth your main model's price.
      */
-    readonly llm: (messages: readonly Message[]) => Promise<string>;
+    readonly llm: LLMProvider | SummarizeCallback;
     /**
-     * Minimum `loaded.length` before summarization triggers. Below this,
-     * no-op — the conversation is short enough to keep verbatim. Default 20.
+     * The model id the summarizer is called with. REQUIRED when `llm` is a
+     * provider, refused as meaningless when `llm` is a callback (the callback
+     * composed its own request and named its own model there).
+     *
+     * There is no `?? agentModel` fallback, by the same reasoning
+     * `.compaction()` uses: the default had no correct case — same family and
+     * it quietly bills your main model for compression, different vendor and it
+     * sends a model id nobody has heard of.
+     */
+    readonly model?: string;
+    /**
+     * Where the summary is written back to. Omit and the fold is computed for
+     * THIS recall only and thrown away — correct, and paid for again every
+     * turn. `defaultPipeline` passes its own store, so the factory path always
+     * writes back.
+     */
+    readonly store?: MemoryStore;
+    /**
+     * Minimum `loaded.length` before a fold is considered. Below this, no-op —
+     * the conversation is short enough to keep whole. Default 20.
      */
     readonly triggerMinEntries?: number;
     /**
-     * Number of most-recent entries to preserve verbatim (NOT summarized).
-     * The oldest `loaded.length - preserveRecent` entries become a single
-     * summary entry. Default 5 — keeps recent turns intact so the agent
-     * can reference specific phrasing.
+     * How many most-recent entries stay VERBATIM. The older ones become the
+     * summary. Default 5 — recent turns keep their exact phrasing so the agent
+     * can quote them.
+     *
+     * The seam is rounded OUTWARD to a whole turn: if the cut would land in the
+     * middle of turn 7, turn 7 goes to the verbatim side entirely. A question
+     * summarized while its answer stayed raw reads like an answer to nothing.
      */
     readonly preserveRecent?: number;
     /**
-     * Optional custom system prompt for the summarizer. Default is a
-     * neutral "summarize the following conversation..." instruction.
-     * Override for domain-specific summaries (e.g., "preserve all
-     * refund-related details").
+     * Do not spend a call to fold fewer than this many entries. Default 2 — one
+     * entry "compressed" into a summary plus a label is a paid call that makes
+     * recall longer. `defineMemory` raises this to the size of the verbatim
+     * tail, which is the cost policy: never fold less than you keep.
+     */
+    readonly minFoldEntries?: number;
+    /**
+     * Override the authored instruction the summarizer is given. Domain
+     * summaries want this ("preserve every refund-related number"). Only the
+     * INSTRUCTION is yours — the transcript delimiters and the label written
+     * onto the summary entry are the library's and stay put.
      */
     readonly systemPrompt?: string;
+    /**
+     * TTL in milliseconds applied to the summary entry, counted from the SPAN's
+     * clock (the newest entry it stands for), not from the fold.
+     * `defaultPipeline` passes its `writeTtlMs` here, so a compliance retention
+     * window expires the summary WITH the turns it compressed — a summary that
+     * outlived them is exactly the leak the retention window exists to prevent.
+     */
+    readonly ttlMs?: number;
+    /**
+     * Tier for the summary entry. Default `'cold'` — condensed, not recent.
+     *
+     * Worth pairing with the load's `tiers` filter if you set one: a filter that
+     * excludes this tier hides the summary from every later recall, and a
+     * summary that is never loaded is a span that is folded (and billed) again
+     * every turn. `defineMemory` sets no tier filter, so the factory path is
+     * safe by construction.
+     */
+    readonly summaryTier?: 'hot' | 'warm' | 'cold';
+    /** `strategyId` on the emitted event. Default `'memory-summarize'`. */
+    readonly strategyId?: string;
 }
+/** Id prefix for every entry this stage writes. */
+export declare const SUMMARY_ID_PREFIX = "msg-summary-";
+/** Metadata key carrying {@link SummaryCoverage} on a summary entry. */
+export declare const SUMMARY_COVERAGE_KEY = "summarizes";
+/**
+ * What a summary entry stands for — the only thing that excludes an original
+ * from recall.
+ *
+ * `coveredIds` is the operative field and it is exact: recall drops an entry
+ * because a loaded summary NAMES it, never because a turn number falls inside
+ * a range. A turn that was half-folded (possible only for hand-composed
+ * configs; the stage rounds the seam outward) keeps the half nobody claimed.
+ */
+export interface SummaryCoverage {
+    /** Earliest turn represented. */
+    readonly fromTurn: number;
+    /** Latest turn represented. Also the entry's `source.turn`. */
+    readonly toTurn: number;
+    /** How many entries were folded. */
+    readonly entryCount: number;
+    /** The exact entries this summary stands for. */
+    readonly coveredIds: readonly string[];
+    /** Which model wrote it. Absent for the callback form — the caller knows. */
+    readonly model?: string;
+    /** When the fold happened (unix ms). */
+    readonly summarizedAtMs: number;
+}
+/** The id a fold over `[fromTurn, toTurn]` always gets. Deterministic. */
+export declare function summaryEntryId(fromTurn: number, toTurn: number): string;
+/**
+ * The coverage a summary entry carries, or `undefined` for an ordinary entry.
+ *
+ * Read through the METADATA, not the id: an id is a name and metadata is the
+ * claim. An entry named like a summary that carries no coverage stands for
+ * nothing and is treated as an ordinary entry.
+ */
+export declare function summaryCoverage(entry: MemoryEntry<unknown>): SummaryCoverage | undefined;
+/** True when this entry is a summary written by this stage. */
+export declare function isSummaryEntry(entry: MemoryEntry<unknown>): boolean;
+/** Opening of the authored label. Stable — readers and tests match on it. */
+export declare const SUMMARY_FRAME_PREFIX = "[summary of earlier turns";
 export declare function summarize(config: SummarizeConfig): (scope: TypedScope<MemoryState>) => Promise<void>;