console_agent 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09b1eab5b0fd84fb27fe9af623c234da290779f84d5972d4a67bfe000d581ab2'
-  data.tar.gz: 344f3afbc67adc4d87c5c2fb4e11ccc902fca071776a4a3aa6cb160783e22998
+  metadata.gz: 53925e32cd4919e550bfdc081ede866613ce3ea18a585aca6cb81d1687ce3901
+  data.tar.gz: ae601be1b81ff2fcb89addda1c008c0646118f2af21c9009a1792556ffd9b4ed
 SHA512:
-  metadata.gz: 73a5c9bd000e30b3cfa63c06efbb0f9619849ec56ca8b4b8f1c71cd7eae29439f9b4ef8d10725950aa8fb813159674820706fa5883784060464f8c9959c914aa
-  data.tar.gz: 4498692aab0860b717b7d309e252cb1b2130b7946a55421f0edd76c3b3469da27c6f8426667e23cf0a2fcab66a356896573f19b819c8ba603f08f50a5e60647d
+  metadata.gz: 54ec67e116e4a05de7a5d915f93dc7babf2d64d2b008bc507718dce92d58ad032beeaa1d7710d8190943454f937f91780ff5614e44f5ef173ab5feff6dddb339
+  data.tar.gz: f12af224368e44b149d740f8d0b2dee4a38ce86564ee9337c5a8ed569a83bb387d3edcf2ae76142d4b510f507c5e6d64d82aab70c16eb94f66d83e3811eb0cd6

data/README.md

@@ -2,6 +2,8 @@
 
 An AI-powered assistant for your Rails console. Ask questions in plain English, get executable Ruby code.
 
+It's like Claude Code embedded in your Rails Console.
+
 ConsoleAgent connects your `rails console` to an LLM (Claude or GPT) and gives it tools to introspect your app's database schema, models, and source code. It figures out what it needs on its own, so you don't pay for 50K tokens of context on every query.
 
 ## Quick Start
@@ -19,19 +21,29 @@ bundle install
 rails generate console_agent:install
 ```
 
-Set your API key and open a console:
+Set your API key (pick one):
 
 ```bash
+# Option A: environment variable
 export ANTHROPIC_API_KEY=sk-ant-...
-rails console
+
+# Option B: in the initializer
+# config.api_key = 'sk-ant-...'
 ```
 
-Then:
+Open a console and go:
 
 ```ruby
+rails console
 ai "show me all users who signed up this week"
 ```
 
+You can also set or change your API key at runtime in the console:
+
+```ruby
+ConsoleAgent.configure { |c| c.api_key = 'sk-ant-...' }
+```
+
 ## Console Commands
 
 | Command | Description |
@@ -137,12 +149,12 @@ ConsoleAgent.configure do |config|
 end
 ```
 
-You can also change settings at runtime in the console:
+All settings can be changed at runtime in the console:
 
 ```ruby
+ConsoleAgent.configure { |c| c.api_key = 'sk-ant-...' }
 ConsoleAgent.configure { |c| c.debug = true }
-ConsoleAgent.configure { |c| c.provider = :openai }
-ENV['OPENAI_API_KEY'] = 'sk-...'
+ConsoleAgent.configure { |c| c.provider = :openai; c.api_key = 'sk-...' }
 ```
 
 ## Context Modes
@@ -176,9 +188,111 @@ ConsoleAgent.configure { |c| c.context_mode = :full }
 | `list_files` | Ruby files in a directory |
 | `read_file` | Read a source file (capped at 200 lines) |
 | `search_code` | Grep for a pattern across Ruby files |
+| `ask_user` | Ask the console user a clarifying question |
+| `save_memory` | Persist a learned fact for future sessions |
+| `recall_memories` | Search saved memories |
+| `load_skill` | Load full instructions for a skill |
 
 The LLM decides which tools to call based on your question. You can see the tool calls happening in real time.
 
