Skip to content

Clarify memory and architecture in README #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
exqqstar merged 1 commit into from
Jun 21, 2026
Merged

Clarify memory and architecture in README #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 46 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,19 @@ inspect runtime state, and resume the thread later from durable local history.

It is not just a chat UI. ExAgent includes the runtime pieces needed for
recoverable agent work: event replay, persistent shell sessions, approval-gated
tools, subagents, goal tracking, procedural memory, MCP tools, and a desktop
inspector for what the agent is doing.
tools, subagents, goal tracking, project memory, MCP tools, workflow runs, and
a desktop inspector for what the agent is doing.
Comment on lines +28 to +29

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Qualify disabled workflow runs

In the desktop UI, WORKFLOW_RUNTIME_ENABLED is hard-coded to false, which keeps canStartWorkflow false and shows users that starting new workflow runs is temporarily disabled / the public build does not expose the run entry (apps/desktop/src/components/WorkflowLibrary.tsx). Advertising “workflow runs” here as a current recoverable-agent capability makes Download/Quickstart users expect a feature they cannot start, so please mark it as in-progress or architecture-only, and mirror the clarification in the Chinese README.

Useful? React with 👍 / 👎.


## Highlights

- Desktop-first local agent workbench for coding projects
- Durable sessions that can be reopened from local project history
- GUI provider setup for API-key and OAuth-based model providers
- Approval-gated coding tools with live transcript and event inspection
- Persistent shells, subagents, goals, MCP tools, and `SKILL.md` support
- Project memory with automatic recall, explicit memory tools, local curation,
and audit state
- Persistent shells, subagents, goals, MCP tools, workflows, and `SKILL.md`
support

## Download

Expand Down Expand Up @@ -78,6 +81,33 @@ or file mutation, the app shows an approval card in the transcript.
For a fuller operator walkthrough, see
[docs/demo/exagent-walkthrough.md](docs/demo/exagent-walkthrough.md).

## Architecture At A Glance

ExAgent is organized around a local Rust runtime exposed to the desktop through
a typed app-server boundary. The Tauri shell stays project-aware while the
runtime owns thread execution, model calls, tools, state, and live events.

- Each thread runs behind an actor-backed `ThreadRuntime`, so turns are
serialized while snapshots, status, and events stream back to the GUI.
- `ThreadSession` assembles the long-lived pieces for one thread: agent,
context, rollout storage, tools, goals, memory, policy, and execution
sessions.
- The context layer keeps real conversation history separate from prompt-only
internal context such as memory recall, goal state, skills, and project docs;
compaction can replace long history with structured summaries.
- Local durability is append-first: each thread has a `rollout.jsonl` ledger,
while `IndexDb` stores cross-thread indexes for projects, threads, goals,
memory, and review state.
- The tool system separates public tool contracts in `src/tools` from per-turn
runtime orchestration in `src/runtime/tool`; agent policy gates both tool
visibility and execution.
- The memory system supports automatic prompt recall, explicit memory tools,
candidate saves, local promotion/archive/forget flows, and audit state.
- The model layer normalizes provider-specific APIs into ExAgent conversation,
tool-call, multimodal, reasoning, and streaming types.
- The workflow runtime powers structured runs such as deep search as a
phase-based scheduler parallel to the normal chat turn loop.

## Development

Useful commands from `apps/desktop`:
Expand Down Expand Up @@ -115,11 +145,23 @@ Current non-goals:
- [apps/desktop](apps/desktop): Tauri desktop shell and React workbench
- [apps/desktop/src-tauri](apps/desktop/src-tauri): desktop Rust commands,
settings, provider auth, and Tauri entrypoint
- [src/app_server](src/app_server): typed desktop/runtime boundary, request
processors, live views, and projections
- [src/runtime](src/runtime): live execution kernel, thread actor, session turn
loop, agent sampling, tool runtime, policy, and exec sessions
- [src/runtime/agent_profile](src/runtime/agent_profile): agent role catalog
and capability policy
- [src/runtime/goal](src/runtime/goal): structured goal state, accounting, and
continuation effects
- [src/runtime/memory](src/runtime/memory): runtime memory bridge into context
and tools
- [src/runtime/workflow](src/runtime/workflow): structured workflow and deep
search runtime
- [src/tools](src/tools): tool trait, registry, and built-in coding tools
- [src/state](src/state): durable rollout models plus desktop index storage
- [src/state](src/state): durable rollout models, desktop index storage, and
memory state
- [src/model](src/model): model provider adapters and conversation types
- [src/mcp](src/mcp): MCP configuration and tool integration
- [tests](tests): integration coverage for runtime, protocol, policy, tools,
and storage
- [docs/demo](docs/demo): desktop-first walkthroughs
Expand Down
26 changes: 23 additions & 3 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,16 @@

