agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,276 @@
+/**
+ * Memory subsystem — public type surface.
+ *
+ * THE 2D mental model the library teaches:
+ *
+ *     MEMORY = TYPE × STRATEGY × STORE
+ *
+ *     TYPE       — what shape of memory you're keeping
+ *                  (Episodic messages / Semantic facts / Narrative beats /
+ *                   Causal footprintjs snapshots)
+ *     STRATEGY   — how to fit content into the next LLM call
+ *                  (Window / Budget / Summarize / TopK / Extract / Decay / Hybrid)
+ *     STORE      — where the bytes live
+ *                  (InMemoryStore / Redis / Postgres / DynamoDB / Vector ...)
+ *
+ * Strategy is universal — same Window works for Episodic and for Causal.
+ * That's why examples are organized by strategy (the discipline) not by
+ * type (the shape).
+ *
+ * Pattern: Single-Source-of-Truth const objects + discriminated union.
+ *          Mirrors `src/conventions.ts` (SUBFLOW_IDS, INJECTION_KEYS).
+ *          NEVER enums (TS enums emit runtime objects + opacity).
+ *          Const-as-const erases at compile time, accepts string literals,
+ *          and gives consumers IDE autocomplete + refactor safety.
+ *
+ * Role:    Layer-1 contract for the memory subsystem. Step 2's
+ *          `defineMemory()` factory consumes these to build pipelines;
+ *          Step 4's `Agent.memory()` builder mounts the resulting
+ *          definitions; Step 5's Causal machinery extends them.
+ *
+ * Emits:   Indirectly — every memory pipeline emits the unified
+ *          `agentfootprint.context.injected` event with `source: 'memory'`
+ *          when its read subflow places content into the messages slot.
+ *
+ * @see ./define.ts          for the `defineMemory()` factory itself
+ * @see ../../docs-next      for guides + the 7 strategy examples
+ * @see MEMORY.md            for the load-bearing design memory
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { ContextRole } from '../events/types.js';
+import type { Embedder } from './embedding/index.js';
+import type { MemoryStore } from './store/index.js';
+/**
+ * What shape of memory you're keeping.
+ *
+ * - `EPISODIC`  — raw conversation messages, replayed on next turn
+ * - `SEMANTIC`  — extracted structured facts, deduped on key
+ * - `NARRATIVE` — beats / summaries of prior runs (append-only)
+ * - `CAUSAL`    — footprintjs execution snapshots, the differentiator
+ *                 (replays stored decisions + tool evidence for "why?"
+ *                 follow-ups — harvested automatically per run)
+ */
+export declare const MEMORY_TYPES: {
+    readonly EPISODIC: "episodic";
+    readonly SEMANTIC: "semantic";
+    readonly NARRATIVE: "narrative";
+    readonly CAUSAL: "causal";
+};
+export type MemoryType = (typeof MEMORY_TYPES)[keyof typeof MEMORY_TYPES];
+/**
+ * How content is selected / compressed for the next LLM call.
+ *
+ * Universal across types. A `WINDOW` strategy on an Episodic store keeps
+ * the last N messages; on a Causal store it keeps the last N snapshots.
+ * Mix and match.
+ */
+export declare const MEMORY_STRATEGIES: {
+    readonly WINDOW: "window";
+    readonly BUDGET: "budget";
+    readonly SUMMARIZE: "summarize";
+    readonly TOP_K: "topK";
+    readonly EXTRACT: "extract";
+    readonly DECAY: "decay";
+    readonly HYBRID: "hybrid";
+};
+export type MemoryStrategyKind = (typeof MEMORY_STRATEGIES)[keyof typeof MEMORY_STRATEGIES];
+/**
+ * When the memory's READ subflow runs.
+ *
+ * Default `TURN_START` reads memory once per `agent.run()`. Use
+ * `EVERY_ITERATION` only when the strategy is sensitive to in-loop tool
+ * results — every-iteration multiplies store-latency by iteration-count.
+ */
+export declare const MEMORY_TIMING: {
+    readonly EVERY_ITERATION: "every-iteration";
+    readonly TURN_START: "turn-start";
+};
+export type MemoryTiming = (typeof MEMORY_TIMING)[keyof typeof MEMORY_TIMING];
+/**
+ * For Causal memory only — which slice of a footprintjs snapshot to
+ * inject. Snapshots can run 100KB+; projecting prevents context blowup.
+ *
+ * - `DECISIONS` — `decide()`/`select()` evidence only (the "why" chain)
+ * - `COMMITS`   — commitLog only (every state write, ordered)
+ * - `NARRATIVE` — narrative entries only (human-readable trace)
+ * - `FULL`      — entire snapshot (use sparingly)
+ */
+export declare const SNAPSHOT_PROJECTIONS: {
+    readonly DECISIONS: "decisions";
+    readonly COMMITS: "commits";
+    readonly NARRATIVE: "narrative";
+    readonly FULL: "full";
+};
+export type SnapshotProjection = (typeof SNAPSHOT_PROJECTIONS)[keyof typeof SNAPSHOT_PROJECTIONS];
+/** Window — keep the last `size` entries. Pure rule, no LLM, no embedder. */
+export interface WindowStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.WINDOW;
+    readonly size: number;
+}
+/**
+ * Budget — pick entries that fit within a token budget. Used as a
+ * decider stage: skip-if-empty | skip-if-no-budget | pick-by-tokens.
+ */
+export interface BudgetStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.BUDGET;
+    /** Reserve N tokens for prompt headers / new user message. Default 256. */
+    readonly reserveTokens?: number;
+    /** Skip injection below this token floor. Default 100. */
+    readonly minimumTokens?: number;
+    /** Hard cap on entries to inject — guards against "lost-in-the-middle". */
+    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."
+ */
+export interface SummarizeStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.SUMMARIZE;
+    /** Keep this many most-recent turns uncompressed. */
+    readonly recent: number;
+    /** LLM that does the compression — recommend a cheap model (haiku). */
+    readonly llm: LLMProvider;
+}
+/**
+ * Top-K — embed the user's query, retrieve top-K by cosine similarity.
+ * STRICT threshold: when no entry meets the threshold, return EMPTY.
+ * No fallback — garbage in context is worse than no memory.
+ */
+export interface TopKStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.TOP_K;
+    readonly topK: number;
+    /** Min cosine similarity. Strict — no fallback below this. Default 0.7. */
+    readonly threshold?: number;
+    readonly embedder: Embedder;
+}
+/**
+ * Extract — on WRITE, an LLM (or pattern matcher) distills entries from
+ * raw messages into structured shapes (facts/beats). Usually paired with
+ * a load-side strategy like TopK or Window for the read direction.
+ */
+export interface ExtractStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.EXTRACT;
+    /** Pattern-based (regex heuristics, free) or LLM-based (paid). */
+    readonly extractor: 'pattern' | 'llm';
+    /** Required when `extractor: 'llm'`. */
+    readonly llm?: LLMProvider;
+    /** Discard extractions below this confidence. Default 0.7. */
+    readonly minConfidence?: number;
+    /** Cap entries extracted per turn. Default 5. */
+    readonly maxPerTurn?: number;
+}
+/**
+ * Decay — score entries by `recency × accessCount`, drop below floor.
+ * For long-running agents where unused memory should fade.
+ */
+export interface DecayStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.DECAY;
+    /** Half-life in milliseconds for the recency component. */
+    readonly halfLifeMs: number;
+    /** Drop entries scoring below this. Default 0.1. */
+    readonly minScore?: number;
+}
+/**
+ * Hybrid — compose multiple strategies. Each sub-strategy runs as its
+ * own selector branch; results are merged in the order listed.
+ */
+export interface HybridStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.HYBRID;
+    readonly strategies: ReadonlyArray<Exclude<Strategy, HybridStrategy>>;
+}
+/** The full strategy union — discriminated by `kind`. */
+export type Strategy = WindowStrategy | BudgetStrategy | SummarizeStrategy | TopKStrategy | ExtractStrategy | DecayStrategy | HybridStrategy;
+/**
+ * Reserved API surface for content redaction before memory writes.
+ * Impl is deferred; the field exists now so adding redaction later
+ * is non-breaking. Snapshot/episodic writes may carry PII — this is
+ * the integration point.
+ */
+export interface MemoryRedactionPolicy {
+    /** Patterns to mask in stored content. */
+    readonly patterns?: readonly RegExp[];
+    /** Replacement string. Default `'[REDACTED]'`. */
+    readonly replacement?: string;
+}
+/**
+ * The opaque value `defineMemory()` returns. `Agent.memory()` consumes
+ * one of these per memory the consumer registers; multiple definitions
+ * layer cleanly via per-id scope keys (`memoryInjection_${id}`).
+ *
+ * Generic `T` is the payload shape stored — `Message` for episodic,
+ * `Fact` for semantic, `NarrativeBeat` for narrative, `RunSnapshot` for
+ * causal. The factory infers `T` from `type`.
+ */
+export interface MemoryDefinition<T = unknown> {
+    /** Stable identifier. Becomes the scope-key suffix and the Lens label. */
+    readonly id: string;
+    /** Surfaces in narrative / Lens hover. */
+    readonly description?: string;
+    /** Which TYPE shape — gates legal STRATEGY combinations. */
+    readonly type: MemoryType;
+    /** Compiled read subflow (built by the factory from type × strategy). */
+    readonly read: ReadonlyMemoryFlowChart<T>;
+    /** Compiled write subflow. Optional — `EPHEMERAL`-style configs omit. */
+    readonly write?: ReadonlyMemoryFlowChart<T>;
+    /** When `read` runs. Default `TURN_START`. */
+    readonly timing: MemoryTiming;
+    /** Role to use when injecting formatted content into the messages slot. */
+    readonly asRole: ContextRole;
+    /** Reserved for a future release — patterns to redact before write. */
+    readonly redact?: MemoryRedactionPolicy;
+    /** Snapshot projection — only meaningful when `type === CAUSAL`. */
+    readonly projection?: SnapshotProjection;
+}
+/**
+ * Opaque tag for the compiled flowchart the factory hands back.
+ * The actual type is `FlowChart<MemoryState>` from footprintjs but we
+ * keep it nominal here so consumers can't reach in. The phantom type
+ * parameter is preserved so consumers can write `ReadonlyMemoryFlowChart<MyShape>`
+ * for documentation, even though the brand erases the parameter at runtime.
+ */
+export type ReadonlyMemoryFlowChart<_T> = {
+    readonly __brand: 'ReadonlyMemoryFlowChart';
+};
+/**
+ * Common options for every memory type. Type-specific options layer on
+ * top via discriminated `type` field in the next overload set (Step 2).
+ */
+export interface DefineMemoryOptionsBase {
+    readonly id: string;
+    readonly description?: string;
+    readonly store: MemoryStore;
+    readonly strategy: Strategy;
+    readonly timing?: MemoryTiming;
+    readonly asRole?: ContextRole;
+    readonly redact?: MemoryRedactionPolicy;
+}
+export interface DefineEpisodicOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.EPISODIC;
+}
+export interface DefineSemanticOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.SEMANTIC;
+}
+export interface DefineNarrativeOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.NARRATIVE;
+}
+export interface DefineCausalOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.CAUSAL;
+    /** Slice of the snapshot to inject. Default `DECISIONS`. */
+    readonly projection?: SnapshotProjection;
+}
+/** Discriminated by `type`. The factory uses this to pick the pipeline. */
+export type DefineMemoryOptions = DefineEpisodicOptions | DefineSemanticOptions | DefineNarrativeOptions | DefineCausalOptions;
+export declare function isMemoryType(value: string): value is MemoryType;
+export declare function isMemoryStrategyKind(value: string): value is MemoryStrategyKind;
+export declare function isMemoryTiming(value: string): value is MemoryTiming;
+export declare function isSnapshotProjection(value: string): value is SnapshotProjection;
+/**
+ * Scope-key prefix used when mounting multiple `.memory()` definitions
+ * on the same Agent. Each memory writes to `memoryInjection_${id}` so
+ * registrations never collide. Formatter merges all keys with this
+ * prefix in registration order.
+ */
+export declare const MEMORY_INJECTION_KEY_PREFIX: "memoryInjection_";
+export declare function memoryInjectionKey(id: string): string;
+export declare function isMemoryInjectionKey(key: string): boolean;

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

