Task Agents

constructor

constructor(storage: IAgentStorage, strategy: CheckpointStrategy = DEFAULT_CHECKPOINT_STRATEGY)

Parameters:

• storage: IAgentStorage
• strategy: CheckpointStrategy (optional) (default: DEFAULT_CHECKPOINT_STRATEGY)

setCurrentState()

Set the current agent state (for interval checkpointing)

setCurrentState(state: AgentState): void

Parameters:

• state: AgentState

Returns: void

onToolCall()

Record a tool call (may trigger checkpoint)

async onToolCall(state: AgentState): Promise<void>

Parameters:

• state: AgentState

Returns: Promise<void>

onLLMCall()

Record an LLM call (may trigger checkpoint)

async onLLMCall(state: AgentState): Promise<void>

Parameters:

• state: AgentState

Returns: Promise<void>

checkpoint()

Force a checkpoint

async checkpoint(state: AgentState, reason: string): Promise<void>

Parameters:

• state: AgentState
• reason: string

Returns: Promise<void>

flush()

Wait for all pending checkpoints to complete

async flush(): Promise<void>

Returns: Promise<void>

cleanup()

Cleanup resources

async cleanup(): Promise<void>

Returns: Promise<void>

constructor

constructor(tools: ToolFunction[] = [])

Parameters:

• tools: ToolFunction<any, any>[] (optional) (default: [])

startWaiting()

Start handling a task's external dependency

async startWaiting(task: Task): Promise<void>

Parameters:

• task: Task

Returns: Promise<void>

stopWaiting()

Stop waiting on a task's external dependency

stopWaiting(task: Task): void

Parameters:

• task: Task

Returns: void

triggerWebhook()

Trigger a webhook

async triggerWebhook(webhookId: string, data: unknown): Promise<void>

Parameters:

• webhookId: string
• data: unknown

Returns: Promise<void>

completeManual()

Complete a manual task

async completeManual(taskId: string, data: unknown): Promise<void>

Parameters:

• taskId: string
• data: unknown

Returns: Promise<void>

cleanup()

Cleanup all active dependencies

cleanup(): void

Returns: void

updateTools()

Update available tools

updateTools(tools: ToolFunction[]): void

Parameters:

• tools: ToolFunction<any, any>[]

Returns: void

constructor

constructor(config: InContextMemoryConfig = {})

Parameters:

• config: InContextMemoryConfig (optional) (default: {})

getInstructions()

getInstructions(): string

Returns: string

getContent()

async getContent(): Promise<string | null>

Returns: Promise<string | null>

getContents()

getContents(): Map<string, InContextEntry>

Returns: Map<string, InContextEntry>

getTokenSize()

getTokenSize(): number

Returns: number

getInstructionsTokenSize()

getInstructionsTokenSize(): number

Returns: number

isCompactable()

isCompactable(): boolean

Returns: boolean

compact()

async compact(targetTokensToFree: number): Promise<number>

Parameters:

• targetTokensToFree: number

Returns: Promise<number>

getTools()

getTools(): ToolFunction[]

Returns: ToolFunction<any, any>[]

destroy()

destroy(): void

Returns: void

getState()

getState(): SerializedInContextMemoryState

Returns: SerializedInContextMemoryState

restoreState()

restoreState(state: unknown): void

Parameters:

• state: unknown

Returns: void

set()

Store or update a key-value pair

set(key: string, description: string, value: unknown, priority?: InContextPriority, showInUI?: boolean): void

Parameters:

• key: string
• description: string
• value: unknown
• priority: InContextPriority | undefined (optional)
• showInUI: boolean | undefined (optional)

Returns: void

get()

Get a value by key

get(key: string): unknown | undefined

Parameters:

• key: string

Returns: unknown

has()

Check if a key exists

has(key: string): boolean

Parameters:

• key: string

Returns: boolean

delete()

Delete an entry

delete(key: string): boolean

Parameters:

• key: string

Returns: boolean

list()

List all entries with metadata

list(): Array<{ key: string; description: string; priority: InContextPriority; updatedAt: number; showInUI: boolean }>

Returns: { key: string; description: string; priority: InContextPriority; updatedAt: number; showInUI: boolean; }[]

clear()

Clear all entries

clear(): void

Returns: void

getStoreSchema()

getStoreSchema(): StoreEntrySchema

Returns: StoreEntrySchema

storeGet()

async storeGet(key?: string, _context?: ToolContext): Promise<StoreGetResult>

Parameters:

• key: string | undefined (optional)
• _context: ToolContext | undefined (optional)

Returns: Promise<StoreGetResult>

storeSet()

async storeSet(key: string, data: Record<string, unknown>, _context?: ToolContext): Promise<StoreSetResult>

Parameters:

• key: string
• data: Record<string, unknown>
• _context: ToolContext | undefined (optional)

Returns: Promise<StoreSetResult>

storeDelete()

async storeDelete(key: string, _context?: ToolContext): Promise<StoreDeleteResult>

Parameters:

• key: string
• _context: ToolContext | undefined (optional)

Returns: Promise<StoreDeleteResult>

storeList()

async storeList(_filter?: Record<string, unknown>, _context?: ToolContext): Promise<StoreListResult>

Parameters:

• _filter: Record<string, unknown> | undefined (optional)
• _context: ToolContext | undefined (optional)

Returns: Promise<StoreListResult>

constructor

constructor(opts: InMemoryAdapterOptions = {})

Parameters:

• opts: InMemoryAdapterOptions (optional) (default: {})

createEntity()

async createEntity(input: NewEntity): Promise<IEntity>

Parameters:

• input: NewEntity

Returns: Promise<IEntity>

createEntities()

async createEntities(inputs: NewEntity[]): Promise<IEntity[]>

Parameters:

• inputs: NewEntity[]

Returns: Promise<IEntity[]>

updateEntity()

async updateEntity(entity: IEntity): Promise<void>

Parameters:

• entity: IEntity

Returns: Promise<void>

getEntity()

async getEntity(id: EntityId, scope: ScopeFilter): Promise<IEntity | null>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<IEntity | null>

getEntities()

async getEntities(ids: EntityId[], scope: ScopeFilter): Promise<Array<IEntity | null>>

Parameters:

• ids: string[]
• scope: ScopeFilter

Returns: Promise<(IEntity | null)[]>

findEntitiesByIdentifier()

async findEntitiesByIdentifier(
    kind: string,
    value: string,
    scope: ScopeFilter,
  ): Promise<IEntity[]>

Parameters:

• kind: string
• value: string
• scope: ScopeFilter

Returns: Promise<IEntity[]>

atomicCreateOrFindByNormalizedName()

Atomic find-or-create by (type, normalizedDisplayName, scope). See the interface contract. JS event-loop atomicity: the body has a single await (the createEntity call); the find-by-normalized phase runs synchronously over the in-memory map, so two concurrent invocations cannot both pass the find without one observing the other's insert.

async atomicCreateOrFindByNormalizedName(
    input: NewEntity,
    scope: ScopeFilter,
  ): Promise<{ entity: IEntity; created: boolean }>

Parameters:

• input: NewEntity
• scope: ScopeFilter

Returns: Promise<{ entity: IEntity; created: boolean; }>

findEntitiesByNormalizedName()

async findEntitiesByNormalizedName(
    type: string | undefined,
    normalized: string,
    scope: ScopeFilter,
    opts?: { matchAliases?: boolean; limit?: number },
  ): Promise<IEntity[]>

Parameters:

• type: string | undefined
• normalized: string
• scope: ScopeFilter
• opts: { matchAliases?: boolean | undefined; limit?: number | undefined; } | undefined (optional)

Returns: Promise<IEntity[]>

searchEntities()

async searchEntities(
    query: string,
    opts: EntitySearchOptions,
    scope: ScopeFilter,
  ): Promise<Page<IEntity>>

Parameters:

• query: string
• opts: EntitySearchOptions
• scope: ScopeFilter

Returns: Promise<Page<IEntity>>

listEntities()

async listEntities(
    filter: EntityListFilter,
    opts: ListOptions,
    scope: ScopeFilter,
  ): Promise<Page<IEntity>>

Parameters:

• filter: EntityListFilter
• opts: ListOptions
• scope: ScopeFilter

Returns: Promise<Page<IEntity>>

archiveEntity()

