agentfootprint/dist/esm/memory/store/writeOptions.d.ts

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

import type { MemoryIdentity } from '../identity/index.js';
import type { MemoryStore } from './types.js';
/** What one write asks of the store, beyond keeping the entry. */
export interface MemoryWriteOptions {
    /**
     * `'skip'` — store the entry, but keep it out of long-term extraction: the
     * service must derive nothing (no fact, summary or preference) from it. It
     * stays readable where it was written (`get`, `list`).
     */
    readonly extraction?: 'skip';
    /**
     * The values a store substitutes into the namespaces its DERIVED long-term
     * records are filed under — one tenant's scope, typically
     * `{ tenantid: 'acme' }`. Which keys exist is the store's configuration.
     *
     * Keep the mapping from your tenant to these values ONE-TO-ONE: a mapping
     * that lowercases, trims or truncates a tenant id files two tenants' derived
     * records under one namespace. An empty object asks for nothing.
     */
    readonly namespaceScope?: Readonly<Record<string, string>>;
}
/** The name of one write option — what a store declares it honours. */
export type MemoryWriteOptionName = keyof MemoryWriteOptions;
/** Every write option, in the order refusals name them. */
export declare const MEMORY_WRITE_OPTION_NAMES: readonly MemoryWriteOptionName[];
/**
 * The reason a store with NO server-side extraction gives — the shared
 * sentence, so every such store refuses in the same words, remedy included.
 */
export declare const NO_SERVER_EXTRACTION: string;
/**
 * Thrown when a write asks for an option the store does not honour.
 *
 * Carries the store and the option by name; never a value — a namespace scope
 * names a tenant, and an error message is the one place a tenant id must not
 * travel. The remedy is in the store's own reason.
 */
export declare class UnsupportedMemoryWriteOptionError extends Error {
    readonly code: "ERR_UNSUPPORTED_MEMORY_WRITE_OPTION";
    /** The store that refused, e.g. `'InMemoryStore'`. */
    readonly store: string;
    /** The option it cannot honour. */
    readonly option: MemoryWriteOptionName;
    constructor(store: string, option: MemoryWriteOptionName, why: string);
}
/**
 * The options this write actually asks for, its values checked.
 *
 * A field that is `undefined` is not asked for; an empty `namespaceScope` asks
 * for nothing either. A value of the wrong shape is a programming error, so it
 * throws a `TypeError` naming the option — and never echoes the value.
 */
export declare function requestedWriteOptions(options?: MemoryWriteOptions): MemoryWriteOptionName[];
/**
 * Refuse, by name, every write option `options` asks for that `honoured` does
 * not contain. Call it first thing in `put`, `putMany` and `putIfVersion` —
 * before anything is written.
 *
 * @param store    the store's name, as the refusal should say it
 * @param honoured the store's own declaration (`MemoryStore.writeOptions`)
 * @param options  what this write asked for
 * @param why      why this store cannot honour what it does not declare, and
 *                 what to do instead
 * @throws {UnsupportedMemoryWriteOptionError} for the first option not honoured
 */
export declare function refuseUnhonouredWriteOptions(store: string, honoured: readonly MemoryWriteOptionName[] | undefined, options: MemoryWriteOptions | undefined, why: string): void;
/** Write options for every write a memory makes (`defineMemory({ writeOptions })`). */
export interface MemoryWriteOptionsConfig {
    /** `'skip'` keeps every write of this memory out of long-term extraction. */
    readonly extraction?: 'skip';
}
/**
 * A memory's namespace scope (`defineMemory({ namespaceScope })`): the scope
 * its writes are filed under AND its reads are confined to.
 *
 * One computed from the run's identity — `(identity) => ({ tenantid: … })`,
 * the multi-tenant shape — or a fixed object, which is right only for a
 * deployment that serves ONE tenant. Keep the function one-to-one (see
 * {@link MemoryWriteOptions.namespaceScope}); a store may ship an encoder into
 * its own alphabet (`agentCoreNamespaceValue` for AgentCore). A scope that
 * comes back empty or malformed refuses the write or the search, never runs it
 * without one.
 */
export type MemoryNamespaceScope = Readonly<Record<string, string>> | ((identity: MemoryIdentity) => Readonly<Record<string, string>>);
/** What `defineMemory` binds to its store: the write options and the scope. */
export interface BoundMemoryOptions extends MemoryWriteOptionsConfig {
    readonly namespaceScope?: MemoryNamespaceScope;
}
/**
 * Refuse a memory's write options or scope at DEFINITION time when its store
 * does not declare them, or when a fixed one is malformed — the first turn
 * should not be where a configuration that can never work is discovered.
 *
 * @throws {UnsupportedMemoryWriteOptionError} naming the store and the option
 * @throws {TypeError} for a malformed option
 */
export declare function assertStoreHonours(store: MemoryStore, config: BoundMemoryOptions, caller: string): void;
/**
 * The store with the memory's write options applied to every write it makes —
 * and its namespace scope applied to every read.
 *
 * Writes (`put`, `putMany`, `putIfVersion`) carry the options. A call's own
 * `extraction` overrides the bound one only where it asks for something (an
 * `undefined` field never erases it). A bound `namespaceScope` is NEVER
 * replaced per call: it comes from the run's identity through the configured
 * resolver and nowhere else, so a call that brings its own is refused.
 *
 * Reads follow the same rule as writes: `search` hands a store that declares
 * `'namespaceScope'` the scope resolved for that identity
 * (`SearchOptions.namespaceScope`), so a store that files derived records by it
 * reads within it. Every other member passes straight through.
 *
 * @throws (as a rejected promise, at a write or a search) a `TypeError` when
 *   the scope function returns an empty or malformed scope — refused rather
 *   than sent outside every tenant's namespace — or when a call brings its
 *   own `namespaceScope` to a memory that binds one.
 */
export declare function bindWriteOptions(store: MemoryStore, config: BoundMemoryOptions): MemoryStore;