cel_memory/lib.rs
1//! cel-memory — the durable cross-turn memory contract for AI agents.
2//!
3//! This crate answers one question: **what should persist across turns?** It
4//! owns the memory *contract* — the [`MemoryProvider`] trait plus the value
5//! types every backend and caller share (chunks, sessions, queries, retrieval
6//! profiles, caller scopes, write hooks, summaries, rollups, aging, export).
7//! Storage backends implement the trait; callers depend only on it.
8//!
9//! The crate is deliberately narrow. It does **not** observe live environment
10//! state and it does **not** assemble per-turn LLM prompts. `cel-memory` owns
11//! persistence only.
12//!
13//! [`BasicMemoryProvider`] is the in-crate reference implementation — real
14//! bodies for [`MemoryProvider::retrieve`], [`MemoryProvider::write`], session
15//! lifecycle, export, stats, summarization, rollups, and re-embed metadata
16//! updates when a [`Summarizer`] is attached; no-ops for
17//! [`MemoryProvider::update_importance`] and [`MemoryProvider::supersede`].
18//! A full storage backend (e.g. [`cel-memory-sqlite`](https://crates.io/crates/cel-memory-sqlite))
19//! implements the same trait in a separate crate — see
20//! [BACKENDS.md](https://github.com/dimpagk92/cel-memory/blob/main/BACKENDS.md).
21
22#![deny(missing_docs)]
23#![warn(rust_2018_idioms)]
24
25pub mod basic;
26pub mod chunk;
27pub mod conformance;
28pub mod embedder;
29pub mod error;
30pub mod importance;
31pub mod offdevice_hook;
32pub mod ops;
33pub mod provider;
34pub mod query;
35pub mod session;
36pub mod summarizer;
37pub mod write_hook;
38
39// Convenient re-exports — the symbols every caller will name.
40pub use basic::BasicMemoryProvider;
41pub use chunk::{ChunkKind, ChunkSource, MemoryChunk, MemoryTier, NewMemoryChunk};
42pub use conformance::assert_write_get_stats;
43pub use embedder::{Embedder, EmbedderError, EmbedderResult, MockEmbedder};
44pub use error::{MemoryError, Result};
45pub use importance::score as score_importance;
46pub use offdevice_hook::{
47 ClosureOffdeviceHook, OffdeviceCallDescriptor, OffdeviceCallHook, OffdeviceDecision,
48};
49pub use ops::{
50 AccessEntry, AgingReport, EvictionEntry, EvictionReason, ExportBundle, ExportFilter,
51 MemoryStats, PurgeReport, ReEmbedReport,
52};
53pub use provider::MemoryProvider;
54pub use query::{CallerScope, MemoryPredicate, MemoryQuery, RetrievalProfile};
55pub use session::{MemorySession, NewMemorySession, SessionFilter, SessionOutcome};
56pub use summarizer::{
57 MockSummarizer, MockSummaryCall, Summarizer, SummarizerError, SummarizerResult, SummaryContext,
58};
59pub use write_hook::{ClosureHook, MemoryWriteHook, WriteDecision};