klieo_memory_sqlite/
lib.rs

1#![deny(missing_docs)]
2#![deny(rust_2018_idioms)]
3#![deny(rustdoc::broken_intra_doc_links)]
4
5//! SQLite-backed implementations of the three memory traits in
6//! [`klieo_core::memory`].
7//!
8//! `MemorySqlite::open(path)` is the capability-shaped default — opens
9//! a SQLite file (or `":memory:"` for ephemeral), runs migrations for
10//! all three trait tables, defaults to [`DummyEmbedder`], and returns
11//! three `Arc<dyn …>` handles ready to drop into
12//! [`klieo_core::AgentContext`].
13//!
14//! For a caller-supplied [`Embedder`] (e.g. the `fastembed` feature's
15//! `FastEmbedEmbedder`), reach for [`MemorySqlite::new`] directly.
16//!
17//! # Quickstart
18//!
19//! ```no_run
20//! use klieo_memory_sqlite::MemorySqlite;
21//!
22//! async fn example() {
23//!     let mem = MemorySqlite::open(":memory:").await.unwrap();
24//!     // mem.short_term, mem.long_term, mem.episodic are
25//!     // Arc<dyn …> handles ready for AgentContext.
26//!     let _ = mem;
27//! }
28//! ```
29//!
30//! # Advanced wiring — custom embedder
31//!
32//! ```no_run
33//! use klieo_memory_sqlite::{MemorySqlite, DummyEmbedder};
34//! use std::sync::Arc;
35//!
36//! async fn example() {
37//!     let mem = MemorySqlite::new(":memory:", Arc::new(DummyEmbedder)).await.unwrap();
38//!     let _ = mem;
39//! }
40//! ```
41//!
42//! # Features
43//!
44//! - **Default** — three SQLite-backed memory traits + `Embedder`
45//!   trait with `DummyEmbedder` (zero-vector). Linear-scan recall.
46//! - **`fastembed`** — adds `FastEmbedEmbedder` (real CPU embeddings
47//!   via ONNX runtime). Heavy first compile; model auto-downloads
48//!   to OS cache dir on first call.
49//! - **`sqlite-vec`** — adds a vec0 virtual-table index on
50//!   `long_term_facts_vec`; `LongTermMemory::recall` uses k-NN MATCH
51//!   instead of linear scan.
52//! - **`test-utils`** — exposes `FakeEmbedder` for downstream test
53//!   deps.
54//!
55//! # Limitations
56//!
57//! - **Sync SQLite under blocking pool.** All trait methods spawn
58//!   `tokio::task::spawn_blocking` so they don't stall the async
59//!   runtime; throughput is bounded by the blocking-pool size.
60
61pub(crate) mod connection;
62
63pub mod embedder;
64pub use embedder::{DummyEmbedder, Embedder};
65
66#[cfg(any(test, feature = "test-utils"))]
67pub use embedder::FakeEmbedder;
68
69pub mod short_term;
70pub use short_term::SqliteShortTerm;
71
72pub mod episodic;
73pub use episodic::SqliteEpisodic;
74
75pub mod long_term;
76pub use long_term::SqliteLongTerm;
77
78pub mod factory;
79pub use factory::MemorySqlite;
80
81// `FastEmbedEmbedder` now lives in `klieo-embed-common`; re-exported here
82// so the `fastembed` feature stays source-stable for existing callers.
83#[cfg(feature = "fastembed")]
84pub use klieo_embed_common::{FastEmbedEmbedder, DEFAULT_DIM, DEFAULT_MODEL};
klieo_memory_sqlite/lib.rs

klieo_memory_sqlite/
lib.rs
