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.

The builder always pre-seeds DefaultEnglishScorer so plain-English importance signals are active without any configuration. Use ContextForgeBuilder::with_persona_scorer to stack a domain-specific scorer on top. See also Self::open for the lower-level path that 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 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.