Graphorin API reference v0.4.0
Graphorin API reference / @graphorin/memory / / IterativeSearchOptions
Interface: IterativeSearchOptions
Defined in: packages/memory/src/tiers/semantic-memory.ts:206
Per-call options for SemanticMemory.searchIterative (P2-4) — the gated grade-then-reformulate loop. Extends FactSearchOptions (every base option applies to each retrieval pass); topK doubles as the cap on the accumulated result count.
Stable
Extends
Properties
| Property | Modifier | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|---|
asOf? | readonly | string | Point-in-time ("as of") read. When set, only facts whose bi-temporal validity interval contains this instant are returned (valid_from <= asOf < valid_to, open-ended bounds allowed), applied at the store layer to both the FTS and vector candidate lists. ISO-8601. Absent ⇒ current behaviour is unchanged. P0-2. Stable | FactSearchOptions.asOf | packages/memory/src/tiers/semantic-memory.ts:116 |
candidateTopK? | readonly | number | Override the per-list candidate count (default 60). | FactSearchOptions.candidateTopK | packages/memory/src/tiers/semantic-memory.ts:106 |
decay? | readonly | { now?: () => number; tauDays: number; } | Optional decay-aware ranking. When set, the reranker output is post-multiplied by the per-fact retention curve score *= exp(-elapsedDays / tauDays) so stale facts drop in the result list without ever being hard-deleted (principle 8). Requires the storage adapter to expose semantic.listForDecay?(...) so the search can read strength + lastAccessedAt; adapters without the surface skip the boost silently. Stable | FactSearchOptions.decay | packages/memory/src/tiers/semantic-memory.ts:139 |
decay.now? | readonly | () => number | Override the wall clock (test seam). | - | packages/memory/src/tiers/semantic-memory.ts:142 |
decay.tauDays | readonly | number | - | - | packages/memory/src/tiers/semantic-memory.ts:140 |
expandHops? | readonly | 0 | 1 | One-hop graph expansion (P2-1). With 1 and a graph-capable storage adapter (store.graph), the facts retrieved by the lexical / vector candidate pass are treated as seeds: facts sharing a canonical entity (subject / object) are fetched via a recursive CTE and fused in as an extra candidate list before rerank — surfacing connected facts the query never matched directly ("what did the person I met in Tbilisi recommend?"). 0 (the default) or a graph-less adapter ⇒ a silent no-op; recall is unchanged. Opt-in + retrieval-heavy. Stable | FactSearchOptions.expandHops | packages/memory/src/tiers/semantic-memory.ts:195 |
forceHard? | readonly | boolean | Skip the heuristic difficulty gate and force the loop (still capped and still a no-op without a grader). For deliberate "deep recall" requests and tests. | - | packages/memory/src/tiers/semantic-memory.ts:218 |
fusion? | readonly | FusionStrategy | Score-fusion strategy (X-2). Omitted (the default) ⇒ RRF via the configured reranker — behaviour is unchanged. { strategy: 'weighted', weights } fuses through WeightedRRFReranker, up-/down-weighting the FTS vs vector candidate lists per FusionWeights; reserve it for callers who have calibrated the weights against labels (the P0-1 eval harness). At equal weights it reproduces RRF. Stable | FactSearchOptions.fusion | packages/memory/src/tiers/semantic-memory.ts:182 |
hyde? | readonly | boolean | HyDE — Hypothetical Document Embeddings (arXiv:2212.10496), P2-3. When true and both a query transformer and an embedder are configured, generate a short hypothetical answer, embed it, and fuse its vector neighbours into the result. Helps short / ambiguous queries but adds a generate + embed round-trip and can drift — hence opt-in. With no transformer (or no embedder) this is a silent no-op and no provider call is made. Stable | FactSearchOptions.hyde | packages/memory/src/tiers/semantic-memory.ts:170 |
includeQuarantined? | readonly | boolean | Include quarantined facts in the result (P1-4). Defaults to false — action-driving recall (fact_search, auto-recall) never returns quarantined rows. Set true only for the validation / inspector path that surfaces quarantined facts to a human for promotion via SemanticMemory.validate. Stable | FactSearchOptions.includeQuarantined | packages/memory/src/tiers/semantic-memory.ts:126 |
maxIterations? | readonly | number | Total-pass cap, clamped to [1, 5]. Omitted ⇒ the facade-configured default (createMemory({ iterativeRetrieval: { maxIterations } })) or 3. | - | packages/memory/src/tiers/semantic-memory.ts:212 |
multiQuery? | readonly | number | Multi-query / RAG-Fusion (P2-3). When set to N > 1 and a query transformer is configured (createMemory({ queryTransform })), the query is fanned into up to N - 1 reworded variants via one cheap LLM call; each variant is retrieved (FTS + vector) and all lists are fused through the existing RRF reranker — recovering memories whose stored wording differs from the user's phrasing. N bounds the total query strings, including the original. Offline (no transformer, or N <= 1) this is a silent no-op: search stays single-shot and makes no provider call. Opt-in + retrieval-heavy, so reserve it for deliberate recall rather than every search. Stable | FactSearchOptions.multiQuery | packages/memory/src/tiers/semantic-memory.ts:158 |
signal? | readonly | AbortSignal | - | FactSearchOptions.signal | packages/memory/src/tiers/semantic-memory.ts:104 |
topK? | readonly | number | - | FactSearchOptions.topK | packages/memory/src/tiers/semantic-memory.ts:103 |