robot_lab 0.2.6 → 0.2.7

data/docs/guides/mcp-integration.md

@@ -50,9 +50,10 @@ MCP servers can be declared directly in a template's YAML front matter, making t
 description: GitHub assistant with MCP tool access
 mcp:
   - name: github
-    transport: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-github"]
+    transport:
+      type: stdio
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-github"]
 ---
 You are a helpful GitHub assistant with access to GitHub tools via MCP.
 ```
@@ -64,6 +65,16 @@ robot = RobotLab.build(template: :github_assistant)
 
 Constructor `mcp:` overrides frontmatter `mcp:` when provided.
 
+> [!CAUTION]
+> `transport:` must be a **nested mapping**, exactly as above. The flat form —
+> `transport: stdio` with sibling `command:`/`args:` keys — does not raise:
+> `Server` calls `transform_keys` on the transport value, a String raises
+> `NoMethodError: undefined method 'transform_keys' for an instance of String`,
+> and that exception is caught by MCP setup's rescue. The robot builds and runs
+> with **zero tools** from that server. It is not silent, though: the failure is
+> logged at `WARN` through `RobotLab.config.logger` (`$stdout` by default) and
+> the server name is recorded in `robot.failed_mcp_server_names`.
+
 ### Hierarchical Configuration
 
 The `mcp:` parameter supports three modes:
@@ -96,14 +107,21 @@ MCP configuration resolves through a hierarchy: **runtime > robot build > networ
 
 ```
 Global (RobotLab.config.mcp)
-  -> Network (task mcp: [...])
+  -> Network (network config:  / task config:)
     -> Robot (mcp: :inherit | :none | [...])
-      -> Runtime (robot.run("msg", mcp: [...]))
+      -> Runtime (robot.run("msg", mcp: [...]), and task mcp: [...])
 ```
 
+> [!NOTE]
+> A task's `mcp:`/`tools:` are **not** a separate network tier — `Task` puts
+> them into the run params, so they arrive as the **runtime** value for that
+> robot's `run()`. Only a `config:` (on the network or on the task) acts as the
+> parent level that `:inherit` resolves against.
+
 ## Timeout Configuration
 
-All transports support a configurable request timeout. The default is 15 seconds. Set a custom timeout at the server level:
+Every server config accepts a `timeout:`. The default is 15 seconds
+(`RobotLab::MCP::Server::DEFAULT_TIMEOUT`). Set it at the server level:
 
 ```ruby
 robot = RobotLab.build(
@@ -119,10 +137,46 @@ robot = RobotLab.build(
 )
 ```
 
-Values >= 1000 are auto-converted from milliseconds to seconds. The minimum timeout is 1 second.
+Values >= 1000 are auto-converted from milliseconds to seconds. The minimum timeout is 1 second:
+
+| Given | Stored |
+|-------|--------|
+| `nil` | `15` (the default) |
+| `30` | `30.0` |
+| `5000` | `5.0` (read as milliseconds) |
+| `0.5` | `1` (floored to the 1-second minimum) |
+
+> [!WARNING]
+> **Only the Stdio transport actually enforces the timeout.** SSE, WebSocket,
+> and StreamableHTTP store the value and never reference it — a remote MCP
+> server that stops responding will hang the call indefinitely regardless of
+> what you set here. Apply your own timeout around remote-transport calls if
+> you need one.
 
 ## Transport Types
 
+Valid `type:` values are exactly: `stdio`, `sse`, `ws`, `websocket`,
+`streamable-http`, `http` (`RobotLab::MCP::Server::VALID_TRANSPORT_TYPES`).
+
+An invalid type raises `ArgumentError: Invalid transport type: <type>. Must be
+one of: stdio, sse, ws, websocket, streamable-http, http` — but **only if you
+construct the server or client yourself**. Through the robot (`mcp:` on
+`RobotLab.build`) the error is caught by the same rescue that handles any other
+connect failure: it is logged at `WARN` and the server name is recorded in
+`robot.failed_mcp_server_names`, and the robot carries on with zero tools from
+that server. See [Connection Errors](#connection-errors).
+
+```ruby
+bad = { name: "oops", transport: { type: "streamable_http", url: "https://x" } }
+
+RobotLab::MCP::Server.new(**bad)   # => raises ArgumentError
+
+robot = RobotLab.build(name: "r", system_prompt: "...", mcp: [bad])
+robot.run("hi", mcp: :inherit, tools: :inherit)
+# logs: WARN Robot 'r' error connecting to MCP server 'oops': Invalid transport type: ...
+robot.failed_mcp_server_names   # => ["oops"]
+```
+
 ### Stdio Transport
 
 Communicate via stdin/stdout with a subprocess:
@@ -154,7 +208,9 @@ Connect via WebSocket:
 ```
 
 !!! note "Dependency Required"
-    WebSocket transport requires the `async-websocket` gem.
+    WebSocket transport requires the `async-websocket` gem. (It also reaches for
+    `Async::HTTP::Endpoint` without requiring it, so `async-http` must be loaded
+    as well.)
 
 ### SSE Transport
 
@@ -170,6 +226,9 @@ Server-Sent Events transport:
 }
 ```
 
+!!! note "Dependency Required"
+    SSE transport requires the `async-http` gem.
+
 ### HTTP Transport
 
 Streamable HTTP transport with session support:
@@ -178,7 +237,7 @@ Streamable HTTP transport with session support:
 {
   name: "http_server",
   transport: {
-    type: "streamable_http",
+    type: "streamable-http",   # or "http" — NOT "streamable_http"
     url: "https://api.example.com/mcp",
     session_id: "optional_session_id",
     auth_provider: -> { "Bearer #{fetch_token}" }
@@ -186,30 +245,60 @@ Streamable HTTP transport with session support:
 }
 ```
 
