agentfootprint 6.44.0 → 7.0.0

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

@@ -0,0 +1,68 @@
+/**
+ * Facts — stable, timeless claims about the user or world.
+ *
+ * Unlike beats (which summarize what happened in a turn) and messages
+ * (which are the raw conversation), facts capture *what's currently
+ * true*:
+ *   - Identity: "user.name" = "Alice"
+ *   - Preferences: "user.favorite_color" = "blue"
+ *   - Commitments: "task.ORD-123.status" = "refunded"
+ *
+ * Facts dedupe by `key`. The storage layer uses stable ids of the form
+ * `fact:${key}`, so a second write to the same key overwrites the
+ * first. This is the difference from beats/messages (which are
+ * append-only log entries).
+ */
+/**
+ * A single fact — a key/value claim with optional confidence +
+ * category metadata.
+ *
+ * **Key convention**: dotted path for nested taxonomies
+ * (`user.name`, `user.preferences.color`, `task.ORD-123.status`).
+ * The library doesn't enforce any structure — extractors define their
+ * own key namespaces.
+ */
+export interface Fact<V = unknown> {
+    /** Stable key — used to dedupe. */
+    readonly key: string;
+    /** The claimed value. JSON-serializable. */
+    readonly value: V;
+    /**
+     * Extractor's confidence in `[0, 1]`. Used by `pickByBudget` to
+     * prefer high-confidence facts when the budget is tight. Optional
+     * — extractors that can't estimate confidence may omit it, in
+     * which case consumers default to a neutral 0.5.
+     */
+    readonly confidence?: number;
+    /**
+     * Optional taxonomy tag — free-form string like `"identity"`,
+     * `"preference"`, `"commitment"`, `"fact"`. Useful for filtering
+     * recall by category.
+     */
+    readonly category?: string;
+    /**
+     * Ids of the source messages this fact was extracted from. Mirrors
+     * `NarrativeBeat.refs` — consumers answer "why does the agent think
+     * `user.name` is Alice?" by walking back to the raw message text.
+     * Optional because some extractors (pattern-based, aggregate) can't
+     * reliably trace a fact to a specific message. LLM-based extractors
+     * should populate it.
+     */
+    readonly refs?: readonly string[];
+}
+/** Build the stable `MemoryStore` id for a fact with the given key. */
+export declare function factId(key: string): string;
+/** True iff the string is a fact id (starts with the `fact:` prefix). */
+export declare function isFactId(id: string): boolean;
+/**
+ * Duck-typed guard — true iff `value` has the shape of a `Fact`.
+ * Used by pipelines that handle mixed-payload stores (facts +
+ * beats + raw messages) to route entries correctly.
+ */
+export declare function isFact(value: unknown): value is Fact;
+/**
+ * Clamp a value to `[0, 1]`; non-finite → 0.5 (neutral). Matches the
+ * `asImportance` convention in the beats layer so pickers can treat
+ * `confidence` and `importance` the same way.
+ */
+export declare function asConfidence(value: unknown): number;

package/dist/esm/memory/facts/writeFacts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * writeFacts — persist extracted facts to the memory store.
+ *
+ * Reads from scope:  `newFacts`, `identity`
+ * Writes to store:   MemoryEntry<Fact> per fact via `store.putMany`
+ *
+ * Ids are `fact:${key}` (set by `extractFacts` via `factId`). Because
+ * `putMany` overwrites on id collision, a second turn writing the same
+ * key REPLACES the prior entry. This is the contract for facts — they
+ * dedup by key, unlike beats and messages which are append-only.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { FactPipelineState } from './extractFacts.js';
+export interface WriteFactsConfig {
+    /** The store to persist to. Typically the same store as the pipeline's read side. */
+    readonly store: MemoryStore;
+}
+export declare function writeFacts(config: WriteFactsConfig): (scope: TypedScope<FactPipelineState>) => Promise<void>;

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

@@ -0,0 +1,2 @@
+export type { MemoryIdentity } from './types.js';
+export { identityNamespace } from './types.js';

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

