How mordechaipotash/brain-mcp works
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: api.py Recorder API · cli.py Recorder CLI · visit.py Chunk Visit · floor_db.py DuckDB Floor Cache
Components 20
Capture
- Session Hooks
plugin/scripts - Origin Scanner
brain_mcp/recorder/scanner.py - Spool Drainer
brain_mcp/recorder/drain.py - Recorder CLI
brain_mcp/recorder/cli.py - Platform Paths
brain_mcp/platform.py
Floor and Index
- Chunk Visit
brain_mcp/recorder/visit.py - Append-only Lake
brain_mcp/recorder/paths.py - Hash Manifest
brain_mcp/recorder/manifest.py - DuckDB Floor Cache
brain_mcp/recorder/floor_db.py - Derived Message Index
brain_mcp/recorder/derived.py
MCP and Recall
- Recorder API
brain_mcp/recorder/api.py - MCP Tool Server
brain_mcp/recorder/server.py - Verified Backup
brain_mcp/recorder/api.py
Conversation Ingesters
- Ingester Contract
brain_mcp/ingest/base.py - Ingester Registry
brain_mcp/ingest/registry.py - Source Adapters
brain_mcp/ingest - Canonical Record Schema
brain_mcp/ingest/schema.py - V1 Migration
brain_mcp/recorder/cli.py
Other components
- Agent Transcripts
- Backup Destination
Connections 25
- Agent Transcripts → Session Hooks: emit deltas
README.md - Agent Transcripts → Origin Scanner: poll origins
README.md - Session Hooks → Spool Drainer: write spool
README.md - Recorder CLI → Spool Drainer: runs capture tick
brain_mcp/recorder/cli.py - Recorder CLI → Origin Scanner: runs capture tick
brain_mcp/recorder/cli.py - Spool Drainer → Chunk Visit: ingests chunks
brain_mcp/recorder/drain.py - Origin Scanner → Chunk Visit: visits origins
brain_mcp/recorder/scanner.py - Chunk Visit → Append-only Lake: appends bytes
brain_mcp/recorder/visit.py - Chunk Visit → Hash Manifest: appends hashes
brain_mcp/recorder/visit.py - Chunk Visit → DuckDB Floor Cache: records ingest state
brain_mcp/recorder/visit.py - DuckDB Floor Cache → Platform Paths: resolves database path
brain_mcp/recorder/floor_db.py - Derived Message Index → DuckDB Floor Cache: uses cache connections
brain_mcp/recorder/derived.py - Recorder CLI → Recorder API: runs health and backup
brain_mcp/recorder/cli.py - Recorder CLI → MCP Tool Server: starts server
brain_mcp/recorder/cli.py - MCP Tool Server → Recorder API: dispatches tools
brain_mcp/recorder/server.py - Recorder API → Derived Message Index: queries derived index
brain_mcp/recorder/api.py - Recorder API → DuckDB Floor Cache: reads floor cache
brain_mcp/recorder/api.py - Recorder API → Append-only Lake: reads cited bytes
brain_mcp/recorder/api.py - Recorder API → Verified Backup: performs backup
brain_mcp/recorder/server.py - Verified Backup → Backup Destination: syncs and verifies
README.md - Ingester Registry → Ingester Contract: registers implementations
brain_mcp/ingest/registry.py - Source Adapters → Ingester Contract: implement contract
brain_mcp/ingest/base.py - Source Adapters → Canonical Record Schema: emit canonical records
brain_mcp/ingest/schema.py - Recorder CLI → V1 Migration: exposes migration command
brain_mcp/recorder/cli.py - V1 Migration → Derived Message Index: imports derived rows
brain_mcp/recorder/cli.py