+!!! note "Dependency Required"
+    Streamable HTTP transport requires the `async-http` gem.
+
+> [!CAUTION]
+> The type is spelled with a **hyphen**. `type: "streamable_http"` (underscore)
+> raises `ArgumentError: Invalid transport type: streamable_http`.
+
+> [!WARNING]
+> The remote transports connect inside an un-awaited `Async` block and set
+> their connected flag **before** the MCP initialize handshake. `client.connected?`
+> therefore returns `true` even when the host is unreachable — do not treat it
+> as proof the server answered. Stdio is the only transport that blocks on the
+> handshake and reports a connect failure synchronously.
+
 ## Using MCP Tools
 
-Once configured, MCP tools are automatically discovered and made available to the robot. The robot connects to MCP servers on its first `run` call and discovers tools dynamically:
+Once configured, MCP tools are discovered on connect and made available to the
+robot. **Connecting is not automatic** — see the warning below:
 
 ```ruby
 robot = RobotLab.build(
   name: "helper",
-  system_prompt: <<~PROMPT
+  system_prompt: <<~PROMPT,
     You can help users with GitHub tasks.
     Use available tools to search repositories, create issues, etc.
-  PROMPT,
+  PROMPT
   mcp: [
     { name: "github", transport: { type: "stdio", command: "mcp-server-github" } }
   ]
 )
 
-# MCP tools are automatically available
-result = robot.run("Find repositories about machine learning")
+# mcp: :inherit connects the servers; tools: :inherit sends their tools to the LLM.
+result = robot.run("Find repositories about machine learning", mcp: :inherit, tools: :inherit)
 puts result.last_text_content
 ```
 
+> [!CAUTION]
+> **A plain `robot.run(message)` neither connects MCP servers nor sends any
+> tools.** Both the `mcp:` and `tools:` parameters of `run` default to `:none`,
+> which means "zero this turn" — the build-time `mcp:` list is simply not
+> consulted. You need **both** flags:
+>
+> ```ruby
+> robot.run("...")                                   # no MCP connection, no tools
+> robot.run("...", mcp: :inherit)                    # connects, but sends zero tools
+> robot.run("...", mcp: :inherit, tools: :inherit)   # connects AND sends its tools
+> ```
+
 ## Filtering MCP Tools
 
-Use the `tools:` parameter to restrict which tools (including MCP-discovered tools) are available to a robot:
+Use the `tools:` parameter to restrict which tools (including MCP-discovered
+tools) reach the LLM. It is a **name allowlist**, and it must be supplied at the
+level that actually runs — the `run()` call (or the network `task`, which
+forwards to `run()`):
 
 ```ruby
 robot = RobotLab.build(
@@ -217,14 +306,32 @@ robot = RobotLab.build(
   system_prompt: "You help read and search files.",
   mcp: [
     { name: "filesystem", transport: { type: "stdio", command: "mcp-server-fs" } }
-  ],
-  tools: %w[read_file search_files list_directory]  # Only allow specific tools
+  ]
 )
+
+robot.run("Summarise the README",
+          mcp:   :inherit,
+          tools: %w[read_file search_files list_directory])  # only these
 ```
 
