KoruDelta — The Invisible Database

Tagline: "Invisible. Causal. Everywhere."

One-line: KoruDelta gives you Git-like history, Redis-like speed, and distributed consistency—without configuration.

What Makes It Different?

| Feature | SQLite | Redis | PostgreSQL | KoruDelta | |---------|--------|-------|------------|---------------| | Zero-config | ✅ | ❌ | ❌ | ✅ | | Time travel / audit | ❌ | ❌ | ❌ (complex) | ✅ Built-in | | Vector search | ❌ (extension) | ❌ | ✅ (pgvector) | ✅ Native | | Causal consistency | ❌ | ❌ | ❌ | ✅ | | Binary size | ~1MB | ~10MB | ~100MB | ~11MB | | History retention | ❌ | ❌ | ❌ | ✅ Unlimited | | Materialized views | ❌ | ❌ | ✅ | ✅ Native |

KoruDelta isn't just another database—it's a time-aware database.

Every write is versioned. Query data as it existed 5 minutes ago. Compare versions with Git-style diffs. Build audit trails without application changes.

Quick Start

# Install (10 seconds)
cargo install koru-delta

# Use (0 configuration)
kdelta set users/alice '{"name": "Alice", "age": 30}'
kdelta get users/alice
kdelta log users/alice          # Full history
kdelta get users/alice --at "2026-02-01T00:00:00Z"  # Time travel

use koru_delta::KoruDelta;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = KoruDelta::start().await?;
    
    // Single write
    db.put("users", "alice", serde_json::json!({
        "name": "Alice",
        "email": "[email protected]"
    })).await?;
    
    // Batch write (10-50x faster for bulk operations)
    db.put_batch(vec![
        ("products", "p1", serde_json::json!({"name": "Widget", "price": 9.99})),
        ("products", "p2", serde_json::json!({"name": "Gadget", "price": 19.99})),
    ]).await?;
    
    // Get current value
    let user = db.get("users", "alice").await?;
    
    // Get history
    let history = db.history("users", "alice").await?;
    
    // Time travel
    let past_user = db.get_at("users", "alice", timestamp).await?;
    
    Ok(())
}

Performance

Real benchmarks (MacBook Pro M1, 16GB RAM, SSD):

| Metric | KoruDelta | SQLite (fsync) | Notes | |--------|-----------|----------------|-------| | Writes (single) | ~201 ops/sec | ~3,700 ops/sec | KoruDelta: WAL + versioning | | Writes (batch) | ~3,500 ops/sec* | N/A | 16x faster with put_batch | | Reads | ~134K ops/sec | ~267K ops/sec | Hot memory cache | | Binary size | 11MB | 1MB | Single static binary | | Memory | Configurable | Configurable | 512MB default |

* Batch write: 1000 items in 280ms vs 4.66s for individual writes

Why slower writes? KoruDelta does more:

• Every write creates a version (immutable history)
• Content-addressed deduplication (Blake3 hashes)
• Causal graph tracking
• Automatic memory tier promotion

Batch writes (put_batch) amortize fsync cost across many items, delivering 10-50x speedups for bulk operations.

Trade-off: Speed for superpowers. If you need audit trails, time travel, or causal consistency, KoruDelta eliminates weeks of application development.

Core Features

🕰️ Time Travel (Built-in)

// Every change is versioned forever
let history = db.history("users", "alice").await?;

// Query past state
let past = db.get_at("users", "alice", yesterday).await?;

// Compare versions
kdelta diff users/alice

Use cases: Audit trails, compliance (HIPAA/GDPR), debugging, undo/redo.

📊 Materialized Views (v2.0.0)

use koru_delta::views::ViewDefinition;
use koru_delta::query::{Query, Filter};

let view = ViewDefinition {
    name: "active_users".to_string(),
    source_collection: "users".to_string(),
    query: Query {
        filters: vec![Filter::eq("status", "active")],
        ..Default::default()
    },
    created_at: chrono::Utc::now(),
    description: Some("Active users only".to_string()),
    auto_refresh: true,
};

db.create_view(view).await?;
let results = db.query_view("active_users").await?;  // Instant

Views persist across restarts and auto-refresh on writes.

🔍 Vector Search (v2.0.0)

