AaronDB

AaronDB is a local, embedded Datalog database for the BEAM. Its documented Stable labels are narrow local contracts backed by committed tests, bounded failure behavior where relevant, reproducible harnesses, and CI; see the evidence index.

"Simplicity is not about making things easy. It is about untangling complexity." — Rich Hickey

Current release line: v4.2.0 certifies the embedded-core-v1 structural closure: local Datalog domain models and deterministic algorithms with mechanically enforced pure-to-adapter boundaries. Sharding, distributed/HA, storage/transport, and MCP surfaces remain experimental; see Feature Maturity, Project Boundaries, and the certification profile.

AaronDB is a BEAM-native temporal Datalog engine written in Gleam. Its strongest shape is a fact-oriented database core built around a transactor actor, immutable-style state transitions, in-memory indexes, and a custom query engine.

This repository also contains local search, graph analytics, federation, cognitive, sharding, and MCP extensions. Their supported contracts are deliberately narrow; read docs/feature_maturity.md and docs/project_boundaries.md before adopting non-core features.

Core Model

1. Facts, not objects: data is represented as datoms.
2. Actor-owned writes: a transactor process serializes state transitions.
3. Query over values: reads execute against database state snapshots.
4. Storage is pluggable: the engine is decoupled from persistence adapters.

What Is Solid Today

• In-memory transactional core
• Datom model with transaction and valid-time fields
• Query DSL and interpreted query execution
• Pull, history, diff, and speculative state evaluation
• Constraints for uniqueness, cardinality, predicates, and composites
• Local Stable retrieval/analytics contracts with committed regression and benchmark evidence

Maturity Snapshot

Explicitly local means exactly that

The Stable labels above are contracts for one BEAM runtime and stated, reproducible local evidence. They do not claim remote federation, replication, high availability, failover, migration, quorum, coordinated writes, global snapshots, distributed graph processing, or universal latency/memory/recall guarantees.

• Vector:cosine HNSW contract plus exact oracle, recall/churn regression, and benchmark harness.
• BM25:Analyzer v1 and lifecycle contract; no transaction integration, persistence, or concurrent mutation safety.
• Graph:directed bounded analytics contract; legacy APIs remain unbounded compatibility paths.
• Temporal/Diff:bounded local snapshot and diff contract, with lifecycle/invariant tests and a reproducible CI evidence harness; no remote/global snapshots or universal performance claims.
• Federation:local fail-fast read contract; no cross-source transaction/snapshot, retries, or partial result mode.

Installation

Add the current release to your gleam.toml:

[dependencies]
aarondb = "4.2"

What 4.2.0 Changes

AaronDB 4.2.0 certifies embedded-core-v1: a deliberately bounded structural profile for local Datalog domain data and deterministic algorithms. The profile is executable: it rejects forbidden effectful imports, unapproved pure-module dependencies, malformed certification metadata, and generated/runtime artifacts.

• Explicit failure boundaries — register_composite_with_timeout and store_rule_with_timeout accept caller-owned deadlines. Existing convenience APIs remain compatibility wrappers with their historical five-second deadline.
• Pure transaction domain — transaction transformation is separated from persistence and subscriber delivery; ordering and lookup failures have characterization tests.
• Deterministic vector evidence — the exact local oracle, validation boundary, and tie ordering are independently testable from the approximate HNSW façade.
• State and continuation ownership — state ownership is documented by concern, and retry/fallback/idempotency policy is explicit data rather than invisible control flow.

It does not promote sharding, Raft, HA, remote federation, storage/transport, MCP, lifecycle/upgrade/rollback, or broader cluster claims. Those surfaces remain experimental until their own candidate-SHA evidence profiles pass. See CHANGELOG.md for the full release notes.

Basic Usage

Create an in-memory database:

import aarondb

let db = aarondb.new()

Transact facts:

import aarondb
import aarondb/fact.{EntityId, Str, Uid}

let assert Ok(_state) = aarondb.transact(db, [
  #(Uid(EntityId(101)), "user/name", Str("Alice")),
  #(Uid(EntityId(101)), "user/role", Str("Admin")),
])

Query with the DSL:

import aarondb
import aarondb/q

let query =
  q.select(["name"])
  |> q.where(q.v("e"), "user/role", q.s("Admin"))
  |> q.where(q.v("e"), "user/name", q.v("name"))
  |> q.to_clauses()

let results = aarondb.query(db, query)

Use temporal and pull APIs:

import aarondb
import aarondb/fact

let history = aarondb.history(db, fact.Uid(fact.EntityId(101)))
let entity = aarondb.pull(db, fact.Uid(fact.EntityId(101)), aarondb.pull_all())

Documentation

• Architecture
• Feature Maturity
• Project Boundaries
• Query DSL
• Local MCP stdio adapter
• Supervision
• Vector search contract
• BM25 search contract
• Graph query contract
• Local federation contract
• Distributed Guide

Current Recommendation

Treat AaronDB first as a temporal Datalog engine with a strong in-memory core. The v4.1 local contracts are ready for their stated use, but distributed features remain deliberately separate work—not marketing adjectives.