cel-memory-duckdb 0.1.0

DuckDB embedded memory backend for AI agents, implementing cel-memory.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# cel-memory-duckdb

[![crates.io](https://img.shields.io/crates/v/cel-memory-duckdb.svg)](https://crates.io/crates/cel-memory-duckdb)
[![docs.rs](https://docs.rs/cel-memory-duckdb/badge.svg)](https://docs.rs/cel-memory-duckdb)
[![CI](https://github.com/dimpagk92/cel-memory-duckdb/actions/workflows/ci.yml/badge.svg)](https://github.com/dimpagk92/cel-memory-duckdb/actions/workflows/ci.yml)

DuckDB embedded memory backend for AI agents. Implements
[`cel-memory`](https://crates.io/crates/cel-memory)'s `MemoryProvider` trait with
hybrid vector + lexical retrieval in a single analytics-friendly file.

**Status:** v0.1.0 starter — Phase 0–1: open/migrate, write/get, hybrid
retrieve (`array_cosine_distance` + ILIKE), sessions, stats. Summarization,
aging, export, and bulk mutations return `NotImplemented` until later phases.

## Purpose

Use `cel-memory-duckdb` when you want local, embeddable memory with DuckDB's
columnar engine — analytics-heavy agents, notebooks, or workloads that already
use DuckDB/Parquet nearby. Swap it in wherever code holds
`Arc<dyn MemoryProvider>`.

## Requirements

- Embedding width **384** (matches [`MockEmbedder`](https://docs.rs/cel-memory/latest/cel_memory/struct.MockEmbedder.html) / bge-small)
- DuckDB bundled via the [`duckdb`](https://crates.io/crates/duckdb) crate (no separate install)

## Example

```rust
use std::sync::Arc;
use cel_memory_duckdb::{DuckdbMemoryProvider, MockEmbedder};

let provider = DuckdbMemoryProvider::open(
    "memory.duckdb",
    Arc::new(MockEmbedder::new()),
).await?;
// Use as cel_memory::MemoryProvider — same trait as BasicMemoryProvider.
```

Run the complete example:

```sh
cargo run --example basic
```

## What's included (Phase 0–1)

- `DuckdbMemoryProvider::open` / `open_in_memory` — embedded migrations
- `write` / `get` / `write_batch`
- Hybrid `retrieve` — cosine distance on `FLOAT[384]` + ILIKE keyword match, fused with RRF
- Session lifecycle — `open_session`, `close_session`, `rename_session`, `get_session`, `list_sessions`
- `stats`

## Roadmap

| Phase | Methods |
|-------|---------|
| 2 | `pin`, `delete`, `purge_all`, `run_aging_sweep`, `export`, … |
| 3 | `summarize_session`, `rollup_day`, `rollup_rule_week` |
| 4 | `re_embed_all`, DuckDB VSS HNSW indexes, richer FTS |

## License

Apache-2.0