HawDB

HawDB is an AI-native embedded database for agents. It keeps the facts an agent reasons over — entities, relationships, documents, and events — in one crash-safe process, returns them as bounded context, and gives each agent its own durable branch to work in.

• Context layer. Graph structure, relational rows, lexical search, and vector search share one engine. A retrieval request takes search candidates, filters them, walks the authorized graph, reranks with a typed score, and hydrates the result from the canonical snapshot. See Context, in one pipeline.
• Built for agent workloads. Agents talk to the database through parameterized Cypher and SQL. Every read has an explicit row and payload budget, and an over-budget request fails instead of returning a silently truncated answer. A read transaction pins one published snapshot, so a multi-step plan sees one consistent state.
• Branches for agents. A copy-on-write branch costs metadata and an empty WAL, not a copy of the data. An agent can try a plan, write intermediate facts, or run a long task on its own branch without disturbing main or other agents. See Branches for agents.

HawDB is written in Rust and licensed under Apache-2.0. It is built for Nowledge Mem, currently in nightly integration. The library is the product: any host that needs a durable context layer opens it the same way.

The site and in-browser playground are at hawdb.ai. Their source is nowledge-co/hawdb-website.

For synchronous SQL materialized views, see the materialized view guide. For BM25 full-text search over SQL rows, see the SQL search index guide.

Install

HawDB is a Rust library. Published releases are on crates.io. The repository pins Rust 1.97.1.

[dependencies]
hawdb = "0.32"

To follow the repository tip instead of a release:

hawdb = { git = "https://github.com/nowledge-co/hawdb" }

Or build the default library from a checkout:

cargo build --locked -p hawdb

The default build includes full-text search, vector search, graph analytics, background maintenance, and the Tokio adapter. A capability left out of the build cannot be turned back on at runtime. See Build.

Python bindings live in-tree and are distributed as hawdb on PyPI. See Python.

Open a database

Database::open creates or recovers a durable project directory. One process owns that directory. Inside the process, reads and writes are transactional.

use hawdb::{Database, Value};
use std::collections::BTreeMap;

fn main() -> hawdb::Result<()> {
    let mut db = Database::open("./knowledge")?;

    let mut note = BTreeMap::new();
    note.insert("title".into(), Value::String("Graph foundations".into()));

    let mut tx = db.begin_transaction()?;
    tx.query_with_params(
        "CREATE (:Note {title: $title})-[:MENTIONS]->(:Entity {name: 'context layer'})",
        &note,
    )?;
    tx.commit()?;

    let found = db.query(
        "MATCH (note:Note)-[:MENTIONS]->(entity:Entity)
         RETURN note.title AS title, entity.name AS name
         ORDER BY title",
    )?;
    println!("{:?}", found.rows.get(0, "title"));
    Ok(())
}

The same program is examples/open_database.rs. The relationship is created in that statement together with both endpoints.

Database::new opens an in-memory database with the same query API. Parameterized statements are the application interface. EXPLAIN returns the physical plan chosen by the Cascades-style optimizer.

Relational facts use PostgreSQL-dialect SQL on the same handle:

db.query_sql(
    "CREATE TABLE events (
        stream_id TEXT NOT NULL,
        sequence BIGINT NOT NULL,
        payload BYTEA NOT NULL,
        PRIMARY KEY (stream_id, sequence)
    ) WITH (
        storage_mode = 'strict_append',
        partition_key = 'stream_id',
        order_key = 'sequence'
    )",
)?;

Strict-append tables accept parameterized INSERT only. Reads name the partition, walk the order key, and set LIMIT. Generated commit_sequence keys are assigned at the durable commit boundary. The contract is in docs/specs/QUERY_FIRST_PUBLIC_API_SPEC.md.

Context, in one pipeline

Search hits enter the pipeline as candidates.

Database::retrieve_knowledge and DatabaseReadTransaction::retrieve_knowledge run one fixed pipeline against a pinned graph snapshot:

1. search_candidate — lexical or vector hits from the published search projection
2. metadata_filter — relevance predicates on projection metadata
3. authorized_graph_expand — neighborhood expansion that rechecks scope on canonical nodes
4. rerank — Max, a weighted sum, or a host-supplied ScoringSpec
5. top_k — truncate before any output entity is built
6. canonical_hydration — load identity, properties, and graph context from the snapshot

A projection epoch is reported beside the graph commit epoch. A stale search hit that no longer matches canonical identity is dropped and counted. Missing score features are reported on the candidate; they are never treated as zero. The whole request fails if it exceeds the query memory budget or the result payload budget. Partial context is not returned.

This is the beginning of the README. Read the rest at the original. Read the full README ↗