agentfootprint 6.44.0 → 7.0.0

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

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

@@ -0,0 +1,140 @@
+import type { MemoryIdentity } from '../identity/index.js';
+/**
+ * MemoryEntry — a single stored item with decay-, version-, and source-aware
+ * metadata.
+ *
+ * Entry shape is generic over `T` so stores can hold messages, facts,
+ * narrative traces, or anything else JSON-serializable. The metadata fields
+ * around `value` are what make entries first-class objects instead of raw
+ * blobs:
+ *
+ *   - `version`       — optimistic concurrency (`putIfVersion`) + migration
+ *   - `tier`          — MemGPT-style hot/warm/cold classification
+ *   - `source`        — provenance — "where did this memory come from?"
+ *   - `lastAccessedAt` / `accessCount` — decay signals
+ *   - `ttl`           — absolute expiry at the storage layer
+ *   - `embeddingModel`— compatibility check for semantic search
+ *
+ * Entries are **immutable in spirit** — a "mutation" is a new entry with the
+ * same `id` and an incremented `version`. Storage adapters may implement
+ * this as an in-place update or an append-only log, but the library treats
+ * entries as values.
+ *
+ * NOTE: `readonly` modifiers are a TypeScript compile-time hint only. At
+ * runtime, nothing prevents a consumer from mutating an entry they received.
+ * The library's internal code never mutates entries; adapters that wish to
+ * enforce this at runtime may `Object.freeze(entry)` before returning.
+ */
+export interface MemoryEntry<T = unknown> {
+    /** Stable id within the identity namespace. */
+    readonly id: string;
+    /** The actual stored payload. JSON-serializable. */
+    readonly value: T;
+    /**
+     * Free-form metadata — tags, labels, user-supplied annotations. Kept
+     * separate from the decay / version fields so those stay typed.
+     */
+    readonly metadata?: Record<string, unknown>;
+    /**
+     * Monotonic version number. Stores use this for `putIfVersion` optimistic
+     * concurrency — write only if the entry is still at the version the
+     * writer expected. Defaults to 1 on first write; callers increment.
+     */
+    readonly version: number;
+    /** Unix ms. */
+    readonly createdAt: number;
+    /** Unix ms. Equal to createdAt on first write. */
+    readonly updatedAt: number;
+    /** Unix ms. Updated by `store.get` / retrieval stages. Decay input. */
+    readonly lastAccessedAt: number;
+    /** Number of times this entry has been read. Decay input. */
+    readonly accessCount: number;
+    /**
+     * Optional absolute expiry (unix ms). Storage adapters MUST refuse to
+     * return entries past their ttl. Implementations: InMemory filters on
+     * read, Redis uses native EXPIRE, DynamoDB uses TTL attribute.
+     */
+    readonly ttl?: number;
+    /**
+     * Optional decay policy applied at retrieval time. When present, stages
+     * that rank entries (picker, reranker) decrease relevance for entries
+     * whose `lastAccessedAt` is far in the past. See `decay.ts`.
+     */
+    readonly decayPolicy?: DecayPolicy;
+    /**
+     * Tier classification — enables MemGPT-style page-in/page-out policies.
+     * Stages can filter by tier (e.g. "load hot entries first, consult cold
+     * only under pressure"). Omitting the field means "untiered."
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+    /**
+     * Provenance — which turn / runtime stage / message produced this entry.
+     * Lets retrieval cite sources ("remembered from turn 5") and lets
+     * `causalChain` cross session boundaries.
+     */
+    readonly source?: MemorySource;
+    /**
+     * Optional dense vector embedding of this entry's value. Populated
+     * by semantic-memory pipelines (see `embedMessages` / `embedBeats`
+     * stages) when an `Embedder` is configured. Stores that support
+     * vector search index on this field; stores that don't ignore it.
+     *
+     * Vector length MUST match the configured embedder's `dimensions`.
+     * Mixing embedders of different sizes within the same identity
+     * namespace will break cosine similarity — `store.search()` uses
+     * `cosineSimilarity()` which throws on length mismatch.
+     */
+    readonly embedding?: readonly number[];
+    /**
+     * Identifier of the embedder that produced `embedding`. Search
+     * stages compare this against the active embedder's id before
+     * trusting distance scores — prevents silent retrieval corruption
+     * when an embedding model is swapped but old entries are still
+     * indexed with the previous vector space.
+     */
+    readonly embeddingModel?: string;
+}
+/**
+ * Where a memory entry came from. The library populates this automatically
+ * when entries are written from inside a memory stage (writeMessages,
+ * extractFacts, etc.); consumers can populate it when writing programmatically.
+ *
+ * When searching across sessions ("did we learn this in a previous session?"),
+ * `identity` + `turn` + `runtimeStageId` form a globally-unique causal coordinate
+ * — you can replay exactly what the agent was doing when the entry was born.
+ */
+export interface MemorySource {
+    /** Run-local turn counter. */
+    readonly turn?: number;
+    /** footprintjs runtime stage id (`stageId#executionIndex`). */
+    readonly runtimeStageId?: string;
+    /** Originating message id, if the entry came from a conversation turn. */
+    readonly messageId?: string;
+    /**
+     * Cross-session provenance — the `MemoryIdentity` that produced this entry.
+     * Lets retrieval stages show "remembered from session X, user Y, turn 5"
+     * instead of anonymous citation. Storage adapters MUST preserve this field
+     * verbatim on every read/write.
+     */
+    readonly identity?: MemoryIdentity;
+}
+/**
+ * Natural-forgetting policy. Decay applies at retrieval time: the entry's
+ * stored value is never mutated; only its computed "relevance" is adjusted.
+ *
+ * Consumers choose half-life + access boost to match their domain:
+ *   - Fast-moving (news, tickets) — halfLifeMs ≈ 1 day, accessBoost ≈ 1.5
+ *   - Stable (user profile, facts)— halfLifeMs ≈ 30 days, accessBoost ≈ 1.1
+ */
+export interface DecayPolicy {
+    /**
+     * How long for relevance to halve when never accessed. Milliseconds.
+     */
+    readonly halfLifeMs: number;
+    /**
+     * Multiplier applied per access (clamped to a reasonable ceiling inside
+     * `applyDecay`). Values > 1.0 boost frequently-used entries; values in
+     * (0, 1.0) would *reduce* relevance with use (rarely desired).
+     */
+    readonly accessBoost: number;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * extractFacts — write-side stage that distills `scope.newMessages` into
+ * `Fact`s via a pluggable `FactExtractor`.
+ *
+ * Reads from scope:  `newMessages`, `turnNumber`, optional `loadedFacts`
+ * Writes to scope:   `newFacts` (MemoryEntry<Fact>[], ready for writeFacts)
+ *
+ * The extractor is called ONCE per turn on the turn's new messages. If
+ * `scope.loadedFacts` is populated (the write subflow ran `loadFacts`
+ * first), existing facts are passed to the extractor so LLM-based
+ * extractors can update rather than duplicate.
+ *
+ * **Stable ids**: each produced entry gets id `fact:${fact.key}`. When
+ * the same key is written again in a future turn, the storage layer
+ * overwrites in place — no duplicate accumulation. This is the core
+ * property that makes facts different from beats (append-only) and
+ * messages (append-only).
+ *
+ * Empty-extraction behavior: `newFacts = []`. Downstream `writeFacts`
+ * short-circuits on empty — no store round-trip.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryEntry } from '../entry/index.js';
+import type { MemoryState } from '../stages/index.js';
+import type { FactExtractor } from './extractor.js';
+import type { Fact } from './types.js';
+export interface ExtractFactsConfig {
+    /** The extractor to call. See `patternFactExtractor` / `llmFactExtractor`. */
+    readonly extractor: FactExtractor;
+    /**
+     * Optional tier for the persisted facts. Typical pattern: `'hot'` for
+     * current identity / preferences, `'warm'` for older commitments.
+     * Omit for no tier.
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+    /**
+     * Optional TTL in ms from `Date.now()` applied to persisted fact
+     * entries. Useful for facts that should decay (task statuses,
+     * short-term preferences). Identity facts typically have no TTL.
+     */
+    readonly ttlMs?: number;
+}
+/** State added to `MemoryState` by the fact pipeline stages. */
+export interface FactPipelineState extends MemoryState {
+    /** Produced by `extractFacts`, consumed by `writeFacts`. */
+    newFacts?: readonly MemoryEntry<Fact>[];
+    /** Produced by `loadFacts`, consumed by `formatFacts` and `extractFacts`. */
+    loadedFacts?: readonly MemoryEntry<Fact>[];
+}
+export declare function extractFacts(config: ExtractFactsConfig): (scope: TypedScope<FactPipelineState>) => Promise<void>;

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

