rubino-agent 0.4.0 → 0.5.1

data/lib/rubino/mcp/manager.rb

@@ -18,16 +18,37 @@ module Rubino
         @config = config || Rubino.configuration
         @clients = {}
         @last_errors = {}
+        # Guards @clients / @last_errors writes during the PARALLEL connect phase
+        # (start_all!). The single-server path (start_server) takes it too, so the
+        # invariant "shared-state mutations are serialized" holds on every caller.
+        @state_mutex = Mutex.new
         route_mcp_logging!
       end
 
-      # Initializes all configured MCP servers
+      # Initializes all configured MCP servers.
+      #
+      # The connect handshake is the slow part: each RubyLLM::MCP.client(**opts)
+      # blocks up to the per-server request_timeout (default 8 s) while it spawns
+      # the child / opens the socket and waits for `initialize`. Done SERIALLY, N
+      # hanging servers cost the SUM of their timeouts (#576 measured 17.6 s with
+      # two stalling servers). So we connect every server CONCURRENTLY — one
+      # thread each (the count is small and these threads are I/O-bound) — which
+      # bounds total connect time to roughly the slowest SINGLE server.
+      #
+      # Thread-safety: each thread only does the network/subprocess connect and
+      # writes its result into @clients/@last_errors UNDER @state_mutex (plain
+      # Hashes are not thread-safe). Tool registration is deferred to the MAIN
+      # thread (register_all_tools! below, after every join) because
+      # Tools::Registry is a process-wide singleton over a plain Hash and is NOT
+      # thread-safe. Best-effort semantics are preserved: start_server rescues
+      # per-server, so one server raising/stalling never aborts the others.
       def start_all!
         server_configs = @config.dig("mcp", "servers") || {}
 
-        server_configs.each do |name, server_config|
-          start_server(name, server_config)
+        threads = server_configs.map do |name, server_config|
+          Thread.new { start_server(name, server_config) }
         end
+        threads.each(&:join)
 
         register_all_tools!
         @clients
@@ -38,14 +59,19 @@ module Rubino
         transport = server_config["transport"] || "stdio"
         client_opts = build_client_options(name, transport, server_config)
 
+        # The slow, blocking connect runs OUTSIDE the lock so concurrent
+        # start_all! threads actually overlap; only the shared-Hash writes are
+        # serialized under @state_mutex.
         client = RubyLLM::MCP.client(**client_opts)
-        @clients[name.to_s] = client
-        @last_errors.delete(name.to_s)
+        @state_mutex.synchronize do
+          @clients[name.to_s] = client
+          @last_errors.delete(name.to_s)
+        end
 
         Rubino.event_bus.emit(:mcp_server_started, name: name)
         client
       rescue StandardError => e
-        @last_errors[name.to_s] = e.message
+        @state_mutex.synchronize { @last_errors[name.to_s] = e.message }
         Rubino.ui.warning("MCP server '#{name}' failed to start: #{e.message}")
         nil
       end
@@ -79,8 +105,13 @@ module Rubino
       # Per-agent mcp_servers scoping is NOT applied here — it lives in
       # Agent::Definition#resolved_tools (#173), the single seam every
       # consumer of an agent's tool set goes through.
+      # Registers in a STABLE order (sorted by server name) rather than @clients'
+      # insertion order — under the parallel start_all! @clients is populated in
+      # connect-COMPLETION order, which is nondeterministic. Sorting keeps the
+      # resulting tool-registration order (and anything downstream that reads it)
+      # deterministic across boots.
       def register_all_tools!
-        @clients.each_key { |server_name| register_server_tools(server_name) }
+        @clients.keys.sort.each { |server_name| register_server_tools(server_name) }
       end
 
       # Registers ONE started server's tools — the `/mcp <server> on` path
@@ -94,11 +125,24 @@ module Rubino
           wrapped = MCPToolWrapper.new(mcp_tool, server_name: name.to_s)
           Tools::Registry.register(wrapped)
         end
+        # A clean tools/list clears any prior failure so a recovered server
+        # stops showing degraded (mirrors start_server clearing on success).
+        @last_errors.delete(name.to_s)
       rescue StandardError => e
