claw_core/
lib.rs

1#![deny(missing_docs)]
2#![deny(clippy::unwrap_used)]
3#![cfg_attr(test, allow(clippy::unwrap_used))]
4#![allow(clippy::module_inception)]
5//! # claw-core
6//!
7//! `claw-core` is the embedded local database engine for **ClawDB** — an
8//! agent-native cognitive database. It provides local-first, ultra-low-latency
9//! storage for AI agents, wrapping SQLite with a clean async Rust API that
10//! includes WAL journaling, migrations, LRU caching, FTS5 full-text search,
11//! transactions, and snapshot/restore support.
12//!
13//! ## Encryption Feature
14//!
15//! Optional encryption-at-rest is available behind the `encryption` Cargo
16//! feature. This requires a SQLCipher build of SQLite. The default build path
17//! remains unencrypted and unchanged unless the feature is explicitly enabled.
18//!
19//! ## Quick start
20//!
21//! ```rust,no_run
22//! use claw_core::prelude::*;
23//!
24//! #[tokio::main]
25//! async fn main() -> claw_core::ClawResult<()> {
26//!     // Open (or create) the database with default settings.
27//!     let engine = ClawEngine::open_default().await?;
28//!
29//!     // Insert a memory record.
30//!     let record = MemoryRecord::new(
31//!         "The capital of France is Paris",
32//!         MemoryType::Semantic,
33//!         vec!["geography".to_string()],
34//!         None,
35//!     );
36//!     let id = engine.insert_memory(&record).await?;
37//!
38//!     // Retrieve it back.
39//!     let fetched = engine.get_memory(id).await?;
40//!     assert_eq!(fetched.content, "The capital of France is Paris");
41//!
42//!     // Close the engine cleanly.
43//!     engine.close().await;
44//!     Ok(())
45//! }
46//! ```
47//!
48//! ## Key types
49//!
50//! | Type | Description |
51//! |------|-------------|
52//! | [`ClawEngine`] | Root handle for all database operations |
53//! | [`ClawConfig`] | Runtime configuration built via [`ClawConfigBuilder`] |
54//! | [`MemoryRecord`] | A persistent memory record with type, tags, and TTL |
55//! | [`MemoryType`] | Enum classifying memory records (Semantic, Episodic, …) |
56//! | [`ClawTransaction`] | Atomic transaction wrapper |
57//! | [`ClawError`] | Unified error type |
58
59// ── module declarations ──────────────────────────────────────────────────────
60
61pub mod cache;
62pub mod config;
63pub mod engine;
64pub mod error;
65pub mod index;
66pub mod journal;
67pub mod schema;
68pub mod snapshot;
69pub mod store;
70pub mod transaction;
71
72// ── top-level re-exports ─────────────────────────────────────────────────────
73
74pub use cache::CacheStats;
75pub use config::{ClawConfig, ClawConfigBuilder, JournalMode};
76pub use engine::{ClawEngine, ClawStats, DbStats};
77pub use error::{ClawError, ClawResult};
78pub use journal::{CheckpointMode, CheckpointResult};
79pub use snapshot::{SnapshotManifest, SnapshotMeta};
80pub use store::memory::{ListOptions, ListPage, MemoryRecord, MemoryType};
81pub use store::session_lifecycle::Session;
82pub use store::tool_output::ToolOutputRecord as ToolOutput;
83pub use transaction::{CacheOp, CacheRecord, ClawTransaction, StagedMemoryOp};
84
85/// The claw-core prelude — import this for the most commonly used types.
86///
87/// ```rust,no_run
88/// use claw_core::prelude::*;
89/// ```
90pub mod prelude {
91    pub use crate::{ClawConfig, ClawEngine, ClawError, ClawResult, MemoryRecord, MemoryType};
92}
claw_core/lib.rs

claw_core/
lib.rs
