robot_lab 0.2.6 → 0.2.7

data/docs/architecture/robot-execution.md

@@ -9,66 +9,95 @@ When you call `robot.run("message")`, several steps occur:
 ```mermaid
 sequenceDiagram
     participant App as Application
-    participant Robot
+    participant Skills as AgentSkillMatching<br/>(prepended)
+    participant Robot as Robot (Hooking run)
+    participant Hooks as Hooks / HookRegistry
     participant Memory
+    participant Ledger as Budget::Ledger
     participant Chat as @chat (RubyLLM)
     participant LLM
 
-    App->>Robot: run("message")
-    Robot->>Memory: resolve_active_memory()
-    Robot->>Robot: resolve_mcp_hierarchy()
-    Robot->>Robot: resolve_tools_hierarchy()
-    Robot->>Robot: ensure_mcp_clients()
-    Robot->>Robot: filtered_tools()
-    Robot->>Chat: with_tools(*filtered)
-    Robot->>Chat: ask("message")
+    App->>Skills: run("message")
+    Skills->>Skills: match_agent_skills + inject (prompt & script tools)
+    Skills->>Robot: super
+
+    Robot->>Memory: resolve_run_memory()
+    Robot->>Memory: current_writer = name
+    Robot->>Hooks: Hooks.run(:run, RunHookContext)
+    Note over Hooks: before_run / around_run wrap everything below
+
+    Robot->>Robot: prepare_tools() — resolve_mcp_hierarchy,<br/>ensure_mcp_clients, resolve_tools_hierarchy,<br/>filtered_tools + cap_tools
+    Robot->>Chat: with_tools(*filtered, replace: true)
+    Robot->>Robot: rerender_template(kwargs) — when template + extra kwargs
+    Robot->>Ledger: reserve_budget! (raises BudgetExceeded if exhausted)
+
+    Robot->>Hooks: Hooks.run(:llm_generation, LlmGenerationHookContext)
+    Robot->>Robot: inject_learnings(request)
+    Robot->>Robot: maybe_compact — fires :compaction family
+    Robot->>Chat: install_circuit_breaker (when max_tool_rounds)
+    Robot->>Chat: install_doom_loop_detection (always)
+    Robot->>Chat: ask(message, &streaming_block)
     Chat->>LLM: API Request
 
-    loop Tool Calls
+    loop Tool loop (inside :llm_generation)
         LLM-->>Chat: tool_call response
-        Chat->>Chat: execute tool
+        Chat->>Hooks: Tool.call — Hooks.run(:tool_call)
         Chat->>LLM: tool result
     end
 
     LLM-->>Chat: final response
     Chat-->>Robot: RubyLLM::Response
-    Robot->>Robot: build_result(response)
-    Robot-->>App: RobotResult
+    Robot->>Robot: build_result(response) — result_text + token accounting
+    Robot->>Ledger: reconcile_budget!
+    Robot->>Robot: enforce_token_budget! / enforce_cost_budget!<br/>(raise InferenceError on overage)
+    Robot->>Hooks: after_run
+    Note over Robot,Memory: ensure: remove_doom_loop_detection,<br/>restore_tool_call_callback, restore current_writer
+    Robot-->>Skills: RobotResult
+    Skills->>Skills: ensure: restore_after_agent_skills
+    Skills-->>App: RobotResult
 ```
 
+The steps are described individually below. Two things this diagram makes
+explicit that the prose repeats: `Robot::AgentSkillMatching` is **prepended**, so
+its `run` wraps `Robot::Hooking#run` (which is the `run` everything else calls);
+and the `:llm_generation` family wraps the provider's *entire* tool loop, so
+`:tool_call` hooks fire nested inside it rather than between generations.
+
 ## Step-by-Step Flow
 
 ### 1. Memory Resolution
 
-The robot determines which memory to use for this run:
+`Robot#run` first resolves the memory this run will write to, via `resolve_run_memory`:
 
 ```ruby
-# Priority order:
+# resolve_active_memory priority order:
 # 1. Explicit network_memory: parameter
 # 2. Network's memory (if running in a network)
 # 3. Robot's inherent @memory (standalone mode)
 run_memory = resolve_active_memory(network: network, network_memory: network_memory)
 
-# Merge runtime memory if provided
+# A runtime memory: kwarg either replaces (Memory) or merges into (Hash) it
 case memory
-when Memory then run_memory = memory
-when Hash   then run_memory.merge!(memory)
+when Memory then memory
+when Hash   then run_memory.tap { |m| m.merge!(memory) }
+else             run_memory
 end
-
-# Track who is writing to memory
-run_memory.current_writer = @name
 ```
 
