🐻

KUMA

Entity-Native Storage Engine for the BEAM

One entity. One actor. One writer.
No conflicts. Ever.

VIEW ON GITLAB EXPLORE
↓
0
writes/sec per entity
0
shards per context
0
lock conflicts
<0
read latency

CAPABILITIES

Built Different

⟫

EVENT SOURCED

Append-only log of facts. Complete audit trail. Time travel to any point in history.

⊡

ACTOR PER ENTITY

One process. One mailbox. One writer. No locks, no conflicts, no surprises.

⬡

SQLITE SHARDS

WAL mode, durable before ack, readable backups. Your data, your files.

⛨

GDPR NATIVE

export() and delete() are single operations. Compliance by design.

⎔

CLUSTERING

Multi-node with consistent hashing. Zero-downtime migration. Scale horizontally.

◈

PROJECTIONS

Async read models via rqlite. Eventually consistent queries. Decoupled reads.

QUICK START

Gleam in Action

main.gleam 
import kuma
import kuma/entity.{Entity}
import kuma/event.{Event}

// Define your entity type
pub type Account {
  Account(id: String, balance: Int, name: String)
}

// Define your events
pub type AccountEvent {
  Deposited(amount: Int)
  Withdrawn(amount: Int)
  Renamed(name: String)
}

pub fn main() {
  // Start Kuma with 16 shards
  let assert Ok(ctx) = kuma.start(kuma.Config(
    path: "/data/accounts",
    shards: 16,
  ))

  // Create an entity — spawns a dedicated actor
  let assert Ok(account) = kuma.spawn(ctx, "acc_001", Account(
    id: "acc_001",
    balance: 0,
    name: "Savings",
  ))

  // Append events — durable before ack
  kuma.append(account, Deposited(amount: 1000))
  kuma.append(account, Deposited(amount: 500))
  kuma.append(account, Withdrawn(amount: 200))

  // Read state — from actor memory, <1ms
  let assert Ok(state) = kuma.read(account)
  // state.balance == 1300 ✓

  // GDPR: export all data for a user
  let assert Ok(data) = kuma.export(account)

  // GDPR: right to be forgotten
  kuma.delete(account)
}

INTERNALS

Architecture

architecture.txt 
┌──────────────────────────────────────────────────────────────────┐
│  KUMA — Entity-Native Storage Engine                          │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Client Request                                                │
│       │                                                          │
│       ▼                                                          │
│  ┌─────────────┐    hash(entity_id)    ┌──────────────┐          │
│  │ Router      │───────────────────▶│ Shard N      │          │
│  │             │                    │ (1 of 16+)   │          │
│  └─────────────┘                    └──────┬───────┘          │
│                                            │                    │
│                                            ▼                    │
│                                    ┌──────────────┐              │
│                                    │ Entity Actor │              │
│                                    │ (1:1 per ID) │              │
│                                    └──────┬───────┘              │
│                                           │                      │
│                              ┌────────────┼────────────┐          │
│                              ▼            ▼            ▼          │
│                        ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│                        │ State    │ │ Events   │ │ Publish  │    │
│                        │ (memory) │ │ (SQLite) │ │ (async)  │    │
│                        └──────────┘ └──────────┘ └─────┬────┘    │
│                                                        │          │
│                                                        ▼          │
│                                                  ┌──────────┐    │
│                                                  │Projections│    │
│                                                  │ (rqlite)  │    │
│                                                  └──────────┘    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

USE CASES

When to Use Kuma

▸

Per-Entity CRUD

Each entity is an isolated actor with its own lifecycle and state.

▸

Event Sourcing

Append-only event log with full replay and time travel capabilities.

▸

Audit Trails

Every mutation is recorded. Nothing is ever lost or overwritten.

▸

GDPR Compliance

Export and delete are first-class operations, not afterthoughts.

▸

High-Write Throughput

50K+ writes/sec per entity. Actor isolation means no contention.

▸

Multi-Tenant Systems

Natural isolation at the entity level. Perfect for SaaS backends.