RAAF Memory Guide

# Basic memory setup
memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::InMemoryStore.new,
  max_tokens: 4000,
  pruning_strategy: :sliding_window
)

runner = RAAF::Runner.new(
  agent: agent,
  memory_manager: memory_manager
)

# Simple in-memory storage
memory_store = RAAF::Memory::InMemoryStore.new

# With size limits
memory_store = RAAF::Memory::InMemoryStore.new(
  max_size: 100.megabytes,
  max_entries: 10000
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: memory_store,
  max_tokens: 4000
)

# Basic file storage
file_store = RAAF::Memory::FileStore.new(
  directory: './conversations',
  session_id: 'user_123'
)

# With compression and encryption
file_store = RAAF::Memory::FileStore.new(
  directory: './conversations',
  session_id: 'user_123',
  compression: :gzip,
  encryption: {
    key: ENV['MEMORY_ENCRYPTION_KEY'],
    algorithm: 'AES-256-GCM'
  }
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: file_store,
  max_tokens: 8000,
  pruning_strategy: :summarization
)

# ActiveRecord integration
class ConversationMemory < ActiveRecord::Base
  serialize :messages, JSON
  serialize :metadata, JSON

  validates :session_id, presence: true
  scope :for_user, ->(user_id) { where(user_id: user_id) }
end

db_store = RAAF::Memory::DatabaseStore.new(
  model: ConversationMemory,
  session_id: 'user_123',
  user_id: current_user.id
)

# With custom schema
db_store = RAAF::Memory::DatabaseStore.new(
  connection: ActiveRecord::Base.connection,
  table_name: 'agent_conversations',
  session_column: 'conversation_id',
  content_column: 'message_data',
  metadata_column: 'context_data'
)

# Basic vector store with OpenAI embeddings
vector_store = RAAF::Memory::VectorStore.new(
  embedding_model: 'text-embedding-3-small',
  dimension: 1536,
  similarity_threshold: 0.7
)

# With custom vector database
vector_store = RAAF::Memory::VectorStore.new(
  backend: :pinecone,
  api_key: ENV['PINECONE_API_KEY'],
  index_name: 'raaf-conversations',
  embedding_model: 'text-embedding-3-small'
)

# With local vector database
vector_store = RAAF::Memory::VectorStore.new(
  backend: :chroma,
  persist_directory: './vector_store',
  collection_name: 'conversations'
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: vector_store,
  max_tokens: 16000,
  pruning_strategy: :semantic_similarity
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: store,
  max_tokens: 4000,
  pruning_strategy: :sliding_window,
  window_config: {
    preserve_system_messages: true,
    preserve_last_user_message: true,
    minimum_messages: 2
  }
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: store,
  max_tokens: 6000,
  pruning_strategy: :summarization,
  summary_config: {
    summary_model: 'gpt-4o-mini',  # Use cheaper model for summaries
    summary_trigger: 0.8,          # Summarize when 80% of tokens used
    summary_ratio: 0.3,            # Reduce to 30% of original size
    preserve_recent_count: 5       # Keep last 5 messages unsummarized
  }
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::VectorStore.new,
  max_tokens: 8000,
  pruning_strategy: :semantic_similarity,
  similarity_config: {
    similarity_threshold: 0.75,
    max_relevant_messages: 20,
    context_window: 3,              # Messages around relevant ones
    recency_weight: 0.3             # Weight recent messages higher
  }
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: store,
  max_tokens: 6000,
  pruning_strategy: :importance_based,
  importance_config: {
    importance_model: 'gpt-4o-mini',
    scoring_prompt: """
      Rate the importance of this message for future conversation context.
      Consider: relevance, emotional significance, actionable information.
      Score from 1-10.
    """,
    minimum_importance: 6,
    preserve_high_importance: true
  }
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::VectorStore.new,
  max_tokens: 10000,
  pruning_strategy: :hybrid,
  hybrid_config: {
    strategies: [
      { type: :sliding_window, weight: 0.3, preserve_count: 3 },
      { type: :semantic_similarity, weight: 0.4, threshold: 0.8 },
      { type: :importance_based, weight: 0.3, min_score: 7 }
    ],
    fallback_strategy: :sliding_window
  }
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: store,
  max_tokens: 4000,
  context_variables: {
    user_preferences: { theme: 'dark', language: 'en' },
    conversation_goal: 'technical_support',
    user_expertise_level: 'intermediate'
  }
)

# Update context variables during conversation
runner.memory_manager.update_context(
  user_expertise_level: 'advanced',
  last_successful_solution: 'database_optimization'
)

