When you write
The server checks access, executes a transaction and commits changes through the storage layer. The write-ahead log supports recovery before memory buffers flush into disk tables.
OPEN SOURCE GRAPH DATABASE
A graph database for agent memory
Connect projects, decisions and their evidence. Query the graph with Cypher and give agents the relevant records.
Experimental beta v0.23.0-beta.2 Check the boundaries before a shared deployment
QUICKSTART
Run a local graph.
You need Git and Docker with Compose. The demo creates a graph, starts the server and stores its files in a named volume.
On macOS, you can use a running Colima engine with export DOCKER_CONTEXT=colima. You still need the Docker CLI and Compose plugin.
Terminal
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- Connection
bolt://127.0.0.1:7687- Graph
demo- Data
- Persistent Docker volume
WRITE AND QUERY
Connect from Python.
Install this checkout's helper in a new environment. It connects to Brainwire over Bolt; a public PyPI package is not available yet.
Terminal · repository root
python3 scripts/setup_python.pyRun the example with .venv-brainwire/bin/python while the Docker demo is running. If you chose a different host port, replace 7687 in the connection URL with that port.
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
"""))Result
[{'customer': 'Ada', 'segment': 'beta'}]The demo already declares these types. For your own graph, start with an ontology. Use parameters for values and bounded batches for imports. If a write's commit outcome is unknown, reconcile it before retrying.
AGENT MEMORY
Follow a decision to its source
Save a decision and its source in one transaction. Recall the project's decisions and supporting records from a fresh process. Graph grants and node visibility apply to the read.
Follow the Docker demo to start the company graph and save a decision. Then run this command from the same shell with BW_PORT set.
Terminal · company example
.venv-brainwire/bin/python -m examples.python.agent_memory --uri "bolt://$BW_PORT" \
recall --project project-release --limit 5EXAMPLE CONNECTION
Release → Keep a rollback window → Release reviewThe output includes the source URL recorded in the graph. Verify the source before citing it.
ARCHITECTURE
One engine, clear layers.
Your application connects over Bolt. The Rust engine executes the supported Cypher subset and stores graph records in RocksDB on persistent disk.
YOUR APPLICATIONPython or a Bolt clientWrites · queries · agent context
TERMINAL WORKSPACEInspect the running graphSchema · indexes · memory · sample
Bolt connection
BRAINWIRE · RUSTGraph engine
- PermissionsIdentity · graph grants · node visibility
- QueriesCypher · ontology · indexes · transactions
- Memory controlsQuery reservations · pressure admission
Durable storage
RocksDBWAL · memtables · SST files
Persistent local volumeWhen you read
The engine uses the query's transaction view, visibility rules and available indexes. Query budgets and timeouts bound supported work; some query shapes still scan.
CAPABILITIES
Build with relationships.
Use the graph as a durable data layer. Your application supplies the data, the access model and any AI provider.
Graph + Cypher
Nodes, typed relationships and properties. Read, create, merge, update and delete through the documented Cypher subset.
Query guide →Explicit ontology
Declare labels, allowed connections, properties and descriptions so applications can understand the graph's structure.
Catalog guide →Application timelines
Store explicit event nodes or keyed relationships. The Python example reads event pages by time and identity.
Timeline model →Agent context
Explore ontology paths, narrow provider candidates to explicit IDs, and read visible records and sources. Graph reads use the caller's access controls.
Context API →Incremental writes
Apply updates to a graph in bounded batches. The standalone ingestion examples include checkpoint and recovery workflows.
DuckDB and DuckLake →Visible operations
Inspect indexes, query-memory counters, persistent files and recovery. Keep a tested checkpoint outside the running volume.
Backup and restore →INGESTION
Load a table and keep the graph current
Map source columns to node and relationship properties. Start with a full load, then rerun the importer when the source changes. These examples target standalone graphs.
DuckDB
Compare snapshots of a local table. A private journal tracks batches for resuming interrupted runs. Enable deletions explicitly for an authoritative source.
Sync a DuckDB table →DuckLake
Read a mapped table at pinned snapshots and apply changes in batches. Each batch checks the source lease before writing.
Sync a DuckLake table →For Obsidian, preview a small Markdown vault and import its notes and wikilinks once into a dedicated empty graph. Choose graph permissions before copying notes. Obsidian example →
USE CASES
Where a graph helps.
Company brain
Link documents, projects, people and tickets. Give an application the relationships behind a record, with sources it can reference.
Document → Project → OwnerAgent memory
Store decisions, facts and events using stable identities. Retrieve relevant context and keep access checks in the data path.
Agent → Decision → EvidenceDependencies and timelines
Follow what depends on a service, what changed on a ticket or how a repository connects. Model the events your application needs.
Service → Deployment → EventUse your pipeline, a connector or a model to map source data into the graph.
TERMINAL WORKSPACE
See what is connected.
Open a read-only workspace against the Docker demo. The example below inspects the Customer and Segment written earlier.
Terminal · repository root
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 Segment01Schema
Allowed types and relationships
02Memory
Query reservations and refusals
03Indexes
Declarations and readiness
04Graph sample
Bounded outgoing relationships
Tab changes panes, r refreshes, ? opens help and q exits. Add --lang pt-BR for Portuguese. Protected servers require credentials and grants; memory telemetry requires instance-admin access.
OPERATIONS
Keep data. Check recovery.
A container restart keeps the named volume. A persistent volume is only one copy, so keep a separate backup and test restoring it.
Terminal · Docker demo
# Check that the graph can serve a request
docker compose -p brainwire-demo -f deploy/compose.demo.yaml exec -T brainwire \
brainwire probe --mode ready
# Stop the demo and keep its named volume
docker compose -p brainwire-demo -f deploy/compose.demo.yaml downAdding --volumes to the stop command deletes the demo data. Start the same Compose project again to reuse its volume.
NATIVE CLI
One binary for local tools.
For native use, build from source with Rust and the RocksDB native build dependencies: a C++ compiler, libclang, CMake and pkg-config.
Terminal · repository root
cargo fetch --locked
cargo build --locked --offline -p brainwire-server --bin brainwire
./target/debug/brainwire --helpUse brainwire serve to start the server, brainwire cypher for offline queries and brainwire config show for configuration. The server owns the RocksDB directory while running; use Bolt or the connected TUI rather than opening that directory from another process.
SYNTHETIC BENCHMARK
One workload, three engines.
Three local runs loaded 1 million nodes and 2 million relationships per engine. Brainwire was a locally built v0.20.0-beta.2 candidate, not the published release image.
All three completed indexed read checks and restarted after a process kill. Peak memory was not measured. These results describe a synthetic workload, not a production guarantee.
A newer single-run diagnostic covers the local v0.21.0-beta.1 candidate at the same graph size. One run is not a general performance ranking.
BETA BOUNDARIES
Evaluate the workload you will run.
Start with rebuildable data and a tested backup. The beta has useful capabilities, with important deployment boundaries.
Memory
Budgets and pressure admission reject some work under load. A process-wide RSS ceiling and sustained representative capacity remain unqualified.
Memory guide →Queries and search
Cypher support is a documented subset. Nodes have one fixed label; ANN and BM25 indexes are not native features. Relationship property indexes are experimental and standalone-only.
Language support →History and security
Events are application-managed; native AS OF reads and automatic retention are unavailable. Shared deployments need authentication and verified encryption. Optional native Bolt TLS uses a server certificate and requires a restart to rotate it.
Distribution and evidence
Three-voter quorum is experimental. Standard deployment templates run one instance. Local synthetic tests do not qualify multi-machine failover or production performance.
Replication guide →DOCUMENTATION
Go deeper when you need to.
What does GitHub Pages host?
This static documentation website. It does not run Brainwire or host your graph. Preview it locally with python3 -m http.server 8000 --directory docs-site --bind 127.0.0.1, then open http://127.0.0.1:8000.