+> [!WARNING]
+> A build-time `tools: %w[...]` allowlist has no effect on its own, because the
+> runtime default of `:none` sends zero tools regardless. And for a
+> **standalone** robot, do not write `tools: :inherit` at build time as a
+> workaround: there the parent level is the global `:none`, so it produces an
+> allowlist of `["none"]` that matches nothing. Leave build-time `tools:` unset
+> and pass the filter at run time.
+>
+> Inside a **network** whose `config:` supplies `tools:`/`mcp:`, this reverses:
+> the parent level is the network's list, and build-time `:inherit` is what
+> makes the robot pick it up. See
+> [Network-Wide Tool and MCP Defaults](creating-networks.md#network-wide-tool-and-mcp-defaults).
+
 ## MCP in Networks
 
-When running robots in a network, use per-task MCP configuration:
+When running robots in a network, use per-task MCP configuration. Remember that
+a task's `mcp:`/`tools:` become that robot's **runtime** values, so `tools:`
+must be set too or the MCP tools will not be sent:
 
 ```ruby
 network = RobotLab.create_network(name: "dev_pipeline") do
@@ -233,6 +340,7 @@ network = RobotLab.create_network(name: "dev_pipeline") do
        mcp: [
          { name: "filesystem", transport: { type: "stdio", command: "mcp-server-fs" } }
        ],
+       tools: :inherit,
        depends_on: [:planner]
   task :reviewer, reviewer_robot, depends_on: [:coder]
 end
@@ -310,6 +418,13 @@ client.list_resources       # => Array of resource definitions
 client.disconnect
 ```
 
+> [!NOTE]
+> `MCP::Client#initialize(server_or_config, poller: nil)` takes its server as a
+> **positional** argument — either a `Server` instance or a config Hash.
+> `Client.new(name: "x", transport: {...})` raises `ArgumentError: wrong number
+> of arguments (given 0, expected 1)`; wrap the hash in braces:
+> `Client.new({ name: "x", transport: {...} })`.
+
 ## Connection Multiplexing
 
 When a robot connects to several local (stdio) MCP servers, each client normally blocks independently while waiting for a response. `MCP::ConnectionPoller` replaces this with a single `IO.select` call across all registered stdout file descriptors, dispatching each response to the pending request for that client.
@@ -377,8 +492,10 @@ robot = RobotLab.build(
   ]
 )
 
-# Discovery connects only :brew for this message — filesystem and github are skipped
-robot.run("install imagemagick")
+# Discovery connects only :brew for this message — filesystem and github are skipped.
+# mcp: :inherit is required; a plain run() resolves the MCP list to empty and
+# discovery never runs.
+robot.run("install imagemagick", mcp: :inherit, tools: :inherit)
 ```
 
 ### How It Works
@@ -387,7 +504,7 @@ robot.run("install imagemagick")
 
 The threshold is intentionally low — server descriptions are short, so raw cosine scores are naturally small even for on-topic queries.
 
-Discovery only applies on the **first** `run()` call (before `@mcp_initialized`). Once a set of servers is connected they remain connected for the robot's lifetime, preserving tool continuity across a conversation.
+Discovery only applies on the **first** MCP-resolving `run()` call (before the robot is marked MCP-initialized). Once a set of servers is connected they remain connected for the robot's lifetime, preserving tool continuity across a conversation.
 
 ### Fallback Behaviour
 
@@ -404,23 +521,42 @@ All servers are returned unchanged when any of the following apply:
 
 ```ruby
 servers = [
-  { name: "filesystem", description: "Read and write files", transport: { ... } },
-  { name: "github",     description: "GitHub repos and PRs",  transport: { ... } }
+  { name: "filesystem", description: "Read and write files",
+    transport: { type: "stdio", command: "mcp-server-fs" } },
+  { name: "github",     description: "GitHub repos and PRs",
+    transport: { type: "stdio", command: "mcp-server-github" } }
 ]
 
 relevant = RobotLab::MCP::ServerDiscovery.select(
-  "list open pull requests",
+  "search github repos",
   from: servers,
   threshold: 0.05   # optional, default
 )
