Crate context_forge 

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

This crate provides SQLite + FTS5 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;

let mut config = Config::default();
config.db_path = PathBuf::from(":memory:");

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

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

Async callers

This crate is synchronous by design — it performs blocking SQLite I/O and never spawns its own threads or runtime. Callers using an async runtime (e.g. Tokio) should wrap calls in spawn_blocking and share a single ContextForge instance behind an Arc:

use std::sync::Arc;

let cf = Arc::new(ContextForge::open(config)?);

// in an async context:
let hits = tokio::task::spawn_blocking({
    let cf = cf.clone();
    move || cf.query("deploy failure", Some("discord:thread:42"), 2048)
}).await??;

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 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 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::SqliteSearcher;

pub use storage::SqliteStorage;

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.

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.

scrub

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

session

Session grouping helpers (group_entries_by_session, SessionGroup).

storage

SQLite-backed storage and search implementations. All SQL lives here.

traits

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

Structs

ContextForge

The documented entry point for context-forge.