Quickstart

Get Brain Server running on your machine and make your first recall in minutes. It builds from source with the Rust toolchain; there are no external services.

Source: the repo is github.com/markfietje/brain-server — clone it below, or browse the releases. The full install runbooks are Deployment (bare metal + launchd) and Docker. This page is the 5-minute run.

Prerequisites

• Rust (stable) with cargo. Get it at rustup.rs.
• macOS or Linux (any architecture Rust compiles to; ARM/Linux recommended for edge).

0. Get the code

git clone https://github.com/markfietje/brain-server.git
cd brain-server

1. Build

# Build the server and the operator CLIs
cargo build --release --features bench

# Optionally include the GitHub connector binary
cargo build --release --features bench,connector-github

The release profile uses opt-level = 2 (speed), lto = "fat", codegen-units = 1, strip = true, and panic = "abort".

2. Run

./target/release/brain-server

The server binds to 127.0.0.1:8765 by default and creates a SQLite database at the configured path (default ~/.openclaw/workspace/brain.db, or BRAIN_DB_PATH).

# Liveness + stats
curl http://localhost:8765/health
curl http://localhost:8765/stats

The server refuses to bind 0.0.0.0 unless BIND_PUBLIC=1. Loopback-safe by default.

3. Ingest

Ingest a markdown document. [[relation::entity]] links build the knowledge graph:

curl -X POST http://localhost:8765/ingest/markdown \
  -H 'Content-Type: application/json' \
  -d '{"title":"Bignay","content":"Bignay is [[alternative_to::blueberry]]. It has [[has_property::antioxidants]]."}'

For structured data, POST /ingest accepts explicit entities and relations.

4. Review — the human-in-the-loop gate

Write-back is human-gated by default. A candidate is scored, not stored — it becomes memory only when a human approves it:

# Propose a fragment (scored; creates NO knowledge row)
curl -X POST http://localhost:8765/ingest/proposal \
  -H 'Content-Type: application/json' \
  -d '{"content":"Bignay is an antioxidant-rich alternative to blueberry."}'

# List the pending queue
curl http://localhost:8765/proposals?status=pending

# The human decides — approve into memory (optionally superseding a conflicting chunk)
curl -X POST http://localhost:8765/proposals/1/approve

# …or reject, audited, never deleted (note: the server records the rejection,
# not a free-text reason — any ?reason= is accepted but not persisted)
curl -X POST http://localhost:8765/proposals/1/reject

The web client at /app puts this in a control room: the Review panel (scoring breakdown + sourcing prompt + screen verdict + raw evidence), the Memory Operations panel (live SLA clocks + flagged inventory + gate health), and the Agent Memory Register (a read-only provenance ledger). See Human in the loop for how to evaluate a proposal well — not just clear the queue.

5. Recall

Structured recall returns ranked evidence with provenance:

curl -X POST http://localhost:8765/recall \
  -H 'Content-Type: application/json' \
  -d '{"query":"blueberry alternative","provenance":true}'

Explore the knowledge graph:

curl http://localhost:8765/graph/entity/bignay
curl 'http://localhost:8765/graph/traverse?start=bignay&max_depth=2'

6. Use the CLI

The brain binary gives you the same surface from a terminal:

./target/release/brain status          # health + stats
./target/release/brain query "blueberry alternative" --k 3
./target/release/brain explain "blueberry alternative"
./target/release/brain ingest-dir ./vault

7. Run as a service (macOS)

For a persistent install managed by launchd:

scripts/install-service.sh

This builds the release binaries, installs them to ~/.local/bin, relocates the auth token to a 0600 file, restarts the service, and waits for /health. See Deployment for details and the client GUI.

Next steps

1. Configure authentication and other tunables in Deployment.
2. Run it in production on Docker or a reverse-proxy SSO (proxy-sso).
3. Understand the retrieval pipeline in Architecture.
4. Review the security posture in Security.
5. Learn the write-back review job in Human in the loop.

All of it lives in the brain-server repository — star it, watch for releases, or open an issue for anything that surprises you.