extractAndRetain

extractAndRetain(messages: AutoExtractMessage[], retainCtx: RetainContext, options: object): Promise<{ candidates: ExtractedCandidate[]; failedCount: number; results: RetainResult[]; }>

Defined in: src/lib/memory/autoExtract.ts:146

Stage 2 — for each extracted candidate, call retain() with auto-merge enabled. The resolver path (decide create/merge/update via a second LLM call against the existing vault) is deferred — the auto-merge inside retain() handles dedup at the cosine-similarity level for hackathon.

Returns the candidates that survived validation along with the retain result for each (which captures whether the fact was created, merged, or skipped).

Parameters

Parameter	Type	Description
`messages`	`AutoExtractMessage`[]	‐
`retainCtx`	`RetainContext`	‐
`options`	`object`	‐
`options.entityCtx?`	`EntityOperationsContext`	When provided, persist each candidate’s `entities[]` to the entity + memory_entity tables after a successful retain. This powers the W5 graph retrieval lane — recall() can query for memories sharing entities with the user’s question.
`options.extract`	`ExtractFactsOptions`	‐
`options.folderId?`	`string` \| `null`	‐
`options.minConfidence?`	`number`	‐
`options.onCandidateFailed?`	(`candidate`: `ExtractedCandidate`, `error`: `unknown`) => `void`	Per-candidate failure hook — invoked once per filtered candidate whose `retain()` call threw. Lets UI layers surface “couldn’t save X” toasts; without it consumers only see the aggregate `failedCount` and can’t name which facts dropped.
`options.scope?`	`string`	Override scope/folder for all retained facts.

Returns

Promise<{ candidates: ExtractedCandidate[]; failedCount: number; results: RetainResult[]; }>