claude_swarm 1.0.4 → 1.0.6

data/examples/v2/swarm_with_hooks.yml

@@ -10,7 +10,7 @@
 # Run: swarm run lib/swarm_sdk/examples/swarm_with_hooks.yml -p "your prompt"
 #
 # Or programmatically:
-#   swarm = SwarmSDK::Swarm.load("lib/swarm_sdk/examples/swarm_with_hooks.yml")
+#   swarm = SwarmSDK.load_file("lib/swarm_sdk/examples/swarm_with_hooks.yml")
 #   result = swarm.execute("your prompt")
 
 version: 2

data/lib/claude_swarm/cli.rb

@@ -43,9 +43,8 @@ module ClaudeSwarm
       type: :string,
       desc: "Root directory for resolving relative paths (defaults to current directory)"
     def start(config_file = nil)
-      # Set root directory early so it's available to all components
-      root_dir = options[:root_dir] || Dir.pwd
-      ENV["CLAUDE_SWARM_ROOT_DIR"] = File.expand_path(root_dir)
+      # Determine root directory for this session
+      root_dir = File.expand_path(options[:root_dir] || Dir.pwd)
 
       # Resolve config path relative to root directory
       config_path = config_file || "claude-swarm.yml"
@@ -71,7 +70,7 @@ module ClaudeSwarm
       end
 
       begin