+`run` then sets `run_memory.current_writer = @name` for the duration of the run and restores the previous writer in an `ensure` block, so subscription callbacks always see the robot that actually wrote a value.
+
+The whole run body is wrapped in `RobotLab::Hooks.run(:run, context, ...)` against the registries `[RobotLab.hooks, network&.hooks, @hooks]`.
+
 ### 2. MCP Hierarchy Resolution
 
-MCP servers are resolved through a hierarchy: **runtime > robot build-time > network > global config**.
+MCP servers and tools are resolved together in `prepare_tools`, through a hierarchy: **runtime (run/task) > robot build-time > network > global config**.
 
 ```ruby
-# Resolve build-time config against network/global
-parent_value = network&.network&.mcp || RobotLab.config.mcp
+# Parent value: task/network RunConfig, then the network object, then global config
+parent_value = network_config&.mcp || network_parent_config(network)&.mcp || RobotLab.config.mcp
 build_resolved = ToolConfig.resolve_mcp(@mcp_config, parent_value: parent_value)
 
-# Then resolve runtime override against build-time
+# Then resolve the runtime override against the build-time value
 resolved_mcp = ToolConfig.resolve_mcp(runtime_mcp, parent_value: build_resolved)
 ```
 
@@ -78,50 +107,66 @@ Values at each level:
 - `:inherit` -- use parent level's MCP config
 - `Array` -- explicit list of server configurations
 
+`run`'s default for `mcp:` is `:none`, so a plain `robot.run("...")` resolves to an empty server list and connects nothing, even when `mcp:` was supplied at build time. Pass `mcp: :inherit` to trigger the connection. (`robot.connect_mcp!` connects eagerly against the build-time config, which is useful for reporting connection status at startup.)
+
 ### 3. MCP Client Initialization
 
 If MCP servers need to be connected (or reconnected), the robot initializes clients:
 
 ```ruby
-# Connect to each MCP server
-mcp_servers.each do |server_config|
-  client = MCP::Client.new(server_config)
-  client.connect
-
-  if client.connected?
-    @mcp_clients[client.server.name] = client
-    discover_mcp_tools(client, server_name)  # Auto-discover tools
-  end
+# Connect to each MCP server (ensure_mcp_clients -> init_mcp_client)
+client = MCP::Client.new(server_config)   # config is POSITIONAL
+client.connect
+
+if client.connected?
+  @mcp_clients[client.server.name] = client
+  discover_mcp_tools(client, server_name)  # each remote tool becomes a Tool.create wrapper
+else
+  @failed_mcp_configs[server_name] = server_config
 end
 ```
 
+Connection failures are logged and recorded, never raised — they surface through `robot.failed_mcp_server_names`. A later run retries only the servers that are still needed and still failed.
+
 ### 4. Tools Resolution
 
-Tools are resolved through the same hierarchy and filtered:
+Tools are resolved through the same hierarchy, filtered, capped, and applied to the chat:
 
 ```ruby
-# Collect all available tools
-available = @local_tools + @mcp_tools
-
-# Apply whitelist if specified
-filtered = ToolConfig.filter_tools(available, allowed_names: resolved_tools)
+# Explicit :none (or a literal []) means "send zero tools this turn"; otherwise
+# filter the local + MCP tools by the resolved allowlist and clamp to max_tools.
+filtered = explicit_none_tools?(tools) ? [] : cap_tools(filtered_tools(resolved_tools))
 
-# Apply tools to the persistent chat
-@chat.with_tools(*filtered) if filtered.any?
+@chat.with_tools(*filtered, replace: true) if filtered.any? || explicit_none_tools?(tools)
 ```
 
+Two details here are load-bearing:
+
+- **`replace: true`** — RubyLLM's `with_tools` appends by default. On a persistent chat that would let tools accumulate across turns, so the chat is made to hold exactly this turn's resolved set. An explicit `:none` therefore clears the chat's tools to zero.
+- **`cap_tools`** — the resolved list is clamped to `RunConfig#max_tools`, which defaults to `DEFAULT_MAX_TOOLS` (128) because most providers reject longer tool arrays. Setting `max_tools` to nil, 0, or a negative number falls back to 128; the cap cannot be disabled. Dropped tools are logged at `warn`.
+
+Because `run` defaults to `tools: :none`, a plain `robot.run("...")` sends the LLM no tools at all. Pass `tools: :inherit` to send the robot's attached tools; pass an explicit array of names to use it as an allowlist.
+
 ### 5. LLM Inference
 
