Graphorin API reference v0.7.0
Graphorin API reference / @graphorin/memory / facade / CreateMemoryOptions
Interface: CreateMemoryOptions
Defined in: packages/memory/src/facade.ts:68
Options accepted by createMemory.
Stable
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
conflictPipeline? | readonly | ConflictPipelineOptions | Conflict pipeline configuration (Phase 10b). Default: enabled, English locale pack, thresholds 0.95 / 0.85 / 0.4. Pass { mode: 'off' } to bypass the pipeline entirely (logs a one-shot WARN per process per the spec). | packages/memory/src/facade.ts:315 |
consolidator? | readonly | { autoPromoteExtraction?: boolean; ceilings?: Partial<ConsolidatorCeilings>; cheapModel?: string | null; cheapProvider?: Provider | null; contextualRetrieval?: ContextualRetrievalMode; decayArchiveThreshold?: number; decayCapacity?: number | null; decayTauDays?: number; deepModel?: string | null; deepProvider?: Provider | null; defaultScope?: SessionScope; dlqBaseBackoffMs?: number; dlqMaxBackoffMs?: number; dlqMaxRetries?: number; enabled?: boolean; formEpisodes?: boolean; importanceScoring?: boolean; importanceThreshold?: number; learnedContext?: boolean; learnedContextMaxChars?: number; lockWaitMs?: number; maxDeepConflictsPerRun?: number; maxStandardBatchSize?: number; maxTranscriptChars?: number; noiseFilters?: readonly ("default" | "minimal" | "none")[]; now?: () => number; onExceed?: OnBudgetExceed; onPhaseFinished?: PhaseListener; phases?: readonly ConsolidatorPhase[]; priceUsage?: (usage) => number; provider?: Provider | null; randomId?: () => string; reflection?: boolean; reflectionMaxQuarantinedInsights?: number; reflectionMaxQuestions?: number; salienceWeights?: SalienceWeights; tier?: ConsolidatorTier; triggers?: readonly ConsolidatorTriggerSpec[]; } | Consolidator configuration. When omitted, empty, or enabled: false, the facade installs the Phase 10a no-op placeholder so consumers can still type their interactions without paying the runtime cost. ANY other setting - including offline knobs like decayCapacity or contextualRetrieval - implicitly enables the production runtime (MST-4); enabled: false together with other settings warns once and keeps the placeholder. | packages/memory/src/facade.ts:230 |
consolidator.autoPromoteExtraction? | readonly | boolean | Opt in to auto-promotion of injection-clean extraction facts (MCON-2). Default off. | packages/memory/src/facade.ts:273 |
consolidator.ceilings? | readonly | Partial<ConsolidatorCeilings> | - | packages/memory/src/facade.ts:235 |
consolidator.cheapModel? | readonly | string | null | - | packages/memory/src/facade.ts:246 |
consolidator.cheapProvider? | readonly | Provider | null | Provider routed to the standard phase when set (MCON-7); falls back to provider. | packages/memory/src/facade.ts:243 |
consolidator.contextualRetrieval? | readonly | ContextualRetrievalMode | Contextual retrieval for standard-phase fact writes (P1-3). 'llm' opts into one budgeted cheap-model call per write to author a situating prefix (consolidator-only); 'late-chunk' (default) and 'off' defer to the write-path mode. Per-tier default. | packages/memory/src/facade.ts:288 |
consolidator.decayArchiveThreshold? | readonly | number | - | packages/memory/src/facade.ts:251 |
consolidator.decayCapacity? | readonly | number | null | Capacity-bounded eviction target for the light phase (X-1). Default unbounded. | packages/memory/src/facade.ts:253 |
consolidator.decayTauDays? | readonly | number | - | packages/memory/src/facade.ts:250 |
consolidator.deepModel? | readonly | string | null | - | packages/memory/src/facade.ts:247 |
consolidator.deepProvider? | readonly | Provider | null | Provider routed to the deep + reflection passes when set (MCON-7). | packages/memory/src/facade.ts:245 |
consolidator.defaultScope? | readonly | SessionScope | - | packages/memory/src/facade.ts:300 |
consolidator.dlqBaseBackoffMs? | readonly | number | - | packages/memory/src/facade.ts:266 |
consolidator.dlqMaxBackoffMs? | readonly | number | - | packages/memory/src/facade.ts:267 |
consolidator.dlqMaxRetries? | readonly | number | - | packages/memory/src/facade.ts:265 |
consolidator.enabled? | readonly | boolean | - | packages/memory/src/facade.ts:231 |
consolidator.formEpisodes? | readonly | boolean | Auto-form quarantined episodes from processed slices (P1-2). Per-tier default. | packages/memory/src/facade.ts:269 |
consolidator.importanceScoring? | readonly | boolean | Score episode importance via the consolidator LLM (P1-2). Per-tier default. | packages/memory/src/facade.ts:271 |
consolidator.importanceThreshold? | readonly | number | Accumulated-importance threshold at which reflection fires (P1-1). | packages/memory/src/facade.ts:277 |
consolidator.learnedContext? | readonly | boolean | Maintain the learned-context digest block (D3): after each deep phase, one budgeted LLM call rewrites the reserved learned_context working block (previous digest + recent episodes / active insights / procedures), so the assembled system prompt carries a compact standing summary. Default false at every tier (Wave-D trial). | packages/memory/src/facade.ts:297 |
consolidator.learnedContextMaxChars? | readonly | number | Character bound for the learned-context digest (D3). Default 1200. | packages/memory/src/facade.ts:299 |
consolidator.lockWaitMs? | readonly | number | - | packages/memory/src/facade.ts:249 |
consolidator.maxDeepConflictsPerRun? | readonly | number | - | packages/memory/src/facade.ts:264 |
consolidator.maxStandardBatchSize? | readonly | number | - | packages/memory/src/facade.ts:256 |
consolidator.maxTranscriptChars? | readonly | number | Input transcript budget for one standard-phase slice, in characters (W-081). Over-budget batches are half-split before the provider call; a lone over-budget message is tail-truncated. Per-tier default (60k chars ~ 15k tokens; 120k on full). | packages/memory/src/facade.ts:263 |
consolidator.noiseFilters? | readonly | readonly ("default" | "minimal" | "none")[] | - | packages/memory/src/facade.ts:248 |
consolidator.now? | readonly | () => number | Override the wall clock - used by tests. | packages/memory/src/facade.ts:303 |
consolidator.onExceed? | readonly | OnBudgetExceed | - | packages/memory/src/facade.ts:236 |
consolidator.onPhaseFinished? | readonly | PhaseListener | Subscribe to phase-finished events. | packages/memory/src/facade.ts:307 |
consolidator.phases? | readonly | readonly ConsolidatorPhase[] | - | packages/memory/src/facade.ts:234 |
consolidator.priceUsage? | readonly | (usage) => number | USD pricer for phase LLM usage (memory-consolidation-02) - wire to @graphorin/pricing so maxCostPerDay can actually trip. | packages/memory/src/facade.ts:241 |
consolidator.provider? | readonly | Provider | null | - | packages/memory/src/facade.ts:301 |
consolidator.randomId? | readonly | () => string | Stable id seed - used by tests. | packages/memory/src/facade.ts:305 |
consolidator.reflection? | readonly | boolean | Run the deep-phase reflection pass synthesizing cited insights (P1-1). Per-tier default. | packages/memory/src/facade.ts:275 |
consolidator.reflectionMaxQuarantinedInsights? | readonly | number | Override the quarantined-insight queue cap (W-082). Default 100. | packages/memory/src/facade.ts:281 |
consolidator.reflectionMaxQuestions? | readonly | number | Upper bound on salient questions reflection asks per pass (P1-1). | packages/memory/src/facade.ts:279 |
consolidator.salienceWeights? | readonly | SalienceWeights | Weights for the multi-signal salience score (X-1). | packages/memory/src/facade.ts:255 |
consolidator.tier? | readonly | ConsolidatorTier | - | packages/memory/src/facade.ts:233 |
consolidator.triggers? | readonly | readonly ConsolidatorTriggerSpec[] | - | packages/memory/src/facade.ts:232 |
contextEngine? | readonly | ContextEngineConfig | Context engine configuration (Phase 10d). The engine assembles the layered six-layer system prompt; memory.compile(scope) delegates to it for the working blocks + rules + metadata fragments. When omitted, a default engine is created (English locale; 'full' base mode; no auto-recall; conservative 'public-tls' provider trust). | packages/memory/src/facade.ts:324 |
contextualRetrieval? | readonly | "off" | "late-chunk" | Contextual-retrieval mode for the write path (P1-3). 'late-chunk' (default) prepends a deterministic, offline situating context (entities / timeframe / topics, derived from the fact's own structured fields) to the text that is embedded + FTS-indexed, so a terse fact stays findable; the canonical text is preserved. 'off' indexes the bare text. The 'llm' enrichment is not available on the hot path - it is a consolidator-only opt-in configured via consolidator: { contextualRetrieval: 'llm' }. | packages/memory/src/facade.ts:112 |
embedder? | readonly | EmbedderProvider | Embedder provider (default: none - vector search is disabled). | packages/memory/src/facade.ts:74 |
embeddings | readonly | EmbeddingMetaRegistryLike | Embedder registry. The default sqlite store exposes one as sqlite.embeddings. | packages/memory/src/facade.ts:72 |
graph? | readonly | EntityResolutionConfig & { entityResolution?: boolean; provider?: Provider; } | Relation-graph entity resolution (P2-1). When entityResolution is true and the storage adapter exposes a graph surface (the default @graphorin/store-sqlite does), remember(...) resolves a fact's subject / object to canonical entities and links them, so search(..., { expandHops: 1 }) can traverse relationships. Omitted (the default) ⇒ facts still carry s/p/o but form no entity links and the write path stays offline + unchanged. Dedup is lexical + embedding (offline, via the configured embedder); LLM adjudication of ambiguous merges is a further opt-in that needs provider. | packages/memory/src/facade.ts:143 |
iterativeRetrieval? | readonly | { difficultyThreshold?: number; maxIterations?: number; maxTokens?: number; provider: Provider; } | Agentic / iterative retrieval (P2-4, opt-in). When supplied, SemanticMemory.searchIterative(...) and the gated deep_recall tool can grade a retrieved set on the given provider and, for queries judged hard, reformulate + retrieve again (widening to one-hop graph expansion) up to maxIterations, abstaining instead of confabulating when memory is insufficient. Omitted (the default) ⇒ searchIterative stays a single difficulty-gated pass with no provider call, and deep_recall is not registered (the tool surface stays at the canonical eleven). Reserve it for hard multi-hop / temporal recall - it adds provider latency per pass. | packages/memory/src/facade.ts:161 |
iterativeRetrieval.difficultyThreshold? | readonly | number | Default difficulty-gate threshold in [0, 1] (W-088). The gate's signal lexicon is English-only: on non-English deployments the auto-gate never fires, so either lower this threshold or rely on forceHard (deep_recall already forces the loop). Omitted ⇒ the built-in 0.5; per-call difficultyThreshold overrides it. | packages/memory/src/facade.ts:175 |
iterativeRetrieval.maxIterations? | readonly | number | Default total-pass cap (clamped to [1, 5]). Default 3. | packages/memory/src/facade.ts:165 |
iterativeRetrieval.maxTokens? | readonly | number | Output-token ceiling per grade call. Default 256. | packages/memory/src/facade.ts:167 |
iterativeRetrieval.provider | readonly | Provider | Cheap provider used to grade retrieved memories + reformulate. | packages/memory/src/facade.ts:163 |
procedureInduction? | readonly | { maxTokens?: number; provider: Provider; } | Opt-in workflow induction (P2-2). When set, ProceduralMemory.induce(...) distils a reusable, value-abstracted procedure from a successful agent trajectory and stores it quarantined + provenance: 'induction'. Omitted (the default) ⇒ induce(...) throws ProcedureInductionNotConfiguredError and the procedural tier stays pure offline CRUD - no provider call. | packages/memory/src/facade.ts:185 |
procedureInduction.maxTokens? | readonly | number | Output-token ceiling per induction call. Default 512. | packages/memory/src/facade.ts:189 |
procedureInduction.provider | readonly | Provider | Provider used to abstract trajectory values into a procedure. | packages/memory/src/facade.ts:187 |
procedurePromotion? | readonly | { afterSuccesses: number; } | Promotion-by-demonstrated-success for quarantined induced procedures (MCON-2 part 4). Fully offline - orthogonal to procedureInduction (no provider needed). When configured, procedural.recordOutcome(scope, id, true) increments the rule's persistent success counter and promotes it into activate() once afterSuccesses verified reuses accumulate; the injection gate still refuses flagged texts. Omitted ⇒ outcomes are counted but nothing auto-promotes. | packages/memory/src/facade.ts:201 |
procedurePromotion.afterSuccesses | readonly | number | Successful demonstrated reuses required before promotion (≥ 1). | packages/memory/src/facade.ts:203 |
queryTransform? | readonly | { maxTokens?: number; maxVariants?: number; provider: Provider; } | Query transformation for retrieval (P2-3, opt-in). When supplied, SemanticMemory.search(..., { multiQuery }) fans the query into reworded variants (multi-query / RAG-Fusion) and { hyde } adds a hypothetical-answer embedding - both via one cheap LLM call on the given provider, fused through the existing RRF reranker. Omitted (the default) ⇒ search stays offline + single-shot and the multiQuery / hyde search options become silent no-ops. Reserve it for retrieval-heavy recall, not every search (it adds provider latency). | packages/memory/src/facade.ts:124 |
queryTransform.maxTokens? | readonly | number | Output-token ceiling per transform call. Default 256. | packages/memory/src/facade.ts:130 |
queryTransform.maxVariants? | readonly | number | Hard ceiling on reworded variants requested per call. Default 5. | packages/memory/src/facade.ts:128 |
queryTransform.provider | readonly | Provider | Cheap provider used to rewrite the query / write the HyDE passage. | packages/memory/src/facade.ts:126 |
reranker? | readonly | ReRanker | Override the reranker used by SemanticMemory.search. | packages/memory/src/facade.ts:84 |
resolveScope? | readonly | ScopeResolver | Resolver that produces the live SessionScope for each memory-tool invocation. Defaults to a closure that throws - the agent runtime overrides it in Phase 12. | packages/memory/src/facade.ts:220 |
runbookSearch? | readonly | boolean | Register the gated runbook_search tool (D3) so the model can look up validated procedures by task description (content recall over procedural memory, returning whole runbooks). Fully offline - the default @graphorin/store-sqlite adapter serves it from the rules FTS index (migration 028); adapters without the index degrade to an in-memory lexical scan. Default false - the tool surface stays at the canonical eleven. | packages/memory/src/facade.ts:214 |
searchDefaults? | readonly | SemanticSearchDefaults | Construction-time retrieval defaults (W-086) merged under every SemanticMemory.search(...) call, per-call options winning key-by-key. This is how the advanced retrieval stack (multi-query fan-out, HyDE, graph expansion, entity matching, weighted fusion, decay ranking) reaches the model-facing surfaces - fact_search, auto-recall and deep_recall all funnel through search() and inherit these without custom tools. Deliberately excludes the trust-sensitive predicates (includeQuarantined, includeSuperseded, trustWeighting, owner) so configuration cannot silently weaken trust gates. The fan-out switches only take effect when their backing dependency is configured (queryTransform for multiQuery/hyde, graph for expandHops/entityMatch) - and they add provider latency and cost to EVERY recall, including auto-recall, so opt in deliberately. | packages/memory/src/facade.ts:101 |
store | readonly | MemoryStoreAdapter | Storage adapter (default: @graphorin/store-sqlite's MemoryStore). | packages/memory/src/facade.ts:70 |
tracer? | readonly | Tracer | Tracer used for every memory.* span. Defaults to the no-op tracer from @graphorin/core so unit tests do not need to wire the observability stack. | packages/memory/src/facade.ts:82 |
workingBlocks? | readonly | readonly BlockDefinition[] | Pre-declared working blocks (idempotent - re-defining is a no-op). | packages/memory/src/facade.ts:76 |