# Access in tools
def provide_help(topic:)
  user_level = runner.memory_manager.context[:user_expertise_level]

  case user_level
  when 'beginner'
    provide_basic_help(topic)
  when 'intermediate'
    provide_detailed_help(topic)
  when 'advanced'
    provide_expert_help(topic)
  end
end

compressed_store = RAAF::Memory::CompressedStore.new(
  backend_store: RAAF::Memory::FileStore.new(directory: './conversations'),
  compression_algorithm: :lz4,      # :gzip, :lz4, :zstd
  compression_level: 6,
  compress_threshold: 1000          # Compress when >1000 characters
)

memory_manager = RAAF::Memory::MemoryManager.new(
  store: compressed_store,
  max_tokens: 8000
)

analytics_store = RAAF::Memory::AnalyticsStore.new(
  backend_store: store,
  analytics_config: {
    track_access_patterns: true,
    track_pruning_events: true,
    track_token_usage: true,
    generate_insights: true
  }
)

# Get memory analytics
analytics = analytics_store.get_analytics
puts "Average conversation length: #{analytics[:avg_conversation_length]}"
puts "Most accessed topics: #{analytics[:top_topics]}"
puts "Pruning efficiency: #{analytics[:pruning_efficiency]}"

# Shared memory for multi-agent workflow
shared_memory = RAAF::Memory::SharedMemoryManager.new(
  store: RAAF::Memory::VectorStore.new,
  session_id: 'workflow_123',
  sharing_strategy: :selective
)

# Research agent
research_agent = RAAF::Agent.new(
  name: "Researcher",
  instructions: "Research topics thoroughly"
)

# Writer agent  
writer_agent = RAAF::Agent.new(
  name: "Writer",
  instructions: "Write based on research findings"
)

# Both agents share the same memory
research_runner = RAAF::Runner.new(
  agent: research_agent,
  memory_manager: shared_memory
)

writer_runner = RAAF::Runner.new(
  agent: writer_agent, 
  memory_manager: shared_memory
)

# Research phase
research_result = research_runner.run("Research sustainable energy")

# Writing phase - has access to research context
writing_result = writer_runner.run("Write an article based on the research")

class ContextHandoffManager
  def initialize
    @agent_memories = {}
  end

  def create_agent_memory(agent_name, base_memory)
    @agent_memories[agent_name] = RAAF::Memory::ScopedMemoryManager.new(
      base_memory: base_memory,
      scope: agent_name,
      inheritance_rules: {
        inherit_context_variables: true,
        inherit_important_messages: true,
        inherit_recent_messages: 3
      }
    )
  end

  def handoff_context(from_agent, to_agent, context_filter = nil)
    source_memory = @agent_memories[from_agent]
    target_memory = @agent_memories[to_agent]

    # Extract relevant context
    handoff_context = source_memory.extract_context(
      filter: context_filter,
      importance_threshold: 7,
      recent_count: 5
    )

    # Transfer to target agent
    target_memory.receive_handoff_context(
      from_agent: from_agent,
      context: handoff_context,
      timestamp: Time.now
    )
  end
end

# Connection pooled database store
pooled_store = RAAF::Memory::PooledDatabaseStore.new(
  connection_pool: ConnectionPool.new(size: 10, timeout: 5) do
    ActiveRecord::Base.connection
  end,
  table_name: 'conversations'
)

async_memory = RAAF::Memory::AsyncMemoryManager.new(
  store: store,
  async_operations: [:save, :prune, :search],
  thread_pool_size: 3,
  queue_size: 100
)

# Non-blocking save
async_memory.save_async(session_id, messages) do |result|
  if result.success?
    logger.info "Memory saved successfully"
  else
    logger.error "Memory save failed: #{result.error}"
  end
end

batch_memory = RAAF::Memory::BatchMemoryManager.new(
  store: store,
  batch_size: 100,
  flush_interval: 30.seconds,
  auto_flush: true
)

# Operations are batched automatically
batch_memory.save(session_id, message1)
batch_memory.save(session_id, message2)
batch_memory.save(session_id, message3)
# Automatically flushes when batch_size reached or flush_interval elapsed

search_memory = RAAF::Memory::SearchableMemoryManager.new(
  store: RAAF::Memory::VectorStore.new,
  search_config: {
    embedding_model: 'text-embedding-3-small',
    index_strategy: :real_time,
    search_fields: [:content, :summary, :context_variables]
  }
)

# Semantic search across conversations
search_results = search_memory.search(
  query: "How to optimize database performance",
  limit: 10,
  similarity_threshold: 0.7,
  filters: {
    user_id: current_user.id,
    date_range: 1.month.ago..Time.now,
    conversation_type: 'technical_support'
  }
)

search_results.each do |result|
  puts "Similarity: #{result[:similarity]}"
  puts "Message: #{result[:content]}"
  puts "Context: #{result[:context]}"