+## Memories & Skills
+
+ConsoleAgent can remember what it learns about your codebase across sessions and load reusable skill instructions on demand.
+
+### Memories
+
+When the AI investigates something complex (like how sharding works in your app), it can save what it learned for next time. Memories are stored in `.console_agent/memories.yml` in your Rails app.
+
+```
+ai> how many users are on this shard?
+  Thinking...
+  -> search_code("shard")
+     Found 50 matches
+  -> read_file("config/initializers/sharding.rb")
+     202 lines
+  -> save_memory("Sharding architecture")
+     Memory saved: "Sharding architecture"
+
+Each shard is a separate database. User.count returns the count for the current shard only.
+
+  User.count
+
+[tokens in: 2,340 | out: 120 | total: 2,460]
+```
+
+Next session, the AI already knows:
+
+```
+ai> count users on this shard
+  Thinking...
+
+  User.count
+
+[tokens in: 580 | out: 45 | total: 625]
+```
+
+The memory file is human-editable YAML:
+
+```yaml
+# .console_agent/memories.yml
+memories:
+  - id: mem_1709123456_42
+    name: Sharding architecture
+    description: "App uses database-per-shard. Each shard is a separate DB. User.count only counts the current shard."
+    tags: [database, sharding]
+    created_at: "2026-02-27T10:30:00Z"
+```
+
+You can commit this file to your repo so the whole team benefits, or gitignore it for personal use.
+
+### Skills
+
+Skills are reusable instruction files that teach the AI how to handle specific tasks. Store them in `.console_agent/skills/` as markdown files with YAML frontmatter:
+
+```markdown
+# .console_agent/skills/sharding.md
+---
+name: Sharded database queries
+description: How to query across database shards. Use when user asks about counting records across shards or shard-specific operations.
+---
+
+## Instructions
+
+This app uses Apartment with one database per shard.
+- `User.count` only counts the current shard
+- To count across all shards: `Shard.all.sum { |s| s.switch { User.count } }`
+- Current shard: `Apartment::Tenant.current`
+```
+
+Only the skill name and description are sent to the AI on every request (~100 tokens per skill). The full instructions are loaded on demand via the `load_skill` tool only when relevant.
+
+### Storage
+
+By default, memories and skills are stored on the filesystem at `Rails.root/.console_agent/`. This works for development and for production environments with a persistent filesystem.
+
+For containers or other environments where the filesystem is ephemeral, you have two options:
+
+**Option A: Commit to your repo.** Create `.console_agent/memories.yml` and `.console_agent/skills/*.md` in your codebase. They'll be baked into your Docker image.
+
+**Option B: Custom storage adapter.** Implement the storage interface and plug it in:
+
+```ruby
+ConsoleAgent.configure do |config|
+  config.storage_adapter = MyS3Storage.new(bucket: 'my-bucket', prefix: 'console_agent/')
+end
+```
+
+A storage adapter just needs four methods: `read(key)`, `write(key, content)`, `list(pattern)`, and `exists?(key)`.
+
+To disable memories or skills:
+
+```ruby
+ConsoleAgent.configure do |config|
+  config.memories_enabled = false
+  config.skills_enabled = false
+end
+```
+
 ## Providers
 
 ### Anthropic (default)
@@ -196,34 +310,20 @@ ConsoleAgent.configure do |config|
 end
 ```
 
-## Docker Setup
+## Local Development
 
-If your Rails app runs in Docker, mount the gem source as a volume.
-
-In `docker-compose.yml`:
-
-```yaml
-volumes:
-  - /path/to/console_agent:/console_agent
-```
-
-In `Gemfile`:
+To develop the gem locally against a Rails app, use a path reference in your Gemfile:
 
 ```ruby
-gem 'console_agent', path: '/console_agent', group: :development
+gem 'console_agent', path: '/path/to/console_agent'
 ```
 
-For Docker builds (where the gem source isn't available yet), add a stub to your Dockerfile before `bundle install`:
+Switch back to the published gem when you're done:
 
-```dockerfile
-RUN mkdir -p /console_agent/lib/console_agent && \
-    echo "module ConsoleAgent; VERSION = '0.1.0'; end" > /console_agent/lib/console_agent/version.rb && \
-    echo "require 'console_agent/version'" > /console_agent/lib/console_agent.rb && \
-    printf "require_relative 'lib/console_agent/version'\nGem::Specification.new do |s|\n  s.name = 'console_agent'\n  s.version = ConsoleAgent::VERSION\n  s.summary = 'stub'\n  s.authors = ['x']\n  s.files = ['lib/console_agent.rb']\n  s.add_dependency 'rails', '>= 5.0'\n  s.add_dependency 'faraday', '>= 1.0'\nend\n" > /console_agent/console_agent.gemspec
+```ruby
+gem 'console_agent'
 ```
 