@@ -0,0 +1,33 @@
+/**
+ * FactExtractor — interface for distilling stable claims out of a turn.
+ *
+ * Complements `BeatExtractor`: a beat summarizes what happened, a
+ * fact captures what's *currently true*. Different extractors produce
+ * different levels of structure (pattern-based for quick identity /
+ * contact info; LLM-based for rich open-ended extraction).
+ *
+ * Built-in extractors:
+ *   - `patternFactExtractor()` — zero-dep regex heuristics for
+ *     common identity / location / contact patterns.
+ *   - `llmFactExtractor({ provider })` — one LLM call per turn for
+ *     open-ended extraction. Opt-in.
+ */
+import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { Fact } from './types.js';
+export interface FactExtractArgs {
+    /** New-turn messages. */
+    readonly messages: readonly Message[];
+    /** Current turn number. Useful for extractors that want it in a source tag. */
+    readonly turnNumber: number;
+    /**
+     * Facts already in the store (if caller has a cheap way to fetch).
+     * Passed to extractors that merge / dedupe at extraction time.
+     * May be empty even when facts exist — not every pipeline pre-loads.
+     */
+    readonly existing?: readonly Fact[];
+    /** Optional abort signal for LLM-based extractors. */
+    readonly signal?: AbortSignal;
+}
+export interface FactExtractor {
+    extract(args: FactExtractArgs): Promise<readonly Fact[]>;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * formatFacts — render loaded `Fact` entries into a single system
+ * message for prompt injection.
+ *
+ * Reads from scope:  `loadedFacts`
+ * Writes to scope:   `formatted` (Message[] — one system message, or empty)
+ *
+ * Facts are tiny and semantically distinct from beats/messages, so they
+ * render as a compact key/value block rather than a narrative paragraph
+ * or per-entry `<memory>` tags. The default shape:
+ *
+ *   Known facts about the user:
+ *
+ *   - user.name: Alice
+ *   - user.email: alice@example.com
+ *   - user.preferences.color: blue
+ *
+ * Why one block, not one message per fact?
+ *   LLMs parse key/value lists efficiently; splitting would waste
+ *   tokens on per-message system overhead and break up the list's
+ *   visual grouping.
+ *
+ * Why NOT run facts through `pickByBudget`?
+ *   Facts are typically 10-50 items, each a handful of tokens. Picking
+ *   subsets is rarely useful — the user either knows your name or
+ *   they don't. Consumers who *do* want budget-based fact pruning can
+ *   copy-paste this stage and wrap it with a picker.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryEntry } from '../entry/index.js';
+import type { Fact } from './types.js';
+import type { FactPipelineState } from './extractFacts.js';
+export interface FormatFactsConfig {
+    /**
+     * 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.
+     */
+    readonly header?: string;
+    /** Footer appended after the fact list. Empty by default. */
+    readonly footer?: string;
+    /**
+     * When `true`, appends `(conf 0.xx)` after each fact's value. Off by
+     * default — confidence is usually noise for the LLM and only useful
+     * in audit / debug flows.
+     */
+    readonly showConfidence?: boolean;
+    /**
+     * Custom per-fact renderer. Receives the entry; returns the block
+     * string (without the leading `- ` bullet). Use for app-specific
+     * formatting: custom attribution, hiding category info, etc.
+     */
+    readonly renderFact?: (entry: MemoryEntry<Fact>) => string;
+    /**
+     * Inject the message even when `loadedFacts` is empty. Usually
+     * undesired — an empty list is noise. Off by default.
+     */
+    readonly emitWhenEmpty?: boolean;
+}
+export declare function formatFacts(config?: FormatFactsConfig): (scope: TypedScope<FactPipelineState>) => Promise<void>;

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

