klieo-memory-sqlite 3.2.0

#![deny(missing_docs)]
#![deny(rust_2018_idioms)]
#![deny(rustdoc::broken_intra_doc_links)]

//! SQLite-backed implementations of the three memory traits in
//! [`klieo_core::memory`].
//!
//! `MemorySqlite::open(path)` is the capability-shaped default — opens
//! a SQLite file (or `":memory:"` for ephemeral), runs migrations for
//! all three trait tables, defaults to [`DummyEmbedder`], and returns
//! three `Arc<dyn …>` handles ready to drop into
//! [`klieo_core::AgentContext`].
//!
//! For a caller-supplied [`Embedder`] (e.g. the `fastembed` feature's
//! `FastEmbedEmbedder`), reach for [`MemorySqlite::new`] directly.
//!
//! # Quickstart
//!
//! ```no_run
//! use klieo_memory_sqlite::MemorySqlite;
//!
//! async fn example() {
//!     let mem = MemorySqlite::open(":memory:").await.unwrap();
//!     // mem.short_term, mem.long_term, mem.episodic are
//!     // Arc<dyn …> handles ready for AgentContext.
//!     let _ = mem;
//! }
//! ```
//!
//! # Advanced wiring — custom embedder
//!
//! ```no_run
//! use klieo_memory_sqlite::{MemorySqlite, DummyEmbedder};
//! use std::sync::Arc;
//!
//! async fn example() {
//!     let mem = MemorySqlite::new(":memory:", Arc::new(DummyEmbedder)).await.unwrap();
//!     let _ = mem;
//! }
//! ```
//!
//! # Features
//!
//! - **Default** — three SQLite-backed memory traits + `Embedder`
//!   trait with `DummyEmbedder` (zero-vector). Linear-scan recall.
//! - **`fastembed`** — adds `FastEmbedEmbedder` (real CPU embeddings
//!   via ONNX runtime). Heavy first compile; model auto-downloads
//!   to OS cache dir on first call.
//! - **`sqlite-vec`** — adds a vec0 virtual-table index on
//!   `long_term_facts_vec`; `LongTermMemory::recall` uses k-NN MATCH
//!   instead of linear scan.
//! - **`test-utils`** — exposes `FakeEmbedder` for downstream test
//!   deps.
//!
//! # Limitations
//!
//! - **Sync SQLite under blocking pool.** All trait methods spawn
//!   `tokio::task::spawn_blocking` so they don't stall the async
//!   runtime; throughput is bounded by the blocking-pool size.

pub(crate) mod connection;

pub mod embedder;
pub use embedder::{DummyEmbedder, Embedder};

#[cfg(any(test, feature = "test-utils"))]
pub use embedder::FakeEmbedder;

pub mod short_term;
pub use short_term::SqliteShortTerm;

pub mod episodic;
pub use episodic::SqliteEpisodic;

pub mod long_term;
pub use long_term::SqliteLongTerm;

pub mod factory;
pub use factory::MemorySqlite;

// `FastEmbedEmbedder` now lives in `klieo-embed-common`; re-exported here
// so the `fastembed` feature stays source-stable for existing callers.
#[cfg(feature = "fastembed")]
pub use klieo_embed_common::{FastEmbedEmbedder, DEFAULT_DIM, DEFAULT_MODEL};