Graphorin API reference v0.7.0

---

Graphorin API reference / @graphorin/memory / / SemanticMemory

Class: SemanticMemory

Defined in: packages/memory/src/tiers/semantic-memory.ts:429

SemanticMemory - long-term factual store. Hybrid (vector + FTS5) search merges the two ranked lists through the configured ReRanker (default RRFReranker with k = 60).

Phase 10a wrote facts straight through with MD5 deduplication; Phase 10b routes every remember(...) call through the multi-stage conflict resolution pipeline (DEC-117 / ADR-018 ext / RB-02). The pipeline can be disabled per-call (pipeline: 'off') or per-Memory instance (createMemory({ conflictPipeline: { mode: 'off' } })).

Stable

Constructors

Constructor

new SemanticMemory(args): SemanticMemory;

Defined in: packages/memory/src/tiers/semantic-memory.ts:445

Parameters

Parameter	Type	Description
args	{ conflictPipeline?: ConflictPipeline; contextualRetrieval?: "off" | "late-chunk"; embedder: | EmbedderProvider | null; embedderIdProvider: () => string | null; entityResolver?: EntityResolver; grader?: RetrievalGrader; iterativeDifficultyThreshold?: number; iterativeMaxIterations?: number; queryTransformer?: QueryTransformer; reranker: ReRanker; searchDefaults?: SemanticSearchDefaults; store: MemoryStoreAdapter; tracer: Tracer; trustWeights?: SalienceWeights; }	-
args.conflictPipeline?	ConflictPipeline	-
args.contextualRetrieval?	"off" | "late-chunk"	Contextual-retrieval mode for the write path (P1-3). 'late-chunk' (default) prepends a deterministic situating context to the text that is embedded + FTS-indexed, leaving the canonical text untouched; 'off' indexes the bare text. The hot write path never makes an LLM call - the 'llm' enrichment is confined to the background consolidator, which supplies a precomputed indexText.
args.embedder	| EmbedderProvider | null	-
args.embedderIdProvider	() => string | null	-
args.entityResolver?	EntityResolver	Entity resolver for the relation graph (P2-1). When supplied, remember(...) resolves a fact's subject / object to canonical entities and links them, enabling search(..., { expandHops: 1 }). Omitted (the default) ⇒ writes carry s/p/o but form no entity links, and the write path stays offline + unchanged.
args.grader?	RetrievalGrader	Retrieval grader for the gated iterative loop (P2-4). When supplied, searchIterative(...) can grade a retrieved set and reformulate on hard queries; omitted (the default) ⇒ searchIterative runs a single, difficulty-gated pass and makes no provider call.
args.iterativeDifficultyThreshold?	number	Default difficulty-gate threshold for searchIterative (W-088). Omitted ⇒ the gate's built-in 0.5. Per-call difficultyThreshold overrides it.
args.iterativeMaxIterations?	number	Default total-pass cap for searchIterative. Default 3.
args.queryTransformer?	QueryTransformer	Query transformer for multi-query / HyDE retrieval (P2-3). When supplied, search(..., { multiQuery }) / { hyde } opt into one cheap LLM call to rewrite / hypothesize the query; omitted (the default) ⇒ those options are silent no-ops and search stays offline + single-shot.
args.reranker	ReRanker	-
args.searchDefaults?	SemanticSearchDefaults	Construction-time retrieval defaults (W-086) merged under every search(...) call - see SemanticSearchDefaults. Because the merge happens inside search(), the model-facing surfaces (fact_search, auto-recall, deep_recall) inherit them without any per-surface wiring; per-call options override key-by-key (so e.g. deep_recall's widen-pass expandHops still wins).
args.store	MemoryStoreAdapter	-
args.tracer	Tracer	-
args.trustWeights?	SalienceWeights	Weights for the rank-time trust discount (C5). Reuses the eviction-path SalienceWeights semantics; defaults to DEFAULT_SALIENCE_WEIGHTS.

Returns

SemanticMemory

Methods

forget()

forget(
   scope, 
   factId, 
reason?): Promise<void>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1310

Soft-delete a fact (kept for replay; never hard-deleted).

Parameters

Parameter	Type
scope	SessionScope
factId	string
reason?	string

Returns

Promise<void>

---

fuse()

fuse(
   query, 
   lists, 
options?): Promise<readonly MemoryHit<Fact>[]>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1348

Fuse multiple ranked lists outside of a search() call.

Parameters

Parameter	Type
query	string
lists	readonly readonly MemoryHit<Fact>[][]
options	{ signal?: AbortSignal; topK?: number; }
options.signal?	AbortSignal
options.topK?	number

Returns

Promise<readonly MemoryHit&lt;Fact&gt;[]>

---

get()

get(scope, factId): Promise<Fact | null>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1126

Lookup a single fact by id. Returns null for soft-deleted / missing.

Parameters

Parameter	Type
scope	SessionScope
factId	string

Returns

Promise&lt;Fact | null&gt;

---

history()

history(scope, factId): Promise<readonly Fact[]>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1156

Return the full bi-temporal supersede chain that factId belongs to, oldest → newest, including superseded / soft-deleted rows so callers can answer "how did this fact change over time". Requires a storage adapter that implements SemanticMemoryStoreExt.historyOf(...) - the default @graphorin/store-sqlite adapter wires this through. P0-2.

Parameters

Parameter	Type
scope	SessionScope
factId	string

Returns

Promise&lt;readonly Fact[]&gt;

Stable

---

neighbors()

neighbors(
   scope, 
   text, 
opts?): Promise<readonly MemoryHit<Fact>[]>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1117

Raw vector KNN neighbours for the consolidator's reconcile pre-filter (P0-3). Unlike search this skips FTS, reranking, and decay so the cosine scores survive intact (the conflict-pipeline zone thresholds are calibrated against them), and it includes quarantined facts so prior synthesized memories are visible to reconciliation. Returns [] when no embedder / vector adapter is configured - the consolidator then treats every candidate as a fresh add, degrading gracefully to the pre-reconcile behaviour.

Parameters

Parameter	Type
scope	SessionScope
text	string
opts	{ topK?: number; }
opts.topK?	number

Returns

Promise<readonly MemoryHit&lt;Fact&gt;[]>

Stable

---

purge()

purge(
   scope, 
   factId, 
reason?): Promise<void>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1329

Hard-delete a fact (GDPR path). Distinct from forget: the record is removed from storage entirely instead of soft-archived. Requires a storage adapter that implements SemanticMemoryStoreExt.purge(...) - the default @graphorin/store-sqlite adapter wires this through.

Parameters

Parameter	Type
scope	SessionScope
factId	string
reason?	string

Returns

Promise&lt;void&gt;

---

remember()

remember(
   scope, 
   input, 
options?): Promise<Fact>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:544

Persist a fact. Returns the stored record. Phase 10b routes every call through the multi-stage conflict resolution pipeline; the legacy straight-through path is reachable per-call via { pipeline: 'off' } (operators may disable the pipeline globally via createMemory({ conflictPipeline: { mode: 'off' } })).

Parameters

Parameter	Type
scope	SessionScope
input	FactInput
options	FactRememberOptions

Returns

Promise&lt;Fact&gt;

---

rememberWithDecision()

rememberWithDecision(
   scope, 
   input, 
options?): Promise<RememberOutcome>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:560

Like remember but returns the pipeline decision alongside the stored fact. Useful for callers that need to distinguish silent dedups (decision.kind === 'dedup') from fresh inserts.

Parameters

Parameter	Type
scope	SessionScope
input	FactInput
options	FactRememberOptions

Returns

Promise&lt;RememberOutcome&gt;

Stable

---

reranker()

reranker(): ReRanker;

Defined in: packages/memory/src/tiers/semantic-memory.ts:533

Currently active reranker.

Returns

ReRanker

---

search()

search(
   scope, 
   query, 
callOpts?): Promise<readonly MemoryHit<Fact>[]>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:773

Hybrid (vector + FTS5) search merged through the configured reranker.

Parameters

Parameter	Type
scope	SessionScope
query	string
callOpts	FactSearchOptions

Returns

Promise<readonly MemoryHit&lt;Fact&gt;[]>

---

searchIterative()

searchIterative(
   scope, 
   query, 
opts?): Promise<IterativeRecallResult>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1041

Gated, iterative ("deep") recall for hard queries (P2-4). A cheap local heuristic (assessQueryDifficulty) decides whether the query is even a loop candidate; simple lookups take exactly one search pass and make no provider call. For a query judged hard and with a grader configured (createMemory({ iterativeRetrieval })), the retrieved set is graded for sufficiency and, when weak, the query is reformulated and retrieved again - widening to one-hop graph expansion (expandHops: 1) on each reformulation pass - up to maxIterations (hard-capped at 5). When still insufficient it returns abstained: true so the caller can decline to answer instead of confabulating.

Without a grader (the offline default) this degrades to a single, difficulty-gated search and never calls a provider.

Parameters

Parameter	Type
scope	SessionScope
query	string
opts	IterativeSearchOptions

Returns

Promise&lt;IterativeRecallResult&gt;

Stable

---

setReranker()

setReranker(reranker): ReRanker;

Defined in: packages/memory/src/tiers/semantic-memory.ts:526

Replace the active reranker. Returns the previous instance.

Parameters

Parameter	Type
reranker	ReRanker

Returns

ReRanker

---

supersede()

supersede(
   scope, 
   oldId, 
   newInput, 
   reason?, 
   options?): Promise<{
  new: Fact;
  old: string;
}>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1270

Mark oldId superseded by a new fact. Returns the new record.

W-019 (security-first, knowledge-preserving): when the successor lands QUARANTINED (the default for extraction/synthesized provenance), the old ACTIVE fact's validity interval is NOT closed

• default recall keeps returning the old knowledge until the successor passes validate, which completes the closure. The link is recorded on the successor's supersedes field. With autoPromoteSynthesized (threaded from the consolidator's autoPromoteExtraction escape hatch) an injection-clean successor is active immediately and the interval closes right away - the pre-W-019 behaviour. Inverting the default (auto-activating the successor) would hand a MINJA attacker instant active memory via any text the reconciler classifies as an 'update'.

