Intelligent Agent Memory System

The Agent Memory System (api/agent_autopilot.py, ~1,320 lines) replaces flat last-N memory with a structured three-tier hierarchy exposed via a Model Context Protocol (MCP) server (api/mcp_memory_server.py). It enables the optimizer agent to retain proven rules across sessions, transfer knowledge between symbols, and provide the LLM with only relevant context — with a Memory Researcher fetching historical context and a Strategy Advisor generating recommendations.

---

Architecture Overview

Key Components

Component	File	Lines	Purpose
Autopilot Loop	api/agent_autopilot.py	745–1320	Full orchestration: vision → memory research → strategy generation → block validation → backtest → learn → synthesize → evaluate → backtrack
MCP Server	api/mcp_memory_server.py	—	TCP JSON-RPC server exposing search_agent_memory tool
Memory Researcher	api/agent_autopilot.py	284–433	Fetches rules + exact/cross-asset insights from MCP before strategy generation
Strategy Advisor	api/agent_autopilot.py	436–676	Two-turn LLM dialogue: turn 0 selects tags for memory search, turn 1 analyzes context and writes recommendations
Critic Sub-Agent	api/agent_autopilot.py	679–742	Standalone strategy logic validator (bypassed in autopilot loop; available for external use)
Block Validation	api/agent_autopilot.py	903–937	Programmatic check for restricted blocks (pro_only, kline_only)
Rule Synthesis	api/agent_autopilot.py	110–202	Promotes 3+ similar insights into a permanent rule
Lifecycle Evaluation	api/agent_autopilot.py	205–270	Reinforces success, decays/deprecates failures
Tag Classification	api/agent_autopilot.py	27–107	LLM assigns tags, strategy type, outcome to each insight

---

Database Model

Sources: models.py

The table is auto-created at startup (api/depthsight_api.py:1262). Extended fields (tags, symbol, strategy_type, outcome, confidence, validated_count, config_hash) were added via migration alembic/versions/2a487db2c451_add_memory_tags.py.

Memory Types

Type	TTL	Description
rule	Permanent	Cross-asset rules promoted from insights
strategy_insight	90/30/60 days	Tagged conclusions from backtest runs
observation	7 days	Raw ephemeral results
preference	N/A	User-level preferences
market_context	N/A	Market regime observations

TTL Policies for Insights

Outcome	TTL
Success (PnL > 0, trades >= 5)	90 days
Failure	30 days
Optimization result	60 days
Rules	Permanent (expires_at = None)

---

MCP Memory Server

The memory system is exposed as a Model Context Protocol tool via a custom TCP-based JSON-RPC 2.0 server (api/mcp_memory_server.py, 329 lines).

Protocol

Aspect	Detail
Transport	TCP (not stdio)
Protocol	JSON-RPC 2.0
Port	8100 (configurable via MCP_MEMORY_PORT)
Host	127.0.0.1 (dev) / 0.0.0.0 (Docker)
Version	2025-03-26

Tool: search_agent_memory

Sources: mcp_memory_server.py

Context Format

### Agent Memory Context

**Universal Rules:**
- 🔴 [conf: 85%] Volume spike > 2x required for breakout

**ETHUSDT Insights:**
- 🟡 [SUCCESS, PnL: +15%] Ascending triangle breakout with ADX confirmation

**Cross-Asset Transfer:**
- ⚡ [Transfer from BTCUSDT] [SUCCESS] Similar momentum setup

Deployment

In Docker, the MCP server runs as a separate container:

Sources: docker-compose.yml

Other services (api, websocket, bot, celery_worker) connect via MCP_MEMORY_HOST=mcp-memory.

Environment Variables

Variable	Default	Description
MCP_MEMORY_PORT	8100	TCP port
MCP_MEMORY_HOST	127.0.0.1	Host (use 0.0.0.0 in Docker)
AI_ADVISOR_MODEL	—	Model for Strategy Advisor agent (defaults to AI_CRITIC_MODEL)
MAX_AUTOPILOT_ITERATIONS	5	Max iterations for the autopilot loop

---

Sub-Agent Critic

The Critic sub-agent (api/agent_autopilot.py:679-742) is a standalone LLM validator that checks strategy JSON for logical flaws. It is bypassed in the autopilot loop (replaced by Memory Researcher + Strategy Advisor) but available as a direct API or utility function.

Critic Checklist

The critic (api/prompts/critic_system.md) checks for:

Check	Description
Inverted SL/TP	Stop Loss above entry for long, or Take Profit below
Contradictory filters	Both uptrend AND downtrend conditions simultaneously
Missing weights	Zero or missing foundation weights
Missing partial exits	Strategy defines exits but no partial exit rules

Output Format

{"approved": true}

On rejection:

{"approved": false, "reason": "Stop Loss is set above entry price for long position.", "critical_flaw": "inverted_stop_loss"}

Sources: agent_autopilot.py

Model Selection

Configurable via AI_CRITIC_MODEL env var:

Provider	Default Model
Gemini	gemini-3-flash-preview
Qwen	qwen-max
OpenRouter	google/gemini-3-flash-preview

Auto-Approve Fallback

If the critic LLM call fails entirely (timeout or JSON decode), the system auto-approves the strategy to avoid blocking the pipeline:

{"approved": True, "reason": "Auto-approved (critic error)"}

---

Memory Researcher

Before strategy generation, the Memory Researcher (api/agent_autopilot.py:284-433) queries the MCP server for relevant historical context — fetching active rules, exact-symbol insights, and cross-asset transfers.

