Brain Server

A local-first semantic-memory and knowledge-graph server for AI agents. Runs on a 4 GB ARM device drawing < 5 W — no GPU, no cloud, no per-query cost.

Static (no-neural-net) embeddings via model2vec / minishlab/potion-retrieval-32M make recall essentially free on CPU. Designed for edge hardware (Jetson Nano, Raspberry Pi 5, mini PC) but runs anywhere Rust compiles. The competitive wedge vs. cloud memory services (Zep, Mem0, Letta Cloud): zero per-query cost, zero data egress, zero network latency on recall.

Version	1.10.0 "Procedural" (ordered-step procedures, deterministic categorize/decide)
Model	minishlab/potion-retrieval-32M (512-dim, static, ~120 MiB RSS)
Stack	Rust 2021 · Axum · rusqlite (WAL) · r2d2 · tokio
Power envelope	< 5 W idle on Jetson Nano (the selling point)
Latency	sub-50ms p99 recall on the reference device
Documentation	API Contract · GET /openapi.yaml live · Technical Spec

---

Features

• Hybrid retrieval — vector KNN (vec0) + lexical FTS5 (BM25) fused via Reciprocal Rank Fusion, with deterministic PRF query expansion and full per-result provenance.
• Structured query — QueryDoc with LexSpec (phrases, exclusions, code paths), multi-source OR scope, temporal since/as_of predicates.
• Temporal evidence — every ingest stamps observed_at / valid_from / valid_to / authority. Point-in-time recall returns the revision active at a timestamp. RecallHit.conflict flags contradictory/superseded hits.
• Knowledge graph — entities and relationships extracted from [[relation::entity]] syntax in markdown. Traverse, query, and follow links. Multi-hop explanations via /graph/traverse?explain=true (structured hop chains); edge-type filter via ?kind=.
• Source lifecycle — every chunk carries provenance (source + immutable revision). Connectors backfill external sources through a supervised pipeline; POST /reconcile sweeps orphans from deleted sources.
• Connectors — supervised ingesters (GitHub issues via App auth) that backfill through the existing source/revision pipeline. Extensible connector contract.
• Prompt-injection quarantine — suspicious content stored but excluded from retrieval until reviewed.
• Append-only audit log — ingest and auth-denial events recorded hash-only.
• Encrypted backup/restore — AES-256-GCM, checksummed backups.
• OpenAI-compatible embeddings — POST /v1/embeddings.
• MCP server — mcp binary exposes search/recall/ingest as MCP tools.
• Calibrated abstention (v1.5) — when retrieval quality is too low to support a claim, /recall returns {decision: "low_confidence", hits: []} instead of top-1 garbage.
• Span verification (v1.5) — POST /verify checks whether a claim is supported by a chunk's actual text (deterministic lexical match, no LLM).
• Self-correction (v1.6) — operator-approved supersedes links atomically expire the prior fact; historical recall (?at=<past>) still returns it. brain resolve + brain check-consistency surface action items.
• Reviewable proposals (v1.8) — /consolidate/propose detects exact duplicates, subject conflicts, unresolved contradictions, stale sources (deleted vault files), and near-duplicates (cosine > 0.95). brain undo-resolve reverses prior resolutions without retrieval regression.
• Opt-in anticipation (v1.9) — POST /suggest returns related-but-not-surfaced chunks (tagged reason: "anticipated"); POST /suggest/feedback records accept/dismiss; GET /suggest/metrics reports the false-positive rate. No push, no decay, no hidden personalization — the agent asks explicitly. BRAIN_SUGGEST_ENABLED=false disables the surface.

---

Quick start

# Build all binaries
cargo build --release --features bench
# or: cargo build --release --features bench,connector-github

# Run the server