# kenkaiii/pocket-agent architecture

> Architecture diagram of the GitHub repository kenkaiii/pocket-agent, 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/kenkaiii/pocket-agent
- Repository: https://github.com/kenkaiii/pocket-agent

## Overview

Pocket Agent is an Electron-based personal assistant with desktop and optional Telegram interfaces. A user message enters the app or bot, reaches the agent manager and chat engine, and can use tools, browser automation, and persistent memory. Separate branches cover scheduled routines, calendar and task reminders, and learned preferences. The README also documents OAuth-backed providers and MCP/skill extensibility. Edges are limited to README statements and shown source-index references or excerpts; unsampled subsystem internals and UI wiring are not inferred.

Main entry points: [`src/agent/chat-engine.ts`](https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/chat-engine.ts) (Chat engine), [`src/memory/index.ts`](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/index.ts) (Memory manager), [`src/main/index.ts`](https://github.com/kenkaiii/pocket-agent/blob/main/src/main/index.ts) (Desktop app), [`src/scheduler/index.ts`](https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/index.ts) (Scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_desktop["Desktop app<br/>[index.ts]"]
  node_settings[("Settings<br/>[index.ts]")]
end

subgraph group_agent["Agent and tools"]
  node_agent_manager["Agent manager<br/>[index.ts]"]
  node_chat_engine["Chat engine<br/>[chat-engine.ts]"]
  node_provider_config["Model providers<br/>[chat-providers.ts]"]
  node_model_resolution["Model selection<br/>[resolve-model.ts]"]
  node_agent_modes["Agent modes<br/>[agent-modes.ts]"]
  node_tool_registry["Agent tools<br/>[index.ts]"]
end

subgraph group_memory["Persistent memory"]
  node_memory_manager[("Memory manager<br/>[index.ts]")]
  node_facts["Personal facts<br/>[facts.ts]"]
  node_semantic_memory["Semantic search<br/>[semantic.ts]"]
  node_soul["Learned preferences<br/>[soul.ts]"]
  node_consolidation["Memory consolidation<br/>[consolidation.ts]"]
  node_daily_logs[("Daily logs<br/>[daily-logs.ts]")]
end

subgraph group_automation["Scheduling and browser"]
  node_scheduler["Scheduler<br/>[index.ts]"]
  node_calendar_tasks["Calendar and tasks<br/>[calendar.ts]"]
  node_pulse["Proactive check-ins<br/>[pulse.ts]"]
  node_browser["Browser automation<br/>[index.ts]"]
  node_electron_browser["Hidden browser<br/>[electron-tier.ts]"]
  node_chrome_browser["Chrome sessions<br/>[cdp-tier.ts]"]
end

subgraph group_interfaces["User interfaces and integrations"]
  node_telegram["Telegram bot<br/>[index.ts]"]
  node_oauth["OAuth providers<br/>[oauth.ts]"]
  node_mcp["MCP servers<br/>[project-server.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop
node_user -.->|"messages"| node_telegram
node_desktop -->|"initializes"| node_agent_manager
node_desktop -->|"initializes"| node_scheduler
node_desktop -->|"initializes"| node_telegram
node_agent_manager -->|"processes with"| node_chat_engine
node_chat_engine -->|"gets config"| node_provider_config
node_chat_engine -->|"resolves model"| node_model_resolution
node_chat_engine -->|"builds routing"| node_agent_modes
node_chat_engine -->|"uses tools"| node_tool_registry
node_chat_engine -->|"loads history"| node_memory_manager
node_agent_manager -->|"reads settings"| node_settings
node_tool_registry -->|"registers browser"| node_browser
node_tool_registry -->|"registers memory tools"| node_memory_manager
node_memory_manager -->|"rolls up"| node_daily_logs
node_memory_manager -->|"delegates to"| node_consolidation
node_facts -->|"uses search"| node_semantic_memory
node_soul -->|"uses search"| node_semantic_memory
node_scheduler -->|"checks events"| node_calendar_tasks
node_scheduler -->|"composes prompt"| node_pulse
node_scheduler -->|"records activity"| node_memory_manager
node_browser -->|"dispatches to"| node_electron_browser
node_browser -->|"dispatches to"| node_chrome_browser
node_oauth -->|"stores credentials"| node_settings

click node_desktop "https://github.com/kenkaiii/pocket-agent/blob/main/src/main/index.ts"
click node_agent_manager "https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/index.ts"
click node_chat_engine "https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/chat-engine.ts"
click node_provider_config "https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/chat-providers.ts"
click node_model_resolution "https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/resolve-model.ts"
click node_agent_modes "https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/agent-modes.ts"
click node_tool_registry "https://github.com/kenkaiii/pocket-agent/blob/main/src/tools/index.ts"
click node_settings "https://github.com/kenkaiii/pocket-agent/blob/main/src/settings/index.ts"
click node_memory_manager "https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/index.ts"
click node_facts "https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/facts.ts"
click node_semantic_memory "https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/semantic.ts"
click node_soul "https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/soul.ts"
click node_consolidation "https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/consolidation.ts"
click node_daily_logs "https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/daily-logs.ts"
click node_scheduler "https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/index.ts"
click node_calendar_tasks "https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/calendar.ts"
click node_pulse "https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/pulse.ts"
click node_browser "https://github.com/kenkaiii/pocket-agent/blob/main/src/browser/index.ts"
click node_electron_browser "https://github.com/kenkaiii/pocket-agent/blob/main/src/browser/electron-tier.ts"
click node_chrome_browser "https://github.com/kenkaiii/pocket-agent/blob/main/src/browser/cdp-tier.ts"
click node_telegram "https://github.com/kenkaiii/pocket-agent/blob/main/src/channels/telegram/index.ts"
click node_oauth "https://github.com/kenkaiii/pocket-agent/blob/main/src/auth/oauth.ts"
click node_mcp "https://github.com/kenkaiii/pocket-agent/blob/main/src/mcp/project-server.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_desktop,node_settings,node_user toneBlue
class node_agent_manager,node_chat_engine,node_provider_config,node_model_resolution,node_agent_modes,node_tool_registry toneAmber
class node_memory_manager,node_facts,node_semantic_memory,node_soul,node_consolidation,node_daily_logs toneMint
class node_scheduler,node_calendar_tasks,node_pulse,node_browser,node_electron_browser,node_chrome_browser toneRose
class node_telegram,node_oauth,node_mcp toneIndigo
```

## Components

### App runtime

- [Desktop app](https://github.com/kenkaiii/pocket-agent/blob/main/src/main/index.ts): `src/main/index.ts`
- [Settings](https://github.com/kenkaiii/pocket-agent/blob/main/src/settings/index.ts): `src/settings/index.ts`

### Agent and tools

- [Agent manager](https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/index.ts): `src/agent/index.ts`
- [Chat engine](https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/chat-engine.ts): `src/agent/chat-engine.ts`
- [Model providers](https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/chat-providers.ts): `src/agent/chat-providers.ts`
- [Model selection](https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/resolve-model.ts): `src/agent/resolve-model.ts`
- [Agent modes](https://github.com/kenkaiii/pocket-agent/blob/main/src/agent/agent-modes.ts): `src/agent/agent-modes.ts`
- [Agent tools](https://github.com/kenkaiii/pocket-agent/blob/main/src/tools/index.ts): `src/tools/index.ts`

### Persistent memory

- [Memory manager](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/index.ts): `src/memory/index.ts`
- [Personal facts](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/facts.ts): `src/memory/facts.ts`
- [Semantic search](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/semantic.ts): `src/memory/semantic.ts`
- [Learned preferences](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/soul.ts): `src/memory/soul.ts`
- [Memory consolidation](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/consolidation.ts): `src/memory/consolidation.ts`
- [Daily logs](https://github.com/kenkaiii/pocket-agent/blob/main/src/memory/daily-logs.ts): `src/memory/daily-logs.ts`

### Scheduling and browser

- [Scheduler](https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/index.ts): `src/scheduler/index.ts`
- [Calendar and tasks](https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/calendar.ts): `src/scheduler/calendar.ts`
- [Proactive check-ins](https://github.com/kenkaiii/pocket-agent/blob/main/src/scheduler/pulse.ts): `src/scheduler/pulse.ts`
- [Browser automation](https://github.com/kenkaiii/pocket-agent/blob/main/src/browser/index.ts): `src/browser/index.ts`
- [Hidden browser](https://github.com/kenkaiii/pocket-agent/blob/main/src/browser/electron-tier.ts): `src/browser/electron-tier.ts`
- [Chrome sessions](https://github.com/kenkaiii/pocket-agent/blob/main/src/browser/cdp-tier.ts): `src/browser/cdp-tier.ts`

### User interfaces and integrations

- [Telegram bot](https://github.com/kenkaiii/pocket-agent/blob/main/src/channels/telegram/index.ts): `src/channels/telegram/index.ts`
- [OAuth providers](https://github.com/kenkaiii/pocket-agent/blob/main/src/auth/oauth.ts): `src/auth/oauth.ts`
- [MCP servers](https://github.com/kenkaiii/pocket-agent/blob/main/src/mcp/project-server.ts): `src/mcp/project-server.ts`

### Other components

- **User**

## Connections

- User → Desktop app: uses (evidence: `README.md`)
- User → Telegram bot: messages (evidence: `README.md`)
- Desktop app → Agent manager: initializes (evidence: `src/main/index.ts`)
- Desktop app → Scheduler: initializes (evidence: `src/main/index.ts`)
- Desktop app → Telegram bot: initializes (evidence: `src/main/index.ts`)
- Agent manager → Chat engine: processes with (evidence: `src/agent/index.ts`)
- Chat engine → Model providers: gets config (evidence: `src/agent/chat-engine.ts`)
- Chat engine → Model selection: resolves model (evidence: `src/agent/chat-engine.ts`)
- Chat engine → Agent modes: builds routing (evidence: `src/agent/chat-engine.ts`)
- Chat engine → Agent tools: uses tools (evidence: `src/agent/chat-engine.ts`)
- Chat engine → Memory manager: loads history (evidence: `src/agent/chat-engine.ts`)
- Agent manager → Settings: reads settings (evidence: `src/agent/index.ts`)
- Agent tools → Browser automation: registers browser (evidence: `src/tools/index.ts`)
- Agent tools → Memory manager: registers memory tools (evidence: `src/tools/index.ts`)
- Memory manager → Daily logs: rolls up (evidence: `src/memory/index.ts`)
- Memory manager → Memory consolidation: delegates to (evidence: `src/memory/index.ts`)
- Personal facts → Semantic search: uses search (evidence: `src/memory/facts.ts`)
- Learned preferences → Semantic search: uses search (evidence: `src/memory/soul.ts`)
- Scheduler → Calendar and tasks: checks events (evidence: `src/scheduler/index.ts`)
- Scheduler → Proactive check-ins: composes prompt (evidence: `src/scheduler/index.ts`)
- Scheduler → Memory manager: records activity (evidence: `src/scheduler/index.ts`)
- Browser automation → Hidden browser: dispatches to (evidence: `src/browser/index.ts`)
- Browser automation → Chrome sessions: dispatches to (evidence: `src/browser/index.ts`)
- OAuth providers → Settings: stores credentials (evidence: `src/auth/oauth.ts`)