@tangle-network/agent-knowledge 3.2.1 → 4.0.0

package/dist/memory/index.d.ts

@@ -1,5 +1,6 @@
-import { A as AgentMemoryAdapter, e as AgentMemorySearchOptions, b as AgentMemoryContext, c as AgentMemoryHit, a as AgentMemoryScope, g as AgentMemoryWriteResult } from '../types-BFRyr390.js';
-export { d as AgentMemoryKind, f as AgentMemoryWriteInput, R as RetrievalHoldoutBypassReason, h as RetrievalHoldoutCallContext, i as RetrievalHoldoutConfig, j as RetrievalHoldoutEligibleItem, k as RetrievalHoldoutEvent, l as RetrievalHoldoutOffPolicyOptions, m as RetrievalHoldoutOffPolicyResult, n as RetrievalHoldoutResult, o as RetrievalHoldoutSessionState, p as RetrievalHoldoutSessionSummary, q as applyRetrievalHoldout, r as applySessionStickyRetrievalHoldout, s as deterministicRng, t as emitRetrievalHoldoutBypass, u as resetRetrievalHoldoutRegistry, v as retrievalHoldoutConfigHash, w as toOffPolicyTrajectory } from '../types-BFRyr390.js';
+import { b as AgentMemoryAdapter, j as AgentMemorySearchOptions, d as AgentMemoryContext, f as AgentMemoryHit, i as AgentMemoryScope, k as AgentMemoryWriteInput, l as AgentMemoryWriteResult, v as KnowledgeBenchmarkFamily, E as KnowledgeBenchmarkSplit, J as KnowledgeMemoryBenchmarkTaskKind, M as KnowledgeMemoryFactMatcher, h as AgentMemoryRunLease, L as KnowledgeMemoryEvent, H as KnowledgeMemoryBenchmarkCase, e as AgentMemoryControllerMode, A as AgentMemoryAcquireRunLease } from '../index-Bqg1mBPt.js';
+export { c as AgentMemoryBranchIsolation, g as AgentMemoryKind, T as OwnedAgentMemoryRunLease, $ as RetrievalHoldoutBypassReason, a0 as RetrievalHoldoutCallContext, a1 as RetrievalHoldoutConfig, a2 as RetrievalHoldoutEligibleItem, a3 as RetrievalHoldoutEvent, a4 as RetrievalHoldoutOffPolicyOptions, a5 as RetrievalHoldoutOffPolicyResult, a6 as RetrievalHoldoutResult, a7 as RetrievalHoldoutSessionState, a8 as RetrievalHoldoutSessionSummary, ak as acquireAgentMemoryRunLease, al as applyRetrievalHoldout, am as applySessionStickyRetrievalHoldout, aw as deterministicRng, ax as emitRetrievalHoldoutBypass, aD as resetRetrievalHoldoutRegistry, aI as retrievalHoldoutConfigHash, aS as toOffPolicyTrajectory } from '../index-Bqg1mBPt.js';
+import { CampaignResult, Scenario, DispatchContext, CampaignStorage, CostLedgerHandle, JudgeConfig, HeldoutSignificance, Lineage, GovernorContext, GovernorOp, SurfaceProposer, LineageStore, HeldoutSignificanceOptions } from '@tangle-network/agent-eval/campaign';
 import { z } from 'zod';
 import { S as SourceRecord } from '../types-6x0OpfW6.js';
 import '@tangle-network/agent-eval/rl';
@@ -7,9 +8,489 @@ import '@tangle-network/agent-eval/rl';
 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>;