+        # Record the failure so /mcp's drill-in (and the degraded glyph below)
+        # can explain a connected-but-toolless server (#575) — start_server
+        # records start failures the same way; a swallowed warning alone left
+        # the broken state invisible.
+        @last_errors[name.to_s] = e.message
         Rubino.ui.warning("Failed to load tools from '#{name}': #{e.message}")
       end
 
-      # Checks health of all connected servers
+      # Checks health of all connected servers. `alive` is process-liveness
+      # (the child is up); `degraded` is protocol-liveness (#575): the process
+      # is alive but tools/list/registration failed, so a recorded last_error
+      # exists despite a live client. Callers render degraded distinctly from
+      # plain reachable — an alive server that legitimately exposes zero tools
+      # has NO last_error and is NOT degraded.
       def health_check
         @clients.map do |name, client|
           alive = begin
@@ -106,7 +150,7 @@ module Rubino
           rescue StandardError
             false
           end
-          { name: name, alive: alive }
+          { name: name, alive: alive, degraded: alive && @last_errors.key?(name.to_s) }
         end
       end
 
@@ -154,7 +198,7 @@ module Rubino
         when "stdio"
           opts[:config] = {
             command: server_config["command"],
-            args: server_config["args"] || [],
+            args: validate_stdio_args!(name, server_config["args"]),
             env: server_config["env"] || {}
           }
         when "sse"
@@ -175,6 +219,23 @@ module Rubino
 
         opts
       end
+
+      # stdio `args` MUST be a list (YAML sequence). A STRING — the natural typo,
+      # `args: "--root /data"` instead of `args: ["--root", "/data"]` — used to be
+      # passed straight to ruby_llm-mcp, which iterated the string into single
+      # characters, spawned a broken process, and surfaced ~8s later as a
+      # misleading "timed out" (the spawn never spoke MCP). Reject it HERE so
+      # start_server's rescue turns it into an immediate, clear config error
+      # instead of a hang. nil ⇒ no args (default []).
+      def validate_stdio_args!(name, args)
+        return [] if args.nil?
+        return args if args.is_a?(Array)
+
+        raise ArgumentError,
+              "MCP server '#{name}': `args` must be a list, got #{args.class} " \
+              "(#{args.inspect}). Use a YAML sequence, e.g. " \
+              "args: [\"--root\", \"/data\"] (not a single string)."
+      end
     end
   end
 end

data/lib/rubino/mcp/mcp_tool_wrapper.rb

@@ -7,14 +7,21 @@ module Rubino
     class MCPToolWrapper < Tools::Base
       attr_reader :mcp_tool, :server_name
 
+      # Cap on the (prefixed) tool name length. A misbehaving MCP server can
+      # advertise an absurdly long tool name (e.g. 20k chars), which would be
+      # registered uncapped, blow up the `tools` table, and 400 at the provider.
+      MAX_NAME_LENGTH = 64
+
       def initialize(mcp_tool, server_name:)
         @mcp_tool = mcp_tool
         @server_name = server_name
       end
 
       def name
-        # Prefix with server name to avoid collisions
-        "#{@server_name}_#{@mcp_tool.name}"
+        # Prefix with server name to avoid collisions. Cap the length so a
+        # hostile/buggy server can't register a giant name that breaks the
+        # `tools` table or 400s the provider (S1-MCP-2).
+        "#{@server_name}_#{@mcp_tool.name}"[0, MAX_NAME_LENGTH]
       end
 
       def description
@@ -28,7 +35,11 @@ module Rubino
         # {}`, so the model had to guess argument names and every call failed
         # server-side validation with -32602 (#170).
         schema = @mcp_tool.params_schema if @mcp_tool.respond_to?(:params_schema)
-        schema || { type: "object", properties: {} }
+        # Coerce anything that isn't a Hash (nil, or a truthy non-Hash like a
+        # string) to a valid empty object schema. A server advertising a
+        # non-Hash `inputSchema` would otherwise poison the whole wire tool
+        # list and 400 every subsequent model call (S1-MCP-1).
+        schema.is_a?(Hash) ? schema : { type: "object", properties: {} }
       end
 
       def risk_level
