@tangle-network/agent-knowledge 4.0.1 → 5.0.0

package/dist/index-Cf7txrYP.d.ts

@@ -0,0 +1,790 @@
+import { f as AgentMemoryAdapter, n as AgentMemorySearchOptions, h as AgentMemoryContext, j as AgentMemoryHit, m as AgentMemoryScope, o as AgentMemoryWriteInput, p as AgentMemoryWriteResult, l as AgentMemoryRunLease, x as KnowledgeBenchmarkFamily, G as KnowledgeBenchmarkSplit, L as KnowledgeMemoryBenchmarkTaskKind, N as KnowledgeMemoryFactMatcher, M as KnowledgeMemoryEvent, J as KnowledgeMemoryBenchmarkCase, i as AgentMemoryControllerMode, A as AgentMemoryAcquireRunLease, $ as RetrievalHoldoutConfig, _ as RetrievalHoldoutCallContext, a2 as RetrievalHoldoutResult, Z as RetrievalHoldoutBypassReason, a1 as RetrievalHoldoutEvent } from './types-BY-xLVw-.js';
+import { OptimizationMethodComparison, Scenario, CompareOptimizationMethodsOptions, OptimizationMethod, DispatchContext, OptimizationMethodRunOptions, CampaignStorage, CostLedgerHandle, CampaignResult, JudgeConfig, HeldoutSignificance, HeldoutSignificanceOptions } from '@tangle-network/agent-eval/campaign';
+import { RunPaidCallInput, CostChannel, CostReceipt } from '@tangle-network/agent-eval';
+import { OffPolicyTrajectory } from '@tangle-network/agent-eval/rl';
+import { AgentCandidateJsonValue } from '@tangle-network/agent-interface';
+import { z } from 'zod';
+import { S as SourceRecord } from './types-6x0OpfW6.js';
+
+interface SerializedCandidateCodec<TCandidate extends AgentCandidateJsonValue> {
+    serialize(candidate: TCandidate): string;
+    parse(surface: string): TCandidate;
+}
+interface SerializedCandidate<TCandidate extends AgentCandidateJsonValue> {
+    value: TCandidate;
+    surface: string;
+    surfaceHash: string;
+}
+type ComparisonOptions<TScenario extends Scenario, TArtifact> = Omit<CompareOptimizationMethodsOptions<TScenario, TArtifact>, 'methods' | 'baselineSurface' | 'trainScenarios' | 'selectionScenarios' | 'testScenarios' | 'dispatchWithSurface' | 'dispatchRef' | 'optimizationRunOptions'>;
+interface RunSerializedKnowledgeOptimizationOptions<TCandidate extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact> extends ComparisonOptions<TScenario, TArtifact> {
+    /** Immutable identity for candidate execution, judges, models, indexes, and external settings. */
+    executionRef: string;
+    baseline: TCandidate;
+    method: OptimizationMethod<TScenario, TArtifact>;
+    trainScenarios: readonly TScenario[];
+    selectionScenarios: readonly TScenario[];
+    finalScenarios: readonly TScenario[];
+    dispatchCandidate(input: {
+        candidate: TCandidate;
+        candidateSurface: string;
+        candidateSurfaceHash: string;
+        scenario: TScenario;
+        context: DispatchContext;
+    }): Promise<TArtifact>;
+    codec?: SerializedCandidateCodec<TCandidate>;
+    /** Detects duplicated cases whose IDs differ within or across data partitions. */
+    scenarioFingerprint?: (scenario: TScenario) => string;
+    optimizationRunOptions?: Omit<OptimizationMethodRunOptions<TScenario, TArtifact>, 'dispatchRef'>;
+}
+interface RunSerializedKnowledgeOptimizationResult<TCandidate extends AgentCandidateJsonValue> {
+    methodName: string;
+    baseline: SerializedCandidate<TCandidate>;
+    winner: SerializedCandidate<TCandidate>;
+    comparison: OptimizationMethodComparison;
+}
+/**
+ * Runs one complete agent-eval method over a serialized knowledge candidate.
+ * The method receives train and selection data; agent-eval owns final scoring.
+ */
+declare function runSerializedKnowledgeOptimization<TCandidate extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact>(options: RunSerializedKnowledgeOptimizationOptions<TCandidate, TScenario, TArtifact>): Promise<RunSerializedKnowledgeOptimizationResult<TCandidate>>;
+declare function jsonCandidateCodec<TCandidate extends AgentCandidateJsonValue>(): SerializedCandidateCodec<TCandidate>;
+declare function jsonObjectCandidateCodec<TCandidate extends Record<string, AgentCandidateJsonValue>>(): SerializedCandidateCodec<TCandidate>;
+declare function scenarioContentFingerprint(scenario: Scenario): string;
+
+declare function defaultGetMemoryContext(adapter: Pick<AgentMemoryAdapter, 'search'>, query: string, options?: AgentMemorySearchOptions): Promise<AgentMemoryContext>;
+declare function renderMemoryContext(hits: AgentMemoryHit[]): string;
+
+type AgentMemoryVisibility = 'private' | 'team' | 'shared';
+type AgentMemoryBranchLifetime = 'resumable' | 'attempt';
+interface AgentMemorySharingPolicy {
+    read: readonly AgentMemoryVisibility[];
+    write: AgentMemoryVisibility;
+}
+interface AgentMemoryJournalEntry {
+    sequence: number;
+    input: AgentMemoryWriteInput;
+    result: AgentMemoryWriteResult;
+}
+interface AgentMemoryBranchSnapshot {
+    branchId: string;
+    lifetime: AgentMemoryBranchLifetime;
+    parentBranchId?: string;
+    adapterId: string;
+    policy: AgentMemorySharingPolicy;
+    baseScope: AgentMemoryScope;
+    journal: readonly AgentMemoryJournalEntry[];
+    digest: `sha256:${string}`;
+}
+interface AgentMemoryBranch extends AgentMemoryAdapter {
+    readonly branchId: string;
+    readonly lifetime: AgentMemoryBranchLifetime;
+    readonly parentBranchId?: string;
+    readonly policy: AgentMemorySharingPolicy;
+    snapshot(): Promise<AgentMemoryBranchSnapshot>;
+    fork(options: {
+        branchId: string;
+        adapter?: AgentMemoryAdapter;
+        policy?: AgentMemorySharingPolicy;
+        baseScope?: AgentMemoryScope;
+        lifetime?: AgentMemoryBranchLifetime;
+    }): Promise<AgentMemoryBranch>;
+}
+interface CreateAgentMemoryBranchOptions {
+    adapter: AgentMemoryAdapter;
+    branchId: string;
+    parentBranchId?: string;
+    policy?: AgentMemorySharingPolicy;
+    baseScope?: AgentMemoryScope;
+    /** Attempt branches use a new ID after a process restart and cannot bind persisted state. */
+    lifetime?: AgentMemoryBranchLifetime;
+    /** Rebind a persisted branch whose external memory is still present. */
+    snapshot?: AgentMemoryBranchSnapshot;
+    /** Optional exact logical scopes allowed to write, used by crash-safe experiments. */
+    allowedWriteScopes?: readonly AgentMemoryScope[];
+}
+interface ForkAgentMemoryBranchSnapshotOptions {
+    snapshot: AgentMemoryBranchSnapshot;
+    adapter: AgentMemoryAdapter;
+    branchId: string;
+    policy?: AgentMemorySharingPolicy;
+    baseScope?: AgentMemoryScope;
+    lifetime?: AgentMemoryBranchLifetime;
+}
+/**
+ * Isolates one candidate branch and records accepted writes for durable resume
+ * or replay into a child branch, including a child backed by another provider.
+ */
+declare function createAgentMemoryBranch(options: CreateAgentMemoryBranchOptions): AgentMemoryBranch;
+/** Replays a durable journal into a fresh provider branch. */
+declare function forkAgentMemoryBranchSnapshot(options: ForkAgentMemoryBranchSnapshotOptions): Promise<AgentMemoryBranch>;
+
+interface AgentMemorySequenceProbe {
+    id: string;
+    query: string;
+    scope?: AgentMemoryScope;
+    limit?: number;
+    taskKind?: KnowledgeMemoryBenchmarkTaskKind;
+    requiredFacts?: readonly KnowledgeMemoryFactMatcher[];
+    forbiddenFacts?: readonly KnowledgeMemoryFactMatcher[];
+    expectedEventIds?: readonly string[];
+    expectedActorIds?: readonly string[];
+    referenceAnswer?: string;
+}
+interface AgentMemorySequenceStep {
+    id: string;
+    instruction?: string;
+    scope?: AgentMemoryScope;
+    writes?: readonly AgentMemoryWriteInput[];
+    parallelWrites?: boolean;
+    probes?: readonly AgentMemorySequenceProbe[];
+    parallelProbes?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Runtime-visible step fields. Evaluation labels and dataset identity are excluded. */
+interface AgentMemoryExecutionStep {
+    ordinal: number;
+    instruction?: string;
+    scope?: AgentMemoryScope;
+}
+type AgentMemoryExecutionPaidCallInput<T> = Omit<RunPaidCallInput<T>, 'channel' | 'phase' | 'tags' | 'signal'> & {
+    channel?: CostChannel;
+};
+type AgentMemoryExecutionCostReceipt = Omit<CostReceipt, 'phase' | 'tags'>;
+type AgentMemoryExecutionPaidCallResult<T> = {
+    succeeded: true;
+    callId: string;
+    value: T;
+    receipt: AgentMemoryExecutionCostReceipt;
+} | {
+    succeeded: false;
+    callId?: string;
+    error: Error;
+    receipt?: AgentMemoryExecutionCostReceipt;
+};
+interface AgentMemoryExecutionCostMeter {
+    runPaidCall<T>(input: AgentMemoryExecutionPaidCallInput<T>): Promise<AgentMemoryExecutionPaidCallResult<T>>;
+}
+/** Execution capabilities with all campaign and evaluation identity removed. */
+interface AgentMemoryExecutionContext {
+    readonly signal: AbortSignal;
+    readonly cost: AgentMemoryExecutionCostMeter;
+}
+interface AgentMemorySequence {
+    id: string;
+    family: KnowledgeBenchmarkFamily | string;
+    split?: KnowledgeBenchmarkSplit;
+    steps: readonly AgentMemorySequenceStep[];
+    /** Exact scopes a runtime callback may write beyond scopes declared by steps. */
+    cleanupScopes?: readonly AgentMemoryScope[];
+    tags?: readonly string[];
+    metadata?: Record<string, unknown>;
+}
+interface BuildAgentMemorySequencesFromBenchmarkCasesOptions {
+    memoryAgentId?: string;
+    eventScope?: (input: {
+        event: KnowledgeMemoryEvent;
+        case: KnowledgeMemoryBenchmarkCase;
+        eventIndex: number;
+    }) => AgentMemoryScope;
+    probeScope?: (testCase: KnowledgeMemoryBenchmarkCase) => AgentMemoryScope;
+}
+interface AgentMemoryExperimentCandidate {
+    id: string;
+    label?: string;
+    /** Change when provider configuration changes so cached cells cannot be reused. */
+    ref: string;
+    /** Local construction is free; call markExternalCall before billable provisioning or reconnects. */
+    createAdapter(input: {
+        branchId: string;
+        purpose: 'execute' | 'recovery';
+        signal: AbortSignal;
+        /** Maximum the adapter must enforce with its provider before external work. */
+        maximumCostUsd: number;
+        markExternalCall(): void;
+        /** Record each observed provider charge. Required for complete positive-cost accounting. */
+        recordExternalCost(actualCostUsd: number): void;
+    }): AgentMemoryAdapter | null | Promise<AgentMemoryAdapter | null>;
+    policy?: AgentMemorySharingPolicy;
+    baseScope?: AgentMemoryScope;
+    /** Maximum the adapter must enforce for one complete history. Zero declares a free path. */
+    externalCostUsdPerSequence?: number;
+    /** Maximum the adapter must enforce for one recovery attempt. Zero declares free recovery. */
+    externalRecoveryCostUsdPerAttempt?: number;
+    /** Requires observed provider receipts for positive external charges. */
+    externalCostAccounting?: 'exact';
+    /** Release resources and, when cleanupBranches is false, delete the isolated state. */
+    disposeAdapter?(adapter: AgentMemoryAdapter): Promise<void>;
+}
+interface AgentMemorySequenceProbeResult {
+    id: string;
+    stepId: string;
+    query: string;
+    score: number;
+    passed: boolean;
+    dimensions: Record<string, number>;
+    applicableDimensions: readonly string[];
+    notes: string;
+    hitIds: readonly string[];
+}
+interface AgentMemorySequenceArtifact {
+    candidateId: string;
+    sequenceId: string;
+    score: number;
+    passed: boolean;
+    dimensions: Record<string, number>;
+    dimensionSampleCounts: Record<string, number>;
+    probes: readonly AgentMemorySequenceProbeResult[];
+    branchDigest: string;
+    journalEntries: number;
+    durationMs: number;
+}
+interface AgentMemorySequenceScenario extends Scenario {
+    kind: 'agent-memory-sequence';
+    candidateId: string;
+    sequenceId: string;
+    sequence: AgentMemorySequence;
+    seedGroup: string;
+}
+interface AgentMemoryExperimentRankingRow {
+    rank: number;
+    candidateId: string;
+    label: string;
+    scoreMean: number;
+    passRate: number;
+    totalSequences: number;
+    totalCells: number;
+    totalProbes: number;
+    cellsFailed: number;
+    totalCostUsd: number;
+    durationMs: number;
+    dimensions: Record<string, number>;
+}
+interface RunAgentMemoryExperimentOptions {
+    experimentId: string;
+    /** Stable external branch namespace; distributed workers must use the same value. */
+    experimentRunId?: string;
+    sequences: readonly AgentMemorySequence[];
+    candidates: readonly AgentMemoryExperimentCandidate[];
+    /** Retired candidates retained only so interrupted branches can be cleaned on resume. */
+    recoveryCandidates?: readonly AgentMemoryExperimentCandidate[];
+    runDir: string;
+    executeStep?: (input: {
+        memory: AgentMemoryBranch;
+        candidateId: string;
+        step: AgentMemoryExecutionStep;
+        context: AgentMemoryExecutionContext;
+    }) => Promise<void>;
+    /** Required with executeStep; identify the runtime/profile behavior in cache keys. */
+    executeStepRef?: string;
+    onBranchSnapshot?: (input: {
+        candidateId: string;
+        sequenceId: string;
+        cellId: string;
+        snapshot: AgentMemoryBranchSnapshot;
+    }) => Promise<void> | void;
+    cleanupBranches?: boolean;
+    storage?: CampaignStorage;
+    repo?: string;
+    seed?: number;
+    reps?: number;
+    resumable?: boolean;
+    costCeiling?: number;
+    /** Shared across nested experiments when an outer improvement run owns spend. */
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+    maxConcurrency?: number;
+    dispatchTimeoutMs?: number;
+    /** Total deadline for each provider cleanup, close, or recovery operation. */
+    cleanupTimeoutMs?: number;
+    /** Refuse a damaged run with more unfinished attempts than this. Default 1000. */
+    maxRecoveryAttempts?: number;
+    /** Bound repeated provider cleanup after process crashes. Default 3 per attempt. */
+    maxRecoveryRetriesPerAttempt?: number;
+    now?: () => Date;
+    /** Required with custom storage when all controllers are confined to one process. */
+    controllerMode?: AgentMemoryControllerMode;
+    /** Required for distributed controllers that share custom storage. */
+    acquireRunLease?: AgentMemoryAcquireRunLease;
+}
+type AgentMemoryExperimentRunLease = AgentMemoryRunLease;
+interface AgentMemoryAttemptEvent {
+    status: 'started' | 'cleaned';
+    branchId: string;
+    candidateId: string;
+    candidateRef: string;
+    sequenceId: string;
+    rep: number;
+    seed: number;
+    cleanupBranches: boolean;
+    externalCostUsdPerSequence: number;
+    externalRecoveryCostUsdPerAttempt: number;
+    recordedAt: string;
+    recovery: boolean;
+}
+interface RunAgentMemoryExperimentResult {
+    campaign: CampaignResult<AgentMemorySequenceArtifact, AgentMemorySequenceScenario>;
+    rows: readonly AgentMemoryExperimentRankingRow[];
+    totalCostUsd: number;
+    /** Recovery spend for retired candidates, excluded from ranking rows but included in totalCostUsd. */
+    unrankedRecoveryCostUsd: number;
+    leaderCandidateId?: string;
+    rankingJsonPath: string;
+    rankingMarkdownPath: string;
+    attemptLogPath: string;
+    recoveryLogPath: string;
+}
+
+/** Converts existing ordered memory benchmark cases into executable histories. */
+
+declare function buildAgentMemorySequencesFromBenchmarkCases(cases: readonly KnowledgeMemoryBenchmarkCase[], options?: BuildAgentMemorySequencesFromBenchmarkCasesOptions): AgentMemorySequence[];
+declare function buildAgentMemorySequenceScenarios(sequences: readonly AgentMemorySequence[], candidates: readonly Pick<AgentMemoryExperimentCandidate, 'id'>[]): AgentMemorySequenceScenario[];
+declare function agentMemorySequenceJudge<TScenario extends Scenario = AgentMemorySequenceScenario>(): JudgeConfig<AgentMemorySequenceArtifact, TScenario>;
+
+/** Runs ordered, branch-isolated memory histories across candidate systems. */
+declare function runAgentMemoryExperiment(options: RunAgentMemoryExperimentOptions): Promise<RunAgentMemoryExperimentResult>;
+
+interface GraphitiMcpClientLike {
+    callTool(request: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+interface GraphitiMemoryAdapterOptions {
+    client: GraphitiMcpClientLike;
+    id?: string;
+    /** Stable server/deployment identity for cache-key helpers. Never put credentials here. */
+    backendRef?: string;
+    defaultScope?: AgentMemoryScope;
+    consistency?: 'queued' | 'visible';
+    ingestionTimeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Maximum episodes inspected to prove a queued write became visible. */
+    episodeScanLimit?: number;
+    provenanceEpisodeLimit?: number;
+    search?: readonly ('facts' | 'nodes')[];
+    toolNames?: Partial<GraphitiToolNames>;
+}
+interface GraphitiToolNames {
+    addMemory: string;
+    searchFacts: string;
+    searchNodes: string;
+    getEpisodes: string;
+    clearGraph: string;
+}
+/** Connects the official Graphiti MCP server without coupling to its Python internals. */
+declare function createGraphitiMemoryAdapter(options: GraphitiMemoryAdapterOptions): AgentMemoryAdapter;
+declare function graphitiMemoryAdapterIdentity(options: Pick<GraphitiMemoryAdapterOptions, 'id' | 'consistency' | 'ingestionTimeoutMs' | 'pollIntervalMs' | 'episodeScanLimit' | 'provenanceEpisodeLimit' | 'search' | 'toolNames' | 'defaultScope'> & {
+    backendRef: string;
+}): string;
+
+/**
+ * Deterministic uniform [0,1) for assignment draws. The sha256 key derivation is ours — it makes
+ * every draw replayable from the logged keys alone (design rule D5) — while the generator core is
+ * the substrate's `mulberry32` (@tangle-network/agent-eval statistics vocabulary), seeded with the
+ * top 32 bits of the digest, so the statistical machinery is reused rather than forked.
+ */
+declare function deterministicRng(key: string): number;
+/**
+ * Value-hash of the knobs that DEFINE the experiment (epsilon + watchlist, order-independent).
+ * Everything else on the config (callbacks, attribution stamps, privacy flags) does not change
+ * which assignments are drawn, so it stays out of the hash.
+ */
+declare function retrievalHoldoutConfigHash(config: Pick<RetrievalHoldoutConfig, 'epsilon' | 'watchlist'>): string;
+/**
+ * Pure per-call holdout: takes post-filter hits, returns delivered hits plus the log event
+ * and the next session state. Suppression only removes items (no backfill), and it happens
+ * before rendering so a drop session's context is byte-identical to a natural smaller retrieval.
+ */
+declare function applyRetrievalHoldout(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx?: RetrievalHoldoutCallContext): RetrievalHoldoutResult;
+/**
+ * Logs a holdout event for adapter context paths that answer WITHOUT going through the
+ * search→render seam (Neo4j short-term conversation context, raw-string getContext results),
+ * so a consumer with a holdout configured still sees every call and the fraction-under-experiment
+ * denominator stays honest instead of silently losing these calls. No suppression is applied:
+ * dropping is only meaningful for retrieved memory hits, never for conversation context.
+ */
+declare function emitRetrievalHoldoutBypass(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx: Omit<RetrievalHoldoutCallContext, 'session'>, bypassReason: RetrievalHoldoutBypassReason): RetrievalHoldoutEvent;
+/**
+ * Clears all sticky-session state. For test isolation and experiment-epoch boundaries;
+ * sessions in flight afterwards re-draw deterministically (same rng keys), so with the default
+ * rng a reset is invisible in the logs unless eligibility sets changed in between.
+ */
+declare function resetRetrievalHoldoutRegistry(): void;
+/**
+ * Convenience wrapper that threads session state internally, keyed by the VALUE of the
+ * experiment-defining knobs (configHash = epsilon + sorted watchlist) plus sessionId, so a fresh
+ * config object per call — the natural pattern when options are built inline — keeps full
+ * stickiness. Distinct experiments never share session state; two config objects with the same
+ * epsilon/watchlist are the same experiment by definition.
+ */
+declare function applySessionStickyRetrievalHoldout(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx?: Omit<RetrievalHoldoutCallContext, 'session'>): RetrievalHoldoutResult;
+/** Aggregated view of one session's holdout exposure — the randomization unit of this design. */
+interface RetrievalHoldoutSessionSummary {
+    /** `${configHash}:${sessionIdHash}` — the trajectory's runId. */
+    runId: string;
+    configHash: string;
+    sessionIdHash: string;
+    sessionHoldout: boolean;
+    sessionTargetId: string | null;
+    /** Item actually suppressed in this session (equals sessionTargetId when a drop occurred). */
+    droppedId: string | null;
+    /** |watchlist ∩ E| at the session's first intersecting randomized call; 0 when never intersecting. */
+    firstCandidateCount: number;
+    /** Randomized retrieval calls observed for this session. */
+    callCount: number;
+    /** Adapter bypass calls observed for this session (logged, never randomized). */
+    bypassCallCount: number;
+    /** Session-level probability of the OBSERVED assignment under the behavior policy. */
+    behaviorProb: number;
+    /** True when the session's events disagree on arm or target (e.g. registry eviction re-draw). */
+    mixedExposure: boolean;
+    /** Present only on sessions surfaced in `excluded` rather than converted. */
+    exclusionReason?: 'mixed-exposure' | 'no-randomized-calls';
+}
+interface RetrievalHoldoutOffPolicyOptions {
+    /**
+     * Realized outcome PER SESSION, keyed by sessionIdHash — the session is the randomization
+     * unit, so rewards are per session, never per call. A missing entry for an included session
+     * throws: silently dropping unscored sessions would corrupt the estimator's denominator, so
+     * filter events to scored sessions upstream instead.
+     */
+    rewards: Record<string, number>;
+    /**
+     * Target-policy probability of the session's observed assignment. Default models the
+     * always-deliver-in-full policy: 1 for full-delivery sessions, 0 for drop sessions.
+     */
+    targetProb?: (session: RetrievalHoldoutSessionSummary) => number;
+    /** Per-session reward-model prediction enabling `doublyRobust`; when absent, qHat is null. */
+    qHat?: (session: RetrievalHoldoutSessionSummary) => number | null;
+}
+interface RetrievalHoldoutOffPolicyResult {
+    /** One trajectory per (configHash, sessionIdHash), never per call. */
+    trajectories: OffPolicyTrajectory[];
+    /** 1:1 with `trajectories` (same order): the diagnostic view of each converted session. */
+    sessions: RetrievalHoldoutSessionSummary[];
+    /** Sessions not converted because exposure was mixed or retrieval was bypassed. */
+    excluded: RetrievalHoldoutSessionSummary[];
+    /** Events with no sessionIdHash: outside session randomization, cannot join a reward. */
+    unattributableEvents: number;
+}
+/**
+ * Maps retrieval-dropout events onto one `OffPolicyTrajectory` per session for use with
+ * `inverseProbabilityWeighting`, `selfNormalizedImportanceWeighting`, or `doublyRobust`.
+ * Randomization occurs once per session: the arm is selected with P(dropout) = epsilon and
+ * the sticky target is drawn once,
+ * uniformly over watchlist ∩ E at the session's first intersecting call.
+ *
+ * Session-level action space and behavior probabilities (they sum to 1 by construction):
+ * - full delivery: `1 - epsilon`;
+ * - drop candidate i of k = |watchlist ∩ E_first|: `epsilon / k` each (the draw event's logged
+ *   `dropPropensity`);
+ * - sessions whose eligibility sets never intersect the watchlist: probability 1, because full
+ *   delivery was certain in either arm.
+ *
+ * Per-call events are repeated observations WITHIN one session-level randomization; per-call
+ * IPW is statistically invalid for this design (per-call "propensities" imply an action
+ * distribution summing to more than 1 and bias IPS downward). Calls where the sticky target is
+ * absent from E, and adapter bypass calls, fold into the session summary (callCount /
+ * bypassCallCount) instead of generating independent propensities.
+ *
+ * Join contract: `rewards` is keyed by `sessionIdHash` (sha256(sessionId) first 16 hex; compute
+ * the same prefix over the outcome table's session ids, or log with
+ * `includePlaintextIdentifiers: true` and join on raw ids upstream). Events are grouped per
+ * (configHash, sessionIdHash) so different experiment configs are never pooled. Mixed-exposure
+ * sessions (arm or target disagreement, e.g. after registry eviction) are excluded from the
+ * trajectories and surfaced in `excluded` for analysis.
+ */
+declare function toOffPolicyTrajectory(events: RetrievalHoldoutEvent[], options: RetrievalHoldoutOffPolicyOptions): RetrievalHoldoutOffPolicyResult;
+
+interface AgentMemoryDimensionComparison {
+    dimension: string;
+    n: number;
+    expectedN: number;
+    measured: boolean;
+    meanDelta: number;
+    low: number;
+    high: number;
+    tolerance: number;
+    regressed: boolean;
+}
+interface AgentMemoryPromotionDecision {
+    status: 'promote' | 'hold' | 'no-change';
+    reasons: readonly string[];
+    baselineScore: number;
+    winnerScore: number;
+    lift: number;
+    significance?: HeldoutSignificance;
+    criticalDimensions: readonly AgentMemoryDimensionComparison[];
+}
+interface AgentMemoryFinalPair {
+    sequenceId: string;
+    rep: number;
+    baseline: AgentMemorySequenceArtifact;
+    winner: AgentMemorySequenceArtifact;
+}
+interface AgentMemoryFinalEvaluation {
+    manifestHash: string;
+    baselineCandidateRef: string;
+    winnerCandidateRef: string;
+    pairs: readonly AgentMemoryFinalPair[];
+}
+interface AgentMemoryActivation {
+    id: string;
+    status: 'not-eligible' | 'not-configured' | 'pending' | 'activated' | 'recovered' | 'already-activated';
+    journalPath: string;
+}
+interface AgentMemoryActivationDriver<TConfig extends AgentCandidateJsonValue> {
+    /** Change whenever activation behavior or the external target changes. */
+    ref: string;
+    /** Return the exact currently active configuration. */
+    readCurrent(): Promise<TConfig>;
+    /** Atomically replace expectedConfig with config, or fail on a concurrent change. */
+    compareAndSet(input: {
+        activationId: string;
+        expectedConfig: TConfig;
+        expectedSurfaceHash: string;
+        config: TConfig;
+        surfaceHash: string;
+        decision: AgentMemoryPromotionDecision;
+        optimization: RunSerializedKnowledgeOptimizationResult<TConfig>;
+        finalEvaluation: AgentMemoryFinalEvaluation;
+    }): Promise<void>;
+}
+type AgentMemoryImprovementRunLease = AgentMemoryRunLease;
+type AgentMemoryImprovementCandidate = Omit<AgentMemoryExperimentCandidate, 'id' | 'externalCostUsdPerSequence' | 'externalRecoveryCostUsdPerAttempt' | 'externalCostAccounting'> & Required<Pick<AgentMemoryExperimentCandidate, 'externalCostUsdPerSequence' | 'externalRecoveryCostUsdPerAttempt'>> & {
+    externalCostAccounting: 'exact';
+};
+interface RunAgentMemoryImprovementOptions<TConfig extends AgentCandidateJsonValue> {
+    experimentId: string;
+    baselineConfig: TConfig;
+    method: OptimizationMethod<MemoryConfigScenario, AgentMemorySequenceArtifact>;
+    trainSequences: readonly AgentMemorySequence[];
+    selectionSequences: readonly AgentMemorySequence[];
+    finalSequences: readonly AgentMemorySequence[];
+    createCandidate(input: {
+        config: TConfig;
+        candidateId: string;
+        surfaceHash: string;
+    }): AgentMemoryImprovementCandidate | Promise<AgentMemoryImprovementCandidate>;
+    /**
+     * Immutable digest covering the installed implementation, method config,
+     * candidate construction, execution behavior, and external settings.
+     */
+    implementationRef: string;
+    runDir: string;
+    repo?: string;
+    storage?: CampaignStorage;
+    /** Required with custom storage when all controllers are confined to one process. */
+    controllerMode?: AgentMemoryControllerMode;
+    /** Required for distributed controllers using custom storage. */
+    acquireRunLease?: AgentMemoryAcquireRunLease;
+    seed?: number;
+    reps?: number;
+    resumable?: boolean;
+    sequenceConcurrency?: number;
+    dispatchTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    maxRecoveryAttempts?: number;
+    maxRecoveryRetriesPerAttempt?: number;
+    /** Total spend limit across method search and final comparison. Default 0. */
+    maxTotalCostUsd?: number;
+    /** Enforced maximum for one config and one sequence. Required with either spend limit. */
+    maximumEvaluationCostUsd?: number;
+    /** Allow activation when a method cannot fully account for cost. Default false. */
+    allowIncompleteCostAccounting?: boolean;
+    optimizationRunOptions?: OptimizationMethodRunOptions<MemoryConfigScenario, AgentMemorySequenceArtifact>;
+    executeStep?: RunAgentMemoryExperimentOptions['executeStep'];
+    executeStepRef?: string;
+    onBranchSnapshot?: RunAgentMemoryExperimentOptions['onBranchSnapshot'];
+    cleanupBranches?: boolean;
+    serializeConfig?: (config: TConfig) => string;
+    parseConfig?: (surface: string) => TConfig;
+    significance?: HeldoutSignificanceOptions;
+    criticalDimensions?: readonly string[];
+    criticalDimensionTolerance?: number;
+    minFinalScore?: number;
+    activation?: AgentMemoryActivationDriver<TConfig>;
+    activationTimeoutMs?: number;
+    now?: () => Date;
+}
+interface RunAgentMemoryImprovementResult<TConfig extends AgentCandidateJsonValue> {
+    optimization: RunSerializedKnowledgeOptimizationResult<TConfig>;
+    baselineConfig: TConfig;
+    winnerConfig: TConfig;
+    baselineSurface: string;
+    winnerSurface: string;
+    baselineSurfaceHash: string;
+    winnerSurfaceHash: string;
+    decision: AgentMemoryPromotionDecision;
+    finalEvaluation: AgentMemoryFinalEvaluation;
+    activation: AgentMemoryActivation;
+    totalCostUsd: number;
+    resultJsonPath: string;
+}
+interface MemoryConfigScenario extends Scenario {
+    kind: 'agent-memory-config-search';
+    sequenceId: string;
+    sequence: AgentMemorySequence;
+}
+
+/** Optimizes memory configuration with an external method and activates only a fresh final win. */
+declare function runAgentMemoryImprovement<TConfig extends AgentCandidateJsonValue>(options: RunAgentMemoryImprovementOptions<TConfig>): Promise<RunAgentMemoryImprovementResult<TConfig>>;
+
+declare const DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS = 180000;
+declare class AgentMemoryLifecycleTimeoutError extends Error {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    constructor(operation: string, timeoutMs: number);
+}
+declare class AgentMemoryLifecycleUnsafeError extends Error {
+    readonly operation: string;
+    readonly priorTimeout: AgentMemoryLifecycleTimeoutError;
+    constructor(operation: string, priorTimeout: AgentMemoryLifecycleTimeoutError);
+}
+declare function resolveMemoryCleanupTimeoutMs(value: number | undefined, label: string): number;
+declare function runBoundedMemoryLifecycle<T>(input: {
+    operation: string;
+    timeoutMs: number;
+    /** Prevent later operations from using the same client while timed-out work may still be running. */
+    resource?: object;
+    /** Cooperatively cancel provider work before reporting a timeout. */
+    abortController?: AbortController;
+    run(): Promise<T> | T;
+}): Promise<T>;
+declare function memoryRecoveryDelayMs(adapter: AgentMemoryAdapter): number;
+declare function sleepForMemoryRecovery(delayMs: number, assertOwned: () => Promise<void>, timeoutMs?: number, operation?: string): Promise<void>;
+declare function createMemoryExecutionPool(limit: number): {
+    run<T>(operation: () => Promise<T>): Promise<T>;
+};
+
+type Mem0ClientMode = 'hosted' | 'oss';
+interface Mem0ClientLike {
+    add(messages: Array<{
+        role: string;
+        content: string;
+    }>, options?: Record<string, unknown>): Promise<unknown>;
+    search(query: string, options?: Record<string, unknown>): Promise<unknown>;
+    getAll?(options?: Record<string, unknown>): Promise<unknown>;
+    delete?(memoryId: string, options?: Record<string, unknown>): Promise<unknown>;
+}
+interface Mem0MemoryAdapterOptions {
+    client: Mem0ClientLike;
+    mode: Mem0ClientMode;
+    id?: string;
+    appId?: string;
+    infer?: boolean;
+    rerank?: boolean;
+    latestOnly?: boolean;
+    /** Bounds delayed-delete visibility checks and abandoned hosted-write recovery waits. */
+    ingestionTimeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Stable deployment/account identity for cache-key helpers. Never put credentials here. */
+    backendRef?: string;
+    defaultScope?: AgentMemoryScope;
+}
+/** Connects both the hosted Mem0 client and the open-source `Memory` class. */
+declare function createMem0MemoryAdapter(options: Mem0MemoryAdapterOptions): AgentMemoryAdapter;
+/** Stable identity useful for dispatch/cache keys without exposing client credentials. */
+declare function mem0MemoryAdapterIdentity(options: Pick<Mem0MemoryAdapterOptions, 'mode' | 'id' | 'appId' | 'infer' | 'rerank' | 'latestOnly' | 'ingestionTimeoutMs' | 'pollIntervalMs' | 'defaultScope'> & {
+    backendRef: string;
+}): string;
+
+interface Neo4jAgentMemoryAdapterOptions {
+    client: object;
+    /** Match the transport passed to the official MemoryClient. */
+    transport: 'rest' | 'bridge';
+    /** Use Neo4j's whole-conversation context instead of query-based search. */
+    contextMode?: 'search' | 'native';
+    id?: string;
+    /** Assert that the client owns disposable external state for this exact branch. */
+    branchId?: string;
+}
+declare function createNeo4jAgentMemoryAdapter(options: Neo4jAgentMemoryAdapterOptions): AgentMemoryAdapter;
+
+declare const AgentMemoryKindSchema: z.ZodEnum<{
+    preference: "preference";
+    message: "message";
+    entity: "entity";
+    fact: "fact";
+    observation: "observation";
+    "reasoning-trace": "reasoning-trace";
+}>;
+declare const AgentMemoryScopeSchema: z.ZodObject<{
+    tenantId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+declare const AgentMemoryHitSchema: z.ZodObject<{
+    id: z.ZodString;
+    uri: z.ZodString;
+    kind: z.ZodEnum<{
+        preference: "preference";
+        message: "message";
+        entity: "entity";
+        fact: "fact";
+        observation: "observation";
+        "reasoning-trace": "reasoning-trace";
+    }>;
+    text: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    score: z.ZodOptional<z.ZodNumber>;
+    normalizedScore: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    validUntil: z.ZodOptional<z.ZodString>;
+    lastVerifiedAt: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const AgentMemoryWriteInputSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        preference: "preference";
+        message: "message";
+        entity: "entity";
+        fact: "fact";
+        observation: "observation";
+        "reasoning-trace": "reasoning-trace";
+    }>;
+    text: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>>;
+    entityName: z.ZodOptional<z.ZodString>;
+    entityType: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    predicate: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodString>;
+    object: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    scope: z.ZodOptional<z.ZodObject<{
+        tenantId: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+        agentId: z.ZodOptional<z.ZodString>;
+        teamId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        namespace: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+
+declare function memoryHitToSourceRecord(hit: AgentMemoryHit, options?: {
+    now?: () => Date;
+    scope?: AgentMemoryScope;
+}): SourceRecord;
+declare function memoryWriteResultToSourceRecord(result: AgentMemoryWriteResult, text: string, options?: {
+    now?: () => Date;
+    scope?: AgentMemoryScope;
+}): SourceRecord;
+
+export { type RunAgentMemoryExperimentResult as $, type AgentMemoryActivation as A, type AgentMemorySequence as B, type AgentMemorySequenceArtifact as C, type AgentMemorySequenceProbe as D, type AgentMemorySequenceProbeResult as E, type AgentMemorySequenceScenario as F, type AgentMemorySequenceStep as G, type AgentMemorySharingPolicy as H, type AgentMemoryVisibility as I, AgentMemoryWriteInputSchema as J, type BuildAgentMemorySequencesFromBenchmarkCasesOptions as K, type CreateAgentMemoryBranchOptions as L, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as M, type ForkAgentMemoryBranchSnapshotOptions as N, type GraphitiMcpClientLike as O, type GraphitiMemoryAdapterOptions as P, type GraphitiToolNames as Q, type RunSerializedKnowledgeOptimizationResult as R, type Mem0ClientLike as S, type Mem0ClientMode as T, type Mem0MemoryAdapterOptions as U, type MemoryConfigScenario as V, type Neo4jAgentMemoryAdapterOptions as W, type RetrievalHoldoutOffPolicyOptions as X, type RetrievalHoldoutOffPolicyResult as Y, type RetrievalHoldoutSessionSummary as Z, type RunAgentMemoryExperimentOptions as _, type RunSerializedKnowledgeOptimizationOptions as a, type RunAgentMemoryImprovementOptions as a0, type RunAgentMemoryImprovementResult as a1, type SerializedCandidate as a2, type SerializedCandidateCodec as a3, agentMemorySequenceJudge as a4, applyRetrievalHoldout as a5, applySessionStickyRetrievalHoldout as a6, buildAgentMemorySequenceScenarios as a7, buildAgentMemorySequencesFromBenchmarkCases as a8, createAgentMemoryBranch as a9, createGraphitiMemoryAdapter as aa, createMem0MemoryAdapter as ab, createMemoryExecutionPool as ac, createNeo4jAgentMemoryAdapter as ad, defaultGetMemoryContext as ae, deterministicRng as af, emitRetrievalHoldoutBypass as ag, forkAgentMemoryBranchSnapshot as ah, graphitiMemoryAdapterIdentity as ai, jsonCandidateCodec as aj, jsonObjectCandidateCodec as ak, mem0MemoryAdapterIdentity as al, memoryHitToSourceRecord as am, memoryRecoveryDelayMs as an, memoryWriteResultToSourceRecord as ao, renderMemoryContext as ap, resetRetrievalHoldoutRegistry as aq, resolveMemoryCleanupTimeoutMs as ar, retrievalHoldoutConfigHash as as, runAgentMemoryExperiment as at, runAgentMemoryImprovement as au, runBoundedMemoryLifecycle as av, runSerializedKnowledgeOptimization as aw, scenarioContentFingerprint as ax, sleepForMemoryRecovery as ay, toOffPolicyTrajectory as az, type AgentMemoryActivationDriver as b, type AgentMemoryAttemptEvent as c, type AgentMemoryBranch as d, type AgentMemoryBranchLifetime as e, type AgentMemoryBranchSnapshot as f, type AgentMemoryDimensionComparison as g, type AgentMemoryExecutionContext as h, type AgentMemoryExecutionCostMeter as i, type AgentMemoryExecutionCostReceipt as j, type AgentMemoryExecutionPaidCallInput as k, type AgentMemoryExecutionPaidCallResult as l, type AgentMemoryExecutionStep as m, type AgentMemoryExperimentCandidate as n, type AgentMemoryExperimentRankingRow as o, type AgentMemoryExperimentRunLease as p, type AgentMemoryFinalEvaluation as q, type AgentMemoryFinalPair as r, AgentMemoryHitSchema as s, type AgentMemoryImprovementRunLease as t, type AgentMemoryJournalEntry as u, AgentMemoryKindSchema as v, AgentMemoryLifecycleTimeoutError as w, AgentMemoryLifecycleUnsafeError as x, type AgentMemoryPromotionDecision as y, AgentMemoryScopeSchema as z };