robot_lab 0.0.1 → 0.0.6

data/docs/architecture/state-management.md

@@ -1,37 +1,87 @@
-# State Management
+# Memory Management
 
-State in RobotLab tracks all data and history for a conversation or workflow.
+Memory in RobotLab is a reactive key-value store that provides persistent storage for runtime data, conversation history, and arbitrary user-defined values. It replaces the old `State` class with a unified system that supports both standalone robot usage and shared network execution.
 
-## State Structure
+## Memory Structure
 
-The `State` class holds:
+The `Memory` class holds:
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Hello!",           # Current user message
-  data: { user_id: "123" }     # Custom workflow data
+memory = RobotLab.create_memory(data: { user_id: "123" })
+
+memory.data        # StateProxy - custom key-value data with method-style access
+memory.results     # Array<RobotResult> - execution history
+memory.messages    # Array<Message> - conversation history
+memory.session_id  # String - optional persistence identifier
+memory.cache       # RubyLLM::SemanticCache - semantic caching module
+```
+
+## Standalone Robot Memory
+
+Every robot has its own inherent memory instance, accessible via `robot.memory`:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful."
 )
 
-state.data        # StateProxy - custom key-value data
-state.results     # Array<RobotResult> - execution history
-state.messages    # Array<Message> - formatted conversation
-state.thread_id   # String - optional persistence ID
-state.memory      # Memory - shared key-value store
+# Access the robot's memory
+robot.memory[:user_name] = "Alice"
+robot.memory[:user_name]  #=> "Alice"
+
+# Run the robot
+result = robot.run("Hello!")
+
+# Memory persists between runs on the same robot instance
+robot.memory[:preference] = "dark_mode"
+result2 = robot.run("What are my preferences?")
+
+# Reset memory to initial state
+robot.reset_memory
+```
+
+## Network Shared Memory
+
+When robots execute within a network, they share the network's memory instead of using their own inherent memory. This enables inter-robot communication.
+
+```ruby
+classifier = RobotLab.build(name: "classifier", system_prompt: "Classify requests.")
+handler = RobotLab.build(name: "handler", system_prompt: "Handle requests.")
+
+network = RobotLab.create_network(name: "support") do
+  task :classifier, classifier, depends_on: :none
+  task :handler, handler, depends_on: [:classifier]
+end
+
+# The network has its own shared memory
+network.memory[:customer_tier] = "premium"
+
+# All robots in the network read/write from network.memory during execution
+result = network.run(message: "I need help with billing")
+
+# Reset network memory between runs if needed
+network.reset_memory
 ```
 
-## Creating State
+The memory resolution logic is:
+
+1. If `network_memory` is provided at runtime, use that
+2. If the robot is in a network, use the network's shared memory
+3. Otherwise, use the robot's own inherent memory (`robot.memory`)
+
+## Creating Memory
 
 ### Basic Creation
 
 ```ruby
-state = RobotLab.create_state(message: "What's the weather?")
+memory = RobotLab.create_memory
 ```
 