Parameters

Parameter	Type
scope	SessionScope
oldId	string
newInput	FactInput
reason?	string
options?	{ autoPromoteSynthesized?: boolean; }
options.autoPromoteSynthesized?	boolean

Returns

Promise<{ new: Fact; old: string; }>

---

validate()

validate(
   scope, 
   factId, 
   reason?, 
options?): Promise<void>;

Defined in: packages/memory/src/tiers/semantic-memory.ts:1196

Promote a quarantined fact to active (P1-4). The validation path that admits a synthesized memory into action-driving recall once a human (or trusted non-agent caller) has reviewed it. Writes a memory_history audit row. Requires a storage adapter that implements SemanticMemoryStoreExt.setStatus(...) - the default @graphorin/store-sqlite adapter wires this through.

MRET-3 / MST-1: promotion of a fact whose text still trips the offline injection heuristics is refused with QuarantinePromotionRefusedError - the model-facing fact_validate tool calls this with no force, so a poisoned memory can never be promoted by the agent itself (the one-turn fact_remember(poison) → fact_validate(id) chain is closed). An operator can override after review by passing { force: true } from a trusted (non-agent) context. Synthesized-but-clean writes (consolidator / reflection) promote normally.

Parameters

Parameter	Type
scope	SessionScope
factId	string
reason?	string
options?	{ force?: boolean; }
options.force?	boolean