@@ -36,6 +47,30 @@ module Rubino
         :medium
       end
 
+      # True: this tool's code runs on an external MCP server. The display layer
+      # reads this (NOT the name shape) to mark the call/approval card.
+      def mcp?
+        true
+      end
+
+      # The MCP server this tool is provided by, used in the display marker.
+      def mcp_server
+        @server_name
+      end
+
+      # The original, UNPREFIXED tool name the server advertised (#name returns
+      # the collision-safe `<server>_<tool>` registry/model-facing name).
+      def bare_name
+        @mcp_tool.name
+      end
+
+      # The display label for the live tool card and approval card:
+      # `"<bare_tool> (mcp:<server>)"` — e.g. `echo (mcp:chaos)`. The
+      # model-facing #name (`chaos_echo`) is unchanged; this is display-only.
+      def display_name
+        "#{bare_name} (mcp:#{@server_name})"
+      end
+
       def call(arguments)
         result = @mcp_tool.execute(**symbolize_keys(arguments))
         # ruby_llm-mcp reports tool failures by RETURNING `{ error: "…" }`

data/lib/rubino/memory/aux_retry.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Memory
+    # Bounded retry/backoff for the aux memory-extraction call (r5 C-2).
+    #
+    # The aux client calls the adapter directly and so — unlike the main
+    # conversation loop, whose Agent::ModelCallRunner owns retry/backoff — got NO
+    # retry: under concurrent load a single RubyLLM::RateLimitError (429) was
+    # caught at the call site, logged `memory.sqlite.skip`, and the extracted
+    # fact was DROPPED for good. This mixin wraps the aux call in the SAME
+    # jittered-backoff policy the main loop uses, retrying retryable errors
+    # (429/overloaded/5xx/transport, per LLM::ErrorClassifier) up to a small
+    # budget and honouring Retry-After on a rate-limit. After the budget is
+    # exhausted (or on a non-retryable error) it re-raises to the caller, which
+    # leaves the per-session cursor put so the turn is re-fed next time rather
+    # than silently lost.
+    #
+    # Host requirements: `@config` (a Config::Configuration answering #dig) and a
+    # `DEFAULT_EXTRACT_MAX_RETRIES` constant on the including class.
+    module AuxRetry
+      # Run `block` (the aux call), retrying transient errors. Re-raises the last
+      # error once the budget is exhausted or the error is non-retryable.
+      def with_aux_retry
+        attempts = 0
+        begin
+          # Honour a detached-polishing cancel (Esc to skip): the background
+          # housekeeping thread binds Rubino.aux_cancel_token, so an Esc that
+          # cancelled it must abort BEFORE spending another aux-LLM call rather
+          # than running to completion off-screen (#319).
+          aux_check_cancelled!
+          yield
+        rescue Rubino::Interrupted
+          # Cancellation is terminal — re-raise straight through so the detached
+          # polishing thread unwinds and leaves the cursor put (re-runs next turn).
+          raise
+        rescue StandardError => e
+          classified = LLM::ErrorClassifier.classify(e)
+          raise unless classified.retryable && attempts < extract_max_retries
+
+          attempts += 1
+          wait = aux_backoff.wait_seconds(
+            attempts,
+            base: Agent::BackoffPolicy::ERROR_PATH[:base],
+            max: Agent::BackoffPolicy::ERROR_PATH[:max],
+            retry_after: aux_rate_limit_retry_after(classified, e)
+          )
+          log_aux_retry(e, attempts, wait)
+          # Sleep in short slices so an Esc during the (possibly long, Retry-After
+          # honouring) backoff wait aborts within ~100ms instead of holding the
+          # detached worker for the full window (#319). On the foreground/API
+          # path no token is bound, so this is one uninterrupted sleep as before.
+          aux_cancellable_sleep(wait)
+          retry
+        end
+      end
+
+      private
+
+      # Raise Interrupted when the detached-polishing cancel token (if bound for
+      # this thread) has been flipped. No-op when no token is bound.
+      def aux_check_cancelled!
+        Rubino.aux_cancel_token&.check!
+      end
+
+      # Sleep +seconds+ in small slices, polling the aux cancel token between
+      # slices so a cancel aborts the wait promptly. Falls back to a single
+      # sleep when no token is bound (no detached polishing).
+      def aux_cancellable_sleep(seconds)
+        token = Rubino.aux_cancel_token
+        return aux_backoff.sleep(seconds) unless token
+
+        remaining = seconds.to_f
+        while remaining.positive?
+          token.check!
+          slice = [remaining, 0.1].min
+          aux_backoff.sleep(slice)
+          remaining -= slice
+        end
+        token.check!
+      end
+
+      def extract_max_retries
+        @config.dig("memory", "extract_max_retries") ||
+          self.class::DEFAULT_EXTRACT_MAX_RETRIES
+      end
+
+      def aux_backoff
+        @aux_backoff ||= Agent::BackoffPolicy.new
+      end
+
+      # Honour Retry-After only on a rate-limit, exactly as the main loop does.
+      def aux_rate_limit_retry_after(classified, error)
+        return unless classified.reason == LLM::FailoverReason::RATE_LIMIT
+
+        aux_backoff.parse_retry_after(error)
+      end
+
+      def log_aux_retry(error, attempt, wait)
+        Rubino.logger.warn(event: "memory.sqlite.extract_retry",
+                           attempt: attempt, sleep: wait, error: error.class.name)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rubino/memory/backends/sqlite.rb

