Skip to content

Memory System

Quantbot features an advanced memory system that enables contextual, intelligent conversations by remembering past interactions, learning user preferences, and maintaining conversation continuity across sessions.

Overview

The memory system is built on Neo4j graph database with Graphiti-core library, providing:

  • Episodic Memory: Stores conversation history and context
  • Entity Extraction: Automatically identifies and links financial entities
  • Semantic Search: Finds relevant past conversations using AI embeddings
  • User Isolation: Strict data separation between users
  • Relationship Mapping: Builds connections between concepts and entities

Architecture

Core Components

graph TB
    subgraph "Memory System"
        MM[Memory Manager<br/>graphiti-core]
        EP[Episode Storage]
        ES[Entity Storage] 
        ED[Edge Storage]
    end

    subgraph "Neo4j Graph Database"
        NODES[(Graph Nodes)]
        EDGES[(Graph Edges)]
        EMBED[(Vector Embeddings)]
    end

    subgraph "AI Integration"
        OPENAI[OpenAI Embeddings<br/>Semantic similarity]
        GEMINI[Google Gemini<br/>Context understanding]
    end

    MM --> EP
    MM --> ES
    MM --> ED
    EP --> NODES
    ES --> NODES
    ED --> EDGES
    MM --> OPENAI
    MM --> GEMINI

    style MM fill:#4ecdc4
    style NODES fill:#008cc1
    style OPENAI fill:#ff6b6b

Data Model

The memory system organizes information into several key node types:

Episode Nodes

  • Conversation Units: Individual user-AI interactions
  • Timestamps: When conversations occurred
  • Context: Full conversation content and metadata
  • User Attribution: Linked to specific user groups

Entity Nodes

  • Financial Entities: Stocks, companies, market indices
  • Concepts: Investment strategies, market conditions
  • Personal Preferences: User goals and interests
  • Relationships: Connections between entities

Group Nodes

  • User Isolation: Each user has a unique group ID
  • Data Segregation: Ensures privacy and security
  • Access Control: Manages data permissions

Key Features

1. Contextual Conversations

The memory system enables Quantbot to:

  • Reference Past Discussions: "As we discussed last week about Tesla..."
  • Track Investment Decisions: Remember portfolio changes and reasoning
  • Maintain Context: Continue conversations across sessions
  • Learn Preferences: Adapt responses based on user interests

2. Entity Recognition

Automatically extracts and stores:

  • Stock Symbols: AAPL, GOOGL, TSLA, etc.
  • Company Names: Apple Inc., Alphabet, Tesla
  • Financial Metrics: P/E ratios, market cap, volatility
  • Investment Strategies: Value investing, growth stocks, dividends
  • Market Events: Earnings announcements, market trends

3. Relationship Building

Creates connections between:

  • User ↔ Stocks: Which stocks the user follows or owns
  • Stocks ↔ Sectors: Technology, healthcare, energy sectors
  • Events ↔ Impacts: How earnings affect stock prices
  • Strategies ↔ Outcomes: Which approaches worked well

Uses AI embeddings to find relevant information:

  • Similar Topics: Find discussions about related stocks
  • Contextual Relevance: Surface pertinent past conversations
  • Concept Matching: Connect abstract ideas and strategies
  • Temporal Relevance: Prioritize recent vs. historical context

Configuration

Environment Variables

# Neo4j Database Connection
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=quantbot_neo4j_password
DEFAULT_DATABASE=neo4j

# OpenAI for Embeddings
OPENAI_API_KEY=your-openai-api-key

# Memory Behavior
MEMORY_MAX_EPISODES_PER_USER=10000
MEMORY_RETENTION_DAYS=365
MEMORY_SEARCH_LIMIT=50
MEMORY_SIMILARITY_THRESHOLD=0.7
MEMORY_ENABLE_ENCRYPTION=true
MEMORY_ISOLATION_STRICT=true
MEMORY_BATCH_SIZE=100
MEMORY_CACHE_TTL_SECONDS=300

# Feature Toggle
DISABLE_MEMORY=false

Memory Manager Configuration

from app.agents.quantbot.utils.memory_manager import MemoryManager

# Initialize memory manager
memory_manager = MemoryManager()

# Configuration options
memory_manager.config = {
    "max_episodes_per_user": 10000,
    "retention_days": 365,
    "similarity_threshold": 0.7,
    "search_limit": 50,
    "enable_encryption": True,
    "batch_size": 100
}

Usage Examples

Storing Conversations

from datetime import datetime
from app.agents.quantbot.utils.memory_manager import MemoryManager

memory_manager = MemoryManager()

# Store a conversation episode
await memory_manager.add_episode(
    group_id=f"user_{user_id}",
    name="quantbot",
    episode_body="User asked about Tesla stock performance and portfolio allocation strategy",
    reference_time=datetime.utcnow()
)

Searching Memory

# Search for relevant past conversations
results = await memory_manager.search(
    group_ids=[f"user_{user_id}"],
    query="Tesla portfolio strategy",
    num_results=10
)

# Process search results
for result in results:
    print(f"Relevance: {result.score}")
    print(f"Content: {result.content}")
    print(f"Timestamp: {result.timestamp}")

Entity Extraction

# Entities are automatically extracted from conversations
# Example of what gets stored:

