rails_console_ai 0.31.0 → 0.33.0

data/lib/rails_console_ai/configuration.rb

@@ -1,39 +1,77 @@
-require 'set'
-
 module RailsConsoleAi
   class Configuration
     PROVIDERS = %i[anthropic openai local bedrock].freeze
 
-    # cache_read: 0.1x input, cache_write: 1.25x input for Anthropic models
-    PRICING = {
-      'claude-sonnet-4-6' => { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000, cache_read: 0.30 / 1_000_000, cache_write: 3.75 / 1_000_000 },
-      'claude-opus-4-6'   => { input: 15.0 / 1_000_000, output: 75.0 / 1_000_000, cache_read: 1.50 / 1_000_000, cache_write: 18.75 / 1_000_000 },
-      'claude-haiku-4-5-20251001' => { input: 0.80 / 1_000_000, output: 4.0 / 1_000_000, cache_read: 0.08 / 1_000_000, cache_write: 1.0 / 1_000_000 },
-      # Bedrock model IDs (same pricing as direct API)
-      'us.anthropic.claude-sonnet-4-6' => { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000, cache_read: 0.30 / 1_000_000, cache_write: 3.75 / 1_000_000 },
-      'us.anthropic.claude-opus-4-6-v1' => { input: 15.0 / 1_000_000, output: 75.0 / 1_000_000, cache_read: 1.50 / 1_000_000, cache_write: 18.75 / 1_000_000 },
+    # Per-family model attributes, matched by substring so one entry covers every
+    # ID variant of a family: bare Anthropic IDs (claude-sonnet-5), dated
+    # snapshots (claude-haiku-4-5-20251001), and Bedrock inference profiles
+    # (us.anthropic.claude-sonnet-5, global.anthropic.claude-opus-4-6-v1).
+    #
+    # input/output are $ per MTok (converted to per-token in .pricing_for).
+    # Cache pricing is derived: read = 0.1x input, write = 1.25x input.
+    # temperature: false marks families that reject the `temperature` parameter
+    # (removed on opus-4-7+, sonnet-5, and fable-5).
+    MODEL_FAMILIES = {
+      'claude-fable-5'    => { input: 10.0, output: 50.0, max_tokens: 16_000, temperature: false },
+      'claude-opus-5'     => { input: 5.0,  output: 25.0, max_tokens: 16_000, temperature: false },
+      'claude-opus-4-8'   => { input: 5.0,  output: 25.0, max_tokens: 16_000, temperature: false },
+      'claude-opus-4-7'   => { input: 5.0,  output: 25.0, max_tokens: 16_000, temperature: false },
+      'claude-opus-4-6'   => { input: 5.0,  output: 25.0, max_tokens: 16_000, temperature: true },
+      'claude-sonnet-5'   => { input: 3.0,  output: 15.0, max_tokens: 16_000, temperature: false },
+      'claude-sonnet-4-6' => { input: 3.0,  output: 15.0, max_tokens: 16_000, temperature: true },
+      'claude-haiku-4-5'  => { input: 1.0,  output: 5.0,  max_tokens: 16_000, temperature: true },
     }.freeze
 
-    DEFAULT_MAX_TOKENS = {
-      'claude-sonnet-4-6' => 16_000,
-      'claude-haiku-4-5-20251001' => 16_000,
-      'claude-opus-4-6'   => 4_096,
-    }.freeze
+    # Family keys sorted longest-first so a more specific family always wins
+    # if keys ever overlap (e.g. a future 'claude-sonnet-5-5' entry would match
+    # before 'claude-sonnet-5').
+    MODEL_FAMILY_KEYS = MODEL_FAMILIES.keys.sort_by { |k| -k.length }.freeze
+
+    # Returns the family attributes for a model ID, or nil for unknown models.
+    def self.model_family(model_id)
+      return nil unless model_id
+      key = MODEL_FAMILY_KEYS.find { |k| model_id.include?(k) }
+      key && MODEL_FAMILIES[key]
+    end
+
+    # Per-token pricing for a model ID, matched by family. Returns
+    # { input:, output:, cache_read:, cache_write: } or nil for unknown models.
+    def self.pricing_for(model_id)
+      family = model_family(model_id)
+      return nil unless family
+      input = family[:input] / 1_000_000
+      {
+        input: input,
+        output: family[:output] / 1_000_000,
+        cache_read: input * 0.1,
+        cache_write: input * 1.25,
+      }
+    end
 
-    # Models that reject the `temperature` parameter. Configuration#resolved_temperature
-    # returns nil for these so providers can omit the field from the request.
-    MODELS_WITHOUT_TEMPERATURE = Set.new(%w[
-      claude-opus-4-7
-      anthropic.claude-opus-4-7
-      us.anthropic.claude-opus-4-7
-      eu.anthropic.claude-opus-4-7
-      jp.anthropic.claude-opus-4-7
-      global.anthropic.claude-opus-4-7
-    ]).freeze
+    # Known environment-level failures the executor recognizes and explains to the
+    # LLM on the FIRST occurrence, so it doesn't burn rounds rediscovering them
+    # through trial and error. Each entry: { name:, pattern:, hint: }.
+    # The pattern is matched against the execution error AND the captured output
+    # (to catch errors rescued and printed by the generated code itself).
+    DEFAULT_ERROR_HINTS = [
+      {
+        name: :decryption_failure,
+        pattern: /OpenSSL::Cipher::CipherError|bad decrypt|ActiveRecord::Encryption::Errors/i,
+        hint: "Decryption failed — this console process's encryption key (e.g. ENV['ENCRYPTION_KEY']) " \
+              "appears to be missing, invalid, or a placeholder for the data you are reading. This is an " \
+              "environment configuration issue, not a data issue, and it affects EVERY encrypted field in " \
+              "this session. Retrying with different code (reloading records, toggling encryption flags, " \
+              "decrypting other fields or records) will fail the same way. Do NOT retry. Report this " \
+              "limitation to the user, tell them the encryption key needs to be configured for this " \
+              "environment, and answer using only what you can determine without decrypting."
+      }
+    ].freeze
 
     attr_accessor :provider, :api_key, :model, :thinking_model, :max_tokens,
                   :auto_execute, :temperature,
                   :timeout, :debug, :max_tool_rounds,
+                  :error_hints,
+                  :token_nudge_threshold, :token_stop_threshold,
                   :storage_adapter, :memories_enabled,
                   :session_logging, :connection_class,
                   :admin_username, :admin_password,
@@ -59,6 +97,9 @@ module RailsConsoleAi
       @timeout      = 30
       @debug        = false
       @max_tool_rounds = 200
+      @error_hints = DEFAULT_ERROR_HINTS.dup
+      @token_nudge_threshold = 500_000    # input tokens in one tool loop → nudge model to wrap up (nil disables)
+      @token_stop_threshold  = 1_000_000  # input tokens in one tool loop → force a final answer (nil disables)
       @storage_adapter  = nil
       @memories_enabled = true
       @session_logging  = true
@@ -176,26 +217,28 @@ module RailsConsoleAi
 
       case @provider
       when :anthropic
-        'claude-sonnet-4-6'
+        'claude-sonnet-5'
       when :openai
         'gpt-5.3-codex'
       when :local
         @local_model
       when :bedrock
-        'us.anthropic.claude-sonnet-4-6'
+        'us.anthropic.claude-sonnet-5'
       end
     end
 
     def resolved_max_tokens
       return @max_tokens if @max_tokens
 
-      DEFAULT_MAX_TOKENS.fetch(resolved_model, 4096)
+      family = self.class.model_family(resolved_model)
+      family ? family[:max_tokens] : 4096
     end
 
-    # Returns nil for models that reject the `temperature` parameter (e.g. opus-4-7).
-    # Providers should use this in place of @temperature.
+    # Returns nil for model families that reject the `temperature` parameter
+    # (opus-4-7+, sonnet-5, fable-5) so providers omit the field from the request.
     def resolved_temperature
-      return nil if MODELS_WITHOUT_TEMPERATURE.include?(resolved_model)
+      family = self.class.model_family(resolved_model)
+      return nil if family && family[:temperature] == false
       @temperature
     end
 
@@ -204,13 +247,13 @@ module RailsConsoleAi
 
       case @provider
       when :anthropic
-        'claude-opus-4-6'
+        'claude-opus-5'
       when :openai
         'gpt-5.3-codex'
       when :local
         @local_model
       when :bedrock
-        'us.anthropic.claude-opus-4-6-v1'
+        'us.anthropic.claude-opus-5'
       end
     end
 

data/lib/rails_console_ai/conversation_engine.rb

@@ -7,6 +7,8 @@ module RailsConsoleAi
     LARGE_OUTPUT_PREVIEW_CHARS = 16_000  # chars — how much of the output the LLM sees upfront
     LOOP_WARN_THRESHOLD = 3              # same tool+args repeated → inject warning
     LOOP_BREAK_THRESHOLD = 5             # same tool+args repeated → break loop
+    REPEAT_ERROR_WARN_THRESHOLD = 3      # same error signature (any args) → inject warning
+    REPEAT_ERROR_BREAK_THRESHOLD = 5     # same error signature (any args) → force wrap-up
 
     def initialize(binding_context:, channel:, slack_thread_ts: nil, slack_channel_name: nil)
       @binding_context = binding_context
@@ -46,6 +48,7 @@ module RailsConsoleAi
         if executed && @executor.last_error && !@executor.last_safety_error
           error_msg = "Code execution failed with error: #{@executor.last_error}"
           error_msg = error_msg[0..1000] + '...' if error_msg.length > 1000
+          error_msg += "\n\n#{@executor.last_error_hint}" if @executor.last_error_hint
           conversation << { role: :assistant, content: @_last_result_text }
           conversation << { role: :user, content: error_msg }
 
@@ -347,6 +350,7 @@ module RailsConsoleAi
       elsif @executor.last_error
         error_msg = "Code execution failed with error: #{@executor.last_error}"
         error_msg = error_msg[0..1000] + '...' if error_msg.length > 1000
+        error_msg += "\n\n#{@executor.last_error_hint}" if @executor.last_error_hint
         @history << { role: :user, content: error_msg }
         :error
       else
@@ -390,7 +394,7 @@ module RailsConsoleAi
       $stdout.puts "\e[36m  Cost estimate:\e[0m"
 
       @token_usage.each do |model, usage|
-        pricing = Configuration::PRICING[model]
+        pricing = Configuration.pricing_for(model)
         pricing ||= { input: 0.0, output: 0.0 } if RailsConsoleAi.configuration.provider == :local
         input_str = "in: #{format_tokens(usage[:input])}"
         output_str = "out: #{format_tokens(usage[:output])}"
@@ -796,7 +800,11 @@ module RailsConsoleAi
       last_tool_names = []
 
       exhausted = false
+      wrap_up_reason = nil
       tool_call_counts = Hash.new(0)
+      error_sig_counts = Hash.new(0)
+      warned_error_sigs = Set.new
+      token_nudge_sent = false
 
       max_rounds.times do |round|
         if @channel.cancelled?
@@ -918,6 +926,12 @@ module RailsConsoleAi
             $stderr.puts "\e[35m[debug] tool result (#{tool_result.to_s.length} chars)\e[0m"
           end
 
+          # Track repeated error signatures across DIFFERENT tool calls — the
+          # identical-call loop detection below misses "same dead end, new code".
+          if (sig = error_signature(tool_result))
+            error_sig_counts[sig] += 1
+          end
+
           tool_msg = provider.format_tool_result(tc[:id], tool_result)
           full_text = tool_result.to_s
           output_id = @executor.store_output(full_text)
@@ -942,23 +956,68 @@ module RailsConsoleAi
           if tool_call_counts[key] >= LOOP_BREAK_THRESHOLD
             @channel.display_status("  Loop detected: #{tc[:name]} called #{tool_call_counts[key]} times with same args — stopping.")
             exhausted = true
+            wrap_up_reason ||= :tool_loop
           elsif tool_call_counts[key] >= LOOP_WARN_THRESHOLD
             @channel.display_status("  Warning: #{tc[:name]} called #{tool_call_counts[key]} times with same args — consider a different approach.")
             messages << { role: :user, content: "You are repeating the same tool call (#{tc[:name]}) with the same arguments. This is not making progress. Try a different approach or provide your answer now." }
           end
         end
+
+        # Circuit breaker: the same error signature recurring across different
+        # tool calls means no new information is being gained (e.g. every
+        # decryption attempt failing with "bad decrypt" regardless of the code).
+        error_sig_counts.each do |sig, count|
+          if count >= REPEAT_ERROR_BREAK_THRESHOLD
+            @channel.display_status("  Circuit breaker: same error hit #{count} times (#{sig}) — stopping.")
+            exhausted = true
+            wrap_up_reason ||= :repeated_errors
+          elsif count >= REPEAT_ERROR_WARN_THRESHOLD && !warned_error_sigs.include?(sig)
+            warned_error_sigs << sig
+            @channel.display_status("  Warning: same error hit #{count} times — nudging model to change strategy.")
+            messages << { role: :user, content: "You have now hit the same error #{count} times (#{sig}). Trying variations of the same approach is not producing new information. If this error cannot be resolved from this session, stop investigating it: summarize what you have established, state what you could not determine and why, and give the user your best answer." }
+          end
+        end
+
+        # Circuit breaker: token budget for a single tool loop.
+        config = RailsConsoleAi.configuration
+        if config.token_stop_threshold && total_input >= config.token_stop_threshold
+          @channel.display_status("  Token budget exceeded (#{format_tokens(total_input)} input tokens this request) — forcing wrap-up.")
+          exhausted = true
+          wrap_up_reason ||= :token_budget
+        elsif config.token_nudge_threshold && total_input >= config.token_nudge_threshold && !token_nudge_sent
+          token_nudge_sent = true
+          @channel.display_status("  High token usage (#{format_tokens(total_input)} input tokens this request) — nudging model to wrap up.")
+          messages << { role: :user, content: "This investigation has consumed #{format_tokens(total_input)} input tokens without reaching a conclusion. Wrap up now: stop opening new lines of investigation, summarize what you have established, state what you could not determine and why, and give the user your best answer. Only make another tool call if you are confident a single call will resolve the question." }
+        end
+
         break if exhausted
 
         # If the user declined execution, don't call the LLM again —
         # just return to the prompt so they can correct their request.
         break if @executor.last_cancelled?
 
-        exhausted = true if round == max_rounds - 1
+        if round == max_rounds - 1
+          exhausted = true
+          wrap_up_reason ||= :round_cap
+        end
       end
 
       if exhausted
-        $stdout.puts "\e[33m  Hit tool round limit (#{max_rounds}). Forcing final answer. Increase with: RailsConsoleAi.configure { |c| c.max_tool_rounds = 200 }\e[0m"
-        messages << { role: :user, content: "You've used all available tool rounds. Please provide your best answer now based on what you've learned so far." }
+        final_nudge =
+          case wrap_up_reason
+          when :repeated_errors
+            "You have hit the same error repeatedly without gaining new information. Do not attempt any further tool calls. Give the user a final answer now: (1) what you established, (2) what you could not determine and the blocking error, and (3) what a human should do next."
+          when :token_budget
+            "This session has exceeded its token budget. Do not attempt any further tool calls. Give the user a final answer now: (1) what you established, (2) what you could not determine and why, and (3) what a human should do next."
+          when :tool_loop
+            "You kept repeating the same tool call with the same arguments. Do not attempt any further tool calls. Provide your best answer now based on what you've learned so far."
+          else
+            "You've used all available tool rounds. Please provide your best answer now based on what you've learned so far."
+          end
+        if wrap_up_reason.nil? || wrap_up_reason == :round_cap
+          $stdout.puts "\e[33m  Hit tool round limit (#{max_rounds}). Forcing final answer. Increase with: RailsConsoleAi.configure { |c| c.max_tool_rounds = 200 }\e[0m"
+        end
+        messages << { role: :user, content: final_nudge }
         result = provider.chat(messages, system_prompt: active_system_prompt)
         total_input += result.input_tokens || 0
         total_output += result.output_tokens || 0
@@ -1167,6 +1226,15 @@ module RailsConsoleAi
       str.length > max ? str[0..max] + '...' : str
     end
 
+    # Extract a normalized error signature from a tool result so we can detect
+    # "same failure, different code" loops. Digits are collapsed so record IDs,
+    # counts, and offsets don't make identical failures look distinct.
+    def error_signature(tool_result)
+      line = tool_result.to_s[/^ERROR: [^\n]+/]
+      return nil unless line
+      line.gsub(/\d+/, 'N')[0, 160]
+    end
+
     # Wraps mid-task user messages with explicit framing so the model treats them
     # as a real-time interruption that supersedes the prior task, rather than as
     # a reply to the most recent tool result.
@@ -1386,7 +1454,7 @@ module RailsConsoleAi
       cache_w = result.cache_write_input_tokens || 0
       parts << "cache r: #{format_tokens(cache_r)} w: #{format_tokens(cache_w)}" if cache_r > 0 || cache_w > 0
       model = effective_model
-      pricing = Configuration::PRICING[model]
+      pricing = Configuration.pricing_for(model)
       if pricing
         cost = ((result.input_tokens || 0) * pricing[:input]) + ((result.output_tokens || 0) * pricing[:output])
         if (cache_r > 0 || cache_w > 0) && pricing[:cache_read]
@@ -1419,7 +1487,7 @@ module RailsConsoleAi
       input_t = result.input_tokens || 0
       output_t = result.output_tokens || 0
       model = effective_model
-      pricing = Configuration::PRICING[model]
+      pricing = Configuration.pricing_for(model)
       pricing ||= { input: 0.0, output: 0.0 } if RailsConsoleAi.configuration.provider == :local
 
       cache_r = result.cache_read_input_tokens || 0

data/lib/rails_console_ai/executor.rb

@@ -44,7 +44,8 @@ module RailsConsoleAi
   class Executor
     CODE_REGEX = /```ruby\s*\n(.*?)```/m
 
-    attr_reader :binding_context, :last_error, :last_safety_error, :last_safety_exception
+    attr_reader :binding_context, :last_error, :last_safety_error, :last_safety_exception,
+                :last_error_hint
     attr_accessor :on_prompt
 
     def initialize(binding_context, channel: nil)
@@ -55,6 +56,7 @@ module RailsConsoleAi
       @output_store = {}
       @output_counter = 0
       @active_skill_bypass_methods = Set.new
+      @error_hint_counts = Hash.new(0)
     end
 
     def extract_code(response)
@@ -98,6 +100,7 @@ module RailsConsoleAi
       @last_error = nil
       @last_safety_error = false
       @last_safety_exception = nil
+      @last_error_hint = nil
       captured_output = StringIO.new
       old_stdout = $stdout
       # Three capture strategies:
@@ -140,6 +143,8 @@ module RailsConsoleAi
       display_result(result) if display
 
       @last_output = captured_output.string
+      # Code may have rescued a known failure and printed it — still surface the hint.
+      @last_error_hint = build_error_hint(@last_output)
       result
     rescue Interrupt
       restore_stdout(use_thread_local, old_stdout)
@@ -174,6 +179,7 @@ module RailsConsoleAi
         return nil
       end
       @last_error = "#{e.class}: #{e.message}"
+      @last_error_hint = build_error_hint(@last_error, captured_output&.string)
       backtrace = e.backtrace.first(3).map { |line| "  #{line}" }.join("\n")
       log_execution_error("Error: #{@last_error}\n#{backtrace}")
       @last_output = captured_output&.string
@@ -346,6 +352,29 @@ module RailsConsoleAi
 
     private
 
+    # Match the error/output against configured known-issue patterns
+    # (Configuration#error_hints). Returns a guidance string for the LLM, or nil.
+    # The first occurrence explains the issue; repeats escalate so the model
+    # stops probing the same dead end.
+    def build_error_hint(*texts)
+      text = texts.compact.join("\n")
+      return nil if text.strip.empty?
+
+      hint_def = Array(RailsConsoleAi.configuration.error_hints).find do |h|
+        h[:pattern] && text.match?(h[:pattern])
+      end
+      return nil unless hint_def
+
+      count = (@error_hint_counts[hint_def[:name]] += 1)
+      if count == 1
+        "KNOWN ISSUE DETECTED (#{hint_def[:name]}): #{hint_def[:hint]}"
+      else
+        "KNOWN ISSUE (#{hint_def[:name]}) — this is failure ##{count} for the same underlying problem. " \
+        "You were already told this cannot succeed from this session. Stop retrying now and report the " \
+        "limitation to the user. Reminder: #{hint_def[:hint]}"
+      end
+    end
+
     def restore_stdout(use_thread_local, old_stdout)
       if use_thread_local
         Thread.current[:capture_io] = nil

data/lib/rails_console_ai/safety_guards.rb

@@ -52,6 +52,22 @@ module RailsConsoleAi
       Thread.current[:rails_console_ai_guards_disabled] = true
     end
 
+    # Hard sandbox: block ALL database access (reads and writes) for the duration of the
+    # block. Used to fence in sub-agents that must never touch the DB (e.g. the
+    # output-explorer, which only examines an in-memory string). Scoped via thread-local,
+    # so it covers synchronous work in the calling thread and is restored afterward —
+    # nestable, and independent of enable!/disable! and the registered guard set.
+    def with_database_blocked
+      BuiltinGuards.ensure_write_blocker_installed!
+      prev = Thread.current[:rails_console_ai_block_all_db]
+      Thread.current[:rails_console_ai_block_all_db] = true
+      begin
+        yield
+      ensure
+        Thread.current[:rails_console_ai_block_all_db] = prev
+      end
+    end
+
     def empty?
       @guards.empty?
     end
@@ -213,6 +229,21 @@ module RailsConsoleAi
 
       private
 
+      # Hard sandbox: when active, block ALL database access (reads and writes), not just
+      # mutations. Used to fence in sub-agents that must never touch the DB (e.g. the
+      # output-explorer, which only examines an in-memory string). Deliberately does NOT
+      # honor the bypass flag — it is a true wall, not a safe-mode toggle.
+      def rails_console_ai_check_db_blocked!(_sql)
+        return unless Thread.current[:rails_console_ai_block_all_db]
+
+        raise RailsConsoleAi::SafetyError.new(
+          "Database access is disabled here. The captured data is in the `output` " \
+          "variable — examine that instead of querying the database.",
+          guard: :database_access,
+          blocked_key: nil
+        )
+      end
+
       def rails_console_ai_check_write!(sql)
         return if Thread.current[:rails_console_ai_bypass_guards]
         return unless Thread.current[:rails_console_ai_block_writes] && sql.match?(WRITE_PATTERN)
@@ -231,26 +262,31 @@ module RailsConsoleAi
       public
 
       def execute(sql, *args, **kwargs)
+        rails_console_ai_check_db_blocked!(sql)
         rails_console_ai_check_write!(sql)
         super
       end
 
       def exec_query(sql, *args, **kwargs)
+        rails_console_ai_check_db_blocked!(sql)
         rails_console_ai_check_write!(sql)
         super
       end
 
       def exec_insert(sql, *args, **kwargs)
+        rails_console_ai_check_db_blocked!(sql)
         rails_console_ai_check_write!(sql)
         super
       end
 
       def exec_delete(sql, *args, **kwargs)
+        rails_console_ai_check_db_blocked!(sql)
         rails_console_ai_check_write!(sql)
         super
       end
 
       def exec_update(sql, *args, **kwargs)
+        rails_console_ai_check_db_blocked!(sql)
         rails_console_ai_check_write!(sql)
         super
       end

data/lib/rails_console_ai/slack_bot.rb

@@ -706,7 +706,7 @@ module RailsConsoleAi
       config = RailsConsoleAi.configuration
       model = engine ? engine.effective_model : config.resolved_model
       thinking = config.resolved_thinking_model
-      pricing = Configuration::PRICING[model]
+      pricing = Configuration.pricing_for(model)
 
       lines = ["*Model info:*"]
       lines << "  Provider: `#{config.provider}`"
@@ -739,7 +739,7 @@ module RailsConsoleAi
       total_cost = 0.0
 
       token_usage.each do |model, usage|
-        pricing = Configuration::PRICING[model]
+        pricing = Configuration.pricing_for(model)
         pricing ||= { input: 0.0, output: 0.0 } if RailsConsoleAi.configuration.provider == :local
         input_str = "in: #{usage[:input]}"
         output_str = "out: #{usage[:output]}"

data/lib/rails_console_ai/sub_agent.rb

@@ -189,7 +189,7 @@ module RailsConsoleAi
 
     def build_system_prompt
       parts = []
-      parts << base_instructions
+      parts << base_instructions unless @agent_config['skip_base_instructions']
       parts << guide_context
       parts << pinned_memory_context
       parts << @agent_config['body'] if @agent_config['body'] && !@agent_config['body'].strip.empty?

data/lib/rails_console_ai/tools/memory_tools.rb

@@ -33,10 +33,15 @@ module RailsConsoleAi
             name: name, description: description, tags: tags,
             edited_by: edited_by || 'ai', change_note: change_note
           )