-The volume mount overwrites the stub at runtime with the real source.
-
 ## Requirements
 
 - Ruby >= 2.5

data/lib/console_agent/configuration.rb

@@ -5,7 +5,8 @@ module ConsoleAgent
 
     attr_accessor :provider, :api_key, :model, :max_tokens,
                   :auto_execute, :context_mode, :temperature,
-                  :timeout, :debug, :max_tool_rounds
+                  :timeout, :debug, :max_tool_rounds,
+                  :storage_adapter, :memories_enabled
 
     def initialize
       @provider     = :anthropic
@@ -17,7 +18,9 @@ module ConsoleAgent
       @temperature  = 0.2
       @timeout      = 30
       @debug        = false
-      @max_tool_rounds = 10
+      @max_tool_rounds = 100
+      @storage_adapter  = nil
+      @memories_enabled = true
     end
 
     def resolved_api_key

data/lib/console_agent/console_methods.rb

@@ -4,6 +4,48 @@ module ConsoleAgent
       ConsoleAgent.status
     end
 
+    def ai_memories(n = nil)
+      require 'yaml'
+      require 'console_agent/tools/memory_tools'
+      storage = ConsoleAgent.storage
+      keys = storage.list('memories/*.md').sort
+
+      if keys.empty?
+        $stdout.puts "\e[2mNo memories stored yet.\e[0m"
+        return nil
+      end
+
+      memories = keys.filter_map do |key|
+        content = storage.read(key)
+        next if content.nil? || content.strip.empty?
+        next unless content =~ /\A---\s*\n(.*?\n)---\s*\n(.*)/m
+        fm = YAML.safe_load($1, permitted_classes: [Time, Date]) || {}
+        fm.merge('description' => $2.strip, 'file' => key)
+      end
+
+      if memories.empty?
+        $stdout.puts "\e[2mNo memories stored yet.\e[0m"
+        return nil
+      end
+
+      shown = n ? memories.last(n) : memories.last(5)
+      total = memories.length
+
+      $stdout.puts "\e[36m[Memories — showing last #{shown.length} of #{total}]\e[0m"
+      shown.each do |m|
+        $stdout.puts "\e[33m  #{m['name']}\e[0m"
+        $stdout.puts "\e[2m  #{m['description']}\e[0m"
+        tags = Array(m['tags'])
+        $stdout.puts "\e[2m  tags: #{tags.join(', ')}\e[0m" unless tags.empty?
+        $stdout.puts
+      end
+
+      path = storage.respond_to?(:root_path) ? File.join(storage.root_path, 'memories') : 'memories/'
+      $stdout.puts "\e[2mStored in: #{path}/\e[0m"
+      $stdout.puts "\e[2mUse ai_memories(n) to show last n.\e[0m"
+      nil
+    end
+
     def ai(query = nil)
       if query.nil?
         $stderr.puts "\e[33mUsage: ai \"your question here\"\e[0m"
@@ -11,6 +53,7 @@ module ConsoleAgent
         $stderr.puts "\e[33m  ai! \"query\" - enter interactive mode (or ai! with no args)\e[0m"
         $stderr.puts "\e[33m  ai? \"query\" - explain only, no execution\e[0m"
         $stderr.puts "\e[33m  ai_status   - show current configuration\e[0m"
+        $stderr.puts "\e[33m  ai_memories - show recent memories (ai_memories(n) for last n)\e[0m"
         return nil
       end
 

data/lib/console_agent/context_builder.rb

@@ -30,6 +30,7 @@ module ConsoleAgent
       parts = []
       parts << smart_system_instructions
       parts << environment_context
+      parts << memory_context
       parts.compact.join("\n\n")
     end
 
@@ -48,6 +49,17 @@ module ConsoleAgent
         you need specific information to write accurate code — such as which user they are, which
         record to target, or what value to use.
 