use koru_delta::vector::Vector;

// Store embedding
let embedding = Vector::new(vec![0.1, 0.2, 0.3, ...], "text-embedding-3-small");
db.embed("docs", "doc1", embedding, None).await?;

// Semantic search
let results = db.embed_search(
    Some("docs"), 
    &query_vector,
    VectorSearchOptions { top_k: 10, threshold: 0.0, model_filter: None }
).await?;

Build RAG applications, semantic document search, recommendation engines.

🔔 Real-time Subscriptions

let (sub_id, mut rx) = db.subscribe(Subscription {
    collection: Some("orders".to_string()),
    key: None,
    filter: None,
    change_types: vec![ChangeType::Insert, ChangeType::Update],
    name: Some("order-monitor".to_string()),
}).await;

while let Ok(event) = rx.recv().await {
    println!("New order: {}", event.key);
}

🔐 Self-Sovereign Auth

use koru_delta::auth::{mine_identity, IdentityUserData};

// Mine an identity (proof-of-work prevents spam)
let identity = mine_identity(
    IdentityUserData::new("alice"),
    4  // difficulty: 4 leading hex zeros
).await;

// identity.id = public key
// identity.secret_key = private key (keep secure!)

No central authority. Users own their keys.

📦 Workspaces (v2.0.0)

Isolated memory spaces with causal boundaries—like separate databases within one:

use koru_delta::workspace_agent::{WorkspaceAgent, WorkspaceMetadata};

let mut workspaces = WorkspaceAgent::new(workspace_root, engine);

// Create isolated workspace
let ws = workspaces.create_workspace("project-a", "Project A");

// Store in workspace (isolated from other workspaces)
workspaces.remember(&ws.id, "task-1", json!({"title": "Design API"}))?;

// Search within workspace only
let results = workspaces.recall(&ws.id, "design API")?;

Use cases: Multi-tenant SaaS, project isolation, sandboxed experiments.

🌐 Browser/WASM

import init, { KoruDeltaWasm } from 'koru-delta';

await init();

// Persistent database (IndexedDB)
const db = await KoruDeltaWasm.new(); // In-memory with optional IndexedDB persistence

await db.put('users', 'alice', { name: 'Alice', age: 30 });
const user = await db.get('users', 'alice');

// Batch writes for better performance (10-50x faster)
await db.putBatch([
    { namespace: 'users', key: 'alice', value: { name: 'Alice' } },
    { namespace: 'users', key: 'bob', value: { name: 'Bob' } },
]);

// Data survives page refreshes!

When to Use KoruDelta

✅ Perfect For

| Use Case | Why KoruDelta Wins | |----------|-------------------| | Audit-heavy apps | Built-in versioning, no schema changes | | Local-first software | Works offline, syncs when online | | Edge/IoT | 11MB binary, survives power loss | | AI agents | Vector search + memory tiering | | Config management | Time travel, easy rollbacks | | Compliance | Immutable history, cryptographic proofs |

⚠️ Not For

| Use Case | Use Instead | |----------|-------------| | 100K+ writes/sec analytics | ClickHouse, TimescaleDB | | Complex SQL JOINs | PostgreSQL | | Multi-region active-active | CockroachDB, Spanner | | Pure caching | Redis |

Architecture

The Secret: Distinction Calculus

KoruDelta is built on koru-lambda-core—a minimal axiomatic system for distributed computation:

• Mathematical guarantees - Safety from formal foundations
• Structural integrity - Can't corrupt by design
• Deterministic operations - Same inputs → same results
• Natural distribution - Consensus emerges from axioms

LCA Architecture (Local Causal Agent)

KoruDelta implements the Local Causal Agent pattern—20 specialized agents, each with a causal perspective in a unified field:

┌─────────────────────────────────────────┐
│        Unified Field (SharedEngine)     │
│     Single DistinctionEngine instance   │
└─────────────────────────────────────────┘
         │              │              │
    ┌────┘         ┌────┘         ┌────┘
┌───┴───┐      ┌───┴───┐     ┌───┴────┐
│Storage│      │Vector │     │Identity│
│ Agent │      │ Agent │     │ Agent  │
└───────┘      └───────┘     └────────┘