+          status_note = if record.respond_to?(:proposed?) && record.proposed?
+                          ' — status: PROPOSED. A human must approve it at /rails_console_ai/memories before you can recall it.'
+                        else
+                          ''
+                        end
           if was_new
-            "Memory saved (db): \"#{record.name}\" (id=#{record.id})"
+            "Memory saved (db): \"#{record.name}\" (id=#{record.id})#{status_note}"
           else
-            "Memory updated (db): \"#{record.name}\" (id=#{record.id})"
+            "Memory updated (db): \"#{record.name}\" (id=#{record.id})#{status_note}"
           end
         end
       rescue Storage::StorageError => e
@@ -72,8 +77,16 @@ module RailsConsoleAi
       end
 
       def recall_memory(name:)
-        memory = load_all_memories.find { |m| m['name'].to_s.downcase == name.to_s.downcase }
-        return "No memory found: \"#{name}\"" unless memory
+        memory = load_activatable_memories.find { |m| m['name'].to_s.downcase == name.to_s.downcase }
+        unless memory
+          # Distinguish "doesn't exist" from "exists but isn't approved yet".
+          proposed = load_all_memories.find { |m| m['name'].to_s.downcase == name.to_s.downcase }
+          if proposed && proposed['source'] == :db && proposed['status'] != 'approved'
+            return "Memory \"#{name}\" exists but is awaiting human approval and cannot be recalled yet. " \
+                   "Ask the user to approve it in the web UI at /rails_console_ai/memories."
+          end
+          return "No memory found: \"#{name}\""
+        end
 
         record_use(memory)
 
