agentfootprint/dist/types/memory/facts/extractFacts.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * 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>;
//# sourceMappingURL=extractFacts.d.ts.map