# xy-claude/brain-core architecture

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

- Interactive diagram: https://gitdiagram.com/xy-claude/brain-core
- Repository: https://github.com/xy-claude/brain-core

## Overview

brain-core is a local, persistent memory system for Claude Code agents. The workflow starts with scaffolding an agent folder, then Claude Code invokes a five-tool MCP server: sessions load and close context, memories are written to the markdown vault and indexed for recall, and distillation captures source material for later curation. SQLite provides the local index and event state; Hindsight is an optional vector-memory integration. Scheduled daily and weekly jobs maintain briefs, archives, and mental models. The graph emphasizes README-described capabilities; some implementation links are omitted where excerpts do not establish calls.

Main entry points: [`src/brain_core/agent.py`](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/agent.py) (Agent API), [`src/brain_core/cli/main.py`](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cli/main.py) (CLI), [`src/brain_core/stores/vault.py`](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/vault.py) (Markdown vault), [`src/brain_core/remember.py`](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/remember.py) (Memory writes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_scaffold["Agent scaffolding<br/>[init.py]"]
  node_mcp["MCP tools<br/>[server.py]"]
  node_agent["Agent API<br/>[agent.py]"]
end

subgraph group_workflow["Memory workflow"]
  node_session["Session lifecycle<br/>[session.py]"]
  node_remember["Memory writes<br/>[remember.py]"]
  node_recall["Memory recall<br/>[recall.py]"]
  node_distill["Source distillation<br/>[distill.py]"]
  node_capture["Transcript capture<br/>[capture.py]"]
end

subgraph group_stores["Memory stores"]
  node_vault["Markdown vault<br/>[vault.py]"]
  node_index["FTS search index<br/>[index.py]"]
  node_transcripts["Transcript store<br/>[transcripts.py]"]
  node_db[("SQLite database<br/>[db.py]")]
  node_graph["Relations store<br/>[graph.py]"]
end

subgraph group_operations["Maintenance and insight"]
  node_cron["Scheduled jobs<br/>[cron.py]"]
  node_status["Health status<br/>[status.py]"]
  node_traits["Trait evidence<br/>[traits.py]"]
end

node_user(("Agent owner"))
node_claude(("Claude Code"))
node_hindsight{{"Hindsight service"}}

node_user -->|"initializes agent"| node_cli
node_cli -->|"scaffolds folder"| node_scaffold
node_claude -->|"invokes tools"| node_mcp
node_mcp -->|"dispatches tools"| node_agent
node_agent -->|"delegates session"| node_session
node_agent -->|"delegates writes"| node_remember
node_agent -->|"delegates search"| node_recall
node_agent -->|"delegates capture"| node_distill
node_agent -->|"delegates health"| node_status
node_remember -->|"writes first"| node_vault
node_remember -->|"writes relations"| node_graph
node_remember -.->|"retains memory"| node_hindsight
node_recall -->|"searches records"| node_index
node_recall -.->|"searches optionally"| node_hindsight
node_vault -->|"indexes records"| node_index
node_index -->|"stores FTS rows"| node_db
node_transcripts -->|"indexes transcripts"| node_db
node_capture -->|"records transcript"| node_agent
node_distill -->|"saves raw source"| node_vault
node_session -->|"reads and writes context"| node_vault
node_session -->|"drains queue"| node_hindsight
node_cron -->|"updates briefs and archives"| node_vault
node_cron -->|"backs up and refreshes"| node_hindsight
node_status -->|"computes evidence"| node_traits
node_cron -->|"reports traits"| node_traits
node_cli -->|"runs jobs"| node_cron
node_cli -->|"runs capture hook"| node_capture
node_cli -->|"reports health"| node_status

click node_cli "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cli/main.py"
click node_scaffold "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cli/init.py"
click node_mcp "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/mcp/server.py"
click node_agent "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/agent.py"
click node_session "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/session.py"
click node_remember "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/remember.py"
click node_recall "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/recall.py"
click node_distill "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/distill.py"
click node_capture "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/capture.py"
click node_vault "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/vault.py"
click node_index "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/index.py"
click node_transcripts "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/transcripts.py"
click node_db "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/storage/db.py"
click node_graph "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/graph.py"
click node_cron "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cron.py"
click node_status "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/status.py"
click node_traits "https://github.com/xy-claude/brain-core/blob/main/src/brain_core/traits.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_cli,node_scaffold,node_mcp,node_agent toneBlue
class node_session,node_remember,node_recall,node_distill,node_capture toneAmber
class node_vault,node_index,node_transcripts,node_db,node_graph toneMint
class node_cron,node_status,node_traits toneRose
class node_user,node_claude,node_hindsight toneIndigo
```

## Components

### Agent interfaces

- [CLI](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cli/main.py): `src/brain_core/cli/main.py`
- [Agent scaffolding](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cli/init.py): `src/brain_core/cli/init.py`
- [MCP tools](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/mcp/server.py): `src/brain_core/mcp/server.py`
- [Agent API](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/agent.py): `src/brain_core/agent.py`

### Memory workflow

- [Session lifecycle](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/session.py): `src/brain_core/session.py`
- [Memory writes](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/remember.py): `src/brain_core/remember.py`
- [Memory recall](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/recall.py): `src/brain_core/recall.py`
- [Source distillation](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/distill.py): `src/brain_core/distill.py`
- [Transcript capture](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/capture.py): `src/brain_core/capture.py`

### Memory stores

- [Markdown vault](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/vault.py): `src/brain_core/stores/vault.py`
- [FTS search index](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/index.py): `src/brain_core/stores/index.py`
- [Transcript store](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/transcripts.py): `src/brain_core/stores/transcripts.py`
- [SQLite database](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/storage/db.py): `src/brain_core/storage/db.py`
- [Relations store](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/stores/graph.py): `src/brain_core/stores/graph.py`

### Maintenance and insight

- [Scheduled jobs](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/cron.py): `src/brain_core/cron.py`
- [Health status](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/status.py): `src/brain_core/status.py`
- [Trait evidence](https://github.com/xy-claude/brain-core/blob/main/src/brain_core/traits.py): `src/brain_core/traits.py`

### Other components

- **Agent owner**
- **Claude Code**
- **Hindsight service**

## Connections

- Agent owner → CLI: initializes agent (evidence: `README.md`)
- CLI → Agent scaffolding: scaffolds folder (evidence: `src/brain_core/cli/main.py`)
- Claude Code → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Agent API: dispatches tools (evidence: `src/brain_core/mcp/server.py`)
- Agent API → Session lifecycle: delegates session (evidence: `src/brain_core/agent.py`)
- Agent API → Memory writes: delegates writes (evidence: `src/brain_core/agent.py`)
- Agent API → Memory recall: delegates search (evidence: `src/brain_core/agent.py`)
- Agent API → Source distillation: delegates capture (evidence: `src/brain_core/agent.py`)
- Agent API → Health status: delegates health (evidence: `src/brain_core/agent.py`)
- Memory writes → Markdown vault: writes first (evidence: `README.md`)
- Memory writes → Relations store: writes relations (evidence: `src/brain_core/remember.py`)
- Memory writes → Hindsight service: retains memory (evidence: `README.md`)
- Memory recall → FTS search index: searches records (evidence: `src/brain_core/recall.py`)
- Memory recall → Hindsight service: searches optionally (evidence: `README.md`)
- Markdown vault → FTS search index: indexes records (evidence: `README.md`)
- FTS search index → SQLite database: stores FTS rows (evidence: `src/brain_core/stores/index.py`)
- Transcript store → SQLite database: indexes transcripts (evidence: `src/brain_core/stores/transcripts.py`)
- Transcript capture → Agent API: records transcript (evidence: `src/brain_core/capture.py`)
- Source distillation → Markdown vault: saves raw source (evidence: `src/brain_core/distill.py`)
- Session lifecycle → Markdown vault: reads and writes context (evidence: `src/brain_core/session.py`)
- Session lifecycle → Hindsight service: drains queue (evidence: `src/brain_core/session.py`)
- Scheduled jobs → Markdown vault: updates briefs and archives (evidence: `src/brain_core/cron.py`)
- Scheduled jobs → Hindsight service: backs up and refreshes (evidence: `src/brain_core/cron.py`)
- Health status → Trait evidence: computes evidence (evidence: `src/brain_core/status.py`)
- Scheduled jobs → Trait evidence: reports traits (evidence: `src/brain_core/cron.py`)
- CLI → Scheduled jobs: runs jobs (evidence: `src/brain_core/cli/main.py`)
- CLI → Transcript capture: runs capture hook (evidence: `src/brain_core/cli/main.py`)
- CLI → Health status: reports health (evidence: `src/brain_core/cli/main.py`)