Struct Database 

pub struct Database { /* private fields */ }

A clonable, thread-safe handle to one database file. See the module docs for the concurrency model.

Implementations

impl Database

pub fn open( path: impl Into<PathBuf>, cfg: Config, ) -> Result<(Self, OpenReport), HostError>

Opens path with every knob at its default and no embedder.

pub fn open_readonly( path: impl Into<PathBuf>, cfg: Config, ) -> Result<ReadOnlyDatabase, HostError>

Opens path read-only over a memory-mapped snapshot: the engine borrows the mapped pages instead of copying the file into RAM, so a large read-mostly database residents only the pages recall/get touch. Requires a checkpointed database (empty journal) and takes a shared lock (N readers or one writer). See ReadOnlyDatabase.

Errors

HostError::Locked, HostError::NeedsCheckpoint, HostError::Io, HostError::Engine — see ReadOnlyDatabase::open semantics.

pub fn builder(cfg: Config) -> DatabaseBuilder

Starts a configured open (knobs).

pub fn remember( &self, input: RememberInput<'_>, ) -> Result<RememberOutcome, HostError>

Remembers a fact. Without an explicit vector and with an embedder configured, the text is embedded first — outside the lock.

pub fn remember_many( &self, inputs: Vec<RememberInput<'_>>, ) -> Result<Vec<RememberOutcome>, HostError>

Remembers a batch of facts in one shot — the bulk-write path (CLI import). Equivalent to remember on each input in order, but far cheaper for a batch: the texts that need embedding are embedded together in one embedder round-trip (outside the lock), and all facts are written under one write-guard with one post-mutation policy pass — instead of N HTTP calls and N critical sections.

Inputs that already carry a vector are not re-embedded. Chunking is the caller’s job: this writes the whole slice it is given, so a caller that needs bounded memory / a bounded HTTP body passes fixed-size batches (CLI import streams the file in --batch-sized slices).

Fail-fast: the first engine error returns Err; the facts written before it stay written (exactly as separate remembers — the journal replay is idempotent, so a retried bulk load is safe). Returns one RememberOutcome per input, in order.

pub fn recall(&self, q: RecallQuery<'_>) -> Result<RecallResult, HostError>

Runs a recall. With a text, no vector and an embedder configured, the query text is embedded first — outside the lock.

pub fn revise( &self, target: FactId, input: RememberInput<'_>, ) -> Result<RememberOutcome, HostError>

Revises target (same auto-embedding rule as remember).

pub fn forget(&self, now: u64, id: FactId) -> Result<bool, HostError>

Tombstones a fact.

pub fn link(&self, input: LinkInput<'_>) -> Result<(), HostError>

Upserts a typed edge.

pub fn get(&self, id: FactId) -> Option<FactSnapshot>

An owned copy of one fact, or None for unknown/tombstoned ids.

pub fn stats(&self) -> Stats

Engine size counters.

pub fn export(&self) -> Vec<ExportedFact>

Dumps the currently-open facts for a human-readable backup See ExportedFact. Collects the whole set; for a large database prefer export_each, which streams.

pub fn export_each(&self, f: impl FnMut(ExportedFact))

Streams the currently-open facts, calling f once per fact under the read guard — the whole dump is never materialized, so a huge database exports without a RAM spike (CLI export writes each line straight out). See ExportedFact.

pub fn maintain(&self, now: u64) -> Result<MaintainReport, HostError>

Runs a maintenance pass now (purge, compaction, HNSW build past the threshold — for the cost model).

Disk-first (milestone H): the compacted image is written by streaming the two big pools (vectors, text) through temp files and then re-mapped, so peak RAM tracks the record count (metadata + graph), not the image size — a database larger than RAM can be maintained. It writes a fresh snapshot and clears the journal (like a checkpoint). The optional auto-maintain policy (maintain_every_forgets) still runs in RAM inline — it is for databases that fit.

The report’s byte counts are the on-disk image size before and after.

pub fn checkpoint(&self, now: u64) -> Result<(), HostError>

Writes a full snapshot and clears the journal now (re-mapping the fresh file — see Database::resnapshot).

pub fn verify(&self) -> Result<(), HostError>

Runs the on-demand integrity check — the equivalent of SQLite’s integrity_check. An open validates only the metadata, so the large byte pools stay non-resident on an mmap’d base; this sweeps them (text UTF-8, vector self-consistency and the fact↔slot bijection) and reports any latent corruption. Skipping it is safe — the accessors never panic on bad bytes; verify only turns corruption into an explicit error.

Errors

HostError::Engine wrapping Error::Corrupt for the first inconsistency found.

pub fn recover( src: impl AsRef<Path>, dst: impl AsRef<Path>, cfg: Config, now: u64, ) -> Result<RecoverReport, HostError>

Salvages a content-corrupt database (Tier 2): opens src, drops the facts that fail the per-fact content checks (verify’s predicate), compacts the survivors and their indexes, and writes a clean image to dst. src on disk is left untouched — the evidence is preserved.

It is disk-first (milestone H): src is opened as an mmap overlay (its pages are reclaimable) and the compacted image is written by streaming the two big pools (vectors, text) through temp files, so peak RAM tracks the record count (metadata + HNSW graph), not the image size. A database far larger than RAM can be recovered, as long as its graph fits.

This handles content corruption (bad text bytes, a broken fact↔slot vector bijection). Structural damage — a snapshot that will not parse — is not salvageable here: src fails to open and recover returns the engine’s typed error; restore from a backup instead (Tier 0).

Errors

HostError::Locked if src or dst is owned elsewhere; HostError::Engine if src will not parse (structural corruption) or dst equals src; HostError::Io for filesystem failures.

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Database

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Summary only — the contents are the user’s memory.