# zszz3/agentrecall architecture

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

- Interactive diagram: https://gitdiagram.com/zszz3/agentrecall
- Repository: https://github.com/zszz3/agentrecall

## Overview

AgentRecall is a desktop application for searching, inspecting, organizing, and resuming AI-coding-agent sessions. The README describes separate v1 and preview v2 applications with independent data stores. In v1, local agent sessions are indexed, queried, and presented for search and detail; optional branches cover remote sync, AI-assisted retrieval, skills, and MCP. V2 retains session management and adds reusable runtimes, multi-agent chat, workflows, evaluation, and directory memory. The sampled worker code confirms the v1 query path; other links reflect documented capabilities and tree structure, not inspected implementations.

Main entry points: [`apps/main-1.0/src/renderer/src/App.tsx`](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/renderer/src/App.tsx) (V1 Desktop UI), [`apps/main-2.0/src/automation/engine/renderer/src/pages/runtime/hooks/useRuntimeConfigManager.ts`](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/renderer/src/pages/runtime/hooks/useRuntimeConfigManager.ts) (V2 Desktop UI), [`apps/main-2.0/src/automation/engine/main/workflows/workflow-engine.ts`](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/workflows/workflow-engine.ts) (Workflow Engine), [`apps/main-1.0/src/main/services/local-session-query-service.ts`](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/services/local-session-query-service.ts) (Query Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v1_sessions["V1 Sessions"]
  node_v1_app["V1 Desktop UI<br/>[App.tsx]"]
  node_v1_query["Query Service"]
  node_v1_worker["Query Worker"]
  node_v1_runner["Query Runner"]
  node_v1_store[("Session Store<br/>[session-store.ts]")]
  node_v1_index["Session Indexer<br/>[indexer.ts]"]
  node_agent_sources["Agent Session Files"]
  node_v1_detail["Session Detail<br/>[detail-panel.tsx]"]
  node_v1_resume["Resume / Migration<br/>[resume-router.ts]"]
end

subgraph group_v1_extras["V1 Extensions"]
  node_v1_ai["AI Retrieval<br/>[ai-assistant.ts]"]
  node_v1_remote["Remote Sessions"]
  node_supabase(("Supabase"))
  node_v1_skills["Skills / Assets<br/>[skill-manager.ts]"]
  node_v1_mcp["MCP Tools<br/>[migration-entry.ts]"]
end

subgraph group_v2_sessions["V2 Sessions"]
  node_v2_app["V2 Desktop UI"]
  node_v2_sessions_node[("Session Platform")]
end

subgraph group_v2_automation["V2 Automation"]
  node_v2_chat["Agent Chat<br/>[agent-hub.ts]"]
  node_v2_runtime["Agent Runtime<br/>[runtime-router.ts]"]
  node_v2_workflow["Workflow Engine<br/>[workflow-engine.ts]"]
  node_v2_eval["Evaluation"]
  node_v2_workflow_store[("Workflow Storage<br/>[storage.ts]")]
end

subgraph group_v2_extensions["V2 Extensions"]
  node_v2_mcp["MCP Gateway<br/>[mcp-bridge.ts]"]
  node_v2_memory["Directory Memory<br/>[main]"]
  node_v2_skills["Skill Library<br/>[skill-manager.ts]"]
end

node_user(("User"))

node_user -->|"search / inspect"| node_v1_app
node_agent_sources -->|"index sessions"| node_v1_index
node_v1_index -->|"write index"| node_v1_store
node_v1_app -->|"query sessions"| node_v1_query
node_v1_query -->|"dispatch request"| node_v1_worker
node_v1_worker -->|"execute request"| node_v1_runner
node_v1_runner -->|"read sessions"| node_v1_store
node_v1_app -->|"open details"| node_v1_detail
node_v1_app -->|"resume / migrate"| node_v1_resume
node_v1_app -.->|"request AI help"| node_v1_ai
node_v1_app -.->|"sync sessions"| node_v1_remote
node_v1_remote -.->|"upload / restore"| node_supabase
node_v1_app -->|"manage skills"| node_v1_skills
node_v1_app -.->|"expose session tools"| node_v1_mcp
node_user -->|"use workbench"| node_v2_app
node_v2_app -->|"search / manage"| node_v2_sessions_node
node_v2_app -->|"start agent chat"| node_v2_chat
node_v2_app -->|"run workflow"| node_v2_workflow
node_v2_app -->|"run evaluation"| node_v2_eval
node_v2_chat -->|"route agent"| node_v2_runtime
node_v2_workflow -->|"execute nodes"| node_v2_runtime
node_v2_workflow -->|"load / save runs"| node_v2_workflow_store
node_v2_app -->|"connect tools"| node_v2_mcp
node_v2_app -->|"manage directory memory"| node_v2_memory
node_v2_app -->|"manage skills"| node_v2_skills

click node_v1_app "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/renderer/src/App.tsx"
click node_v1_query "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/services/local-session-query-service.ts"
click node_v1_worker "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/session-query-worker.ts"
click node_v1_runner "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/session-query-worker-runner.ts"
click node_v1_store "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/session-store.ts"
click node_v1_index "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/indexer.ts"
click node_v1_detail "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/renderer/src/features/session-detail/detail-panel.tsx"
click node_v1_resume "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/resume-router.ts"
click node_v1_ai "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/ai-assistant.ts"
click node_v1_remote "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/remote-session-sync.ts"
click node_v1_skills "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/skill-manager.ts"
click node_v1_mcp "https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/mcp/migration-entry.ts"
click node_v2_app "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/renderer/src/pages/runtime/hooks/useRuntimeConfigManager.ts"
click node_v2_sessions_node "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/core/postgres/session-repository.ts"
click node_v2_chat "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/hub/agent-hub.ts"
click node_v2_runtime "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/agents/runtime/runtime-router.ts"
click node_v2_workflow "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/workflows/workflow-engine.ts"
click node_v2_eval "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/evaluation-runner.ts"
click node_v2_workflow_store "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/shared/workflow-v2/storage.ts"
click node_v2_mcp "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/bridges/mcp-bridge.ts"
click node_v2_memory "https://github.com/zszz3/agentrecall/tree/main/apps/main-2.0/src/automation/engine/main"
click node_v2_skills "https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/core/skill-manager.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_v1_app,node_v1_query,node_v1_worker,node_v1_runner,node_v1_store,node_v1_index,node_agent_sources,node_v1_detail,node_v1_resume,node_user toneBlue
class node_v1_ai,node_v1_remote,node_supabase,node_v1_skills,node_v1_mcp toneAmber
class node_v2_app,node_v2_sessions_node toneMint
class node_v2_chat,node_v2_runtime,node_v2_workflow,node_v2_eval,node_v2_workflow_store toneRose
class node_v2_mcp,node_v2_memory,node_v2_skills toneIndigo
```

## Components

### V1 Sessions

- [V1 Desktop UI](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/renderer/src/App.tsx): `apps/main-1.0/src/renderer/src/App.tsx`
- [Query Service](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/services/local-session-query-service.ts): `apps/main-1.0/src/main/services/local-session-query-service.ts`
- [Query Worker](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/session-query-worker.ts): `apps/main-1.0/src/main/session-query-worker.ts`
- [Query Runner](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/main/session-query-worker-runner.ts): `apps/main-1.0/src/main/session-query-worker-runner.ts`
- [Session Store](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/session-store.ts): `apps/main-1.0/src/core/session-store.ts`
- [Session Indexer](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/indexer.ts): `apps/main-1.0/src/core/indexer.ts`
- **Agent Session Files**
- [Session Detail](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/renderer/src/features/session-detail/detail-panel.tsx): `apps/main-1.0/src/renderer/src/features/session-detail/detail-panel.tsx`
- [Resume / Migration](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/resume-router.ts): `apps/main-1.0/src/core/resume-router.ts`

### V1 Extensions

- [AI Retrieval](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/ai-assistant.ts): `apps/main-1.0/src/core/ai-assistant.ts`
- [Remote Sessions](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/remote-session-sync.ts): `apps/main-1.0/src/core/remote-session-sync.ts`
- **Supabase**
- [Skills / Assets](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/core/skill-manager.ts): `apps/main-1.0/src/core/skill-manager.ts`
- [MCP Tools](https://github.com/zszz3/agentrecall/blob/main/apps/main-1.0/src/mcp/migration-entry.ts): `apps/main-1.0/src/mcp/migration-entry.ts`

### V2 Sessions

- [V2 Desktop UI](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/renderer/src/pages/runtime/hooks/useRuntimeConfigManager.ts): `apps/main-2.0/src/automation/engine/renderer/src/pages/runtime/hooks/useRuntimeConfigManager.ts`
- [Session Platform](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/core/postgres/session-repository.ts): `apps/main-2.0/src/core/postgres/session-repository.ts`

### V2 Automation

- [Agent Chat](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/hub/agent-hub.ts): `apps/main-2.0/src/automation/engine/main/hub/agent-hub.ts`
- [Agent Runtime](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/agents/runtime/runtime-router.ts): `apps/main-2.0/src/automation/engine/main/agents/runtime/runtime-router.ts`
- [Workflow Engine](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/workflows/workflow-engine.ts): `apps/main-2.0/src/automation/engine/main/workflows/workflow-engine.ts`
- [Evaluation](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/evaluation-runner.ts): `apps/main-2.0/src/automation/engine/main/evaluation-runner.ts`
- [Workflow Storage](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/shared/workflow-v2/storage.ts): `apps/main-2.0/src/automation/engine/shared/workflow-v2/storage.ts`

### V2 Extensions

- [MCP Gateway](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/automation/engine/main/bridges/mcp-bridge.ts): `apps/main-2.0/src/automation/engine/main/bridges/mcp-bridge.ts`
- [Directory Memory](https://github.com/zszz3/agentrecall/tree/main/apps/main-2.0/src/automation/engine/main): `apps/main-2.0/src/automation/engine/main`
- [Skill Library](https://github.com/zszz3/agentrecall/blob/main/apps/main-2.0/src/core/skill-manager.ts): `apps/main-2.0/src/core/skill-manager.ts`

### Other components

- **User**

## Connections

- User → V1 Desktop UI: search / inspect
- Agent Session Files → Session Indexer: index sessions
- Session Indexer → Session Store: write index
- V1 Desktop UI → Query Service: query sessions
- Query Service → Query Worker: dispatch request
- Query Worker → Query Runner: execute request
- Query Runner → Session Store: read sessions
- V1 Desktop UI → Session Detail: open details
- V1 Desktop UI → Resume / Migration: resume / migrate
- V1 Desktop UI → AI Retrieval: request AI help
- V1 Desktop UI → Remote Sessions: sync sessions
- Remote Sessions → Supabase: upload / restore
- V1 Desktop UI → Skills / Assets: manage skills
- V1 Desktop UI → MCP Tools: expose session tools
- User → V2 Desktop UI: use workbench
- V2 Desktop UI → Session Platform: search / manage
- V2 Desktop UI → Agent Chat: start agent chat
- V2 Desktop UI → Workflow Engine: run workflow
- V2 Desktop UI → Evaluation: run evaluation
- Agent Chat → Agent Runtime: route agent
- Workflow Engine → Agent Runtime: execute nodes
- Workflow Engine → Workflow Storage: load / save runs
- V2 Desktop UI → MCP Gateway: connect tools
- V2 Desktop UI → Directory Memory: manage directory memory
- V2 Desktop UI → Skill Library: manage skills