swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_cli/ui/icons.rb

@@ -31,29 +31,6 @@ module SwarmCLI
       ARROW_RIGHT = "→"
       BULLET = "•"
       COMPRESS = "🗜️"
-
-      # All icons as hash for backward compatibility
-      ALL = {
-        thinking: THINKING,
-        response: RESPONSE,
-        success: SUCCESS,
-        error: ERROR,
-        info: INFO,
-        warning: WARNING,
-        agent: AGENT,
-        tool: TOOL,
-        delegate: DELEGATE,
-        result: RESULT,
-        hook: HOOK,
-        llm: LLM,
-        tokens: TOKENS,
-        cost: COST,
-        time: TIME,
-        sparkles: SPARKLES,
-        arrow_right: ARROW_RIGHT,
-        bullet: BULLET,
-        compress: COMPRESS,
-      }.freeze
     end
   end
 end

data/lib/swarm_cli/version.rb

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

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

@@ -93,10 +93,10 @@ module SwarmMemory
                 "Clear old entries or use smaller content."
             end
 
-            # Strip .md extension and flatten path for disk storage
-            # "concepts/ruby/classes.md" → "concepts--ruby--classes"
+            # Strip .md extension for disk storage
+            # "concepts/ruby/classes.md" → "concepts/ruby/classes"
             base_path = file_path.sub(/\.md\z/, "")
-            disk_path = flatten_path(base_path)
+            disk_path = base_path
 
             # 1. Write content to .md file (stored exactly as provided)
             md_file = File.join(@directory, "#{disk_path}.md")
@@ -162,9 +162,9 @@ module SwarmMemory
           return entry.content
         end
 
-        # Strip .md extension and flatten path
+        # Strip .md extension
         base_path = file_path.sub(/\.md\z/, "")
-        disk_path = flatten_path(base_path)
+        disk_path = base_path
         md_file = File.join(@directory, "#{disk_path}.md")
 
         raise ArgumentError, "memory://#{file_path} not found" unless File.exist?(md_file)
@@ -189,9 +189,9 @@ module SwarmMemory
           return load_virtual_entry(file_path)
         end
 
-        # Strip .md extension and flatten path
+        # Strip .md extension
         base_path = file_path.sub(/\.md\z/, "")
-        disk_path = flatten_path(base_path)
+        disk_path = base_path
         md_file = File.join(@directory, "#{disk_path}.md")
         yaml_file = File.join(@directory, "#{disk_path}.yml")
 
@@ -230,9 +230,9 @@ module SwarmMemory
           @semaphore.acquire do
             raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
 
-            # Strip .md extension and flatten path
+            # Strip .md extension
             base_path = file_path.sub(/\.md\z/, "")
-            disk_path = flatten_path(base_path)
+            disk_path = base_path
             md_file = File.join(@directory, "#{disk_path}.md")
 
             raise ArgumentError, "memory://#{file_path} not found" unless File.exist?(md_file)
@@ -500,29 +500,6 @@ module SwarmMemory
         )
       end
 
-      # Flatten path for disk storage
-      # "concepts/ruby/classes" → "concepts--ruby--classes"
-      #
-      # @param logical_path [String] Logical path with slashes
-      # @return [String] Flattened path with --
-      # Identity function - paths are now stored hierarchically
-      # Kept for backward compatibility during transition
-      #
-      # @param logical_path [String] Logical path
-      # @return [String] Same path (no flattening)
-      def flatten_path(logical_path)
-        logical_path
-      end
-
-      # Identity function - paths are now stored hierarchically
-      # Kept for backward compatibility during transition
-      #
-      # @param disk_path [String] Disk path
-      # @return [String] Same path (no unflattening)
-      def unflatten_path(disk_path)
-        disk_path
-      end
-
       # Check if content is a stub (redirect)
       #
       # @param content [String] File content
@@ -566,7 +543,7 @@ module SwarmMemory
       # @return [void]
       def increment_hits(file_path)
         base_path = file_path.sub(/\.md\z/, "")
-        disk_path = flatten_path(base_path)
+        disk_path = base_path
         yaml_file = File.join(@directory, "#{disk_path}.yml")
         return unless File.exist?(yaml_file)
 
@@ -587,7 +564,7 @@ module SwarmMemory
       # @return [Integer] Size in bytes
       def get_entry_size(file_path)
         base_path = file_path.sub(/\.md\z/, "")