Returns

Promise&lt;void&gt;

Stable

---

fuseRrf()

static fuseRrf<TRecord>(lists, k?): readonly MemoryHit<TRecord>[];

Defined in: packages/memory/src/tiers/semantic-memory.ts:1357

Pure-fusion helper - exposed for callers that already collected results.

Type Parameters

Type Parameter
TRecord extends Fact

Parameters

Parameter	Type	Default value
lists	readonly readonly MemoryHit<TRecord>[][]	undefined
k	number	60

Returns

readonly MemoryHit&lt;TRecord&gt;[]

---

fuseWeighted()

static fuseWeighted<TRecord>(
   lists, 
   weights, 
   k?): readonly MemoryHit<TRecord>[];

Defined in: packages/memory/src/tiers/semantic-memory.ts:1370

Pure weighted-fusion helper (X-2) - like SemanticMemory.fuseRrf but scales each list i's reciprocal-rank contribution by weights[i]. A missing / invalid entry defaults to 1, so equal or absent weights reproduce RRF.

Type Parameters

Type Parameter
TRecord extends Fact

Parameters

Parameter	Type	Default value
lists	readonly readonly MemoryHit<TRecord>[][]	undefined
weights	readonly number[] | undefined	undefined
k	number	60

Returns

readonly MemoryHit&lt;TRecord&gt;[]