ClawDB

   ________                ____  ____
  / ____/ /___ ___      __/ __ \/ __ )
 / /   / / __ `/ / | /| / / / / / __  |
/ /___/ / /_/ / /| |/ |/ / /_/ / /_/ /
\____/_/\__,_/ / |__/|__/_____/_____/

The cognitive database for AI agents.

ClawDB is a production-grade memory runtime that unifies durable storage, semantic retrieval, branch/merge workflows, synchronization, reflection pipelines, and policy governance in one API and one operational surface.

Features

Workspace Crates

ClawDB is a multi-crate workspace. Each crate has a focused responsibility and can be consumed independently when needed.

clawdb (Runtime API)

The clawdb crate is the top-level API for embedding ClawDB in Rust applications.

• Exposes session-oriented methods (session, validate_session, revoke_session)
• Exposes memory methods (remember, remember_typed, search, recall)
• Exposes branch methods (branch, fork_branch, merge, diff, list_branches)
• Exposes sync/reflect entrypoints (sync, reflect)
• Exposes health and telemetry hooks (health, metrics_handle)

Primary path in this repo: clawdb/src.

clawdb-server (HTTP + gRPC Surface)

The clawdb-server crate hosts the runtime as network services.

• HTTP API for clients and automation
• gRPC API with reflection support
• Prometheus metrics endpoints
• Config-driven startup with env overrides

Primary paths in this repo:

• clawdb-server/src/http
• clawdb-server/src/grpc
• clawdb-server/src/state.rs

clawdb-cli (Pure HTTP Client)

The clawdb-cli crate is intentionally decoupled from runtime internals.

• Talks to clawdb-server over HTTP only
• No direct linkage to component crates at call time
• Supports table/json/tsv output modes
• Includes commands for init, status, remember/search/recall, branches, sync, reflect, policy, config, session, completion

Primary path in this repo: clawdb-cli/src.

This design keeps the CLI small and stable while allowing server/runtime internals to evolve independently.

Quick Start

1. Add the crate:

cargo add clawdb

2. Use ClawDB in your app:

use clawdb::prelude::*;

#[tokio::main]
async fn main() -> ClawDBResult<()> {
	let db = ClawDB::open_default().await?;
	let session = db.session(uuid::Uuid::new_v4(), "assistant", vec!["memory:write".into()]).await?;
	let _ = db.remember(&session, "Hello ClawDB").await?;
	let hits = db.search(&session, "hello").await?;
	println!("It works: {} result(s)", hits.len());
	db.close().await
}

3. Run:

cargo run

Expected output includes: It works: <n> result(s).

Installation

From crates.io

cargo add clawdb

From binary releases

Download artifacts from GitHub Releases and add clawdb, clawdb-cli, and clawdb-server to your PATH.

From Docker

docker build -t clawdb:latest .
docker run --rm -p 50050:50050 -p 8080:8080 -p 9090:9090 clawdb:latest

Architecture

				 ┌─────────────────────┐
				 │       ClawDB         │
				 │  Unified Runtime     │
				 └──────────┬──────────┘
	  ┌─────────────────────┼─────────────────────┐
	  │           │         │         │            │
 ┌────▼───┐ ┌─────▼───┐ ┌──▼─────┐ ┌─▼──────┐ ┌──▼──────┐ ┌──▼────┐
 │  core  │ │ vector  │ │  sync  │ │ branch │ │ reflect │ │ guard │
 └────────┘ └─────────┘ └────────┘ └────────┘ └─────────┘ └───────┘

API Reference

Primary engine methods:

1. async fn new(config: ClawDBConfig) -> ClawDBResult<ClawDB>
2. async fn open_default() -> ClawDBResult<ClawDB>
3. async fn open(data_dir: &Path) -> ClawDBResult<ClawDB>
4. async fn session(agent_id: Uuid, role: &str, scopes: Vec<String>) -> ClawDBResult<ClawDBSession>
5. async fn remember(session: &ClawDBSession, content: &str) -> ClawDBResult<RememberResult>
6. async fn remember_typed(session: &ClawDBSession, content: &str, memory_type: &str, tags: &[String], metadata: serde_json::Value) -> ClawDBResult<RememberResult>
7. async fn search(session: &ClawDBSession, query: &str) -> ClawDBResult<Vec<serde_json::Value>>
8. async fn search_with_options(session: &ClawDBSession, query: &str, top_k: usize, semantic: bool, filter: Option<serde_json::Value>) -> ClawDBResult<Vec<serde_json::Value>>
9. async fn recall(session: &ClawDBSession, memory_ids: &[String]) -> ClawDBResult<Vec<serde_json::Value>>
10. async fn branch(session: &ClawDBSession, name: &str) -> ClawDBResult<Uuid>
11. async fn merge(session: &ClawDBSession, source: Uuid, target: Uuid) -> ClawDBResult<serde_json::Value>
12. async fn sync(session: &ClawDBSession) -> ClawDBResult<serde_json::Value>

Additional methods include diff, reflect, validate_session, revoke_session, health, close, shutdown, and transaction.

Configuration Reference

Top-level ClawDBConfig fields:

1. data_dir (CLAW_DATA_DIR)
2. workspace_id (CLAW_WORKSPACE_ID)
3. agent_id (CLAW_AGENT_ID)
4. log_level (CLAW_LOG_LEVEL)
5. log_format (CLAW_LOG_FORMAT)
6. core
7. vector
8. sync
9. branch
10. guard
11. reflect
12. server
13. plugins
14. telemetry

CLI Reference

Commands:

1. clawdb init
2. clawdb start
3. clawdb status
4. clawdb remember
5. clawdb search
6. clawdb branch
7. clawdb sync
8. clawdb reflect
9. clawdb policy
10. clawdb config

Examples:

clawdb init --with-reflect
clawdb start --grpc-port 50050 --http-port 8080
clawdb remember "deploy started" --type event --tags deploy,prod
clawdb search "deploy" --top-k 5 --semantic
clawdb branch create hotfix-42 --from trunk

Plugin Development Guide

Implement ClawPlugin from clawdb::plugins::interface and provide a plugin manifest:

name = "my_plugin"
version = "0.1.0"
description = "Example ClawDB plugin"
capabilities = ["ReadMemory", "EmitEvents"]
entry_symbol = "create_plugin"

Build as dynamic library and place under plugins_dir.

Deployment Guide

Docker Compose Quick Start

docker compose up -d --build

Kubernetes

kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/hpa.yaml

Ecosystem

Crate	Role	Version
claw-core	Durable storage
claw-vector	Semantic retrieval
claw-sync	Synchronization
claw-branch	Branch/merge runtime
claw-guard	Governance and access control
clawdb	Unified runtime API