Algo Builder Agent Architecture

This page documents the Algo Builder Agent as an in-app and MCP-accessible chat-based research and execution agent for the full algorithmic trading lifecycle: market research, algorithm design, backtesting, optimization, deployment to algo wallets, and portfolio-level monitoring and rebalancing.

Mental Model

The Algo Builder Agent is structured around two key inversions of the discretionary runtime:

One instance per user, not one per wallet. The discretionary agent is 1-to-1 with an isolated agent wallet; the algo builder is 1-to-1 with the user.
Sessions share a per-user persistent file system, instead of sharing a per-session live trading state. Multiple chat sessions write to and read from the same memory tree — that tree is the long-term research workspace.

It is:

a chat-based research agent
session-based for conversation, but instance-based for memory
tool-driven rather than live-context-injected
focused on the full algo lifecycle: research → build → backtest → optimize → deploy → monitor → rebalance

It does not maintain a per-session live trading runtime, autonomous alert threads, or per-turn injected account snapshots.

Main Components

backend/services/agent/index.ts
backend/services/agent/system-prompt.ts
backend/services/agent/ws/handler.ts
backend/core/agent-core/agent-loop.ts
backend/core/agent-core/stream-processor.ts
backend/services/agent/tools/*
frontend/src/features/agent/*

Where It Runs

The Algo Builder Agent appears in two related surfaces sharing the same backend tool registry:

In-app agent UI

The React agent panel inside the Reversion app provides:

chat sessions (multiple per user, all tied to the same memory FS)
streaming assistant turns
queued follow-up messages
tool-call rendering
model/provider selection
memory FS browsing and editing

External MCP clients

Claude Desktop, Cursor, VS Code, and other MCP-compatible apps drive the same backend tool surface through Reversion MCP.

The MCP server is an external transport into the same broader agent/tool ecosystem.

Architecture

Browser chat panel or MCP client
    ↕ WebSocket or MCP tool calls
services/agent transport + session handling
    ↕ shared runAgentTurn(...)
shared tool registry and python workers
    ↕ backend APIs / compute workers / exchange integrations
Reversion platform capabilities

Session Model

The Algo Builder Agent uses standard chat sessions, but with a critical addition: per-user persistent memory shared across sessions.

Each session owns:

transcript history
selected model/provider
queued pending user messages
streaming state
tool-call history
a session-only scratchpad (scratch_* tools, lost on session end)

All sessions for the same user share:

the persistent memory filesystem (memory_read, memory_write, memory_list, memory_append, memory_search)
the user’s algo wallets (their account context)
the user’s algorithm configs and run history

This is intentionally inverted from the discretionary agent’s session-scoped runtime model: discretionary sessions wrap a wallet-scoped trading environment, while algo builder sessions are conversation views over a user-scoped research workspace.

Per-User Memory File System

The persistent memory is the primary mechanism for offloaded research context. Typical usage:

/research/btc/regime-2026q2.md — regime observations
/strategies/{algo_id}/notes.md — design rationale, test history
/insights/optimizations.md — appended findings from optimization runs
/insights/strategy-failures.md — appended post-mortems
/user/preferences.md — risk tolerance, preferred indicators, style

Because every session reads the same tree, a strategy designed in one chat is instantly visible to a portfolio review chat opened later. Treat the memory FS like a research notebook the agent and user co-author.

Account Context — Algo Wallets

The agent’s “account state” is the user’s set of algo wallets, exposed through the get_algo_wallets_overview tool. Each wallet entry includes:

funded balance (total, free, used, equity, unrealizedPnl)
open positions and orders
vacant flag (no assigned run vs. running one)
when occupied: assigned run + algo config + live performance metrics (PnL, Sharpe, drawdown, win rate, equity curve metadata)

If the user has no algo wallets, the overview returns an empty list with a summary.message instructing the agent to direct the user to the wallet manager.

The agent does not see:

the manual trading account
discretionary positions or wallets
agent wallets owned by the discretionary runtime

Turn Model

At a high level, an Algo Builder Agent turn does:

receive user input through websocket transport (or MCP tool call)
resolve the target chat session
resolve provider/model credentials
compose the system prompt: base instructions + active skill stack + per-session context
construct the tool registry for the session’s selected scope
run the shared agent loop
stream deltas and tool states back to the frontend

This is intentionally closer to a standard tool-augmented research assistant than a stateful trading runtime — but the lifecycle tools (deploy_algo_to_wallet, stop_algo_run, get_algo_wallets_overview) put live deployment and portfolio monitoring inside the same chat surface.

Tool Surface

The Algo Builder Agent uses the general agent tool registry in:

backend/services/agent/tools/*

Major tool families:

account / portfolio — get_algo_wallets_overview (algo wallets list with live state)
market data — prices, funding, orderbooks, charts
algorithm CRUD — list_algorithms, create_algorithm, add_indicator, set_stop_take_profit, show_algorithm
backtesting — run_backtest, get_backtest_results, plot_backtest, rolling_cv_backtest
optimization — Bayesian param sweeps with progress + plotting
deployment — deploy_algo_to_wallet (live), stop_algo_run (graceful stop, frees wallet)
memory — persistent per-user FS (memory_*) and session scratchpad (scratch_*)
skill stack — stack_push, stack_pop, stack_list for runtime prompt composition
calendar / web / social — research support

The same family is exposed externally through the MCP docs.

Algo Deployment Model

Algo wallets and deployments are wired together through the apiWallets.assignedRunId slot:

walletGroup = 'algo' and custodyType = 'privy'
one assigned run at a time per wallet — the wallet is the deployment target
POST /algo/runs with walletId creates a run record AND assigns it to the wallet
the algo runner (backend/services/algo/stateless-loop.ts, port 3200) polls and executes
on graceful stop (PATCH /algo/runs/:runId/status with STOPPING), the runner closes any open position (if closePositionOnExit), then transitions to DONE and the wallet’s assignedRunId is cleared

Sizing, leverage, and starting capital live on the run record — they cannot be hot-swapped. To change them, stop the run and redeploy.

Capital Rebalancing

The agent recommends but does not execute wallet-level capital movements:

It reads balance.free (unencumbered USDC) and balance.used (locked margin) per wallet
It proposes transfers with concrete numbers and constraints
The user executes through the wallet manager UI

The algo runner does not coordinate with rebalances — it operates on the live wallet balance, and Hyperliquid enforces the margin invariant. Withdrawals beyond balance.free are physically impossible.

For sizing-config rebalances within a running algo, the pattern is stop_algo_run → edit algo config → deploy_algo_to_wallet.

Python / Compute Boundary

The Algo Builder Agent owns the general-purpose analysis worker side of the system:

chart and research-oriented python tooling
optimization plotting
algorithm research compute helpers

This is intentionally separate from the discretionary agent’s dedicated worker/runtime path.

Frontend UX Model

The in-app Algo Builder Agent UI is a chat interface with:

multiple sessions (all tied to the same per-user memory FS)
streaming status
queued messages
tool-call blocks
markdown responses
a memory FS browser

The discretionary widget needs additional live-state panels and alert-thread UX, which the algo builder does not.

Difference From The Discretionary Agent

Algo Builder Agent	Discretionary Agent
one instance per user	one instance per agent wallet
sessions share a per-user persistent memory FS	threads share a per-session live trading runtime
no autonomous alert threads	autonomous alert threads + chat threads
no per-turn injected live account environment	canonical runtime snapshot injected each turn
sees the user’s portfolio of algo wallets	sees one isolated agent wallet HL account
algo design + deploy + portfolio monitoring tools	discretionary entry + watcher + alert tools
no agent-layer risk caps	portfolio + per-market caps + drawdown penalty + lockout
simpler chat-centric UX with FS browser	chat + live account + alert runtime UX

Summary

The Algo Builder Agent is Reversion’s research-and-portfolio agent:

one workspace per user with shared persistent memory across chat sessions
direct access to the user’s portfolio of algo wallets
end-to-end lifecycle tooling: research, build, backtest, optimize, deploy, monitor, rebalance
complementary to the discretionary agent’s per-wallet live trading runtime