Skip to main content

Documentation Index

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

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

When the trading process restarts in live mode, open positions, their OCO brackets, the agent’s command history, and every subsystem’s accumulated state are all recovered from disk before the engine reconnects to Binance. Nothing is lost. In paper and backtest mode the same subsystems use in-memory backends — state is ephemeral and is discarded on exit. The difference is entirely in how each backend is wired in config/setup.config.ts.

​
What Survives a Restart

Live Mode

All six subsystems are persisted to dump/data/ under the strategy folder. On startup the engine reads signals (open positions), storage state, notification history, recent history, memory, and session data — then reconciles with Binance before resuming.

Paper / Backtest Mode

Storage, notifications, and recent history use in-memory backends and are lost on restart. Session and memory use local (filesystem) backends. No Binance reconciliation occurs because no real orders exist.

​
Persistence Wiring

The full config/setup.config.ts that drives all persistence decisions: 
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();
RecentLive.usePersist() / RecentBacktest.useMemory() appears twice in the actual source file — once before the Notifications block and once after it. This is a verbatim reproduction of config/setup.config.ts; the duplicate block has no additional effect at runtime.

​
Backend Key

MethodWhat it means
.usePersist()File-backed storage under dump/data/ — survives process restarts
.useLocal()Filesystem-backed but local to the run; used by backtest subsystems that need durability within a session but not cross-restart recovery
.useMemory()Pure in-memory — fast, zero I/O, lost on restart

​
Markdown and Log

Markdown.useDummy();   // markdown rendering disabled in the trading process
Log.useJsonl();        // all engine events stream to JSONL files
Markdown.useDummy() disables the engine’s internal markdown renderer — the trading process does not write live markdown reports. The StatusMarkdownService in @pro/agent handles the separate MCP audit trail independently. Log.useJsonl() routes every engine event to append-only JSONL files under dump/report/. These files grow continuously and are never truncated by the engine.

​
JSONL Event Streams

All event log files live in content/manual.strategy/dump/report/. Each line is a self-contained JSON object stamped with the event’s metadata.

live.jsonl

Every trade lifecycle event: position open, close, take-profit hit, stop-loss hit. The primary record of what the engine executed.

performance.jsonl

Per-trade PnL records written when a position closes. Each entry contains entry price, exit price, realized profit/loss, and the position direction.

max_drawdown.jsonl

Drawdown tracking records. Appended whenever the portfolio’s drawdown reaches a new low, giving a time-series of worst-case exposure.

highest_profit.jsonl

Peak profit records. Appended whenever cumulative profit reaches a new high watermark — the complement of max_drawdown.jsonl.

​
MCP Audit Trail

Every get_status response — the full text and images that Claude received — is dumped to disk before it leaves the trading process:
  • dump/mcp/<minute-stamp>.md — the complete text payload rendered as markdown
  • dump/images/<id>.png — chart screenshots referenced relatively from the markdown file
These files are written by StatusMarkdownService in @pro/agent, not by the engine’s Log subsystem. The web UI served on :60050 includes a dump viewer that renders these files. See the audit trail page for full details.

​
Restart Behaviour

1

Engine reads persisted signals

On startup, the engine loads all open positions and pending signals from dump/data/. These were written by StorageLive.usePersist() and StateLive.usePersist() in the previous run.
2

Binance reconnection and reconciliation

The live module reconnects to Binance via ccxt and checks for existing open orders using clientOrderId = signalId. If an OCO bracket is already on the book, the engine confirms it without placing a duplicate.
3

Session restored

SessionLive.usePersist() restores the GramJS Telegram session from dump/data/, so the scraper reconnects to the channel without requiring a new QR scan.
4

Engine resumes

The MCP HTTP bridge starts on 127.0.0.1:60051, Live.background() loops resume for all whitelisted symbols, and the system is ready to accept get_status, open_position, and close_position calls.
dump/data/ persistence is what makes it safe to restart the trading process while positions are open. The engine will reconcile with the exchange on startup — existing OCO brackets are detected and re-adopted rather than duplicated, and the position’s full history (including the agent’s original note) is restored from persisted state.

​
Optional Redis and MongoDB Backends

For production deployments, the file-backed .usePersist() backends can be replaced with database-backed storage from @backtest-kit/mongo:
Environment VariablePurpose
CC_REDIS_HOSTEnables the Redis-backed persistence backend for high-frequency state (signals, recent history)
CC_MONGO_CONNECTION_STRINGEnables the MongoDB-backed persistence backend via @backtest-kit/mongo for storage, notifications, and memory
When these variables are set and the @backtest-kit/mongo package is configured, the file-backed dump/data/ writes are replaced with database writes. The engine’s API surface is identical — only the storage driver changes.
For production deployments, consider using the MongoDB backend for more robust persistence and easier querying of historical trade data. JSONL files under dump/report/ are still written regardless of which storage backend is active — they are controlled by Log.useJsonl(), not by the storage subsystem.

​
Version Control Exclusions

The .gitignore already excludes both runtime artifacts that must never be committed: 
dump/
session.txt
dump/ contains live trading state, the full MCP audit trail (which may include proprietary channel content and position details), and JSONL logs. session.txt grants full access to the Telegram account that authorized the scraper — treat it like a private key and keep it off shared machines and out of version control.
If session.txt is exposed, anyone with it can read and interact with your Telegram account. Rotate it immediately by revoking the session from Telegram Settings → Devices and running npm start -- --session again to generate a fresh one.

Build docs developers (and LLMs) love

Get started for freeTalk to us