tradememory-protocol 0.5.0

MCP memory system for AI trading agents. Store, recall, and learn from past trades.

TradeMemory Protocol

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

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

The Problem

Your AI trading agent has no memory. Every session starts from zero — same mistakes, same blown setups, no learning.

Session 1: Agent loses $200 on Asian session breakouts
Session 2: Agent loses $180 on Asian session breakouts  ← no memory of Session 1
Session 3: Agent loses $210 on Asian session breakouts  ← still no memory

The Fix

pip install tradememory-protocol

Session 1: Agent loses $200 → remember_trade stores context + outcome
Session 2: Agent calls recall_memories → "Asian breakouts: 0% win rate, -$590"
           Agent skips the trade.  ← memory saved $180

graph LR
    T["Execute Trade"] --> S["store<br/>remember_trade()"]
    S --> R["recall<br/>recall_memories()"]
    R --> L["learn<br/>adjust strategy"]
    L --> T
    style S fill:#22c55e,color:#fff
    style R fill:#3b82f6,color:#fff
    style L fill:#f59e0b,color:#fff

---

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
• Behavioral bias detection — Flags overtrading, revenge trading, and disposition effect from your trade history
• 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 — Rule-based tuning from discovered patterns: disable losing strategies, prefer winners, adjust lot sizes, restrict directions

10 MCP tools · 737 tests · MIT license · All v0.3.x features work unchanged

---

See It Work (30 seconds)

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

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

Output — trade recording → pattern discovery → strategy adjustment (click to expand)

── Step 1: Recording trades to memory ──

  # │ 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: 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

── Step 3: 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.

---

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

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

Config file location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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 .

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)

Component	Formula	What It Does
Q — Outcome Quality	sigmoid(k · pnl_r / σ_r)	Maps R-multiple outcomes to (0,1) via sigmoid. A +3R winner scores 0.98; a -3R loser scores 0.02 but never zero — losing memories are recalled as warnings.
Sim — Context Similarity	Gaussian kernel over ContextVector	Measures how similar the current market context (symbol, regime, ATR, session) is to when the memory was formed. Irrelevant memories are suppressed.
Rec — Recency	(1 + age_days/τ)^(-d)	ACT-R power-law decay. A 30-day-old memory retains 70.7% strength; a 1-year-old memory retains 27.5%. Much gentler than exponential — old regime-relevant memories remain retrievable.
Conf — Confidence	0.5 + 0.5 · confidence	Memories formed during high-confidence states score higher. Floor of 0.5 prevents early memories from being ignored.
Aff — Affective Modulation	1.0 + α · relevance(m, state)	Current drawdown/streak state modulates recall. During drawdowns, cautionary memories surface; during winning streaks, overconfidence checks activate.

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)

Tool	Description
store_trade_memory	Store a trade decision with full context into memory
recall_similar_trades	Find past trades with similar market context (auto-upgrades to OWM when episodic data exists)
get_strategy_performance	Aggregate performance stats per strategy
get_trade_reflection	Deep-dive into a specific trade's reasoning and lessons

OWM Tools (6 — new in v0.4.0)

Tool	Description
remember_trade	Store a trade into all five memory layers simultaneously (episodic + Bayesian semantic update + procedural running averages + affective EWMA)
recall_memories	Outcome-weighted recall with full score breakdown per component
get_behavioral_analysis	Procedural memory analysis: hold times, disposition ratio, lot sizing variance, Kelly comparison
get_agent_state	Current affective state: confidence, risk appetite, drawdown %, win/loss streaks, recommended action
create_trading_plan	Store a conditional plan in prospective memory (e.g., "if regime changes to ranging, skip breakout trades")
check_active_plans	Match active plans against current market context, expire stale plans

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)

• OWM cognitive memory architecture (5 memory types, outcome-weighted recall, Kelly sizing)
• 10 MCP tools + 20+ REST API endpoints
• MT5 connector (scripts/mt5_sync.py) — auto-sync trades from MetaTrader 5
• Binance connector (scripts/binance_sync.py) — poll and sync spot trades
• Daily/weekly/monthly reflection engine (rule-based + optional LLM)
• State persistence (cross-session memory)
• Streamlit dashboard
• 737 unit tests passing
• Interactive demo (demo.py)

Planned

• Multi-strategy portfolio support
• Agent-to-agent learning
• More exchange connectors (Bybit, Alpaca, Interactive Brokers)

---

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, Binance REST API
• Dashboard: Streamlit + Plotly
• Testing: pytest (737 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 connectors: MetaTrader 5 (scripts/mt5_sync.py) and Binance spot (scripts/binance_sync.py). For other platforms (Alpaca, Interactive Brokers), send trades through the MCP remember_trade tool or REST API.

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.

---

Research

We used TradeMemory's episodic memory system to run controlled A/B experiments on LLM trading agents. Key finding: naively adding memory made the agent worse (Profit Factor 2.42 → 0.94) due to positive recall bias — the same cognitive bias documented in human investors.

I Gave My Trading Agent Memory. It Made Everything Worse. Here's How I Fixed It.

The full experiment was conducted using the Trade Dreaming replay engine built on top of this protocol.

---

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