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 device/world
10//! state — that is `cel-cortex`'s job ("what is true now?") — and it does
11//! **not** assemble per-turn LLM prompts — that is `cel-brief`'s job ("what
12//! should the model see this turn?"). cel-memory owns persistence only.
13//!
14//! Cellar is the motivating consumer: its embedded agent runtime, NL rule
15//! compiler, `cel_act` gateway, rule-matcher post-fire hook, and Activity /
16//! Memory tabs all compile against this trait. But nothing here depends on
17//! Cellar — the crate is reusable memory infrastructure for any agent runtime.
18//!
19//! [`BasicMemoryProvider`] is the in-crate reference implementation — real
20//! bodies for [`MemoryProvider::retrieve`], [`MemoryProvider::write`], session
21//! lifecycle, simple deletes, export, and stats; `Err(NotImplemented)` for
22//! summarization, rollups, and re-embed; no-ops for `update_importance` and
23//! `supersede`. A full storage backend (e.g. the `cel-memory-sqlite` crate)
24//! drops in behind the same trait without caller churn.
25
26#![deny(missing_docs)]
27#![warn(rust_2018_idioms)]
28
29pub mod basic;
30pub mod chunk;
31pub mod error;
32pub mod importance;
33pub mod offdevice_hook;
34pub mod ops;
35pub mod provider;
36pub mod query;
37pub mod session;
38pub mod summarizer;
39pub mod write_hook;
40
41// Convenient re-exports — the symbols every caller will name.
42pub use basic::BasicMemoryProvider;
43pub use chunk::{ChunkKind, ChunkSource, MemoryChunk, MemoryTier, NewMemoryChunk};
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};