Sources: agent_autopilot.py

The context is formatted as a structured text block with three sections:

**Universal Rules (max 2):**
- [conf: 85%] Volume spike > 2x required for breakout

**Exact Insights for {symbol} (max 3):**
- [SUCCESS, PnL: +15%] Ascending triangle breakout with ADX

**Cross-Asset Transfer:**
- [Transfer from BTCUSDT] [SUCCESS] Similar momentum setup

---

Strategy Advisor

After the Memory Researcher returns context, the Strategy Advisor (api/agent_autopilot.py:436-676) conducts a two-turn LLM dialogue:

1. Turn 0 — Tag Selection: The advisor proposes tags for memory search (e.g., ["momentum", "breakout", "ethusdt"]). These tags are used to query additional context.
2. Turn 1 — Recommendation: The advisor analyzes the full context (tags + memory + chart screenshot on 1st iteration) and writes a strategy recommendation.

Sources: agent_autopilot.py

Configurable via AI_ADVISOR_MODEL env var (default: same as AI_CRITIC_MODEL).

---

Block Validation

After strategy generation, a programmatic block validator (api/agent_autopilot.py:903-937) checks for restricted blocks:

Block Type	Restriction
pro_only	Only allowed if user has Pro subscription
kline_only	Only allowed on supported timeframes

If validation fails, the autopilot retries strategy generation with the list of violating blocks as feedback.

---

Autopilot Loop

The full agent cycle is orchestrated in run_autopilot_loop() (api/agent_autopilot.py:745-1135). It accepts a max_iterations parameter (default: MAX_AUTOPILOT_ITERATIONS):

Sources: agent_autopilot.py

Loop Steps

Step	Description
Vision	Separate LLM call analyzes chart screenshot (1st iteration only); returns pattern description used as context
Memory Research	Fetch rules + exact/cross-asset insights via MCP
Strategy Advisor	Two-turn LLM: selects tags → generates strategy with full context
Block Validation	Programmatic check for pro_only / kline_only violations; retries on failure
Backtest	Celery task executes the backtest asynchronously
Learn	Save insight with tags, outcome, confidence; success = 90d TTL, failure = 30d TTL
Synthesize	If 3+ insights for this strategy type, promote to a rule
Evaluate	Reinforce success (+0.1 confidence) or decay failure (-0.2); deprecate if confidence <= 0.3
Backtrack	Compare PnL to best so far; reset strategy if worse, update baseline if better

Screenshot & Vision Analysis

On the first autopilot iteration, a chart screenshot is sent to the LLM in two stages:

1. Vision analysis — a separate LLM call analyzes the screenshot for chart patterns, returning structured observations
2. Strategy generation — the vision output is passed as context to the Strategy Advisor

Sources: agent_autopilot.py

The feature is optional — both image_base64 and image_mime_type are nullable parameters.

---

Rule Lifecycle: Reinforcement & Forgetting

Two mechanisms control memory decay:

1. TTL-Based Forgetting

Each memory has an expires_at timestamp. Expired rows are:

• Filtered out of all queries (expires_at IS NULL OR expires_at > now())
• Purged by delete_expired_memories() CRUD function

2. Confidence-Based Deprecation

Sources: agent_autopilot.py

Event	Effect
Backtest confirms rule	confidence += 0.1, validated_count += 1
Backtest contradicts rule	confidence -= 0.2, validated_count -= 1
Confidence <= 0.3	Rule marked deprecated (expires_at = now())
validated_count <= -2	Rule marked deprecated

Rule Promotion (Synthesis)

When 3+ insights with the same strategy type exist, the system promotes them into a permanent rule:

Sources: agent_autopilot.py

---

MCP Integration with AI Providers

The AI Assistant (api/ai_assistant.py) converts MCP tools into each provider's native function-calling format:

Sources: ai_assistant.py

Provider	Mechanism	Configuration
Gemini	types.Tool with FunctionCallingConfig(mode="ANY")	Forces function call on turn 0, JSON response on subsequent turns
OpenRouter / Qwen	OpenRouter function-calling format	Detects native tool_calls or text-fallback regex call:search_agent_memory(...)
Fallback	Regex call:search_agent_memory(...)	For models that don't support native function calling

The user_id is injected server-side into every MCP tool call, so the model does not need to supply it.

---

Tag Classification

Tags are assigned by an LLM call at insight save time (tag_strategy_insight()):

Sources: agent_autopilot.py

The prompt (api/prompts/tag_insight.md) instructs the LLM to:

1. Extract the strategy type from structural blocks
2. Prefer reusing existing tags for consistency
3. Assign confidence based on PnL and trade count
4. Return JSON with strategy_type, tags, outcome, confidence

If the LLM call fails, the system falls back to extracting strategy_type from block names and building tags from [symbol, strategy_type, filter types].

---

REST API

In addition to the MCP interface, memories can be managed via REST:

Sources: ai.py

---

Why This Wins

Judge Criteria	What We Show
Memory Agent	Three-tier hierarchy with MCP tool interface
Persistent Memory	Lives in PostgreSQL across sessions
Learning from Experience	Rules auto-extracted from 3+ similar insights
Forgetting	TTL expiry + confidence-based deprecation
Transfer Learning	Knowledge from ETH applied to BTC, marked ⚡
Memory Researcher	Fetches rules + insights for strategic context before generation
Strategy Advisor	Two-turn LLM dialogue: selects tags → generates strategy
Screenshot Vision	Separate vision analysis step on first generation pass
MCP Protocol	Standardized tool interface compatible with any MCP host