# bassprofressor-lab/cyberbrain architecture

> Architecture diagram of the GitHub repository bassprofressor-lab/cyberbrain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bassprofressor-lab/cyberbrain
- Repository: https://github.com/bassprofressor-lab/cyberbrain

## Overview

Cyberbrain is a local-first, cited memory system for AI coding agents. Users enter through the CLI, agent hooks, MCP, or the web interface; those adapters share the application composition layer, which supports note operations and retrieval. Retrieval combines word and semantic search and reports citations and caveats. Separate capabilities cover model-assisted features, policy and audit controls, and optional team collection. The README documents the product workflow and capabilities; several internal subsystem connections are not visible in the sampled code, so those links are omitted or marked unverified.

Main entry points: [`crates/cyberbrain/src/app.rs`](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/app.rs) (Application composition), [`crates/cyberbrain/src/serve/mod.rs`](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/serve/mod.rs) (Web API), [`crates/cyberbrain-index/src/index.rs`](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-index/src/index.rs) (Hybrid index), [`crates/cyberbrain/src/main.rs`](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/main.rs) (CLI dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI dispatch<br/>[main.rs]"]
  node_hooks["Agent hooks<br/>[mod.rs]"]
  node_mcp["MCP server<br/>[mod.rs]"]
  node_web["Web API<br/>[mod.rs]"]
  node_ui["Web interface<br/>[App.tsx]"]
end

subgraph group_memory["Memory and retrieval"]
  node_app["Application composition<br/>[app.rs]"]
  node_store[("Markdown note store<br/>[store.rs]")]
  node_code["Code scanning<br/>[lib.rs]"]
  node_index[("Hybrid index<br/>[index.rs]")]
  node_vectors["Vector retrieval<br/>[vectors.rs]"]
end

subgraph group_intelligence["Model features"]
  node_embed["Local embeddings<br/>[lib.rs]"]
  node_llm["Inference client<br/>[client.rs]"]
  node_llm_tasks["Model features<br/>[tasks.rs]"]
end

subgraph group_governance["Trust and compliance"]
  node_policy["Policy controls<br/>[policy.rs]"]
  node_egress["Egress controls<br/>[mod.rs]"]
  node_audit[("Audit trail<br/>[audit.rs]")]
end

subgraph group_team["Team collection"]
  node_hub_client["Hub delivery<br/>[client.rs]"]
  node_hub_service["Hub collector<br/>[service.rs]"]
  node_hub_store[("Hub storage<br/>[store.rs]")]
  node_hub(("Remote hub"))
end

node_user(("Operator or agent"))

node_user -->|"issues commands"| node_cli
node_user -->|"triggers events"| node_hooks
node_user -->|"uses tools"| node_mcp
node_user -->|"opens page"| node_web
node_web -->|"serves interface"| node_ui
node_cli -->|"dispatches to"| node_app
node_hooks -.->|"adapts requests"| node_app
node_mcp -.->|"adapts requests"| node_app
node_web -.->|"adapts requests"| node_app
node_app -.->|"reads and writes"| node_store
node_app -.->|"retrieves and updates"| node_index
node_app -.->|"enforces controls"| node_policy
node_app -.->|"records events"| node_audit
node_code -.->|"supplies scan content"| node_index
node_index -->|"uses vectors"| node_vectors
node_embed -.->|"creates embeddings"| node_vectors
node_app -.->|"requests model features"| node_llm_tasks
node_llm_tasks -->|"calls client"| node_llm
node_llm -->|"checks permission"| node_egress
node_policy -->|"configures register"| node_egress
node_hub_client -->|"delivers audit trail"| node_hub
node_hub_service -.->|"collects records"| node_hub_store
node_hub -.->|"sends records"| node_hub_service

click node_cli "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/main.rs"
click node_hooks "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hook/mod.rs"
click node_mcp "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/mcp/mod.rs"
click node_web "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/serve/mod.rs"
click node_ui "https://github.com/bassprofressor-lab/cyberbrain/blob/main/ui/src/App.tsx"
click node_app "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/app.rs"
click node_store "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-core/src/store.rs"
click node_code "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-code/src/lib.rs"
click node_index "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-index/src/index.rs"
click node_vectors "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-index/src/vectors.rs"
click node_embed "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-embed/src/lib.rs"
click node_llm "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-llm/src/client.rs"
click node_llm_tasks "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-llm/src/tasks.rs"
click node_policy "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-policy/src/policy.rs"
click node_egress "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-policy/src/egress/mod.rs"
click node_audit "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-policy/src/audit.rs"
click node_hub_client "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hub/client.rs"
click node_hub_service "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hub/service.rs"
click node_hub_store "https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hub/store.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_hooks,node_mcp,node_web,node_ui toneBlue
class node_app,node_store,node_code,node_index,node_vectors toneAmber
class node_embed,node_llm,node_llm_tasks toneMint
class node_policy,node_egress,node_audit toneRose
class node_hub_client,node_hub_service,node_hub_store,node_hub,node_user toneIndigo
```

## Components

### User interfaces

- [CLI dispatch](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/main.rs): `crates/cyberbrain/src/main.rs`
- [Agent hooks](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hook/mod.rs): `crates/cyberbrain/src/hook/mod.rs`
- [MCP server](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/mcp/mod.rs): `crates/cyberbrain/src/mcp/mod.rs`
- [Web API](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/serve/mod.rs): `crates/cyberbrain/src/serve/mod.rs`
- [Web interface](https://github.com/bassprofressor-lab/cyberbrain/blob/main/ui/src/App.tsx): `ui/src/App.tsx`

### Memory and retrieval

- [Application composition](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/app.rs): `crates/cyberbrain/src/app.rs`
- [Markdown note store](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-core/src/store.rs): `crates/cyberbrain-core/src/store.rs`
- [Code scanning](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-code/src/lib.rs): `crates/cyberbrain-code/src/lib.rs`
- [Hybrid index](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-index/src/index.rs): `crates/cyberbrain-index/src/index.rs`
- [Vector retrieval](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-index/src/vectors.rs): `crates/cyberbrain-index/src/vectors.rs`

### Model features

- [Local embeddings](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-embed/src/lib.rs): `crates/cyberbrain-embed/src/lib.rs`
- [Inference client](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-llm/src/client.rs): `crates/cyberbrain-llm/src/client.rs`
- [Model features](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-llm/src/tasks.rs): `crates/cyberbrain-llm/src/tasks.rs`

### Trust and compliance

- [Policy controls](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-policy/src/policy.rs): `crates/cyberbrain-policy/src/policy.rs`
- [Egress controls](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-policy/src/egress/mod.rs): `crates/cyberbrain-policy/src/egress/mod.rs`
- [Audit trail](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain-policy/src/audit.rs): `crates/cyberbrain-policy/src/audit.rs`

### Team collection

- [Hub delivery](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hub/client.rs): `crates/cyberbrain/src/hub/client.rs`
- [Hub collector](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hub/service.rs): `crates/cyberbrain/src/hub/service.rs`
- [Hub storage](https://github.com/bassprofressor-lab/cyberbrain/blob/main/crates/cyberbrain/src/hub/store.rs): `crates/cyberbrain/src/hub/store.rs`
- **Remote hub**

### Other components

- **Operator or agent**

## Connections

- Operator or agent → CLI dispatch: issues commands (evidence: `README.md`)
- Operator or agent → Agent hooks: triggers events (evidence: `README.md`)
- Operator or agent → MCP server: uses tools (evidence: `README.md`)
- Operator or agent → Web API: opens page (evidence: `README.md`)
- Web API → Web interface: serves interface (evidence: `README.md`)
- CLI dispatch → Application composition: dispatches to (evidence: `crates/cyberbrain/src/main.rs`)
- Agent hooks → Application composition: adapts requests
- MCP server → Application composition: adapts requests
- Web API → Application composition: adapts requests
- Application composition → Markdown note store: reads and writes
- Application composition → Hybrid index: retrieves and updates
- Application composition → Policy controls: enforces controls
- Application composition → Audit trail: records events
- Code scanning → Hybrid index: supplies scan content
- Hybrid index → Vector retrieval: uses vectors (evidence: `crates/cyberbrain-index/src/index.rs`)
- Local embeddings → Vector retrieval: creates embeddings
- Application composition → Model features: requests model features
- Model features → Inference client: calls client (evidence: `crates/cyberbrain-llm/src/tasks.rs`)
- Inference client → Egress controls: checks permission (evidence: `crates/cyberbrain-llm/src/client.rs`)
- Policy controls → Egress controls: configures register (evidence: `crates/cyberbrain-policy/src/egress/mod.rs`)
- Hub delivery → Remote hub: delivers audit trail (evidence: `README.md`)
- Hub collector → Hub storage: collects records
- Remote hub → Hub collector: sends records
