agentfootprint 6.43.0 → 6.45.0

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

@@ -0,0 +1,49 @@
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryPipeline } from './types.js';
+export interface DefaultPipelineConfig {
+    /** The store both subflows share. */
+    readonly store: MemoryStore;
+    /** How many recent entries to load per turn. Default 20 (see loadRecent). */
+    readonly loadCount?: number;
+    /**
+     * Token reserve for prompt headers / new user message / safety margin.
+     * Default 256.
+     */
+    readonly reserveTokens?: number;
+    /** Minimum memory-token budget before the picker skips injection. Default 100. */
+    readonly minimumTokens?: number;
+    /**
+     * Hard cap on entries selected per turn, independent of tokens. Helps
+     * with "lost-in-the-middle" degradation. Default: no cap.
+     */
+    readonly maxEntries?: number;
+    /**
+     * Optional tier constraint — e.g. `['hot']` to read only entries
+     * marked `hot` by the write side. Combines with `loadCount` (cap
+     * AFTER filter).
+     */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /**
+     * Optional tier written entries are tagged with. Matches the `tiers`
+     * read filter when both sides want to coordinate tier policy.
+     */
+    readonly writeTier?: 'hot' | 'warm' | 'cold';
+    /**
+     * Optional write-side TTL in milliseconds from `now`. Every written
+     * entry expires this long after storage. Useful for compliance
+     * retention windows.
+     */
+    readonly writeTtlMs?: number;
+    /**
+     * Override for the formatter's header text. Omit to use the default
+     * "Relevant context from prior conversations..." phrasing.
+     */
+    readonly formatHeader?: string;
+    /** Override for the formatter's footer text. Default: empty. */
+    readonly formatFooter?: string;
+}
+/**
+ * Build the default read + write pipelines sharing a single store.
+ * Returns two FlowChart subflows ready to be mounted by the wire layer.
+ */
+export declare function defaultPipeline(config: DefaultPipelineConfig): MemoryPipeline;

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

@@ -0,0 +1,28 @@
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryPipeline } from './types.js';
+export interface EphemeralPipelineConfig {
+    /** The store to read from. Writes never happen — backend can be read-only. */
+    readonly store: MemoryStore;
+    /** How many recent entries to load per turn. Default 20. */
+    readonly loadCount?: number;
+    /** Token reserve for prompt headers / safety margin. Default 256. */
+    readonly reserveTokens?: number;
+    /** Minimum memory-token budget before the picker skips injection. Default 100. */
+    readonly minimumTokens?: number;
+    /** Hard cap on entries selected per turn. Default: no cap. */
+    readonly maxEntries?: number;
+    /**
+     * Optional tier filter — e.g. `['hot']` to load only pre-seeded "hot"
+     * entries. Omitted means all tiers.
+     */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /** Override for the formatter's header text. */
+    readonly formatHeader?: string;
+    /** Override for the formatter's footer text. */
+    readonly formatFooter?: string;
+}
+/**
+ * Build an ephemeral (read-only) pipeline. The returned object has
+ * `write: undefined`; wire helpers no-op on it.
+ */
+export declare function ephemeralPipeline(config: EphemeralPipelineConfig): MemoryPipeline;

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

@@ -0,0 +1,26 @@
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryPipeline } from './types.js';
+import type { FactExtractor } from '../facts/extractor.js';
+export interface FactPipelineConfig {
+    /** The store both subflows share. */
+    readonly store: MemoryStore;
+    /**
+     * Fact extractor. Defaults to `patternFactExtractor()` — zero-dep,
+     * zero-cost, baseline quality. Swap for
+     * `llmFactExtractor({ provider })` for semantic quality.
+     */
+    readonly extractor?: FactExtractor;
+    /** Forwarded to `loadFacts` (upper bound on `list` page size). */
+    readonly loadLimit?: number;
+    /** Tier filter for read (e.g. `['hot']`). */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /** Tier to tag written facts with. */
+    readonly writeTier?: 'hot' | 'warm' | 'cold';
+    /** Optional TTL for written facts (ms from write time). */
+    readonly writeTtlMs?: number;
+    /** Forwarded to `formatFacts`. */
+    readonly formatHeader?: string;
+    readonly formatFooter?: string;
+    readonly formatShowConfidence?: boolean;
+}
+export declare function factPipeline(config: FactPipelineConfig): MemoryPipeline;

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