-        disk_path = flatten_path(base_path)
+        disk_path = base_path
         yaml_file = File.join(@directory, "#{disk_path}.yml")
 
         if File.exist?(yaml_file)

data/lib/swarm_memory/core/storage_read_tracker.rb

@@ -2,40 +2,77 @@
 
 module SwarmMemory
   module Core
-    # StorageReadTracker manages read-entry tracking for all agents
+    # StorageReadTracker manages read-entry tracking for all agents with content digest verification
     #
     # This module maintains a global registry of which memory entries each agent
-    # has read during their conversation. This enables enforcement of the
-    # "read-before-edit" rule that ensures agents have context before modifying entries.
+    # has read during their conversation along with SHA256 digests of the content.
+    # This enables enforcement of the "read-before-edit" rule that ensures agents
+    # have context before modifying entries, AND prevents editing entries that have
+    # changed externally since being read.
     #
-    # Each agent maintains an independent set of read entries, keyed by agent identifier.
+    # Each agent maintains an independent map of read entries to content digests.
     module StorageReadTracker
-      @read_entries = {}
+      @read_entries = {} # { agent_id => { entry_path => sha256_digest } }
       @mutex = Mutex.new
 
       class << self
-        # Register that an agent has read a storage entry
+        # Register that an agent has read a storage entry with content digest
         #
         # @param agent_id [Symbol] The agent identifier
         # @param entry_path [String] The storage entry path
-        # @return [void]
-        def register_read(agent_id, entry_path)
+        # @param content [String] Entry content (for digest calculation)
+        # @return [String] The calculated SHA256 digest
+        def register_read(agent_id, entry_path, content)
           @mutex.synchronize do
-            @read_entries[agent_id] ||= Set.new
-            @read_entries[agent_id] << entry_path
+            @read_entries[agent_id] ||= {}
+            digest = Digest::SHA256.hexdigest(content)
+            @read_entries[agent_id][entry_path] = digest
+            digest
           end
         end
 
-        # Check if an agent has read a storage entry
+        # Check if an agent has read an entry AND content hasn't changed
         #
         # @param agent_id [Symbol] The agent identifier
         # @param entry_path [String] The storage entry path
-        # @return [Boolean] true if the agent has read this entry
-        def entry_read?(agent_id, entry_path)
+        # @param storage [Storage] Storage instance to read current content
+        # @return [Boolean] true if agent read entry and content matches
+        def entry_read?(agent_id, entry_path, storage)
           @mutex.synchronize do
             return false unless @read_entries[agent_id]
 
-            @read_entries[agent_id].include?(entry_path)
+            stored_digest = @read_entries[agent_id][entry_path]
+            return false unless stored_digest
+
+            # Check if entry still matches stored digest
+            begin
+              current_content = storage.read(file_path: entry_path)
+              current_digest = Digest::SHA256.hexdigest(current_content)
+              current_digest == stored_digest
+            rescue StandardError
+              false # Entry deleted or inaccessible
+            end
+          end
+        end
+
+        # Get all read entries with digests for snapshot
+        #
+        # @param agent_id [Symbol] The agent identifier
+        # @return [Hash] { entry_path => digest }
+        def get_read_entries(agent_id)
+          @mutex.synchronize do
+            @read_entries[agent_id]&.dup || {}
+          end
+        end
+
+        # Restore read entries with digests from snapshot
+        #
+        # @param agent_id [Symbol] The agent identifier
+        # @param entries_with_digests [Hash] { entry_path => digest }
+        # @return [void]
+        def restore_read_entries(agent_id, entries_with_digests)
+          @mutex.synchronize do
+            @read_entries[agent_id] = entries_with_digests.dup
           end
         end
 

data/lib/swarm_memory/integration/cli_registration.rb

@@ -13,8 +13,9 @@ module SwarmMemory
         #
         # @return [void]
         def register!
-          # Only register if SwarmCLI is present
-          return unless defined?(SwarmCLI)
+          # Only register if SwarmCLI::CommandRegistry is available
+          # Check for the specific class, not just the module
+          return unless defined?(SwarmCLI::CommandRegistry)
 
           # Load CLI commands explicitly (Zeitwerk might not have loaded it yet)
           require_relative "../cli/commands"

data/lib/swarm_memory/integration/sdk_plugin.rb