All operations follow: ΔNew = ΔLocal_Root ⊕ ΔAction

Each agent:

1. Has a local_root (its causal perspective)
2. Receives actions (Store, Query, etc.)
3. Synthesizes: new_root = synthesize(local_root, action)
4. Updates its perspective

Benefits:

• Complete audit trail (every operation leaves a causal trace)
• Content-addressed (same data = same ID everywhere)
• Cross-agent synthesis (combine multiple perspectives)
• Natural distribution (distinctions are universal)

Storage: WAL + Content-Addressed

~/.korudelta/db/
├── wal/000001.wal          # Append-only log (immutable)
└── values/ab/cd1234...     # Deduplicated by content hash

Benefits:

• O(1) writes (append, not rewrite)
• Crash-safe (never overwrites data)
• Automatic deduplication
• The log IS the history

Memory: Brain-Inspired Tiering

| Tier | Capacity | Access | Eviction | |------|----------|--------|----------| | Hot | 10K items | ~400ns | LRU | | Warm | Recent chronicle | ~1µs | Age-based | | Cold | Consolidated epochs | ~10µs | Fitness score | | Deep | Genomic (1KB) | Load on demand | Manual |

Like human memory: frequently used items stay hot, patterns consolidate to deep storage.

CLI Reference

# Basic CRUD
kdelta set users/alice '{"name": "Alice"}'
kdelta get users/alice
kdelta delete users/alice

# Time travel
kdelta get users/alice --at "2026-02-01T00:00:00Z"
kdelta log users/alice              # History
kdelta diff users/alice             # Compare versions

# Views
kdelta view create active_users users --filter 'status = "active"'
kdelta view list
kdelta view query active_users
kdelta view refresh active_users

# Queries
kdelta query users --filter 'age > 30' --sort name --limit 10
kdelta query sales --sum amount      # Aggregation

# HTTP API
kdelta serve --port 8080
kdelta --url http://localhost:8080 get users/alice

# Cluster (experimental)
kdelta start --join 192.168.1.100

Examples

# Full feature showcase
cargo run --example crisis_coordination_demo

# Distributed cluster validation  
cargo run --example cluster_e2e_test

# Stress testing
cargo run --example stress_test --release

# Original demos
cargo run --example ecommerce_demo

Project Stats

• 15,000+ lines Rust code
• 463 tests (all passing)
• 0 compiler warnings
• 11MB binary size
• Cross-platform: Linux, macOS, Windows, WASM

Distributed Status

Current (v3.0.0): Full cluster support in native Rust. Python bindings have cluster support. WASM is single-node.

| Platform | Cluster Support | Notes | |----------|----------------|-------| | Rust (native) | ✅ Full | TCP-based clustering with live replication | | Python | ✅ Full | Same as Rust via PyO3 bindings | | WASM (Browser/Node.js) | ❌ N/A | Single-node only (WebSocket cluster planned) |

| Feature | Status | |---------|--------| | Node discovery | ✅ Working | | Initial sync on join | ✅ Working | | Live replication | ✅ Working | | Gossip protocol | ✅ Working | | HTTP API | ✅ Working |

Security

• Auth: Proof-of-work identity mining (prevents spam)
• Crypto: Ed25519 signatures, Blake3 hashing
• Model: Self-sovereign (users own keys, no central auth server)
• TLS: Recommended for HTTP API (use reverse proxy)

Operations

# Resource limits (via code)
let config = CoreConfig {
    memory: MemoryConfig {
        hot_capacity: 10000,
        max_memory_mb: 512,
        ..Default::default()
    },
    resource_limits: ResourceLimits {
        max_disk_mb: 10 * 1024,  // 10GB
        max_open_files: 256,
        max_connections: 100,
        ..Default::default()
    },
    ..Default::default()
};

# Logging
export KORU_LOG=info  # error, warn, info, debug, trace

Monitoring: Structured logs via tracing. Prometheus metrics planned for future release.

Contributing

See CONTRIBUTING.md and ARCHITECTURE.md.

License

MIT OR Apache-2.0

Links

• GitHub
• Design - Philosophy and decisions
• Architecture - Technical deep dive
• CLI Guide - Complete command reference

KoruDelta: Where data meets history, and simplicity meets power.