async archiveEntity(id: EntityId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

deleteEntity()

async deleteEntity(id: EntityId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

createFact()

async createFact(input: NewFact): Promise<IFact>

Parameters:

• input: NewFact

Returns: Promise<IFact>

createFacts()

async createFacts(inputs: NewFact[]): Promise<IFact[]>

Parameters:

• inputs: NewFact[]

Returns: Promise<IFact[]>

getFact()

async getFact(id: FactId, scope: ScopeFilter): Promise<IFact | null>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<IFact | null>

findFacts()

async findFacts(
    filter: FactFilter,
    opts: FactQueryOptions,
    scope: ScopeFilter,
  ): Promise<Page<IFact>>

Parameters:

• filter: FactFilter
• opts: FactQueryOptions
• scope: ScopeFilter

Returns: Promise<Page<IFact>>

updateFact()

async updateFact(id: FactId, patch: Partial<IFact>, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• patch: Partial<IFact>
• scope: ScopeFilter

Returns: Promise<void>

rewriteEntityPrincipal()

Rewrite entity:<from> → entity:<to> access grants across stored entities + facts. In-place mutation of the backing maps (reads return clones, so callers never see partial state). Mirrors MongoMemoryAdapter.rewriteEntityPrincipal — scoped to the caller's tenant (scope.groupId) for parity + defense-in-depth.

async rewriteEntityPrincipal(
    fromEntityId: EntityId,
    toEntityId: EntityId,
    scope: ScopeFilter,
  ): Promise<void>

Parameters:

• fromEntityId: string
• toEntityId: string
• scope: ScopeFilter

Returns: Promise<void>

countFacts()

async countFacts(filter: FactFilter, scope: ScopeFilter): Promise<number>

Parameters:

• filter: FactFilter
• scope: ScopeFilter

Returns: Promise<number>

traverse()

async traverse(
    startId: EntityId,
    opts: TraversalOptions,
    scope: ScopeFilter,
  ): Promise<Neighborhood>

Parameters:

• startId: string
• opts: TraversalOptions
• scope: ScopeFilter

Returns: Promise<Neighborhood>

semanticSearch()

async semanticSearch(
    queryVector: number[],
    filter: FactFilter,
    opts: SemanticSearchOptions,
    scope: ScopeFilter,
  ): Promise<Array<{ fact: IFact; score: number }>>

Parameters:

• queryVector: number[]
• filter: FactFilter
• opts: SemanticSearchOptions
• scope: ScopeFilter

Returns: Promise<{ fact: IFact; score: number; }[]>

semanticSearchEntities()

async semanticSearchEntities(
    queryVector: number[],
    filter: EntitySemanticSearchFilter,
    opts: SemanticSearchOptions & { minScore?: number; embeddingField?: EntityEmbeddingField },
    scope: ScopeFilter,
  ): Promise<Array<{ entity: IEntity; score: number }>>

Parameters:

• queryVector: number[]
• filter: EntitySemanticSearchFilter
• opts: SemanticSearchOptions & { minScore?: number | undefined; embeddingField?: EntityEmbeddingField | undefined; }
• scope: ScopeFilter

Returns: Promise<{ entity: IEntity; score: number; }[]>

destroy()

destroy(): void

Returns: void

save()

async save(state: AgentState): Promise<void>

Parameters:

• state: AgentState

Returns: Promise<void>

load()

async load(agentId: string): Promise<AgentState | undefined>

Parameters:

• agentId: string

Returns: Promise<AgentState | undefined>

delete()

async delete(agentId: string): Promise<void>

Parameters:

• agentId: string

Returns: Promise<void>

list()

async list(filter?: { status?: AgentStatus[] }): Promise<AgentState[]>

Parameters:

• filter: { status?: AgentStatus[] | undefined; } | undefined (optional)

Returns: Promise<AgentState[]>

patch()

async patch(agentId: string, updates: Partial<AgentState>): Promise<void>

Parameters:

• agentId: string
• updates: Partial<AgentState>

Returns: Promise<void>

inventory()

protected async inventory(): Promise<Array<{ id: string; bytes: number }>>

Returns: Promise<{ id: string; bytes: number; }[]>

writeBlob()

protected async writeBlob(id: string, bytes: Buffer): Promise<void>

Parameters:

• id: string
• bytes: Buffer<ArrayBufferLike>

Returns: Promise<void>

readBlob()

protected async readBlob(id: string): Promise<Buffer | null>

Parameters:

• id: string

Returns: Promise<Buffer<ArrayBufferLike> | null>

removeBlob()

protected async removeBlob(id: string): Promise<boolean>

Parameters:

• id: string

Returns: Promise<boolean>

addMessage()

async addMessage(message: HistoryMessage): Promise<void>

Parameters:

• message: HistoryMessage

Returns: Promise<void>

getMessages()

async getMessages(): Promise<HistoryMessage[]>

Returns: Promise<HistoryMessage[]>

getRecentMessages()

async getRecentMessages(count: number): Promise<HistoryMessage[]>

Parameters:

• count: number

Returns: Promise<HistoryMessage[]>

removeMessage()

async removeMessage(id: string): Promise<void>

Parameters:

• id: string

Returns: Promise<void>

removeOlderThan()

async removeOlderThan(timestamp: number): Promise<number>

Parameters:

• timestamp: number

Returns: Promise<number>

clear()

async clear(): Promise<void>

Returns: Promise<void>

getCount()

async getCount(): Promise<number>

Returns: Promise<number>

getState()

async getState(): Promise<SerializedHistoryState>

Returns: Promise<SerializedHistoryState>

restoreState()

async restoreState(state: SerializedHistoryState): Promise<void>

Parameters:

• state: SerializedHistoryState

Returns: Promise<void>

increment()

increment(metric: string, value: number = 1, tags?: MetricTags): void

Parameters:

• metric: string
• value: number (optional) (default: 1)
• tags: MetricTags | undefined (optional)

Returns: void

gauge()

gauge(metric: string, value: number, tags?: MetricTags): void

Parameters:

• metric: string
• value: number
• tags: MetricTags | undefined (optional)

Returns: void

timing()

timing(metric: string, duration: number, tags?: MetricTags): void

Parameters:

• metric: string
• duration: number
• tags: MetricTags | undefined (optional)

Returns: void

histogram()

histogram(metric: string, value: number, tags?: MetricTags): void

Parameters:

• metric: string
• value: number
• tags: MetricTags | undefined (optional)

Returns: void

getMetrics()

Get all metrics (for testing)

getMetrics(): {
    counters: Map<string, number>;
    gauges: Map<string, number>;
    timings: Map<string, number[]>;
    histograms: Map<string, number[]>;
  }

Returns: { counters: Map<string, number>; gauges: Map<string, number>; timings: Map<string, number[]>; histograms: Map<string, number[]>; }

clear()

Clear all metrics

clear(): void

Returns: void

getTimingStats()

Get summary statistics for timings

getTimingStats(metric: string, tags?: MetricTags): {
    count: number;
    min: number;
    max: number;
    mean: number;
    p50: number;
    p95: number;
    p99: number;
  } | null

Parameters:

• metric: string
• tags: MetricTags | undefined (optional)

Returns: { count: number; min: number; max: number; mean: number; p50: number; p95: number; p99: number; } | null

savePlan()

async savePlan(plan: Plan): Promise<void>

Parameters:

• plan: Plan

Returns: Promise<void>

getPlan()

async getPlan(planId: string): Promise<Plan | undefined>

Parameters:

• planId: string

Returns: Promise<Plan | undefined>

updateTask()

async updateTask(planId: string, task: Task): Promise<void>

Parameters:

• planId: string
• task: Task

Returns: Promise<void>

addTask()

async addTask(planId: string, task: Task): Promise<void>

Parameters:

• planId: string
• task: Task

Returns: Promise<void>

deletePlan()

async deletePlan(planId: string): Promise<void>

Parameters:

• planId: string

Returns: Promise<void>

listPlans()

async listPlans(filter?: { status?: PlanStatus[] }): Promise<Plan[]>

Parameters:

• filter: { status?: PlanStatus[] | undefined; } | undefined (optional)

Returns: Promise<Plan[]>

findByWebhookId()

async findByWebhookId(webhookId: string): Promise<{ plan: Plan; task: Task } | undefined>

Parameters:

• webhookId: string

Returns: Promise<{ plan: Plan; task: Task; } | undefined>

get()

async get(key: string): Promise<MemoryEntry | undefined>

Parameters:

• key: string

Returns: Promise<MemoryEntry | undefined>

set()

async set(key: string, entry: MemoryEntry): Promise<void>

Parameters:

• key: string
• entry: MemoryEntry

Returns: Promise<void>

delete()

async delete(key: string): Promise<void>

Parameters:

• key: string

Returns: Promise<void>

has()

async has(key: string): Promise<boolean>

Parameters:

• key: string

Returns: Promise<boolean>

getAll()

async getAll(): Promise<MemoryEntry[]>

Returns: Promise<MemoryEntry[]>

getByScope()

async getByScope(scope: MemoryScope): Promise<MemoryEntry[]>

Parameters:

• scope: MemoryScope

Returns: Promise<MemoryEntry[]>

clearScope()

async clearScope(scope: MemoryScope): Promise<void>

Parameters:

• scope: MemoryScope

Returns: Promise<void>

clear()

async clear(): Promise<void>

Returns: Promise<void>

getTotalSize()

async getTotalSize(): Promise<number>

Returns: Promise<number>

constructor

constructor(taskId: EntityId, from: string | undefined, to: string)

Parameters:

• taskId: string
• from: string | undefined
• to: string

save()

async save(name: string, stored: StoredConnectorConfig): Promise<void>

Parameters:

• name: string
• stored: StoredConnectorConfig

Returns: Promise<void>

get()

async get(name: string): Promise<StoredConnectorConfig | null>

Parameters:

• name: string

Returns: Promise<StoredConnectorConfig | null>

delete()

async delete(name: string): Promise<boolean>

Parameters:

• name: string

Returns: Promise<boolean>

has()

async has(name: string): Promise<boolean>

Parameters:

• name: string

Returns: Promise<boolean>

list()

async list(): Promise<string[]>

Returns: Promise<string[]>

listAll()

async listAll(): Promise<StoredConnectorConfig[]>

Returns: Promise<StoredConnectorConfig[]>

clear()

Clear all stored configs (useful for testing)

clear(): void

Returns: void

size()

Get the number of stored configs

size(): number

Returns: number

constructor

constructor(private estimator: ITokenEstimator)

Parameters:

• estimator: ITokenEstimator

canCompact()

canCompact(component: IContextComponent): boolean

Parameters:

• component: IContextComponent

Returns: boolean

compact()

async compact(component: IContextComponent, targetTokens: number): Promise<IContextComponent>

Parameters:

• component: IContextComponent
• targetTokens: number

Returns: Promise<IContextComponent>

estimateSavings()

estimateSavings(component: IContextComponent): number

Parameters:

• component: IContextComponent

Returns: number

constructor

constructor(config: MemoryPluginConfig)

Parameters:

• config: MemoryPluginConfig

getInstructions()

getInstructions(): string

Returns: string

prepare()

Force lazy bootstrap to complete.

The plugin resolves userEntityId / agentEntityId / groupEntityId lazily on first getContent(). That's fine when the agent starts with an LLM turn — getContent() runs as part of building the first prompt.

It's NOT fine when the agent starts with deterministic pre-steps (e.g. routines: preSteps execute before the first LLM turn). A pre-step invoking memory_recall({ subject: 'me' }) calls getOwnSubjectIds().userEntityId — undefined → "no user scope" error.

prepare() is the contract for "make sure your lazy state is ready before any tool you contribute is invoked". The routine runner calls it once after building the agent and before pre-steps fire. Idempotent.

async prepare(): Promise<void>

Returns: Promise<void>

getContent()

async getContent(): Promise<string | null>

Returns: Promise<string | null>

getContents()

getContents(): unknown

Returns: unknown

getTokenSize()

getTokenSize(): number

Returns: number

getInstructionsTokenSize()

getInstructionsTokenSize(): number

Returns: number

isCompactable()

isCompactable(): boolean

Returns: boolean

compact()

async compact(_targetTokensToFree: number): Promise<number>

Parameters:

• _targetTokensToFree: number

Returns: Promise<number>

getTools()

getTools(): ToolFunction[]

Returns: ToolFunction<any, any>[]

destroy()

destroy(): void

Returns: void

getState()

getState(): unknown

Returns: unknown

restoreState()

restoreState(state: unknown): void

Parameters:

• state: unknown

Returns: void

getBootstrappedIds()

Entity IDs created (or resolved) during bootstrap. Undefined before bootstrap. Always returns the variant agent entity id (keyed by system_agent_id), even when a persona is configured — for "what was actually bootstrapped" use this; for "what 'me' / 'this_agent' resolve to in tools" use getOwnSubjectIds().

getBootstrappedIds(): {
    userEntityId?: string;
    agentEntityId?: string;
    groupEntityId?: string;
  }

Returns: { userEntityId?: string | undefined; agentEntityId?: string | undefined; groupEntityId?: string | undefined; }

getOwnSubjectIds()

Subject ids for LLM-facing 'me' / 'this_agent' token resolution, used by both this plugin's read tools and (via AgentContextNextGen's wiring) MemoryWritePluginNextGen's write tools. agentEntityId here is persona-aware: if a personaEntityId was configured, this returns the persona, so memory_set_agent_rule writes and rule-block reads share one subject across every variant carrying the same persona.

Use getBootstrappedIds() instead when you need the variant agent entity id (analytics, factContextIds, snapshots).

getOwnSubjectIds(): { userEntityId?: string; agentEntityId?: string }

Returns: { userEntityId?: string | undefined; agentEntityId?: string | undefined; }

storeToken()

async storeToken(key: string, token: StoredToken): Promise<void>

Parameters:

• key: string
• token: StoredToken

Returns: Promise<void>

getToken()

async getToken(key: string): Promise<StoredToken | null>

Parameters:

• key: string

Returns: Promise<StoredToken | null>

deleteToken()

async deleteToken(key: string): Promise<void>

Parameters:

• key: string

Returns: Promise<void>

hasToken()

async hasToken(key: string): Promise<boolean>

Parameters:

• key: string

Returns: Promise<boolean>

clearAll()

Clear all tokens (useful for testing)

clearAll(): void

Returns: void

size()

Get number of stored tokens

size(): number

Returns: number

listKeys()

List all storage keys (for account enumeration)

async listKeys(): Promise<string[]>

Returns: Promise<string[]>

constructor

constructor(config: MemorySystemConfig)

Parameters:

• config: MemorySystemConfig

upsertEntity()

async upsertEntity(
    input: Partial<IEntity> & {
      identifiers: Identifier[];
      displayName: string;
      type: string;
      /**
       * How `input.metadata` is folded into an existing entity on resolve.
       * Default: undefined → metadata is ignored on resolve (current behavior,
       * backward-compatible).
       *  - `'fillMissing'`: only set keys absent from stored metadata; existing
       *    values are never overwritten. Safe for LLM-driven re-extraction.
       *  - `'overwrite'`: shallow-merge — incoming keys win. Use when the
       *    caller is authoritative (calendar API for events, sync from system
       *    of record).
       *
       * On create (no match) all keys are set verbatim regardless of this option.
       */
      metadataMerge?: 'fillMissing' | 'overwrite';
      /**
       * Optional whitelist applied when `metadataMerge` is set: only these
       * top-level keys are touched. Other incoming keys are ignored. Lets the
       * caller pin the merge to a known set (e.g. `['startTime','endTime',
       * 'status']` for events) without leaking unrelated extracted fields.
       *
       * Has no effect when `metadataMerge` is unset.
       */
      metadataMergeKeys?: string[];
    },
    scope: ScopeFilter,
    options?: {
      /**
       * Allow a resolve-and-update to mutate an existing entity owned by a
       * different user WITHIN THE SAME GROUP/TENANT. Default `false`.
       *
       * When `true`: if the best-match entity shares `scope.groupId`, the
       * per-owner `assertCanAccess(write)` check is skipped — so trusted
       * server-side consolidation (e.g. the signal pipeline converging a
       * group-visible Person/Organization that another user in the same group
       * created) can enrich it without re-owning it first. Mirrors the
       * `allowCrossOwner` option on `mergeEntities`.
       *
       * Tenancy invariant is preserved: a cross-tenant best-match (different
       * `groupId`) still goes through `assertCanAccess`, which denies it — the
       * flag never enables cross-tenant writes. The host is responsible for
       * gating which callers may pass it (server pipeline code only — never an
       * agent/tool surface).
       */
      allowCrossOwner?: boolean;
    },
  ): Promise<UpsertEntityResult>

Parameters:

• input: Partial<IEntity> & { identifiers: Identifier[]; displayName: string; type: string; metadataMerge?: "fillMissing" | "overwrite" | undefined; metadataMergeKeys?: string[] | undefined; }
• scope: ScopeFilter
• options: { allowCrossOwner?: boolean | undefined; } | undefined (optional)

Returns: Promise<UpsertEntityResult>

getEntity()

getEntity(id: EntityId, scope: ScopeFilter): Promise<IEntity | null>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<IEntity | null>

getEntities()

Batch fetch. Returned array aligns with ids positionally; missing ids / scope-filtered-out entries become null. Intended for call sites that need to resolve many EntityId references cheaply (e.g. rendering fact.objectId as a displayName in the system message).

getEntities(ids: EntityId[], scope: ScopeFilter): Promise<Array<IEntity | null>>

Parameters:

• ids: string[]
• scope: ScopeFilter

Returns: Promise<(IEntity | null)[]>

findEntitiesByIdentifier()

Return every entity visible at scope whose identifier list contains (kind, value). Thin pass-through to the store — exposed so callers that need to detect bootstrap duplicates (e.g. MemoryPluginNextGen) don't have to reach into store directly.

findEntitiesByIdentifier(
    kind: string,
    value: string,
    scope: ScopeFilter,
  ): Promise<IEntity[]>

Parameters:

• kind: string
• value: string
• scope: ScopeFilter

Returns: Promise<IEntity[]>

searchEntities()

searchEntities(
    query: string,
    opts: { types?: string[]; limit?: number; cursor?: string },
    scope: ScopeFilter,
  )

Parameters:

• query: string
• opts: { types?: string[] | undefined; limit?: number | undefined; cursor?: string | undefined; }
• scope: ScopeFilter

Returns: Promise<Page<IEntity>>

listEntities()

List entities by type + optional metadata equality filter. Thin pass-through to the store's listEntities — exposed on MemorySystem so tool layers don't need to reach into the store directly.

Read-side date coercion: ISO-8601 strings inside metadataFilter are coerced to Date here (once, at the public boundary) so adapters always see Date-typed values in range/equality clauses. Without it, callers (LLM tools especially) writing the natural shape — { startTime: { $gte: "2026-05-14T00:00:00Z" } } — would silently get zero matches against metadata.startTime (BSON Date), because Mongo and the InMemory comparator treat String and Date as distinct types in range comparisons. Adapters do not re-coerce — DRY, single point of responsibility across all backends.

listEntities(
    filter: import('./types.js').EntityListFilter,
    opts: import('./types.js').ListOptions,
    scope: ScopeFilter,
  )

Parameters:

• filter: EntityListFilter
• opts: ListOptions
• scope: ScopeFilter

Returns: Promise<Page<IEntity>>

findFacts()

Enumerate facts directly. Pass-through to the store's findFacts so tool layers can list raw facts without reaching into the store. For ranked/ retrieval-oriented queries prefer getContext or semanticSearch.

findFacts(
    filter: FactFilter,
    opts: import('./types.js').FactQueryOptions,
    scope: ScopeFilter,
  )

Parameters:

• filter: FactFilter
• opts: FactQueryOptions
• scope: ScopeFilter

Returns: Promise<Page<IFact>>

getFact()

Fetch a single fact by id. Returns null when the fact does not exist or is not visible to the caller's scope.

getFact(id: FactId, scope: ScopeFilter)

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<IFact | null>

resolveEntity()

Resolve a surface form ("Microsoft", "Q3 Planning", "John") to ranked candidate entities. Matching tiers: strong identifier → exact displayName → exact alias → fuzzy → semantic (identityEmbedding). Returns candidates sorted by confidence; empty if nothing meets opts.threshold (default 0.5).

resolveEntity(
    query: ResolveEntityQuery,
    scope: ScopeFilter,
    opts?: ResolveEntityOptions,
  ): Promise<EntityCandidate[]>

Parameters:

• query: ResolveEntityQuery
• scope: ScopeFilter
• opts: ResolveEntityOptions | undefined (optional)

Returns: Promise<EntityCandidate[]>

upsertEntityBySurface()

Upsert-or-resolve by surface form. If the top candidate clears autoResolveThreshold (default conservative 0.90), returns that entity with the new surface + identifiers merged in (alias accumulation). Otherwise creates a new entity and reports near-matches as mergeCandidates for deferred human review.

async upsertEntityBySurface(
    input: UpsertBySurfaceInput,
    scope: ScopeFilter,
    opts?: UpsertBySurfaceOptions,
  ): Promise<UpsertBySurfaceResult>

Parameters:

• input: UpsertBySurfaceInput
• scope: ScopeFilter
• opts: UpsertBySurfaceOptions | undefined (optional)

Returns: Promise<UpsertBySurfaceResult>

mergeEntities()

Merge two entities — copy loser's identifiers + aliases onto winner, rewrite every fact whose subject or object is the loser to point at the winner, and archive the loser.

Scope-window limitation (defence-in-depth, by design): the rewrite step only touches facts visible to the caller's scope. Facts scoped more narrowly than the caller (e.g. other users' private facts on either entity) are left untouched and will continue to reference the archived loser. This prevents a user from rewriting data they cannot see, but means a "complete" merge requires a caller with broad-enough scope to see every referencing fact.

async mergeEntities(
    winnerId: EntityId,
    loserId: EntityId,
    scope: ScopeFilter,
    options?: {
      /**
       * Allow merging entities owned by different users within the same
       * group/tenant. Default `false`.
       *
       * When `true`: the per-entity `assertCanAccess(write)` check is
       * skipped (both winner and loser may be owned by users other than
       * `scope.userId`), AND the same bypass is applied while rewriting
       * fact references so the graph stays coherent post-merge.
       *
       * Tenancy invariant is preserved: the call refuses if
       * `winner.groupId !== loser.groupId`. The host is responsible for
       * gating which callers may pass the flag (typically a group/super
       * admin running a legitimate consolidation pass).
       *
       * The owner of the surviving winner is unchanged either way — only
       * the loser is archived, so its ownerId becomes irrelevant after.
       */
      allowCrossOwner?: boolean;
    },
  ): Promise<IEntity>

Parameters:

• winnerId: string
• loserId: string
• scope: ScopeFilter
• options: { allowCrossOwner?: boolean | undefined; } | undefined (optional)

Returns: Promise<IEntity>

setAccess()

Replace the explicit acl on an entity or fact and re-materialize its readPrincipals/writePrincipals in place. The sanctioned exception to fact-immutability for ACCESS changes (same category as the merge rewrite). Caller must have write on the record.

Backs host grant/revoke surfaces. Returns the updated record.

async setAccess(
    kind: 'entity' | 'fact',
    id: string,
    acl: ACLEntry[],
    scope: ScopeFilter,
  ): Promise<IEntity | IFact>

Parameters:

• kind: "entity" | "fact"
• id: string
• acl: ACLEntry[]
• scope: ScopeFilter

Returns: Promise<IEntity | IFact>

archiveEntity()

Archive an entity (soft delete). Cascades to facts where the entity is subjectId or objectId — those get archived too.

Tombstone semantics for contextIds (NO cascade): facts whose contextIds array references this entity, and other entities whose top-level contextIds references this one, are LEFT UNCHANGED. The reference becomes a dangling pointer — readers resolving the id see null (archived), the referencing record stays live. Symmetric across fact-contextIds (long-standing behavior) and entity-contextIds. Rationale: contextIds is a soft multi-anchor binding, not a hard structural edge; force-removing it on archive would destructively mutate consumer records the caller may not even own. Hosts that want a stronger semantic should run a sweep after archive.

async archiveEntity(id: EntityId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

deleteEntity()

Delete an entity. Soft (default): same cascade rules as archiveEntity. Hard (opts.hard: true): the entity row is removed; facts where it's subject/object are archived. Same tombstone rule for contextIds: contextIds references — fact-level and entity-level — are left as dangling pointers. See archiveEntity JSDoc for rationale.

async deleteEntity(
    id: EntityId,
    scope: ScopeFilter,
    opts: { hard?: boolean } = {},
  ): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter
• opts: { hard?: boolean | undefined; } (optional) (default: {})

Returns: Promise<void>

canonicalizePredicate()

Normalize a predicate string to its canonical form. When no registry is configured, returns the input unchanged.

Used by ExtractionResolver and available to external callers that want to pre-normalize predicates before querying.

canonicalizePredicate(input: string): string

Parameters:

• input: string

Returns: string

hasPredicateRegistry()

True when a predicate registry is configured on this MemorySystem.

hasPredicateRegistry(): boolean

Returns: boolean

getPredicateRegistry()

Return the configured predicate registry, or undefined when none is set. Exposed so prompt-rendering layers (e.g. MemoryWritePluginNextGen) can generate LLM-facing predicate vocabulary from the same source of truth — avoids hand-maintained predicate lists drifting out of sync with what the storage layer actually accepts and ranks.

getPredicateRegistry(): PredicateRegistry | undefined

Returns: PredicateRegistry | undefined

ensureAdapterIndexes()

H7: ensure the configured adapter has all recommended indexes. No-op for adapters that don't expose ensureIndexes (InMemoryAdapter has nothing to index). Delegates to the adapter's own method — typically MongoMemoryAdapter.ensureIndexes(). Idempotent.

Call from your migration system, not from application hot paths. Index creation on production collections can be expensive; the library intentionally does not call this automatically at construction time.

See docs/MEMORY_PERMISSIONS.md (or the memory README) for the full list of recommended indexes and why each matters. Cross-process deployments with MemoryPluginNextGen additionally need a unique index on {identifiers.kind: 1, identifiers.value: 1} (partial, filtered on identifiers.$.value: {$exists: true}) — this one is not created by ensureIndexes() because adding a unique index to a collection with existing duplicates fails hard; callers should build + verify it explicitly in a migration.

async ensureAdapterIndexes(): Promise<void>

Returns: Promise<void>

assertEnterpriseReady()

Surface configuration drift that would make this MemorySystem unsafe for enterprise multi-tenant deployment. Returns a list of human-readable failings rather than throwing — hosts gate startup on findings.length.

Two readiness tiers — ok is not "fully enterprise ready":

• ok === true → the MINIMUM-SAFETY tier passed: data integrity invariants are held + tenant isolation is enforceable. No severity: 'error' findings remain. The host can boot without risking cross-tenant data leaks, owner-required violations, or permission-denial bypasses, but the LLM-writer ergonomics may still be lax.
• ok === true AND findings.every(f => f.severity !== 'warn') → the FULL enterprise-readiness tier. Adds the strict-vocabulary guarantee (LLM writers can't invent predicates), enables Mongo's fast paths for vector search, and confirms the adapter is fully tuned. This is what production deployments should actually gate on.

Operators who want the stricter gate:

const { ok, findings } = memory.assertEnterpriseReady();
const enterpriseReady = ok && findings.every((f) => f.severity !== 'warn');
if (!enterpriseReady) throw new Error(`Memory not fully ready: ${JSON.stringify(findings)}`);

Severity rationale:

• 'error' is reserved for invariant violations — config that lets bad data into the store or leaks across tenants (no visibilityPolicy, no PredicateRegistry at all).
• 'warn' covers quality / ergonomics — config that hurts retrieval, consistency, or LLM-write hygiene but doesn't compromise integrity (permissive predicate mode, missing vector index names).

What's checked:

• error — PredicateRegistry is configured. Without one, predicates remain free-form strings; fragmentation is guaranteed under any LLM-driven write path.
• error — visibilityPolicy is set. Library defaults grant world-read to every entity/fact (644-style) — unsafe by default for enterprise. A policy that returns { world: 'none' } (private) or { world: 'none', group: 'read' } (group-readable) is the typical enterprise baseline.
• warn — predicateMode === 'strict'. Permissive mode + LLM writers fragments the predicate vocabulary over time (prefers vs prefer vs preference), eroding dedup and ranking quality. Not an error because the data still has owners + permissions; only the vocabulary hygiene is at risk.
• warn — Mongo adapter: vectorIndexName is set (drives Atlas Vector Search fast paths). Skipped for InMemoryAdapter.
• warn — Mongo adapter + embedder present: entityContentVectorIndexName is set. Without it findSimilarOpenTasks, document search, and any composer-driven retrieval fall back to the slow path.

What's NOT checked (require side effects the library shouldn't trigger from a readonly probe):

• Whether the Mongo unique partial index on {identifiers.kind, identifiers.value} actually exists. Run a migration-side probe (db.entities.getIndexes()).
• Whether the unique normalized-name partial index from ensureNormalizedNameUniqueIndex exists. Same — migration-side.
• Whether ensureVectorSearchIndexes() has been called against Atlas. Idempotent to call again from your migration; that's the supported path.

assertEnterpriseReady(): {
    ok: boolean;
    findings: Array<{ severity: 'error' | 'warn'; code: string; message: string }>;
  }

Returns: { ok: boolean; findings: { severity: "error" | "warn"; code: string; message: string; }[]; }

backfillNormalizedFields()

Backfill normalizedDisplayName + normalizedAliases on entities written before v0.8.0 (or by adapter paths that bypassed the storage-boundary stamp). Iterates entities in scope in batches, recomputes the fields from each entity's current displayName / aliases, and writes when the stored value differs.

Idempotent — running twice with the same data is a no-op. Run before ensureNormalizedNameUniqueIndex (the unique partial index would fail to build if pre-backfill dups exist).

Returns { scanned, updated, skipped } for caller observability:

• scanned — total entities visited.
• updated — wrote an entity because at least one field differed.
• skipped — entity already had both fields populated and consistent; no write performed.

Concurrency caveat: the backfill uses updateEntity (optimistic concurrency on version). Concurrent writers bumping the version between read and write trigger a retry once; further conflicts surface as OptimisticConcurrencyError on the helper.

Force mode: pass { force: true } to write every scanned entity regardless of whether the stored value differs. Useful when normalizeSurface has been tweaked and the entire population needs re-stamping. Default is the cheaper differ-only path.

async backfillNormalizedFields(
    scope: ScopeFilter,
    opts?: { batchSize?: number; force?: boolean },
  ): Promise<{ scanned: number; updated: number; skipped: number }>

Parameters:

• scope: ScopeFilter
• opts: { batchSize?: number | undefined; force?: boolean | undefined; } | undefined (optional)

Returns: Promise<{ scanned: number; updated: number; skipped: number; }>

backfillAccessPrincipals()

Backfill readPrincipals / writePrincipals on every entity + fact (live AND archived) written before the principal model — or by any path that predates the storage-boundary stamp. Recomputes each row's arrays from its ownerId / groupId / permissions / acl and writes when they differ.

THE MIGRATION GATE: a host MUST run this to completion before it starts passing scope.principals. Query-time (Mongo) filtering has NO legacy fallback for rows lacking readPrincipals — an un-backfilled row is simply invisible to a principal caller (see ScopeFilter.principals).

Idempotent — re-running with the same data is a no-op (arrays are recomputed deterministically and compared before writing). { force: true } rewrites every row regardless (use after the materialization rules change).

Entities go through updateEntity (the storage boundary re-stamps the arrays) with the same retry-once optimistic-concurrency handling as backfillNormalizedFields. Facts are patched directly with the computed arrays (no updateFact recompute is triggered — the patch carries the arrays, not the access-source fields).

async backfillAccessPrincipals(
    scope: ScopeFilter,
    opts?: { batchSize?: number; force?: boolean },
  ): Promise<{
    entitiesScanned: number;
    entitiesUpdated: number;
    factsScanned: number;
    factsUpdated: number;
  }>

Parameters:

• scope: ScopeFilter
• opts: { batchSize?: number | undefined; force?: boolean | undefined; } | undefined (optional)

Returns: Promise<{ entitiesScanned: number; entitiesUpdated: number; factsScanned: number; factsUpdated: number; }>

hoistContextIdsFromFactsToEntities()

Migration helper — for every fact with the given predicate, hoist the fact's contextIds array onto the target entity's contextIds (union merge). Target entity is the fact's subject or object depending on entitySide.

Reference recipe — hoist legacy committed_to(person, task) linkage onto task entities (the v10-era pattern that v11+ writes natively as task.contextIds):

await memory.hoistContextIdsFromFactsToEntities({
  predicate: 'committed_to',
  entitySide: 'object',
  entityType: 'task',
  archiveSource: false, // keep originals as provenance until host confirms
}, scope);

Idempotent — addEntityContextIds deduplicates against existing values. Safe to re-run. Skips facts with empty contextIds, missing target id, or where the target entity type doesn't match entityType.

Performance. O(facts-with-this-predicate). Pass batchSize to tune memory pressure vs round-trips (default 200, hard ceiling 1000).

Source archival. When archiveSource: true, the source fact is archived after the hoist succeeds for that fact. Defaults to false because hosts often want to keep the original fact for provenance — the migration is informational, not destructive.

async hoistContextIdsFromFactsToEntities(
    opts: {
      predicate: string;
      entitySide: 'subject' | 'object';
      entityType?: string;
      batchSize?: number;
      dryRun?: boolean;
      archiveSource?: boolean;
    },
    scope: ScopeFilter,
  ): Promise<{
    scannedFacts: number;
    /** Facts that triggered a real entity write (added >= 1 new contextId). */
    hoistedEntities: number;
    /**
     * Facts where the target entity already had every contextId — no write
     * performed. Important for migration planning: re-runs of an idempotent
     * migration are expected to land entirely in this bucket. Also bumped on
     * dry-run when the simulated hoist would have been a no-op.
     */
    skippedAlreadyHoisted: number;
    skippedNoContextIds: number;
    skippedWrongType: number;
    skippedNoTarget: number;
    archivedFacts: number;
    errors: number;
  }>

Parameters:

• opts: { predicate: string; entitySide: "object" | "subject"; entityType?: string | undefined; batchSize?: number | undefined; dryRun?: boolean | undefined; archiveSource?: boolean | undefined; }
• scope: ScopeFilter

Returns: Promise<{ scannedFacts: number; hoistedEntities: number; skippedAlreadyHoisted: number; skippedNoContextIds: number; skippedWrongType: number; skippedNoTarget: number; archivedFacts: number; errors: number; }>

getPredicateDefinition()

Lookup a predicate definition (by canonical name or alias). Null when no registry or unknown.

getPredicateDefinition(nameOrAlias: string): PredicateDefinition | null

Parameters:

• nameOrAlias: string

Returns: PredicateDefinition | null

resolveUnknownPredicate()

H5: the configured drift policy + closest known predicate for an unknown. Returns { policy: 'fuzzy_map', mappedTo? } / { policy: 'keep' } / { policy: 'drop' }. mappedTo is only present when the policy is 'fuzzy_map' AND a close registry match exists. Intended for callers (ExtractionResolver) that want to apply the policy themselves and record the decision in their result payload.

resolveUnknownPredicate(canonical: string): {
    policy: 'fuzzy_map' | 'keep' | 'drop';
    mappedTo?: string;
    distance?: number;
  }

Parameters:

• canonical: string

Returns: { policy: "fuzzy_map" | "keep" | "drop"; mappedTo?: string | undefined; distance?: number | undefined; }

addFact()

async addFact(
    input: Partial<IFact> & {
      subjectId: EntityId;
      predicate: string;
      kind: IFact['kind'];
      /**
       * When true: before inserting, look for a non-archived fact with the same
       * (subjectId, canonicalized predicate, kind) and matching (value, objectId).
       * On match → bump `observedAt` on the existing fact and return it — NO new
       * row is inserted. Used by the session ingestor to prevent bloat across
       * repeated observations ("anton works_at everworker" re-extracted).
       * Details merging is the caller's responsibility (see updateFactDetails).
       * Defaults to false for backward-compatibility.
       */
      dedup?: boolean;
    },
    scope: ScopeFilter,
  ): Promise<IFact>

Parameters:

• input: Partial<IFact> & { subjectId: string; predicate: string; kind: FactKind; dedup?: boolean | undefined; }
• scope: ScopeFilter

Returns: Promise<IFact>

addFacts()

async addFacts(
    inputs: Array<
      Partial<IFact> & { subjectId: EntityId; predicate: string; kind: IFact['kind'] }
    >,
    scope: ScopeFilter,
  ): Promise<IFact[]>

Parameters:

• inputs: (Partial<IFact> & { subjectId: string; predicate: string; kind: FactKind; })[]
• scope: ScopeFilter

Returns: Promise<IFact[]>

supersedeFact()

supersedeFact(
    oldId: FactId,
    newInput: Partial<IFact> & { predicate: string; kind: IFact['kind']; subjectId: EntityId },
    scope: ScopeFilter,
  ): Promise<IFact>

Parameters:

• oldId: string
• newInput: Partial<IFact> & { predicate: string; kind: FactKind; subjectId: string; }
• scope: ScopeFilter

Returns: Promise<IFact>

archiveFact()

async archiveFact(id: FactId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

expireFacts()

Scheduled lifecycle sweep — archives facts whose validUntil is in the past relative to asOf (defaults to "now"). Host applications call this on a daily cadence to keep the visible graph trimmed.

Contract:

• Only affects facts that already have validUntil set. Facts without validUntil are valid forever and never touched.
• Only archives facts that are NOT already archived.
• Archived facts remain queryable via archivedOnly / includeArchived paths — this is soft archive, not hard delete.
• Scope-bounded: the caller's scope determines which facts are visible. Multi-tenant schedulers iterate over scopes and call once per scope.
• Emits BOTH fact.archive and fact.expire per archived fact. The fact.archive event preserves the "any archival" contract that existing subscribers (cache invalidators, audit appenders) depend on; fact.expire is the lifecycle-specific signal carrying predicate + validUntil for observability that wants to distinguish automatic expiry from operator/agent archives.

Returns the count of facts archived in this sweep. Paginated internally to bound memory; pageSize defaults to 500.

async expireFacts(
    opts: {
      /** Cutoff. Facts with `validUntil < asOf` are eligible. Defaults to `new Date()`. */
      asOf?: Date;
      /**
       * Restrict to specific predicates. When omitted, all expired facts in
       * scope are archived. Pass `[]` to short-circuit to 0 (no-op).
       */
      predicates?: string[];
      /** Maximum number of facts to archive in this call. Defaults to unbounded. */
      limit?: number;
      /** Internal page size for findFacts. Defaults to 500. */
      pageSize?: number;
    },
    scope: ScopeFilter,
  ): Promise<{ archived: number }>

Parameters:

• opts: { asOf?: Date | undefined; predicates?: string[] | undefined; limit?: number | undefined; pageSize?: number | undefined; }
• scope: ScopeFilter

Returns: Promise<{ archived: number; }>

restoreFact()

Reverse of archiveFact — restore a previously-archived fact so it participates in queries again. Used by the memory_restore tool to give agents an undo path for mistaken archives.

F1 guard: if the target fact was archived as part of a supersession (i.e. another non-archived fact has supersedes: targetId), restoring it would create two "current" facts for the same (subject, predicate) pair. Throws FactSupersededError with the successor's id so callers can handle the successor first. The tool layer surfaces this as a structured error to the LLM.

async restoreFact(id: FactId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

updateFactDetails()

Update an existing fact's details field in place. Intended for merging narrative context when the session ingestor finds a duplicate fact and produces an LLM-merged details string. Recomputes isSemantic (the merged text may cross the length threshold), clears the stale embedding, and re-embeds if an embedder is configured.

This mutates the fact — the prior details is lost. Use supersession if you need the full audit chain.

async updateFactDetails(
    id: FactId,
    details: string,
    scope: ScopeFilter,
  ): Promise<IFact>

Parameters:

• id: string
• details: string
• scope: ScopeFilter

Returns: Promise<IFact>

applyEntityReconciliationOps()

Apply entity-anchored reconciliation operations (Pillar 2).

Caller has:

1. Built an entityReconciliationPrompt for ONE entity's non-archived facts.
2. Run that prompt through an extractor (LLM call).
3. Parsed the LLM output into ReconciliationOp[] via parseExtractionWithStatus.

This method dispatches the resulting ops against the fact graph:

• update → updateFact (value / details / observedAt patch).
• archive → archiveFact.
• create ops are REJECTED (counted as rejectedHallucinated in the outcome) — Pillar 2 only resolves, never creates.

factId validation: every update/archive op's factId MUST appear in priorFacts. Hallucinations are rejected with a warn-level log entry.

Returns op-level counts so callers can log decisions + emit activity-log entries (per feedback_log_every_decision).

async applyEntityReconciliationOps(
    ops: ReconciliationOp[],
    priorFacts: IFact[],
    scope: ScopeFilter,
    opts?: {
      /** Optional skeptic filter — return false to drop an op with logging. */
      skepticFilter?: (op: ReconciliationOp) => boolean;
      /**
       * Source signal id to stamp on `updateFact` patches. Optional — entity
       * reconciliation isn't bound to a single source signal (that's the
       * point), so callers may leave it undefined.
       */
      sourceSignalId?: string;
    },
  ): Promise<OperationOutcome>

Parameters:

• ops: ReconciliationOp[]
• priorFacts: IFact[]
• scope: ScopeFilter
• opts: { skepticFilter?: ((op: ReconciliationOp) => boolean) | undefined; sourceSignalId?: string | undefined; } | undefined (optional)

Returns: Promise<OperationOutcome>

applyReconciliationOps()

Apply signal-reconciliation operations (the SECOND pass — see signalReconciliationPrompt). Generic over signal source: the caller has extracted NEW facts/tasks in pass 1, loaded the PRIOR facts/tasks (deterministic + semantic, de-duplicated), run signalReconciliationPrompt, and parsed the output via parseSignalReconciliationOpsWithStatus.

Dispatch:

• FACT ops are delegated to {@link applyEntityReconciliationOps} — archive supersedes, update mutates in place, create is rejected (the pass reconciles, it does not create — pass 1 owns creation). Every fact op's factId is validated against context.priorFacts.
• task_update ops mutate the task in place: newState routes through {@link transitionTaskState} (state + stateHistory + completedAt), and narrative / dueAt / assigneeId patch the metadata. Every taskId is validated against context.priorTasks; hallucinated ids are rejected. When newState moves the task into a TERMINAL state, the task metadata is stamped with AI-resolution provenance (aiResolved, aiResolutionReason, aiResolutionEvidenceQuote, aiResolvedAt) so the host can distinguish AI auto-resolution from user action.

Returns op-level counts (fact creates/updates/archives + task updates/resolves

• rejections) so callers can log every decision per feedback_log_every_decision.

async applyReconciliationOps(
    ops: SignalReconciliationOp[],
    context: { priorFacts: IFact[]; priorTasks: IEntity[] },
    scope: ScopeFilter,
    opts?: {
      /** Optional skeptic filter — return false to drop an op with logging. */
      skepticFilter?: (op: SignalReconciliationOp) => boolean;
      /** Source signal id stamped on fact-update patches + task state history. */
      sourceSignalId?: string;
      /** Transition timestamp. Defaults to now. */
      at?: Date;
    },
  ): Promise<SignalReconciliationOutcome>

Parameters:

• ops: SignalReconciliationOp[]
• context: { priorFacts: IFact[]; priorTasks: IEntity[]; }
• scope: ScopeFilter
• opts: { skepticFilter?: ((op: SignalReconciliationOp) => boolean) | undefined; sourceSignalId?: string | undefined; at?: Date | undefined; } | undefined (optional)

Returns: Promise<SignalReconciliationOutcome>

updateFact()

Mutate a fact in-place. Used by per-conversation reconciliation (ExtractionResolver) to update value / details / observedAt / sourceSignalId / evidenceQuote on a prior fact when the LLM emits an update op — replacing the legacy "supersede chain" pattern that left tombstones behind.

Restrictions:

• Cannot change subjectId, predicate, kind, objectId, id, createdAt, archived (use archiveFact / restoreFact).
• Caller's scope must have write access to the fact.

Side effects:

• When details changes, re-computes isSemantic, clears stale embedding + summaryForEmbedding, and re-embeds on the embedder queue (best-effort).

async updateFact(
    id: FactId,
    patch: Partial<
      Pick<
        IFact,
        | 'value'
        | 'details'
        | 'observedAt'
        | 'sourceSignalId'
        | 'evidenceQuote'
        | 'confidence'
        | 'importance'
        | 'metadata'
      >
    >,
    scope: ScopeFilter,
  ): Promise<IFact>

Parameters:

• id: string
• patch: Partial<Pick<IFact, "metadata" | "value" | "details" | "confidence" | "evidenceQuote" | "sourceSignalId" | "importance" | "observedAt">>
• scope: ScopeFilter

Returns: Promise<IFact>

findDuplicateFact()

Find an existing non-archived fact matching the (subjectId, predicate, kind, value, objectId) signature of input. Returns null on no match.

Exposed for callers (the session ingestor) that need to split insert vs merge paths themselves — e.g. to batch LLM-based details merging across several duplicates rather than merging one at a time.

Predicate is canonicalized via the registry (if one is configured) so aliases match the same way addFact would treat them.

async findDuplicateFact(
    input: Partial<IFact> & {
      subjectId: EntityId;
      predicate: string;
      kind: IFact['kind'];
    },
    scope: ScopeFilter,
  ): Promise<IFact | null>

Parameters:

• input: Partial<IFact> & { subjectId: string; predicate: string; kind: FactKind; }
• scope: ScopeFilter

Returns: Promise<IFact | null>

getContext()

async getContext(
    entityId: EntityId,
    opts: ContextOptions,
    scope: ScopeFilter,
  ): Promise<EntityView>

Parameters:

• entityId: string
• opts: ContextOptions
• scope: ScopeFilter

Returns: Promise<EntityView>

resolveRelatedItems()

Tasks related to a subject entity. Finds task entities (type='task') where any of the common relational metadata fields point at the subject, OR where a relational fact ties a task to the subject. Returns only non- terminal states by default.

async resolveRelatedItems(
    entityIds: EntityId[],
    scope: ScopeFilter,
    opts?: {
      types?: ('task' | 'event')[];
      /** Task state filter. Default: configured `taskStates.active`. Pass empty array to disable filtering. */
      taskStates?: string[];
      /** Per-bucket cap (tasks and events each capped at this value). Default 50, hard ceiling 200. */
      limit?: number;
      asOf?: Date;
      recentEventsWindowDays?: number;
    },
  ): Promise<RelatedItemsResult>

Parameters:

• entityIds: string[]
• scope: ScopeFilter
• opts: { types?: ("task" | "event")[] | undefined; taskStates?: string[] | undefined; limit?: number | undefined; asOf?: Date | undefined; recentEventsWindowDays?: number | undefined; } | undefined (optional)

Returns: Promise<RelatedItemsResult>

findSimilarOpenTasks()

Semantic kNN over open tasks. Embeds queryText and ranks active tasks by similarity against their contentEmbedding — the metadata-rich composed text (state, due date, assignee/project displayNames, description, contextIds — see taskContentComposer in composers/defaults.ts). This is what lets generic-title tasks like "Follow up" rank correctly when 50 tasks share a name but differ on assignee/project/dueAt.

Pushes the task-state filter into the vector pipeline via EntitySemanticSearchFilter.states when configured filter paths support it (metadata.state in ENTITIES_FILTER_PATHS on Mongo Atlas). The post-filter loop is kept as belt-and-suspenders for adapters that silently ignore unknown filter fields.

Returns empty array when no embedder/semantic adapter is configured — callers should treat semantic similarity as opportunistic, not load-bearing.

async findSimilarOpenTasks(
    queryOrVector: string | number[],
    scope: ScopeFilter,
    opts?: {
      topK?: number;
      minScore?: number;
      taskStates?: string[];
      /**
       * Narrow the search to tasks whose top-level `contextIds` includes this
       * entity id. Pushed into the underlying `semanticSearchEntities` filter
       * → Atlas `$vectorSearch.filter` clause. Requires `'contextIds'` in the
       * entities vector index's filter paths (declared by default — see
       * `ENTITIES_FILTER_PATHS` in MongoMemoryAdapter).
       */
      contextId?: EntityId;
      /**
       * Narrow by assignee entity id. Pushed into vector pipeline filter via
       * `metadata.assigneeId` path. Useful for "tasks for Alice similar to X"
       * scoped queries.
       */
      assigneeId?: EntityId;
      /**
       * Narrow by project entity id. Pushed into vector pipeline filter via
       * `metadata.projectId` path.
       */
      projectId?: EntityId;
      /**
       * Narrow by reporter entity id. Pushed into vector pipeline filter via
       * `metadata.reporterId` path. Mirrors `assigneeId`. Useful for surgical
       * "tasks where X is reporter" queries — e.g. "what did I ask Y to do?".
       */
      reporterId?: EntityId;
      /**
       * OR-wildcard role match — narrows to tasks where this entity appears
       * in any of `metadata.assigneeId`, `metadata.reporterId`,
       * `metadata.projectId`, or top-level `contextIds`. The entity-side
       * analog of `FactFilter.touchesEntity`.
       *
       * Prefer this over fanning out N separate role-narrowed searches and
       * unioning client-side: the union is pushed into Atlas
       * `$vectorSearch.filter` as one compound `$or`, so vector ranking sees
       * the participant-touching candidates together rather than competing
       * across role-specific top-K cuts.
       */
      touchesEntity?: EntityId;
      /**
       * Multi-anchor variant of `touchesEntity` — narrows to tasks touched by
       * ANY id in this array (any of `assigneeId`/`reporterId`/`projectId`/
       * `contextIds`). Use for participant fan-out: pass every participant +
       * context-anchor entity id and let ONE ranked vector query surface the
       * tasks relevant to the whole signal, instead of N per-anchor searches
       * unioned client-side. ANDs with `touchesEntity` when both are set.
       */
      touchesAnyOf?: EntityId[];
    },
  ): Promise<Array<{ task: IEntity; score: number }>>

Parameters:

• queryOrVector: string | number[]
• scope: ScopeFilter
• opts: { topK?: number | undefined; minScore?: number | undefined; taskStates?: string[] | undefined; contextId?: string | undefined; assigneeId?: string | undefined; projectId?: string | undefined; reporterId?: string | undefined; touchesEntity?: string | undefined; touchesAnyOf?: string[] | undefined; } | undefined (optional)

Returns: Promise<{ task: IEntity; score: number; }[]>

semanticSearchEntities()

General-purpose entity-level semantic search over the content embedding (IEntity.contentEmbedding, populated by the registered per-type content composers). The type-agnostic analog of findSimilarOpenTasks (task-only) and searchDocuments (document-only): rank ANY entity type by semantic similarity to a query, narrowed by the full EntitySemanticSearchFilter set (type(s), contextId, task-role fields, and the single/multi touchesEntity / touchesAnyOf OR-wildcards).

Why it exists: hosts building signal-time retrieval ("which entities is this email about?") previously had to fall back to fact-level semanticSearch + manual subject/object/contextIds aggregation. This exposes the entity content vector directly, so the composed entity text (display name, identifiers, narrative, contextIds, host-specific fields) is what gets matched — strictly better recall than re-deriving entities from fact hits.

Accepts a precomputed vector (from embedQuery) to skip the per-call embed round-trip when fanning out several searches over one query.

Error contract mirrors findSimilarOpenTasks: returns [] when the store lacks a semantic-entity capability, when a string query is passed but no embedder is configured, or when the underlying search throws. Semantic similarity is opportunistic, never load-bearing.

embeddingField defaults to 'content' (the composer-backed vector). Pass 'identity' to search the name/identifier vector used by entity resolution. Adapters MUST NOT silently fall back to the other field — entities lacking the selected vector are simply absent from results.

async semanticSearchEntities(
    queryOrVector: string | number[],
    filter: EntitySemanticSearchFilter,
    scope: ScopeFilter,
    opts?: { topK?: number; minScore?: number; embeddingField?: EntityEmbeddingField },
  ): Promise<Array<{ entity: IEntity; score: number }>>

Parameters:

• queryOrVector: string | number[]
• filter: EntitySemanticSearchFilter
• scope: ScopeFilter
• opts: { topK?: number | undefined; minScore?: number | undefined; embeddingField?: EntityEmbeddingField | undefined; } | undefined (optional)

Returns: Promise<{ entity: IEntity; score: number; }[]>

updateEntityMetadata()

Shallow-merge a patch into entity.metadata. Version-bumping, scope-checked, emits entity.upsert event. Caller does NOT read-modify-write — this helper handles all of that atomically (from the caller's perspective).

async updateEntityMetadata(
    id: EntityId,
    patch: Record<string, unknown>,
    scope: ScopeFilter,
  ): Promise<IEntity>

Parameters:

• id: string
• patch: Record<string, unknown>
• scope: ScopeFilter

Returns: Promise<IEntity>

addEntityContextIds()

Union-merge new entity ids into entity.contextIds. The canonical way to mutate the top-level multi-entity binding after creation.

Semantics:

• Visibility-validate every addition (each must be visible to the caller; invisible ids throw — mirrors addFact's context-visibility rule).
• Filter self-references silently (id === entityId).
• Dedupe against existing contextIds.
• No-op fast path when every addition is already present.

Return shape: { entity, added } — added is the count of new contextIds actually persisted (post dedupe + self-reference filter). added === 0 means the call was a no-op (everything was already there or filtered out); the returned entity is unchanged from storage. Migration / audit callers branch on added > 0 to count real mutations.

Concurrency: read-modify-write with optimistic-version retry. Two callers unioning different additions onto the same entity converge because the losing-retry observes the winner's write and computes a fresh union. maxAttempts caps at 3 — the last attempt's OptimisticConcurrencyError bubbles on exhaustion (caller's choice to surface or further-retry at a higher level).

async addEntityContextIds(
    entityId: EntityId,
    additions: EntityId[],
    scope: ScopeFilter,
    opts?: { maxAttempts?: number },
  ): Promise<{ entity: IEntity; added: number }>

Parameters:

• entityId: string
• additions: string[]
• scope: ScopeFilter
• opts: { maxAttempts?: number | undefined; } | undefined (optional)

Returns: Promise<{ entity: IEntity; added: number; }>

transitionTaskState()

Transition a task entity to a new state — the canonical way to mutate task.metadata.state after creation.

Side effects (read-modify-write at the MemorySystem layer; adapters with native transactions may promote to atomic):

• Sets metadata.state = newState.
• Appends metadata.stateHistory: TaskStateHistoryEntry[], keeping only the most-recent stateHistoryCap entries (default 200). Older entries drop in FIFO order. stateHistory is the only audit trail — no separate audit fact is written.
• When newState is in taskStates.terminal AND metadata.completedAt is unset, sets metadata.completedAt = at.

Validate modes:

• 'warn' (default): any transition allowed; out-of-matrix transitions log to console.warn and still proceed.
• 'strict': out-of-matrix transitions throw InvalidTaskTransitionError and the metadata write is skipped.
• 'none': silent.

Subject must be a type: 'task' entity. For non-task subjects, update metadata directly via updateEntityMetadata.

async transitionTaskState(
    taskId: EntityId,
    newState: string,
    opts: TransitionTaskStateOptions,
    scope: ScopeFilter,
  ): Promise<TransitionTaskStateResult>

Parameters:

• taskId: string
• newState: string
• opts: TransitionTaskStateOptions
• scope: ScopeFilter

Returns: Promise<TransitionTaskStateResult>

listOpenTasks()

List open (non-terminal) tasks for a scope, optionally filtered by assignee or project. Thin wrapper around listEntities — uses the configured taskStates.active as the $in filter on metadata.state.

Client-side sort: metadata.dueAt ascending (undefined last), then updatedAt descending. TODO: push down once EntityListFilter.orderBy lands on adapters.

Hard cap 200; default limit 50. Pass a smaller limit explicitly to constrain prompt-token budget when injecting into an extraction prompt.

async listOpenTasks(
    scope: ScopeFilter,
    opts: {
      assigneeId?: EntityId;
      projectId?: EntityId;
      /**
       * Narrow to tasks whose top-level `contextIds` array includes this
       * anchor (project, deal, meeting, etc.). First-class filter — does NOT
       * go through `metadataFilter` (which would query the wrong path).
       */
      contextId?: EntityId;
      limit?: number;
    } = {},
  ): Promise<IEntity[]>

Parameters:

• scope: ScopeFilter
• opts: { assigneeId?: string | undefined; projectId?: string | undefined; contextId?: string | undefined; limit?: number | undefined; } (optional) (default: {})

Returns: Promise<IEntity[]>

listRecentTopics()

List recent topic entities for a scope. Fetches up to limit * 4 (capped at 200) topics and filters client-side by updatedAt >= cutoff where cutoff defaults to now - days days. Sorted by updatedAt descending.

TODO: push down once EntityListFilter.updatedAfter + orderBy land on adapters.

async listRecentTopics(
    scope: ScopeFilter,
    opts: { days?: number; limit?: number } = {},
  ): Promise<IEntity[]>

Parameters:

• scope: ScopeFilter
• opts: { days?: number | undefined; limit?: number | undefined; } (optional) (default: {})

Returns: Promise<IEntity[]>

iterateOpenTasks()

Async iterator over all open tasks visible to scope, yielded in batches.

Sort: metadata.dueAt asc nulls-last, then updatedAt desc, then id asc tiebreak. Same as listOpenTasks, but iterates the full result set rather than truncating at 200.

Use this when you need EVERY open task (status refresh, audit sweeps, backfills). Use listOpenTasks when you need a small bounded slice (prompt injection).

async *iterateOpenTasks(
    scope: ScopeFilter,
    opts: {
      assigneeId?: EntityId;
      projectId?: EntityId;
      /** Narrow to tasks whose top-level `contextIds` includes this anchor. */
      contextId?: EntityId;
      batchSize?: number;
      /** Resume from a cursor returned by a prior interrupted iteration. */
      startAfter?: string;
    } = {},
  ): AsyncIterable<IEntity[]>

Parameters:

• scope: ScopeFilter
• opts: { assigneeId?: string | undefined; projectId?: string | undefined; contextId?: string | undefined; batchSize?: number | undefined; startAfter?: string | undefined; } (optional) (default: {})

Returns: AsyncIterable<IEntity[]>

iterateRecentTopics()

Async iterator over recent topic entities visible to scope, yielded in batches. Sort: updatedAt desc. The days window is applied client-side (consistent with listRecentTopics); iteration stops when either the store is exhausted OR the first batch with all entries older than the cutoff is encountered (since sort is desc, no younger ones exist past that point).

async *iterateRecentTopics(
    scope: ScopeFilter,
    opts: { days?: number; batchSize?: number; startAfter?: string } = {},
  ): AsyncIterable<IEntity[]>

Parameters:

• scope: ScopeFilter
• opts: { days?: number | undefined; batchSize?: number | undefined; startAfter?: string | undefined; } (optional) (default: {})

Returns: AsyncIterable<IEntity[]>

iterateEntitiesByFilter()

Generic async iterator over entities matching filter. The caller MUST pass orderBy to guarantee deterministic iteration — without it, the adapter's natural order kicks in and the iteration result is non-portable across stores. This method does not warn (the adapter does) but does require the caller to be explicit.

async *iterateEntitiesByFilter(
    filter: EntityListFilter,
    scope: ScopeFilter,
    opts: {
      batchSize?: number;
      startAfter?: string;
      orderBy: EntityOrderBy | EntityOrderBy[];
    },
  ): AsyncIterable<IEntity[]>

Parameters:

• filter: EntityListFilter
• scope: ScopeFilter
• opts: { batchSize?: number | undefined; startAfter?: string | undefined; orderBy: EntityOrderBy | EntityOrderBy[]; }

Returns: AsyncIterable<IEntity[]>

iterateFacts()

Generic async iterator over facts matching query. Like iterateEntitiesByFilter, the caller MUST pass orderBy (FactOrderBy accepts observedAt | createdAt | confidence) to ensure deterministic iteration across stores.

async *iterateFacts(
    query: FactFilter,
    scope: ScopeFilter,
    opts: {
      batchSize?: number;
      startAfter?: string;
      orderBy: FactOrderBy;
    },
  ): AsyncIterable<IFact[]>

Parameters:

• query: FactFilter
• scope: ScopeFilter
• opts: { batchSize?: number | undefined; startAfter?: string | undefined; orderBy: FactOrderBy; }

Returns: AsyncIterable<IFact[]>

getProfile()

Resolve the most-specific profile visible to the caller. Precedence: ownerId match > groupId match > global. First hit wins.

async getProfile(entityId: EntityId, scope: ScopeFilter): Promise<IFact | null>

Parameters:

• entityId: string
• scope: ScopeFilter

Returns: Promise<IFact | null>

traverse()

async traverse(
    entityId: EntityId,
    opts: TraversalOptions,
    scope: ScopeFilter,
  ): Promise<Neighborhood>

Parameters:

• entityId: string
• opts: TraversalOptions
• scope: ScopeFilter

Returns: Promise<Neighborhood>

embedQuery()

Embed a query string once so the resulting vector can be reused across multiple semanticSearch / findSimilarOpenTasks calls with different filters. Avoids re-embedding the same query in fan-out workloads (multi-predicate searches, RAG with per-tenant filters, etc.).

Throws SemanticSearchUnavailableError when no embedder is configured — mirroring semanticSearch's error contract so callers can rely on embedQuery succeeding wherever semanticSearch(string, ...) would.

async embedQuery(query: string): Promise<number[]>

Parameters:

• query: string

Returns: Promise<number[]>

semanticSearch()

Semantic kNN over facts. Accepts either:

• string — embeds internally (one round-trip per call), OR
• number[] — a pre-computed vector from embedQuery, reused across fan-out calls so the embed cost is paid once.

The number[] form throws only on the store-capability check; no embedder is required (the vector is already available).

async semanticSearch(
    queryOrVector: string | number[],
    filter: FactFilter,
    scope: ScopeFilter,
    topK: number = DEFAULT_SEMANTIC_TOP_K,
  ): Promise<Array<{ fact: IFact; score: number }>>

Parameters:

• queryOrVector: string | number[]
• filter: FactFilter
• scope: ScopeFilter
• topK: number (optional) (default: DEFAULT_SEMANTIC_TOP_K)

Returns: Promise<{ fact: IFact; score: number; }[]>

regenerateProfile()

async regenerateProfile(
    entityId: EntityId,
    targetScope: ScopeFields,
    _trigger: 'threshold' | 'manual' = 'manual',
  ): Promise<IFact>

Parameters:

• entityId: string
• targetScope: ScopeFields
• _trigger: "manual" | "threshold" (optional) (default: 'manual')

Returns: Promise<IFact>

deriveFactsFor()

async deriveFactsFor(entityId: EntityId, scope: ScopeFilter): Promise<IFact[]>

Parameters:

• entityId: string
• scope: ScopeFilter

Returns: Promise<IFact[]>

createDocument()

Create a new document. When slug is provided, the document carries {kind:'canonical', value:'doc:<slug>'} so subsequent lookups via getDocument(slug) resolve deterministically. When attachTo is set, an idempotent has_document fact is written linking the parent to the new document.

Returns the created entity. Content-embedding refresh is queued asynchronously — read pendingEmbeddings() / flushEmbeddings() to observe.

async createDocument(input: CreateDocumentInput, scope: ScopeFilter): Promise<Document>

Parameters:

• input: CreateDocumentInput
• scope: ScopeFilter

Returns: Promise<Document>

updateDocument()

Update a document — body, role, format, summary, or extra metadata. All fields optional; only provided keys are touched (shallow overwrite over metadata). Queues a content-embedding refresh if body changed (gated by metadataDeepEqual short-circuit in applyMetadataMerge).

idOrSlug accepts either a raw entity id or a bare slug (the doc: prefix is added automatically when the value isn't recognized as an id).

async updateDocument(
    idOrSlug: string,
    patch: UpdateDocumentInput,
    scope: ScopeFilter,
  ): Promise<Document>

Parameters:

• idOrSlug: string
• patch: UpdateDocumentInput
• scope: ScopeFilter

Returns: Promise<Document>

getDocument()

Fetch a document by id or slug. Returns the entity verbatim (including metadata.body). Returns null when not found / not visible.

async getDocument(idOrSlug: string, scope: ScopeFilter): Promise<Document | null>

Parameters:

• idOrSlug: string
• scope: ScopeFilter

Returns: Promise<Document | null>

attachDocument()

Attach a document to a parent entity via the canonical has_document predicate. Idempotent — a no-op when an identical non-archived fact already exists in the caller's scope.

async attachDocument(parentId: EntityId, docIdOrSlug: string, scope: ScopeFilter): Promise<void>

Parameters:

• parentId: string
• docIdOrSlug: string
• scope: ScopeFilter

Returns: Promise<void>

detachDocument()

Remove a has_document attachment between a parent entity and a document. Archives EVERY matching non-archived fact in scope (idempotent), so duplicate attachments — should they exist due to race conditions — are cleaned up in one call.

Returns {archived, skippedDueToPermissions} so callers can distinguish "no matching facts" (both zero) from "had matches but couldn't write any" (archived=0, skipped>0).

async detachDocument(
    parentId: EntityId,
    docIdOrSlug: string,
    scope: ScopeFilter,
  ): Promise<DetachDocumentResult>

Parameters:

• parentId: string
• docIdOrSlug: string
• scope: ScopeFilter

Returns: Promise<DetachDocumentResult>

listDocuments()

List documents — optionally narrowed by attachedTo, role, ownerId. By default the response strips metadata.body (listing pages can be large); pass includeBody: true to keep it.

async listDocuments(filter: ListDocumentsFilter, scope: ScopeFilter): Promise<Document[]>

Parameters:

• filter: ListDocumentsFilter
• scope: ScopeFilter

Returns: Promise<Document[]>

searchDocuments()

Search documents — semantic mode uses contentEmbedding (requires an embedder); keyword mode runs a case-insensitive substring match over metadata.body and displayName against a page of candidates. Both modes honor attachedTo / role filters and clamp limit to [1, 50].

Score semantics: semantic returns 0..1 cosine similarity from the underlying semanticSearchEntities; keyword returns a coarse 0..1 hit score (1.0 for displayName match, 0.5 for body-only).

async searchDocuments(input: SearchDocumentsInput, scope: ScopeFilter): Promise<DocumentSearchHit[]>

Parameters:

• input: SearchDocumentsInput
• scope: ScopeFilter

Returns: Promise<DocumentSearchHit[]>

flushEmbeddings()

flushEmbeddings(): Promise<void>

Returns: Promise<void>

pendingEmbeddings()

pendingEmbeddings(): number

Returns: number

backfillContentEmbeddings()

Backfill contentEmbedding / contentEmbeddingText for entities whose stored embedding doesn't match what the current composer would produce.

Run-once migration helper. Use cases:

• Upgrading from a release where content embedding was document-only — backfill makes every task / event / person / etc. searchable semantically without waiting for each entity's next mutation.
• After overriding a composer in MemorySystemConfig.entityContentComposers so the new composer's output applies to historical data immediately.
• After running mergeEntities / archiveEntity campaigns where cascading content refresh would be desirable.

Idempotent. Skips entities whose contentEmbeddingText already matches the composer output (no embed cost). Safe to re-run.

Resumable. No transactional guarantees. Interrupting mid-run leaves a partially-converged population; re-running converges the remainder.

Scoping. Bounded by scope (same visibility rules as every other read). Multi-tenant hosts iterate over scopes and call once per scope.

Concurrency. Each enqueue goes through the standard EmbeddingQueue with bounded concurrency (config.embeddingQueue.concurrency). Caller should await memorySystem.flushEmbeddings() after the helper returns to wait for all in-flight embeds.

async backfillContentEmbeddings(
    scope: ScopeFilter,
    opts?: {
      /** Narrow to specific entity types. Empty/omitted = all types. */
      types?: string[];
      /** Page size for the streaming scan. Default 500, max 1000. */
      batchSize?: number;
      /** Progress callback invoked after each page. */
      onProgress?: (scanned: number, queued: number) => void;
    },
  ): Promise<{ scanned: number; queued: number; skipped: number }>

Parameters:

• scope: ScopeFilter
• opts: { types?: string[] | undefined; batchSize?: number | undefined; onProgress?: ((scanned: number, queued: number) => void) | undefined; } | undefined (optional)

Returns: Promise<{ scanned: number; queued: number; skipped: number; }>

backfillFactEmbeddings()

Backfill embedding / summaryForEmbedding for facts. Sister method to backfillContentEmbeddings — same idempotency, same scoping rules. Run once when upgrading to a release that removes the 80-char threshold gate, so short atomic facts (e.g. (Sarah, works_at, Acme)) become searchable semantically without waiting for each fact's next mutation.

async backfillFactEmbeddings(
    scope: ScopeFilter,
    opts?: {
      /** Narrow to specific fact predicates. Empty/omitted = all predicates. */
      predicates?: string[];
      /** Narrow to fact kind. Empty/omitted = both atomic + document. */
      kind?: IFact['kind'];
      /** Page size for the streaming scan. Default 500, max 1000. */
      batchSize?: number;
      /** Progress callback invoked after each page. */
      onProgress?: (scanned: number, queued: number) => void;
    },
  ): Promise<{ scanned: number; queued: number; skipped: number }>

Parameters:

• scope: ScopeFilter
• opts: { predicates?: string[] | undefined; kind?: FactKind | undefined; batchSize?: number | undefined; onProgress?: ((scanned: number, queued: number) => void) | undefined; } | undefined (optional)

Returns: Promise<{ scanned: number; queued: number; skipped: number; }>

destroy()

destroy(): void

Returns: void

shutdown()

async shutdown(): Promise<void>

Returns: Promise<void>

constructor

constructor(config: MemoryWritePluginConfig)

Parameters:

• config: MemoryWritePluginConfig

getInstructions()

getInstructions(): string | null

Returns: string | null

getContent()

async getContent(): Promise<string | null>

Returns: Promise<string | null>

getContents()

getContents(): unknown

Returns: unknown

getTokenSize()

getTokenSize(): number

Returns: number

getInstructionsTokenSize()

getInstructionsTokenSize(): number

Returns: number

isCompactable()

isCompactable(): boolean

Returns: boolean

compact()

async compact(_targetTokensToFree: number): Promise<number>

Parameters:

• _targetTokensToFree: number

Returns: Promise<number>

getTools()

getTools(): ToolFunction[]

Returns: ToolFunction<any, any>[]

destroy()

destroy(): void

Returns: void

getState()

getState(): unknown

Returns: unknown

restoreState()

restoreState(_state: unknown): void

Parameters:

• _state: unknown

Returns: void

constructor

constructor(public readonly limit: string)

Parameters:

• limit: string

constructor

constructor(options: { id?: string; limits?: ModelTaskLimits; signal?: AbortSignal } = {})

Parameters:

• options: { id?: string | undefined; limits?: ModelTaskLimits | undefined; signal?: AbortSignal | undefined; } (optional) (default: {})

cancel()

cancel(reason: unknown = new DOMException('Model task cancelled', 'AbortError')): void

Parameters:

• reason: unknown (optional) (default: new DOMException('Model task cancelled', 'AbortError'))

Returns: void

execute()

Execute one logical call; installed SDK adapters admit every physical retry separately.

async execute<T>(descriptor: ModelCallDescriptor, operation: (signal: AbortSignal) => Promise<T>, options: {
    signal?: AbortSignal; transport?: boolean; usage?: (result: T) => TokenUsage | undefined;
    /** @internal Latest terminal usage survives an iterator failure or cancellation. */
    observedUsage?: () => TokenUsage | undefined;
    /** @internal Final synchronous native request/authority guard, including retries. */
    beforeDispatch?: () => void;
    /** @internal Observed provider/transport dispatch after successful reservation. */
    onDispatch?: () => void;
  } = {}): Promise<{ result: T; invocationId: string }>

Parameters:

• descriptor: ModelCallDescriptor
• operation: (signal: AbortSignal) => Promise<T>
• options: { signal?: AbortSignal | undefined; transport?: boolean | undefined; usage?: ((result: T) => TokenUsage | undefined) | undefined; observedUsage?: (() => TokenUsage | undefined) | undefined; beforeDispatch?: (() => void) | undefined; onDispatch?: (() => void) | undefined; } (optional) (default: {})

Returns: Promise<{ result: T; invocationId: string; }>

iterate()

Streaming variant with pull-based backpressure and invocation-local transport tracking.

async *iterate<T>(descriptor: ModelCallDescriptor, factory: (signal: AbortSignal) => AsyncIterable<T>, options: {
    signal?: AbortSignal; transport?: boolean; usage?: (event: T) => TokenUsage | undefined;
    beforeDispatch?: () => void;
    /** @internal Observed provider/transport dispatch after successful reservation. */
    onDispatch?: () => void;
  } = {}): AsyncIterableIterator<T>

Parameters:

• descriptor: ModelCallDescriptor
• factory: (signal: AbortSignal) => AsyncIterable<T>
• options: { signal?: AbortSignal | undefined; transport?: boolean | undefined; usage?: ((event: T) => TokenUsage | undefined) | undefined; beforeDispatch?: (() => void) | undefined; onDispatch?: (() => void) | undefined; } (optional) (default: {})

Returns: AsyncIterableIterator<T>

recordExternal()

Host-reported usage is idempotent by ID. Conflicting replays fail explicitly.

recordExternal(report: { id: string; purpose: string; connector: string; model: string; parentInvocationId?: string; usage: TokenUsage | null;
    status?: 'succeeded' | 'failed' | 'cancelled'; }): void

Parameters:

• report: { id: string; purpose: string; connector: string; model: string; parentInvocationId?: string | undefined; usage: TokenUsage | null; status?: "failed" | "cancelled" | "succeeded" | undefined; }

Returns: void

recordValidation()

Attach a host validation result without recounting the model usage.

recordValidation(invocationId: string, valid: boolean): void

Parameters:

• invocationId: string
• valid: boolean

Returns: void

snapshot()

snapshot(): ModelTaskSnapshot

Returns: ModelTaskSnapshot

destroy()

destroy(): void

Returns: void

constructor

constructor(opts: MongoMemoryAdapterOptions)

Parameters:

• opts: MongoMemoryAdapterOptions

ensureIndexes()

H7: ensure the recommended indexes exist. Idempotent — Mongo's createIndex is a no-op when the index is already present with matching specification. Callers integrate this into their migration system; the adapter does NOT call it automatically (indexes are the client app's responsibility, not a library concern).

Invokes the shared ensureIndexes(...) function against this adapter's collections. See indexes.ts for the index list and why each exists.

async ensureIndexes(): Promise<void>

Returns: Promise<void>

createEntity()

async createEntity(input: NewEntity): Promise<IEntity>

Parameters:

• input: NewEntity

Returns: Promise<IEntity>

createEntities()

async createEntities(inputs: NewEntity[]): Promise<IEntity[]>

Parameters:

• inputs: NewEntity[]

Returns: Promise<IEntity[]>

updateEntity()

async updateEntity(entity: IEntity): Promise<void>

Parameters:

• entity: IEntity

Returns: Promise<void>

getEntity()

async getEntity(id: EntityId, scope: ScopeFilter): Promise<IEntity | null>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<IEntity | null>

getEntities()

async getEntities(ids: EntityId[], scope: ScopeFilter): Promise<Array<IEntity | null>>

Parameters:

• ids: string[]
• scope: ScopeFilter

Returns: Promise<(IEntity | null)[]>

findEntitiesByIdentifier()

async findEntitiesByIdentifier(
    kind: string,
    value: string,
    scope: ScopeFilter,
  ): Promise<IEntity[]>

Parameters:

• kind: string
• value: string
• scope: ScopeFilter

Returns: Promise<IEntity[]>

atomicCreateOrFindByNormalizedName()

Atomic find-or-create by (type, normalizedDisplayName, scope). See the interface contract.

Implementation: optimistic find-then-insert with duplicate-key recovery. Cross-process atomicity depends on the unique partial index on {groupId, ownerId, type, normalizedDisplayName} being installed — without it, a racing insert succeeds and produces duplicates. The library exports ensureNormalizedNameUniqueIndex for hosts to install in their migration (not auto-installed because adding a unique index to a collection containing duplicates fails).

async atomicCreateOrFindByNormalizedName(
    input: NewEntity,
    scope: ScopeFilter,
  ): Promise<{ entity: IEntity; created: boolean }>

Parameters:

• input: NewEntity
• scope: ScopeFilter

Returns: Promise<{ entity: IEntity; created: boolean; }>

findEntitiesByNormalizedName()

async findEntitiesByNormalizedName(
    type: string | undefined,
    normalized: string,
    scope: ScopeFilter,
    opts?: { matchAliases?: boolean; limit?: number },
  ): Promise<IEntity[]>

Parameters:

• type: string | undefined
• normalized: string
• scope: ScopeFilter
• opts: { matchAliases?: boolean | undefined; limit?: number | undefined; } | undefined (optional)

Returns: Promise<IEntity[]>

searchEntities()

async searchEntities(
    query: string,
    opts: EntitySearchOptions,
    scope: ScopeFilter,
  ): Promise<Page<IEntity>>

Parameters:

• query: string
• opts: EntitySearchOptions
• scope: ScopeFilter

Returns: Promise<Page<IEntity>>

listEntities()

async listEntities(
    filter: EntityListFilter,
    opts: ListOptions,
    scope: ScopeFilter,
  ): Promise<Page<IEntity>>

Parameters:

• filter: EntityListFilter
• opts: ListOptions
• scope: ScopeFilter

Returns: Promise<Page<IEntity>>

archiveEntity()

async archiveEntity(id: EntityId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

deleteEntity()

async deleteEntity(id: EntityId, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<void>

createFact()

async createFact(input: NewFact): Promise<IFact>

Parameters:

• input: NewFact

Returns: Promise<IFact>

createFacts()

async createFacts(inputs: NewFact[]): Promise<IFact[]>

Parameters:

• inputs: NewFact[]

Returns: Promise<IFact[]>

getFact()

async getFact(id: FactId, scope: ScopeFilter): Promise<IFact | null>

Parameters:

• id: string
• scope: ScopeFilter

Returns: Promise<IFact | null>

findFacts()

async findFacts(
    filter: FactFilter,
    opts: FactQueryOptions,
    scope: ScopeFilter,
  ): Promise<Page<IFact>>

Parameters:

• filter: FactFilter
• opts: FactQueryOptions
• scope: ScopeFilter

Returns: Promise<Page<IFact>>

updateFact()

async updateFact(id: FactId, patch: Partial<IFact>, scope: ScopeFilter): Promise<void>

Parameters:

• id: string
• patch: Partial<IFact>
• scope: ScopeFilter

Returns: Promise<void>

rewriteEntityPrincipal()

Rewrite entity:<from> → entity:<to> access grants across entities, facts, and (if present) the facts archive. Bulk identity fix used by mergeEntities; scoped to the caller's tenant for safety, no per-record write check, no version bump (these are access-token rewrites, not semantic mutations). See IMemoryStore.rewriteEntityPrincipal.

async rewriteEntityPrincipal(
    fromEntityId: EntityId,
    toEntityId: EntityId,
    scope: ScopeFilter,
  ): Promise<void>

Parameters:

• fromEntityId: string
• toEntityId: string
• scope: ScopeFilter

Returns: Promise<void>

countFacts()

async countFacts(filter: FactFilter, scope: ScopeFilter): Promise<number>

Parameters:

• filter: FactFilter
• scope: ScopeFilter

Returns: Promise<number>

traverse()

async traverse(
    startId: EntityId,
    opts: TraversalOptions,
    scope: ScopeFilter,
  ): Promise<Neighborhood>

Parameters:

• startId: string
• opts: TraversalOptions
• scope: ScopeFilter

Returns: Promise<Neighborhood>

semanticSearch()

async semanticSearch(
    queryVector: number[],
    filter: FactFilter,
    opts: SemanticSearchOptions,
    scope: ScopeFilter,
  ): Promise<Array<{ fact: IFact; score: number }>>

Parameters:

• queryVector: number[]
• filter: FactFilter
• opts: SemanticSearchOptions
• scope: ScopeFilter

Returns: Promise<{ fact: IFact; score: number; }[]>

semanticSearchEntities()

async semanticSearchEntities(
    queryVector: number[],
    filter: EntitySemanticSearchFilter,
    opts: SemanticSearchOptions & { minScore?: number; embeddingField?: EntityEmbeddingField },
    scope: ScopeFilter,
  ): Promise<Array<{ entity: IEntity; score: number }>>

Parameters:

• queryVector: number[]
• filter: EntitySemanticSearchFilter
• opts: SemanticSearchOptions & { minScore?: number | undefined; embeddingField?: EntityEmbeddingField | undefined; }
• scope: ScopeFilter

Returns: Promise<{ entity: IEntity; score: number; }[]>

ensureVectorSearchIndexes()

Create the Atlas Vector Search indexes for facts and/or entities if they aren't already present. Separate from ensureIndexes() because vector indexes need runtime parameters (dimensions, similarity) and take longer to build — callers shouldn't pay that cost unless they use semantic search.

Requires:

• Atlas Server v6.0.11+ and mongodb node driver v6.6+ (the driver exposes createSearchIndex / listSearchIndexes).
• The IMongoCollectionLike wrapper must implement createSearchIndex (both bundled wrappers do; custom wrappers may need updating).

Idempotent — re-running is safe: existing indexes with the configured name are detected via listSearchIndexes and skipped. Concurrent-create races (two migrations running at once) are absorbed: if createSearchIndex fails but the index is present on re-check, we treat it as "another process won" and continue.

Fire-and-forget: returns as soon as Atlas accepts the create request. The index builds asynchronously on Atlas (30–60s typical). Runs during startup migrations, so the index is ready well before real traffic. The typical first query lands minutes after the migration, not seconds — no readiness wait needed.

Index names come from the adapter's config by default. If the adapter was constructed with vectorIndexName: 'custom_facts' (or entityVectorIndexName: 'custom_entities'), this helper creates indexes under those names automatically. Callers can still override via factsIndexName / entitiesIndexName, but the default is the safe choice — runtime queries and helper output always agree.

Filter fields are auto-declared in the index definition. Atlas $vectorSearch silently ignores filter clauses whose paths aren't declared as type: 'filter' in the index. We declare scope + archived

• discriminator paths for both collections so scope enforcement works on the $vectorSearch fast path. See the field lists in FACTS_FILTER_PATHS / ENTITIES_FILTER_PATHS below — manual Atlas-UI creators must match or the filter is silently ignored (scope bypass).

async ensureVectorSearchIndexes(opts: {
    /** Embedding dimensionality — MUST match your embedder. Must be a positive integer. */
    dimensions: number;
    /** Default: 'cosine'. Match the similarity your embedder was trained for. */
    similarity?: 'cosine' | 'dotProduct' | 'euclidean';
    /**
     * Atlas index name for facts. Default: the adapter's own `vectorIndexName`
     * option, or `'facts_vector'` when that's also unset. Pass `null` to skip
     * the facts index entirely.
     */
    factsIndexName?: string | null;
    /**
     * Atlas index name for entities (identityEmbedding). Default: the
     * adapter's own `entityVectorIndexName` option, or `'entities_vector'`
     * when unset. Pass `null` to skip.
     */
    entitiesIndexName?: string | null;
    /**
     * Atlas index name for entity content (contentEmbedding) — used by
     * document semantic search. **Opt-in.** Default: the adapter's own
     * `entityContentVectorIndexName` option, or **`null` (skip)** when that's
     * also unset. Hosts that use documents should either set the adapter's
     * `entityContentVectorIndexName` (so the runtime path and this helper
     * agree on the name) or pass `entitiesContentIndexName` explicitly here.
     *
     * Default-skip is deliberate: adding a third Atlas index automatically
     * on `ensureVectorSearchIndexes()` would silently bill existing
     * deployments that aren't using documents.
     */
    entitiesContentIndexName?: string | null;
  }): Promise<void>

Parameters:

• opts: { dimensions: number; similarity?: "cosine" | "dotProduct" | "euclidean" | undefined; factsIndexName?: string | null | undefined; entitiesIndexName?: string | null | undefined; entitiesContentIndexName?: string | null | undefined; }

Returns: Promise<void>

destroy()

destroy(): void

Returns: void

shutdown()

async shutdown(): Promise<void>

Returns: Promise<void>

constructor

constructor(
    /** Array of task failures */
    public readonly failures: TaskFailure[]
  )

Parameters:

• failures: TaskFailure[]

getErrors()

Get all failure errors

getErrors(): Error[]

Returns: Error[]

getFailedTaskIds()

Get failed task IDs

getFailedTaskIds(): string[]

Returns: string[]

static create()

Create a new PlanningAgent

static create(config: PlanningAgentConfig): PlanningAgent

Parameters:

• config: PlanningAgentConfig

Returns: PlanningAgent

generatePlan()

Generate a plan from a goal

async generatePlan(input: {
    goal: string;
    context?: string;
    constraints?: string[];
  }): Promise<GeneratedPlan>

Parameters:

• input: { goal: string; context?: string | undefined; constraints?: string[] | undefined; }

Returns: Promise<GeneratedPlan>

refinePlan()

Validate and refine an existing plan

async refinePlan(plan: Plan, feedback: string): Promise<GeneratedPlan>

Parameters:

• plan: Plan
• feedback: string

Returns: Promise<GeneratedPlan>

getCurrentTasks()

Get current tasks (for tool access)

getCurrentTasks(): TaskInput[]

Returns: TaskInput[]

addTask()

Add task (called by planning tools)

addTask(task: TaskInput): void

Parameters:

• task: TaskInput

Returns: void

updateTask()

Update task (called by planning tools)

updateTask(name: string, updates: Partial<TaskInput>): void

Parameters:

• name: string
• updates: Partial<TaskInput>

Returns: void

removeTask()

Remove task (called by planning tools)

removeTask(name: string): void

Parameters:

• name: string

Returns: void

finalizePlanning()

Mark planning as complete

finalizePlanning(): void

Returns: void

constructor

constructor(config: TaskStatePluginConfig)

Parameters:

• config: TaskStatePluginConfig

emptyState()

emptyState(): TaskStateSnapshot

Returns: TaskStateSnapshot

updateHost()

Host-only atomic update. The model has no tool exposing this method.

updateHost(delta: TaskStateHostDelta, expectedRevision: number): TaskStateSnapshot

Parameters:

• delta: TaskStateHostDelta
• expectedRevision: number

Returns: TaskStateSnapshot