# nastechresearch/nastech-agent architecture

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

- Interactive diagram: https://gitdiagram.com/nastechresearch/nastech-agent
- Repository: https://github.com/nastechresearch/nastech-agent

## Overview

Nastech Agent is a self-improving conversational AI agent, exposed through CLI/TUI and messaging integrations, with a companion desktop app. A user submits a request, the agent runs a model/tool conversation, then returns a response; learning, memory, scheduling, delegation, and research capabilities form important additional branches. The README documents these capabilities, but sampled source is limited, so the graph shows documented product relationships rather than asserting unsampled implementation calls.

Main entry points: [`agent/conversation_loop.py`](https://github.com/nastechresearch/nastech-agent/blob/main/agent/conversation_loop.py) (Conversation loop), [`agent/session_persistence.py`](https://github.com/nastechresearch/nastech-agent/blob/main/agent/session_persistence.py) (Session persistence), [`agent`](https://github.com/nastechresearch/nastech-agent/tree/main/agent) (Messaging gateway), [`apps/desktop/src/api/client.ts`](https://github.com/nastechresearch/nastech-agent/blob/main/apps/desktop/src/api/client.ts) (Desktop API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[console_engine.py]"]
  node_tui["Terminal UI"]
  node_acp["ACP adapter<br/>[entry.py]"]
  node_gateway["Messaging gateway"]
end

subgraph group_agent_runtime["Agent runtime"]
  node_loop["Conversation loop"]
  node_context["Context engine<br/>[context_engine.py]"]
  node_tools["Tool execution<br/>[tool_executor.py]"]
  node_subagents["Subagents"]
  node_sessions[("Session persistence")]
end

subgraph group_learning["Learning and memory"]
  node_memory["Curated memory<br/>[memory_manager.py]"]
  node_skills["Skill learning<br/>[skill_utils.py]"]
  node_session_search["Session search"]
  node_user_model["User modeling"]
  node_trajectory["Trajectory research<br/>[trajectory.py]"]
end

subgraph group_integrations["Providers and automation"]
  node_providers["Model providers"]
  node_terminal["Terminal backends"]
  node_scheduler["Scheduled automation"]
end

subgraph group_desktop["Desktop application"]
  node_desktop["Desktop app"]
  node_desktop_api["Desktop API client<br/>[client.ts]"]
  node_desktop_main["Electron main<br/>[main.ts]"]
end

node_user(("User"))
node_platforms(("Messaging platforms"))
node_model_service(("Model services"))

node_user -->|"submits request"| node_cli
node_user -->|"enters request"| node_tui
node_user -->|"sends request"| node_acp
node_user -->|"chats"| node_desktop
node_platforms -->|"deliver messages"| node_gateway
node_cli -->|"starts conversation"| node_loop
node_tui -->|"sends conversation"| node_loop
node_acp -->|"bridges conversation"| node_loop
node_gateway -->|"routes messages"| node_loop
node_desktop -->|"requests data"| node_desktop_api
node_desktop_api -.->|"calls backend"| node_gateway
node_loop -->|"prepares context"| node_context
node_loop -->|"requests completion"| node_providers
node_providers -->|"sends requests"| node_model_service
node_loop -->|"dispatches tools"| node_tools
node_tools -->|"runs commands"| node_terminal
node_loop -->|"persists session"| node_sessions
node_loop -->|"delegates work"| node_subagents
node_loop -->|"uses memory"| node_memory
node_memory -.->|"supports learning"| node_skills
node_sessions -.->|"provides history"| node_session_search
node_sessions -.->|"provides history"| node_user_model
node_loop -.->|"records trajectories"| node_trajectory
node_scheduler -->|"starts automations"| node_loop
node_desktop_main -.->|"hosts app services"| node_desktop_api

click node_cli "https://github.com/nastechresearch/nastech-agent/blob/main/nastech_cli/console_engine.py"
click node_tui "https://github.com/nastechresearch/nastech-agent/blob/main/ui-tui/src/app/useInputHandlers.ts"
click node_acp "https://github.com/nastechresearch/nastech-agent/blob/main/acp_adapter/entry.py"
click node_gateway "https://github.com/nastechresearch/nastech-agent/tree/main/agent"
click node_loop "https://github.com/nastechresearch/nastech-agent/blob/main/agent/conversation_loop.py"
click node_context "https://github.com/nastechresearch/nastech-agent/blob/main/agent/context_engine.py"
click node_tools "https://github.com/nastechresearch/nastech-agent/blob/main/agent/tool_executor.py"
click node_subagents "https://github.com/nastechresearch/nastech-agent/blob/main/agent/subagent_lifecycle.py"
click node_sessions "https://github.com/nastechresearch/nastech-agent/blob/main/agent/session_persistence.py"
click node_memory "https://github.com/nastechresearch/nastech-agent/blob/main/agent/memory_manager.py"
click node_skills "https://github.com/nastechresearch/nastech-agent/blob/main/agent/skill_utils.py"
click node_session_search "https://github.com/nastechresearch/nastech-agent/tree/main/agent"
click node_user_model "https://github.com/nastechresearch/nastech-agent/tree/main/agent"
click node_trajectory "https://github.com/nastechresearch/nastech-agent/blob/main/agent/trajectory.py"
click node_providers "https://github.com/nastechresearch/nastech-agent/blob/main/agent/provider_registry.py"
click node_terminal "https://github.com/nastechresearch/nastech-agent/tree/main/agent"
click node_scheduler "https://github.com/nastechresearch/nastech-agent/blob/main/agent/periodic_scheduler.py"
click node_desktop "https://github.com/nastechresearch/nastech-agent/tree/main/apps/desktop/src/app/chat"
click node_desktop_api "https://github.com/nastechresearch/nastech-agent/blob/main/apps/desktop/src/api/client.ts"
click node_desktop_main "https://github.com/nastechresearch/nastech-agent/blob/main/apps/desktop/electron/main.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_cli,node_tui,node_acp,node_gateway,node_user toneBlue
class node_loop,node_context,node_tools,node_subagents,node_sessions toneAmber
class node_memory,node_skills,node_session_search,node_user_model,node_trajectory toneMint
class node_providers,node_terminal,node_scheduler toneRose
class node_desktop,node_desktop_api,node_desktop_main,node_platforms,node_model_service toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/nastechresearch/nastech-agent/blob/main/nastech_cli/console_engine.py): `nastech_cli/console_engine.py`
- [Terminal UI](https://github.com/nastechresearch/nastech-agent/blob/main/ui-tui/src/app/useInputHandlers.ts): `ui-tui/src/app/useInputHandlers.ts`
- [ACP adapter](https://github.com/nastechresearch/nastech-agent/blob/main/acp_adapter/entry.py): `acp_adapter/entry.py`
- [Messaging gateway](https://github.com/nastechresearch/nastech-agent/tree/main/agent): `agent`

### Agent runtime

- [Conversation loop](https://github.com/nastechresearch/nastech-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Context engine](https://github.com/nastechresearch/nastech-agent/blob/main/agent/context_engine.py): `agent/context_engine.py`
- [Tool execution](https://github.com/nastechresearch/nastech-agent/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Subagents](https://github.com/nastechresearch/nastech-agent/blob/main/agent/subagent_lifecycle.py): `agent/subagent_lifecycle.py`
- [Session persistence](https://github.com/nastechresearch/nastech-agent/blob/main/agent/session_persistence.py): `agent/session_persistence.py`

### Learning and memory

- [Curated memory](https://github.com/nastechresearch/nastech-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Skill learning](https://github.com/nastechresearch/nastech-agent/blob/main/agent/skill_utils.py): `agent/skill_utils.py`
- [Session search](https://github.com/nastechresearch/nastech-agent/tree/main/agent): `agent`
- [User modeling](https://github.com/nastechresearch/nastech-agent/tree/main/agent): `agent`
- [Trajectory research](https://github.com/nastechresearch/nastech-agent/blob/main/agent/trajectory.py): `agent/trajectory.py`

### Providers and automation

- [Model providers](https://github.com/nastechresearch/nastech-agent/blob/main/agent/provider_registry.py): `agent/provider_registry.py`
- [Terminal backends](https://github.com/nastechresearch/nastech-agent/tree/main/agent): `agent`
- [Scheduled automation](https://github.com/nastechresearch/nastech-agent/blob/main/agent/periodic_scheduler.py): `agent/periodic_scheduler.py`

### Desktop application

- [Desktop app](https://github.com/nastechresearch/nastech-agent/tree/main/apps/desktop/src/app/chat): `apps/desktop/src/app/chat`
- [Desktop API client](https://github.com/nastechresearch/nastech-agent/blob/main/apps/desktop/src/api/client.ts): `apps/desktop/src/api/client.ts`
- [Electron main](https://github.com/nastechresearch/nastech-agent/blob/main/apps/desktop/electron/main.ts): `apps/desktop/electron/main.ts`

### Other components

- **User**
- **Messaging platforms**
- **Model services**

## Connections

- User → CLI: submits request
- User → Terminal UI: enters request
- User → ACP adapter: sends request
- User → Desktop app: chats
- Messaging platforms → Messaging gateway: deliver messages
- CLI → Conversation loop: starts conversation
- Terminal UI → Conversation loop: sends conversation
- ACP adapter → Conversation loop: bridges conversation
- Messaging gateway → Conversation loop: routes messages
- Desktop app → Desktop API client: requests data
- Desktop API client → Messaging gateway: calls backend
- Conversation loop → Context engine: prepares context
- Conversation loop → Model providers: requests completion
- Model providers → Model services: sends requests
- Conversation loop → Tool execution: dispatches tools
- Tool execution → Terminal backends: runs commands
- Conversation loop → Session persistence: persists session
- Conversation loop → Subagents: delegates work
- Conversation loop → Curated memory: uses memory
- Curated memory → Skill learning: supports learning
- Session persistence → Session search: provides history
- Session persistence → User modeling: provides history
- Conversation loop → Trajectory research: records trajectories
- Scheduled automation → Conversation loop: starts automations
- Electron main → Desktop API client: hosts app services