TradeMemory Protocol

A Mnemox Project — MCP server that gives AI trading agents persistent, outcome-weighted memory.

AI trading agents are stateless by default. Every session starts from zero — no memory of what worked, what failed, or why. TradeMemory is an MCP server that stores trade decisions into a five-type cognitive memory system, recalls them using outcome-weighted scoring (grounded in ACT-R power-law decay, Kelly criterion, and Bayesian updating), and learns across sessions through a store → recall → learn loop.

Works with: Claude Desktop · Claude Code · Cursor · Windsurf · any MCP client

What It Does

• Trade journaling — Records every decision with reasoning, confidence, market context, and outcome
• Outcome-weighted recall (OWM) — Five memory types (episodic, semantic, procedural, affective, prospective) scored by Q × Sim × Rec × Conf × Aff to surface the right memory at the right time
• Reflection engine — Analyzes trade history to find session/strategy/confidence patterns (rule-based, with optional LLM)
• Kelly-from-memory — Context-weighted position sizing derived from recalled trade outcomes, not global statistics
• State persistence — Agent loads its confidence level, drawdown state, behavioral patterns, and active plans when starting a new session
• Strategy adjustments (L3) — Rule-based tuning from L2 patterns: disable losing strategies, prefer winners, adjust lot sizes, restrict directions

All v0.3.x features work unchanged. OWM is an additive upgrade.

What it does NOT do yet: multi-agent learning, cryptocurrency exchange support. These are planned for future phases.

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tradememory": {
      "command": "uvx",
      "args": ["tradememory-protocol"]
    }
  }
}

Restart Claude Desktop. You'll see TradeMemory tools in the 🔨 menu. Try asking:

• "Store my latest XAUUSD trade: long 0.05 lots, entry 2847, exit 2855, profit $40"
• "Show my trading performance this week"
• "Run a reflection on my last 20 trades"

Claude Code

claude mcp add tradememory -- uvx tradememory-protocol

Then ask Claude:

• "What patterns do you see in my recent losing trades?"
• "Compare my London session vs Asian session win rates"

Cursor / Other MCP Clients