@@ -0,0 +1,14 @@
+export type { Fact } from './types.js';
+export { factId, isFactId, isFact, asConfidence } from './types.js';
+export type { FactExtractor, FactExtractArgs } from './extractor.js';
+export { patternFactExtractor } from './patternFactExtractor.js';
+export { llmFactExtractor } from './llmFactExtractor.js';
+export type { LLMFactExtractorConfig } from './llmFactExtractor.js';
+export { extractFacts } from './extractFacts.js';
+export type { ExtractFactsConfig, FactPipelineState } from './extractFacts.js';
+export { writeFacts } from './writeFacts.js';
+export type { WriteFactsConfig } from './writeFacts.js';
+export { loadFacts } from './loadFacts.js';
+export type { LoadFactsConfig } from './loadFacts.js';
+export { formatFacts } from './formatFacts.js';
+export type { FormatFactsConfig } from './formatFacts.js';

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

@@ -0,0 +1,64 @@
+/**
+ * llmFactExtractor — LLM-backed fact extractor.
+ *
+ * Uses an LLMProvider (typically a cheap model like Claude Haiku or
+ * GPT-4o-mini) to pull stable, timeless claims out of a conversation
+ * turn. Complements `patternFactExtractor` — regex catches the obvious
+ * self-disclosures, the LLM catches the open-ended ones.
+ *
+ * The extractor asks the LLM for a JSON response in this shape:
+ *
+ * ```json
+ * {
+ *   "facts": [
+ *     {
+ *       "key": "user.name",
+ *       "value": "Alice",
+ *       "confidence": 0.95,
+ *       "category": "identity",
+ *       "refs": ["msg-1-0"]
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * The extractor parses, clamps confidence via `asConfidence()`, dedups
+ * by `key` (last occurrence wins, matching `patternFactExtractor`),
+ * and returns the facts. Malformed responses fall back to `[]` — a bad
+ * extraction should not break the agent turn.
+ *
+ * Usage:
+ * ```ts
+ * import { anthropic } from 'agentfootprint';
+ * import { llmFactExtractor, factPipeline, InMemoryStore } from 'agentfootprint/memory';
+ *
+ * const pipeline = factPipeline({
+ *   store: new InMemoryStore(),
+ *   extractor: llmFactExtractor({ provider: yourLLMProvider }),
+ * });
+ * ```
+ */
+import type { LLMProvider } from '../../adapters/types.js';
+import type { FactExtractor } from './extractor.js';
+export interface LLMFactExtractorConfig {
+    /** The provider used for extraction. Typically a cheap/fast model. */
+    readonly provider: LLMProvider;
+    /**
+     * Override the system prompt. Defaults to a one-paragraph instruction
+     * that elicits the JSON shape described in the module docs.
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Dev-mode logger invoked when the LLM response fails to parse.
+     * Defaults to `console.warn` — production consumers can route the
+     * signal to their telemetry pipeline.
+     */
+    readonly onParseError?: (error: unknown, rawContent: string) => void;
+    /**
+     * Include up to this many existing facts in the user prompt so the
+     * model can update / refine rather than duplicate. Set to `0` to
+     * skip — cheaper but loses update awareness. Default `16`.
+     */
+    readonly includeExistingLimit?: number;
+}
+export declare function llmFactExtractor(config: LLMFactExtractorConfig): FactExtractor;

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