end

rag_memory = RAAF::Memory::RAGMemoryManager.new(
  store: RAAF::Memory::VectorStore.new,
  rag_config: {
    chunk_size: 500,
    chunk_overlap: 50,
    retrieval_count: 5,
    rerank_model: 'cross-encoder/ms-marco-MiniLM-L-6-v2'
  }
)

# Add knowledge documents
rag_memory.index_document(
  content: File.read('technical_docs.md'),
  metadata: { type: 'documentation', topic: 'database' }
)

# Agent with RAG capabilities
rag_agent = RAAF::Agent.new(
  name: "RAGAgent",
  instructions: <<~INSTRUCTIONS
    You are a technical assistant with access to relevant documentation.
    Use the provided context to answer questions accurately.
  INSTRUCTIONS
)

# Tool for RAG retrieval
rag_agent.add_tool(lambda do |query:|
  relevant_docs = rag_memory.retrieve(
    query: query,
    count: 3,
    rerank: true
  )

  {
    context: relevant_docs.map { |doc| doc[:content] },
    sources: relevant_docs.map { |doc| doc[:metadata] }
  }
end)

RSpec.describe 'Memory Management' do
  let(:memory_store) { RAAF::Memory::InMemoryStore.new }
  let(:memory_manager) do
    RAAF::Memory::MemoryManager.new(
      store: memory_store,
      max_tokens: 1000,
      pruning_strategy: :sliding_window
    )
  end

  it 'stores and retrieves messages' do
    memory_manager.add_message(
      session_id: 'test_session',
      role: 'user',
      content: 'Hello'
    )

    messages = memory_manager.get_messages('test_session')
    expect(messages).to have(1).message
    expect(messages.first[:content]).to eq('Hello')
  end

  it 'prunes messages when token limit exceeded' do
    # Add messages that exceed token limit
    10.times do |i|
      memory_manager.add_message(
        session_id: 'test_session',
        role: 'user',
        content: 'A' * 200  # Large message
      )
    end

    messages = memory_manager.get_messages('test_session')
    total_tokens = memory_manager.count_tokens(messages)

    expect(total_tokens).to be <= 1000
    expect(messages.count).to be < 10
  end
end

RSpec.describe 'Memory in Agent Workflows' do
  let(:memory_manager) do
    RAAF::Memory::MemoryManager.new(
      store: RAAF::Memory::InMemoryStore.new,
      max_tokens: 2000
    )
  end

  let(:agent) do
    RAAF::Agent.new(
      name: "MemoryAgent",
      instructions: "Remember what users tell you"
    )
  end

  let(:runner) do
    RAAF::Runner.new(
      agent: agent,
      memory_manager: memory_manager
    )
  end

  it 'maintains context across turns' do
    # First turn
    result1 = runner.run("My name is Alice and I'm a developer")
    expect(result1.success?).to be true

    # Second turn - agent should remember
    result2 = runner.run("What's my profession?")
    expect(result2.messages.last[:content]).to include('developer')
  end

  it 'handles memory pruning gracefully' do
    # Fill memory to capacity
    20.times do |i|
      runner.run("This is message number #{i} with lots of content to fill up memory space")
    end

    # New message should still work
    result = runner.run("What's the weather like?")
    expect(result.success?).to be true
  end
end

# Short conversations, development
memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::InMemoryStore.new,
  max_tokens: 4000,
  pruning_strategy: :sliding_window
)

# Long conversations, detailed context needed
memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::VectorStore.new,
  max_tokens: 8000,
  pruning_strategy: :semantic_similarity
)

# Production, high volume
memory_manager = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::DatabaseStore.new,
  max_tokens: 6000,
  pruning_strategy: :hybrid,
  async_operations: true
)

# Development configuration
development_memory = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::FileStore.new(directory: './tmp/conversations'),
  max_tokens: 4000,
  pruning_strategy: :sliding_window,
  debug_mode: true
)

# Production configuration
production_memory = RAAF::Memory::MemoryManager.new(
  store: RAAF::Memory::DatabaseStore.new(
    model: ConversationMemory,
    connection_pool: true
  ),
  max_tokens: 8000,
  pruning_strategy: :hybrid,
  encryption: true,
  compression: true,
  monitoring: true
)

monitored_memory = RAAF::Memory::MonitoredMemoryManager.new(
  store: store,
  monitoring_config: {
    track_token_usage: true,
    track_pruning_events: true,
    track_performance_metrics: true,
    alert_on_errors: true
  }
)

# Memory health check
health_status = monitored_memory.health_check
puts "Memory health: #{health_status[:status]}"
puts "Token usage: #{health_status[:token_usage_percent]}%"
puts "Average response time: #{health_status[:avg_response_time]}ms"