# byteclub-labs/gbrain architecture

> Architecture diagram of the GitHub repository byteclub-labs/gbrain, 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/byteclub-labs/gbrain
- Repository: https://github.com/byteclub-labs/gbrain

## Overview

GBrain is an agent-oriented knowledge brain: sources become stored, chunked memory; agents retrieve it through search and graph capabilities, with synthesis and gap analysis documented as the user-facing result. It also supports context injection, autonomous enrichment/consolidation, MCP access, and an admin UI. The README documents several of these product behaviors, but their full implementation paths were not sampled; edges based on that documentation cite the README. Unverified internal links are omitted.

Main entry points: [`src/core/engine.ts`](https://github.com/byteclub-labs/gbrain/blob/master/src/core/engine.ts) (Brain engine API), [`src/core/search/sql-ranking.ts`](https://github.com/byteclub-labs/gbrain/blob/master/src/core/search/sql-ranking.ts) (Search ranking), [`src/core/ingestion`](https://github.com/byteclub-labs/gbrain/tree/master/src/core/ingestion) (Source ingestion), [`src/core/chunkers/recursive.ts`](https://github.com/byteclub-labs/gbrain/blob/master/src/core/chunkers/recursive.ts) (Chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Access interfaces"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_admin["Admin console<br/>[App.tsx]"]
end

subgraph group_ingest["Memory ingestion"]
  node_ingestion["Source ingestion"]
  node_chunking["Chunking<br/>[recursive.ts]"]
  node_contextual["Contextual retrieval prep"]
  node_linking["Entity links<br/>[link-extraction.ts]"]
end

subgraph group_retrieval["Retrieval and answers"]
  node_search["Search ranking<br/>[sql-ranking.ts]"]
  node_embedding["Embedding search"]
  node_reflex["Contextual recall"]
  node_answer["Synthesis and gap analysis"]
end

subgraph group_storage["Memory and storage"]
  node_engine["Brain engine API<br/>[engine.ts]"]
  node_pglite[("PGLite store<br/>[pglite-engine.ts]")]
  node_postgres[("Postgres store<br/>[postgres-engine.ts]")]
  node_graph["Knowledge graph<br/>[link-extraction.ts]"]
  node_facts["Fenced memory<br/>[takes-fence.ts]"]
end

subgraph group_operations["Autonomous operations"]
  node_ai["AI gateway<br/>[gateway.ts]"]
  node_cycle["Dream cycle<br/>[cycle.ts]"]
  node_context["Context engine<br/>[context-engine.ts]"]
  node_migration["Schema migrations<br/>[migrate.ts]"]
end

node_person(("User or agent"))

node_person -.->|"runs commands"| node_cli
node_person -.->|"calls tools"| node_mcp
node_person -.->|"manages brain"| node_admin
node_person -.->|"provides sources"| node_ingestion
node_ingestion -.->|"chunks pages"| node_chunking
node_ingestion -->|"extracts edges"| node_linking
node_ingestion -.->|"writes pages"| node_engine
node_chunking -.->|"stores chunks"| node_engine
node_contextual -->|"generates synopses"| node_ai
node_contextual -.->|"processes chunks"| node_chunking
node_person -->|"asks questions"| node_search
node_search -.->|"uses vectors"| node_embedding
node_search -.->|"queries memory"| node_engine
node_search -->|"traverses links"| node_graph
node_search -->|"synthesizes evidence"| node_answer
node_answer -->|"returns cited answer"| node_person
node_mcp -->|"dispatches operations"| node_engine
node_engine -->|"implemented by"| node_pglite
node_engine -->|"implemented by"| node_postgres
node_postgres -->|"runs migrations"| node_migration
node_pglite -->|"uses migrations"| node_migration
node_cycle -.->|"consolidates memory"| node_engine
node_cycle -.->|"uses models"| node_ai
node_context -->|"builds recall"| node_reflex
node_reflex -->|"resolves entities"| node_engine
node_engine -.->|"indexes memory"| node_facts

click node_cli "https://github.com/byteclub-labs/gbrain/blob/master/src/cli.ts"
click node_mcp "https://github.com/byteclub-labs/gbrain/blob/master/src/mcp/server.ts"
click node_admin "https://github.com/byteclub-labs/gbrain/blob/master/admin/src/App.tsx"
click node_ingestion "https://github.com/byteclub-labs/gbrain/tree/master/src/core/ingestion"
click node_chunking "https://github.com/byteclub-labs/gbrain/blob/master/src/core/chunkers/recursive.ts"
click node_contextual "https://github.com/byteclub-labs/gbrain/blob/master/src/core/contextual-retrieval-service.ts"
click node_linking "https://github.com/byteclub-labs/gbrain/blob/master/src/core/link-extraction.ts"
click node_search "https://github.com/byteclub-labs/gbrain/blob/master/src/core/search/sql-ranking.ts"
click node_embedding "https://github.com/byteclub-labs/gbrain/blob/master/src/core/search/embedding-column.ts"
click node_reflex "https://github.com/byteclub-labs/gbrain/blob/master/src/core/context/retrieval-reflex.ts"
click node_answer "https://github.com/byteclub-labs/gbrain/tree/master/src/core"
click node_engine "https://github.com/byteclub-labs/gbrain/blob/master/src/core/engine.ts"
click node_pglite "https://github.com/byteclub-labs/gbrain/blob/master/src/core/pglite-engine.ts"
click node_postgres "https://github.com/byteclub-labs/gbrain/blob/master/src/core/postgres-engine.ts"
click node_graph "https://github.com/byteclub-labs/gbrain/blob/master/src/core/link-extraction.ts"
click node_facts "https://github.com/byteclub-labs/gbrain/blob/master/src/core/takes-fence.ts"
click node_ai "https://github.com/byteclub-labs/gbrain/blob/master/src/core/ai/gateway.ts"
click node_cycle "https://github.com/byteclub-labs/gbrain/blob/master/src/core/cycle.ts"
click node_context "https://github.com/byteclub-labs/gbrain/blob/master/src/core/context-engine.ts"
click node_migration "https://github.com/byteclub-labs/gbrain/blob/master/src/core/migrate.ts"

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_admin,node_person toneBlue
class node_ingestion,node_chunking,node_contextual,node_linking toneAmber
class node_search,node_embedding,node_reflex,node_answer toneMint
class node_engine,node_pglite,node_postgres,node_graph,node_facts toneRose
class node_ai,node_cycle,node_context,node_migration toneIndigo
```

## Components

### Access interfaces

- [CLI](https://github.com/byteclub-labs/gbrain/blob/master/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/byteclub-labs/gbrain/blob/master/src/mcp/server.ts): `src/mcp/server.ts`
- [Admin console](https://github.com/byteclub-labs/gbrain/blob/master/admin/src/App.tsx): `admin/src/App.tsx`

### Memory ingestion

- [Source ingestion](https://github.com/byteclub-labs/gbrain/tree/master/src/core/ingestion): `src/core/ingestion`
- [Chunking](https://github.com/byteclub-labs/gbrain/blob/master/src/core/chunkers/recursive.ts): `src/core/chunkers/recursive.ts`
- [Contextual retrieval prep](https://github.com/byteclub-labs/gbrain/blob/master/src/core/contextual-retrieval-service.ts): `src/core/contextual-retrieval-service.ts`
- [Entity links](https://github.com/byteclub-labs/gbrain/blob/master/src/core/link-extraction.ts): `src/core/link-extraction.ts`

### Retrieval and answers

- [Search ranking](https://github.com/byteclub-labs/gbrain/blob/master/src/core/search/sql-ranking.ts): `src/core/search/sql-ranking.ts`
- [Embedding search](https://github.com/byteclub-labs/gbrain/blob/master/src/core/search/embedding-column.ts): `src/core/search/embedding-column.ts`
- [Contextual recall](https://github.com/byteclub-labs/gbrain/blob/master/src/core/context/retrieval-reflex.ts): `src/core/context/retrieval-reflex.ts`
- [Synthesis and gap analysis](https://github.com/byteclub-labs/gbrain/tree/master/src/core): `src/core`

### Memory and storage

- [Brain engine API](https://github.com/byteclub-labs/gbrain/blob/master/src/core/engine.ts): `src/core/engine.ts`
- [PGLite store](https://github.com/byteclub-labs/gbrain/blob/master/src/core/pglite-engine.ts): `src/core/pglite-engine.ts`
- [Postgres store](https://github.com/byteclub-labs/gbrain/blob/master/src/core/postgres-engine.ts): `src/core/postgres-engine.ts`
- [Knowledge graph](https://github.com/byteclub-labs/gbrain/blob/master/src/core/link-extraction.ts): `src/core/link-extraction.ts`
- [Fenced memory](https://github.com/byteclub-labs/gbrain/blob/master/src/core/takes-fence.ts): `src/core/takes-fence.ts`

### Autonomous operations

- [AI gateway](https://github.com/byteclub-labs/gbrain/blob/master/src/core/ai/gateway.ts): `src/core/ai/gateway.ts`
- [Dream cycle](https://github.com/byteclub-labs/gbrain/blob/master/src/core/cycle.ts): `src/core/cycle.ts`
- [Context engine](https://github.com/byteclub-labs/gbrain/blob/master/src/core/context-engine.ts): `src/core/context-engine.ts`
- [Schema migrations](https://github.com/byteclub-labs/gbrain/blob/master/src/core/migrate.ts): `src/core/migrate.ts`

### Other components

- **User or agent**

## Connections

- User or agent → CLI: runs commands
- User or agent → MCP server: calls tools
- User or agent → Admin console: manages brain
- User or agent → Source ingestion: provides sources
- Source ingestion → Chunking: chunks pages
- Source ingestion → Entity links: extracts edges (evidence: `README.md`)
- Source ingestion → Brain engine API: writes pages
- Chunking → Brain engine API: stores chunks
- Contextual retrieval prep → AI gateway: generates synopses (evidence: `src/core/contextual-retrieval-service.ts`)
- Contextual retrieval prep → Chunking: processes chunks
- User or agent → Search ranking: asks questions (evidence: `README.md`)
- Search ranking → Embedding search: uses vectors
- Search ranking → Brain engine API: queries memory
- Search ranking → Knowledge graph: traverses links (evidence: `README.md`)
- Search ranking → Synthesis and gap analysis: synthesizes evidence (evidence: `README.md`)
- Synthesis and gap analysis → User or agent: returns cited answer (evidence: `README.md`)
- MCP server → Brain engine API: dispatches operations (evidence: `src/mcp/server.ts`)
- Brain engine API → PGLite store: implemented by (evidence: `src/core/pglite-engine.ts`)
- Brain engine API → Postgres store: implemented by (evidence: `src/core/postgres-engine.ts`)
- Postgres store → Schema migrations: runs migrations (evidence: `src/core/postgres-engine.ts`)
- PGLite store → Schema migrations: uses migrations (evidence: `src/core/pglite-engine.ts`)
- Dream cycle → Brain engine API: consolidates memory
- Dream cycle → AI gateway: uses models
- Context engine → Contextual recall: builds recall (evidence: `src/core/context-engine.ts`)
- Contextual recall → Brain engine API: resolves entities (evidence: `src/core/context/reflex.ts`)
- Brain engine API → Fenced memory: indexes memory