@@ -156,7 +156,7 @@ module SwarmMemory
       # @return [String] Memory prompt contribution
       def system_prompt_contribution(agent_definition:, storage:)
         # Extract mode from memory config
-        memory_config = agent_definition.memory
+        memory_config = agent_definition.plugin_config(:memory)
         mode = if memory_config.is_a?(SwarmMemory::DSL::MemoryConfig)
           memory_config.mode # MemoryConfig object from DSL
         elsif memory_config.respond_to?(:mode)
@@ -204,20 +204,100 @@ module SwarmMemory
       # @param agent_definition [Agent::Definition] Agent definition
       # @return [Boolean] True if agent has memory configuration
       def storage_enabled?(agent_definition)
-        agent_definition.memory_enabled?
+        memory_config = agent_definition.plugin_config(:memory)
+        return false if memory_config.nil?
+
+        # MemoryConfig object (from DSL)
+        return memory_config.enabled? if memory_config.respond_to?(:enabled?)
+
+        # Hash (from YAML) - check for directory key
+        if memory_config.is_a?(Hash)
+          directory = memory_config[:directory] || memory_config["directory"]
+          return !directory.nil? && !directory.to_s.strip.empty?
+        end
+
+        false
       end
 
       # Contribute to agent serialization
       #
-      # Preserves memory configuration when agents are cloned (e.g., in NodeOrchestrator).
+      # Preserves memory configuration when agents are cloned (e.g., in Workflow).
       # 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_config = agent_definition.plugin_config(:memory)
+        return {} unless memory_config
+
+        { memory: memory_config }
+      end
+
+      # Snapshot plugin-specific state for an agent
+      #
+      # Captures memory read tracking state for session persistence.
+      # This allows agents to remember which memory entries they've read
+      # across sessions.
+      #
+      # @param agent_name [Symbol] Agent identifier
+      # @return [Hash] Plugin-specific state
+      def snapshot_agent_state(agent_name)
+        entries_with_digests = Core::StorageReadTracker.get_read_entries(agent_name)
+        return {} if entries_with_digests.empty?
+
+        { read_entries: entries_with_digests }
+      end
+
+      # Restore plugin-specific state for an agent
+      #
+      # Restores memory read tracking state from snapshot.
+      # This is idempotent - calling multiple times with same state
+      # produces the same result.
+      #
+      # @param agent_name [Symbol] Agent identifier
+      # @param state [Hash] Previously snapshotted state (with symbol keys)
+      # @return [void]
+      def restore_agent_state(agent_name, state)
+        entries = state[:read_entries] || state["read_entries"]
+        return unless entries
+
+        Core::StorageReadTracker.restore_read_entries(agent_name, entries)
+      end
+
+      # Get digest for a memory tool result
+      #
+      # Returns the digest for a MemoryRead tool call, enabling change detection
+      # hooks to know if a memory entry has been modified since last read.
+      #
+      # @param agent_name [Symbol] Agent identifier
+      # @param tool_name [String] Name of the tool
+      # @param path [String] Path of the memory entry
+      # @return [String, nil] Digest string or nil if not a memory tool
+      def get_tool_result_digest(agent_name:, tool_name:, path:)
+        return unless tool_name == "MemoryRead"
+
+        Core::StorageReadTracker.get_read_entries(agent_name)[path]
+      end
 
-        { memory: agent_definition.memory }
+      # Translate YAML configuration into DSL calls
+      #
+      # Called during YAML-to-DSL translation. Handles memory-specific YAML
+      # configuration and translates it into DSL method calls on the builder.
+      #
+      # @param builder [Agent::Builder] Builder instance (self in DSL context)
+      # @param agent_config [Hash] Full agent config from YAML
+      # @return [void]
+      def translate_yaml_config(builder, agent_config)
+        memory_config = agent_config[:memory]
+        return unless memory_config
+
+        builder.instance_eval do
+          memory do
+            directory(memory_config[:directory]) if memory_config[:directory]
+            adapter(memory_config[:adapter]) if memory_config[:adapter]
+            mode(memory_config[:mode]) if memory_config[:mode]
+          end
+        end
       end
 
       # Lifecycle: Agent initialized
@@ -239,7 +319,7 @@ module SwarmMemory
         return unless storage # Only proceed if memory is enabled for this agent
 
         # Extract mode from memory config
