claw-core

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

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

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

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

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

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

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.