# brianluby/rusty-brain architecture

> Architecture diagram of the GitHub repository brianluby/rusty-brain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brianluby/rusty-brain
- Repository: https://github.com/brianluby/rusty-brain

## Overview

rusty-brain is a local-first memory service for AI coding agents, exposed through a CLI, MCP tools, and best-effort capture hooks. The main path sends a memory operation to the local daemon, where the engine enriches and embeds writes or performs hybrid recall against SQLite; recall combines keyword, vector, and graph signals into ranked results. Other documented capabilities include maintenance and review, optional loopback HTTP, portable operations, and agent-hook installation. Relationships below follow the README’s architecture and capability descriptions; unsampled internals are represented only at documented subsystem boundaries.

Main entry points: [`crates/rb-daemon/src/server.rs`](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/server.rs) (Daemon server), [`crates/rb-engine/src/engine.rs`](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-engine/src/engine.rs) (Memory engine), [`crates/rusty-brain/src/cli.rs`](https://github.com/brianluby/rusty-brain/blob/main/crates/rusty-brain/src/cli.rs) (CLI), [`crates/rb-mcp/src/server.rs`](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-mcp/src/server.rs) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_cli["CLI<br/>[cli.rs]"]
  node_mcp["MCP server<br/>[server.rs]"]
  node_hooks["Capture hooks<br/>[capture.rs]"]
  node_installer["Hook installer<br/>[engine.rs]"]
end

subgraph group_runtime["Daemon Runtime"]
  node_daemon["Daemon server<br/>[server.rs]"]
  node_http["Loopback HTTP<br/>[http.rs]"]
  node_protocol["Socket protocol<br/>[client.rs]"]
end

subgraph group_memory["Memory Processing"]
  node_engine["Memory engine<br/>[engine.rs]"]
  node_enrichment["Memory enrichment<br/>[enrich.rs]"]
  node_embeddings["Embedding providers<br/>[provider.rs]"]
  node_search["Hybrid retrieval<br/>[fusion.rs]"]
  node_ranking["Result ranking<br/>[rank.rs]"]
  node_types["Memory contracts<br/>[query.rs]"]
end

subgraph group_persistence["Persistence"]
  node_sqlite[("SQLite memory store<br/>[core.rs]")]
end

subgraph group_operations["Operations"]
  node_jobs["Maintenance jobs<br/>[consolidation.rs]"]
  node_config["Runtime configuration<br/>[lib.rs]"]
  node_cli_ops["Import and export<br/>[import.rs]"]
end

node_user(("CLI user"))
node_agent(("MCP agent"))

node_user -->|"uses"| node_cli
node_agent -->|"calls tools"| node_mcp
node_cli -->|"sends operations"| node_daemon
node_mcp -->|"proxies requests"| node_daemon
node_hooks -->|"captures via socket"| node_daemon
node_installer -->|"installs hooks"| node_hooks
node_daemon -->|"dispatches operations"| node_engine
node_cli -->|"uses socket client"| node_protocol
node_protocol -->|"sends framed requests"| node_daemon
node_http -->|"serves local requests"| node_daemon
node_engine -->|"enriches writes"| node_enrichment
node_engine -->|"embeds memories"| node_embeddings
node_engine -->|"stores and reads"| node_sqlite
node_engine -->|"retrieves candidates"| node_search
node_search -->|"fuses and ranks"| node_ranking
node_ranking -->|"returns results"| node_types
node_daemon -->|"runs maintenance"| node_jobs
node_daemon -->|"resolves settings"| node_config
node_cli -->|"offers data operations"| node_cli_ops

click node_cli "https://github.com/brianluby/rusty-brain/blob/main/crates/rusty-brain/src/cli.rs"
click node_mcp "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-mcp/src/server.rs"
click node_hooks "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-hooks/src/capture.rs"
click node_installer "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-install/src/engine.rs"
click node_daemon "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/server.rs"
click node_http "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/http.rs"
click node_protocol "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-proto/src/client.rs"
click node_engine "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-engine/src/engine.rs"
click node_enrichment "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-engine/src/enrich.rs"
click node_embeddings "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-embed/src/provider.rs"
click node_search "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-search/src/fusion.rs"
click node_ranking "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-search/src/rank.rs"
click node_types "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-types/src/query.rs"
click node_sqlite "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-store/src/store/core.rs"
click node_jobs "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/jobs/consolidation.rs"
click node_config "https://github.com/brianluby/rusty-brain/blob/main/crates/rb-config/src/lib.rs"
click node_cli_ops "https://github.com/brianluby/rusty-brain/blob/main/crates/rusty-brain/src/import.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp,node_hooks,node_installer,node_user toneBlue
class node_daemon,node_http,node_protocol toneAmber
class node_engine,node_enrichment,node_embeddings,node_search,node_ranking,node_types toneMint
class node_sqlite toneRose
class node_jobs,node_config,node_cli_ops,node_agent toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/brianluby/rusty-brain/blob/main/crates/rusty-brain/src/cli.rs): `crates/rusty-brain/src/cli.rs`
- [MCP server](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-mcp/src/server.rs): `crates/rb-mcp/src/server.rs`
- [Capture hooks](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-hooks/src/capture.rs): `crates/rb-hooks/src/capture.rs`
- [Hook installer](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-install/src/engine.rs): `crates/rb-install/src/engine.rs`

