Vector Memory & Decision Logs
Relevant source files
The following files were used as context for generating this wiki page:
Vector Memory and Decision Logs form the core of the Agentic Trading System's explainability and optimization layer. This system is designed to provide a structured, deterministic approach to recording why specific trade decisions were made, enabling historical review, backtesting reproducibility, and agentic reasoning refinement. By utilizing a modular architecture, the system separates trade execution logic from the storage of decision-making metadata.
The primary purpose of this module is to observe market data, make structured trade decisions (such as buy_to_open), and annotate those decisions with human-readable or machine-processable reasoning (e.g., "momentum breakout at 10:05 AM"). These logs are stored in a pgvector-backed database to allow for high-performance similarity searches over historical trading behaviors and market conditions.
Sources: PLAN.md:4-15, PLAN.md:72-76
Architecture and Components
The system architecture is divided into modular agents and specialized tools that interact with a vector-capable PostgreSQL database. The memory subsystem provides a persistent layer where embeddings of market states and decision logs reside.
Core Memory Components
| Component | Description | Source |
|---|---|---|
memory/ directory | Contains the pgvector-backed decision logs and embedding logic. | PLAN.md:26 |
VectorLoggerTool | A Pydantic AI tool used to annotate decisions for vector search. | PLAN.md:65 |
agents/ | Logic handlers (LongAgent, BreakoutAgent, etc.) that generate reasoning. | PLAN.md:21 |
Data Flow for Decision Logging
The logging process begins when an agent receives a market tick. Upon fulfilling entry or exit criteria, the agent generates a structured TradeDecision which includes an annotation string. This data is passed through a Pydantic AI tool abstraction to the vector database.
The diagram above illustrates the path from raw market data to persistent vector storage for future optimization and review.
Sources: PLAN.md:10-15, PLAN.md:26, PLAN.md:65
Decision Log Implementation
In the current implementation, logging is facilitated by the Strategy class and its specialized subclasses. The RiskAverseStrategy, for instance, utilizes a structured log() method to capture and output signal statuses and order metadata.
Logging Attributes
Decision logs typically capture the following data points to ensure deterministic backtesting and review:
- Signal Metadata: Indicators such as volatility percentages, new high flags, and high-low differentials.
- Order Notifications: Execution price, size, cost, and commission.
- Temporal Context: ISO-formatted timestamps for every logged event.
# Example reasoning capture from risk_adverse.py
def log(self, txt, dt=None, level="info"):
dt = dt or self.datas[0].datetime.date(0)
print(f"{dt.isoformat()}: {txt}")
# Usage during a signal
self.log(f"BUY SIGNAL: Volatility: {self.volatility.avg_volatility[0]:.2f}%, "
f"New High: Yes, Volume: {self.datavolume[0]:.0f}, High-Low Diff: "
f"{self.high_low_diff.diff[0]:.3f}")
Sources: strategies/risk_adverse.py:270-280, strategies/risk_adverse.py:421-427
Trade Tracking Data Model
The system tracks trades through completion, logging gross and net P/L for performance analysis.
| Field | Data Type | Description |
|---|---|---|
trade_count | Integer | Total number of executed trades. |
winning_trades | Integer | Number of trades with positive net P/L. |
pnl | Float | Gross Profit/Loss before commissions. |
pnlcomm | Float | Net Profit/Loss after commissions. |
Sources: strategies/risk_adverse.py:307-315, strategies/risk_adverse.py:535-545
Execution and Notification Logging
The system bridges the gap between agent reasoning and actual broker execution through a comprehensive notification system. Logs are updated in real-time as orders transition through various statuses.
Order Status Sequence
The interaction between the strategy and the broker (e.g., Interactive Brokers) generates execution logs that are appended to the decision history.
This sequence ensures that the initial "intent" (reasoning) is eventually paired with the "outcome" (execution details).
Sources: backtrader/strategy.py:756-764, backtrader/stores/ibstore_insync.py:430-450
Log Management Classes
The project uses specialized message objects to wrap log data before storage or notification.
ErrorMsg: CapturesreqId,errorCode, anderrorString.OrderStatusMsg: Tracksfilled,remaining, andavgFillPrice.OpenOrderMsg: Links orders to specificcontractsandorderStates.
Sources: backtrader/stores/ibstore_insync.py:65-150
Reporting and Post-Trade Analysis
As planned in the system roadmap, logs are not only used for internal agent memory but also for generating analytical reports.
Planned Reporting Tools
- Daily/Weekly Reporting CLI: Summarizes positions, risk, and P&L based on logged vectors.
- Command Center UI: A Panel-based interface for monitoring real-time decision logs.
- Pre-market/Daily Reports: Tools to generate contextual reports using scraped data and historical memory.
Sources: PLAN.md:68-70, PLANNING.md:20-28
The modularity of the system ensures that as new agents (e.g., ShortAgent) or exit strategies are added, they can immediately leverage the existing VectorLoggerTool to maintain consistent decision logs. This structure supports the philosophy of composable and explainable trading jobs.
Sources: PLAN.md:72-76, PLANNING.md:10-18