-The message is sent to the LLM via `Agent#ask`, which delegates to `@chat.ask`:
+The message is sent to the LLM via `Agent#ask`, which delegates to `@chat.ask`. `invoke_ask` wraps that call in the `:llm_generation` hook and installs the per-run guards first:
 
 ```ruby
-# Robot#run calls Agent#ask
-response = ask(message, **kwargs)
-
-# Internally, Agent#ask calls:
-# @chat.ask(message)
+RobotLab::Hooks.run(:llm_generation, generation_context, registries: ..., per_run_hooks: hooks) do
+  effective_message = inject_learnings(generation_context.request)
+  maybe_compact(network: context.network)
+  install_circuit_breaker if @config.max_tool_rounds
+  install_doom_loop_detection
+  ask(effective_message, **kwargs.slice(:with), &effective_streaming_block(block))
+end
 ```
 
+Notes on the surrounding behavior:
+
+- `:llm_generation` fires **exactly once per `robot.run`** — the provider's tool loop happens inside the block, not once per API call.
+- Only `:with` from `run`'s keyword arguments reaches `ask`. Every other unrecognized keyword is treated as template re-render context.
+- Doom-loop detection is installed unconditionally on every run; `doom_loop_threshold:` (default 3) only tunes it.
+
 The persistent `@chat` (a `RubyLLM::Chat` instance) handles:
 
 - Maintaining conversation history
@@ -138,38 +183,41 @@ RubyLLM's `@chat` handles the tool loop automatically. When the LLM requests a t
 3. Sends the result back to the LLM
 4. Repeats until the LLM produces a final text response
 
-The `on_tool_call` and `on_tool_result` callbacks fire during this loop if configured:
+The `on_tool_call` and `on_tool_result` callbacks fire during this loop if configured. They are read off the effective `RunConfig` and registered on `@chat` during `Robot#initialize`:
 
 ```ruby
-# These callbacks are registered on @chat during Robot#initialize
-@chat.on_tool_call(&@on_tool_call) if @on_tool_call
-@chat.on_tool_result(&@on_tool_result) if @on_tool_result
+def register_chat_callbacks
+  @chat.on_tool_call(&@on_tool_call)     if @on_tool_call
+  @chat.on_tool_result(&@on_tool_result) if @on_tool_result
+  setup_bus_channel if @bus
+end
 ```
 
+When `max_tool_rounds` is set, `install_circuit_breaker` temporarily wraps `on_tool_call` for the duration of the run and raises `ToolLoopError` once the round count is exceeded; the original callback is restored in `run`'s `ensure` block.
+
 ### 7. Result Construction
 
-After the LLM responds, a `RobotResult` is built:
+After the LLM responds, `build_result` turns the response into a `RobotResult`:
 
 ```ruby
 def build_result(response, _memory)
-  output = if response.respond_to?(:content) && response.content
-    [TextMessage.new(role: 'assistant', content: response.content)]
-  else
-    []
-  end
-
-  tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
-
-  RobotResult.new(
-    robot_name: @name,
-    output: output,
-    tool_calls: normalize_tool_calls(tool_calls),
-    stop_reason: response.respond_to?(:stop_reason) ? response.stop_reason : nil,
-    raw: response
-  )
+  text   = result_text(response)
+  output = text ? [TextMessage.new(role: 'assistant', content: text)] : []
+  # ... reads response.tokens (or input_tokens/output_tokens), accumulates them
+  #     into the robot's running totals, and passes them to RobotResult
 end
 ```
 