+}
+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;
+        sequence: AgentMemorySequence;
+        rep: number;
+        seed: number;
+        purpose: 'execute' | 'recovery';
+        signal: AbortSignal;
+        markExternalCall(): void;
+    }): AgentMemoryAdapter | null | Promise<AgentMemoryAdapter | null>;
+    policy?: AgentMemorySharingPolicy;
+    baseScope?: AgentMemoryScope;
+    /** Conservative external provider charge for one complete history. */
+    externalCostUsdPerSequence?: number;
+    /** Conservative extra provider charge when recovering one interrupted history. */
+    externalRecoveryCostUsdPerAttempt?: number;
+    /** 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;
+        sequence: AgentMemorySequence;
+        step: AgentMemorySequenceStep;
+        context: DispatchContext;
+    }) => 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 {
+    schema: 2;
+    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[];
+/** Runs ordered, branch-isolated memory histories across candidate systems. */
+declare function runAgentMemoryExperiment(options: RunAgentMemoryExperimentOptions): Promise<RunAgentMemoryExperimentResult>;
+declare function buildAgentMemorySequenceScenarios(sequences: readonly AgentMemorySequence[], candidates: readonly Pick<AgentMemoryExperimentCandidate, 'id'>[]): AgentMemorySequenceScenario[];
+declare function agentMemorySequenceJudge(): JudgeConfig<AgentMemorySequenceArtifact, AgentMemorySequenceScenario>;
+
+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;
+
+interface AgentMemoryImprovementSeed<TConfig> {
+    config: TConfig;
+    track: string;
+    vision?: string;
+    proposer: string;
+}
+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 AgentMemoryActivation {
+    id: string;
+    status: 'not-eligible' | 'not-configured' | 'pending' | 'activated' | 'recovered' | 'already-activated';
+    journalPath: string;
+}
+interface AgentMemoryActivationDriver<TConfig> {
+    /** 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;
+        lineage: Lineage;
+        holdout: RunAgentMemoryExperimentResult;
+    }): Promise<void>;
+}
+type AgentMemoryImprovementRunLease = AgentMemoryRunLease;
+interface AgentMemoryGovernor {
+    decide(context: GovernorContext & {
+        costLedger: CostLedgerHandle;
+        costPhase: string;
+    }): GovernorOp | Promise<GovernorOp>;
+}
+interface RunAgentMemoryImprovementOptions<TConfig> {
+    experimentId: string;
+    trainSequences: readonly AgentMemorySequence[];
+    holdoutSequences: readonly AgentMemorySequence[];
+    /** First entry is the current baseline; remaining entries seed independent search tracks. */
+    seeds: readonly AgentMemoryImprovementSeed<TConfig>[];
+    createCandidate(input: {
+        config: TConfig;
+        candidateId: string;
+        surfaceHash: string;
+    }): Omit<AgentMemoryExperimentCandidate, 'id'> | Promise<Omit<AgentMemoryExperimentCandidate, 'id'>>;
+    proposer: SurfaceProposer;
+    /** Optional proposer implementations keyed by seed and branch proposer labels. */
+    proposers?: Readonly<Record<string, SurfaceProposer>>;
+    /** Stable version or commit for the candidate factory, proposer, and governor. */
+    improvementRef: string;
+    governor?: AgentMemoryGovernor;
+    budget: {
+        maxSteps: number;
+    };
+    populationSize?: number;
+    candidateConcurrency?: number;
+    sequenceConcurrency?: number;
+    runDir: string;
+    repo?: string;
+    storage?: CampaignStorage;
+    lineageStore?: LineageStore;
+    /** Required with custom storage when all controllers are confined to one process. */
+    controllerMode?: AgentMemoryControllerMode;
+    /** Required for distributed controllers using custom storage. Worker concurrency is independent. */
+    acquireRunLease?: AgentMemoryAcquireRunLease;
+    seed?: number;
+    reps?: number;
+    resumable?: boolean;
+    dispatchTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    maxRecoveryAttempts?: number;
+    maxRecoveryRetriesPerAttempt?: number;
+    maxTotalCostUsd?: number;
+    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;
+    minHoldoutScore?: number;
+    activation?: AgentMemoryActivationDriver<TConfig>;
+    activationTimeoutMs?: number;
+    now?: () => Date;
+}
+interface RunAgentMemoryImprovementResult<TConfig> {
+    lineage: Lineage;
+    baselineConfig: TConfig;
+    winnerConfig: TConfig;
+    baselineSurface: string;
+    winnerSurface: string;
+    baselineSurfaceHash: string;
+    winnerSurfaceHash: string;
+    decision: AgentMemoryPromotionDecision;
+    activation: AgentMemoryActivation;
+    holdout?: RunAgentMemoryExperimentResult;
+    totalCostUsd: number;
+    resultJsonPath: string;
+}
+/** Searches branchable memory configurations and activates only a fresh holdout win. */
+declare function runAgentMemoryImprovement<TConfig>(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: Record<string, unknown>;
+    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;
 
@@ -24,6 +505,9 @@ declare const AgentMemoryKindSchema: z.ZodEnum<{
 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>>;
@@ -77,6 +561,9 @@ declare const AgentMemoryWriteInputSchema: z.ZodObject<{
     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>>;
@@ -93,4 +580,4 @@ declare function memoryWriteResultToSourceRecord(result: AgentMemoryWriteResult,
     scope?: AgentMemoryScope;
 }): SourceRecord;
 
-export { AgentMemoryAdapter, AgentMemoryContext, AgentMemoryHit, AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryScope, AgentMemoryScopeSchema, AgentMemorySearchOptions, AgentMemoryWriteInputSchema, AgentMemoryWriteResult, type Neo4jAgentMemoryAdapterOptions, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, memoryHitToSourceRecord, memoryWriteResultToSourceRecord, renderMemoryContext };
+export { AgentMemoryAcquireRunLease, type AgentMemoryActivation, type AgentMemoryActivationDriver, AgentMemoryAdapter, type AgentMemoryAttemptEvent, type AgentMemoryBranch, type AgentMemoryBranchLifetime, type AgentMemoryBranchSnapshot, AgentMemoryContext, AgentMemoryControllerMode, type AgentMemoryDimensionComparison, type AgentMemoryExperimentCandidate, type AgentMemoryExperimentRankingRow, type AgentMemoryExperimentRunLease, type AgentMemoryGovernor, AgentMemoryHit, AgentMemoryHitSchema, type AgentMemoryImprovementRunLease, type AgentMemoryImprovementSeed, type AgentMemoryJournalEntry, AgentMemoryKindSchema, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, type AgentMemoryPromotionDecision, AgentMemoryRunLease, AgentMemoryScope, AgentMemoryScopeSchema, AgentMemorySearchOptions, type AgentMemorySequence, type AgentMemorySequenceArtifact, type AgentMemorySequenceProbe, type AgentMemorySequenceProbeResult, type AgentMemorySequenceScenario, type AgentMemorySequenceStep, type AgentMemorySharingPolicy, type AgentMemoryVisibility, AgentMemoryWriteInput, AgentMemoryWriteInputSchema, AgentMemoryWriteResult, type BuildAgentMemorySequencesFromBenchmarkCasesOptions, type CreateAgentMemoryBranchOptions, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, type ForkAgentMemoryBranchSnapshotOptions, type GraphitiMcpClientLike, type GraphitiMemoryAdapterOptions, type GraphitiToolNames, type Mem0ClientLike, type Mem0ClientMode, type Mem0MemoryAdapterOptions, type Neo4jAgentMemoryAdapterOptions, type RunAgentMemoryExperimentOptions, type RunAgentMemoryExperimentResult, type RunAgentMemoryImprovementOptions, type RunAgentMemoryImprovementResult, agentMemorySequenceJudge, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, createAgentMemoryBranch, createGraphitiMemoryAdapter, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, forkAgentMemoryBranchSnapshot, graphitiMemoryAdapterIdentity, mem0MemoryAdapterIdentity, memoryHitToSourceRecord, memoryRecoveryDelayMs, memoryWriteResultToSourceRecord, renderMemoryContext, resolveMemoryCleanupTimeoutMs, runAgentMemoryExperiment, runAgentMemoryImprovement, runBoundedMemoryLifecycle, sleepForMemoryRecovery };

package/dist/memory/index.js

@@ -3,38 +3,79 @@ import {
   AgentMemoryKindSchema,
   AgentMemoryScopeSchema,
   AgentMemoryWriteInputSchema,
+  agentMemorySequenceJudge,
   applyRetrievalHoldout,
   applySessionStickyRetrievalHoldout,
+  buildAgentMemorySequenceScenarios,
+  buildAgentMemorySequencesFromBenchmarkCases,
+  createAgentMemoryBranch,
+  createGraphitiMemoryAdapter,
+  createMem0MemoryAdapter,
   createNeo4jAgentMemoryAdapter,
   defaultGetMemoryContext,
   deterministicRng,
   emitRetrievalHoldoutBypass,
+  forkAgentMemoryBranchSnapshot,
+  graphitiMemoryAdapterIdentity,
+  mem0MemoryAdapterIdentity,
   renderMemoryContext,
   resetRetrievalHoldoutRegistry,
   retrievalHoldoutConfigHash,
+  runAgentMemoryExperiment,
+  runAgentMemoryImprovement,
   toOffPolicyTrajectory
-} from "../chunk-VN2OGUUP.js";
+} from "../chunk-UWOTQNBI.js";
 import {
+  AgentMemoryLifecycleTimeoutError,
+  AgentMemoryLifecycleUnsafeError,
+  DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS,
+  acquireAgentMemoryRunLease,
+  createMemoryExecutionPool,
   memoryHitToSourceRecord,
-  memoryWriteResultToSourceRecord
-} from "../chunk-XVU5FFQA.js";
+  memoryRecoveryDelayMs,
+  memoryWriteResultToSourceRecord,
+  resolveMemoryCleanupTimeoutMs,
+  runBoundedMemoryLifecycle,
+  sleepForMemoryRecovery
+} from "../chunk-DW6APRTX.js";
+import "../chunk-DQ3PDMDP.js";
 import "../chunk-YMKHCTS2.js";
 export {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
+  AgentMemoryLifecycleTimeoutError,
+  AgentMemoryLifecycleUnsafeError,
   AgentMemoryScopeSchema,
   AgentMemoryWriteInputSchema,
+  DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS,
+  acquireAgentMemoryRunLease,
+  agentMemorySequenceJudge,
   applyRetrievalHoldout,
   applySessionStickyRetrievalHoldout,
+  buildAgentMemorySequenceScenarios,
+  buildAgentMemorySequencesFromBenchmarkCases,
+  createAgentMemoryBranch,
+  createGraphitiMemoryAdapter,
+  createMem0MemoryAdapter,
+  createMemoryExecutionPool,
   createNeo4jAgentMemoryAdapter,
   defaultGetMemoryContext,
   deterministicRng,
   emitRetrievalHoldoutBypass,
+  forkAgentMemoryBranchSnapshot,
+  graphitiMemoryAdapterIdentity,
+  mem0MemoryAdapterIdentity,
   memoryHitToSourceRecord,
+  memoryRecoveryDelayMs,
   memoryWriteResultToSourceRecord,
   renderMemoryContext,
   resetRetrievalHoldoutRegistry,
+  resolveMemoryCleanupTimeoutMs,
   retrievalHoldoutConfigHash,
+  runAgentMemoryExperiment,
+  runAgentMemoryImprovement,
+  runBoundedMemoryLifecycle,
+  sleepForMemoryRecovery,
   toOffPolicyTrajectory
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "3.2.1",
+  "version": "4.0.0",
   "description": "Source-grounded, eval-gated knowledge growth primitives for agents.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -52,6 +52,7 @@
     "dist",
     "docs",
     "AGENTS.md",
+    "CHANGELOG.md",
     "README.md"
   ],
   "publishConfig": {
@@ -69,19 +70,20 @@
     "verify:package": "node scripts/verify-package.mjs"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": "^0.122.7",
+    "@tangle-network/agent-eval": "^0.122.8",
     "@tangle-network/agent-interface": "^0.31.0",
     "proper-lockfile": "4.1.2",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
+    "@biomejs/biome": "^2.5.4",
     "@neo4j-labs/agent-memory": "0.4.0",
     "@tangle-network/sandbox": "^0.9.7",
     "@types/node": "^25.6.0",
     "@types/proper-lockfile": "4.1.4",
+    "mem0ai": "3.1.0",
     "tsup": "^8.0.0",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.1",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   },