@@ -0,0 +1,13 @@
+export type { MemoryPipeline } from './types.js';
+export { defaultPipeline } from './default.js';
+export type { DefaultPipelineConfig } from './default.js';
+export { ephemeralPipeline } from './ephemeral.js';
+export type { EphemeralPipelineConfig } from './ephemeral.js';
+export { narrativePipeline } from './narrative.js';
+export type { NarrativePipelineConfig } from './narrative.js';
+export { semanticPipeline } from './semantic.js';
+export type { SemanticPipelineConfig } from './semantic.js';
+export { factPipeline } from './fact.js';
+export type { FactPipelineConfig } from './fact.js';
+export { autoPipeline } from './auto.js';
+export type { AutoPipelineConfig, AutoPipelineState } from './auto.js';

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

@@ -0,0 +1,35 @@
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryPipeline } from './types.js';
+import type { BeatExtractor } from '../beats/extractor.js';
+export interface NarrativePipelineConfig {
+    /** The store both subflows share. */
+    readonly store: MemoryStore;
+    /**
+     * Beat extractor. Defaults to `heuristicExtractor()` — zero-dep,
+     * zero-cost, baseline quality. Swap for `llmExtractor({ provider })`
+     * for semantic quality.
+     */
+    readonly extractor?: BeatExtractor;
+    /** Forwarded to `loadRecent` (how many beats to consider per turn). */
+    readonly loadCount?: number;
+    /** Forwarded to `pickByBudget`. */
+    readonly reserveTokens?: number;
+    readonly minimumTokens?: number;
+    readonly maxEntries?: number;
+    /** Tier filter for read (e.g. `['hot']`). */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /** Tier to tag written beats with. */
+    readonly writeTier?: 'hot' | 'warm' | 'cold';
+    /** Optional TTL for written beats (ms from write time). */
+    readonly writeTtlMs?: number;
+    /** Forwarded to `formatAsNarrative`. */
+    readonly formatHeader?: string;
+    readonly formatFooter?: string;
+    readonly formatShowRefs?: boolean;
+    readonly formatLeadIn?: string;
+}
+/**
+ * Build the narrative read + write pipelines sharing a single store.
+ * Returns `{ read, write }` ready to be passed to `Agent.memory()` via the appropriate `defineMemory` config (or used directly via `mountMemoryRead`/`mountMemoryWrite`).
+ */
+export declare function narrativePipeline(config: NarrativePipelineConfig): MemoryPipeline;

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

@@ -0,0 +1,37 @@
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryPipeline } from './types.js';
+import type { Embedder } from '../embedding/types.js';
+export interface SemanticPipelineConfig {
+    /** Vector-capable store. Must implement `search()`. */
+    readonly store: MemoryStore;
+    /** Embedder used for both write-side indexing and read-side query. */
+    readonly embedder: Embedder;
+    /**
+     * Stable id for the embedder — attached to written entries and used
+     * as a filter at read time so a later embedder swap doesn't produce
+     * cross-model similarity pollution. Example: `"openai-text-embedding-3-small"`.
+     */
+    readonly embedderId?: string;
+    /** Top-k entries to consider per turn. Default 20; picker narrows further. */
+    readonly k?: number;
+    /** Cosine threshold below which matches are dropped. Default none. */
+    readonly minScore?: number;
+    /** Tier filter for retrieval. */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /** Tier to tag writes with. */
+    readonly writeTier?: 'hot' | 'warm' | 'cold';
+    /** TTL for written entries (ms from write time). */
+    readonly writeTtlMs?: number;
+    /** Forwarded to `pickByBudget`. */
+    readonly reserveTokens?: number;
+    readonly minimumTokens?: number;
+    readonly maxEntries?: number;
+    /** Forwarded to `formatDefault`. */
+    readonly formatHeader?: string;
+    readonly formatFooter?: string;
+}
+/**
+ * Build the semantic read + write pipelines sharing a single store.
+ * Returns `{ read, write }` ready to pass to `Agent.memory()` via the appropriate `defineMemory` config (or used directly via `mountMemoryRead`/`mountMemoryWrite`).
+ */
+export declare function semanticPipeline(config: SemanticPipelineConfig): MemoryPipeline;

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