@@ -33,7 +33,7 @@
  *          when its read subflow places content into the messages slot.
  *
  * @see ./define.ts          for the `defineMemory()` factory itself
- * @see ../../docs-site      for guides + the 7 strategy examples
+ * @see ../../docs-next      for guides + the 7 strategy examples
  * @see MEMORY.md            for the load-bearing design memory
  */
 // ─── Const-objects (SSOT) ───────────────────────────────────────────

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

@@ -0,0 +1,18 @@
+/**
+ * cosineSimilarity — the similarity metric used by `store.search()`.
+ *
+ *   cos(a, b) = dot(a, b) / (||a|| * ||b||)
+ *
+ * Range: [-1, 1]. Equal-direction vectors → 1. Orthogonal → 0.
+ * Opposite → -1.
+ *
+ * Zero-magnitude handling: if either vector is all-zero (or the empty
+ * vector), returns 0 — never NaN. NaN in a similarity score would
+ * poison downstream picker comparisons (NaN < x is false for all x)
+ * and silently demote the entry. Explicit 0 is safer.
+ *
+ * Length mismatch THROWS: comparing vectors of different dimensions
+ * is almost always a bug (different embedders mixed in the same store).
+ * Fail loud rather than silently truncate.
+ */
+export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;

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

@@ -0,0 +1,58 @@
+/**
+ * embedMessages — write-side stage that attaches an embedding vector
+ * to each `MemoryEntry` in `scope.newMessages` before persistence.
+ *
+ * Reads from scope:  `newMessages` (Message[]) — same input as writeMessages
+ * Writes to scope:   `newMessages` (with entries pre-wrapped — see note)
+ *
+ * Note on composition:
+ *   Unlike the `extractBeats → writeBeats` pair (which produces fully
+ *   wrapped `MemoryEntry<NarrativeBeat>[]`), `embedMessages` runs
+ *   AFTER a packaging step and BEFORE `writeMessages`. The simplest
+ *   shape is: stage writes `scope.newMessageEmbeddings: number[][]`
+ *   — one vector per message — and `writeMessages` merges it into the
+ *   entries it builds.
+ *
+ * We take the cleaner path: embed here, write the embeddings to
+ * scope as a parallel array keyed by message index, and extend
+ * `writeMessages` to pick them up. No reshuffle of the existing
+ * write stage's contract.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { Embedder } from './types.js';
+import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { MemoryState } from '../stages/index.js';
+/** Extend MemoryState to carry per-message embeddings for writeMessages. */
+export interface EmbedMessagesState extends MemoryState {
+    /**
+     * Per-message embedding vectors, indexed by position in `newMessages`.
+     * Produced by `embedMessages`; consumed by `writeMessages` when the
+     * pipeline is a semantic one.
+     */
+    newMessageEmbeddings?: readonly (readonly number[])[];
+    /** Identifier of the embedder — carried onto entries for model-mismatch guards. */
+    newMessageEmbeddingModel?: string;
+}
+export interface EmbedMessagesConfig {
+    /** The embedder to call. Typically OpenAI / Voyage / Cohere / custom. */
+    readonly embedder: Embedder;
+    /**
+     * Identifier for the embedder — stored on each entry's
+     * `embeddingModel` so `store.search({ embedderId })` can guard
+     * against cross-model pollution. Use a stable string like
+     * `"openai-text-embedding-3-small"`.
+     */
+    readonly embedderId?: string;
+    /**
+     * Pull the text to embed from a message. Default: extracts the
+     * message content as a string (supports both `string` content and
+     * `[{ type: 'text', text: ... }]` block arrays).
+     */
+    readonly textFrom?: (message: Message) => string;
+}
+/**
+ * Build the `embedMessages` stage. Prefers `embedBatch()` when the
+ * embedder implements it (one round-trip for the whole turn), otherwise
+ * falls back to N sequential `embed()` calls.
+ */
+export declare function embedMessages(config: EmbedMessagesConfig): (scope: TypedScope<EmbedMessagesState>) => Promise<void>;

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

