robot_lab 0.0.1 → 0.0.6

data/docs/guides/memory.md

@@ -1,259 +1,315 @@
 # Memory System
 
-The memory system allows robots to share data within a network run.
+The memory system provides key-value storage for robots, supporting both standalone and network execution modes.
 
 ## Overview
 
-Memory provides:
+Memory is a reactive key-value store that provides:
 
-- Key-value storage accessible by all robots
-- Namespaced scopes for organization
-- Persistence within a single network run
+- Key-value storage with `[]` and `[]=` accessors
+- Reserved keys for structured data (`:data`, `:results`, `:messages`, `:session_id`, `:cache`)
+- Reactive subscriptions and blocking reads for inter-robot communication
+- Optional Redis backend for persistence
+- Semantic caching via `RubyLLM::SemanticCache`
 
-## Basic Usage
+## Standalone Robot Memory
+
+Every robot has its own inherent memory that persists across runs:
+
+```ruby
+robot = RobotLab.build(
+  name: "assistant",
+  system_prompt: "You are helpful."
+)
+
+# Memory persists across runs
+robot.memory[:user_name] = "Alice"
+robot.memory[:preferences] = { theme: "dark", language: "en" }
+
+result = robot.run("Hello!")
+
+# Read it back later
+robot.memory[:user_name]      # => "Alice"
+robot.memory[:preferences]    # => { theme: "dark", language: "en" }
+```
+
+## Basic Operations
 
 ### Store Values
 
 ```ruby
-state.memory.remember("user_name", "Alice")
-state.memory.remember("preferences", { theme: "dark", language: "en" })
+robot.memory[:key] = "value"
+robot.memory[:count] = 42
+robot.memory[:config] = { timeout: 30, retries: 3 }
 ```
 
 ### Retrieve Values
 
 ```ruby
-name = state.memory.recall("user_name")  # => "Alice"
-prefs = state.memory.recall("preferences")  # => { theme: "dark", ... }
-
-# Returns nil if not found
-missing = state.memory.recall("unknown")  # => nil
+name = robot.memory[:user_name]    # => "Alice"
+missing = robot.memory[:unknown]   # => nil
 ```
 
 ### Check Existence
 
 ```ruby
-state.memory.exists?("user_name")  # => true
-state.memory.exists?("unknown")    # => false
+robot.memory.key?(:user_name)   # => true
+robot.memory.key?(:unknown)     # => false
 ```
 
-### Remove Values
+### Delete Values
 
 ```ruby
-state.memory.forget("user_name")
+robot.memory.delete(:temp_data)
 ```
 
-## Scoped Memory
+### List Keys
 
-Organize data with namespaces:
+```ruby
+robot.memory.keys      # => [:user_name, :preferences] (excludes reserved keys)
+robot.memory.all_keys  # => [:data, :results, :messages, :session_id, :cache, :user_name, ...]
+```
+
+### Merge Values
 
 ```ruby
-# Create a scoped view
-user_memory = state.memory.scoped("user:123")
+robot.memory.merge!(user_id: 123, session: "abc")
+```
+
+## Reserved Keys
 
-# Operations are scoped
-user_memory.remember("name", "Alice")
-user_memory.remember("email", "alice@example.com")
+Memory has reserved keys with special behavior:
 
-# Keys are prefixed
-state.memory.recall("user:123:name")  # => "Alice"
+| Key | Type | Description |
+|-----|------|-------------|
+| `:data` | Hash (StateProxy) | Runtime data with method-style access |
+| `:results` | Array | Accumulated robot results |
+| `:messages` | Array | Conversation history |
+| `:session_id` | String | Session identifier for history persistence |
+| `:cache` | SemanticCache | Semantic cache (read-only after init) |
 
-# Scoped recall
-user_memory.recall("name")  # => "Alice"
+### The Data Hash
+
+The `:data` key provides a `StateProxy` for method-style access:
+
+```ruby
+robot.memory.data[:category] = "billing"
+robot.memory.data.category    # => "billing" (method-style access)
+robot.memory.data.to_h        # => { category: "billing" }
+```
+
+### Results and Messages
+
+```ruby
+robot.memory.results    # => Array of RobotResult objects
+robot.memory.messages   # => Array of Message objects
+robot.memory.session_id # => "abc123" or nil
 ```
 