-        memory_config = agent_definition.memory
+        memory_config = agent_definition.plugin_config(:memory)
         mode = if memory_config.is_a?(SwarmMemory::DSL::MemoryConfig)
           memory_config.mode # MemoryConfig object from DSL
         elsif memory_config.respond_to?(:mode)
@@ -250,9 +330,12 @@ module SwarmMemory
           :interactive # Default
         end
 
-        # Store storage and mode for this agent
-        @storages[agent_name] = storage
-        @modes[agent_name] = mode
+        # V7.0: Extract base name for storage tracking (delegation instances share storage)
+        base_name = agent_name.to_s.split("@").first.to_sym
+
+        # Store storage and mode using BASE NAME
+        @storages[base_name] = storage # ← Changed from agent_name to base_name
+        @modes[base_name] = mode # ← Changed from agent_name to base_name
 
         # Get mode-specific tools
         allowed_tools = tools_for_mode(mode)
@@ -278,7 +361,7 @@ module SwarmMemory
             agent_definition: agent_definition,
           )
 
-          agent.with_tool(load_skill_tool)
+          agent.add_tool(load_skill_tool)
         end
 
         # Mark mode-specific memory tools + LoadSkill as immutable
@@ -298,9 +381,12 @@ module SwarmMemory
       # @param is_first_message [Boolean] True if first message
       # @return [Array<String>] System reminders (0-2 reminders)
       def on_user_message(agent_name:, prompt:, is_first_message:)
-        storage = @storages[agent_name]
+        # V7.0: Extract base name for storage lookup (delegation instances share storage)
+        base_name = agent_name.to_s.split("@").first.to_sym
+        storage = @storages[base_name] # ← Changed from agent_name to base_name
+
         return [] unless storage&.semantic_index
-        return [] if prompt.empty?
+        return [] if prompt.nil? || prompt.empty?
 
         # Adaptive threshold based on query length
         # Short queries use lower threshold as they have less semantic richness

data/lib/swarm_memory/tools/memory_edit.rb

@@ -124,8 +124,8 @@ module SwarmMemory
         # Read current content (this will raise ArgumentError if entry doesn't exist)
         content = @storage.read(file_path: file_path)
 
-        # Enforce read-before-edit
-        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path)
+        # Enforce read-before-edit with content verification
+        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path, @storage)
           return validation_error(
             "Cannot edit memory entry without reading it first. " \
               "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \

data/lib/swarm_memory/tools/memory_multi_edit.rb

@@ -140,8 +140,8 @@ module SwarmMemory
         # Read current content (this will raise ArgumentError if entry doesn't exist)
         content = @storage.read(file_path: file_path)
 
-        # Enforce read-before-edit
-        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path)
+        # Enforce read-before-edit with content verification
+        unless Core::StorageReadTracker.entry_read?(@agent_name, file_path, @storage)
           return validation_error(
             "Cannot edit memory entry without reading it first. " \
               "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \

data/lib/swarm_memory/tools/memory_read.rb

@@ -64,12 +64,12 @@ module SwarmMemory
       # @param file_path [String] Path to read from
       # @return [String] JSON with content and metadata
       def execute(file_path:)
-        # Register this read in the tracker
-        Core::StorageReadTracker.register_read(@agent_name, file_path)
-
         # Read full entry with metadata
         entry = @storage.read_entry(file_path: file_path)
 
+        # Register this read in the tracker with content digest
+        Core::StorageReadTracker.register_read(@agent_name, file_path, entry.content)
+
         # Always return JSON format (metadata always exists - at minimum title)
         format_as_json(entry)
       rescue ArgumentError => e

data/lib/swarm_memory/version.rb

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

data/lib/swarm_memory.rb

@@ -31,13 +31,18 @@ loader = Zeitwerk::Loader.new
 loader.tag = File.basename(__FILE__, ".rb")
 loader.push_dir("#{__dir__}/swarm_memory", namespace: SwarmMemory)
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "dsl" => "DSL",
+  "sdk_plugin" => "SDKPlugin",
+)
 loader.setup
 
 # Explicitly load DSL components and extensions to inject into SwarmSDK
 # These must be loaded after Zeitwerk but before anything uses them
 require_relative "swarm_memory/dsl/memory_config"
 require_relative "swarm_memory/dsl/builder_extension"
-require_relative "swarm_memory/chat_extension"
+# NOTE: ChatExtension was removed in favor of SDK's built-in remove_tool method
 
 module SwarmMemory
   class << self

