# ko3ak81/agent-second-brain-public architecture

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

- Interactive diagram: https://gitdiagram.com/ko3ak81/agent-second-brain-public
- Repository: https://github.com/ko3ak81/agent-second-brain-public

## Overview

Agent Second Brain is a Telegram personal-assistant bot that captures messages and media, turns them into vault knowledge and tasks/events, and provides conversational retrieval and scheduled reports. The graph combines README-documented product flows with source-index-supported wiring; unsampled handlers and services are represented only at the directory or subsystem level, so some internal links are intentionally omitted.

Main entry points: [`src/d_brain/services/processor.py`](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/processor.py) (AI processing), [`src/d_brain/bot/main.py`](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/main.py) (Bot runtime), [`src/d_brain/bot/handlers/commands.py`](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/commands.py) (Commands), [`src/d_brain/bot/handlers`](https://github.com/ko3ak81/agent-second-brain-public/tree/main/src/d_brain/bot/handlers) (Message and media handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Telegram capture"]
  node_bot["Bot runtime<br/>[main.py]"]
  node_commands["Commands<br/>[commands.py]"]
  node_message_handlers["Message and media handlers"]
end

subgraph group_knowledge["Knowledge processing"]
  node_processor["AI processing<br/>[processor.py]"]
  node_vault[("Obsidian vault<br/>[storage.py]")]
  node_dedup[("File deduplication<br/>[dedup_state.py]")]
  node_transcription["Voice transcription<br/>[transcription.py]"]
  node_token_compression["Context compression"]
end

subgraph group_actions["Tasks and calendar"]
  node_event_callbacks["Event callbacks<br/>[event_callback.py]"]
  node_event_parser["Event parsing<br/>[eventparse.py]"]
  node_todoist["Todoist tasks<br/>[todoist.py]"]
  node_calendar["Google Calendar<br/>[gcal.py]"]
end

subgraph group_automation["Scheduled services"]
  node_scheduler["Reminder scheduler<br/>[scheduler.py]"]
  node_job_runner["Periodic job runner<br/>[runner.py]"]
  node_job_registry["Job registry<br/>[__init__.py]"]
  node_job_base["Job contract<br/>[base.py]"]
  node_autofetch_job["Auto-fetch job<br/>[autofetch_job.py]"]
  node_gmail["Gmail source<br/>[gmail.py]"]
  node_rollup["Memory rollups<br/>[rollup.py]"]
  node_hotness["Memory fading<br/>[hotness.py]"]
  node_report["Daily report<br/>[process.py]"]
end

subgraph group_state["Persistence and settings"]
  node_session[("Conversation history<br/>[session.py]")]
  node_event_state[("Pending event state<br/>[pending_events.py]")]
  node_user_settings[("User preferences<br/>[user_settings.py]")]
  node_autofetch_state[("Fetch cursors and budget<br/>[state.py]")]
  node_config["Application settings<br/>[config.py]"]
  node_quota[("Processing quota<br/>[quota_state.py]")]
  node_process_log[("Processing history<br/>[process_log.py]")]
end

node_user(("Telegram user"))
node_telegram["Telegram"]
node_deepgram["Deepgram"]

node_user -->|"sends content"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_bot -->|"registers router"| node_commands
node_bot -->|"registers routers"| node_message_handlers
node_bot -->|"registers router"| node_event_callbacks
node_message_handlers -.->|"requests processing"| node_processor
node_message_handlers -->|"extracts event intent"| node_event_parser
node_message_handlers -.->|"transcribes voice"| node_transcription
node_transcription -->|"sends audio"| node_deepgram
node_message_handlers -.->|"saves captures"| node_vault
node_vault -->|"checks duplicate"| node_dedup
node_processor -->|"classifies and files"| node_vault
node_processor -->|"creates tasks"| node_todoist
node_processor -->|"loads session context"| node_session
node_processor -->|"tracks usage"| node_quota
node_processor -->|"records processing"| node_process_log
node_processor -->|"compresses context"| node_token_compression
node_commands -->|"adds reminder"| node_todoist
node_commands -->|"schedules chat ping"| node_scheduler
node_commands -->|"records reminder"| node_session
node_commands -->|"reads timezone"| node_user_settings
node_event_callbacks -->|"resolves pending event"| node_event_state
node_event_callbacks -->|"creates event"| node_calendar
node_event_callbacks -->|"writes event card"| node_vault
node_event_callbacks -->|"reads timezone"| node_user_settings
node_bot -->|"starts runner"| node_job_runner
node_job_runner -.->|"runs registered jobs"| node_job_registry
node_job_registry -->|"builds job list"| node_job_base
node_job_registry -->|"registers optional fetch"| node_autofetch_job
node_autofetch_job -.->|"fetches mail"| node_gmail
node_gmail -->|"checks seen and budget"| node_autofetch_state
node_autofetch_job -.->|"files fetched items"| node_vault
node_job_registry -->|"registers rollup"| node_rollup
node_job_registry -->|"registers recompute"| node_hotness
node_bot -->|"registers processing route"| node_report
node_report -->|"runs processing"| node_processor
node_config -->|"configures runtime"| node_bot

click node_bot "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/main.py"
click node_commands "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/commands.py"
click node_message_handlers "https://github.com/ko3ak81/agent-second-brain-public/tree/main/src/d_brain/bot/handlers"
click node_event_callbacks "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/event_callback.py"
click node_processor "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/processor.py"
click node_event_parser "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/eventparse.py"
click node_vault "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/storage.py"
click node_dedup "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/dedup_state.py"
click node_session "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/session.py"
click node_todoist "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/todoist.py"
click node_calendar "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/gcal.py"
click node_event_state "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/pending_events.py"
click node_user_settings "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/user_settings.py"
click node_scheduler "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/scheduler.py"
click node_job_runner "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/runner.py"
click node_job_registry "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/__init__.py"
click node_job_base "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/base.py"
click node_autofetch_job "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/autofetch_job.py"
click node_gmail "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/autofetch/gmail.py"
click node_autofetch_state "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/autofetch/state.py"
click node_rollup "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/rollup.py"
click node_hotness "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/hotness.py"
click node_report "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/process.py"
click node_transcription "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/transcription.py"
click node_config "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/config.py"
click node_quota "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/quota_state.py"
click node_process_log "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/process_log.py"
click node_token_compression "https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/token_compression.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_bot,node_commands,node_message_handlers,node_user toneBlue
class node_processor,node_vault,node_dedup,node_transcription,node_token_compression toneAmber
class node_event_callbacks,node_event_parser,node_todoist,node_calendar toneMint
class node_scheduler,node_job_runner,node_job_registry,node_job_base,node_autofetch_job,node_gmail,node_rollup,node_hotness,node_report toneRose
class node_session,node_event_state,node_user_settings,node_autofetch_state,node_config,node_quota,node_process_log,node_telegram,node_deepgram toneIndigo
```

## Components

### Telegram capture

- [Bot runtime](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/main.py): `src/d_brain/bot/main.py`
- [Commands](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/commands.py): `src/d_brain/bot/handlers/commands.py`
- [Message and media handlers](https://github.com/ko3ak81/agent-second-brain-public/tree/main/src/d_brain/bot/handlers): `src/d_brain/bot/handlers`

### Knowledge processing

- [AI processing](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/processor.py): `src/d_brain/services/processor.py`
- [Obsidian vault](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/storage.py): `src/d_brain/services/storage.py`
- [File deduplication](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/dedup_state.py): `src/d_brain/services/dedup_state.py`
- [Voice transcription](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/transcription.py): `src/d_brain/services/transcription.py`
- [Context compression](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/token_compression.py): `src/d_brain/services/token_compression.py`

### Tasks and calendar

- [Event callbacks](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/event_callback.py): `src/d_brain/bot/handlers/event_callback.py`
- [Event parsing](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/eventparse.py): `src/d_brain/services/eventparse.py`
- [Todoist tasks](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/todoist.py): `src/d_brain/services/todoist.py`
- [Google Calendar](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/gcal.py): `src/d_brain/services/gcal.py`

### Scheduled services

- [Reminder scheduler](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/scheduler.py): `src/d_brain/services/scheduler.py`
- [Periodic job runner](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/runner.py): `src/d_brain/jobs/runner.py`
- [Job registry](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/__init__.py): `src/d_brain/jobs/__init__.py`
- [Job contract](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/base.py): `src/d_brain/jobs/base.py`
- [Auto-fetch job](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/jobs/autofetch_job.py): `src/d_brain/jobs/autofetch_job.py`
- [Gmail source](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/autofetch/gmail.py): `src/d_brain/services/autofetch/gmail.py`
- [Memory rollups](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/rollup.py): `src/d_brain/services/rollup.py`
- [Memory fading](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/hotness.py): `src/d_brain/services/hotness.py`
- [Daily report](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/bot/handlers/process.py): `src/d_brain/bot/handlers/process.py`

### Persistence and settings

- [Conversation history](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/session.py): `src/d_brain/services/session.py`
- [Pending event state](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/pending_events.py): `src/d_brain/services/pending_events.py`
- [User preferences](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/user_settings.py): `src/d_brain/services/user_settings.py`
- [Fetch cursors and budget](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/autofetch/state.py): `src/d_brain/services/autofetch/state.py`
- [Application settings](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/config.py): `src/d_brain/config.py`
- [Processing quota](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/quota_state.py): `src/d_brain/services/quota_state.py`
- [Processing history](https://github.com/ko3ak81/agent-second-brain-public/blob/main/src/d_brain/services/process_log.py): `src/d_brain/services/process_log.py`

### Other components

- **Telegram user**
- **Telegram**
- **Deepgram**

## Connections

- Telegram user → Telegram: sends content (evidence: `README.md`)
- Telegram → Bot runtime: delivers updates (evidence: `src/d_brain/bot/main.py`)
- Bot runtime → Commands: registers router (evidence: `src/d_brain/bot/main.py`)
- Bot runtime → Message and media handlers: registers routers (evidence: `src/d_brain/bot/main.py`)
- Bot runtime → Event callbacks: registers router (evidence: `src/d_brain/bot/main.py`)
- Message and media handlers → AI processing: requests processing (evidence: `src/d_brain/bot/handlers/process.py`)
- Message and media handlers → Event parsing: extracts event intent (evidence: `src/d_brain/bot/handlers/text.py`)
- Message and media handlers → Voice transcription: transcribes voice (evidence: `src/d_brain/bot/handlers/event_callback.py`)
- Voice transcription → Deepgram: sends audio (evidence: `README.md`)
- Message and media handlers → Obsidian vault: saves captures (evidence: `src/d_brain/bot/handlers/commands.py`)
- Obsidian vault → File deduplication: checks duplicate (evidence: `src/d_brain/services/storage.py`)
- AI processing → Obsidian vault: classifies and files (evidence: `README.md`)
- AI processing → Todoist tasks: creates tasks (evidence: `README.md`)
- AI processing → Conversation history: loads session context (evidence: `src/d_brain/services/processor.py`)
- AI processing → Processing quota: tracks usage (evidence: `src/d_brain/services/processor.py`)
- AI processing → Processing history: records processing (evidence: `src/d_brain/services/processor.py`)
- AI processing → Context compression: compresses context (evidence: `src/d_brain/services/processor.py`)
- Commands → Todoist tasks: adds reminder (evidence: `src/d_brain/bot/handlers/commands.py`)
- Commands → Reminder scheduler: schedules chat ping (evidence: `src/d_brain/bot/handlers/commands.py`)
- Commands → Conversation history: records reminder (evidence: `src/d_brain/bot/handlers/commands.py`)
- Commands → User preferences: reads timezone (evidence: `src/d_brain/bot/handlers/commands.py`)
- Event callbacks → Pending event state: resolves pending event (evidence: `src/d_brain/bot/handlers/event_callback.py`)
- Event callbacks → Google Calendar: creates event (evidence: `src/d_brain/bot/handlers/event_callback.py`)
- Event callbacks → Obsidian vault: writes event card (evidence: `README.md`)
- Event callbacks → User preferences: reads timezone (evidence: `src/d_brain/bot/handlers/event_callback.py`)
- Bot runtime → Periodic job runner: starts runner (evidence: `src/d_brain/bot/main.py`)
- Periodic job runner → Job registry: runs registered jobs (evidence: `src/d_brain/jobs/__init__.py`)
- Job registry → Job contract: builds job list (evidence: `src/d_brain/jobs/__init__.py`)
- Job registry → Auto-fetch job: registers optional fetch (evidence: `src/d_brain/jobs/__init__.py`)
- Auto-fetch job → Gmail source: fetches mail
- Gmail source → Fetch cursors and budget: checks seen and budget (evidence: `src/d_brain/services/autofetch/gmail.py`)
- Auto-fetch job → Obsidian vault: files fetched items
- Job registry → Memory rollups: registers rollup (evidence: `src/d_brain/jobs/__init__.py`)
- Job registry → Memory fading: registers recompute (evidence: `src/d_brain/jobs/__init__.py`)
- Bot runtime → Daily report: registers processing route (evidence: `src/d_brain/bot/main.py`)
- Daily report → AI processing: runs processing (evidence: `src/d_brain/bot/handlers/process.py`)
- Application settings → Bot runtime: configures runtime (evidence: `src/d_brain/__main__.py`)