@@ -0,0 +1,49 @@
+/**
+ * MemoryIdentity — hierarchical scoping for everything memory-related.
+ *
+ * The library enforces isolation at every storage call: no cross-tenant
+ * reads, no cross-principal writes, period. Enterprise deploys (Azure Entra,
+ * AWS SSO, etc.) surface tenant + principal from the incoming request;
+ * simpler deploys just use `conversationId`.
+ *
+ * Why three fields instead of one "key"?
+ *   - `tenant`     — organization / workspace / account boundary
+ *   - `principal`  — user / service-account identity within the tenant
+ *   - `conversationId` — a single thread / session for that principal
+ *
+ * Storage adapters prefix namespaces with the full identity tuple. A bug in
+ * a multi-tenant app that passes the wrong `tenant` can't accidentally read
+ * another customer's memory — the tuple mismatch surfaces as "no data"
+ * rather than a silent leak.
+ *
+ * Fields after `conversationId` are reserved for future expansion (agent id,
+ * role, etc.) without breaking existing stores.
+ */
+export interface MemoryIdentity {
+    /**
+     * Optional organization / workspace / account boundary. Omit for
+     * single-tenant deploys. Storage adapters MUST refuse cross-tenant reads
+     * when this field is set.
+     */
+    readonly tenant?: string;
+    /**
+     * Optional user / service-account identity within the tenant. Isolates
+     * memory per end-user inside a shared tenant.
+     */
+    readonly principal?: string;
+    /**
+     * Required — the conversation / session / thread id. Stable across
+     * multiple `agent.run()` calls so history accumulates correctly.
+     */
+    readonly conversationId: string;
+}
+/**
+ * Encode a MemoryIdentity as a deterministic storage namespace. Used by
+ * storage adapters that need a single string key (Redis, localStorage,
+ * filesystem paths). Format is stable across library versions — adapters
+ * can safely use it for long-lived keys.
+ *
+ * Empty `tenant` / `principal` collapse to `_` so the format has a constant
+ * shape (easy to parse, easy to list by prefix).
+ */
+export declare function identityNamespace(identity: MemoryIdentity): string;

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

@@ -0,0 +1,19 @@
+/**
+ * Memory subsystem — narrative beats, fact extraction, embedding-based
+ * retrieval, and pipelines that compose them.
+ *
+ * Re-exported from agentfootprint's main entry. See individual module
+ * READMEs for usage.
+ */
+export * from './beats/index.js';
+export * from './causal/index.js';
+export * from './embedding/index.js';
+export * from './entry/index.js';
+export * from './facts/index.js';
+export * from './identity/index.js';
+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 WindowStrategy, 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 { defineMemory } from './define.js';

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

@@ -0,0 +1,59 @@
+import type { LLMProvider } from '../../adapters/types.js';
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryEntry } from '../entry/index.js';
+import type { MemoryPipeline } from './types.js';
+import { type FactPipelineState, type FactExtractor } from '../facts/index.js';
+import { type NarrativeBeat, type BeatExtractor, type ExtractBeatsState } from '../beats/index.js';
+export interface AutoPipelineConfig {
+    /** The store both extractors share. */
+    readonly store: MemoryStore;
+    /**
+     * When present, upgrades both fact AND beat extraction to LLM-backed
+     * variants. Typically a cheap/fast model like Claude Haiku. Omit to
+     * use the free heuristic + regex defaults.
+     */
+    readonly provider?: LLMProvider;
+    /**
+     * Override the fact extractor explicitly. Takes precedence over
+     * `provider`. Use when you want facts via LLM but beats via heuristic,
+     * or vice-versa.
+     */
+    readonly factExtractor?: FactExtractor;
+    /**
+     * Override the beat extractor explicitly. Takes precedence over
+     * `provider`.
+     */
+    readonly beatExtractor?: BeatExtractor;
+    /**
+     * Upper bound on the `store.list` page size during read. Large enough
+     * to fit typical identity+history; raise for long-lived agents with
+     * dozens of fact categories and hundreds of beats. Default `200`.
+     */
+    readonly loadLimit?: number;
+    /** Tier filter for read. */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /** Tier to tag newly written entries (both facts and beats). */
+    readonly writeTier?: 'hot' | 'warm' | 'cold';
+    /** TTL in ms applied to newly written entries. */
+    readonly writeTtlMs?: number;
+    /** Header for the facts block in the injected system message. */
+    readonly factsHeader?: string;
+    /** Lead-in phrase for the narrative paragraph. Default `"From earlier: "`. */
+    readonly narrativeLeadIn?: string;
+    /**
+     * When `true`, appends `(conf 0.xx)` after each fact. Off by default
+     * — confidence is noise for the LLM in typical flows.
+     */
+    readonly showConfidence?: boolean;
+    /**
+     * When `true`, appends `(refs: msg-x-y, ...)` after each beat line.
+     * Off by default.
+     */
+    readonly showRefs?: boolean;
+}
+/** State used by the auto pipeline's subflows. */
+export interface AutoPipelineState extends FactPipelineState, ExtractBeatsState {
+    /** Beats loaded from the store during auto-READ. */
+    loadedBeats?: readonly MemoryEntry<NarrativeBeat>[];
+}
+export declare function autoPipeline(config: AutoPipelineConfig): MemoryPipeline;

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>;