A graph database for agent memory

Connect projects, decisions and their evidence. Query the graph with Cypher and give agents the relevant records.

Documentation · Quickstart · Agent memory · Ingestion · Benchmarks

Brainwire is an open source graph database built in Rust on RocksDB. Define your ontology, write over Bolt and inspect the live graph in your terminal. In the company example, an agent can recall a decision and follow it to the meeting that supports it. Try the decision memory demo

v0.23.0-beta.2 · experimental beta. Use rebuildable data and a tested backup. Current limits

The backup guide covers private checkpoint copies and restore permissions. Protect backup storage and test the restore procedure.

The demo uses a live Brainwire v0.21.0-beta.2 server and synthetic company data. Watch the video

Quickstart

Use Git and Docker with Compose. On macOS, Colima can run the Docker engine. With Colima running, run export DOCKER_CONTEXT=colima first.

git clone --branch v0.23.0-beta.2 https://github.com/allandefraga/brainwire.git # brainwire-release-version
cd brainwire
export BRAINWIRE_IMAGE=ghcr.io/allandefraga/brainwire:v0.23.0-beta.2 # brainwire-release-version
docker compose -p brainwire-demo -f deploy/compose.demo.yaml up --no-build --pull always --wait --wait-timeout 900

Check readiness with the built-in probe.

docker compose -p brainwire-demo -f deploy/compose.demo.yaml exec -T brainwire brainwire probe --mode ready

The demo listens at bolt://127.0.0.1:7687 and keeps data in a Docker volume. Use synthetic data on a trusted host and container network. The demo disables authentication, and other containers on the demo network can reach it. Use Docker Engine 28 or newer because earlier versions can expose loopback ports to the local network. Docker port publishing · Protected deployment

Write and query from Python

python3 scripts/setup_python.py

Run this with .venv-brainwire/bin/python:

from brainwire import connect

with connect("bolt://127.0.0.1:7687", "demo", auth=None) as graph:
    graph.upsert_node("Customer", "customer-1", {"name": "Ada"})
    graph.upsert_node("Segment", "segment-1", {"name": "beta"})
    graph.upsert_edge(
        ("Customer", "customer-1"), "IN_SEGMENT", ("Segment", "segment-1")
    )
    print(graph.run_cypher("""
        MATCH (c:Customer)-[:IN_SEGMENT]->(s:Segment)
        RETURN c.name AS customer, s.name AS segment
    """))

The demo includes these types. For your own graph, define an ontology first. See Python and protected deployment.

Try agent context

The company demo saves a decision and its source in one transaction. In a fresh process, recall the project decisions and supporting records the reader can see. Repeating the same write returns the same IDs. Set up the company graph with Docker

After saving the example decision, run the read command in the same shell with BW_PORT set.

.venv-brainwire/bin/python -m examples.python.agent_memory --uri "bolt://$BW_PORT" \
  recall --project project-release --limit 5

If you are using the Customer and Segment records from the quickstart above, run .venv-brainwire/bin/python -m examples.python.agent_context_demo to read those records and their connection. Context API and provider configuration

Explore in the terminal

docker compose -p brainwire-demo -f deploy/compose.demo.yaml exec brainwire \
  brainwire shell --connect 127.0.0.1:7687 --graph demo \
  --node-label Customer --entity-id customer-1 \
  --edge-type IN_SEGMENT --target-label Segment

Use Tab to change views, r to refresh, ? for help and q to quit. The connected TUI is read-only; it shows schema, indexes, memory diagnostics and a bounded relationship sample. Add --lang pt-BR for Portuguese. Explore the TUI.

To stop the demo while keeping its volume:

docker compose -p brainwire-demo -f deploy/compose.demo.yaml down

Bring your data

Source	Start here
Application writes	Upsert nodes and relationships in batches from Python.
DuckDB	Load a local table, then compare snapshots with a resumable journal. DuckDB sync
DuckLake	Load a mapped table and apply changes between pinned versions. DuckLake sync
Obsidian	Preview a small Markdown vault and import notes and wikilinks once into an empty graph. Obsidian example
Python code	Extract local Python structure and trace source links. Code graph example

How it works

Applications write and query over Bolt. The Rust engine checks access, executes transactions and stores graph records in RocksDB. Keep its files on a persistent volume so restarting the container reopens the same graph. A terminal workspace provides read-only inspection.

The standard deployment runs one instance. The separate three-voter Raft setup is experimental. Read the architecture guide for memory, storage and recovery.

How RocksDB stores the graph

RocksDB stores Brainwire's records and indexes as key/value data. Writes first enter a write-ahead log (WAL) on disk and a memtable in memory. A flush writes the memtable into sorted, immutable SST files.

• L0 receives new files; their key ranges can overlap.
• L1 and deeper levels organize files into non-overlapping key ranges within each level. Deeper levels normally hold more data.
• Compaction merges files, keeping the versions still needed by reads and eventually reclaiming obsolete values and deletion markers.

Reads combine memory and the relevant SST files. A shared block cache can avoid disk reads. Compaction uses CPU, disk bandwidth and temporary disk space, so keep the persistent volume and leave room for storage to grow. Storage details

A synthetic benchmark

Three local runs loaded 1 million nodes and 2 million relationships into each engine, checked indexed reads, then restarted after a process kill. The engines ran sequentially, each with a 3 GiB container limit and two CPUs. Brainwire was a locally built v0.20.0-beta.2 candidate, not the published image.

Metric	Brainwire	FalkorDB	Neo4j
Indexed point read, median p95	0.898 ms	0.361 ms	0.724 ms
One-hop read, median p95	0.905 ms	0.367 ms	0.702 ms
Ready after process kill, median	0.862 s	3.175 s	9.286 s

Each p95 summarizes 1,000 warm, serial queries per run; the table shows the median of those three p95 values, not a pooled p95. Each sampled node had two outgoing edges. These are diagnostic results, not production promises. Engines used different protocols, internal memory settings, authentication and durability settings; peak memory was not measured. Read the workload, exact versions, raw result and limitations before comparing or reproducing them.

A newer single-run diagnostic also tests the local v0.21.0-beta.1 candidate with the same graph size. It is reported separately because one run is not comparable to the median above.

See the memory and recovery test results.

Current limits

Brainwire is an experimental beta. Plan a controlled trial:

• Memory: budgets and sampled RSS/cgroup admission can refuse growing queries under pressure. They are partial protection, not a guaranteed process-wide RSS ceiling. Sustained capacity testing is incomplete.
• Search and Cypher: Cypher support is a subset; native ANN and BM25 indexes are not available.
• History: explicit events are supported; automatic revisions and AS OF reads are not.
• Ingestion: DuckDB snapshot sync needs a private persistent journal and exclusive ownership of mapped IDs. DuckLake fencing covers cooperating standalone writers; neither sync provides a graph-wide atomic cutover.
• Security: shared deployments need a service-token policy and verified encryption. Optional native Bolt TLS requires a server certificate, a matching private key and client trust configuration. Rotate the server certificate by restarting. Protected transport
• Distribution: three-voter quorum is experimental. Standard Docker, Kubernetes and Swarm configurations run one instance; multi-machine failover is not qualified.

See memory, security, recovery, replication and benchmark conditions. Synthetic tests are not production SLOs.

Learn more

Getting started · Architecture · Python · Cypher · TUI · Operations

Brainwire is Apache-2.0. Please report bugs with a small synthetic reproduction via GitHub Issues.