claw-core 0.1.0

Embedded local database engine for ClawDB — an agent-native cognitive database
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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# claw-core

> Embedded local database engine for **ClawDB** — an agent-native cognitive database.

[![Crates.io](https://img.shields.io/crates/v/claw-core)](https://crates.io/crates/claw-core)
[![docs.rs](https://img.shields.io/docsrs/claw-core)](https://docs.rs/claw-core)
[![CI](https://github.com/Claw-DB/claw-core/actions/workflows/ci.yml/badge.svg)](https://github.com/Claw-DB/claw-core/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

## Features

- 🏠 **Local-first** — all data stays on device; no network dependency
- 📝 **WAL journaling** — SQLite Write-Ahead Logging for high-concurrency reads
- ⚡ **Async Rust** — fully async via `tokio` + `sqlx`
- 🧠 **LRU cache** — configurable in-memory LRU cache reduces DB round-trips
- 🔍 **FTS5 search** — full-text search over memory content using SQLite FTS5
- 📸 **Snapshot/restore** — point-in-time database snapshots
- 🔄 **Migration system** — embedded, versioned SQL migrations via `sqlx::migrate!`
- 🔒 **ACID transactions** — explicit commit/rollback via `ClawTransaction`

## Quick start

```rust
use claw_core::prelude::*;

#[tokio::main]
async fn main() -> claw_core::ClawResult<()> {
    // Open (or create) the database with default settings.
    let engine = ClawEngine::open_default().await?;

    // Insert a memory record.
    let record = MemoryRecord::new(
        "The capital of France is Paris",
        MemoryType::Semantic,
        vec!["geography".to_string()],
        None, // no TTL
    );
    let id = engine.insert_memory(&record).await?;

    // Full-text search.
    let hits = engine.fts_search("France").await?;
    println!("{} result(s) found", hits.len());

    // Retrieve by ID (cache-aware).
    let fetched = engine.get_memory(id).await?;
    assert_eq!(fetched.content, "The capital of France is Paris");

    engine.close().await;
    Ok(())
}
```

## ClawConfig customization

```rust
use claw_core::{ClawConfig, JournalMode};

let config = ClawConfig::builder()
    .db_path("/var/data/agent/claw.db")
    .max_connections(5)
    .cache_size_mb(128)
    .journal_mode(JournalMode::WAL)
    .snapshot_dir("/var/data/agent/snapshots")
    .auto_migrate(true)
    .build()
    .expect("valid config");
```

## Architecture

```
Caller
  │
  ▼
ClawEngine
  ├── LRU Cache (tokio::sync::Mutex<ClawCache>)
  │     └── MemoryRecord entries (in-memory)
  └── SqlitePool (sqlx)
        └── SQLite file (WAL mode)
              ├── memories        (+ memories_fts FTS5)
              ├── sessions
              ├── active_memory
              ├── session_state
              ├── tool_output
              └── context
```

## Performance characteristics

| Operation | Target |
|-----------|--------|
| Cache hit read latency | < 100 µs |
| Insert throughput (NVMe) | > 10,000 records/s |
| FTS5 search (10k records) | < 10 ms |
| Tag search (10k records) | < 5 ms |
| WAL checkpoint | < 1 ms (passive) |

> Benchmarks: `cargo bench` (requires `criterion` in dev-dependencies)

## Contributing

Contributions are welcome! Please open an issue or pull request on
[GitHub](https://github.com/Claw-DB/claw-core).

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Run tests: `cargo test --all-features`
4. Run lints: `cargo clippy -- -D warnings && cargo fmt --check`
5. Submit a pull request

## License

Licensed under the [Apache-2.0](LICENSE) license.