Graphorin API reference v0.4.0
Graphorin API reference / @graphorin/memory / / SemanticMemory
Class: SemanticMemory
Defined in: packages/memory/src/tiers/semantic-memory.ts:282
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:295
Parameters
| Parameter | Type | Description |
|---|---|---|
args | { conflictPipeline?: ConflictPipeline; contextualRetrieval?: "off" | "late-chunk"; embedder: | EmbedderProvider | null; embedderIdProvider: () => string | null; entityResolver?: EntityResolver; grader?: RetrievalGrader; iterativeMaxIterations?: number; queryTransformer?: QueryTransformer; reranker: ReRanker; store: MemoryStoreAdapter; tracer: Tracer; } | - |
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.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.store | MemoryStoreAdapter | - |
args.tracer | Tracer | - |
Returns
SemanticMemory
Methods
forget()
forget(
scope,
factId,
reason?): Promise<void>;Defined in: packages/memory/src/tiers/semantic-memory.ts:895
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:933
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<Fact>[]>
get()
get(scope, factId): Promise<Fact | null>;Defined in: packages/memory/src/tiers/semantic-memory.ts:786
Lookup a single fact by id. Returns null for soft-deleted / missing.
Parameters
| Parameter | Type |
|---|---|
scope | SessionScope |
factId | string |
Returns
Promise<Fact | null>
history()
history(scope, factId): Promise<readonly Fact[]>;Defined in: packages/memory/src/tiers/semantic-memory.ts:816
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<readonly Fact[]>
Stable
neighbors()
neighbors(
scope,
text,
opts?): Promise<readonly MemoryHit<Fact>[]>;Defined in: packages/memory/src/tiers/semantic-memory.ts:777
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<Fact>[]>
Stable
purge()
purge(
scope,
factId,
reason?): Promise<void>;Defined in: packages/memory/src/tiers/semantic-memory.ts:914
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<void>
remember()
remember(
scope,
input,
options?): Promise<Fact>;Defined in: packages/memory/src/tiers/semantic-memory.ts:370
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<Fact>
rememberWithDecision()
rememberWithDecision(
scope,
input,
options?): Promise<RememberOutcome>;Defined in: packages/memory/src/tiers/semantic-memory.ts:386
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<RememberOutcome>
Stable
reranker()
reranker(): ReRanker;Defined in: packages/memory/src/tiers/semantic-memory.ts:359
Currently active reranker.
Returns
search()
search(
scope,
query,
opts?): Promise<readonly MemoryHit<Fact>[]>;Defined in: packages/memory/src/tiers/semantic-memory.ts:573
Hybrid (vector + FTS5) search merged through the configured reranker.
Parameters
| Parameter | Type |
|---|---|
scope | SessionScope |
query | string |
opts | FactSearchOptions |
Returns
Promise<readonly MemoryHit<Fact>[]>
searchIterative()
searchIterative(
scope,
query,
opts?): Promise<IterativeRecallResult>;Defined in: packages/memory/src/tiers/semantic-memory.ts:713
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<IterativeRecallResult>
Stable
setReranker()
setReranker(reranker): ReRanker;Defined in: packages/memory/src/tiers/semantic-memory.ts:352
Replace the active reranker. Returns the previous instance.
Parameters
| Parameter | Type |
|---|---|
reranker | ReRanker |
Returns
supersede()
supersede(
scope,
oldId,
newInput,
reason?): Promise<{
new: Fact;
old: string;
}>;Defined in: packages/memory/src/tiers/semantic-memory.ts:866
Mark oldId superseded by a new fact. Returns the new record.
Parameters
| Parameter | Type |
|---|---|
scope | SessionScope |
oldId | string |
newInput | FactInput |
reason? | string |
Returns
Promise<{ new: Fact; old: string; }>
validate()
validate(
scope,
factId,
reason?): Promise<void>;Defined in: packages/memory/src/tiers/semantic-memory.ts:847
Promote a quarantined fact to active (P1-4). The validation path that admits a synthesized / injection-flagged 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.
Parameters
| Parameter | Type |
|---|---|
scope | SessionScope |
factId | string |
reason? | string |
Returns
Promise<void>
Stable
fuseRrf()
static fuseRrf<TRecord>(lists, k?): readonly MemoryHit<TRecord>[];Defined in: packages/memory/src/tiers/semantic-memory.ts:942
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<TRecord>[]
fuseWeighted()
static fuseWeighted<TRecord>(
lists,
weights,
k?): readonly MemoryHit<TRecord>[];Defined in: packages/memory/src/tiers/semantic-memory.ts:955
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<TRecord>[]