agentfootprint 6.44.0 → 6.45.0

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;

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;