-### Nested Scopes
+## Runtime Memory Injection
+
+Pass memory values for a single run using the `memory:` keyword:
 
 ```ruby
-session = state.memory.scoped("session:abc")
-prefs = session.scoped("preferences")
+# Inject a hash -- values are merged into the active memory
+result = robot.run("What's my order status?", memory: { user_id: 123, order_id: "ORD-456" })
 
-prefs.remember("theme", "dark")
-# Full key: "session:abc:preferences:theme"
+# The robot's memory now contains those keys
+robot.memory[:user_id]    # => 123
+robot.memory[:order_id]   # => "ORD-456"
 ```
 
-## Memory Operations
+You can also pass a full `Memory` object to replace the active memory for that run:
+
+```ruby
+custom_memory = RobotLab.create_memory(data: { user_id: 123 })
+custom_memory[:context] = "billing inquiry"
 
-### List All Keys
+result = robot.run("Help me", memory: custom_memory)
+```
+
+## Resetting Memory
+
+Clear a robot's memory back to its initial state:
 
 ```ruby
-state.memory.all
-# => {
-#   "user_name" => "Alice",
-#   "user:123:email" => "alice@example.com",
-#   ...
-# }
+robot.reset_memory
+robot.memory.keys  # => [] (custom keys cleared, reserved keys reset)
 ```
 
-### List Namespaces
+You can also clear just the custom keys without resetting reserved keys:
 
 ```ruby
-state.memory.namespaces
-# => ["user:123", "session:abc", ...]
+robot.memory.clear  # Clears non-reserved keys only
 ```
 
-### Search by Pattern
+## Network Shared Memory
+
+When robots run in a network, they share the network's memory instead of using their own inherent memory. This allows robots to communicate through shared state:
 
 ```ruby
-# Find keys matching pattern
-matches = state.memory.search("user:*")
-# => { "user:123:name" => "Alice", "user:123:email" => "..." }
+network = RobotLab.create_network(name: "pipeline") do
+  task :analyzer, analyzer_robot, depends_on: :none
+  task :writer, writer_robot, depends_on: [:analyzer]
+end
+
+# All robots in the network share this memory
+network.memory[:project] = "quarterly_report"
+
+result = network.run(message: "Analyze sales data")
+
+# After the run, shared memory contains values written by all robots
+network.memory[:analysis_result]  # Written by analyzer
+network.memory[:draft]            # Written by writer
 ```
 
-### Statistics
+### Resetting Network Memory
 
 ```ruby
-state.memory.stats
-# => { total_keys: 15, namespaces: ["user:123", "session"] }
+network.reset_memory  # Clear shared memory between runs
 ```
 
-### Clear Memory
+## Reactive Memory
+
+Memory supports reactive features for concurrent robot execution.
+
+### Blocking Reads
+
+Wait for a value to become available (useful in parallel pipelines):
 
 ```ruby
-# Clear a namespace
-state.memory.scoped("temp").clear
+# In robot A (writer)
+memory.set(:sentiment, { score: 0.8, confidence: 0.95 })
+
+# In robot B (reader, may run concurrently)
+result = memory.get(:sentiment, wait: true)    # Blocks until available
+result = memory.get(:sentiment, wait: 30)      # Blocks up to 30 seconds
 
-# Clear all memory
-state.memory.clear_all
+# Multiple keys
+results = memory.get(:sentiment, :entities, :keywords, wait: 60)
+# => { sentiment: {...}, entities: [...], keywords: [...] }
 ```
 
-## Shared Namespace
+### Subscriptions
 