+`result_text` is deliberately more forgiving than `response.content`. It falls back, in order, to:
+
+1. `response.content`, when present and non-empty
+2. `response.thinking` — Ollama routes some models' (e.g. qwen3) entire output through `reasoning_content`, which RubyLLM surfaces as `thinking`
+3. the most recent non-empty assistant message in `@chat.messages`, scoped to messages *after* the last user message, for models that end a turn on a tool call with no trailing text
+
+Scoping the history fallback to the current turn is what prevents a previous turn's answer from being returned when a thinking-mode model emits nothing in `content`.
+
+`build_result` also does token accounting: it reads `response.tokens` (falling back to `input_tokens`/`output_tokens`), adds them to the robot's running totals, and stores them on the result. `run` then reconciles the budget reservation and enforces `token_budget` / `cost_budget`, raising **`RobotLab::InferenceError`** when this call's actual usage pushed cumulative usage over budget. (`RobotLab::BudgetExceeded` is the *other* budget error: it is raised by `reserve_budget!` **before** the call, when a prior call already exhausted the dimension. See [Budgets](../guides/observability.md#budgets-token-cost).)
+
 ## RobotResult
 
 The result object from a `robot.run` call:
@@ -178,12 +226,15 @@ The result object from a `robot.run` call:
 result = robot.run("Hello!")
 
 result.robot_name       # => "assistant"
-result.output           # => [TextMessage, ...]
-result.tool_calls       # => [ToolResultMessage, ...]
-result.stop_reason      # => "stop" or nil
+result.output           # => [TextMessage] synthesized from result_text
+result.tool_calls       # => [] in practice (see below)
+result.stop_reason      # => nil — always (see below)
 result.created_at       # => Time
 result.id               # => UUID string
 result.duration         # => Float or nil (elapsed seconds, set in pipeline execution)
+result.input_tokens     # => Integer
+result.output_tokens    # => Integer
+result.checksum         # => "sha256-hex"
 result.raw              # => raw LLM response object
 
 # Convenience methods
@@ -191,19 +242,33 @@ result.last_text_content  # => "Hi there!" (last text message content)
 result.reply              # => alias for last_text_content
 result.has_tool_calls?    # => false
 result.stopped?           # => true
+result.export             # => Hash (excludes debug fields)
+result.to_h / result.to_json
 ```
 
+`stop_reason` is always `nil`. `build_result` assigns it with `response.respond_to?(:stop_reason) ? response.stop_reason : nil`, and `RubyLLM::Message` does not define `stop_reason`, so no `robot.run` result ever reports one. It is dropped from `export` by the `.compact`, and `stopped?` therefore reduces to `!has_tool_calls?`.
+
+`output` is a single synthesized `TextMessage`, not a transcript of the turn, and `tool_calls` is read off the final assistant message — which no longer carries tool calls once RubyLLM's tool loop has finished, so it is effectively always empty. Observe tool usage through the `on_tool_call`/`on_tool_result` callbacks or the tool hooks instead.
+
 ## Streaming
 
-Robots support streaming by passing a block to `run`:
+Robots support streaming by passing a block to `run`. The block receives a `RubyLLM::Chunk`; its text is in `content`:
 
 ```ruby
-result = robot.run("Tell me a story") do |event|
-  print event.text if event.respond_to?(:text)
+result = robot.run("Tell me a story") do |chunk|
+  print chunk.content
 end
 ```
 
-The block is forwarded to `Agent#ask` which passes it to `@chat.ask`. Streaming events are provider-specific but typically include text deltas.
+`effective_streaming_block` merges the block with any stored `on_content:` callback. If both are present, both fire — the stored `on_content` first, then the runtime block. The merged block is forwarded to `Agent#ask`, which passes it to `@chat.ask`.
+
+```ruby
+# on_content fires on every run, no block required
+robot = RobotLab.build(name: "bot", system_prompt: "...",
+                       on_content: ->(chunk) { print chunk.content })
+```
+
+`on_content` is read from the robot's own config at construction — a network-level `config:` does not supply it.
 
 ## Template Resolution
 
@@ -213,31 +278,45 @@ When a robot has a `template:`, it is resolved during initialization:
 # 1. Parse the template via prompt_manager
 parsed = PM.parse(@template)
 
-# 2. Extract and apply front matter config
-#    (model, temperature, top_p, etc.)
-apply_front_matter_config(parsed.metadata)
+# 2. Apply the non-LLM front matter keys: robot_name, description, tools, mcp
+#    (constructor-provided values win, so these only fill in gaps)
+apply_front_matter_extras(parsed.metadata)
 
-# 3. Render the template body with context
-rendered = parsed.to_s(**resolved_context)
+# 3. Turn the LLM keys into a RunConfig. Front matter is the BASE;
+#    @config (constructor kwargs) merges over it and wins.
+effective = RunConfig.from_front_matter(parsed.metadata).merge(@config)
+effective.apply_to(@chat, provider: @provider, assume_model_exists: !@provider.nil?)
 
-# 4. Set as system instructions on @chat
-@chat.with_instructions(rendered)
+# 4. Render the template body with context and set it as system instructions
+@chat.with_instructions(parsed.to_s(**resolved_context))
 ```
 
+If required parameters are missing at build time, rendering is skipped and deferred: the first `run` that supplies context calls `rerender_template`, which re-renders and re-appends the inline `system_prompt`. When `skills:` are in play, each skill's body and front matter are accumulated the same way and the bodies are joined before being set as one instructions block.
+
 ### Front Matter Config Keys
 
-Templates can configure the chat via YAML front matter:
+Templates parse these LLM keys into a `RunConfig`:
 
 | Key | Effect |
 |-----|--------|
 | `model` | Sets the LLM model |
 | `temperature` | Sets randomness |
-| `top_p` | Sets nucleus sampling |
-| `top_k` | Sets top-k sampling |
-| `max_tokens` | Sets max response tokens |
-| `presence_penalty` | Sets presence penalty |
-| `frequency_penalty` | Sets frequency penalty |
-| `stop` | Sets stop sequences |
+| `top_p` | Parsed, but **not applied** — see below |
+| `top_k` | Parsed, but **not applied** |
+| `max_tokens` | Parsed, but **not applied** |
+| `presence_penalty` | Parsed, but **not applied** |
+| `frequency_penalty` | Parsed, but **not applied** |
+| `stop` | Parsed, but **not applied** |
+
+`RunConfig#apply_to` dispatches `chat.with_<field>` guarded by `respond_to?`. `RubyLLM::Chat` only defines `with_model` and `with_temperature`, so the other six are silently dropped when they come from front matter. To set them, use constructor kwargs or a `config:` RunConfig — that path goes through `apply_chat_params` → `with_params` and does take effect:
+
+```ruby
+RobotLab.build(name: "bot", template: :report, max_tokens: 2000, top_p: 0.3)
+```
+
+Front matter keys that are not LLM fields — `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters` — all work.
+
+Template bodies render with ERB: use `<%= var %>`. `{{ var }}` is not interpolated and passes through verbatim.
 
 ## Model Selection
 
@@ -269,6 +348,7 @@ sequenceDiagram
     participant Chat as @chat
 
     SF->>Task: call(result)
+    Task->>Task: Hooks.run(:task, ...)
     Task->>Task: deep_merge(run_params, task_context)
     Task->>Robot: call(enhanced_result)
     Robot->>Robot: extract_run_context(result)
@@ -279,7 +359,9 @@ sequenceDiagram
     Robot-->>SF: result.continue(robot_result)
 ```
 
-The `Task` wrapper deep-merges per-task configuration (context, mcp, tools) before delegating to the robot's `call`. The base `Robot#call` extracts the message, calls `run`, and records the elapsed time in `RobotResult#duration`. If the robot raises any exception, the error is caught and wrapped in a `RobotResult` so one failing robot does not crash the entire pipeline:
+The `Task` wrapper runs the `:task` hook family and deep-merges its per-task configuration (context, mcp, tools, memory, config) into `run_params` before delegating to the robot's `call`. Note that a task's `mcp:`/`tools:` land in `run_params` and are therefore consumed by the robot as *runtime* values, not as a separate tier between the network and the robot.
+
+The base `Robot#call` extracts the message, calls `run`, and records the elapsed time in `RobotResult#duration`. Because the result is stored under `@name.to_sym`, the pipeline context is keyed by the **robot's** name, not the task name. If the robot raises any exception, the error is caught and wrapped in a `RobotResult` so one failing robot does not crash the entire pipeline:
 
 ```ruby
 def call(result)

data/docs/architecture/state-management.md

@@ -1,6 +1,6 @@
 # Memory Management
 
-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.
+Memory in RobotLab is a reactive key-value store that provides persistent storage for runtime data, conversation history, and arbitrary user-defined values. A single unified `Memory` class serves both standalone robot usage and shared network execution.
 
 ## Memory Structure
 
@@ -41,6 +41,8 @@ result2 = robot.run("What are my preferences?")
 robot.reset_memory
 ```
 
+`reset_memory` resets only the key-value store. It does **not** touch the robot's chat history — that is `robot.clear_messages(keep_system: true)`. The two are independent.
+
 ## 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.
@@ -116,7 +118,7 @@ memory.data.category  #=> "billing"   (method-style via StateProxy)
 
 memory.results       #=> []
 memory.session_id    #=> nil
-memory.cache         #=> RubyLLM::SemanticCache
+memory.cache         #=> RubyLLM::SemanticCache (the module itself), or nil when enable_cache: false
 ```
 
 ## StateProxy
@@ -141,7 +143,7 @@ Memory supports pub/sub semantics where robots can subscribe to key changes and
 
 ### Setting Values
 
-Use `memory.set(key, value)` to write a value and notify subscribers asynchronously:
+Use `memory.set(key, value)` to write a value, wake any waiters, and notify subscribers. Subscriber callbacks are dispatched through `Async { }`: inside a running reactor they run as fibers, but **outside** one they run synchronously on the writer's thread.
 
 ```ruby
 memory.set(:sentiment, { score: 0.8, confidence: 0.95 })
@@ -164,7 +166,7 @@ memory.get(:sentiment)
 # Block indefinitely until value exists
 memory.get(:sentiment, wait: true)
 
-# Block up to 30 seconds, raise AwaitTimeout if exceeded
+# Block up to 30 seconds, then raise RobotLab::AwaitTimeout
 memory.get(:sentiment, wait: 30)
 
 # Wait for multiple keys at once
@@ -172,6 +174,11 @@ results = memory.get(:sentiment, :entities, :keywords, wait: 60)
 #=> { sentiment: {...}, entities: [...], keywords: [...] }
 ```
 
+Two things to be careful with:
+
+- On expiry a blocking read **raises** `RobotLab::AwaitTimeout`; it does not return `nil`. Rescue it if a missing value is acceptable.
+- With multiple keys the timeout is applied **per missing key**, not to the call as a whole. `get_multiple` waits on the missing keys one at a time in order, so the call raises as soon as the *first* one expires — it does not spend the full 60 s on each. The 180 s worst case is only reached when the earlier keys arrive just before their own deadlines.
+
 ### Subscriptions
 
 Subscribe to key changes with async callbacks. The callback receives a `MemoryChange` object:
@@ -237,11 +244,12 @@ Each `RobotResult` contains:
 
 ```ruby
 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.output           # [TextMessage] synthesized from the final response text
+result.tool_calls       # Array<ToolResultMessage> - effectively always empty (see Message Flow)
+result.stop_reason      # always nil for a robot.run result (see Message Flow)
 result.last_text_content # Convenience: last text content string
-result.has_tool_calls?  # Whether any tools were called
+result.input_tokens     # Prompt tokens for the run
+result.output_tokens    # Completion tokens for the run
 result.created_at       # When it was created
 ```
 
@@ -307,6 +315,8 @@ json = memory.to_json
 memory = Memory.from_hash(hash)
 ```
 
+`to_h` is compacted, so nil-valued reserved keys (a missing `session_id`, for instance) are omitted entirely rather than serialized as `nil`.
+
 ## Semantic Cache
 
 Memory includes a semantic cache via `RubyLLM::SemanticCache` that reduces costs and latency by returning cached responses for semantically equivalent queries:
@@ -334,19 +344,28 @@ robot = RobotLab.build(name: "bot", system_prompt: "...", enable_cache: false)
 Memory defaults to a Hash-based backend but can use Redis for distributed scenarios:
 
 ```ruby
-# Auto-detect (uses Redis if available, falls back to Hash)
+# Try Redis, fall back to Hash
 memory = Memory.new(backend: :auto)
 
-# Force Hash backend
+# Hash backend — the only value that is honoured literally
 memory = Memory.new(backend: :hash)
 
-# Force Redis backend
+# Same behaviour as :auto — try Redis, fall back to Hash
 memory = Memory.new(backend: :redis)
 
-# Check backend
+# Check what you actually got
 memory.redis?  #=> true/false
 ```
 
+!!! note "`backend: :redis` does not force Redis"
+    `select_backend` special-cases only `:hash`; every other value (`:redis`,
+    `:auto`, anything else) takes the same branch —
+    `create_redis_backend || create_hash_backend`. `create_redis_backend`
+    returns `nil` when `redis` is unavailable and rescues `StandardError` to
+    `nil` on a connection failure, so an unreachable Redis silently downgrades
+    to a Hash with no exception and no warning. Always check `memory.redis?` if
+    the distinction matters.
+
 Redis is configured via `RobotLab.config.redis` or the `REDIS_URL` environment variable.
 
 ## Best Practices