### Daemon Runtime

- [Daemon server](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/server.rs): `crates/rb-daemon/src/server.rs`
- [Loopback HTTP](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/http.rs): `crates/rb-daemon/src/http.rs`
- [Socket protocol](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-proto/src/client.rs): `crates/rb-proto/src/client.rs`

### Memory Processing

- [Memory engine](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-engine/src/engine.rs): `crates/rb-engine/src/engine.rs`
- [Memory enrichment](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-engine/src/enrich.rs): `crates/rb-engine/src/enrich.rs`
- [Embedding providers](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-embed/src/provider.rs): `crates/rb-embed/src/provider.rs`
- [Hybrid retrieval](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-search/src/fusion.rs): `crates/rb-search/src/fusion.rs`
- [Result ranking](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-search/src/rank.rs): `crates/rb-search/src/rank.rs`
- [Memory contracts](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-types/src/query.rs): `crates/rb-types/src/query.rs`

### Persistence

- [SQLite memory store](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-store/src/store/core.rs): `crates/rb-store/src/store/core.rs`

### Operations

- [Maintenance jobs](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-daemon/src/jobs/consolidation.rs): `crates/rb-daemon/src/jobs/consolidation.rs`
- [Runtime configuration](https://github.com/brianluby/rusty-brain/blob/main/crates/rb-config/src/lib.rs): `crates/rb-config/src/lib.rs`
- [Import and export](https://github.com/brianluby/rusty-brain/blob/main/crates/rusty-brain/src/import.rs): `crates/rusty-brain/src/import.rs`

### Other components

- **CLI user**
- **MCP agent**

## Connections

- CLI user → CLI: uses
- MCP agent → MCP server: calls tools
- CLI → Daemon server: sends operations
- MCP server → Daemon server: proxies requests
- Capture hooks → Daemon server: captures via socket
- Hook installer → Capture hooks: installs hooks
- Daemon server → Memory engine: dispatches operations
- CLI → Socket protocol: uses socket client
- Socket protocol → Daemon server: sends framed requests (evidence: `crates/rb-proto/src/client.rs`)
- Loopback HTTP → Daemon server: serves local requests (evidence: `crates/rb-daemon/src/http.rs`)
- Memory engine → Memory enrichment: enriches writes (evidence: `crates/rb-engine/src/engine.rs`)
- Memory engine → Embedding providers: embeds memories
- Memory engine → SQLite memory store: stores and reads
- Memory engine → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → Result ranking: fuses and ranks
- Result ranking → Memory contracts: returns results
- Daemon server → Maintenance jobs: runs maintenance
- Daemon server → Runtime configuration: resolves settings (evidence: `crates/rb-config/src/lib.rs`)
- CLI → Import and export: offers data operations