entities = {
    "stocks": ["TSLA", "AAPL", "GOOGL"],
    "companies": ["Tesla", "Apple", "Alphabet"],
    "concepts": ["portfolio allocation", "risk management", "growth stocks"],
    "metrics": ["P/E ratio", "market cap", "volatility"],
    "strategies": ["dollar cost averaging", "momentum investing"]
}

Memory in Action

Conversation Continuity

Previous Conversation: 

User: "I'm thinking about investing in Tesla. What do you think?"
Quantbot: "Tesla has shown strong growth but high volatility. 
          Given your moderate risk tolerance, consider a 
          smaller position size..."

Later Conversation: 

User: "How is Tesla doing today?"
Quantbot: "Tesla is up 3.2% today. Remembering our previous 
          discussion about your interest in TSLA and your 
          moderate risk approach, this might be a good entry 
          point for the smaller position we discussed..."

Learning User Preferences

The system learns and remembers:

  • Risk Tolerance: Conservative, moderate, or aggressive
  • Investment Goals: Growth, income, preservation
  • Sector Preferences: Technology, healthcare, energy
  • Portfolio Size: Small retail vs. large institutional
  • Time Horizon: Short-term trading vs. long-term investing

Contextual Recommendations

Based on memory, Quantbot provides:

  • Personalized Analysis: Tailored to user's portfolio and goals
  • Consistent Advice: Aligned with previous recommendations
  • Progressive Learning: Builds on past conversations
  • Relevant Examples: Uses user's own portfolio for context

Privacy and Security

User Data Isolation

  • Group-Based Separation: Each user has a unique group ID
  • Strict Boundaries: Users cannot access others' memory data
  • Permission Validation: All queries verified against user identity
  • Audit Trail: Memory access logged for security monitoring

Data Encryption

  • At Rest: Sensitive data encrypted in Neo4j
  • In Transit: Secure connections to database
  • API Keys: Encrypted storage of user API keys
  • PII Protection: Personal information anonymized

Data Retention

  • Configurable Retention: Default 365 days, customizable
  • Automatic Cleanup: Old episodes removed automatically
  • User Control: Users can request data deletion
  • Compliance Ready: GDPR and privacy regulation compliant

Performance Considerations

Optimization Strategies

  • Vector Indexing: Neo4j vector indexes for fast similarity search
  • Caching: Frequently accessed memories cached in Redis
  • Batch Processing: Bulk operations for efficiency
  • Connection Pooling: Optimized database connections
  • Async Operations: Non-blocking memory operations

Scaling

  • Horizontal Scaling: Neo4j clustering for large deployments
  • Memory Limits: Per-user episode limits prevent unbounded growth
  • Search Optimization: Configurable search result limits
  • Background Processing: Memory storage happens asynchronously

Monitoring and Metrics

Memory Health Metrics

  • Storage Usage: Total episodes and entities per user
  • Search Performance: Query response times and relevance scores
  • Memory Quality: Entity extraction accuracy and relationship density
  • User Engagement: How often memory enhances conversations

Troubleshooting

Common Issues

Memory Not Loading: 

# Check Neo4j connection
docker compose logs neo4j

# Verify environment variables
docker compose exec backend printenv | grep NEO4J

# Test memory manager
docker compose exec backend python -c "
from app.agents.quantbot.utils.memory_manager import MemoryManager
mm = MemoryManager()
print('Memory manager initialized successfully')
"

Search Results Poor: 

# Check similarity threshold (lower = more results)
MEMORY_SIMILARITY_THRESHOLD=0.5

# Verify OpenAI API key for embeddings
echo $OPENAI_API_KEY

# Check search limit
MEMORY_SEARCH_LIMIT=20

Performance Issues: 

# Monitor Neo4j performance
# Visit http://localhost:7474
# Check query performance and index usage

# Adjust batch sizes
MEMORY_BATCH_SIZE=50

# Enable caching
MEMORY_CACHE_TTL_SECONDS=600

API Integration

Memory API Endpoints

The memory system integrates with the REST API:

Store Memory

POST /api/v1/memory/ingest
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "User discussion about Tesla investment strategy",
  "context": {
    "user_id": 123,
    "timestamp": "2025-01-15T10:30:00Z",
    "entities": ["TSLA", "investment strategy"]
  }
}

Search Memory

GET /api/v1/memory/retrieve?query=Tesla%20strategy&limit=10
Authorization: Bearer <token>

Response: 

{
  "results": [
    {
      "content": "Previous discussion about Tesla investment...",
      "score": 0.89,
      "timestamp": "2025-01-10T14:20:00Z",
      "entities": ["TSLA", "portfolio allocation"]
    }
  ],
  "total": 5,
  "query": "Tesla strategy"
}

Future Enhancements

Planned Features

  • Multi-Modal Memory: Store and recall charts, images, documents
  • Collaborative Memory: Shared insights across user groups (with permission)
  • Memory Analytics: Detailed insights into conversation patterns
  • Memory Export: User-controlled data export and portability
  • Advanced Search: Natural language queries with complex filters

Research Areas

  • Improved Entity Extraction: Better financial concept recognition
  • Temporal Reasoning: Understanding time-based relationships
  • Causal Inference: Learning cause-effect relationships in markets
  • Memory Consolidation: Automatic summarization of old conversations
  • Cross-Domain Learning: Applying insights across different market sectors

The memory system transforms Quantbot from a stateless chatbot into an intelligent financial assistant that truly learns and remembers, providing increasingly personalized and valuable insights over time.