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 error;
28pub mod importance;
29pub mod offdevice_hook;
30pub mod ops;
31pub mod provider;
32pub mod query;
33pub mod session;
34pub mod summarizer;
35pub mod write_hook;
36
37// Convenient re-exports — the symbols every caller will name.
38pub use basic::BasicMemoryProvider;
39pub use chunk::{ChunkKind, ChunkSource, MemoryChunk, MemoryTier, NewMemoryChunk};
40pub use error::{MemoryError, Result};
41pub use importance::score as score_importance;
42pub use offdevice_hook::{
43 ClosureOffdeviceHook, OffdeviceCallDescriptor, OffdeviceCallHook, OffdeviceDecision,
44};
45pub use ops::{
46 AccessEntry, AgingReport, EvictionEntry, EvictionReason, ExportBundle, ExportFilter,
47 MemoryStats, PurgeReport, ReEmbedReport,
48};
49pub use provider::MemoryProvider;
50pub use query::{CallerScope, MemoryPredicate, MemoryQuery, RetrievalProfile};
51pub use session::{MemorySession, NewMemorySession, SessionFilter, SessionOutcome};
52pub use summarizer::{
53 MockSummarizer, MockSummaryCall, Summarizer, SummarizerError, SummarizerResult, SummaryContext,
54};
55pub use write_hook::{ClosureHook, MemoryWriteHook, WriteDecision};