@@ -7,10 +7,10 @@ require "time"
 module Rubino
   module Memory
     module Backends
-      # "Tiny-Zep" memory backend on embedded SQLite (Zep/Graphiti-inspired,
-      # minus the graph DB, the server, and the six-LLM-call pipeline).
+      # LLM-extracted, bi-temporal fact store on embedded SQLite with hybrid
+      # recall — minus a graph DB, a server, or a multi-LLM-call pipeline.
       #
-      # Three ideas are kept from Zep:
+      # Three ideas drive the design:
       #   * ATOMIC LLM-extracted facts (one declarative fact per row), via a
       #     single aux-LLM call per turn that both ADDs new facts and SUPERSEDES
       #     contradicted ones (Graphiti edge-invalidation, collapsed to 1 call).
@@ -28,12 +28,22 @@ module Rubino
       # tainted or over-budget content into a future system prompt.
       class Sqlite < Backend
         include SqliteGraph
+        include SqliteExtraction
+        include SalienceGate
+        include AuxRetry
 
         TABLE = :memory_facts
         FTS   = :memory_facts_fts
         RRF_K = 60
         DEFAULT_K = 20
 
+        # Bounded retry budget for the aux extraction call on a transient error
+        # (429/overloaded/5xx). Small by design: extraction is best-effort
+        # background work, and the per-session cursor re-feeds an exhausted turn
+        # next time, so we ride out a brief rate-limit window without piling up
+        # background backoff. Overridable via `memory.extract_max_retries`.
+        DEFAULT_EXTRACT_MAX_RETRIES = 3
+
         # Weighted-RRF list weights for the DIRECT relevance signals (FTS/BM25 and
         # vector KNN). Graph (1-hop) and recency are no longer fused here — they
         # are tail supplements (see #rank) so they can never outrank a direct
@@ -84,9 +94,17 @@ module Rubino
         # -- WRITE path --
 
         def store(kind:, content:, source_session_id: nil, confidence: 1.0, metadata: {})
