# Memory

`cel-memory` answers:

> What should persist across agent turns, and how does agent code avoid coupling to one storage backend?

## Crates

| Crate | Role |
|---|---|
| `cel-memory` | Trait, value types, `Embedder`, sessions, retrieval queries, write hooks, `Summarizer` trait |
| `cel-memory-sqlite` | SQLite + vector + FTS implementation of the trait |
| `cel-summarizer` | LLM-backed `Summarizer` implementations (Anthropic + Ollama) |

Published at **0.2.0**. See [../migration-0.2.md](../migration-0.2.md) when upgrading from 0.1.x.

## Core Types

- `MemoryProvider` — async interface every backend implements.
- `MemoryChunk` / `NewMemoryChunk` — persisted units of memory.
- `MemorySession` / `NewMemorySession` — run or conversation scopes.
- `MemoryQuery` — retrieval request.
- `RetrievalProfile` — retrieval mode for the caller's intent.
- `MemoryWriteHook` — governance hook for redaction or veto before persistence.
- `Embedder` / `MockEmbedder` — embedding seam (defined in `cel-memory` since 0.2.0).
- `Summarizer` — LLM synthesis seam; production impls in [`cel-summarizer`](https://crates.io/crates/cel-summarizer).

## Why It Exists

Agent runtimes should depend on the memory contract, not a database:

```text
agent runtime → MemoryProvider → BasicMemoryProvider
                              → SqliteMemoryProvider
                              → your backend
```

That keeps local-first use, test doubles, and production backends swappable.

## Examples

In-memory reference provider:

```sh
cargo run -p cel-memory --example basic
```

SQLite backend:

```sh
cargo run -p cel-memory-sqlite --example basic
```

## Governance Boundary

The OSS trait includes write hooks because governance must be enforceable at the
boundary. The commercial product can add policy authoring, review queues,
retention controls, compliance exports, and audit UI on top of the same hook.

## Backend Choice

Use `BasicMemoryProvider` when you need:

- examples
- tests
- in-process prototypes

Use `SqliteMemoryProvider` when you need:

- local persistence
- hybrid vector + FTS retrieval
- one file to back up or encrypt
- backend behavior closer to production

See [../../examples/memory-provider](../../examples/memory-provider).