data/lib/swarm_sdk/agent/builder.rb

@@ -24,6 +24,13 @@ module SwarmSDK
       # Expose mcp_servers for tests
       attr_reader :mcp_servers
 
+      # Get tools list as array for validation
+      #
+      # @return [Array<Symbol>] List of tools
+      def tools_list
+        @tools.to_a
+      end
+
       def initialize(name)
         @name = name
         @description = nil
@@ -52,6 +59,8 @@ module SwarmSDK
         @permissions_config = {}
         @default_permissions = {} # Set by SwarmBuilder from all_agents
         @memory_config = nil
+        @shared_across_delegations = nil # nil = not set (will default to false in Definition)
+        @context_management_config = nil # Context management DSL hooks
       end
 
       # Set/get agent model
@@ -267,6 +276,80 @@ module SwarmSDK
         @permissions_config = PermissionsBuilder.build(&block)
       end
 
+      # Configure delegation isolation mode
+      #
+      # @param enabled [Boolean] If true, allows sharing instances across delegations (old behavior)
+      #                          If false (default), creates isolated instances per delegation
+      # @return [self] Returns self for method chaining
+      #
+      # @example
+      #   shared_across_delegations true  # Allow sharing (old behavior)
+      def shared_across_delegations(enabled)
+        @shared_across_delegations = enabled
+        self
+      end
+
+      # Configure context management handlers
+      #
+      # Define custom handlers for context warning thresholds (60%, 80%, 90%).
+      # Handlers receive a rich context object with message manipulation methods.
+      # When a custom handler is registered, automatic compression is disabled
+      # for that threshold, giving full control to the handler.
+      #
+      # @yield Context management DSL block
+      # @return [void]
+      #
+      # @example Basic compression at 60%
+      #   context_management do
+      #     on :warning_60 do |ctx|
+      #       ctx.compress_tool_results(keep_recent: 10)
+      #     end
+      #   end
+      #
+      # @example Multiple thresholds with different strategies
+      #   context_management do
+      #     on :warning_60 do |ctx|
+      #       ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
+      #     end
+      #
+      #     on :warning_80 do |ctx|
+      #       ctx.prune_old_messages(keep_recent: 30)
+      #       ctx.compress_tool_results(keep_recent: 5, truncate_to: 200)
+      #     end
+      #
+      #     on :warning_90 do |ctx|
+      #       ctx.log_action("emergency_pruning", remaining: ctx.tokens_remaining)
+      #       ctx.prune_old_messages(keep_recent: 15)
+      #     end
+      #   end
+      #
+      # @example Conditional logic based on metrics
+      #   context_management do
+      #     on :warning_80 do |ctx|
+      #       if ctx.usage_percentage > 85
+      #         ctx.prune_old_messages(keep_recent: 10)
+      #       else
+      #         ctx.compress_tool_results(keep_recent: 5)
+      #       end
+      #     end
+      #   end
+      def context_management(&block)
+        builder = ContextManagement::Builder.new
+        builder.instance_eval(&block)
+        @context_management_config = builder.build
+      end
+
+      # Set permissions directly from hash (for YAML translation)
+      #
+      # This is intentionally separate from permissions() to keep the DSL clean.
+      # Called by Configuration when translating YAML permissions.
+      #
+      # @param hash [Hash] Permissions configuration hash
+      # @return [void]
+      def permissions_hash=(hash)
+        @permissions_config = hash || {}
+      end
+
       # Check if model has been explicitly set (not default)
       #
       # Used by Swarm::Builder to determine if all_agents model should apply.
@@ -374,10 +457,18 @@ module SwarmSDK
         agent_config[:permissions] = @permissions_config if @permissions_config.any?
         agent_config[:default_permissions] = @default_permissions if @default_permissions.any?
         agent_config[:memory] = @memory_config if @memory_config
+        agent_config[:shared_across_delegations] = @shared_across_delegations unless @shared_across_delegations.nil?
 
         # Convert DSL hooks to HookDefinition format
         agent_config[:hooks] = convert_hooks_to_definitions if @hooks.any?
 
+        # Merge context management hooks into agent hooks
+        if @context_management_config
+          agent_config[:hooks] ||= {}
+          agent_config[:hooks][:context_warning] ||= []
+          agent_config[:hooks][:context_warning].concat(@context_management_config)
+        end
+
         Agent::Definition.new(@name, agent_config)
       end