+          k = normalize_kind(kind)
+          # Exact/normalized-verbatim dedup at the direct write seam (#Y4):
+          # MemoryTool#add bypasses the extraction near-dup gate, so the same fact
+          # saved twice used to mint two identical rows. Idempotent — a verbatim
+          # repeat (or whitespace/case variant) returns the existing row.
+          existing = verbatim_duplicate(k, content)
+          return present(existing) if existing
+
           insert_fact(
             text: content,
-            kind: normalize_kind(kind),
+            kind: k,
             entities: Array(metadata[:entities]),
             source_session_id: source_session_id,
             confidence: confidence,
@@ -122,17 +140,40 @@ module Rubino
           target
         end
 
-        # ONE aux-LLM call over the recent turn(s): returns {add, supersede}.
+        # ONE aux-LLM call over the turn's NEW messages: returns {add, supersede}.
         # Apply is pure Ruby — insert adds (deduped + guarded), retire
         # superseded rows and insert their replacement.
+        #
+        # Per-session cursor (#249): only messages newer than the session's
+        # `memory_extracted_msg_id` watermark are fed, so each turn's extraction
+        # is bounded to that turn's new messages instead of an overlapping
+        # recency window. When a turn added nothing new past the cursor, we skip
+        # the aux-LLM call entirely (no redundant duplicate extraction pass), and
+        # advance the cursor only once the apply has landed.
         def extract(session_id)
-          turn = recent_turn_text(session_id)
+          new_messages = unextracted_messages(session_id)
+          turn = turn_text(new_messages)
           return [] if turn.strip.empty?
 
+          # Salience gate (r5 F5/F6/F7): a greeting, a one-word "help", or any
+          # turn whose USER text asserts nothing durable is a NOOP — skip the aux
+          # call AND advance the cursor so it never mints a fact nor gets re-fed.
+          unless salient?(turn)
+            advance_extraction_cursor(session_id, new_messages)
+            return []
+          end
+
           result = call_llm(session_id: session_id, turn: turn)
+          # A nil result means the aux call failed/parsed to nothing — leave the
+          # cursor put so this turn's messages are retried next time rather than
+          # silently dropped. A parsed result (even an empty {add,supersede})
+          # means these messages WERE processed: advance the watermark so they're
+          # never re-fed, which is the overlapping-window re-work #249 removes.
           return [] unless result
 
-          apply(result, session_id)
+          stored = apply(result, session_id)
+          advance_extraction_cursor(session_id, new_messages)
+          stored
         end
 
         # -- READ path --
@@ -144,7 +185,7 @@ module Rubino
           return nil if rows.empty?
 
           text = rows.map { |r| r[:text] }.join("\n")
-          limit = @config.memory_user_char_limit
+          limit = @config.dig("memory", "user_char_limit")
           text.length > limit ? text[0...limit] : text
         end
 
@@ -164,7 +205,7 @@ module Rubino
         # ({id:, kind:, content:, ...}) so the prompt assembler is unchanged.
         def retrieve(session_id:, query: nil, k: DEFAULT_K)
           ranked = rank(query: query, k: k)
-          budget = @config.memory_char_limit
+          budget = @config.dig("memory", "memory_char_limit")
           selected = []
           total = 0
           ranked.each do |row|
@@ -191,12 +232,19 @@ module Rubino
         end
 
         def find(id)
-          row = @db[TABLE].where(Sequel.like(:id, "#{id}%")).first
+          row = resolve_row(id)
           row && present(row)
         end
 
         def delete(id)
-          @db[TABLE].where(Sequel.like(:id, "#{id}%")).delete.positive?
+          row = resolve_row(id)
+          row ? @db[TABLE].where(id: row[:id]).delete.positive? : false
+        end
+
+        # Resolve a caller-supplied id to AT MOST ONE row (shared with Store,
+        # parameterized by this backend's dataset).
+        def resolve_row(id)
+          Memory.resolve_row(@db[TABLE], id)
         end
 
         # Count only LIVE facts (valid_to IS NULL) — retired/superseded rows are
@@ -375,6 +423,12 @@ module Rubino
         # default extractor, which silently skips dups).
         def guarded_insert(text:, kind:, entities:, session_id:, valid_from:, id: nil)
           return nil if text.to_s.strip.empty?
+          # NOOP error-derived tool-limitation claims (#69): after a transient
+          # tool failure the aux model can mint a durable-looking "the tool can't
+          # edit non-ASCII files" — a meta claim that is often wrong and primes
+          # future refusals. Drop it here, the single insert choke point shared by
+          # add[] and supersede[], so neither path can persist one.
+          return nil if tool_limitation_claim?(text)
 
           insert_fact(
             text: text, kind: normalize_kind(kind), entities: Array(entities),
@@ -463,6 +517,16 @@ module Rubino
           str.to_s.downcase.split(/\W+/).reject(&:empty?).to_set
         end
 
+        # First LIVE fact of `kind` whose normalized-verbatim form equals the
+        # candidate's (trim/collapse-whitespace + case-fold, #Y4), or nil.
+        def verbatim_duplicate(kind, content)
+          target = Deduplicator.normalize_verbatim(content)
+          return nil if target.empty?
+
+          live_dataset.where(kind: kind).all
+                      .find { |row| Deduplicator.normalize_verbatim(row[:text]) == target }
+        end
+
         # ---- guards (ThreatScanner + char-budget, same floor as Store) ----
 
         def enforce_guards!(kind, text)
@@ -474,21 +538,18 @@ module Rubino
 
         def enforce_char_budget!(kind, text)
           group = kind == USER_KIND ? "user" : "memory"
-          # INGEST cap, decoupled from the injection budget. `memory_char_limit`
+          # INGEST cap, decoupled from the injection budget. memory.memory_char_limit
           # bounds only what `retrieve` packs into the prompt; storing facts is
-          # gated by `memory_ingest_char_limit` (nil => unbounded) so long
+          # gated by memory.ingest_char_limit (nil => unbounded) so long
           # multi-session conversations don't stall once the injection budget
           # fills. User facts keep their own (small) profile budget.
-          limit = group == "user" ? @config.memory_user_char_limit : @config.memory_ingest_char_limit
+          key = group == "user" ? "user_char_limit" : "ingest_char_limit"
+          limit = @config.dig("memory", key)
           return unless limit&.positive?
 
-          current = current_chars(group)
-          requested = text.to_s.length
-          return if current + requested <= limit
-
-          raise Store::BudgetExceededError.new(
-            group: group, limit: limit, current: current, requested: requested
-          )
+          Memory.enforce_budget!(group: group, limit: limit,
+                                 current: current_chars(group),
+                                 requested: text.to_s.length)
         end
 
         # Budget is metered over LIVE facts only — superseded rows don't count
@@ -501,55 +562,35 @@ module Rubino
 
         # ---- LLM ----
 
+        # ONE aux-LLM extraction call, retried on a transient error via AuxRetry
+        # (r5 C-2): a 429/overloaded/5xx backs off (honouring Retry-After) and
+        # retries up to `memory.extract_max_retries` instead of dropping the fact
+        # on the first RateLimitError. Only after the budget is exhausted (or on a
+        # non-retryable error) do we rescue and return nil — and the caller leaves
+        # the cursor put on nil, so even an exhausted turn is re-fed next time
+        # rather than silently lost.
         def call_llm(session_id:, turn:)
-          response = aux_client.call(
-            task: :compression,
-            messages: [
-              { role: "system", content: SqliteExtractionPrompt::SYSTEM },
-              { role: "user", content: SqliteExtractionPrompt.user_message(
-                now: Time.now.utc.iso8601, live_facts: live_facts_for_prompt, turn: turn
-              ) }
-            ]
-          )
-          parse_json(response&.content)
+          with_aux_retry do
+            response = aux_client.call(
+              task: :compression,
+              messages: [
+                { role: "system", content: SqliteExtractionPrompt::SYSTEM },
+                { role: "user", content: SqliteExtractionPrompt.user_message(
+                  now: Time.now.utc.iso8601, live_facts: live_facts_for_prompt, turn: turn
+                ) }
+              ]
+            )
+            parse_json(response&.content)
+          end
         rescue StandardError => e
           log_skip(e)
           nil
         end
 
-        def live_facts_for_prompt
-          live_dataset.order(Sequel.desc(:created_at)).limit(60).all.map do |r|
-            { id: r[:id][0, 8], kind: r[:kind], text: r[:text] }
-          end
-        end
-
-        # The aux model may wrap JSON in prose or a fenced block; extract the
-        # outermost object and parse leniently.
-        def parse_json(content)
-          return nil if content.to_s.strip.empty?
-
-          str = content[/\{.*\}/m] || content
-          JSON.parse(str)
-        rescue JSON::ParserError
-          nil
-        end
-
         def aux_client
           @aux_client ||= LLM::AuxiliaryClient.new(config: @config)
         end
 
-        def recent_turn_text(session_id)
-          msgs = Session::Store.new(db: @db).recent(session_id, count: 6)
-          msgs.filter_map do |m|
-            next if m.content.nil? || m.content.to_s.empty?
-            next unless %w[user assistant].include?(m.role)
-
-            "#{m.role.upcase}: #{m.content}"
-          end.join("\n")
-        rescue StandardError
-          ""
-        end
-
         # ---- embeddings (best-effort) ----
 
         # Vector mode is opt-in (`memory.sqlite.vector: true`) AND requires
@@ -585,13 +626,9 @@ module Rubino
           nil
         end
 
-        def encode_embedding(vec)
-          vec.pack("e*")
-        end
+        def encode_embedding(vec) = vec.pack("e*")
 
-        def decode_embedding(blob)
-          blob && blob.to_s.unpack("e*")
-        end
+        def decode_embedding(blob) = blob && blob.to_s.unpack("e*")
 
         def cosine(a, b)
           return 0.0 if a.empty? || b.empty? || a.size != b.size
@@ -608,7 +645,7 @@ module Rubino
           k = kind.to_s
           return USER_KIND if k.empty?
 
-          # Map legacy/default-backend kinds onto the tiny-Zep vocabulary so the
+          # Map legacy/default-backend kinds onto the fact-store vocabulary so the
           # backend tolerates store() calls from the existing MemoryTool/job.
           case k
           when "user_profile", "preference", "fact", "env" then k

data/lib/rubino/memory/backends.rb

@@ -4,9 +4,10 @@ module Rubino
   module Memory
     # Registry of pluggable memory backends, mirroring Tools::Registry: a
     # name => class map with register/build. The active backend is selected by
-    # the `memory.backend` config key (default "sqlite" — the tiny-Zep FTS5/
-    # graph-lite backend). DEFAULT_NAME below is the registry fallback used only
-    # when the configured name is blank/unknown.
+    # the `memory.backend` config key (default "sqlite" — the FTS5/
+    # graph-lite SQLite backend). DEFAULT_NAME below is the registry fallback used only
+    # when the configured name is BLANK/unset. An explicitly-set UNKNOWN name is
+    # a misconfiguration (a typo silently degrading memory) → rejected.
     module Backends
       @registry = {}
 
@@ -29,25 +30,40 @@ module Rubino
           @registry[name.to_s]
         end
 
-        # Builds the configured backend instance. Falls back to the default
-        # backend when `memory.backend` is unset or names an unknown backend,
-        # so a stale config never breaks the interaction.
+        # Builds the configured backend instance. A BLANK/unset `memory.backend`
+        # falls back to the default backend (so a fresh config just works); an
+        # explicitly-set name that names NO registered backend is a typo that
+        # would otherwise silently degrade to the default — reject it with a
+        # clear error listing the known backends instead.
         def build(config: nil)
           cfg = config || Rubino.configuration
-          name = cfg.dig("memory", "backend").to_s
-          klass = @registry[name] || @registry[DEFAULT_NAME]
-          raise Error, "no memory backend registered (looked for #{name.inspect})" unless klass
+          name = cfg.dig("memory", "backend").to_s.strip
+          klass = name.empty? ? @registry[DEFAULT_NAME] : @registry[name]
+
+          unless klass
+            raise Error, unknown_backend_message(name) unless name.empty?
+
+            raise Error, "no memory backend registered (looked for #{DEFAULT_NAME.inspect})"
+          end
 
           klass.new(config: cfg)
         end
 
+        # A clear, actionable rejection for an unknown `memory.backend` name,
+        # listing the registered backends so the user can fix the typo.
+        def unknown_backend_message(name)
+          known = names.sort.join(", ")
+          "unknown memory backend #{name.inspect}: set memory.backend to one of " \
+            "[#{known}] (or leave it unset for the default)."
+        end
+
         # For tests.
         def reset!
           @registry = {}
         end
       end
 
-      DEFAULT_NAME = "default"
+      DEFAULT_NAME = "sqlite"
     end
   end
 end