Graphorin API reference v0.7.0
Graphorin API reference / @graphorin/memory / / IterativeSearchOptions
Interface: IterativeSearchOptions
Defined in: packages/memory/src/tiers/semantic-memory.ts:328
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:180 |
candidateTopK? | readonly | number | Override the per-list candidate count (default 60). | FactSearchOptions.candidateTopK | packages/memory/src/tiers/semantic-memory.ts:162 |
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:226 |
decay.now? | readonly | () => number | Override the wall clock (test seam). | - | packages/memory/src/tiers/semantic-memory.ts:229 |
decay.tauDays | readonly | number | - | - | packages/memory/src/tiers/semantic-memory.ts:227 |
difficultyThreshold? | readonly | number | Difficulty-gate threshold in [0, 1] for THIS call (W-088). The gate's signal lexicon is English-only - for non-English deployments lower the threshold or use forceHard. Omitted ⇒ the facade default (iterativeRetrieval.difficultyThreshold) or the built-in 0.5. | - | packages/memory/src/tiers/semantic-memory.ts:348 |
entityMatch? | readonly | boolean | Exact entity-match retriever (D5). When set, the query terms are normalized to entity names and facts linked to a matching canonical entity are fused in as a precise candidate leg (entity fusion weight), distinct from the fuzzy FTS / vector legs. A no-op without a graph-capable adapter. Opt-in. Stable | FactSearchOptions.entityMatch | packages/memory/src/tiers/semantic-memory.ts:304 |
expandHops? | readonly | 0 | 1 | 2 | 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. 2 (D5) widens to two-hop expansion - pair with graphScoring: 'ppr' so distant neighbours decay instead of tying with direct ones. Stable | FactSearchOptions.expandHops | packages/memory/src/tiers/semantic-memory.ts:284 |
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:340 |
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:269 |
graphScoring? | readonly | "flat" | "ppr" | Graph-expansion scoring (D5). 'flat' (the default) scores every graph neighbour 1 (the pre-D5 behaviour). 'ppr' uses PPR-lite damped spreading activation (damping^hopDepth) via the store's expandActivation, so a two-hop neighbour ranks below a direct one; a no-op without expandHops >= 1 or a graph-capable adapter. Stable | FactSearchOptions.graphScoring | packages/memory/src/tiers/semantic-memory.ts:294 |
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:257 |
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:190 |
includeSuperseded? | readonly | boolean | Include superseded / validity-expired facts (memory-retrieval-01). Defaults to false: a default read behaves as asOf = now, so a fact whose validity interval was closed (e.g. by supersede) never surfaces as current - what the fact_supersede tool promises. Set true only for inspector / audit paths. Ignored when an explicit asOf is supplied. Stable | FactSearchOptions.includeSuperseded | packages/memory/src/tiers/semantic-memory.ts:213 |
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:334 |
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:245 |
owner? | readonly | | MemoryOwner | readonly MemoryOwner[] | Retrieval-time principal filter (D3). When set, only facts whose owner is in the requested set are returned - 'user' for user-stated facts, 'agent' for the agent's own inferences, 'shared' for multi-agent shared records. Rows written before the feature (owner NULL) are treated as 'user'. Applied in-store on the FTS + vector legs and as a record-level filter on the fused result so the HyDE / graph legs obey it too. Absent (the default) ⇒ no owner filter - recall is byte-identical. Stable | FactSearchOptions.owner | packages/memory/src/tiers/semantic-memory.ts:317 |
signal? | readonly | AbortSignal | - | FactSearchOptions.signal | packages/memory/src/tiers/semantic-memory.ts:160 |
tags? | readonly | readonly string[] | Any-of tags filter (MRET-4). A fact matches when it carries at least one of the requested tags; untagged facts never match. Applied in-store on the FTS leg and as a record-level filter on the fused result so every candidate leg (vector / HyDE / graph) obeys it. | FactSearchOptions.tags | packages/memory/src/tiers/semantic-memory.ts:170 |
topK? | readonly | number | - | FactSearchOptions.topK | packages/memory/src/tiers/semantic-memory.ts:159 |
trustWeighting? | readonly | "on" | "off" | Rank-time trust discount (C5). 'on' (default) multiplies each hit's fused score by its trust factor - quarantined-but-included rows by 1 - quarantine (default 0.3x), foreign-provenance rows by 1 - foreignProvenance (default 0.8x); first-party active facts are untouched. 'off' restores pure similarity ranking (inspector / calibration paths). Factors surface as the trust signal on hits and in explainRecall. Stable | FactSearchOptions.trustWeighting | packages/memory/src/tiers/semantic-memory.ts:202 |