-        config = Configuration.new(config_path, base_dir: ClaudeSwarm.root_dir, options: options)
+        config = Configuration.new(config_path, base_dir: root_dir, options: options)
         generator = McpGenerator.new(config, vibe: options[:vibe])
         orchestrator = Orchestrator.new(
           config,
@@ -547,24 +546,23 @@ module ClaudeSwarm
           exit(1)
         end
 
-        # Change to the original root directory if it exists
+        # Load the original root directory from session
         root_dir_file = File.join(session_path, "root_directory")
-        if File.exist?(root_dir_file)
+        root_dir = if File.exist?(root_dir_file)
           original_dir = File.read(root_dir_file).strip
           if Dir.exist?(original_dir)
-            Dir.chdir(original_dir)
-            ENV["CLAUDE_SWARM_ROOT_DIR"] = original_dir
-            say("Changed to original directory: #{original_dir}", :green) unless options[:prompt]
+            say("Using original directory: #{original_dir}", :green) unless options[:prompt]
+            original_dir
           else
             error("Original directory no longer exists: #{original_dir}")
             exit(1)
           end
         else
           # If no root_directory file, use current directory
-          ENV["CLAUDE_SWARM_ROOT_DIR"] = Dir.pwd
+          Dir.pwd
         end
 
-        config = Configuration.new(config_file, base_dir: ClaudeSwarm.root_dir)
+        config = Configuration.new(config_file, base_dir: root_dir)
 
         # Load session metadata if it exists to check for worktree info
         session_metadata_file = File.join(session_path, "session_metadata.json")

data/lib/claude_swarm/commands/ps.rb

@@ -96,9 +96,8 @@ module ClaudeSwarm
         main_instance = config.dig("swarm", "main")
 
         # Get base directory from session metadata or root_directory file
-        base_dir = ClaudeSwarm.root_dir
         root_dir_file = File.join(session_dir, "root_directory")
-        base_dir = File.read(root_dir_file).strip if File.exist?(root_dir_file)
+        base_dir = File.exist?(root_dir_file) ? File.read(root_dir_file).strip : Dir.pwd
 
         # Get all directories - handle both string and array formats
         dir_config = config.dig("swarm", "instances", main_instance, "directory")

data/lib/claude_swarm/configuration.rb

@@ -13,13 +13,12 @@ module ClaudeSwarm
     ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
     O_SERIES_MODEL_PATTERN = /^(o\d+(\s+(Preview|preview))?(-pro|-mini|-deep-research|-mini-deep-research)?|gpt-5(-mini|-nano)?)$/
 
-    attr_reader :config, :config_path, :swarm, :swarm_name, :main_instance, :instances, :root_directory
+    attr_reader :config, :config_path, :swarm, :swarm_name, :main_instance, :instances, :base_dir
 
     def initialize(config_path, base_dir: nil, options: {})
       @config_path = Pathname.new(config_path).expand_path
       @config_dir = @config_path.dirname
-      @base_dir = base_dir || @config_dir
-      @root_directory = @base_dir
+      @base_dir = base_dir || @config_dir.to_s
       @options = options
       load_and_validate
     end

data/lib/claude_swarm/mcp_generator.rb

@@ -183,21 +183,17 @@ module ClaudeSwarm
         args.push("--claude-session-id", claude_session_id) if claude_session_id
       end
 
-      # Capture environment variables needed for Ruby and Bundler to work properly
-      # This includes both BUNDLE_* variables and Ruby-specific variables
+      # Capture environment variables needed for running claude-swarm
+      # We intentionally exclude Bundler variables to ensure we use the system-installed gem
       required_env = {}
 
-      # Bundle-specific variables
-      ENV.each do |k, v|
-        required_env[k] = v if k.start_with?("BUNDLE_")
-      end
-
-      # Claude Swarm-specific variables
+      # Claude Swarm-specific variables (always needed)
       ENV.each do |k, v|
         required_env[k] = v if k.start_with?("CLAUDE_SWARM_")
       end
 
       # Ruby-specific variables that MCP servers need
+      # Exclude RUBYOPT and RUBYLIB to avoid Bundler interference
       [
         "RUBY_ROOT",
         "RUBY_ENGINE",
@@ -205,8 +201,6 @@ module ClaudeSwarm
         "GEM_ROOT",
         "GEM_HOME",
         "GEM_PATH",
-        "RUBYOPT",
-        "RUBYLIB",
         "PATH",
       ].each do |key|
         required_env[key] = ENV[key] if ENV[key]

data/lib/claude_swarm/orchestrator.rb

@@ -38,7 +38,7 @@ module ClaudeSwarm
         @session_log_path = File.join(@session_path, "session.log")
       else
         # Generate new session path
-        session_params = { working_dir: ClaudeSwarm.root_dir }
+        session_params = { working_dir: @config.base_dir }
         session_params[:session_id] = @provided_session_id if @provided_session_id
         @session_path = SessionPath.generate(**session_params)
         SessionPath.ensure_directory(@session_path)
@@ -49,7 +49,6 @@ module ClaudeSwarm
 
       end
       ENV["CLAUDE_SWARM_SESSION_PATH"] = @session_path
-      ENV["CLAUDE_SWARM_ROOT_DIR"] = ClaudeSwarm.root_dir
 
       # Initialize components that depend on session path
       @process_tracker = ProcessTracker.new(@session_path)
@@ -235,13 +234,11 @@ module ClaudeSwarm
           before_commands_dir = parent_dir
         end
 
-        Dir.chdir(before_commands_dir) do
-          success = execute_before_commands?(before_commands)
-          unless success
-            non_interactive_output { print("❌ Before commands failed. Aborting swarm launch.") }
-            cleanup_all
-            exit(1)
-          end
+        success = execute_before_commands?(before_commands, chdir: before_commands_dir)
+        unless success
+          non_interactive_output { print("❌ Before commands failed. Aborting swarm launch.") }
+          cleanup_all
+          exit(1)
         end
 
         non_interactive_output do
@@ -262,19 +259,18 @@ module ClaudeSwarm
       end
 
       # Execute the main instance - this will cascade to other instances via MCP
-      Dir.chdir(main_instance[:directory]) do
-        # Execute main Claude instance with unbundled environment to avoid bundler conflicts
-        # This ensures the main instance runs in a clean environment without inheriting
-        # Claude Swarm's BUNDLE_* environment variables
-        Bundler.with_unbundled_env do
-          if @non_interactive_prompt
-            stream_to_session_log(*command)
-          else
-            system_with_pid!(*command) do |pid|
-              @process_tracker.track_pid(pid, "claude_#{@config.main_instance}")
-              non_interactive_output do
-                puts "✓ Claude instance started with PID: #{pid}"
-              end
+      # Execute main Claude instance with unbundled environment to avoid bundler conflicts
+      # This ensures the main instance runs in a clean environment without inheriting
+      # Claude Swarm's BUNDLE_* environment variables
+      main_dir = main_instance[:directory]
+      Bundler.with_unbundled_env do
+        if @non_interactive_prompt
+          stream_to_session_log(*command, chdir: main_dir)
+        else
+          system_with_pid!(*command, chdir: main_dir) do |pid|
+            @process_tracker.track_pid(pid, "claude_#{@config.main_instance}")
+            non_interactive_output do
+              puts "✓ Claude instance started with PID: #{pid}"
             end
           end
         end
@@ -306,12 +302,12 @@ module ClaudeSwarm
       puts
     end
 
-    def execute_before_commands?(commands)
-      execute_commands(commands, phase: "before", fail_fast: true)
+    def execute_before_commands?(commands, chdir:)
+      execute_commands(commands, phase: "before", fail_fast: true, chdir: chdir)
     end
 
-    def execute_after_commands?(commands)
-      execute_commands(commands, phase: "after", fail_fast: false)
+    def execute_after_commands?(commands, chdir:)
+      execute_commands(commands, phase: "after", fail_fast: false, chdir: chdir)
     end
 
     def execute_after_commands_once
@@ -336,16 +332,14 @@ module ClaudeSwarm
         after_commands_dir = parent_dir
       end
 
-      Dir.chdir(after_commands_dir) do
-        non_interactive_output do
-          print("⚙️  Executing after commands...")
-        end
+      non_interactive_output do
+        print("⚙️  Executing after commands...")
+      end
 
-        success = execute_after_commands?(after_commands)
-        unless success
-          non_interactive_output do
-            puts "⚠️  Some after commands failed"
-          end
+      success = execute_after_commands?(after_commands, chdir: after_commands_dir)
+      unless success
+        non_interactive_output do
+          puts "⚠️  Some after commands failed"
         end
       end
     end
@@ -357,7 +351,7 @@ module ClaudeSwarm
 
       # Save the root directory
       root_dir_file = File.join(session_path, "root_directory")
-      File.write(root_dir_file, ClaudeSwarm.root_dir)
+      File.write(root_dir_file, @config.base_dir)
 
       # Save session metadata
       metadata_file = File.join(session_path, "session_metadata.json")
@@ -366,7 +360,7 @@ module ClaudeSwarm
 
     def build_session_metadata
       {
-        "root_directory" => ClaudeSwarm.root_dir,
+        "root_directory" => @config.base_dir,
         "timestamp" => Time.now.utc.iso8601,
         "start_time" => @start_time.utc.iso8601,
         "swarm_name" => @config.swarm_name,
@@ -642,12 +636,12 @@ module ClaudeSwarm
       end
     end
 
-    def stream_to_session_log(*command)
+    def stream_to_session_log(*command, chdir:)
       # Setup logger for session logging
       logger = Logger.new(@session_log_path, level: :info, progname: @config.main_instance)
 
       # Use Open3.popen2e to capture stdout and stderr merged for formatting
-      Open3.popen2e(*command) do |stdin, stdout_and_stderr, wait_thr|
+      Open3.popen2e(*command, chdir: chdir) do |stdin, stdout_and_stderr, wait_thr|
         stdin.close
 
         # Read and process the merged output
@@ -819,7 +813,10 @@ module ClaudeSwarm
       @logger ||= Logger.new(File.join(@session_path, "session.log"), level: :info, progname: "orchestrator")
     end
 
-    def execute_commands(commands, phase:, fail_fast:)
+    def execute_commands(commands, phase:, fail_fast:, chdir:)
+      raise ArgumentError, "chdir parameter is required" if chdir.nil?
+      raise ArgumentError, "chdir must be a valid directory: #{chdir}" unless File.directory?(chdir)
+
       all_succeeded = true
 
       # Setup logger for session logging if we have a session path
@@ -839,13 +836,15 @@ module ClaudeSwarm
             end
           end
 
-          output = %x(#{command} 2>&1)
-          success = $CHILD_STATUS.success?
+          # Use Open3.capture2e with chdir option to execute the command
+          # This allows setting the working directory without changing the process directory
+          output, status = Open3.capture2e(command, chdir: chdir)
+          success = status.success?
           output_separator = "-" * 80
 
           logger.info { "Command output:" }
           logger.info { output }
-          logger.info { "Exit status: #{$CHILD_STATUS.exitstatus}" }
+          logger.info { "Exit status: #{status.exitstatus}" }
           logger.info { output_separator }
 
           # Show output if in debug mode or if command failed
@@ -854,7 +853,7 @@ module ClaudeSwarm
               output_prefix = phase == "after" ? "After command" : "Command"
               puts "#{output_prefix} #{index + 1} output:"
               puts output
-              print("Exit status: #{$CHILD_STATUS.exitstatus}")
+              print("Exit status: #{status.exitstatus}")
             end
           end
 

data/lib/claude_swarm/system_utils.rb

@@ -2,14 +2,14 @@
 
 module ClaudeSwarm
   module SystemUtils
-    def system!(*args)
-      system(*args)
+    def system!(*args, **options)
+      system(*args, **options)
       handle_command_failure(last_status, args)
     end
 
-    def system_with_pid!(*args)
+    def system_with_pid!(*args, **options)
       # Spawn the process - by default, inherits the parent's I/O
-      pid = Process.spawn(*args)
+      pid = Process.spawn(*args, **options)
 
       # Yield the PID to the block if given
       yield(pid) if block_given?

data/lib/claude_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  VERSION = "1.0.4"
+  VERSION = "1.0.6"
 end

data/lib/claude_swarm.rb

@@ -30,22 +30,20 @@ require_relative "claude_swarm/version"
 # Zeitwerk setup
 require "zeitwerk"
 loader = Zeitwerk::Loader.new
-loader.tag = "claude_swarm"
-
+loader.tag = File.basename(__FILE__, ".rb")
 loader.ignore("#{__dir__}/claude_swarm/templates")
+loader.push_dir("#{__dir__}/claude_swarm", namespace: ClaudeSwarm)
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.inflector.inflect(
   "cli" => "CLI",
   "openai" => "OpenAI",
 )
+loader.setup
 
 module ClaudeSwarm
   class Error < StandardError; end
 
   class << self
-    def root_dir
-      ENV.fetch("CLAUDE_SWARM_ROOT_DIR") { Dir.pwd }
-    end
-
     def home_dir
       ENV.fetch("CLAUDE_SWARM_HOME") { File.expand_path("~/.claude-swarm") }
     end
@@ -67,6 +65,3 @@ module ClaudeSwarm
     end
   end
 end
-
-loader.push_dir("#{__dir__}/claude_swarm", namespace: ClaudeSwarm)
-loader.setup

data/lib/swarm_cli/commands/mcp_serve.rb

@@ -29,7 +29,7 @@ module SwarmCLI
 
         # Validate the swarm configuration
         begin
-          SwarmSDK::Swarm.load(config_path)
+          SwarmSDK.load_file(config_path)
         rescue SwarmSDK::ConfigurationError => e
           $stderr.puts "Error: Invalid swarm configuration: #{e.message}"
           exit(1)
@@ -92,7 +92,7 @@ module SwarmCLI
 
           define_method(:call) do |task:, description: nil, thinking_budget: nil|
             # Load swarm for each execution (ensures fresh state)
-            swarm = SwarmSDK::Swarm.load(self.class.config_path)
+            swarm = SwarmSDK.load_file(self.class.config_path)
 
             # Build prompt with thinking budget if provided
             prompt = task

data/lib/swarm_cli/commands/mcp_tools.rb

@@ -14,9 +14,9 @@ module SwarmCLI
 
       def initialize(options)
         @options = options
-        # Create scratchpad with persistence for MCP server
-        scratchpad_path = File.join(Dir.pwd, ".swarm", "scratchpad.json")
-        @scratchpad = SwarmSDK::Scratchpad.new(persist_to: scratchpad_path)
+        # Create volatile scratchpad for MCP server
+        # Note: Scratchpad is always volatile - data is not persisted between sessions
+        @scratchpad = SwarmSDK::Tools::Stores::ScratchpadStorage.new
       end
 
       def execute

data/lib/swarm_cli/config_loader.rb

@@ -4,8 +4,8 @@ module SwarmCLI
   # ConfigLoader handles loading swarm configurations from both YAML and Ruby DSL files.
   #
   # Supports:
-  # - YAML files (.yml, .yaml) - loaded via SwarmSDK::Swarm.load
-  # - Ruby DSL files (.rb) - executed and expected to return a SwarmSDK::Swarm instance
+  # - YAML files (.yml, .yaml) - loaded via SwarmSDK.load_file
+  # - Ruby DSL files (.rb) - executed and expected to return a SwarmSDK::Swarm or SwarmSDK::NodeOrchestrator instance
   #
   # @example Load YAML config
   #   swarm = ConfigLoader.load("config.yml")
@@ -18,11 +18,11 @@ module SwarmCLI
       # Load a swarm configuration from file (YAML or Ruby DSL)
       #
       # Detects file type by extension:
-      # - .yml, .yaml -> Load as YAML using SwarmSDK::Swarm.load
-      # - .rb -> Execute as Ruby DSL and expect SwarmSDK::Swarm instance
+      # - .yml, .yaml -> Load as YAML using SwarmSDK.load_file
+      # - .rb -> Execute as Ruby DSL and expect SwarmSDK::Swarm or SwarmSDK::NodeOrchestrator instance
       #
       # @param path [String, Pathname] Path to configuration file
-      # @return [SwarmSDK::Swarm] Configured swarm instance
+      # @return [SwarmSDK::Swarm, SwarmSDK::NodeOrchestrator] Configured swarm or orchestrator instance
       # @raise [SwarmCLI::ConfigurationError] If file not found or invalid format
       def load(path)
         path = Pathname.new(path).expand_path
@@ -50,7 +50,7 @@ module SwarmCLI
       # @param path [Pathname] Path to YAML file
       # @return [SwarmSDK::Swarm] Configured swarm instance
       def load_yaml(path)
-        SwarmSDK::Swarm.load(path.to_s)
+        SwarmSDK.load_file(path.to_s)
       rescue SwarmSDK::ConfigurationError => e
         # Re-raise with CLI context
         raise ConfigurationError, "Configuration error in #{path}: #{e.message}"
@@ -59,12 +59,12 @@ module SwarmCLI
       # Load Ruby DSL configuration file
       #
       # Executes the Ruby file in a clean binding and expects it to return
-      # a SwarmSDK::Swarm instance. The file should use SwarmSDK.build or
-      # create a Swarm instance directly.
+      # a SwarmSDK::Swarm or SwarmSDK::NodeOrchestrator instance. The file should
+      # use SwarmSDK.build or create a Swarm/NodeOrchestrator instance directly.
       #
       # @param path [Pathname] Path to Ruby DSL file
-      # @return [SwarmSDK::Swarm] Configured swarm instance
-      # @raise [ConfigurationError] If file doesn't return a Swarm instance
+      # @return [SwarmSDK::Swarm, SwarmSDK::NodeOrchestrator] Configured swarm or orchestrator instance
+      # @raise [ConfigurationError] If file doesn't return a valid instance
       def load_ruby_dsl(path)
         # Read the file content
         content = path.read
@@ -73,10 +73,11 @@ module SwarmCLI
         # This allows the DSL file to use SwarmSDK.build directly
         result = eval(content, binding, path.to_s, 1) # rubocop:disable Security/Eval
 
-        # Validate result is a Swarm instance
-        unless result.is_a?(SwarmSDK::Swarm)
+        # Validate result is a Swarm or NodeOrchestrator instance
+        # Both have the same execute(prompt) interface
+        unless result.is_a?(SwarmSDK::Swarm) || result.is_a?(SwarmSDK::NodeOrchestrator)
           raise ConfigurationError,
-            "Ruby DSL file must return a SwarmSDK::Swarm instance. " \
+            "Ruby DSL file must return a SwarmSDK::Swarm or SwarmSDK::NodeOrchestrator instance. " \
               "Got: #{result.class}. " \
               "Use: SwarmSDK.build { ... } or Swarm.new(...)"
         end

data/lib/swarm_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmCLI
-  VERSION = "2.1.0"
+  VERSION = "2.1.2"
 end

data/lib/swarm_cli.rb

@@ -22,7 +22,9 @@ require_relative "swarm_cli/version"
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, ".rb")
 loader.push_dir("#{__dir__}/swarm_cli", namespace: SwarmCLI)
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.inflector.inflect(
   "cli" => "CLI",
   "ui" => "UI",

data/lib/swarm_memory/adapters/base.rb

@@ -7,11 +7,11 @@ module SwarmMemory
     # Subclasses must implement all public methods to provide
     # different storage backends (filesystem, Redis, SQLite, etc.)
     class Base
-      # Maximum size per entry (1MB)
-      MAX_ENTRY_SIZE = 1_000_000
+      # Maximum size per entry (3MB)
+      MAX_ENTRY_SIZE = 3_000_000
 
-      # Maximum total storage size (100MB)
-      MAX_TOTAL_SIZE = 100_000_000
+      # Maximum total storage size (100GB)
+      MAX_TOTAL_SIZE = 100_000_000_000
 
       # Write content to storage
       #

data/lib/swarm_memory/adapters/filesystem_adapter.rb

@@ -171,12 +171,6 @@ module SwarmMemory
 
         content = File.read(md_file)
 
-        # Check if it's a stub (redirect)
-        if stub_content?(content)
-          target_path = extract_redirect_target(content)
-          return read(file_path: target_path) if target_path
-        end
-
         # Increment hit counter
         increment_hits(file_path)
 
@@ -205,12 +199,6 @@ module SwarmMemory
 
         content = File.read(md_file)
 
-        # Follow stub redirect if applicable
-        if stub_content?(content)
-          target_path = extract_redirect_target(content)
-          return read_entry(file_path: target_path) if target_path
-        end
-
         # Read metadata
         yaml_data = File.exist?(yaml_file) ? YAML.load_file(yaml_file, permitted_classes: [Time, Date, Symbol]) : {}
 

data/lib/swarm_memory/core/storage.rb

@@ -95,22 +95,82 @@ module SwarmMemory
         )
       end
 
-      # Read content from storage
+      # Read content from storage, automatically following stub redirects
       #
       # @param file_path [String] Path to read from
       # @return [String] Content at the path
       def read(file_path:)
-        normalized_path = PathNormalizer.normalize(file_path)
-        @adapter.read(file_path: normalized_path)
+        entry = read_entry(file_path: file_path)
+        entry.content
       end
 
-      # Read full entry with metadata
+      # Read full entry with metadata, automatically following stub redirects
+      #
+      # Stub redirects are created by MemoryDefrag when merging/moving entries.
+      # This method transparently follows redirect chains up to 5 levels deep.
       #
       # @param file_path [String] Path to read from
+      # @param visited [Array<String>] Internal: tracks visited paths to detect circular redirects
       # @return [Entry] Full entry object
-      def read_entry(file_path:)
+      # @raise [ArgumentError] If path not found, circular redirect detected, or too many redirects
+      def read_entry(file_path:, visited: [])
         normalized_path = PathNormalizer.normalize(file_path)
-        @adapter.read_entry(file_path: normalized_path)
+
+        # Detect circular redirects immediately
+        if visited.include?(normalized_path)
+          cycle = visited + [normalized_path]
+          raise ArgumentError,
+            "Circular redirect detected in memory storage: #{cycle.join(" → ")}\n\n" \
+              "This indicates corrupted stub files. Please run MemoryDefrag to repair:\n  " \
+              "MemoryDefrag(action: \"analyze\")"
+        end
+
+        # Check depth limit (prevent infinite chains)
+        if visited.size >= 5
+          chain = visited + [normalized_path]
+          raise ArgumentError,
+            "Memory redirect chain too deep (>5 redirects): #{chain.join(" → ")}\n\n" \
+              "This indicates fragmented memory storage. Please run maintenance:\n  " \
+              "MemoryDefrag(action: \"full\", dry_run: true)  # Preview first\n  " \
+              "MemoryDefrag(action: \"full\", dry_run: false) # Execute"
+        end
+
+        # Read entry from adapter
+        begin
+          entry = @adapter.read_entry(file_path: normalized_path)
+        rescue ArgumentError
+          # If this is a redirect target that doesn't exist, provide helpful error
+          if visited.empty?
+            # Not a redirect, just re-raise original error
+            raise
+          else
+            original_path = visited.first
+            raise ArgumentError,
+              "memory://#{original_path} was redirected to memory://#{normalized_path}, but the target was not found.\n\n" \
+                "The original entry may have been merged or moved incorrectly. " \
+                "Run MemoryDefrag to identify and fix broken redirects:\n  " \
+                "MemoryDefrag(action: \"analyze\")"
+          end
+        end
+
+        # Check if this is a stub redirect
+        if entry.metadata && entry.metadata["stub"] == true
+          redirect_target = entry.metadata["redirect_to"]
+
+          # Validate redirect target exists
+          if redirect_target.nil? || redirect_target.strip.empty?
+            raise ArgumentError,
+              "memory://#{normalized_path} is a stub with invalid redirect metadata.\n\n" \
+                "This should never happen (stubs are created by MemoryDefrag). " \
+                "The stub file may be corrupted. Please report this as a bug."
+          end
+
+          # Follow redirect recursively, tracking visited paths
+          return read_entry(file_path: redirect_target, visited: visited + [normalized_path])
+        end
+
+        # Not a stub, return the entry
+        entry
       end
 
       # Delete an entry

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -207,6 +207,19 @@ module SwarmMemory
         agent_definition.memory_enabled?
       end
 
+      # Contribute to agent serialization
+      #
+      # Preserves memory configuration when agents are cloned (e.g., in NodeOrchestrator).
+      # This allows memory configuration to persist across node transitions.
+      #
+      # @param agent_definition [Agent::Definition] Agent definition
+      # @return [Hash] Memory config to include in to_h
+      def serialize_config(agent_definition:)
+        return {} unless agent_definition.memory
+
+        { memory: agent_definition.memory }
+      end
+
       # Lifecycle: Agent initialized
       #
       # Filters tools by mode (removing non-mode tools), registers LoadSkill,
@@ -287,6 +300,7 @@ module SwarmMemory
       def on_user_message(agent_name:, prompt:, is_first_message:)
         storage = @storages[agent_name]
         return [] unless storage&.semantic_index
+        return [] if prompt.empty?
 
         # Adaptive threshold based on query length
         # Short queries use lower threshold as they have less semantic richness

data/lib/swarm_memory/optimization/defragmenter.rb

@@ -747,7 +747,11 @@ module SwarmMemory
       # @param to [String] Target path
       # @param reason [String] Reason (merged, moved)
       # @return [void]
+      # @raise [ArgumentError] If target path or reason is nil/empty
       def create_stub(from:, to:, reason:)
+        raise ArgumentError, "Cannot create stub without target path" if to.nil? || to.strip.empty?
+        raise ArgumentError, "Cannot create stub without reason" if reason.nil? || reason.strip.empty?
+
         stub_content = "# #{reason} → #{to}\n\nThis entry was #{reason} into #{to}."
 
         @adapter.write(