@@ -0,0 +1,8 @@
+export type { Embedder, EmbedArgs, EmbedBatchArgs } from './types.js';
+export { cosineSimilarity } from './cosine.js';
+export { mockEmbedder } from './mockEmbedder.js';
+export type { MockEmbedderOptions } from './mockEmbedder.js';
+export { embedMessages } from './embedMessages.js';
+export type { EmbedMessagesConfig, EmbedMessagesState } from './embedMessages.js';
+export { loadRelevant } from './loadRelevant.js';
+export type { LoadRelevantConfig } from './loadRelevant.js';

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

@@ -0,0 +1,51 @@
+/**
+ * loadRelevant — read-side stage that embeds a query and fetches the
+ * top-k most similar entries from a vector-capable `MemoryStore`.
+ *
+ * Reads from scope:   `identity`, `newMessages` (or custom queryFrom)
+ * Writes to scope:    `loaded` (MemoryEntry[], ordered best-first — to be
+ *                     narrowed by `pickByBudget` downstream)
+ *
+ * Query derivation:
+ *   Default: the last user message in `newMessages`. That's the natural
+ *   "what is the user asking about?" signal. Override with `queryFrom`
+ *   for custom retrieval (e.g., compose user + assistant content,
+ *   pull a summary, etc.).
+ *
+ * Empty behavior:
+ *   No query text → no search → `loaded = []`. Downstream
+ *   `pickByBudget` picks nothing and the formatter emits nothing — safe.
+ *
+ * Feature detection:
+ *   Throws at stage build time if the store doesn't implement
+ *   `search()`. Fail-loud — a semantic pipeline configured against a
+ *   non-vector store is a config bug, not a runtime condition.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { MemoryState } from '../stages/index.js';
+import type { Embedder } from './types.js';
+export interface LoadRelevantConfig {
+    /** The vector-capable store. Must implement `search()`. */
+    readonly store: MemoryStore;
+    /** Embedder used to turn the query text into a vector. */
+    readonly embedder: Embedder;
+    /**
+     * Identifier for the embedder. When set, the search filters entries
+     * to those produced by the same embedder (prevents cross-model
+     * similarity pollution).
+     */
+    readonly embedderId?: string;
+    /** Top-k to retrieve. Default 20 — picker will narrow further by budget. */
+    readonly k?: number;
+    /** Minimum cosine score [-1, 1] to consider a match. Default: none. */
+    readonly minScore?: number;
+    /** Filter results by tier. */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /**
+     * Extract the query text from scope. Default: the last user message
+     * in `newMessages`. Override for custom retrieval signals.
+     */
+    readonly queryFrom?: (scope: TypedScope<MemoryState>) => string;
+}
+export declare function loadRelevant(config: LoadRelevantConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

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

@@ -0,0 +1,22 @@
+/**
+ * mockEmbedder — deterministic character-frequency embedder for tests.
+ *
+ * Produces a vector of length `dimensions` (default 32) where each
+ * coordinate is the count of characters whose code-point modulo
+ * `dimensions` lands on that index. Same text → same vector always,
+ * and texts that share characters have elevated cosine similarity.
+ *
+ * This is good enough for testing pipeline plumbing and basic
+ * retrieval semantics (e.g. "dogs" retrieves beats mentioning "dog"
+ * over beats mentioning "car"). It is NOT a real embedder — do not
+ * use for anything consumer-facing.
+ */
+import type { Embedder } from './types.js';
+export interface MockEmbedderOptions {
+    readonly dimensions?: number;
+}
+/**
+ * Build a deterministic mock embedder. Same text always yields the
+ * same vector; texts sharing characters share cosine similarity.
+ */
+export declare function mockEmbedder(options?: MockEmbedderOptions): Embedder;

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

@@ -0,0 +1,46 @@
+/**
+ * Embedder — text-to-vector abstraction.
+ *
+ * Pluggable interface: consumers bring their own embedding backend
+ * (OpenAI, Voyage, Cohere, Sentence Transformers, a local model, a
+ * custom rules-based hashing scheme, etc.). The library ships
+ * `mockEmbedder()` for tests — no default real embedder, since LLM
+ * providers' embedding APIs are not uniform (Anthropic doesn't
+ * publish one at all).
+ *
+ * An embedder is configured once (model + api key + dims) and reused
+ * across many turns. `dimensions` is a constant per instance — mixing
+ * embedders of different dims within the same `MemoryStore` breaks
+ * cosine similarity, so adapters should reject mismatched sizes.
+ */
+export interface EmbedArgs {
+    /** The text to embed. */
+    readonly text: string;
+    /**
+     * Optional abort signal — embedders making network calls should
+     * thread this through to respect run-level timeouts.
+     */
+    readonly signal?: AbortSignal;
+}
+export interface EmbedBatchArgs {
+    readonly texts: readonly string[];
+    readonly signal?: AbortSignal;
+}
+/**
+ * An Embedder turns text into a dense vector of constant dimensionality.
+ * Implement `embedBatch` for backends that support one-call multi-embed
+ * (OpenAI / Voyage / etc.) — without it, batch callers fall back to
+ * N sequential `embed()` calls.
+ */
+export interface Embedder {
+    /** Vector length. Constant per embedder instance. */
+    readonly dimensions: number;
+    /** Embed a single text into a vector of length `dimensions`. */
+    embed(args: EmbedArgs): Promise<number[]>;
+    /**
+     * Optional batch API. When present, pipeline stages can avoid N
+     * sequential round-trips for turn-level indexing. Adapter SHOULD
+     * implement when the backend supports it.
+     */
+    embedBatch?(args: EmbedBatchArgs): Promise<number[][]>;
+}

package/dist/esm/memory/entry/decay.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Decay computation — pure function.
+ *
+ * Applied by retrieval stages to compute an entry's effective relevance at
+ * read time. Never mutates the entry; only returns a scaling factor in
+ * `[0, +∞)` that stages apply to their existing score.
+ *
+ * Model:
+ *   factor = exp(-ln2 · Δt / halfLife) · min(accessBoost^accessCount, MAX_BOOST)
+ *
+ * The time term is exponential decay (half after one half-life). The access
+ * term is multiplicative — each read of an entry boosts its future
+ * relevance. `MAX_BOOST_MULTIPLIER` caps runaway boosting so a frequently-
+ * read but old entry doesn't crowd out newer relevant entries indefinitely.
+ */
+import type { DecayPolicy, MemoryEntry } from './types.js';
+/**
+ * Compute the decay factor for an entry at a given moment.
+ *
+ * @param entry   The memory entry to score. Must have `lastAccessedAt` and
+ *                `accessCount` set (storage adapters populate these).
+ * @param now     The reference time (unix ms). Defaults to `Date.now()`.
+ * @param policy  Optional override — when omitted, uses `entry.decayPolicy`.
+ *                Stages can pass a stage-wide default so entries without a
+ *                per-entry policy still decay consistently. If neither is
+ *                set, returns 1.0 (no decay applied).
+ *
+ * @returns Scaling factor in `[0, MAX_BOOST_MULTIPLIER]` — stages multiply
+ *          this against their existing relevance score.
+ */
+export declare function computeDecayFactor(entry: Pick<MemoryEntry, 'lastAccessedAt' | 'accessCount' | 'decayPolicy'>, now?: number, policy?: DecayPolicy): number;
+/**
+ * Compute decay for multiple entries in one call. Order-preserving; returns
+ * one factor per entry. Convenience for stages that rank whole batches.
+ */
+export declare function computeDecayFactors(entries: readonly Pick<MemoryEntry, 'lastAccessedAt' | 'accessCount' | 'decayPolicy'>[], now?: number, policy?: DecayPolicy): number[];

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

@@ -0,0 +1,2 @@
+export type { MemoryEntry, MemorySource, DecayPolicy } from './types.js';
+export { computeDecayFactor, computeDecayFactors } from './decay.js';