ExAgent 是一个桌面优先的代理工作台，底层是 Rust 运行时，桌面应用使用 Tauri 和 React 构建。它面向本地项目里的长时间编码工作：启动会话、选择 provider/model、审批工具动作、检查运行时状态，并在之后从本地持久历史中恢复线程。

它不只是一个聊天 UI。ExAgent 包含可恢复代理工作的运行时能力：事件回放、持久 shell 会话、带审批的工具、子代理、目标跟踪、过程记忆、MCP 工具，以及用于观察代理行为的桌面检查器。
它不只是一个聊天 UI。ExAgent 包含可恢复代理工作的运行时能力：事件回放、持久 shell 会话、带审批的工具、子代理、目标跟踪、项目记忆、MCP 工具、workflow runs，以及用于观察代理行为的桌面检查器。

## 亮点

- 面向编码项目的本地桌面代理工作台
- 可从本地项目历史重新打开的持久会话
- 用 GUI 配置 API key 和 OAuth 模型 provider
- 带审批的编码工具、实时 transcript 和事件检查
- 持久 shell、子代理、目标、MCP 工具和 `SKILL.md` 支持
- 项目记忆，支持自动 recall、显式 memory tools、本地治理和 audit state
- 持久 shell、子代理、目标、MCP 工具、workflows 和 `SKILL.md` 支持

## 下载

Expand Down Expand Up @@ -64,6 +65,19 @@ npm run tauri:dev

更完整的操作 walkthrough 见 [docs/demo/exagent-walkthrough.md](docs/demo/exagent-walkthrough.md)。

## 架构概览

ExAgent 围绕本地 Rust runtime 组织，并通过 typed app-server boundary 暴露给桌面端。Tauri shell 负责项目感知的桌面入口，runtime 负责 thread 执行、模型调用、工具、状态和实时事件。

- 每个 thread 都运行在 actor-backed `ThreadRuntime` 后面，因此同一 thread 的 turns 会被串行化，同时 snapshots、status 和 events 会流回 GUI。
- `ThreadSession` 装配一个 thread 的长期运行部件：agent、context、rollout storage、tools、goals、memory、policy 和 execution sessions。
- context 层把真实 conversation history 和 prompt-only internal context 分开；memory recall、goal state、skills、project docs 等只进入 prompt，compaction 可以把长历史替换成结构化摘要。
- 本地持久化是 append-first：每个 thread 有自己的 `rollout.jsonl` ledger，`IndexDb` 存 projects、threads、goals、memory 和 review state 的跨线程索引。
- tool system 把 `src/tools` 里的公开 tool contracts 和 `src/runtime/tool` 里的 per-turn runtime orchestration 分开；agent policy 同时约束工具可见性和执行权限。
- memory system 支持自动 prompt recall、显式 memory tools、candidate saves、本地 promote/archive/forget 流程和 audit state。
- model 层把不同 provider 的 API 统一成 ExAgent 内部的 conversation、tool-call、multimodal、reasoning 和 streaming 类型。
- workflow runtime 以 phase-based scheduler 的方式运行 deep search 等结构化任务，它和普通 chat turn loop 是平行的执行模型。

## 开发

在 `apps/desktop` 下常用命令：
Expand Down Expand Up @@ -99,10 +113,16 @@ ExAgent 仍处于早期阶段，当前主要面向个人工作站上的本地优

- [apps/desktop](apps/desktop)：Tauri 桌面 shell 和 React 工作台
- [apps/desktop/src-tauri](apps/desktop/src-tauri)：桌面 Rust commands、settings、provider auth 和 Tauri entrypoint
- [src/app_server](src/app_server)：typed desktop/runtime boundary、request processors、live views 和 projections
- [src/runtime](src/runtime)：实时执行内核、thread actor、session turn loop、agent sampling、tool runtime、policy 和 exec sessions
- [src/runtime/agent_profile](src/runtime/agent_profile)：agent role catalog 和 capability policy
- [src/runtime/goal](src/runtime/goal)：structured goal state、accounting 和 continuation effects
- [src/runtime/memory](src/runtime/memory)：runtime memory bridge，负责接入 context 和 tools
- [src/runtime/workflow](src/runtime/workflow)：structured workflow 和 deep search runtime
- [src/tools](src/tools)：tool trait、registry 和内置编码工具
- [src/state](src/state)：持久 rollout model 和桌面 index storage
- [src/state](src/state)：持久 rollout model、桌面 index storage 和 memory state
- [src/model](src/model)：模型 provider adapters 和 conversation types
- [src/mcp](src/mcp)：MCP configuration 和 tool integration
- [tests](tests)：runtime、protocol、policy、tools 和 storage 的集成测试
- [docs/demo](docs/demo)：桌面优先 walkthrough

Expand Down