+        You have memory tools to persist what you learn across sessions:
+        - save_memory: persist facts or procedures you learn about this codebase.
+          If a memory with the same name already exists, it will be updated in place.
+        - delete_memory: remove a memory by name
+        - recall_memories: search your saved memories for details
+
+        IMPORTANT: Check the Memories section below BEFORE answering. If a memory is relevant,
+        use recall_memories to get full details and apply that knowledge to your answer.
+        When you use a memory, mention it briefly (e.g. "Based on what I know about sharding...").
+        When you discover important patterns about this app, save them as memories.
+
         RULES:
         - Give ONE concise answer. Do not offer multiple alternatives or variations.
         - Respond with a single ```ruby code block that directly answers the question.
@@ -187,6 +199,23 @@ module ConsoleAgent
       nil
     end
 
+    def memory_context
+      return nil unless @config.memories_enabled
+
+      require 'console_agent/tools/memory_tools'
+      summaries = Tools::MemoryTools.new.memory_summaries
+      return nil if summaries.nil? || summaries.empty?
+
+      lines = ["## Memories"]
+      lines.concat(summaries)
+      lines << ""
+      lines << "Call recall_memories to get details before answering. Do NOT guess from the name alone."
+      lines.join("\n")
+    rescue => e
+      ConsoleAgent.logger.debug("ConsoleAgent: memory context failed: #{e.message}")
+      nil
+    end
+
     def eager_load_app!
       return unless defined?(Rails) && Rails.respond_to?(:application)
 

data/lib/console_agent/executor.rb

@@ -1,4 +1,43 @@
+require 'stringio'
+
 module ConsoleAgent
+  # Writes to two IO streams simultaneously
+  class TeeIO
+    def initialize(primary, secondary)
+      @primary = primary
+      @secondary = secondary
+    end
+
+    def write(str)
+      @primary.write(str)
+      @secondary.write(str)
+    end
+
+    def puts(*args)
+      @primary.puts(*args)
+      # Capture what puts would output
+      args.each { |a| @secondary.write("#{a}\n") }
+      @secondary.write("\n") if args.empty?
+    end
+
+    def print(*args)
+      @primary.print(*args)
+      args.each { |a| @secondary.write(a.to_s) }
+    end
+
+    def flush
+      @primary.flush if @primary.respond_to?(:flush)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @primary.respond_to?(method, include_private) || super
+    end
+
+    def method_missing(method, *args, &block)
+      @primary.send(method, *args, &block)
+    end
+  end
+
   class Executor
     CODE_REGEX = /```ruby\s*\n(.*?)```/m
 
@@ -33,21 +72,43 @@ module ConsoleAgent
     def execute(code)
       return nil if code.nil? || code.strip.empty?
 
+      captured_output = StringIO.new
+      old_stdout = $stdout
+      # Tee output: capture it and also print to the real stdout
+      $stdout = TeeIO.new(old_stdout, captured_output)
+
       result = binding_context.eval(code, "(console_agent)", 1)
+
+      $stdout = old_stdout
       $stdout.puts colorize("=> #{result.inspect}", :green)
+
+      @last_output = captured_output.string
       result
     rescue SyntaxError => e
+      $stdout = old_stdout if old_stdout
       $stderr.puts colorize("SyntaxError: #{e.message}", :red)
+      @last_output = nil
       nil
     rescue => e
+      $stdout = old_stdout if old_stdout
       $stderr.puts colorize("Error: #{e.class}: #{e.message}", :red)
       e.backtrace.first(3).each { |line| $stderr.puts colorize("  #{line}", :red) }
+      @last_output = captured_output&.string
       nil
     end
 
+    def last_output
+      @last_output
+    end
+
+    def last_cancelled?
+      @last_cancelled
+    end
+
     def confirm_and_execute(code)
       return nil if code.nil? || code.strip.empty?
 
+      @last_cancelled = false
       $stdout.print colorize("Execute? [y/N/edit] ", :yellow)
       answer = $stdin.gets.to_s.strip.downcase
 
@@ -71,6 +132,7 @@ module ConsoleAgent
         end
       else
         $stdout.puts colorize("Cancelled.", :yellow)
+        @last_cancelled = true
         nil
       end
     end

data/lib/console_agent/repl.rb

@@ -1,3 +1,5 @@
+require 'readline'
+
 module ConsoleAgent
   class Repl
     def initialize(binding_context)
@@ -9,6 +11,7 @@ module ConsoleAgent
       @history = []
       @total_input_tokens = 0
       @total_output_tokens = 0
+      @input_history = []
     end
 
     def one_shot(query)
@@ -52,17 +55,26 @@ module ConsoleAgent
       @total_output_tokens = 0
 
       loop do
-        $stdout.print "\e[33mai> \e[0m"
-        input = $stdin.gets
-        break if input.nil?
+        input = Readline.readline("\e[33mai> \e[0m", false)
+        break if input.nil? # Ctrl-D
 
         input = input.strip
         break if input.downcase == 'exit' || input.downcase == 'quit'
         next if input.empty?
 
+        # Add to Readline history (avoid consecutive duplicates)
+        Readline::HISTORY.push(input) unless input == Readline::HISTORY.to_a.last
+
         @history << { role: :user, content: input }
 
-        result = send_query(input, conversation: @history)
+        begin
+          result = send_query(input, conversation: @history)
+        rescue Interrupt
+          $stdout.puts "\n\e[33m  Aborted.\e[0m"
+          @history.pop # Remove the user message that never got a response
+          next
+        end
+
         track_usage(result)
         code = @executor.display_response(result.text)
         display_usage(result, show_session: true)
@@ -76,10 +88,26 @@ module ConsoleAgent
             exec_result = @executor.confirm_and_execute(code)
           end
 
-          if exec_result
-            result_str = exec_result.inspect
-            result_str = result_str[0..500] + '...' if result_str.length > 500
-            @history << { role: :user, content: "Execution result: #{result_str}" }
+          if @executor.last_cancelled?
+            @history << { role: :user, content: "User declined to execute the code." }
+          else
+            output_parts = []
+
+            # Capture printed output (puts, print, etc.)
+            if @executor.last_output && !@executor.last_output.strip.empty?
+              output_parts << "Output:\n#{@executor.last_output.strip}"
+            end
+
+            # Capture return value
+            if exec_result
+              output_parts << "Return value: #{exec_result.inspect}"
+            end
+
+            unless output_parts.empty?
+              result_str = output_parts.join("\n\n")
+              result_str = result_str[0..1000] + '...' if result_str.length > 1000
+              @history << { role: :user, content: "Code was executed. #{result_str}" }
+            end
           end
         end
       end
@@ -87,6 +115,7 @@ module ConsoleAgent
       display_session_summary
       $stdout.puts "\e[36mLeft ConsoleAgent interactive mode.\e[0m"
     rescue Interrupt
+      # Ctrl-C during Readline input — exit cleanly
       $stdout.puts
       display_session_summary
       $stdout.puts "\e[36mLeft ConsoleAgent interactive mode.\e[0m"
@@ -132,6 +161,8 @@ module ConsoleAgent
       total_output = 0
       result = nil
 
+      exhausted = false
+
       max_rounds.times do |round|
         if round == 0
           $stdout.puts "\e[2m  Thinking...\e[0m"
@@ -163,7 +194,8 @@ module ConsoleAgent
             tool_result = tools.execute(tc[:name], tc[:arguments])
 
             preview = compact_tool_result(tc[:name], tool_result)
-            $stdout.puts "\e[2m     #{preview}\e[0m"
+            cached_tag = tools.last_cached? ? " (cached)" : ""
+            $stdout.puts "\e[2m     #{preview}#{cached_tag}\e[0m"
           end
 
           if ConsoleAgent.configuration.debug
@@ -172,6 +204,17 @@ module ConsoleAgent
 
           messages << provider.format_tool_result(tc[:id], tool_result)
         end
+
+        exhausted = true if round == max_rounds - 1
+      end
+
+      # If we hit the tool round limit, force a final response without tools
+      if exhausted
+        $stdout.puts "\e[33m  Hit tool round limit (#{max_rounds}). Forcing final answer. Increase with: ConsoleAgent.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." }
+        result = provider.chat(messages, system_prompt: context)
+        total_input += result.input_tokens || 0
+        total_output += result.output_tokens || 0
       end
 
       Providers::ChatResult.new(
@@ -197,6 +240,12 @@ module ConsoleAgent
         "(\"#{args['query']}\"#{dir})"
       when 'list_files'
         args['directory'] ? "(\"#{args['directory']}\")" : ''
+      when 'save_memory'
+        "(\"#{args['name']}\")"
+      when 'delete_memory'
+        "(\"#{args['name']}\")"
+      when 'recall_memories'
+        args['query'] ? "(\"#{args['query']}\")" : ''
       else
         ''
       end
@@ -244,6 +293,13 @@ module ConsoleAgent
         else
           truncate(result, 80)
         end
+      when 'save_memory'
+        (result.start_with?('Memory saved') || result.start_with?('Memory updated')) ? result : truncate(result, 80)
+      when 'delete_memory'
+        result.start_with?('Memory deleted') ? result : truncate(result, 80)
+      when 'recall_memories'
+        chunks = result.split("\n\n")
+        chunks.length > 1 ? "#{chunks.length} memories found" : truncate(result, 80)
       else
         truncate(result, 80)
       end

data/lib/console_agent/storage/base.rb

@@ -0,0 +1,27 @@
+module ConsoleAgent
+  module Storage
+    class StorageError < StandardError; end
+
+    class Base
+      def read(key)
+        raise NotImplementedError
+      end
+
+      def write(key, content)
+        raise NotImplementedError
+      end
+
+      def list(pattern)
+        raise NotImplementedError
+      end
+
+      def exists?(key)
+        raise NotImplementedError
+      end
+
+      def delete(key)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/console_agent/storage/file_storage.rb

@@ -0,0 +1,63 @@
+require 'fileutils'
+require 'console_agent/storage/base'
+
+module ConsoleAgent
+  module Storage
+    class FileStorage < Base
+      attr_reader :root_path
+
+      def initialize(root_path = nil)
+        @root_path = root_path || default_root
+      end
+
+      def read(key)
+        path = full_path(key)
+        return nil unless File.exist?(path)
+        File.read(path)
+      end
+
+      def write(key, content)
+        path = full_path(key)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+        true
+      rescue Errno::EACCES, Errno::EROFS, IOError => e
+        raise StorageError, "Cannot write #{key}: #{e.message}"
+      end
+
+      def list(pattern)
+        Dir.glob(File.join(@root_path, pattern)).sort.map do |path|
+          path.sub("#{@root_path}/", '')
+        end
+      end
+
+      def exists?(key)
+        File.exist?(full_path(key))
+      end
+
+      def delete(key)
+        path = full_path(key)
+        return false unless File.exist?(path)
+        File.delete(path)
+        true
+      rescue Errno::EACCES, Errno::EROFS, IOError => e
+        raise StorageError, "Cannot delete #{key}: #{e.message}"
+      end
+
+      private
+
+      def full_path(key)
+        sanitized = key.gsub('..', '').gsub(%r{\A/+}, '')
+        File.join(@root_path, sanitized)
+      end
+
+      def default_root
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          File.join(Rails.root.to_s, '.console_agent')
+        else
+          File.join(Dir.pwd, '.console_agent')
+        end
+      end
+    end
+  end
+end

data/lib/console_agent/tools/memory_tools.rb

@@ -0,0 +1,136 @@
+require 'yaml'
+
+module ConsoleAgent
+  module Tools
+    class MemoryTools
+      MEMORIES_DIR = 'memories'
+
+      def initialize(storage = nil)
+        @storage = storage || ConsoleAgent.storage
+      end
+
+      def save_memory(name:, description:, tags: [])
+        key = memory_key(name)
+        existing = load_memory(key)
+
+        frontmatter = {
+          'name' => name,
+          'tags' => Array(tags).empty? && existing ? (existing['tags'] || []) : Array(tags),
+          'created_at' => existing ? existing['created_at'] : Time.now.utc.iso8601
+        }
+        frontmatter['updated_at'] = Time.now.utc.iso8601 if existing
+
+        content = "---\n#{YAML.dump(frontmatter).sub("---\n", '').strip}\n---\n\n#{description}\n"
+        @storage.write(key, content)
+
+        path = @storage.respond_to?(:root_path) ? File.join(@storage.root_path, key) : key
+        if existing
+          "Memory updated: \"#{name}\" (#{path})"
+        else
+          "Memory saved: \"#{name}\" (#{path})"
+        end
+      rescue Storage::StorageError => e
+        "FAILED to save (#{e.message}). Add this manually to .console_agent/#{key}:\n" \
+        "---\nname: #{name}\ntags: #{Array(tags).inspect}\n---\n\n#{description}"
+      end
+
+      def delete_memory(name:)
+        key = memory_key(name)
+        unless @storage.exists?(key)
+          # Try to find by name match across all memory files
+          found_key = find_memory_key_by_name(name)
+          return "No memory found: \"#{name}\"" unless found_key
+          key = found_key
+        end
+
+        memory = load_memory(key)
+        @storage.delete(key)
+        "Memory deleted: \"#{memory ? memory['name'] : name}\""
+      rescue Storage::StorageError => e
+        "FAILED to delete memory (#{e.message})."
+      end
+
+      def recall_memories(query: nil, tag: nil)
+        memories = load_all_memories
+        return "No memories stored yet." if memories.empty?
+
+        results = memories
+        if tag && !tag.empty?
+          results = results.select { |m|
+            Array(m['tags']).any? { |t| t.downcase.include?(tag.downcase) }
+          }
+        end
+        if query && !query.empty?
+          q = query.downcase
+          results = results.select { |m|
+            m['name'].to_s.downcase.include?(q) ||
+            m['description'].to_s.downcase.include?(q) ||
+            Array(m['tags']).any? { |t| t.downcase.include?(q) }
+          }
+        end
+
+        return "No memories matching your search." if results.empty?
+
+        results.map { |m|
+          line = "**#{m['name']}**\n#{m['description']}"
+          line += "\nTags: #{m['tags'].join(', ')}" if m['tags'] && !m['tags'].empty?
+          line
+        }.join("\n\n")
+      end
+
+      def memory_summaries
+        memories = load_all_memories
+        return nil if memories.empty?
+
+        memories.map { |m|
+          tags = Array(m['tags'])
+          tag_str = tags.empty? ? '' : " [#{tags.join(', ')}]"
+          "- #{m['name']}#{tag_str}"
+        }
+      end
+
+      private
+
+      def memory_key(name)
+        slug = name.downcase.strip
+          .gsub(/[^a-z0-9\s-]/, '')
+          .gsub(/[\s]+/, '-')
+          .gsub(/-+/, '-')
+          .sub(/^-/, '').sub(/-$/, '')
+        "#{MEMORIES_DIR}/#{slug}.md"
+      end
+
+      def load_memory(key)
+        content = @storage.read(key)
+        return nil if content.nil? || content.strip.empty?
+        parse_memory(content)
+      rescue => e
+        ConsoleAgent.logger.warn("ConsoleAgent: failed to load memory #{key}: #{e.message}")
+        nil
+      end
+
+      def load_all_memories
+        keys = @storage.list("#{MEMORIES_DIR}/*.md")
+        keys.map { |key| load_memory(key) }.compact
+      rescue => e
+        ConsoleAgent.logger.warn("ConsoleAgent: failed to load memories: #{e.message}")
+        []
+      end
+
+      def parse_memory(content)
+        return nil unless content =~ /\A---\s*\n(.*?\n)---\s*\n(.*)/m
+        frontmatter = YAML.safe_load($1, permitted_classes: [Time, Date]) || {}
+        description = $2.strip
+        frontmatter.merge('description' => description)
+      end
+
+      def find_memory_key_by_name(name)
+        keys = @storage.list("#{MEMORIES_DIR}/*.md")
+        keys.find do |key|
+          memory = load_memory(key)
+          memory && memory['name'].to_s.downcase == name.downcase
+        end
+      end
+    end
+  end
+end

data/lib/console_agent/tools/registry.rb

@@ -5,12 +5,21 @@ module ConsoleAgent
     class Registry
       attr_reader :definitions
 
+      # Tools that should never be cached (side effects or user interaction)
+      NO_CACHE = %w[ask_user save_memory delete_memory].freeze
+
       def initialize
         @definitions = []
         @handlers = {}
+        @cache = {}
+        @last_cached = false
         register_all
       end
 
+      def last_cached?
+        @last_cached
+      end
+
       def execute(tool_name, arguments = {})
         handler = @handlers[tool_name]
         unless handler
@@ -27,7 +36,18 @@ module ConsoleAgent
                  arguments || {}
                end
 
-        handler.call(args)
+        unless NO_CACHE.include?(tool_name)
+          cache_key = [tool_name, args].hash
+          if @cache.key?(cache_key)
+            @last_cached = true
+            return @cache[cache_key]
+          end
+        end
+
+        @last_cached = false
+        result = handler.call(args)
+        @cache[[tool_name, args].hash] = result unless NO_CACHE.include?(tool_name)
+        result
       rescue => e
         "Error executing #{tool_name}: #{e.message}"
       end
@@ -158,6 +178,58 @@ module ConsoleAgent
           },
           handler: ->(args) { ask_user(args['question']) }
         )
+
+        register_memory_tools
+      end
+
+      def register_memory_tools
+        return unless ConsoleAgent.configuration.memories_enabled
+
+        require 'console_agent/tools/memory_tools'
+        memory = MemoryTools.new
+
+        register(
+          name: 'save_memory',
+          description: 'Save a fact or pattern you learned about this codebase for future sessions. Use after discovering how something works (e.g. sharding, auth, custom business logic).',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'name' => { 'type' => 'string', 'description' => 'Short name for this memory (e.g. "Sharding architecture")' },
+              'description' => { 'type' => 'string', 'description' => 'Detailed description of what you learned' },
+              'tags' => { 'type' => 'array', 'items' => { 'type' => 'string' }, 'description' => 'Optional tags (e.g. ["database", "sharding"])' }
+            },
+            'required' => ['name', 'description']
+          },
+          handler: ->(args) {
+            memory.save_memory(name: args['name'], description: args['description'], tags: args['tags'] || [])
+          }
+        )
+
+        register(
+          name: 'delete_memory',
+          description: 'Delete a memory by name.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'name' => { 'type' => 'string', 'description' => 'The memory name to delete (e.g. "Sharding architecture")' }
+            },
+            'required' => ['name']
+          },
+          handler: ->(args) { memory.delete_memory(name: args['name']) }
+        )
+
+        register(
+          name: 'recall_memories',
+          description: 'Search your saved memories about this codebase. Call with no args to list all, or pass a query/tag to filter.',
+          parameters: {
+            'type' => 'object',
+            'properties' => {
+              'query' => { 'type' => 'string', 'description' => 'Search term to filter by name, description, or tags' },
+              'tag' => { 'type' => 'string', 'description' => 'Filter by a specific tag' }
+            }
+          },
+          handler: ->(args) { memory.recall_memories(query: args['query'], tag: args['tag']) }
+        )
       end
 
       def ask_user(question)

data/lib/console_agent/version.rb

@@ -1,3 +1,3 @@
 module ConsoleAgent
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/console_agent.rb

@@ -13,6 +13,23 @@ module ConsoleAgent
 
     def reset_configuration!
       @configuration = Configuration.new
+      reset_storage!
+    end
+
+    def storage
+      @storage ||= begin
+        adapter = configuration.storage_adapter
+        if adapter
+          adapter
+        else
+          require 'console_agent/storage/file_storage'
+          Storage::FileStorage.new
+        end
+      end
+    end
+
+    def reset_storage!
+      @storage = nil
     end
 
     def logger
@@ -48,6 +65,7 @@ module ConsoleAgent
       lines << "  Timeout:        #{c.timeout}s"
       lines << "  Max tool rounds:#{c.max_tool_rounds}" if c.context_mode == :smart
       lines << "  Auto-execute:   #{c.auto_execute}"
+      lines << "  Memories:       #{c.memories_enabled}"
       lines << "  Debug:          #{c.debug}"
       $stdout.puts lines.join("\n")
       nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console_agent
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Cortfr
@@ -98,7 +98,10 @@ files:
 - lib/console_agent/providers/openai.rb
 - lib/console_agent/railtie.rb
 - lib/console_agent/repl.rb
+- lib/console_agent/storage/base.rb
+- lib/console_agent/storage/file_storage.rb
 - lib/console_agent/tools/code_tools.rb
+- lib/console_agent/tools/memory_tools.rb
 - lib/console_agent/tools/model_tools.rb
 - lib/console_agent/tools/registry.rb
 - lib/console_agent/tools/schema_tools.rb