-### With Custom Data
+### With Initial Data
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Process my order",
+memory = RobotLab.create_memory(
   data: {
     user_id: "user_123",
     order_id: "ord_456",
@@ -40,284 +90,302 @@ state = RobotLab.create_state(
 )
 ```
 
-### From Existing Results
+### With Caching Disabled
 
 ```ruby
-state = RobotLab.create_state(
-  message: "Continue our conversation",
-  results: previous_results,
-  thread_id: "thread_abc"
-)
+memory = RobotLab.create_memory(data: {}, enable_cache: false)
 ```
 
-## StateProxy
-
-The `data` attribute is a `StateProxy` that provides convenient access:
-
-```ruby
-state.data[:user_id]          # Hash-style access
-state.data[:user_id] = "456"  # Assignment
-
-state.data.user_id            # Method-style access
-state.data.user_id = "456"    # Method-style assignment
+## Reserved Keys
 
-state.data.key?(:user_id)     # Check existence
-state.data.keys               # Get all keys
-state.data.to_h               # Convert to plain hash
-```
+Memory has five reserved keys with special behavior and dedicated accessors:
 
-### Change Tracking
+| Key | Type | Description |
+|-----|------|-------------|
+| `:data` | `StateProxy` | Runtime data with method-style access |
+| `:results` | `Array<RobotResult>` | Accumulated robot execution results |
+| `:messages` | `Array<Message>` | Conversation history |
+| `:session_id` | `String` | Conversation session identifier |
+| `:cache` | `RubyLLM::SemanticCache` | Semantic cache module (read-only after init) |
 
-StateProxy can track changes:
+Reserved keys are accessed through dedicated methods and are excluded from `memory.keys`:
 
 ```ruby
-state = State.new(
-  data: { count: 0 },
-  on_change: ->(key, old_val, new_val) {
-    puts "#{key}: #{old_val} -> #{new_val}"
-  }
-)
+memory.data[:category] = "billing"
+memory.data.category  #=> "billing"   (method-style via StateProxy)
 
-state.data[:count] = 1  # Prints: "count: 0 -> 1"
+memory.results       #=> []
+memory.session_id    #=> nil
+memory.cache         #=> RubyLLM::SemanticCache
 ```
 
-## Memory
+## StateProxy
 
-Memory provides a shared key-value store across robots:
+The `data` attribute is a `StateProxy` that provides convenient hash-style and method-style access:
 
 ```ruby
-# Store values
-state.memory.remember("user_name", "Alice")
-state.memory.remember("preferences", { theme: "dark" })
+memory.data[:user_id]          # Hash-style access
+memory.data[:user_id] = "456"  # Assignment
 
-# Retrieve values
-name = state.memory.recall("user_name")  # => "Alice"
+memory.data.user_id            # Method-style access
+memory.data.user_id = "456"    # Method-style assignment
 
-# Check existence
-state.memory.exists?("user_name")  # => true
+memory.data.key?(:user_id)     # Check existence
+memory.data.keys               # Get all keys
+memory.data.to_h               # Convert to plain hash
+```
 
-# Remove values
-state.memory.forget("user_name")
+## Reactive Features
 
-# List all
-state.memory.all  # => { "user_name" => "Alice", ... }
-```
+Memory supports pub/sub semantics where robots can subscribe to key changes and optionally block until values become available.
 
-### Scoped Memory
+### Setting Values
 
-Organize memory with namespaces:
+Use `memory.set(key, value)` to write a value and notify subscribers asynchronously:
 
 ```ruby
-# Create scoped view
-user_memory = state.memory.scoped("user:123")
-user_memory.remember("last_login", Time.now)
+memory.set(:sentiment, { score: 0.8, confidence: 0.95 })
+```
 
-# Access scoped data
-user_memory.recall("last_login")
+The `[]=` operator also triggers reactive notifications for non-reserved keys:
 
-# Full key is "user:123:last_login"
-state.memory.recall("user:123:last_login")
+```ruby
+memory[:sentiment] = { score: 0.8 }  # Equivalent to memory.set(:sentiment, ...)
 ```
 
-### Shared Memory
+### Blocking Reads
 
-Use the `SHARED` namespace for cross-robot data:
+Use `memory.get(key, wait:)` to block until a value becomes available. This is useful for concurrent pipeline execution where one robot needs to wait for another's output:
 
 ```ruby
-# In first robot
-state.memory.remember("SHARED:context", important_data)
+# Immediate read (returns nil if missing)
+memory.get(:sentiment)
+
+# Block indefinitely until value exists
+memory.get(:sentiment, wait: true)
+
+# Block up to 30 seconds, raise AwaitTimeout if exceeded
+memory.get(:sentiment, wait: 30)
 
-# In second robot (same or different network run)
-data = state.memory.recall("SHARED:context")
+# Wait for multiple keys at once
+results = memory.get(:sentiment, :entities, :keywords, wait: 60)
+#=> { sentiment: {...}, entities: [...], keywords: [...] }
 ```
 
-### Memory Operations
+### Subscriptions
+
+Subscribe to key changes with async callbacks. The callback receives a `MemoryChange` object:
 
 ```ruby
-# Search by pattern
-matches = state.memory.search("user:*")
+memory.subscribe(:raw_data) do |change|
+  puts "#{change.key} changed from #{change.previous} to #{change.value}"
+  puts "Written by: #{change.writer} at #{change.timestamp}"
+end
+
+# Subscribe to multiple keys
+memory.subscribe(:sentiment, :entities) do |change|
+  update_dashboard(change.key, change.value)
+end
+
+# Pattern-based subscriptions (glob-style matching)
+memory.subscribe_pattern("analysis:*") do |change|
+  puts "Analysis key #{change.key} updated"
+end
+
+# Unsubscribe
+sub_id = memory.subscribe(:status) { |c| puts c.value }
+memory.unsubscribe(sub_id)
+
+# Check if key has subscribers
+memory.subscribed?(:status)  #=> true/false
+```
 
-# Get statistics
-state.memory.stats
-# => { total_keys: 15, namespaces: ["user", "session"] }
+### MemoryChange
 
-# Clear namespace
-state.memory.scoped("temp").clear
+The `MemoryChange` object provides context about what changed:
 
-# Clear everything
-state.memory.clear_all
+```ruby
+change.key           #=> :sentiment
+change.value         #=> { score: 0.8 }
+change.previous      #=> nil (or previous value)
+change.writer        #=> "classifier" (robot name)
+change.network_name  #=> "support_pipeline"
+change.timestamp     #=> Time
+change.created?      #=> true (new key, no previous value)
+change.updated?      #=> false
+change.deleted?      #=> false
 ```
 
-## Results
+## Memory Lifecycle
+
+### Results
 
 Results track the history of robot executions:
 
 ```ruby
 # Append a result
-state.append_result(robot_result)
+memory.append_result(robot_result)
 
-# Get all results
-state.results
+# Get all results (returns a copy)
+memory.results
 
-# Get results from index
-state.results_from(5)  # Results starting at index 5
-
-# Format for LLM conversation
-state.format_history
+# Get results from a specific index (for incremental persistence)
+memory.results_from(5)
 ```
 
-### Result History
-
 Each `RobotResult` contains:
 
 ```ruby
-result.robot_name   # Which robot produced this
-result.output       # Array<Message> - response content
-result.tool_calls   # Array<ToolMessage> - tools called
-result.stop_reason  # "stop", "tool", etc.
-result.created_at   # When it was created
+result.robot_name       # Which robot produced this
+result.output           # Array<Message> - response content
+result.tool_calls       # Array<ToolResultMessage> - tools called
+result.stop_reason      # Stop reason from LLM
+result.last_text_content # Convenience: last text content string
+result.has_tool_calls?  # Whether any tools were called
+result.created_at       # When it was created
 ```
 
-## Messages
+### Format History
 
-The `messages` method formats state for LLM consumption:
+The `format_history` method prepares messages for LLM consumption:
 
 ```ruby
-messages = state.messages
-
-# Returns Array<Message> with:
-# - System message (if present)
-# - Alternating user/assistant messages
-# - Tool calls and results
+formatted = memory.format_history
+# Returns combined messages + formatted results
 ```
 
-## Thread ID
+### Merge
 
-For persistent conversations:
+Merge additional values into memory:
 
 ```ruby
-# Set thread ID
-state.thread_id = "thread_123"
+memory.merge!(user_id: 123, category: "billing")
+```
 
-# Or via UserMessage
-message = UserMessage.new(
-  "Continue",
-  thread_id: "thread_123"
-)
-state = RobotLab.create_state(message: message)
+### Key Management
+
+```ruby
+memory.key?(:user_id)      # Check existence
+memory.keys                 # Get all non-reserved keys
+memory.all_keys             # Get all keys including reserved
+memory.delete(:temp_data)   # Delete a specific key
+memory.clear                # Clear all non-reserved keys
+memory.reset                # Reset to initial state (preserves cache)
 ```
 
-## State Cloning
+## Cloning
 
-Create independent copies:
+Create independent copies of memory for isolated execution. Subscriptions are not cloned:
 
 ```ruby
-original = RobotLab.create_state(data: { count: 1 })
-clone = original.clone
+original = RobotLab.create_memory(data: { count: 1 })
+cloned = original.clone
 
-clone.data[:count] = 2
-original.data[:count]  # Still 1
+cloned[:count] = 2
+original[:count]  #=> still 1
 ```
 
 ## Serialization
 
-Convert state to/from hash:
+Convert memory to and from hash for persistence:
 
 ```ruby
 # To hash
-hash = state.to_h
-json = state.to_json
+hash = memory.to_h
+#=> {
+#     data: { ... },
+#     results: [...],
+#     messages: [...],
+#     session_id: "abc123",
+#     custom: { my_key: "value" }
+#   }
+
+# To JSON
+json = memory.to_json
 
 # From hash
-state = State.from_hash(hash)
+memory = Memory.from_hash(hash)
 ```
 
-### Hash Structure
+## Semantic Cache
+
+Memory includes a semantic cache via `RubyLLM::SemanticCache` that reduces costs and latency by returning cached responses for semantically equivalent queries:
 
 ```ruby
-{
-  data: { ... },
-  results: [
-    {
-      robot_name: "assistant",
-      output: [...],
-      tool_calls: [...],
-      stop_reason: "stop"
-    }
-  ],
-  thread_id: "thread_123"
-}
+# Using the cache with fetch
+response = memory.cache.fetch("What is Ruby?") do
+  RubyLLM.chat.ask("What is Ruby?")
+end
+
+# Wrapping a chat instance
+chat = memory.cache.wrap(RubyLLM.chat(model: "gpt-4o"))
+chat.ask("What is Ruby?")  # Cached on semantic similarity
 ```
 
-## UserMessage
+Caching can be disabled per-memory or per-robot:
 
-Enhanced message with metadata:
+```ruby
+memory = RobotLab.create_memory(enable_cache: false)
+robot = RobotLab.build(name: "bot", system_prompt: "...", enable_cache: false)
+```
+
+## Backend Options
+
+Memory defaults to a Hash-based backend but can use Redis for distributed scenarios:
 
 ```ruby
-message = UserMessage.new(
-  "What's the status of my order?",
-  thread_id: "thread_123",
-  system_prompt: "Respond in Spanish",  # Augment system prompt
-  metadata: {
-    user_id: "user_456",
-    source: "web_chat"
-  }
-)
+# Auto-detect (uses Redis if available, falls back to Hash)
+memory = Memory.new(backend: :auto)
 
-state = RobotLab.create_state(message: message)
-```
+# Force Hash backend
+memory = Memory.new(backend: :hash)
 
-### UserMessage Properties
+# Force Redis backend
+memory = Memory.new(backend: :redis)
 
-| Property | Description |
-|----------|-------------|
-| `content` | The message text |
-| `thread_id` | Conversation thread ID |
-| `system_prompt` | Additional system instructions |
-| `metadata` | Custom key-value data |
-| `id` | Unique message identifier |
-| `created_at` | Timestamp |
+# Check backend
+memory.redis?  #=> true/false
+```
+
+Redis is configured via `RobotLab.config.redis` or the `REDIS_URL` environment variable.
 
 ## Best Practices
 
 ### 1. Use Memory for Cross-Robot Data
 
 ```ruby
-# Don't pass data through routing
-router = ->(args) {
-  # Bad: parsing previous output for data
-}
-
-# Do: use memory
-state.memory.remember("classification", "billing")
-# Later robot reads it directly
+# In a network, robots share memory automatically.
+# Robot A writes:
+memory.set(:classification, "billing")
+
+# Robot B reads:
+category = memory.get(:classification)
 ```
 
-### 2. Scope Memory Appropriately
+### 2. Use Blocking Reads for Concurrent Pipelines
 
 ```ruby
-# Session data
-session = state.memory.scoped("session:#{session_id}")
-
-# User preferences
-user = state.memory.scoped("user:#{user_id}")
-
-# Temporary working data
-temp = state.memory.scoped("temp")
+# When robots run in parallel, use blocking reads
+# to synchronize on shared data:
+results = memory.get(:sentiment, :entities, wait: 60)
 ```
 
 ### 3. Keep Data Minimal
 
 ```ruby
-# Don't store large objects
-state.data[:huge_response] = api_response  # Bad
+# Store references instead of large objects
+memory[:response_id] = response.id    # Preferred
+# memory[:huge_response] = api_response  # Avoid
+```
+
+### 4. Reset Between Independent Runs
 
-# Store references instead
-state.data[:response_id] = response.id  # Good
+```ruby
+network.reset_memory
+result = network.run(message: "New conversation")
 ```
 
 ## Next Steps
 
-- [Memory System](../guides/memory.md) - Advanced memory patterns
-- [History Guide](../guides/history.md) - Persisting state
+- [Network Orchestration](network-orchestration.md) - How networks share memory
 - [Message Flow](message-flow.md) - How messages are processed