Crate context_forge 

context-forge — a local-first persistent memory library for LLM applications.

This crate provides turso + Tantivy BM25 retrieval, recency-decay scoring, and token-budget-aware context assembly with no network calls. It is intended to be embedded in larger applications (CLI tools, bots, agent runtimes) that need durable, searchable memory.

Quick start

use context_forge::{kind, ContextForge, Config, SaveOptions};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), context_forge::Error> {
    let mut config = Config::default();
    config.db_path = PathBuf::from(":memory:");

    let cf = ContextForge::open(config).await?;
    cf.save("the deploy failure was caused by a missing env var", kind::SNAPSHOT, &SaveOptions::default()).await?;

    let hits = cf.query("deploy failure", None, 2048).await?;
    assert_eq!(hits.len(), 1);
    Ok(())
}

Security

Retrieved entries are untrusted text. Content persisted from past conversations may contain adversarial instructions (stored prompt injection) — whatever was saved into the store, including text that originated from another user or from a tool’s output, comes back out verbatim on ContextForge::query (aside from save-time secret scrubbing, see below).

Callers MUST present retrieved memory to models as quoted data (e.g. inside a fenced or otherwise clearly delimited context block labeled as history), never as system-level instructions, and MUST NOT execute or evaluate anything found in it.

Save-time secret scrubbing

ContextForge::save applies scrub_secrets to content before it is persisted, using the ScrubConfig supplied in Config::scrub. This redacts common credential formats (cloud provider keys, API tokens, private key blocks, JWTs, bearer tokens) with [REDACTED:<label>] placeholders so they never reach the database or the search index. Scrubbing is on by default and can be disabled via Config { scrub: ScrubConfig { enabled: false }, .. } — this is an explicit, non-silent opt-out.

Note that SaveOptions::metadata is not scrubbed (see its docs).

Re-exports

pub use builder::ContextForgeBuilder;

pub use config::Config;

pub use config::EvictionPolicy;

pub use distill::merge_distilled;

pub use distill::split_on_budget;

pub use distill::ChunkingDistiller;

pub use distill::DistilledMemory;

pub use distill::Distiller;

pub use distill::Fact;

pub use distill::FactKind;

pub use distill::ReduceStrategy;

pub use engine::ContextEngine;

pub use engine::SaveOptions;

pub use engine::MATCH_ALL_QUERY;

pub use entry::kind;

pub use entry::ContextEntry;

pub use entry::ScoredEntry;

pub use error::Error;

pub use lexicon::bootstrap_prompt;

pub use lexicon::CompositeLexiconScorer;

pub use lexicon::ConfigLexiconScorer;

pub use lexicon::DefaultEnglishScorer;

pub use lexicon::LexiconAppender;

pub use lexicon::LexiconConfig;

pub use lexicon::LexiconPatterns;

pub use lexicon::LexiconProposal;

pub use lexicon::LexiconScorer;

pub use scrub::scrub_secrets;

pub use scrub::ScrubConfig;

pub use session::group_entries_by_session;

pub use session::SessionGroup;

pub use storage::open_storage;

pub use storage::TursoSearcher;

pub use storage::TursoStorage;

pub use traits::ContextStorage;

pub use traits::Result;

pub use traits::Searcher;

Modules

analysis

Importance-detection pipeline (tokenizer, lexicon, scoring). Pure computation, no I/O. Enabled by the analysis feature (default). Text analysis primitives for importance detection.

builder

ContextForgeBuilder — the opinionated construction path for ContextForge. ContextForgeBuilder — opinionated construction path for crate::ContextForge.

config

Engine and scrub configuration types (Config, EvictionPolicy, ScrubConfig).

distill

Local-LLM distillation trait and the optional distill-http implementation. Distillation: turning a raw conversation transcript into durable memory.

engine

ContextEngine: search, recency decay, and token-budget assembly. Core business logic: assembly, scoring, and snapshot management.

entry

ContextEntry, ScoredEntry, and the kind constants module.

error

The crate’s Error type. Crate-wide error type.

lexicon

Lexicon-based importance scoring — LexiconScorer trait, ConfigLexiconScorer, DefaultEnglishScorer, CompositeLexiconScorer, LexiconAppender, and LexiconProposal. Lexicon-based importance scoring.

scrub

Save-time secret scrubbing (scrub_secrets, ScrubConfig). Secret scrubbing applied to entry content before persistence.

semantic

Dense-vector embedding abstraction for semantic search.

session

Session grouping helpers (group_entries_by_session, SessionGroup).

storage

Turso-backed storage and search implementations.

traits

ContextStorage and Searcher traits, and the crate’s Result alias.

Structs

ContextForge

The documented entry point for context-forge.