-The `SHARED` namespace is a convention for cross-robot data:
+Subscribe to key changes with asynchronous callbacks:
 
 ```ruby
-# In first robot
-state.memory.remember("SHARED:context", important_data)
+# Subscribe to a single key
+memory.subscribe(:raw_data) do |change|
+  puts "#{change.key} changed by #{change.writer}"
+  puts "Old: #{change.previous}, New: #{change.value}"
+end
+
+# Subscribe to multiple keys
+memory.subscribe(:sentiment, :entities) do |change|
+  update_dashboard(change.key, change.value)
+end
 
-# In later robot
-context = state.memory.recall("SHARED:context")
+# Pattern subscriptions (glob-style)
+memory.subscribe_pattern("analysis:*") do |change|
+  puts "Analysis key #{change.key} updated"
+end
 ```
 
-### Using Shared Scope
+### Unsubscribe
 
 ```ruby
-shared = state.memory.scoped(RobotLab::Memory::SHARED_NAMESPACE)
-shared.remember("workflow_status", "in_progress")
+sub_id = memory.subscribe(:status) { |c| puts c.value }
+memory.unsubscribe(sub_id)
 ```
 
-## In Tool Handlers
+## Creating Standalone Memory
 
-Access memory from tools:
+Use the factory method for standalone memory objects:
 
 ```ruby
-tool :update_preference do
-  description "Update user preference"
-  parameter :key, type: :string, required: true
-  parameter :value, type: :string, required: true
-
-  handler do |key:, value:, state:, **_|
-    prefs = state.memory.scoped("preferences")
-    prefs.remember(key, value)
-    { success: true, key: key, value: value }
-  end
-end
+memory = RobotLab.create_memory(
+  data: { user_id: 123, category: nil },
+  enable_cache: true
+)
+
+memory[:session_id] = "abc123"
+memory[:custom_key] = "custom_value"
 ```
 
-## In Routers
+## Serialization
 
-Use memory for routing decisions:
+Memory can be exported and reconstructed:
 
 ```ruby
-router = ->(args) {
-  case args.call_count
-  when 0
-    :classifier
-  when 1
-    # Read classification from memory
-    intent = args.network.state.memory.recall("SHARED:intent")
-    case intent
-    when "billing" then :billing_agent
-    when "technical" then :tech_agent
-    else :general_agent
-    end
-  else
-    nil
-  end
-}
+# Export to hash
+hash = robot.memory.to_h
+# => { data: {...}, results: [...], messages: [...], session_id: "...", custom: {...} }
+
+# Export to JSON
+json = robot.memory.to_json
+
+# Reconstruct from hash
+restored = RobotLab::Memory.from_hash(hash)
 ```
 
 ## Patterns
 
-### Accumulating Data
+### Accumulating Data Across Robots
 
 ```ruby
-# In each robot
-def add_finding(state, finding)
-  findings = state.memory.recall("findings") || []
+# In each robot's processing
+def accumulate_finding(memory, finding)
+  findings = memory[:findings] || []
   findings << finding
-  state.memory.remember("findings", findings)
+  memory[:findings] = findings
 end
 
-# In final robot
-all_findings = state.memory.recall("findings")
+# In the final robot
+all_findings = memory[:findings]
 ```
 
 ### Tracking Progress
 
 ```ruby
-# Track workflow stages
-state.memory.remember("stage", "intake")
+memory[:stage] = "intake"
 # ... processing ...
-state.memory.remember("stage", "analysis")
+memory[:stage] = "analysis"
 # ... processing ...
-state.memory.remember("stage", "response")
+memory[:stage] = "response"
 ```
 
 ### Caching Expensive Operations
 
 ```ruby
-tool :fetch_user do
-  handler do |user_id:, state:, **_|
+class FetchUser < RubyLLM::Tool
+  description "Fetch user details by ID"
+  param :user_id, type: :string, desc: "User ID"
+
+  def execute(user_id:)
     cache_key = "cache:user:#{user_id}"
 
-    # Check cache
-    cached = state.memory.recall(cache_key)
+    # Check robot's memory for cached value
+    # (In practice, you'd access memory through the robot's context)
+    cached = Thread.current[:robot_memory]&.[](cache_key.to_sym)
     return cached if cached
 
     # Fetch and cache
     user = User.find(user_id).to_h
-    state.memory.remember(cache_key, user)
+    Thread.current[:robot_memory]&.[]=(cache_key.to_sym, user)
     user
   end
 end
 ```
 