-# => only the :github entry
+# => [{ name: "github", ... }]
 ```
 
+> [!IMPORTANT]
+> Scoring is lexical, not semantic — it compares word stems against each
+> server's `description`. A query that happens to share no stems with **any**
+> description scores 0.0 everywhere, trips the "nothing above threshold"
+> fallback in the table above, and gets **all** servers back rather than none.
+> With the two servers above:
+>
+> ```ruby
+> select("search github repos",     from: servers)  # => ["github"]
+> select("read and write files",    from: servers)  # => ["filesystem"]
+> select("list open pull requests", from: servers)  # => ["filesystem", "github"]  <- fallback
+> ```
+>
+> The last one selects everything because the description says "PRs", not "pull
+> requests". Write descriptions using the words your prompts will actually use.
+
 ## Connection Resilience
 
 ### Eager Connection
 
-By default, MCP connections are lazy — established on the first `run()` call. Use `connect_mcp!` to connect early:
+`connect_mcp!` connects the robot's configured servers immediately, without
+waiting for a `run()` that passes `mcp: :inherit`:
 
 ```ruby
 robot = RobotLab.build(
@@ -440,14 +576,22 @@ if robot.failed_mcp_server_names.any?
 end
 ```
 
+> [!NOTE]
+> `connect_mcp!` only opens the connections. A later plain `robot.run(message)`
+> still sends the LLM **zero** tools, because `run`'s `tools:` defaults to
+> `:none`. Eager connection and tool visibility are separate switches.
+
 ### Automatic Retry
 
-Failed MCP servers are automatically retried on subsequent `run()` calls. If a server was down when the robot first connected, it will be retried transparently:
+Failed MCP servers are retried on subsequent `run()` calls **that resolve to a
+non-empty MCP list** — i.e. runs that pass `mcp: :inherit` (or an explicit
+array). If a server was down when the robot first connected, it is retried
+transparently:
 
 ```ruby
-robot.run("First message")       # github connects, filesystem fails
+robot.run("First message",  mcp: :inherit, tools: :inherit)  # github connects, filesystem fails
 # ... filesystem comes back up ...
-robot.run("Second message")      # filesystem retried and connects
+robot.run("Second message", mcp: :inherit, tools: :inherit)  # filesystem retried and connects
 ```
 
 ### Injecting External MCP Clients
@@ -464,25 +608,45 @@ This skips the normal connection process and marks the robot as MCP-initialized.
 
 ### Connection Errors
 
+MCP connection failures are **not raised**. They are logged as warnings and
+recorded on the robot; the run continues without that server's tools, and one
+failing server does not prevent the others from connecting. Inspect the result
+rather than rescuing:
+
 ```ruby
-begin
-  result = robot.run("Search for repos")
-rescue RobotLab::MCPError => e
-  puts "MCP Error: #{e.message}"
+result = robot.run("Search for repos", mcp: :inherit, tools: :inherit)
+
+if robot.failed_mcp_server_names.any?
+  warn "MCP servers unavailable: #{robot.failed_mcp_server_names.join(', ')}"
 end
 ```
 
-MCP connection failures are logged as warnings but do not raise errors by default. The robot will continue without MCP tools if a server is unreachable. One failing server does not prevent other servers from connecting.
-
 ### Timeout Errors
 
-Stdio transports wrap all blocking I/O with a configurable timeout. If a server does not respond within the timeout period, an `MCPError` is raised with a descriptive message:
+Stdio transports wrap all blocking I/O with a configurable timeout. On expiry
+the transport raises `MCPError`. Note that the two messages differ, and neither
+uses the server *name* you configured — the handshake message names the
+**command**, and the per-request message names nothing at all:
 
 ```ruby
-# Server that takes too long will raise:
-# RobotLab::MCPError: MCP server 'heavy-server' did not respond within 15s
+# Handshake timed out during connect:
+# RobotLab::MCPError: MCP server 'heavy-mcp-server' did not respond within 15s
+
+# A later request timed out:
+# RobotLab::MCPError: MCP server did not respond within 15s
 ```
 
+> [!IMPORTANT]
+> `MCP::Client#connect` rescues **every** `StandardError`, logs
+> `"MCP connection failed for <name>: ..."` at `:warn`, and returns `self` with
+> `connected?` false. So a connect-time timeout never reaches your `begin/rescue`
+> — check `client.connected?` (or `robot.failed_mcp_server_names`) instead.
+> Per-request calls such as `list_tools` and `call_tool` **do** propagate
+> `MCPError`.
+
+SSE, WebSocket, and StreamableHTTP raise no timeout error at all — see the
+warning under [Timeout Configuration](#timeout-configuration).
+
 ## Disconnecting
 
 Robots can be manually disconnected from MCP servers:
@@ -546,25 +710,28 @@ robot = RobotLab.build(
 
 ### 2. Limit Tool Access
 
-Restrict which MCP tools are available to a robot using the `tools:` parameter:
+Restrict which MCP tools reach the LLM with a `tools:` allowlist on the run:
 
 ```ruby
 robot = RobotLab.build(
   name: "reader",
   system_prompt: "You read and search files.",
-  mcp: [{ name: "fs", transport: { type: "stdio", command: "mcp-fs" } }],
-  tools: %w[read_file search_files]  # No write access
+  mcp: [{ name: "fs", transport: { type: "stdio", command: "mcp-fs" } }]
 )
+
+robot.run("Find the config file",
+          mcp:   :inherit,
+          tools: %w[read_file search_files])  # No write access
 ```
 
 ### 3. Use Appropriate Transports
 
 | Transport | Best For |
 |-----------|----------|
-| `stdio` | Local servers, CLI tools |
-| `websocket` | Persistent connections, bidirectional |
+| `stdio` | Local servers, CLI tools. The only transport that enforces `timeout:` and reports connect failures synchronously. |
+| `websocket` (or `ws`) | Persistent connections, bidirectional |
 | `sse` | Server push, event streams |
-| `streamable_http` | Remote APIs, session-based |
+| `streamable-http` (or `http`) | Remote APIs, session-based |
 
 ## Next Steps
 

data/docs/guides/memory.md

@@ -86,7 +86,7 @@ Memory has reserved keys with special behavior:
 | `: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) |
+| `:cache` | `RubyLLM::SemanticCache` module, or `nil` | Semantic cache (read-only after init). Set at construction time; `nil` when built with `enable_cache: false` |
 
 ### The Data Hash
 
@@ -143,6 +143,16 @@ You can also clear just the custom keys without resetting reserved keys:
 robot.memory.clear  # Clears non-reserved keys only
 ```
 
+> [!WARNING]
+> `reset_memory` resets **only the key-value store**. It does not touch the
+> robot's conversation history — the chat still holds every prior message, and
+> the LLM will still see them. Clearing the transcript is a separate call:
+>
+> ```ruby
+> robot.reset_memory                        # key-value store only
+> robot.clear_messages(keep_system: true)   # conversation history only
+> ```
+
 ## 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:
@@ -190,11 +200,40 @@ results = memory.get(:sentiment, :entities, :keywords, wait: 60)
 # => { sentiment: {...}, entities: [...], keywords: [...] }
 ```
 
-Each blocking wait is backed by an `IO.pipe` pair (`Waiter` class). Calling `signal` writes one byte per waiting caller, so all threads blocked on `IO.select` wake immediately. This design works cleanly with Ruby's Async fiber scheduler — no mutex contention or spurious wakeups.
+> [!WARNING]
+> A blocking `get` that expires **raises `RobotLab::AwaitTimeout`** — it does
+> not return `nil`. (A *non*-blocking `get`, the default, returns `nil` for a
+> missing key.) Wrap it if a missing value is survivable:
+>
+> ```ruby
+> begin
+>   memory.get(:sentiment, wait: 30)
+> rescue RobotLab::AwaitTimeout => e
+>   # => "Timeout waiting for :sentiment after 30 seconds"
+>   nil
+> end
+> ```
+
+> [!CAUTION]
+> With multiple keys the timeout is applied **per missing key**, not to the call
+> as a whole. `memory.get(:a, :b, :c, wait: 30)` awaits the missing keys
+> sequentially, each with its own fresh 30-second budget.
+>
+> It does not, however, spend the whole 90 seconds before reporting: the first
+> key whose wait expires **raises `AwaitTimeout` immediately**, aborting the call
+> — so the keys that were already resolved are lost along with the ones not yet
+> attempted. The 90 seconds is the worst case only for a call that *succeeds*
+> (each key arriving just under its own deadline).
+
+Each blocking wait is backed by an `IO.pipe` pair (`Waiter` class). The waiting
+side calls `@read_io.wait_readable(timeout)`; `signal` writes one byte per
+waiting caller so every blocked waiter wakes exactly once. `wait_readable`
+yields to Ruby's Async fiber scheduler when one is installed — no mutex
+contention or spurious wakeups.
 
 ### Subscriptions
 
-Subscribe to key changes with asynchronous callbacks:
+Subscribe to key changes:
 
 ```ruby
 # Subscribe to a single key
@@ -214,6 +253,24 @@ memory.subscribe_pattern("analysis:*") do |change|
 end
 ```
 
+> [!IMPORTANT]
+> Subscription callbacks are dispatched through `Async { }`. Inside a running
+> Async reactor that defers them; **outside one — which is the normal case for
+> plain Ruby, Rails request threads, and tests — the block runs synchronously
+> on the writer's thread**, before `memory[:key] = value` returns:
+>
+> ```ruby
+> order = []
+> memory.subscribe(:k) { |c| order << "callback" }
+> order << "before-set"
+> memory[:k] = 1
+> order << "after-set"
+> order   # => ["before-set", "callback", "after-set"]
+> ```
+>
+> Keep subscription callbacks fast, and never assume the writer has moved on by
+> the time your callback runs.
+
 ### Unsubscribe
 
 ```ruby
@@ -243,6 +300,8 @@ Memory can be exported and reconstructed:
 # Export to hash
 hash = robot.memory.to_h
 # => { data: {...}, results: [...], messages: [...], session_id: "...", custom: {...} }
+# to_h is compacted: nil entries are dropped, so an unset :session_id (and the
+# :cache key, which is never exported) simply will not appear.
 
 # Export to JSON
 json = robot.memory.to_json
@@ -279,34 +338,60 @@ memory[:stage] = "response"
 
 ### Caching Expensive Operations
 
+A tool reaches memory through its owning robot. Subclass `RobotLab::Tool` (which
+has a `robot` accessor) and attach an **instance constructed with `robot:`** —
+that is the only supported way for tool code to read and write robot memory:
+
 ```ruby
-class FetchUser < RubyLLM::Tool
+class FetchUser < RobotLab::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}"
+    cache_key = :"cache:user:#{user_id}"
 
-    # 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)
+    cached = robot&.memory&.[](cache_key)
     return cached if cached
 
-    # Fetch and cache
     user = User.find(user_id).to_h
-    Thread.current[:robot_memory]&.[]=(cache_key.to_sym, user)
+    robot&.memory&.[]=(cache_key, user)
     user
   end
 end
+
+robot = RobotLab.build(name: "support", system_prompt: "...")
+robot.local_tools << FetchUser.new(robot: robot)
+
+robot.run("Look up user 42", tools: :inherit)
 ```
 
+> [!WARNING]
+> There is **no thread-local memory handle** in RobotLab — nothing anywhere in
+> the codebase ever assigns `Thread.current[:robot_memory]`. A tool that reads
+> it will always see `nil` and silently cache nothing. Go through `robot.memory`
+> as above, and remember that `FetchUser.new` without `robot:` leaves `robot`
+> `nil`.
+
 ### Semantic Caching
 
-Memory includes a semantic cache for LLM response caching:
+Memory exposes a semantic cache for LLM response caching. It is on by default
+and becomes `nil` when you opt out with `enable_cache: false`:
+
+```ruby
+RobotLab.create_memory.cache                       # => RubyLLM::SemanticCache
+RobotLab.create_memory(enable_cache: false).cache  # => nil
+
+RobotLab.build(name: "x", system_prompt: "…").memory.cache
+# => RubyLLM::SemanticCache
+RobotLab.build(name: "x", system_prompt: "…", enable_cache: false).memory.cache
+# => nil
+```
+
+Guard for `nil` in any code that might run against a cache-disabled memory.
 
 ```ruby
 # Access the semantic cache
-cache = robot.memory.cache  # => RubyLLM::SemanticCache
+cache = robot.memory.cache
 
 # Use it to cache semantically similar queries
 response = cache.fetch("What is Ruby?") do
@@ -314,6 +399,12 @@ response = cache.fetch("What is Ruby?") do
 end
 ```
 
+> [!NOTE]
+> `memory.cache` is the `RubyLLM::SemanticCache` **module itself**, not a
+> per-memory instance. Its cache store, vector store, and configuration are
+> process-global — two memories with `enable_cache: true` share one cache. It
+> also embeds every query, so `fetch` costs an embedding call.
+
 ## Best Practices
 
 ### 1. Use Descriptive Keys