Creates tables and runs migrations. Idempotent. Leases →
drain()
Promise<void>
Waits for background jobs in auto mode, and for the removal drain that setup() started when drainExternalDeletionsOnSetup is on
clearVectorCache()
void
Frees cached parsed vectors
syncSearchIndex(entityId?)
Promise<void>
Re-syncs the keyword index after upsertGraph. With no argument, it also retries a failed FTS5 init. It also calls the removal hook for the ids upsertGraph superseded, which can take up to deletionHookTimeoutMs per id. It never drains an entity’s wider backlog.
body: 'Kurt wants PRs merged with merge commits, never squashed.',
tags: ['git'],
okf_type: 'Preference',
valid_from: Date.parse('2026-03-01'),
});
fact.id; // 'fact_…'
Stores one mutable fact in one transaction, with no text-generation (LLM) call, and returns the stored row (WikiFact, with timestamps, defaults, isStale and trustTier). Use it when the host already knows the fact. To replace a fact, use supersede() so history is kept.
Field
Type
Default
title
string, required, non-empty after trim
body
string, required ('' allowed)
tags
string[]
[]
confidence
'certain' | 'inferred' | 'tentative'
'certain'
source_type
'user_stated' | 'user_confirmed'
'user_stated'
okf_type
string | null
null
valid_from
epoch ms, finite and >= 0
since created_at
Validation. Throws TypeError before anything is written. An explicit null for confidence or source_type is rejected; omit the field to take the default. Nothing is clipped; length limits are the host’s.
okf_type. Follows the upsertGraph rule: the manifest’s canonical slug when known, WikiStrictOntologyViolation under strict mode otherwise, and null otherwise.
Embedding. When llmProvider.embed is configured it awaits one embedding call; failures surface as embedding_failed with operation: 'remember', not a throw. Without embed the fact is keyword-only, and getPendingMaintenance().reembedPending picks it up once an embed exists.
No maintenance. Never starts the librarian or heal and writes no event, in 'auto' and 'deferred' mode alike.
Not idempotent. Two identical calls store two facts. Hosts that expose retries own the idempotency key.
Transactions. Opens its own transaction. Do not call it inside withTransactionAsync.
listSourceRefs() returns one row per live sourceRef: soft-deleted rows and rows with a null
sourceRef are excluded. sourceHash and lastIngestedAt come from the most recently updated
live row for that sourceRef, and factCount counts the live rows.
jobs accepts 'librarian', 'heal', 'reembed', 'externalDeletions' (default all). externalDeletions is { confirmed, pending }. It runs first and doesn’t use tokenBudget. It awaits the setup() removal drain first, when one was started.
