cel-memory

Backend-agnostic memory traits and value types for AI agents.

cel-memory is the contract between an agent and an arbitrary persistence layer. The trait is small enough to drop in your own backend (file, SQLite, Redis, Mem0, Hindsight, etc.) without changing agent code. The companion cel-memory-sqlite crate provides a local SQLite implementation.

Purpose

Use cel-memory when agent code needs durable, scoped retrieval but should not depend on a storage engine. Callers depend on MemoryProvider; backends decide how chunks are stored, embedded, indexed, summarized, and aged. Attach a Summarizer with [BasicMemoryProvider::with_summarizer] to enable session summaries and rollups.

Status: v0.2.0 on crates.io — the MemoryProvider trait surface is stable. Two implementations ship against it: BasicMemoryProvider (in-crate, in-memory reference) and cel-memory-sqlite (SQLite + vector + FTS, hybrid retrieval). LLM summarizers live in cel-summarizer.

What's Included

• MemoryProvider trait — async interface every backend implements.
• Value types: MemoryChunk, ChunkKind, MemoryTier, MemoryQuery, MemorySession, etc.
• BasicMemoryProvider — in-memory reference impl. Useful for tests and as the conformance reference for new backends.
• MemoryWriteHook trait — governance hook every backend should consult before persisting (lets a rule engine redact or veto writes).
• MemoryError — self-contained error type.

Out Of Scope

• Storage. See cel-memory-sqlite for SQLite + vector retrieval.
• Embedding runtimes. The [Embedder] trait is defined here; ONNX/fastembed backends ship in companion crates.
• LLM-call retrieval logic. See cel-brief for "retrieve memory + assemble into an LLM prompt."

Example

use cel_memory::{
    BasicMemoryProvider, ChunkKind, ChunkSource, MemoryProvider,
    NewMemoryChunk, MemoryQuery, CallerScope, RetrievalProfile,
};
use serde_json::json;

let memory = BasicMemoryProvider::new();

memory.write(NewMemoryChunk {
    kind: ChunkKind::Chat,
    source: ChunkSource::Embedded,
    caller_id: "my-agent".into(),
    content: "User prefers dry-run mode".into(),
    session_id: None,
    project_root: None,
    metadata: json!(null),
    importance: None,
    shareable: false,
    pinned: false,
}).await?;

let hits = memory.retrieve(MemoryQuery {
    text: "dry-run".into(),
    caller_scope: CallerScope::Own,
    caller_id: "my-agent".into(),
    k: 5,
    // ...
    profile: RetrievalProfile::AgentChatTurn,
    kinds: None, since: None, until: None,
    session_id: None, project_root_prefix: None,
    include_rollups: true, min_importance: None,
}).await?;

Runnable examples:

cargo run --example basic
cargo run --example backend_swap
cargo run --example write_hook
cargo run --example custom_provider

• basic uses the in-memory reference provider end to end.
• backend_swap shows application code written against MemoryProvider.
• write_hook shows policy/redaction before persistence.
• custom_provider shows a provider wrapper that implements the trait.

Implementing another backend

Storage engines (PostgreSQL, DuckDB, Redis, hosted vector DBs, etc.) belong in separate crates that implement MemoryProvider. Do not add drivers or SQL to this repo.

See BACKENDS.md for a phased implementation guide, schema mapping from cel-memory-sqlite, retrieval expectations, and conformance testing. Published community backends can be listed there and in the table below.

Upgrading from 0.1.x

0.2.0 moves Embedder into this crate and removes the ChunkSource::Cortex alias. See the 0.2 migration guide.

Comparable libraries

License

Apache-2.0