claw-core 0.1.2

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

#![deny(missing_docs)]
#![deny(clippy::unwrap_used)]
#![cfg_attr(test, allow(clippy::unwrap_used))]
#![allow(clippy::module_inception)]
//! # claw-core
//!
//! `claw-core` is the embedded local database engine for **ClawDB** — an
//! agent-native cognitive database. It provides local-first, ultra-low-latency
//! storage for AI agents, wrapping SQLite with a clean async Rust API that
//! includes WAL journaling, migrations, LRU caching, FTS5 full-text search,
//! transactions, and snapshot/restore support.
//!
//! ## Encryption Feature
//!
//! Optional encryption-at-rest is available behind the `encryption` Cargo
//! feature. This requires a SQLCipher build of SQLite. The default build path
//! remains unencrypted and unchanged unless the feature is explicitly enabled.
//!
//! ## Quick start
//!
//! ```rust,no_run
//! 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,
//!     );
//!     let id = engine.insert_memory(&record).await?;
//!
//!     // Retrieve it back.
//!     let fetched = engine.get_memory(id).await?;
//!     assert_eq!(fetched.content, "The capital of France is Paris");
//!
//!     // Close the engine cleanly.
//!     engine.close().await;
//!     Ok(())
//! }
//! ```
//!
//! ## Key types
//!
//! | Type | Description |
//! |------|-------------|
//! | [`ClawEngine`] | Root handle for all database operations |
//! | [`ClawConfig`] | Runtime configuration built via [`ClawConfigBuilder`] |
//! | [`MemoryRecord`] | A persistent memory record with type, tags, and TTL |
//! | [`MemoryType`] | Enum classifying memory records (Semantic, Episodic, …) |
//! | [`ClawTransaction`] | Atomic transaction wrapper |
//! | [`ClawError`] | Unified error type |

// ── module declarations ──────────────────────────────────────────────────────

pub mod cache;
pub mod config;
pub mod engine;
pub mod error;
pub mod index;
pub mod journal;
pub mod schema;
pub mod snapshot;
pub mod store;
pub mod transaction;

// ── top-level re-exports ─────────────────────────────────────────────────────

pub use cache::CacheStats;
pub use config::{ClawConfig, ClawConfigBuilder, JournalMode};
pub use engine::{ClawEngine, ClawStats, DbStats};
pub use error::{ClawError, ClawResult};
pub use journal::{CheckpointMode, CheckpointResult};
pub use snapshot::{SnapshotManifest, SnapshotMeta};
pub use store::memory::{ListOptions, ListPage, MemoryRecord, MemoryType};
pub use store::session_lifecycle::Session;
pub use store::tool_output::ToolOutputRecord as ToolOutput;
pub use transaction::{CacheOp, CacheRecord, ClawTransaction, StagedMemoryOp};

/// The claw-core prelude — import this for the most commonly used types.
///
/// ```rust,no_run
/// use claw_core::prelude::*;
/// ```
pub mod prelude {
    pub use crate::{ClawConfig, ClawEngine, ClawError, ClawResult, MemoryRecord, MemoryType};
}