pub struct ContextForge { /* private fields */ }Expand description
The documented entry point for context-forge.
ContextForge wires together a SqliteStorage backend, a
SqliteSearcher, 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§
Source§impl ContextForge
impl ContextForge
Sourcepub fn open(config: Config) -> Result<Self>
pub 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, the connection pool cannot be built, or migrations fail.
Sourcepub fn save(
&self,
content: &str,
kind: &str,
opts: &SaveOptions,
) -> Result<String>
pub 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.
Sourcepub fn distill_and_save(
&self,
transcript: &str,
distiller: &dyn Distiller,
opts: &SaveOptions,
) -> Result<Vec<String>>
pub 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.
Sourcepub fn query(
&self,
query: &str,
scope: Option<&str>,
token_budget: usize,
) -> Result<Vec<ContextEntry>>
pub 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.
Sourcepub fn delete(&self, id: &str) -> Result<bool>
pub 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.
Sourcepub fn clear_scope(&self, scope: &str) -> Result<usize>
pub 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.