Skip to main content

Interface: MemoryRecallConfig

Defined in: packages/agentos/src/cognition/memory/core/config.ts:480

The recall settings of memory.recall on agent() and gmi(), of a persona's cognitiveMemoryConfig.recall, and of a manager's recall.

Extended by​

Properties​

budget?​

optional budget: object

Defined in: packages/agentos/src/cognition/memory/core/config.ts:491

totalTokens: the budget of the whole memory block a GMI turn sends, its preamble included, in tokens of about 4 characters. An integer of at least 0; at 0 the turn sends no block and records every candidate left out for the budget. On agent() without runtime: 'gmi' it is the tokenBudget handed to memoryProvider.getContext when memoryProviderOptions.tokenBudget is unset.

totalTokens?​

optional totalTokens: number

Default​

{ totalTokens: 1600 }

capture?​

optional capture: RecallCaptureMode

Defined in: packages/agentos/src/cognition/memory/core/config.ts:504

'metadata' returns a capture record (MemoryRecallCapture) with every assembled context (AssembledMemoryContext.capture) and on a GMI turn's result; 'metadata+stream' also sends it on the runtime stream (a METADATA_UPDATE carrying memorySources, and memoryRecall on the FINAL_RESPONSE); 'off' records nothing. The record holds ids, ranks, scores, counts and timings, never a memory's text or the query's; ids and scores can concern memories of the other scopes a turn reads (the organization's, the persona's), so the host decides who sees a capture.

Default​

'metadata'

rerank?​

optional rerank: "none" | { kind: "local"; maxCandidates?: number; model: string; revision: string; timeoutMs?: number; } | { invoke: (system, user, model?) => Promise<string>; kind: "llm"; maxCandidates?: number; model: string; timeoutMs?: number; }

Defined in: packages/agentos/src/cognition/memory/core/config.ts:552

Reranks the recalled memories before they are shown. 'none': no reranker. { kind: 'local' }: a cross-encoder that runs in this process, named by model (a Hugging Face model id) and a pinned revision, a whole commit id of the model's repository in lower case (40 hexadecimal characters, or 64 for a SHA-256 repository; a branch, a tag, a shortened id or an upper-case id is refused: the first three can name other weights later, and Transformers.js finds a pinned revision's cached files under the id as written); the query and the memories never leave the process. The model's files load through Transformers.js's own cache. { kind: 'llm' }: the host's own model call (invoke(system, user, model), called with model) scores and ranks them, which sends the query and the first 200 characters of each candidate memory to that model's provider. No remote reranking service is offered for memories.

A reranker that is loading, unavailable, slow or failing never fails a turn: the order stands and the capture's reranker says why. The local model loads when the manager initialises (recallReady() resolves when it has); a load that fails is not retried. timeoutMs bounds one rerank (default 1500 for local, 10000 for llm); maxCandidates is how many of the best candidates are scored (default 20). Both are positive integers, and timeoutMs is at most 2,147,483,647, the longest delay a timer keeps (a timer set past it runs after 1 ms). The local model's pass runs on the calling thread, so its deadline cannot fire while it runs: a pass that ends after timeoutMs counts as a timeout and its order is not used. After three failures or timeouts in a row the rerank is skipped for 60 seconds. Under 'dense' the reranked candidates' scores become 0.7 × retrieval score + 0.3 × rerank score and order them; under 'hybrid' they are ordered by 0.7 × fused score / the best fused score of the cut's recalled candidates (at most 1) + 0.3 × rerank score and keep their scores.

On a built manager, change it with applyRecallConfig(): the provider is built once, so a value written to the configuration is not read.

Default​

'none'

retrieval?​

optional retrieval: "hybrid" | "dense"

Defined in: packages/agentos/src/cognition/memory/core/config.ts:516

How a turn finds its memories. 'dense': by meaning (the vector query and its six-signal ranking), shown in Relevant Memories and Recent Experiences. 'hybrid': by meaning, by the turn's exact words (the store's full-text index through the storage adapter, or an in-process index where memory has no store) and by recency, fused into one deduped pool and shown as one Relevant Memories section. Both embed the query once, and neither calls any other vendor.

Default​

'dense'