@@ -0,0 +1,43 @@
+/**
+ * loadFacts — read-side stage that loads stored `Fact` entries into
+ * `scope.loadedFacts`.
+ *
+ * Reads from scope:  `identity`
+ * Writes to scope:   `loadedFacts` (appends — does not replace)
+ *
+ * Unlike `loadRecent` (which returns ALL entries and lets downstream
+ * stages filter), `loadFacts` queries the store and keeps only entries
+ * whose id matches the `fact:` prefix. Facts are typically few dozen
+ * at most per identity — a linear scan after a bounded `list` call is
+ * cheap.
+ *
+ * Why append, not replace?
+ *   Same contract as `loadRecent` — pipelines may combine multiple
+ *   load stages (e.g. facts + recent messages + beats). Appending lets
+ *   each contribute without coordination.
+ *
+ * Note: this stage writes `loadedFacts` (a separate field from
+ * `loaded`) because fact entries have a different payload type
+ * (`MemoryEntry<Fact>`) than message entries (`MemoryEntry<Message>`).
+ * Keeping them separate prevents format stages from misrouting entries.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { FactPipelineState } from './extractFacts.js';
+export interface LoadFactsConfig {
+    /** The store to read from. */
+    readonly store: MemoryStore;
+    /**
+     * Upper bound on the `list` call's page size. Adapters may cap this
+     * lower. Defaults to 100 — enough for typical identity/preference
+     * inventories. Fact pipelines that accumulate task statuses or
+     * commitments should raise this.
+     */
+    readonly limit?: number;
+    /**
+     * Optional tier filter. When set, only loads facts tagged with one
+     * of these tiers. Matches the `loadRecent` / `loadRelevant` API.
+     */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+}
+export declare function loadFacts(config: LoadFactsConfig): (scope: TypedScope<FactPipelineState>) => Promise<void>;

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

@@ -0,0 +1,2 @@
+import type { FactExtractor } from './extractor.js';
+export declare function patternFactExtractor(): FactExtractor;