mnemox-ai/tradememory-protocol

Decision audit trail + persistent memory for AI trading agents. Outcome-weighted recall, tamper-evident SHA-256 chain with RFC 3161 anchoring, 20 MCP tools.

TradeMemory Protocol – A local‑first memory & safety layer for AI trading agents

What it is – An open‑source Python package that records every trade an AI‑driven trader makes, analyses the trader’s own historical performance, and can intervene (refuse or reorder) before the next order reaches a broker’s MCP (Market‑Connect‑Protocol) server. It works with popular broker APIs (Alpaca, Hyperliquid, MT5, Binance) and can run as a thin proxy that enforces user‑defined risk policies.

Key concepts

  • Recall – recall_memories(order="losses_first") returns past losing trades weighted by outcome, similarity, recency, confidence, and “emotional state” (the OWM five‑factor model).
  • Record – remember_trade writes a trade into five memory layers (episodic, semantic, procedural, affective, raw record).
  • Reflect – Periodic statistical summaries (median hold time, loss concentration, R‑multiple) help the agent detect drift.
  • Audit – Every decision is SHA‑256 hashed, chained, and daily Merkle‑rooted, providing a tamper‑evident log that can be exported.

How you use it

  1. Sync your history – tradememory sync hyperliquid --address 0x… or tradememory sync alpaca --env-file ~/.secrets/alpaca.env pulls fills into a local SQLite DB.
  2. Add the memory server to your agent – In Claude Desktop (or any MCP‑compatible agent) configure the tradememory MCP server.
  3. Pre‑flight – Before the agent proposes an order, call recall_memories to surface similar past losses; the proxy can automatically refuse orders that violate limits.
  4. Optional brake – Install the proxy extra (pip install "tradememory-protocol[proxy]") to run a local proxy that forwards only policy‑approved orders to the broker while logging every decision.

Main features (MCP tools)

Category Tools Purpose
Memory remember_trade, recall_memories Record trades, retrieve weighted loss‑first lists
State get_agent_state, get_behavioral_analysis Current confidence, drawdown, streak metrics
Planning create_trading_plan, check_active_plans Build conditional trading plans
Risk check_trade_legitimacy Five‑factor pre‑trade gate (full / reduced / skip)
Audit export_audit_trail, verify_audit_hash, verify_audit_chain Tamper‑evident logging, Merkle roots
Evolution evolution_* tools Research‑grade strategy generation & back‑testing

Typical use‑cases

  • US equity trader – A single retail user runs the memory server locally, gets a “losses‑first” checklist before each Alpaca order, and enforces daily‑loss caps.
  • Forex EA system – An automated MT5 expert advisor syncs trades, the memory layer automatically rejects orders that repeat recent losing patterns.
  • Compliance audit trail – Institutional users export the SHA‑256‑chained log to satisfy MiFID II or future EU AI‑Act requirements.

Limitations (see LIMITATIONS.md)

  • The OWM scoring is research‑grade; statistical significance is still being gathered (current validation runs on < 20 trades).
  • Only a subset of order types (bracket, stop‑limit, trailing) are currently refused rather than evaluated.
  • No built‑in digital signatures for audit records; tamper‑evidence relies on hash chaining.
  • Evolution engine is experimental and not intended for production deployment.

Installation & quick start

pip install tradememory-protocol          # core memory server
tradememory sync hyperliquid --address 0xYourAddress
# optional brake proxy (Python 3.12+)
pip install "tradememory-protocol[proxy]"
tradememory proxy init --account-id <id> --symbols AAPL,MSFT

Run tradememory as an MCP server and point your AI agent’s MCP config to it.

Security & privacy

  • The memory server never holds broker keys; keys are only passed to the broker process started by the proxy.
  • All outbound calls are read‑only (except optional Discord webhook for MT5 sync).
  • Audit roots are timestamped via RFC 3161 by default; can be disabled with TRADEMEMORY_TSA=off.

Research status

  • OWM five‑factor scoring implemented and CI‑tested.
  • Audit trail fully functional.
  • Evolution and hybrid vector recall are in research mode.
  • Ongoing empirical validation (target ≥ 100 trades for statistical confidence).

Docs & help

  • Getting Started, Use Cases, API reference, OWM Framework, Architecture, and a Chinese README are all in the docs/ folder.
  • Issues: open a brake‑integration issue or book a 30‑minute free setup call.

License – MIT for the core package; the optional proxy extra pulls in mnemox‑control (AGPL‑3.0‑only, commercial license available).

Not financial advice – the tool only surfaces historical loss patterns; trading decisions remain the user’s responsibility.

Related

  • Project
    LeoYeAI/talewell

    Talewell is a git‑backed, Markdown‑based long‑term memory system for AI agents. It stores each memory record as a version‑controlled file, provides deterministic offline recall, enforces provenance, and exposes a portable AMP protocol so any agent platform (OpenClaw, Claude Code, Codex, etc.) can use the same memory repo via plugins or a simple file convention.

  • Project
    akitaonrails/ai-memory

    ai‑memory is a Rust‑based, self‑contained service that gives AI coding assistants a shared, long‑term, markdown‑backed memory. It automatically captures prompts and tool calls via hooks, stores them as git‑versioned markdown pages, and lets any supported agent (Claude Code, Codex, Cursor, Gemini CLI, etc.) retrieve a concise hand‑off on a different machine or after a teammate’s session. By default it works offline with zero LLM calls; optional LLM‑driven “dream” consolidation, vector search, and aging policies are configurable. The project provides native packages, Docker images, and a macOS menu‑bar app, and includes built‑in multi‑user auth, audit logs, and per‑project sharing.

  • Project
    atomicstrata/atomicmemory

    AtomicMemory is an open‑source, inspection‑ready memory service for LLM agents. It offers correction‑aware updates, model‑agnostic embeddings, and both managed‑cloud and self‑hosted Docker deployments. The project ships a Rust Core server, a TypeScript SDK, a CLI (`am`), adapters for LangChain, LangGraph, Vercel AI, etc., and plugins for various agent hosts. Quick start is a one‑line installer that creates a cloud profile; a `--local` flag runs the Core container on your machine. Memory can be ingested and queried via the CLI or programmatically via the SDK, and agents can be linked through an MCP server. Licensed under Apache 2.0.

  • Project
    Lyellr88/marm-memory

    A persistent local memory server for AI agents using the Model Context Protocol (MCP), providing shared long-term memory and code-graph awareness across different AI clients.

  • Project
    Trampoline-AI/predict-rlm

    predict-rlm is a Python library that gives large language models a sandboxed, stateful runtime. Models write and execute Python code, keep mutable state, call focused sub‑models, and use tools/skills (e.g., PDF handling, spreadsheets). The framework records a full trace for observability and can feed those traces to optimisation tools like GEPA. It’s aimed at complex, multi‑step workflows such as document analysis, audit, or spreadsheet automation, and supports optional Docker sandboxing and rich callbacks.