-### User Session Data
-
-```ruby
-# Store session data
-session = state.memory.scoped("session:#{session_id}")
-session.remember("started_at", Time.now.iso8601)
-session.remember("page_views", 0)
-
-# Update during conversation
-views = session.recall("page_views") || 0
-session.remember("page_views", views + 1)
-```
-
-## Memory vs State.data
+### Semantic Caching
 
-| Feature | Memory | State.data |
-|---------|--------|------------|
-| Purpose | Robot-to-robot sharing | Input/output data |
-| Scope | Namespaced | Flat hash |
-| Typical Use | Intermediate results | User input, workflow config |
-| Persistence | Within run | Can be serialized |
+Memory includes a semantic cache for LLM response caching:
 
 ```ruby
-# Use state.data for input configuration
-state = RobotLab.create_state(
-  message: "Process order",
-  data: { order_id: "123", priority: "high" }
-)
+# Access the semantic cache
+cache = robot.memory.cache  # => RubyLLM::SemanticCache
 
-# Use memory for intermediate findings
-state.memory.remember("validation_result", { valid: true })
-state.memory.remember("processing_steps", ["validated", "charged"])
+# Use it to cache semantically similar queries
+response = cache.fetch("What is Ruby?") do
+  robot.run("What is Ruby?")
+end
 ```
 
 ## Best Practices
@@ -262,48 +318,48 @@ state.memory.remember("processing_steps", ["validated", "charged"])
 
 ```ruby
 # Good
-state.memory.remember("classification:intent", "billing")
-state.memory.remember("user:123:last_order_id", "ord_456")
+robot.memory[:classification_intent] = "billing"
+robot.memory[:user_last_order_id] = "ord_456"
 
 # Bad
-state.memory.remember("x", "billing")
-state.memory.remember("temp1", "ord_456")
+robot.memory[:x] = "billing"
+robot.memory[:temp1] = "ord_456"
 ```
 
-### 2. Scope Related Data
+### 2. Use Data Hash for Structured Runtime Input
 
 ```ruby
-# Good
-user = state.memory.scoped("user:#{user_id}")
-user.remember("name", name)
-user.remember("email", email)
-user.remember("plan", plan)
-
-# Less organized
-state.memory.remember("user_name", name)
-state.memory.remember("user_email", email)
-state.memory.remember("user_plan", plan)
+memory = RobotLab.create_memory(
+  data: { order_id: "123", priority: "high", customer_tier: "gold" }
+)
+
+# Access via data proxy
+memory.data.order_id       # => "123"
+memory.data.priority       # => "high"
+memory.data.customer_tier  # => "gold"
 ```
 
-### 3. Clean Up Temporary Data
+### 3. Clean Up Temporary Values
 
 ```ruby
-# At end of processing
-state.memory.scoped("temp").clear
+# After processing is done
+robot.memory.delete(:temp_calculation)
+robot.memory.delete(:intermediate_result)
 ```
 
 ### 4. Document Memory Keys
 
 ```ruby
-# In your robot definitions, document expected keys
-# Memory keys used:
-# - SHARED:intent - Classification result
-# - SHARED:entities - Extracted entities
-# - user:{id}:* - User-specific data
+# In your robot definitions, document expected keys:
+#
+# Memory keys used by this pipeline:
+# - :intent       - Classification result (set by classifier)
+# - :entities     - Extracted entities (set by entity_extractor)
+# - :response     - Final response draft (set by responder)
 ```
 
 ## Next Steps
 
-- [State Management](../architecture/state-management.md) - Full state details
 - [Building Robots](building-robots.md) - Using memory in robots
+- [Creating Networks](creating-networks.md) - Shared memory in networks
 - [API Reference: Memory](../api/core/memory.md) - Complete API