# hbar-systems/brainfoundry-nous architecture

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

- Interactive diagram: https://gitdiagram.com/hbar-systems/brainfoundry-nous
- Repository: https://github.com/hbar-systems/brainfoundry-nous

## Overview

BrainFoundry is a self-hosted personal AI: a user chats through the console, the FastAPI brain answers using a configured model and retrieved memory, and optional tools and integrations extend that loop. Separate product branches cover document ingestion, research, tasks, installable apps, and federation. BrainKernel (NodeOS) supplies permit and mutation governance. The README documents the major capabilities; sampled source confirms selected implementation details, but many endpoint and subsystem connections are documented rather than shown in the excerpts.

Main entry points: [`api/main.py`](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/main.py) (Chat API), [`ui/pages/index.js`](https://github.com/hbar-systems/brainfoundry-nous/blob/main/ui/pages/index.js) (Web console), [`nodeos/main.py`](https://github.com/hbar-systems/brainfoundry-nous/blob/main/nodeos/main.py) (BrainKernel NodeOS), [`scripts/ingest_folder.py`](https://github.com/hbar-systems/brainfoundry-nous/blob/main/scripts/ingest_folder.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_console["Web console<br/>[index.js]"]
end

subgraph group_brain["Brain runtime"]
  node_chat["Chat API<br/>[main.py]"]
  node_providers["Model providers<br/>[providers.py]"]
end

subgraph group_memory["Memory and knowledge"]
  node_embeddings["Embeddings<br/>[model.py]"]
  node_vectorstore[("Postgres pgvector")]
  node_ingest["Document ingestion<br/>[ingest_folder.py]"]
  node_memorytypes["Memory trust labels<br/>[memory_type.py]"]
end

subgraph group_capabilities["Tools and integrations"]
  node_research["Deep research<br/>[research.py]"]
  node_websearch["Web search tool<br/>[web_search.py]"]
  node_toolregistry["Tool dispatch<br/>[__init__.py]"]
  node_integrations["External integrations"]
  node_tasks["Tasks and reminders<br/>[tasks_store.py]"]
  node_apps["Installable apps<br/>[apps.py]"]
end

subgraph group_governance["Governance and federation"]
  node_nodeos["BrainKernel NodeOS<br/>[main.py]"]
  node_identity["Identity and permits<br/>[core.py]"]
  node_audit["Append-only audit<br/>[audit.py]"]
  node_federation["Brain federation"]
end

node_owner(("Brain owner"))
node_localmodel["Ollama"]

node_owner -->|"uses"| node_console
node_console -->|"sends chat"| node_chat
node_chat -->|"calls models"| node_providers
node_providers -->|"falls back"| node_localmodel
node_chat -->|"retrieves memory"| node_vectorstore
node_ingest -->|"stores documents"| node_vectorstore
node_ingest -.->|"embeds content"| node_embeddings
node_chat -.->|"embeds queries"| node_embeddings
node_memorytypes -.->|"labels memory"| node_vectorstore
node_chat -->|"dispatches tools"| node_toolregistry
node_toolregistry -->|"runs tool"| node_websearch
node_research -->|"searches web"| node_websearch
node_chat -->|"offers integrations"| node_integrations
node_chat -->|"manages tasks"| node_tasks
node_console -->|"installs apps"| node_apps
node_chat -->|"checks authority"| node_nodeos
node_nodeos -->|"issues permits"| node_identity
node_nodeos -->|"records commands"| node_audit
node_chat -->|"records model calls"| node_audit
node_federation -.->|"publishes to peers"| node_federation

click node_console "https://github.com/hbar-systems/brainfoundry-nous/blob/main/ui/pages/index.js"
click node_chat "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/main.py"
click node_providers "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/providers.py"
click node_embeddings "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/embeddings/model.py"
click node_ingest "https://github.com/hbar-systems/brainfoundry-nous/blob/main/scripts/ingest_folder.py"
click node_memorytypes "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/memory_type.py"
click node_research "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/research.py"
click node_websearch "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tools/web_search.py"
click node_toolregistry "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tools/__init__.py"
click node_integrations "https://github.com/hbar-systems/brainfoundry-nous/tree/main/api/integrations"
click node_tasks "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tasks_store.py"
click node_apps "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/apps.py"
click node_nodeos "https://github.com/hbar-systems/brainfoundry-nous/blob/main/nodeos/main.py"
click node_identity "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/identity/core.py"
click node_audit "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tools/audit.py"
click node_federation "https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/federation_publisher.py"

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_console toneBlue
class node_chat,node_providers toneAmber
class node_embeddings,node_vectorstore,node_ingest,node_memorytypes toneMint
class node_research,node_websearch,node_toolregistry,node_integrations,node_tasks,node_apps toneRose
class node_nodeos,node_identity,node_audit,node_federation,node_owner,node_localmodel toneIndigo
```

## Components

### User experience

- [Web console](https://github.com/hbar-systems/brainfoundry-nous/blob/main/ui/pages/index.js): `ui/pages/index.js`

### Brain runtime

- [Chat API](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/main.py): `api/main.py`
- [Model providers](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/providers.py): `api/providers.py`

### Memory and knowledge

- [Embeddings](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/embeddings/model.py): `api/embeddings/model.py`
- **Postgres pgvector**
- [Document ingestion](https://github.com/hbar-systems/brainfoundry-nous/blob/main/scripts/ingest_folder.py): `scripts/ingest_folder.py`
- [Memory trust labels](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/memory_type.py): `api/memory_type.py`

### Tools and integrations

- [Deep research](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/research.py): `api/research.py`
- [Web search tool](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tools/web_search.py): `api/tools/web_search.py`
- [Tool dispatch](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tools/__init__.py): `api/tools/__init__.py`
- [External integrations](https://github.com/hbar-systems/brainfoundry-nous/tree/main/api/integrations): `api/integrations`
- [Tasks and reminders](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tasks_store.py): `api/tasks_store.py`
- [Installable apps](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/apps.py): `api/apps.py`

### Governance and federation

- [BrainKernel NodeOS](https://github.com/hbar-systems/brainfoundry-nous/blob/main/nodeos/main.py): `nodeos/main.py`
- [Identity and permits](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/identity/core.py): `api/identity/core.py`
- [Append-only audit](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/tools/audit.py): `api/tools/audit.py`
- [Brain federation](https://github.com/hbar-systems/brainfoundry-nous/blob/main/api/federation_publisher.py): `api/federation_publisher.py`

### Other components

- **Brain owner**
- **Ollama**

## Connections

- Brain owner → Web console: uses
- Web console → Chat API: sends chat
- Chat API → Model providers: calls models (evidence: `api/main.py`)
- Model providers → Ollama: falls back
- Chat API → Postgres pgvector: retrieves memory
- Document ingestion → Postgres pgvector: stores documents
- Document ingestion → Embeddings: embeds content
- Chat API → Embeddings: embeds queries (evidence: `api/main.py`)
- Memory trust labels → Postgres pgvector: labels memory
- Chat API → Tool dispatch: dispatches tools (evidence: `api/main.py`)
- Tool dispatch → Web search tool: runs tool (evidence: `api/tools/web_search.py`)
- Deep research → Web search tool: searches web (evidence: `api/research.py`)
- Chat API → External integrations: offers integrations (evidence: `api/main.py`)
- Chat API → Tasks and reminders: manages tasks (evidence: `api/main.py`)
- Web console → Installable apps: installs apps (evidence: `api/apps.py`)
- Chat API → BrainKernel NodeOS: checks authority (evidence: `api/main.py`)
- BrainKernel NodeOS → Identity and permits: issues permits
- BrainKernel NodeOS → Append-only audit: records commands
- Chat API → Append-only audit: records model calls (evidence: `api/main.py`)
- Brain federation → Brain federation: publishes to peers