Add to .cursor/mcp.json (or your client's MCP config):

{
  "mcpServers": {
    "tradememory": {
      "command": "uvx",
      "args": ["tradememory-protocol"]
    }
  }
}

From Source

git clone https://github.com/mnemox-ai/tradememory-protocol.git
cd tradememory-protocol
pip install -e .

Run the Demo

No API key needed. Runs 30 simulated XAUUSD trades through the full pipeline:

python scripts/demo.py

Output shows: trade recording (L1) → pattern discovery (L2) → strategy adjustments (L3) → agent reloading state with memory.

┌───────────────────────────────────────────────┐
│                                               │
│    TradeMemory Protocol                       │
│    Persistent memory for AI trading agents    │
│                                               │
└───────────────────────────────────────────────┘

── Step 1: L1 — Recording trades to TradeJournal ──

  # │ Result │ Session │ Strategy    │ P&L      │ R
  1 │ LOSS   │ Asia    │ Pullback    │ $-15.00  │ -1.0
  2 │ WIN    │ London  │ VolBreakout │ $+42.00  │ +2.1
  3 │ WIN    │ London  │ VolBreakout │ $+28.50  │ +1.5
  ...
  30 │ WIN   │ London  │ Pullback    │ $+28.00  │ +1.4

  Total: 30 trades | Winners: 19 | Win rate: 63% | Net P&L: $+499.50

── Step 2: L2 — Reflection Engine discovers patterns ──

  Pattern             │ Win Rate │ Record    │ Net P&L   │ Assessment
  London session      │     100% │ 14W / 0L  │ $+608.50  │ HIGH EDGE
  Asian session       │      10% │  1W / 9L  │ $-156.00  │ WEAK
  VolBreakout strategy│      73% │ 11W / 4L  │ $+429.50  │ HIGH EDGE

  Confidence correlation:
    High (>0.75): 100% win rate
    Low  (<0.55):   0% win rate

── Step 3: L3 — Strategy adjustments generated ──

  Parameter                │ Old  │ New  │ Reason
  london_max_lot           │ 0.05 │ 0.08 │ London WR 100% — earned more room
  asian_max_lot            │ 0.05 │ 0.025│ Asian WR 10% — reduce exposure
  min_confidence_threshold │ 0.40 │ 0.55 │ Trades below 0.55 have 0% WR

All demo data is simulated. See Before/After Comparison for detailed breakdown.

Start the Server

python -m src.tradememory.server
# Runs on http://localhost:8000

Docker

docker compose up -d

# Or manually:
docker build -t tradememory .
docker run -p 8000:8000 -e ANTHROPIC_API_KEY=your-key tradememory

As OpenClaw Skill

Give your OpenClaw agent trading memory:

Install this skill: https://github.com/mnemox-ai/tradememory-protocol

Then tell your agent via WhatsApp:

• "Record my XAUUSD trade: long 0.05 lots, +$40 profit"
• "Show my trading performance this week"
• "Run a reflection on my last 20 trades"

See .skills/tradememory/SKILL.md for the full skill reference.

Tutorials

• English Tutorial — Step-by-step from install to using memory in trades
• 中文教學 — 完整教學指南

Architecture

graph TD
    Agent["AI Trading Agent<br/>(Claude / GPT / Custom)"] -->|MCP Protocol| Server

    subgraph Server["TradeMemory Protocol Server"]
        direction TB

        subgraph OWM["OWM Cognitive Memory"]
            EP["Episodic<br/>Trade events + context"]
            SEM["Semantic<br/>Bayesian beliefs"]
            PROC["Procedural<br/>Behavioral patterns"]
            AFF["Affective<br/>Confidence + drawdown"]
            PROS["Prospective<br/>Conditional plans"]
        end

        subgraph Legacy["Legacy Pipeline (v0.3.x)"]
            L1["L1 Hot — RAM<br/>Active trades"]
            L2["L2 Warm — JSON<br/>Discovered patterns"]
            L3["L3 Cold — SQLite<br/>Strategy adjustments"]
        end

        OWM ---|"recall_memories()"| RECALL["Outcome-Weighted<br/>Recall Engine"]
        Legacy ---|"recall_similar_trades()"| RECALL
    end

    MT5["MT5 / Binance / Alpaca"] -->|"mt5_sync.py"| Server

Legacy compatibility: All v0.3.x tools and data remain functional. recall_similar_trades auto-detects whether OWM episodic data exists — if yes, it uses outcome-weighted scoring; if no, it falls back to keyword matching. Zero migration required.

Why OWM?

Outcome-Weighted Memory is a novel application of established cognitive science to AI trading agents — not an invention of new theory. It combines Tulving's episodic memory taxonomy (1972), Anderson's ACT-R activation framework (2007), Kelly's optimal bet sizing (1956), and Damasio's somatic marker hypothesis (1994) into a single recall function purpose-built for sequential financial decisions.

The core recall formula scores each candidate memory m given current context C:

Score(m, C) = Q(m) × Sim(m, C) × Rec(m) × Conf(m) × Aff(m)

Academic foundations:

• Anderson, J. R. (2007). How Can the Human Mind Occur in the Physical Universe? — ACT-R activation and power-law decay
• Kelly, J. L. (1956). A New Interpretation of Information Rate — Optimal bet sizing from outcome history
• Tulving, E. (1972). Episodic and semantic memory — Five-type memory taxonomy
• Damasio, A. (1994). Descartes' Error — Affective markers in decision-making

Full specification: docs/OWM_FRAMEWORK.md (1,875 lines, includes mathematical proofs, boundary analysis, and financial validation against Kelly/Bayesian/Prospect Theory)

MCP Tools (v0.4.0)

Core Memory Tools (4 — backward compatible)

OWM Tools (6 — new in v0.4.0)

REST API

• POST /trade/record_decision — Log entry decision with full context
• POST /trade/record_outcome — Log trade result (P&L, exit reason)
• POST /trade/query_history — Search past trades by strategy/date/result
• POST /reflect/run_daily — Trigger daily summary (rule-based, or LLM with API key)
• POST /reflect/run_weekly — Weekly deep reflection
• POST /reflect/run_monthly — Monthly reflection
• POST /risk/get_constraints — Dynamic risk parameters
• POST /risk/check_trade — Validate trade against constraints
• POST /mt5/sync — Sync trades from MetaTrader 5
• POST /reflect/generate_adjustments — Generate L3 strategy adjustments from L2 patterns
• GET /adjustments/query — Query strategy adjustments by status/type
• POST /adjustments/update_status — Update adjustment lifecycle (proposed→approved→applied)
• 7 new OWM endpoints under /owm/ prefix — episodic/semantic/procedural/affective/prospective CRUD + recall + Kelly sizing

Full API reference: docs/API.md

Project Status

What Works (v0.4.0)

• Core MCP server + TradeJournal
• OWM cognitive memory architecture (5 memory types, outcome-weighted recall, Kelly sizing)
• SQLite storage + Pydantic data models
• MT5 connector (auto-sync trades from MetaTrader 5)
• Daily reflection engine (rule-based + optional LLM)
• State persistence (cross-session memory)
• Streamlit dashboard
• 399 unit tests passing
• Interactive demo (demo.py)
• Weekly/monthly reflection cycles
• Adaptive risk algorithms

Planned (Phase 2 — Q2 2026)

• Multi-strategy portfolio support
• Agent-to-agent learning
• Public beta

Future (Phase 3 — Q3 2026)

• Cryptocurrency exchange support (Binance/Bybit)
• Stock market support (Alpaca/Interactive Brokers)
• SaaS hosted version

Technical Stack

• MCP Server: FastMCP 3.x (stdio transport)
• REST API: FastAPI + uvicorn
• Storage: SQLite (trade records + OWM tables), JSON (L2)
• Memory: OWM 5-type cognitive memory with outcome-weighted recall
• Reflection: Rule-based pattern analysis, optional Claude API for deeper insights
• Broker Integration: MT5 Python API (Phase 1)
• Dashboard: Streamlit + Plotly
• Testing: pytest (399 tests)

Documentation

• OWM Framework Specification — Full theoretical foundation (1,875 lines)
• Tutorial (English)
• 教學 (中文)
• Before/After Comparison — Simulated impact data
• Quick Start Guide
• Architecture Overview
• API Reference
• Data Schema
• Reflection Report Format
• MT5 Setup Guide
• Daily Reflection Setup

Connect to MT5 (Optional)

Sync live trades from MetaTrader 5 into TradeMemory automatically.

Prerequisites

1. MetaTrader 5 running with your broker account
2. Python 3.12 (system Python 3.13+ is not supported by the MT5 package)
3. Enable API access in MT5: Tools → Options → Expert Advisors → Allow Algo Trading
   • Also set Api=1 in common.ini under [Experts] section

Quick Start

# 1. Install dependencies
pip install MetaTrader5 python-dotenv requests fastapi uvicorn pydantic

# 2. Configure .env
cp .env.example .env
# Edit .env with your MT5 credentials

# 3. Start both services
scripts/start_services.bat

Auto-Start on Login (Windows)

# Run as Administrator:
scripts\install_autostart.bat

This registers a Windows Task Scheduler task that starts the tradememory server and scripts/mt5_sync.py 30 seconds after login.

scripts/
├── start_services.bat       # Start tradememory server + mt5_sync.py
├── stop_services.bat        # Stop all services
├── install_autostart.bat    # Register auto-start task (run as admin)
└── TradeMemory_AutoStart.xml # Task Scheduler config

Manual Start

# Terminal 1: Start API server
python -c "import sys; sys.path.insert(0, 'src'); from tradememory.server import main; main()"
# Runs on http://localhost:8000

# Terminal 2: Start MT5 sync (scans every 60s)
python scripts/mt5_sync.py

Daily Reflection

# Windows: Import start_daily_reflection.bat into Task Scheduler (23:55 daily)
# Linux/Mac: 55 23 * * * /path/to/daily_reflection.sh

See MT5 Setup Guide for detailed configuration.

FAQ

Does TradeMemory connect directly to my broker?
No. TradeMemory is a memory layer, not a trading platform connector. It accepts standardized trade data from any source. For MT5 users, scripts/mt5_sync.py automatically polls and syncs closed trades every 60 seconds.

What trading platforms are supported?
Any platform that can output trade data. Built-in support exists for MetaTrader 5 via scripts/mt5_sync.py. For other platforms (Binance, Alpaca, Interactive Brokers), you send trades through the MCP store_trade_memory tool or REST API using a standardized format.

What data does it store?
Five memory types: Episodic (individual trade events with full context), Semantic (Bayesian beliefs about strategy effectiveness, updated with each trade), Procedural (behavioral patterns — hold times, disposition ratio, lot sizing variance), Affective (agent confidence, drawdown state, win/loss streaks), and Prospective (conditional trading plans). Plus the legacy L1/L2/L3 layers for backward compatibility.

Is it free to use?
Yes. MIT license, fully open source. All 10 MCP tools work without any API keys. The optional LLM reflection feature requires a Claude API key for deeper insights, but the core memory system — including OWM recall and Kelly sizing — runs entirely locally.

Can I use it without MetaTrader 5?
Yes. MT5 is just one data source. You can manually store trades via the MCP store_trade_memory or remember_trade tools, send them through the REST API, or write a custom sync script for your platform.

Contributing

See CONTRIBUTING.md for guidelines.

• Star the repo to follow progress
• Report bugs via GitHub Issues
• Submit PRs for bug fixes or new features
• Join the discussion in Discussions

License

MIT — see LICENSE.

Disclaimer

This software is for educational and research purposes only. It does not constitute financial advice. Trading involves substantial risk of loss. You are solely responsible for your trading decisions. The authors accept no liability for losses incurred through use of this software.

Contact

• GitHub Issues
• GitHub Discussions

Built by Mnemox