# mordechaipotash/brain-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/mordechaipotash/brain-mcp
- Repository: https://github.com/mordechaipotash/brain-mcp

## Overview

brain-mcp is a local recorder and citation-based recall service for AI conversation history. Its main workflow captures agent transcript bytes through hooks or polling, drains/scans them into an append-only lake with a manifest, derives a DuckDB cache, and exposes MCP tools for cited search, retrieval, freshness checks, and verified backup. The graph also preserves the legacy-format ingester modules and v1 migration capability. Some subsystem links are based on README or SOURCE INDEX references because their full source was not excerpted.

Main entry points: [`brain_mcp/recorder/api.py`](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/api.py) (Recorder API), [`brain_mcp/recorder/cli.py`](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/cli.py) (Recorder CLI), [`brain_mcp/recorder/visit.py`](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/visit.py) (Chunk Visit), [`brain_mcp/recorder/floor_db.py`](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/floor_db.py) (DuckDB Floor Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture"]
  node_hooks["Session Hooks"]
  node_scanner["Origin Scanner<br/>[scanner.py]"]
  node_drain["Spool Drainer<br/>[drain.py]"]
  node_cli["Recorder CLI<br/>[cli.py]"]
  node_platform_paths["Platform Paths<br/>[platform.py]"]
end

subgraph group_floor["Floor and Index"]
  node_visit["Chunk Visit<br/>[visit.py]"]
  node_lake[("Append-only Lake<br/>[paths.py]")]
  node_manifest["Hash Manifest<br/>[manifest.py]"]
  node_floor_db[("DuckDB Floor Cache<br/>[floor_db.py]")]
  node_derived[("Derived Message Index<br/>[derived.py]")]
end

subgraph group_recall["MCP and Recall"]
  node_api["Recorder API<br/>[api.py]"]
  node_mcp["MCP Tool Server<br/>[server.py]"]
  node_backup["Verified Backup<br/>[api.py]"]
end

subgraph group_ingest["Conversation Ingesters"]
  node_ingester_base["Ingester Contract<br/>[base.py]"]
  node_ingester_registry["Ingester Registry<br/>[registry.py]"]
  node_source_adapters["Source Adapters"]
  node_record_schema["Canonical Record Schema<br/>[schema.py]"]
  node_v1_migration["V1 Migration<br/>[cli.py]"]
end

node_agent_sources["Agent Transcripts"]
node_destination["Backup Destination"]

node_agent_sources -.->|"emit deltas"| node_hooks
node_agent_sources -.->|"poll origins"| node_scanner
node_hooks -.->|"write spool"| node_drain
node_cli -->|"runs capture tick"| node_drain
node_cli -->|"runs capture tick"| node_scanner
node_drain -->|"ingests chunks"| node_visit
node_scanner -->|"visits origins"| node_visit
node_visit -->|"appends bytes"| node_lake
node_visit -->|"appends hashes"| node_manifest
node_visit -->|"records ingest state"| node_floor_db
node_floor_db -->|"resolves database path"| node_platform_paths
node_derived -->|"uses cache connections"| node_floor_db
node_cli -->|"runs health and backup"| node_api
node_cli -->|"starts server"| node_mcp
node_mcp -->|"dispatches tools"| node_api
node_api -->|"queries derived index"| node_derived
node_api -->|"reads floor cache"| node_floor_db
node_api -->|"reads cited bytes"| node_lake
node_api -->|"performs backup"| node_backup
node_backup -->|"syncs and verifies"| node_destination
node_ingester_registry -->|"registers implementations"| node_ingester_base
node_source_adapters -->|"implement contract"| node_ingester_base
node_source_adapters -->|"emit canonical records"| node_record_schema
node_cli -->|"exposes migration command"| node_v1_migration
node_v1_migration -->|"imports derived rows"| node_derived

click node_hooks "https://github.com/mordechaipotash/brain-mcp/tree/main/plugin/scripts"
click node_scanner "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/scanner.py"
click node_drain "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/drain.py"
click node_cli "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/cli.py"
click node_visit "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/visit.py"
click node_lake "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/paths.py"
click node_manifest "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/manifest.py"
click node_floor_db "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/floor_db.py"
click node_derived "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/derived.py"
click node_api "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/api.py"
click node_mcp "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/server.py"
click node_backup "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/api.py"
click node_ingester_base "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/ingest/base.py"
click node_ingester_registry "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/ingest/registry.py"
click node_source_adapters "https://github.com/mordechaipotash/brain-mcp/tree/main/brain_mcp/ingest"
click node_record_schema "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/ingest/schema.py"
click node_platform_paths "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/platform.py"
click node_v1_migration "https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/cli.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_hooks,node_scanner,node_drain,node_cli,node_platform_paths toneBlue
class node_visit,node_lake,node_manifest,node_floor_db,node_derived toneAmber
class node_api,node_mcp,node_backup toneMint
class node_ingester_base,node_ingester_registry,node_source_adapters,node_record_schema,node_v1_migration toneRose
class node_agent_sources,node_destination toneIndigo
```

## Components

### Capture

- [Session Hooks](https://github.com/mordechaipotash/brain-mcp/tree/main/plugin/scripts): `plugin/scripts`
- [Origin Scanner](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/scanner.py): `brain_mcp/recorder/scanner.py`
- [Spool Drainer](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/drain.py): `brain_mcp/recorder/drain.py`
- [Recorder CLI](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/cli.py): `brain_mcp/recorder/cli.py`
- [Platform Paths](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/platform.py): `brain_mcp/platform.py`

### Floor and Index

- [Chunk Visit](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/visit.py): `brain_mcp/recorder/visit.py`
- [Append-only Lake](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/paths.py): `brain_mcp/recorder/paths.py`
- [Hash Manifest](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/manifest.py): `brain_mcp/recorder/manifest.py`
- [DuckDB Floor Cache](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/floor_db.py): `brain_mcp/recorder/floor_db.py`
- [Derived Message Index](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/derived.py): `brain_mcp/recorder/derived.py`

### MCP and Recall

- [Recorder API](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/api.py): `brain_mcp/recorder/api.py`
- [MCP Tool Server](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/server.py): `brain_mcp/recorder/server.py`
- [Verified Backup](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/api.py): `brain_mcp/recorder/api.py`

### Conversation Ingesters

- [Ingester Contract](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/ingest/base.py): `brain_mcp/ingest/base.py`
- [Ingester Registry](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/ingest/registry.py): `brain_mcp/ingest/registry.py`
- [Source Adapters](https://github.com/mordechaipotash/brain-mcp/tree/main/brain_mcp/ingest): `brain_mcp/ingest`
- [Canonical Record Schema](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/ingest/schema.py): `brain_mcp/ingest/schema.py`
- [V1 Migration](https://github.com/mordechaipotash/brain-mcp/blob/main/brain_mcp/recorder/cli.py): `brain_mcp/recorder/cli.py`

### Other components

- **Agent Transcripts**
- **Backup Destination**

## Connections

- Agent Transcripts → Session Hooks: emit deltas (evidence: `README.md`)
- Agent Transcripts → Origin Scanner: poll origins (evidence: `README.md`)
- Session Hooks → Spool Drainer: write spool (evidence: `README.md`)
- Recorder CLI → Spool Drainer: runs capture tick (evidence: `brain_mcp/recorder/cli.py`)
- Recorder CLI → Origin Scanner: runs capture tick (evidence: `brain_mcp/recorder/cli.py`)
- Spool Drainer → Chunk Visit: ingests chunks (evidence: `brain_mcp/recorder/drain.py`)
- Origin Scanner → Chunk Visit: visits origins (evidence: `brain_mcp/recorder/scanner.py`)
- Chunk Visit → Append-only Lake: appends bytes (evidence: `brain_mcp/recorder/visit.py`)
- Chunk Visit → Hash Manifest: appends hashes (evidence: `brain_mcp/recorder/visit.py`)
- Chunk Visit → DuckDB Floor Cache: records ingest state (evidence: `brain_mcp/recorder/visit.py`)
- DuckDB Floor Cache → Platform Paths: resolves database path (evidence: `brain_mcp/recorder/floor_db.py`)
- Derived Message Index → DuckDB Floor Cache: uses cache connections (evidence: `brain_mcp/recorder/derived.py`)
- Recorder CLI → Recorder API: runs health and backup (evidence: `brain_mcp/recorder/cli.py`)
- Recorder CLI → MCP Tool Server: starts server (evidence: `brain_mcp/recorder/cli.py`)
- MCP Tool Server → Recorder API: dispatches tools (evidence: `brain_mcp/recorder/server.py`)
- Recorder API → Derived Message Index: queries derived index (evidence: `brain_mcp/recorder/api.py`)
- Recorder API → DuckDB Floor Cache: reads floor cache (evidence: `brain_mcp/recorder/api.py`)
- Recorder API → Append-only Lake: reads cited bytes (evidence: `brain_mcp/recorder/api.py`)
- Recorder API → Verified Backup: performs backup (evidence: `brain_mcp/recorder/server.py`)
- Verified Backup → Backup Destination: syncs and verifies (evidence: `README.md`)
- Ingester Registry → Ingester Contract: registers implementations (evidence: `brain_mcp/ingest/registry.py`)
- Source Adapters → Ingester Contract: implement contract (evidence: `brain_mcp/ingest/base.py`)
- Source Adapters → Canonical Record Schema: emit canonical records (evidence: `brain_mcp/ingest/schema.py`)
- Recorder CLI → V1 Migration: exposes migration command (evidence: `brain_mcp/recorder/cli.py`)
- V1 Migration → Derived Message Index: imports derived rows (evidence: `brain_mcp/recorder/cli.py`)
