agentfootprint/dist/esm/memory/beats/formatAsNarrative.d.ts

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

/**
 * formatAsNarrative — render selected NarrativeBeats into a single
 * cohesive paragraph for prompt injection.
 *
 * Reads from scope:  `selected` (MemoryEntry<NarrativeBeat>[])
 * Writes to scope:   `formatted` (Message[] — single system message, or empty)
 *
 * Contrasts with `formatDefault` which produces per-entry `<memory>`
 * blocks for raw-message recall. `formatAsNarrative` composes beats
 * into a story paragraph:
 *
 *   Relevant context from prior conversations:
 *
 *   From earlier: User revealed their name is Alice. User asked about
 *   refunds for order ORD-123. Assistant confirmed the refund was
 *   processed.
 *
 * Why a paragraph vs per-beat blocks?
 *   Beats are already summaries — wrapping each in its own tag adds
 *   boilerplate tokens without adding information. A connected
 *   paragraph flows more naturally into the LLM's context.
 *
 * Source citations:
 *   When `showRefs` is enabled, the rendered line appends `(refs: msg-1-0, msg-1-2)`
 *   so the LLM (and consumer debugging) can walk beats back to source
 *   messages. Off by default — cites add tokens and some LLMs parrot them.
 *
 * Empty-input behavior:
 *   `selected.length === 0` → writes `formatted: []` (no system message).
 *   Matches `formatDefault`'s "skip empty" behavior — injecting an
 *   empty header-only block is worse than no injection at all.
 */
import type { TypedScope } from 'footprintjs';
import type { MemoryState } from '../stages/index.js';
export interface FormatAsNarrativeConfig {
    /**
     * Header prepended to the injected message. Defaults to
     * `"Relevant context from prior conversations. Use when it helps
     * answer the current turn."` — matches `formatDefault`.
     */
    readonly header?: string;
    /** Footer appended after the beats paragraph. Empty by default. */
    readonly footer?: string;
    /**
     * When `true`, each beat line appends `(refs: msg-x-y, ...)`. Off
     * by default — saves tokens and avoids LLMs echoing the refs in
     * their replies. Turn on for audit / debug use cases.
     */
    readonly showRefs?: boolean;
    /**
     * Connective phrase inserted before the beats paragraph. Defaults
     * to `"From earlier: "`. Set to `""` to disable.
     */
    readonly leadIn?: string;
    /**
     * Inject the message even when `selected` is empty. Usually
     * undesired — empty memory noise displaces real context. Off by
     * default.
     */
    readonly emitWhenEmpty?: boolean;
}
export declare function formatAsNarrative(config?: FormatAsNarrativeConfig): (scope: TypedScope<MemoryState>) => Promise<void>;