Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/theonetrade/ai-trading-mcp/llms.txt

Use this file to discover all available pages before exploring further.

The engine distinguishes sharply between live and backtest (paper) persistence: live state is written to disk and survives restarts, while paper and backtest counterparts stay in memory or local temporary storage. This means you can kill and restart the trading process at any time without losing an open position, its brackets, or any of the history the agent has seen.

​
Live vs Backtest Persistence

Persistence behavior is declared in config/setup.config.ts using the usePersist(), useMemory(), and useLocal() methods on each subsystem: 
import { serve } from '@backtest-kit/mcp';

import {
  Markdown,
  StorageLive,
  StorageBacktest,
  NotificationLive,
  NotificationBacktest,
  RecentLive,
  RecentBacktest,
  Dump,
  MemoryLive,
  MemoryBacktest,
  StateLive,
  StateBacktest,
  SessionLive,
  SessionBacktest,
  Log,
} from "backtest-kit";

{
  Dump.useMarkdown();
}

{
  SessionLive.usePersist();
  SessionBacktest.useLocal();
}

{
  StorageLive.usePersist();
  StorageBacktest.useMemory();
}

{
  RecentLive.usePersist();
  RecentBacktest.useMemory();
}

{
  NotificationLive.usePersist();
  NotificationBacktest.useMemory();
}

{
  RecentLive.usePersist();
  RecentBacktest.useMemory();
}

{
  MemoryLive.usePersist();
  MemoryBacktest.useLocal();
}

{
  StateLive.usePersist();
  StateBacktest.useLocal();
}

{
  Markdown.useDummy();
  Log.useJsonl();
}

serve();
usePersist() writes state to dump/data/ and reloads it on the next startup. useMemory() keeps state in the process heap — it is gone when the process exits. useLocal() writes to a local temporary location that is not expected to survive across deployments.

​
What Persists in Live Mode

When running with --live (or --paper with usePersist() variants), the following subsystems write their state to dump/data/:
SubsystemWhat it holds
SignalsActive signals and their current lifecycle stage
StoragePer-symbol key-value store used by strategy callbacks
NotificationsQueued and delivered notification history
RecentRecent price and candle data cache
MemoryAgent memory written via MCP tool calls
StateEngine-level state including open positions and OCO bracket references
SessionsActive command sessions and their history
The practical result: after a restart, the open position is still there, the OCO bracket orders on Binance are still there and still being watched, and the agent’s command history is still there. The engine picks up exactly where it left off.

​
The dump/ Directory

All persistent and audit data lives under dump/ inside the strategy’s working folder (content/manual.strategy/dump/): 
dump/
├── data/          # Live engine state (survives restarts)
│   ├── signals/
│   ├── storage/
│   ├── notifications/
│   ├── recent/
│   ├── memory/
│   ├── state/
│   └── sessions/
├── mcp/           # Audit trail — one markdown file per get_status call
│   └── YYYY-MM-DDTHH-mm.md
├── images/        # Chart screenshots referenced by the audit markdown files
│   └── <id>.png
└── report/        # JSONL event streams
    ├── live.jsonl
    ├── performance.jsonl
    ├── max_drawdown.jsonl
    └── highest_profit.jsonl
dump/data/ is the live engine state. Files here are read at startup and written on every state change. This is the directory you need to back up if you want cross-host recovery. dump/mcp/ is the audit trail. Every get_status response — the full portfolio snapshot plus the last 15 Telegram posts — is dumped as a markdown file stamped with the minute it was generated. The web dashboard on :60050 includes a viewer for these files. dump/images/ holds chart screenshots extracted from Telegram posts. The audit markdown files reference them with relative paths so they render inline in the dashboard and in any markdown viewer. dump/report/ holds JSONL event streams that record the engine’s full trading history:
FileContents
live.jsonlAll engine events in chronological order
performance.jsonlPer-position PnL records
max_drawdown.jsonlMaximum drawdown snapshots
highest_profit.jsonlPeak unrealized and realized profit snapshots

​
Optional: Redis and MongoDB Backends

By default all usePersist() subsystems write to the local filesystem under dump/data/. The @backtest-kit/mongo package provides drop-in Redis and MongoDB backends for teams that need centralized state or higher durability guarantees. To enable them, set the connection variables in your environment and wire in the package according to its documentation: 
CC_REDIS_HOST=127.0.0.1
CC_MONGO_CONNECTION_STRING=mongodb://localhost:27017/backtest-kit?wtimeoutMS=15000
When neither variable is overridden, the engine continues to use the local filesystem — no external dependencies are required for a single-host deployment.

​
Restart Safety

The process is designed to be stopped and restarted without manual intervention:
1

Process stops

Whether by a clean shutdown, a crash, or a systemd restart, the process exits. All usePersist() subsystems have already written their latest state to dump/data/.
2

Process restarts

On the next startup each subsystem calls usePersist() and reloads from dump/data/. The engine reconstructs the full signal and position state.
3

Engine resumes

The open position is live again, the OCO brackets on Binance are re-associated, and the agent’s session history is available in the next get_status call. No manual reconciliation is needed for a normal restart.
The audit trail in dump/mcp/ is also fully preserved — every markdown file and every referenced image from before the restart is still there.
If you are running the trading process inside a Docker container, mount dump/ as a persistent volume so that live state, the audit trail, and the JSONL reports survive container recreation. Without a volume mount, everything under dump/ is lost when the container is replaced — including any open position state that the engine would otherwise recover from.
volumes:
  - ./dump:/app/content/manual.strategy/dump

Build docs developers (and LLMs) love

Get started for freeTalk to us