# sumoksh1/ai-research-agent architecture

> Architecture diagram of the GitHub repository sumoksh1/ai-research-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sumoksh1/ai-research-agent
- Repository: https://github.com/sumoksh1/ai-research-agent

## Overview

AI Research Agent is an interactive CLI assistant for research and coding. Users submit a request for direct ReAct execution or sequential planned tasks; the agent consults Gemini, dispatches tools, and returns results. Short-term conversation state and SQLite-backed long-term memory support those workflows, with memory viewing and conversation clearing available from the menu. The graph preserves the documented research, calculation, workspace, and memory tool capabilities. Some tool implementations were not excerpted, so their documented roles are shown without guessed internal call relationships.

Main entry points: [`src/agent/features/chat/agent.py`](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/chat/agent.py) (ReAct agent), [`src/agent/core/tool_registry.py`](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/core/tool_registry.py) (Tool registry), [`src/agent/app.py`](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/app.py) (Interactive menu), [`src/agent/features/planning/planner.py`](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/planning/planner.py) (Plan execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["CLI and execution"]
  node_cli["Interactive menu<br/>[app.py]"]
  node_session["Conversation session<br/>[session.py]"]
  node_planner["Plan execution<br/>[planner.py]"]
end

subgraph group_reasoning["Agent reasoning"]
  node_agent["ReAct agent<br/>[agent.py]"]
  node_llm["Gemini client<br/>[llm.py]"]
  node_registry["Tool registry<br/>[tool_registry.py]"]
end

subgraph group_memory["Memory"]
  node_memory_store[("SQLite memory store<br/>[store.py]")]
  node_retrieval["Memory retrieval<br/>[retrieval.py]"]
  node_extraction["Memory extraction<br/>[extraction.py]"]
  node_memory_view["Memory viewing<br/>[view.py]"]
end

subgraph group_tools["Agent tools"]
  node_web_search["Web search<br/>[web_search.py]"]
  node_fetch_page["Page fetch<br/>[fetch_page.py]"]
  node_calculator["Calculator<br/>[calculator.py]"]
  node_workspace_tools["Workspace files"]
  node_workspace_guard["Workspace path guard<br/>[_workspace.py]"]
  node_memory_tools["Memory tools"]
end

node_user(("CLI user"))
node_gemini["Gemini API"]

node_user -->|"submits request"| node_cli
node_cli -->|"runs directly"| node_agent
node_cli -->|"runs plan"| node_planner
node_cli -->|"views memories"| node_memory_view
node_cli -->|"clears history"| node_session
node_planner -->|"runs each task"| node_agent
node_planner -->|"generates plan"| node_llm
node_agent -->|"adds messages"| node_session
node_agent -->|"builds context"| node_retrieval
node_retrieval -->|"retrieves facts"| node_memory_store
node_agent -->|"requests response"| node_llm
node_llm -->|"calls API"| node_gemini
node_agent -->|"dispatches tools"| node_registry
node_registry -->|"executes handler"| node_web_search
node_registry -->|"executes handler"| node_fetch_page
node_registry -->|"executes handler"| node_calculator
node_registry -->|"executes handler"| node_workspace_tools
node_registry -->|"executes handler"| node_memory_tools
node_workspace_tools -->|"validates paths"| node_workspace_guard
node_workspace_tools -->|"reads or writes files"| node_user
node_agent -->|"saves user facts"| node_extraction
node_planner -->|"saves request"| node_extraction
node_extraction -->|"stores facts"| node_memory_store
node_extraction -->|"extracts facts"| node_llm
node_memory_tools -.->|"searches or deletes"| node_memory_store
node_memory_view -.->|"lists facts"| node_memory_store

click node_cli "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/app.py"
click node_session "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/chat/session.py"
click node_planner "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/planning/planner.py"
click node_agent "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/chat/agent.py"
click node_llm "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/core/llm.py"
click node_registry "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/core/tool_registry.py"
click node_web_search "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/web_search.py"
click node_fetch_page "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/fetch_page.py"
click node_calculator "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/calculator.py"
click node_workspace_tools "https://github.com/sumoksh1/ai-research-agent/tree/main/src/agent/features/tools"
click node_workspace_guard "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/_workspace.py"
click node_memory_tools "https://github.com/sumoksh1/ai-research-agent/tree/main/src/agent/features/tools"
click node_memory_store "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/store.py"
click node_retrieval "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/retrieval.py"
click node_extraction "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/extraction.py"
click node_memory_view "https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/view.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_cli,node_session,node_planner,node_user toneBlue
class node_agent,node_llm,node_registry toneAmber
class node_memory_store,node_retrieval,node_extraction,node_memory_view,node_gemini toneMint
class node_web_search,node_fetch_page,node_calculator,node_workspace_tools,node_workspace_guard,node_memory_tools toneRose
```

## Components

### CLI and execution

- [Interactive menu](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/app.py): `src/agent/app.py`
- [Conversation session](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/chat/session.py): `src/agent/features/chat/session.py`
- [Plan execution](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/planning/planner.py): `src/agent/features/planning/planner.py`

### Agent reasoning

- [ReAct agent](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/chat/agent.py): `src/agent/features/chat/agent.py`
- [Gemini client](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/core/llm.py): `src/agent/core/llm.py`
- [Tool registry](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/core/tool_registry.py): `src/agent/core/tool_registry.py`

### Memory

- [SQLite memory store](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/store.py): `src/agent/features/memory/store.py`
- [Memory retrieval](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/retrieval.py): `src/agent/features/memory/retrieval.py`
- [Memory extraction](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/extraction.py): `src/agent/features/memory/extraction.py`
- [Memory viewing](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/memory/view.py): `src/agent/features/memory/view.py`

### Agent tools

- [Web search](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/web_search.py): `src/agent/features/tools/web_search.py`
- [Page fetch](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/fetch_page.py): `src/agent/features/tools/fetch_page.py`
- [Calculator](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/calculator.py): `src/agent/features/tools/calculator.py`
- [Workspace files](https://github.com/sumoksh1/ai-research-agent/tree/main/src/agent/features/tools): `src/agent/features/tools`
- [Workspace path guard](https://github.com/sumoksh1/ai-research-agent/blob/main/src/agent/features/tools/_workspace.py): `src/agent/features/tools/_workspace.py`
- [Memory tools](https://github.com/sumoksh1/ai-research-agent/tree/main/src/agent/features/tools): `src/agent/features/tools`

### Other components

- **CLI user**
- **Gemini API**

## Connections

- CLI user → Interactive menu: submits request (evidence: `src/agent/app.py`)
- Interactive menu → ReAct agent: runs directly (evidence: `src/agent/app.py`)
- Interactive menu → Plan execution: runs plan (evidence: `src/agent/app.py`)
- Interactive menu → Memory viewing: views memories (evidence: `src/agent/app.py`)
- Interactive menu → Conversation session: clears history (evidence: `src/agent/app.py`)
- Plan execution → ReAct agent: runs each task (evidence: `src/agent/features/planning/planner.py`)
- Plan execution → Gemini client: generates plan (evidence: `src/agent/features/planning/planner.py`)
- ReAct agent → Conversation session: adds messages (evidence: `src/agent/features/chat/agent.py`)
- ReAct agent → Memory retrieval: builds context (evidence: `src/agent/features/chat/agent.py`)
- Memory retrieval → SQLite memory store: retrieves facts (evidence: `src/agent/features/memory/retrieval.py`)
- ReAct agent → Gemini client: requests response (evidence: `src/agent/features/chat/agent.py`)
- Gemini client → Gemini API: calls API (evidence: `src/agent/core/llm.py`)
- ReAct agent → Tool registry: dispatches tools (evidence: `src/agent/features/chat/agent.py`)
- Tool registry → Web search: executes handler (evidence: `src/agent/features/tools/__init__.py`)
- Tool registry → Page fetch: executes handler (evidence: `src/agent/features/tools/__init__.py`)
- Tool registry → Calculator: executes handler (evidence: `src/agent/features/tools/__init__.py`)
- Tool registry → Workspace files: executes handler (evidence: `README.md`)
- Tool registry → Memory tools: executes handler (evidence: `src/agent/features/tools/__init__.py`)
- Workspace files → Workspace path guard: validates paths (evidence: `src/agent/features/tools/write_file.py`)
- Workspace files → CLI user: reads or writes files (evidence: `README.md`)
- ReAct agent → Memory extraction: saves user facts (evidence: `src/agent/features/chat/agent.py`)
- Plan execution → Memory extraction: saves request (evidence: `src/agent/features/planning/planner.py`)
- Memory extraction → SQLite memory store: stores facts (evidence: `src/agent/features/memory/extraction.py`)
- Memory extraction → Gemini client: extracts facts (evidence: `src/agent/features/memory/extraction.py`)
- Memory tools → SQLite memory store: searches or deletes
- Memory viewing → SQLite memory store: lists facts
