context-forge 0.5.0-beta.1

Local-first persistent memory for LLM applications - SQLite + FTS5 BM25 retrieval, recency decay, token-budget context assembly, secret scrubbing, and optional local-LLM distillation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

use crate::entry::{ContextEntry, ScoredEntry};
use crate::error::Error;

/// Result type alias for crate operations.
pub type Result<T> = std::result::Result<T, Error>;

/// Trait for persisting and retrieving context entries.
///
/// Implementations must be thread-safe (`Send + Sync`) to support
/// concurrent access from multiple worker threads.
pub trait ContextStorage: Send + Sync {
    /// Persist a single entry.
    ///
    /// # Security
    ///
    /// Implementations persist `entry.content` verbatim — secret scrubbing
    /// happens only in [`ContextForge::save`](crate::ContextForge::save).
    /// Callers writing through this trait directly are responsible for
    /// scrubbing first (see [`scrub_secrets`](crate::scrub_secrets)).
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying storage write fails.
    fn save(&self, entry: &ContextEntry) -> Result<()>;

    /// Return the top-k entries (most recent or highest priority).
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying storage read fails.
    fn get_top_k(&self, k: usize) -> Result<Vec<ContextEntry>>;

    /// Return every stored entry.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying storage read fails.
    fn get_all(&self) -> Result<Vec<ContextEntry>>;

    /// Delete an entry by id. Returns `true` if an entry was removed.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying storage delete fails.
    fn delete(&self, id: &str) -> Result<bool>;

    /// Remove all entries. Returns the number of entries removed.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying storage delete fails.
    fn clear(&self) -> 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.
    fn clear_scope(&self, scope: &str) -> Result<usize>;

    /// Return the total number of stored entries.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying storage read fails.
    fn count(&self) -> Result<usize>;
}

/// Trait for searching context entries by relevance.
///
/// Implementations must be thread-safe (`Send + Sync`) to support
/// concurrent access from multiple worker threads.
pub trait Searcher: Send + Sync {
    /// Search for entries matching `query`, optionally restricted to `scope`,
    /// returning at most `limit` results ordered by descending relevance score.
    ///
    /// `scope = None` searches every entry regardless of scope (global recall).
    /// `scope = Some(s)` restricts results to entries whose `scope` equals `s`.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying search fails.
    fn search(&self, query: &str, scope: Option<&str>, limit: usize) -> Result<Vec<ScoredEntry>>;
}