@@ -0,0 +1,31 @@
+/**
+ * Pipeline types — what a memory pipeline preset returns to the wire layer.
+ *
+ * The wire layer (Layer 5) mounts these two flowcharts as subflows inside
+ * the agent's main flowchart:
+ *   - `read` runs beforeTurn — produces `scope.formatted` for injection
+ *   - `write` runs afterTurn — persists `scope.newMessages`
+ *
+ * Having BOTH returned as a bundle keeps the two sides coupled to a
+ * single store/config choice: you can't accidentally use
+ * `.memory(definition)` with `preset2.write` and end up
+ * writing to a different store than you read from.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { MemoryState } from '../stages/index.js';
+/**
+ * The two flowcharts that together form a memory pipeline. Either may be
+ * `undefined` for one-sided pipelines (e.g. `ephemeral` has no `write`).
+ */
+export interface MemoryPipeline {
+    /**
+     * Read subflow — runs before each agent turn to populate
+     * `scope.formatted` with memory content to inject.
+     */
+    readonly read: FlowChart<MemoryState>;
+    /**
+     * Write subflow — runs after each turn to persist `scope.newMessages`.
+     * Optional: `ephemeral` and `readonly` pipelines omit this.
+     */
+    readonly write?: FlowChart<MemoryState>;
+}

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

