TradeMemory Protocol
Persistent trading-agent memory with risk checks and a tamper-evident decision trail.
- Source repo
- mnemox-ai/tradememory-protocol
- Stars
- ★ 1.4k
- Last updated
- 9d ago
- License
- MIT
- Primary language
- Python
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code · Claude.ai
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A US-equity trader runs recall and a pre-flight checklist before each AAPL or TSLA position to surface outcomes from similar prior setups.
- Not a fit if
- Teams wanting a vendor-hosted service instead of self-hosting
- Users expecting active feature development; the project is in maintenance mode
- Compliance teams needing external anchoring or zkML proof, absent in v0.5.2
- Source review
- 65/100 · Some gaps 1 safety controls not found
What does this agent do, and when should you use it?
TradeMemory Protocol is a self-hosted memory and audit layer for agents trading stocks, forex, crypto, or futures; it does not execute orders, access wallets, or move funds. Its 20 MCP tools and 35-plus REST endpoints record both trades and decisions not to trade across episodic, semantic, procedural, affective, and trade-record memory layers. Before a position is opened, an agent can recall prior cases using outcome quality, contextual similarity, recency, confidence, and emotional state, then inspect drawdown, streaks, behavior, and active plans. The audit subsystem assigns SHA-256 content hashes, maintains a forward-linked ledger and daily Merkle roots, and supports record, chain-slice, full-chain, and export workflows. It can be installed from PyPI, source, or Docker and has documented Claude Desktop and Claude Code setup, but the project entered maintenance mode in August 2026 with no new features or hosted service planned.
Before a trade, recall_memories retrieves outcome-weighted historical cases, while get_agent_state and get_behavioral_analysis return confidence, drawdown, streak, and behavioral information. check_trade_legitimacy applies a five-factor pre-trade gate that can return full, reduced, or skip, and create_trading_plan plus check_active_plans manage conditional prospective plans. After a trade, remember_trade updates episodic, semantic, procedural, affective, and trade-record storage in one operation; get_strategy_performance, get_trade_reflection, validate_strategy, and compute_dqs expose performance, reflection, and statistical-validation workflows. The evolution group—evolution_fetch_market_data, evolution_discover_patterns, evolution_run_backtest, evolution_evolve_strategy, and evolution_get_log—fetches data, discovers patterns, backtests, evolves strategies, and reports its log, although this component remains research-stage. export_audit_trail, verify_audit_hash, verify_audit_chain, and get_daily_root produce audit exports and verify individual hashes, linked sequences, or daily Merkle roots. The service reads and stores decision context supplied by another agent; broker execution remains outside its boundary.
- A US-equity trader runs recall and a pre-flight checklist before each AAPL or TSLA position to surface outcomes from similar prior setups.
- A team operating a MetaTrader 5 forex EA synchronizes thousands of decisions and records why signals were blocked as well as which orders were executed.
- A multi-asset compliance team retains Trading Decision Records for actions and no-trade decisions, then exports a verifiable decision history for review.
- A strategy researcher uses reflections, DSR, MBL, pattern discovery, and backtesting to investigate strategy decay while treating the evolution engine as research-stage.
- A trading-agent developer adds durable memory, behavioral monitoring, and a risk gate to an existing execution stack through MCP or REST without granting this service order permissions.
How do you install or deploy this agent?
A working Python command environment is required, although the supplied material does not state a minimum Python version. No broker, exchange, wallet, or trading API credentials are required. Install from PyPI with:
pip install tradememory-protocolFor Claude Desktop, add this to claude_desktop_config.json:
{"mcpServers":{"tradememory":{"command":"uvx","args":["tradememory-protocol"]}}}
For Claude Code, run:
claude mcp add tradememory -- uvx tradememory-protocolTo install from source:
git clone https://github.com/mnemox-ai/tradememory-protocol.git
cd tradememory-protocol && pip install -e . && python -m tradememoryThe documented container startup command is:
docker compose up -dHow do you use this agent?
After configuring the MCP server, a first supported interaction in Claude is: “Record my AAPL long at $195 — earnings beat, institutional buying, high confidence.” This supplies context for remember_trade. Before the next decision, call recall_memories for comparable market conditions and combine it with get_agent_state, check_active_plans, and check_trade_legitimacy for state, plan, and risk checks. After closing or resolving a trade, call remember_trade again with its outcome, then use get_trade_reflection or get_behavioral_analysis during scheduled reviews. For integrity checks, verify_audit_hash(trade_id="MT5-7047640363") checks one record, verify_audit_chain(from_seq=1, to_seq=None) walks the complete chain, and get_daily_root(date="2026-05-14") checks a day's root. A bulk regulatory export is documented as GET /audit/export?strategy=VolBreakout&start=2026-03-01&format=jsonl.
What are this agent's strengths and limitations?
- One interface combines pre-trade recall, post-trade recording, behavioral analysis, risk gating, and audit operations across 20 MCP tools and a REST API.
- The audit model covers no-trade decisions as well as executed trades and supports integrity checks at individual-record, chain-range, and daily-root levels.
- Its local-first boundary excludes broker credentials, wallet access, order execution, and fund movement, limiting the privileges entrusted to the memory service.
- The documented deployment and integration paths include PyPI, source installation, Docker, MT5, Claude Desktop, and Claude Code.
- Recall considers outcome quality, context similarity, recency, confidence, and emotional state instead of relying solely on keywords or chronological retrieval.
- As of August 2026, the repository is in maintenance mode: bug and security reports are reviewed, but new features and a hosted service are not planned.
- Empirical validation is still limited; the supplied evidence reports 40 trades against a target of at least 100 for statistical significance.
- The evolution engine remains research-stage, with strategy generation working but statistical-gate pass rates still under optimization.
- Audit maturity has important limits: the material identifies TSA timestamping, external anchoring, and zkML proof of inference as absent from v0.5.2, so linked hashes should not be treated as a complete external proof system.
- Adopters must operate the service themselves, and the supplied documentation does not specify a minimum Python version, storage sizing guidance, or a disaster-recovery procedure.
How does this agent compare with similar options?
Compared with trading MCP servers centered on order placement, price retrieval, or chart access, TradeMemory is a companion memory and audit layer. It records decision context, recalls prior outcomes, and verifies record integrity, but it does not replace a broker adapter, execution engine, or fund-management system.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| TradeMemory Protocol This agent | 65 · Some gaps | MCP serverFree | ★ 1.4k | 9d ago | Python | Claude Code · Claude.ai |
| Vibe-Trading | 64 · Some gaps | CLIFree + model costs | ★ 36k | 1d ago | Python | OpenAI API · Claude API |
| QuantDinger AI Trading OS | 89 · Good | Self-hosted serviceFree + model costs | ★ 13k | today | Python | Codex · Claude Code · OpenAI API |
| Nocturne Memory: Long-Term Memory Server for MCP Agents | 56 · Major gaps | MCP serverFree | ★ 1.4k | 26d ago | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence says the core product records and recalls trading memory without executing trades or handling funds. It discloses a default RFC 3161 outbound request carrying only a 32-byte hash and an opt-out, while the test configuration forcibly prevents real TSA traffic. Risk checks implement rejection, lot caps, and scaling, supporting least privilege and controlled external effects. No explicit confirmation step is shown before record mutations or exports, and no deletion, undo, or recovery workflow is evidenced, so user confirmation is thin and rollback scores zero. Dependencies have minimum bounds but no lockfile or vulnerability scanning evidence. The scheduled workflow injects a Supabase service-role key through secrets; no leakage is shown, but it remains a privileged deployment surface. Attribution identifies Mnemox, contact addresses, and Sean, although publisher verification is absent and responsibility is not entirely unified.
CI covers Python 3.10–3.12 and runs both tests and a demo. The supplied risk tests cover insufficient data, thresholds, rejection, scaling, and persistence, while checking human-readable reasons. However, the README variously says TSA is enabled by default, external anchoring remains on the roadmap, and Phase 1.5 is not yet present; it also discusses v0.5.2 while package metadata is v0.5.4. These material inconsistencies limit self-consistency to 1. Tests demonstrate useful reason fields in part of the product, but there is no comprehensive evidence for errors from networking, database failures, or every MCP and REST operation.
Documentation distinctly addresses equity traders, forex EA systems, compliance teams, and separate trader/developer tracks. It describes multiple markets and integration paths through MCP, REST, Docker, SQLite/Postgres options, and a TSA environment toggle. Tool names and risk gates give reasonably precise invocation intent. Full marks are withheld outside audience coverage because source code evidence is limited to selected modules, claims of working with any market, broker, or AI platform are broad, and the evolution engine is explicitly still in a research phase.
The README has strong navigation, a concise quick start, categorized tools, and links to architecture, API, tutorials, and limitations. Installation through pip, uvx, source, Claude, Cursor, and Docker is clearly described. The full MIT text agrees with README and package metadata. Maintenance mode, non-advice scope, small empirical sample, and unfinished capabilities are disclosed. Deductions apply because no FAQ content is supplied, stability guarantees for the 20 MCP tools and 35+ endpoints are not visible, and the referenced changelog itself is absent. A maintenance email and update posture exist, but the responsibilities of Mnemox, Sean, and the paid-service contact are not precisely separated.
Categorized tools, sample JSON results, audit verification operations, risk-check explanations, and export functions indicate outputs usable by agents and reviewers. Combining persistent decision memory, outcome-weighted recall, behavioral risk controls, and tamper detection supplies clear marginal value beyond an execution-only trading agent. Self-hosting and MIT licensing reduce acquisition cost, but storage, TSA traffic, deployment dependencies, and unfinished external anchoring impose operational costs. Empirical validation is only n=40, so effectiveness and compliance benefits are not established strongly enough for a maximum cost-benefit score.
Several claims are traceable across README, package metadata, CI, test configuration, and focused tests, including Python support, offline tests, risk constraints, and anti-resonance thresholds. Nevertheless, the supplied evidence omits implementation modules, the full test inventory, LIMITATIONS.md, and CHANGELOG.md, so it cannot substantiate 1,400+ passing tests, all 20 tools, 35+ endpoints, production usage, or the full audit-chain implementation. Regulatory coverage, production adoption, and universal compatibility are presented too close to fact despite limited corroboration, and TSA maturity statements conflict.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- This is a low-confidence static review; no code, tests, installation path, or TSA request was executed.
- The README conflicts about RFC 3161 TSA maturity: it says TSA is on by default while also describing external anchoring as roadmap or not yet present. Verify the implementation and effective defaults before deployment.
- Do not treat a SHA-256 chain or regulatory mapping as compliance certification. External time anchoring, integrity boundaries, key management, and retention policy require independent review.
- The scheduled live executor uses a Supabase service-role key. Deployers should isolate it, rotate credentials, and verify the script's actual permissions; least-privileged database access is not demonstrated.
- Dependencies are not reproducibly locked and no dependency vulnerability scan is shown. Produce a lockfile and perform a security review before installation.
- The risk module returns an ACTIVE default when data is insufficient rather than stopping activity; operators should explicitly accept or change that safety policy.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.5.6 v0.5.6 — sync your own history, losses first
Release notes excerpt
TradeMemory now pulls in your own fills, shows where your history loses money, and puts those losing trades in front of your agent before the next order. ```bash pip install -U tradememory-protocol Hyperliquid: public fills, no key needed tradememory sync hyperliquid --address 0xYourAddress Alpaca: read-only calls with your own keys, kept in a local file tradememory sync alpaca --env-file ~/.secrets/alpaca.env ``` Added …View on GitHub ↗ -
v0.5.5 v0.5.5 — SPA path containment security hotfix
Release notes excerpt
Security hotfix for the dashboard SPA catch-all route (GitHub issue #13). - SPA static path is now bounded to dashboard/dist — the catch-all in server.py checked containment with a plain string startswith, which has no path-component boundary: a sibling directory whose name merely shares the prefix (dist-x/) passed the check. Containment is now Path.is_relative_to in a dedicated _resolve_static_file helper. Paths that escape the dist root return 404 as before; client-side routes still fall back to index.html. …View on GitHub ↗ -
v0.5.4 v0.5.4 — anchoring integrity hotfix
Release notes excerpt
Same-day hotfix for three critical gaps an adversarial review found in the v0.5.3 anchoring path: - Rebuilds no longer destroy existing anchors — tsa_token is preserved when the recomputed root is identical, dropped only when the underlying data actually changed. - TSA rejections can no longer masquerade as anchors — PKIStatus is now verified; explicit rejections raise instead of being stored as proof. …View on GitHub ↗