@@ -83,7 +96,7 @@ module RailsConsoleAi
       end
 
       def recall_memories(query: nil, tag: nil)
-        memories = load_all_memories
+        memories = load_activatable_memories
         return "No memories stored yet." if memories.empty?
 
         results = memories
@@ -117,7 +130,7 @@ module RailsConsoleAi
       end
 
       def memory_summaries
-        memories = load_all_memories
+        memories = load_activatable_memories
         return nil if memories.empty?
 
         memories.map { |m|
@@ -127,6 +140,10 @@ module RailsConsoleAi
         }
       end
 
+      # Includes proposed (unapproved) DB memories — they show up in the admin UI
+      # with a "PROPOSED" badge. The AI-facing surface (#memory_summaries,
+      # #recall_memory, #recall_memories) filters them out via
+      # #load_activatable_memories, so an unapproved memory can never be recalled.
       def load_all_memories
         db = Storage::DatabaseStorage.all_memories
         file = load_all_file_memories
@@ -135,6 +152,12 @@ module RailsConsoleAi
         (db + file).sort_by { |m| m['name'].to_s.downcase }
       end
 
+      # Memories the AI is allowed to see / recall: approved DB memories + all file
+      # memories. File memories are considered pre-approved because they're git-tracked.
+      def load_activatable_memories
+        load_all_memories.reject { |m| m['source'] == :db && m['status'] != 'approved' }
+      end
+
       private
 
       # DB-backed memories only — file memories have no row to update.