rusty-brain

rusty-brain

Local-first, persistent memory for AI coding agents — a Rust daemon with hybrid (vector + keyword + graph) retrieval over SQLite, exposed via MCP and a CLI.

Status: early development. The pieces described below are implemented and covered by unit and integration tests, but the project has only had basic correctness testing. It has not been performance-, scale-, or capability-tested, and retrieval quality has not been measured against real embedding models at any meaningful corpus size. Treat it as a work in progress, not a finished product. Interfaces and on-disk format may change.

What it is

rusty-brain is a small memory substrate that an AI coding agent (or several, concurrently) can write notes to and recall from. It runs as a single local daemon backed by one SQLite database, and is reachable two ways:

• a command-line interface (rusty-brain), and
• an MCP server (rusty-brain mcp) that exposes memory operations as tools to any MCP-capable agent.

Memories are scoped to a namespace (global, per-project, or per-session), carry lightweight enrichment (summary, keywords, tags, type, importance), and can be linked to one another. Recall fuses full-text search, vector similarity, and graph proximity into a single ranked result set.

It is deliberately a substrate, not an orchestrator: it stores and retrieves memory for agents but has no notion of tasks, scheduling, or agent lifecycles.

Background

Before building this, we surveyed a number of existing agentic-memory systems. They informed the design — our recency/importance/relevance ranking and our treatment of consolidation and forgetting are well-trodden ideas — but their architectures did not align with our design criteria. We wanted something local-first, built from small purpose-built crates with compiler-enforced boundaries, with a single source of truth on disk and a lean default dependency footprint, rather than a large general-purpose system. rusty-brain is that focused rebuild. The principles we settled on:

• A workspace of focused crates, never a monolith — boundaries enforced by the compiler, heavy/optional pieces behind feature flags or separate crates.
• One database, one transaction, one source of truth — memories, full-text index, and vectors live in a single SQLite file; writes serialize through one thread, reads run concurrently over WAL.
• Fail-closed where it matters, fail-open where it shouldn't — namespace isolation and the embedding-dimension contract refuse to run on doubt; best-effort capture hooks never block or break an agent session.
• Reproducible from git — file-discovered, checksummed migrations; CI rebuilds a fresh database from committed SQL and exercises every query path.

Architecture (high level)

flowchart TB
  subgraph clients["Clients"]
    CLI["rusty-brain CLI"]
    AGENT["MCP-capable agent"]
    HOOKS["rusty-brain-hooks<br/>(capture, fail-open)"]
  end

  AGENT -->|"JSON-RPC over stdio"| MCPSRV["rusty-brain mcp<br/>(MCP server)"]

  subgraph daemon["rusty-brain daemon (one local process)"]
    ENGINE["engine<br/>enrich → embed → store → link → recall"]
    WRITER["single writer thread"]
    POOL["read pool (WAL)"]
    BUS["change broadcast"]
  end

  CLI -->|"Unix socket"| daemon
  MCPSRV -->|"Unix socket"| daemon
  HOOKS -->|"Unix socket"| daemon

  ENGINE --> WRITER
  ENGINE --> POOL
  ENGINE --> EMB["embeddings<br/>deterministic · Voyage · local ONNX"]
  WRITER --> DB[("SQLite + sqlite-vec<br/>memories · vectors · links · FTS")]
  POOL --> DB
  WRITER --> BUS

  classDef client fill:#e3f2fd,stroke:#4781c4,color:#0d2b4e;
  classDef proc fill:#ede7f6,stroke:#7e57c2,color:#311b54;
  classDef store fill:#fff3e0,stroke:#ef8e3a,color:#5a3209;
  classDef embed fill:#e8f5e9,stroke:#52a45a,color:#1b3d20;
  classDef accent fill:#fce4ec,stroke:#c96198,color:#5a1535;
  class CLI,AGENT,HOOKS,MCPSRV client;
  class ENGINE,WRITER,POOL proc;
  class EMB embed;
  class DB store;
  class BUS accent;
  style clients fill:#f2f7fd,stroke:#9bbbe0,color:#0d2b4e;
  style daemon fill:#f6f3fb,stroke:#b9a7da,color:#311b54;

A deeper walkthrough — component boundaries, the write and recall data flows, and the namespace model — lives in docs/ARCHITECTURE.md.

What works today

Implemented and test-covered (correctness only — see Testing):