@@ -0,0 +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)
+ *
+ * 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.
+ *
+ * Default format:
+ *   One `system` message containing a citation-tagged block per entry:
+ *
+ *     <memory source="turn:5" updated="2026-04-18T06:00:00Z">
+ *     User said: I live in San Francisco.
+ *     </memory>
+ *
+ *   Citation tags let the LLM reference sources in its response; the
+ *   Anthropic-reviewer ask ("recall should carry source").
+ *
+ *   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."
+ *
+ *   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.
+ */
+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';
+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.).
+     */
+    readonly header?: string;
+    /**
+     * Footer appended after all entries. Empty by default. Useful for
+     * explicit guidance ("Use this context only when relevant. Do not
+     * mention retrieval unless asked.").
+     */
+    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.
+     */
+    readonly renderEntry?: (entry: MemoryEntry<Message>) => string;
+    /**
+     * When `true`, inject even if `selected` is empty (emits only header
+     * and footer). Usually NOT desired — an empty memory block is noise.
+     * Default: skip emitting when selected is empty.
+     */
+    readonly emitWhenEmpty?: boolean;
+}
+export declare function formatDefault(config?: FormatDefaultConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

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

@@ -0,0 +1,13 @@
+export type { MemoryState } from './types.js';
+export { loadRecent } from './loadRecent.js';
+export type { LoadRecentConfig } from './loadRecent.js';
+export { writeMessages } from './writeMessages.js';
+export type { WriteMessagesConfig } from './writeMessages.js';
+export { pickByBudget } from './pickByBudget.js';
+export type { PickByBudgetConfig } from './pickByBudget.js';
+export { formatDefault } from './formatDefault.js';
+export type { FormatDefaultConfig } from './formatDefault.js';
+export { approximateTokenCounter, countMessageTokens } from './tokenize.js';
+export type { TokenCounter } from './tokenize.js';
+export { summarize } from './summarize.js';
+export type { SummarizeConfig } from './summarize.js';

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

@@ -0,0 +1,49 @@
+/**
+ * loadRecent — read-side stage that injects the N most recent stored
+ * messages into scope.loaded.
+ *
+ * Simplest possible retrieval: "what did we say last?" — no scoring,
+ * no ranking, no decay, just chronological tail. Appropriate for small
+ * conversations or as the warm-tier component of a hybrid pipeline.
+ *
+ * Reads from scope:  `identity`
+ * Writes to scope:   `loaded` (appends — does not replace)
+ *
+ * Why append, not replace?
+ *   Pipelines typically run multiple load stages (recent + semantic +
+ *   facts). Appending lets each contribute without coordination. The
+ *   picker stage (Layer 3) deduplicates + ranks the combined set.
+ *
+ * Why `count` primary, tokens secondary?
+ *   Token counting needs a tokenizer — adds a dependency. `count` is
+ *   universally available and "most recent N" is the most common ask.
+ *   Token-budget enforcement happens in the picker stage where it
+ *   naturally composes with other signals.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryState } from './types.js';
+export interface LoadRecentConfig {
+    /** The store to read from. */
+    readonly store: MemoryStore;
+    /**
+     * Maximum number of entries to return. Defaults to 20 — large enough
+     * for typical chat recency, small enough to fit most context windows.
+     * Stores may cap this lower; in that case you get whatever fits.
+     */
+    readonly count?: number;
+    /**
+     * Optional tier filter. When set, only loads entries marked with one
+     * of these tiers (e.g. `['hot']` for aggressive context management).
+     * Omitted filter = all tiers, consistent with MemoryStore.list default.
+     */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+}
+/**
+ * Build a stage function that loads recent entries into `scope.loaded`.
+ *
+ * The returned stage is async and side-effect-free on failure: if the
+ * store throws, the stage re-throws (fail-loud) — callers wrap with
+ * `withRetry` / `withFallback` if they want degrade-to-empty behavior.
+ */
+export declare function loadRecent(config: LoadRecentConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

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

@@ -0,0 +1,63 @@
+import type { FlowChartBuilder } from 'footprintjs';
+import type { MemoryState } from './types.js';
+import { type TokenCounter } from './tokenize.js';
+/**
+ * Reusable shape for a **composable pipeline segment** — a function that
+ * appends one or more stages to a builder and returns the builder. This
+ * is the memory layer's convention for packaging multi-stage work
+ * (decider + branches, multi-stage sub-pipelines) as a single unit that
+ * consumers can drop into any flowchart:
+ *
+ * ```ts
+ * let b = flowChart<MyState>('Seed', seed, 'seed');
+ * b = pickByBudget(config)(b);          // appends a decider + 3 branches
+ * b = b.addFunction('Format', fmt, ...);
+ * ```
+ *
+ * Generic in `T` so segments targeting the memory layer can be composed
+ * into host flowcharts whose state extends `MemoryState`. Future
+ * segments (NarrativeMemory, SemanticRetrieval, FactExtraction) follow
+ * the same shape for uniform composition ergonomics.
+ */
+export type PipelineSegment<T extends object> = (builder: FlowChartBuilder<T>) => FlowChartBuilder<T>;
+export interface PickByBudgetConfig {
+    /**
+     * Tokens to keep in reserve — not used for memory. Default 256.
+     * Covers system-prompt overhead, new user message headroom, and safety
+     * margin against token-counter approximation error. Tune per model.
+     */
+    readonly reserveTokens?: number;
+    /**
+     * Hard floor on memory tokens. If the budget minus reserve is less than
+     * this, NO memory is injected (better to skip than inject a fragment).
+     * Default 100 — under 100 tokens of memory is usually worse than none.
+     */
+    readonly minimumTokens?: number;
+    /**
+     * Pluggable token counter — defaults to `approximateTokenCounter`
+     * (1 token ≈ 4 chars). Swap for a real tokenizer when accuracy matters.
+     */
+    readonly countTokens?: TokenCounter;
+    /**
+     * Optional cap on the NUMBER of entries, independent of tokens.
+     * Useful when the budget is large enough to include hundreds of
+     * entries but the LLM's "lost-in-the-middle" effect degrades quality
+     * past ~20. Default: no cap (budget is the only limit).
+     */
+    readonly maxEntries?: number;
+}
+/**
+ * Append the pick-by-budget decider + branches to `builder`. Returns
+ * the builder so calls chain naturally:
+ *
+ * ```ts
+ * let b = flowChart<MemoryState>('LoadRecent', loadRecent(config), 'load-recent');
+ * b = pickByBudget(pickConfig)(b);
+ * b = b.addFunction('Format', formatDefault(formatConfig), 'format-default');
+ * ```
+ *
+ * Generic in `T` so consumers whose scope extends `MemoryState` (e.g.,
+ * an AgentLoopState that embeds memory fields) can compose this into
+ * their own pipeline without casting.
+ */
+export declare function pickByBudget<T extends MemoryState = MemoryState>(config?: PickByBudgetConfig): PipelineSegment<T>;

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

@@ -0,0 +1,87 @@
+/**
+ * summarize — stage that compresses old loaded entries into a single
+ * summary entry, preserving the most-recent N verbatim.
+ *
+ * Reads from scope:  `loaded`
+ * Writes to scope:   `loaded` (mutated: oldest entries replaced by one
+ *                     synthetic summary entry)
+ *
+ * Where this fits in the pipeline:
+ *
+ *   loadRecent → summarize → pickByBudget → formatDefault
+ *
+ * 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.
+ *
+ * ## Determinism contract (Anthropic-reviewer ask)
+ *
+ * For prompt caching to stay stable across runs, the summary content
+ * MUST be the same each time for the same input. This requires:
+ *
+ *   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.
+ *
+ * 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).
+ *
+ * ## When summarize does NOT fire
+ *
+ * - `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).
+ *
+ * ## Config guidance
+ *
+ * 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.
+ *
+ * ## Summary entry shape
+ *
+ * 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
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { MemoryState } from './types.js';
+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.
+     */
+    readonly llm: (messages: readonly Message[]) => Promise<string>;
+    /**
+     * Minimum `loaded.length` before summarization triggers. Below this,
+     * no-op — the conversation is short enough to keep verbatim. 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.
+     */
+    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").
+     */
+    readonly systemPrompt?: string;
+}
+export declare function summarize(config: SummarizeConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

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

@@ -0,0 +1,43 @@
+/**
+ * tokenize — approximate token counter for budget-aware memory stages.
+ *
+ * Memory stages need to answer "how many tokens does this content cost?"
+ * to decide what fits in a budget. A real tokenizer (tiktoken, Anthropic's
+ * tokenizer, etc.) is accurate but:
+ *
+ *   - Adds a dependency (tiktoken is ~2MB, has WASM loading quirks).
+ *   - Differs per model family (Claude counts differently from GPT).
+ *   - Pulls frontend bundles from small to huge.
+ *
+ * Phase 1 uses a deterministic approximation: 1 token ≈ 4 characters of
+ * English text. The constant comes from OpenAI's own documentation and
+ * is within ~15% for typical chat content. For "how much memory can I
+ * inject into an 8K context", 15% is fine.
+ *
+ * Consumers who need exact counts pass their own `TokenCounter` through
+ * the pipeline config. When that lands (Phase 2), this default stays as
+ * the dependency-free baseline.
+ */
+import type { LLMMessage as Message } from '../../adapters/types.js';
+/** A function that returns the token count of a string. */
+export type TokenCounter = (text: string) => number;
+/**
+ * Default approximation — 1 token per ~4 characters. Low-accuracy,
+ * zero-dependency, deterministic (same input → same count). Good enough
+ * for budget-based decisions; replace via pipeline config for accuracy.
+ *
+ * Accuracy notes:
+ *   - ASCII English: within ~15% of tiktoken.
+ *   - CJK / emoji / heavy unicode: can undercount by ~2× because
+ *     `String.length` counts UTF-16 code units, and CJK chars often
+ *     take multiple tokens each. Use a real tokenizer for these workloads.
+ *   - Code / JSON: reasonably accurate (punctuation-heavy is ~4 chars/tok).
+ */
+export declare const approximateTokenCounter: TokenCounter;
+/**
+ * Count tokens in a single message. Handles string content and the
+ * content-block array variant (where each block has its own text field).
+ * Non-text blocks (tool calls, images) contribute a small constant to
+ * reflect their structural cost.
+ */
+export declare function countMessageTokens(message: Message, counter?: TokenCounter): number;

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

@@ -0,0 +1,75 @@
+/**
+ * MemoryState — shared scope for every stage in a memory pipeline.
+ *
+ * Each stage reads some fields and writes others; the pipeline's narrative
+ * shows who wrote what. Fields are added as layers need them — this is the
+ * minimal shape for Layer 2 (load + write stages). Layer 3 will add
+ * `candidates`, `selected`, `formatted`; Layer 8 will add summarization
+ * fields. Every field is optional so pipelines can mix stages freely.
+ *
+ * Shape design: fields cluster by pipeline direction.
+ *   - `identity` / `turnNumber` / `contextTokensRemaining` are INPUTS
+ *     set by the wire layer before the pipeline runs.
+ *   - `loaded` is the READ-SIDE output.
+ *   - `newMessages` is the WRITE-SIDE input.
+ *   - (later layers: `candidates`, `selected`, `formatted`, `saveBatch`)
+ */
+import type { MemoryIdentity } from '../identity/index.js';
+import type { MemoryEntry } from '../entry/index.js';
+import type { LLMMessage as Message } from '../../adapters/types.js';
+export interface MemoryState {
+    /**
+     * Scoping for every storage call this pipeline makes. Wire layer
+     * populates this before the pipeline runs; stages MUST NOT mutate it.
+     */
+    readonly identity: MemoryIdentity;
+    /**
+     * Run-local turn counter — 1 for the first `agent.run`, 2 for the second,
+     * and so on within the same conversationId. Written into `MemoryEntry.source`
+     * by write-side stages for provenance.
+     */
+    readonly turnNumber: number;
+    /**
+     * Context-window pressure signal (MemGPT-reviewer ask). Populated by the
+     * wire layer with `model.contextWindow - tokensUsedSoFar`. Picker stages
+     * (Layer 3) use this to decide how much memory to inject.
+     *
+     * 0 or negative values should be treated by consumers as "no headroom" —
+     * stages typically skip or truncate memory injection in that case.
+     */
+    readonly contextTokensRemaining: number;
+    /**
+     * Read-side output: entries loaded from the store this turn. Stages
+     * typically APPEND rather than replace so multiple load stages can
+     * contribute (e.g. recent-messages + semantic-retrieval + facts).
+     */
+    loaded: MemoryEntry<Message>[];
+    /**
+     * Picker output — the subset of `loaded` that fits the context budget,
+     * in chronological order (oldest first). Format stages consume this.
+     * Empty array when the picker decided NOT to inject memory (budget
+     * below minimum, or no entries loaded).
+     */
+    selected: MemoryEntry<Message>[];
+    /**
+     * Formatter output — the `Message[]` that will be injected into the
+     * LLM's prompt this turn. The wire layer merges this into the agent's
+     * messages array (typically as `system` messages before the user turn).
+     */
+    formatted: Message[];
+    /**
+     * Write-side input: messages to persist at the end of this turn. The
+     * wire layer populates from the agent's final message state;
+     * `writeMessages` wraps each as a `MemoryEntry` and calls `store.put`.
+     */
+    newMessages: Message[];
+    /**
+     * Write-side input (CAUSAL pipelines): evidence harvested during the run by
+     * `causalEvidenceRecorder` — decisions, tool calls, iterations, duration,
+     * token usage. Populated by the wire layer via the mount's `evidenceSource`;
+     * undefined for non-causal pipelines (writeSnapshot falls back to zeros).
+     */
+    runEvidence?: import('../causal/evidenceRecorder.js').RunEvidence;
+    /** Escape hatch for pipeline-specific fields. Typed per-pipeline as needed. */
+    [key: string]: unknown;
+}