Struct ContextForge 

pub struct ContextForge { /* private fields */ }

The documented entry point for context-forge.

ContextForge wires together a TursoStorage backend, a TursoSearcher, and a ContextEngine behind a small, stable API surface. Advanced callers that need direct access to the underlying storage or searcher can construct those types directly and pass them to ContextEngine::new instead.

Implementations

impl ContextForge

pub fn builder(config: Config) -> ContextForgeBuilder

Create a builder for ContextForge.

Lexicon scoring is opt-in: by default the engine ranks on relevance (BM25, plus semantic when an embedding model is set), with no lexicon layer. Enable it with ContextForgeBuilder::with_default_english_scorer and/or ContextForgeBuilder::with_persona_scorer. Self::open is the lower-level path that likewise wires no scorer.

pub async fn open(config: Config) -> Result<Self>

Open (or create) the database at config.db_path, run any pending migrations, and build the engine.

Errors

Returns an error if the database cannot be opened or migrations fail.

pub async fn save( &self, content: &str, kind: &str, opts: &SaveOptions, ) -> Result<String>

Save a new entry. Returns the generated entry ID.

kind is a caller-defined classification (see kind for well-known values). Capacity enforcement (LRU eviction) is handled atomically by the storage layer.

Before persistence, content is passed through scrub_secrets using this instance’s ScrubConfig (see Config::scrub), redacting common credential formats with [REDACTED:<label>] placeholders. opts.metadata is stored verbatim and is not scrubbed — see SaveOptions::metadata.

Errors

Returns an error if content is empty or if the underlying storage write fails.

pub async fn save_batch( &self, items: &[(String, String, SaveOptions)], ) -> Result<Vec<String>>

Save many entries in one batch, committing the search index once for the whole batch instead of once per entry — much cheaper for bulk ingest.

Each item is (content, kind, options), handled exactly as save (content is scrubbed per item). Returns the generated ids in the same order as items.

Errors

Returns an error if any item’s content is empty or if the underlying storage write fails. On failure, entries written before the failure may remain persisted.

pub async fn distill_and_save( &self, transcript: &str, distiller: &dyn Distiller, opts: &SaveOptions, ) -> Result<Vec<String>>

Distill transcript into a summary and durable facts, then save them as separate entries sharing opts.scope and opts.session_id.

transcript is passed through scrub_secrets before it is sent to distiller (so secrets never reach a distillation endpoint), and the summary/facts produced are scrubbed again before persistence via the normal ContextForge::save path (defense in depth).

The summary is saved with kind::SUMMARY; each fact is saved with kind::FACT and metadata {"fact_kind": "<kind>", "source": "distill"}.

The distilled output is bounded before any of it is saved: at most MAX_FACTS facts are kept, each fact’s text is truncated to at most MAX_FACT_CHARS characters, and the summary is truncated to at most MAX_SUMMARY_CHARS characters. Excess facts and text beyond these limits are silently dropped or truncated, since they are untrusted model-generated content.

Returns the IDs of the saved entries: the summary’s ID first, followed by each fact’s ID in order.

Errors

Returns an error if distillation fails, or if any save fails.

pub async fn query( &self, query: &str, scope: Option<&str>, token_budget: usize, ) -> Result<Vec<ContextEntry>>

Assemble entries matching query that fit within token_budget.

scope = None searches every entry regardless of scope (global recall). scope = Some(s) restricts the search to entries whose scope equals s.

query is treated as natural-language text: it is split into alphanumeric terms which are OR-matched and ranked by bm25 relevance. FTS5 operator syntax (AND, OR, NEAR, prefix *, quoted phrases, column filters, etc.) is not interpreted — operator characters are treated as term separators, so arbitrary user text never produces a query syntax error. A query with no alphanumeric terms (empty or punctuation-only) returns an empty result set rather than an error. The special value MATCH_ALL_QUERY ("*") matches every entry.

Errors

Returns an error if the search or recency-weighting step fails.

pub async fn delete(&self, id: &str) -> Result<bool>

Delete a single entry by id. Returns true if an entry was removed.

Errors

Returns an error if the underlying storage delete fails.

pub async fn clear_scope(&self, scope: &str) -> Result<usize>

Remove all entries within a given scope. Returns the number of entries removed.

Errors

Returns an error if the underlying storage delete fails.

pub async fn clear_all(&self) -> Result<usize>

Remove all entries. Returns the number of entries removed.

Errors

Returns an error if the underlying storage delete fails.

pub async fn count(&self) -> Result<usize>

Return the total number of stored entries.

Errors

Returns an error if the underlying storage count fails.