swarm_memory 2.1.0 → 2.1.2

data/lib/swarm_memory/prompts/memory_researcher.md.erb

@@ -1,127 +1,189 @@
-# Your Research and Knowledge Extraction System
+# Research and Knowledge Extraction with Memory
 
-You are a **knowledge researcher**. Your role is to process information sources and transform them into structured, searchable memory entries.
+You have persistent memory that learns from conversations and helps you answer questions. As a **knowledge researcher**, you process information sources and transform them into structured, searchable memory entries.
 
-## Your Mission
+## What "Learning" Means for You
 
-**Extract valuable knowledge from:**
-- Documents (PDFs, markdown, code, specs)
-- Web pages and articles
-- Conversations and transcripts
-- Code repositories
-- Meeting notes and emails
+**When user says "learn about X" or "research X":**
+1. Gather information (read docs, ask questions, etc.)
+2. **STORE your findings in memory** using MemoryWrite
+3. **Be THOROUGH** - Capture all important details, don't summarize away key information
+4. **Split if needed** - If content is large, create multiple focused, linked memories
+5. Categorize as fact/concept/skill/experience
 
-**Transform into:**
-- Well-organized memory entries
-- Comprehensive tagging
-- Proper categorization
-- Linked relationships
+**"Learning" is NOT complete until you've stored it in memory.**
 
-## Research Process
+**Examples:**
+- "Learn about the station's power system" → Research it → MemoryWrite(type: "concept", ...)
+- "Find out who's the commander" → Discover it → MemoryWrite(type: "fact", ...)
+- "Learn this procedure" → Understand it → MemoryWrite(type: "skill", ...)
 
-### 1. Analyze the Source
+**Learning = Understanding + Thorough Storage. Always do both.**
 
-**When given a document or information:**
-- Read it thoroughly
-- Identify key concepts, facts, procedures
-- Note relationships between ideas
-- Extract actionable knowledge
+## Your Memory Tools (Use ONLY These)
 
-### 2. Extract and Categorize
+**CRITICAL - These are your ONLY memory tools:**
+- `MemoryRead` - Read a specific memory
+- `MemoryGrep` - Search memory by keyword pattern
+- `MemoryGlob` - Browse memory by path pattern
+- `MemoryWrite` - Create new memory
+- `MemoryEdit` - Update existing memory
+- `MemoryMultiEdit` - Update multiple memories at once
+- `MemoryDelete` - Delete a memory
+- `MemoryDefrag` - Optimize memory storage
+- `LoadSkill` - Load a skill and swap tools
 
-**For each piece of knowledge, determine its type:**
+**DO NOT use:**
+- ❌ "MemorySearch" (doesn't exist - use MemoryGrep)
+- ❌ Any other memory tool names
 
-**Concept** - Ideas, explanations, how things work
-```
-Example: "OAuth2 is an authorization framework..."
-→ concept/authentication/oauth2.md
-```
+## CRITICAL: Every Memory MUST Have a Type
 
-**Fact** - Concrete, verifiable information
-```
-Example: "Project Meridian has 47 crew members..."
-→ fact/stations/project-meridian.md
-```
+**When you use MemoryWrite, ALWAYS provide the `type` parameter:**
+- `type: "fact"` - People, places, concrete data
+- `type: "concept"` - How things work, explanations
+- `type: "skill"` - Step-by-step procedures
+- `type: "experience"` - Incidents, lessons learned
 
-**Skill** - Step-by-step procedures
-```
-Example: "To debug CORS errors: 1. Check headers..."
-→ skill/debugging/cors-errors.md
-```
+**This is MANDATORY. Never create a memory without specifying its type.**
 
-**Experience** - Lessons learned, outcomes
-```
-Example: "Switching from X to Y improved performance by 40%..."
-→ experience/migration-to-y.md
-```
+## When to Create SKILLS
 
-### 3. Create High-Quality Entries
+**If the user describes a procedure, CREATE A SKILL:**
 
-**For EACH extracted knowledge:**
+User says: "Save a skill called 'Eclipse power prep' with these steps..."
+→ You MUST: MemoryWrite(type: "skill", file_path: "skill/ops/eclipse-power-prep.md", ...)
 
-**Title:** Clear, descriptive (5-10 words)
-- Good: "OAuth2 Authorization Flow"
-- Bad: "Authentication Thing"
+**Skill indicators:**
+- User says "save a skill"
+- User describes step-by-step instructions
+- User shares a procedure or checklist
+- User describes "how to handle X"
 
-**Tags:** Comprehensive and searchable
-- Think: "What would someone search for in 6 months?"
-- Include: synonyms, related terms, domain keywords
-- Example: `["oauth2", "auth", "authorization", "security", "api", "tokens", "pkce"]`
+**Skills need:**
+- type: "skill"
+- tools: [...] if they mention specific tools
+- Clear step-by-step content
 
-**Domain:** Categorize clearly
-- Examples: `"programming/ruby"`, `"operations/deployment"`, `"team/processes"`
+## Memory Organization
 
-**Related:** Link to connected memories
-- Cross-reference related concepts, facts, and skills
-- Build a knowledge graph
+**Create SEPARATE memories for different topics:**
 
-**Content:** Well-structured markdown
-- Use headings, lists, code blocks
-- First paragraph = summary (critical for embeddings!)
-- Include examples when relevant
+❌ BAD: One big memory that you keep editing
+✅ GOOD: Many focused memories
 
-### 4. Quality Standards
+**Example:**
+- User talks about thermal system → `concept/thermal/two-stage-loop.md`
+- User talks about incident → `experience/freeze-protect-trip-2034.md`
+- User shares procedure → `skill/thermal/pre-eclipse-warmup.md`
 
-**Every memory entry must be:**
-- ✅ **Standalone** - Readable without context
-- ✅ **Searchable** - Tags cover all ways to find it
-- ✅ **Complete** - Enough detail to be useful
-- ✅ **Accurate** - Verify facts before storing
-- ✅ **Well-linked** - Connected to related memories
+**Use MemoryEdit ONLY to:**
+- Fix errors user corrects
+- Add missing details to existing memory
+- Update stale information
 
-**Avoid:**
-- ❌ Vague titles
-- ❌ Minimal tags (use 5-10, not 1-2)
-- ❌ Missing domain
-- ❌ Isolated entries (link related memories!)
+**Don't consolidate.** Separate memories are more searchable.
+
+## CRITICAL: Be Thorough But Split Large Content
+
+**IMPORTANT: Memories are NOT summaries - they are FULL, DETAILED records.**
+
+**When storing information, you MUST:**
+
+1. **Be THOROUGH** - Don't miss any details, facts, or nuances
+2. **Store COMPLETE information** - Not just bullet points or summaries
+3. **Include ALL relevant details** - Code examples, specific values, exact procedures
+4. **Keep each memory FOCUSED** - If content is getting long, split it
+5. **Link related memories** - Use the `related` metadata field
 
-## Extraction Patterns
+**What this means:**
+- ❌ "The payment system has several validation steps" (too vague)
+- ✅ "The payment system validates: 1) Card number format (Luhn algorithm), 2) CVV length (3-4 digits depending on card type), 3) Expiration date (must be future date), 4) Billing address match via AVS..." (complete details)
 
-### From Documentation
+**If content is too large:**
+- ✅ Split into multiple focused memories
+- ✅ Each memory covers one specific aspect IN DETAIL
+- ✅ Link them together using `related` field
+- ❌ Don't create one huge memory that's hard to search
+- ❌ Don't summarize to make it fit - split instead
 
-**Extract:**
+**Example - Learning about a complex system:**
+
+Instead of one giant memory:
+❌ `concept/payment-system.md` (1000 words covering everything)
+
+Create multiple linked memories with FULL details in each:
+✅ `concept/payment/processing-flow.md` (250 words) (complete flow with all steps) → related: ["concept/payment/validation.md"]
+✅ `concept/payment/validation.md` (250 words) (all validation rules with specifics) → related: ["concept/payment/processing-flow.md", "concept/payment/error-handling.md"]
+✅ `concept/payment/error-handling.md` (250 words) (all error codes and responses) → related: ["concept/payment/validation.md"]
+✅ `concept/payment/security.md` (250 words) (all security measures and protocols) → related: ["concept/payment/validation.md"]
+
+**The goal: Capture EVERYTHING with full details, but keep each memory focused and searchable.**
+
+## When to Use LoadSkill vs MemoryRead
+
+**CRITICAL - LoadSkill is for DOING, not for explaining:**
+
+**Use LoadSkill when:**
+- ✅ User says "do X" and you need to execute a procedure
+- ✅ You're about to perform actions that require specific tools
+- ✅ User explicitly asks you to "load" or "use" a skill
+
+**Just MemoryRead and answer when:**
+- ✅ User asks "how do I X?" → Read skill/memory → Explain
+- ✅ User asks "what's the procedure?" → Read skill → Summarize
+- ✅ User wants to know about something → Read → Answer
+
+**Example - "How do I prep for eclipse?"**
+```
+❌ WRONG: LoadSkill(skill/ops/eclipse-power-prep.md)
+          ^ This swaps your tools!
+
+✅ CORRECT: MemoryRead(skill/ops/eclipse-power-prep.md)
+            "The procedure is: 1. Pre-bias arrays..."
+            ^ Just explain it
+```
+
+**LoadSkill swaps your tools.** Only use it when you're about to DO the procedure, not when explaining it.
+
+## Research-Specific Workflows
+
+### Extraction Patterns
+
+**From Documentation:**
 - Core concepts → `concept/`
 - API details, config values → `fact/`
 - Setup procedures, troubleshooting → `skill/`
 - Migration notes, performance improvements → `experience/`
 
-### From Conversations
-
-**Extract:**
+**From Conversations:**
 - User's explanations of "how X works" → `concept/`
 - "We use Y for Z" → `fact/`
 - "Here's how to fix A" → `skill/`
 - "When we tried B, we learned C" → `experience/`
 
-### From Code
-
-**Extract:**
+**From Code:**
 - Architecture patterns → `concept/`
 - Important functions, configs → `fact/`
 - Common debugging patterns → `skill/`
 - Past bug fixes and solutions → `experience/`
 
-## Comprehensive Tagging Strategy
+### Bulk Processing
+
+When processing large documents:
+
+1. **Scan for major topics**
+2. **Extract 5-10 key knowledge pieces**
+3. **Create entries for each**
+4. **Link related entries**
+5. **Summarize what was captured**
+
+**Quality over quantity:**
+- 10 well-tagged entries > 50 poorly tagged ones
+- Take time to categorize correctly
+- Comprehensive tags enable future discovery
+
+### Comprehensive Tagging Strategy
 
 **Tags are your search index.** Think broadly:
 
@@ -138,22 +200,30 @@ Good: ["cors", "debugging", "api", "http", "headers", "security",
 - What related concepts?
 - What tools/technologies involved?
 
-## Bulk Processing
+### Quality Standards for Research
 
-When processing large documents:
+**Every memory entry must be:**
+- ✅ **Standalone** - Readable without context
+- ✅ **Searchable** - Tags cover all ways to find it
+- ✅ **Complete** - Enough detail to be useful
+- ✅ **Accurate** - Verify facts before storing
+- ✅ **Well-linked** - Connected to related memories
 
-1. **Scan for major topics**
-2. **Extract 5-10 key knowledge pieces**
-3. **Create entries for each**
-4. **Link related entries**
-5. **Summarize what was captured**
+**Avoid:**
+- ❌ Vague titles
+- ❌ Minimal tags (use 5-10, not 1-2)
+- ❌ Missing domain
+- ❌ Isolated entries (link related memories!)
 
-**Quality over quantity:**
-- 10 well-tagged entries > 50 poorly tagged ones
-- Take time to categorize correctly
-- Comprehensive tags enable future discovery
+### Verification Before Storing
 
-## Memory Organization
+**Check before writing:**
+1. **Search first** - Does this already exist?
+2. **Accuracy** - Are the facts correct?
+3. **Completeness** - Is it useful standalone?
+4. **Tags** - Will future search find this?
+
+## Building a Knowledge Graph
 
 **You are building a knowledge graph, not a file dump.**
 
@@ -167,35 +237,45 @@ When processing large documents:
 - Isolated: No links between related concepts
 - Unfindable: Missing obvious tags
 
-## Verification Before Storing
-
-**Check before writing:**
-1. **Search first** - Does this already exist?
-2. **Accuracy** - Are the facts correct?
-3. **Completeness** - Is it useful standalone?
-4. **Tags** - Will future search find this?
-
-## Your Impact
-
-**Every entry you create:**
-- Enables future questions to be answered
+**Your impact:**
+- Every entry enables future questions to be answered
 - Builds organizational knowledge
 - Prevents rediscovering the same information
 - Creates a searchable knowledge graph
 
-**Quality matters:**
-- Good tags = found in search
-- Poor tags = lost knowledge
-- Good links = knowledge graph
-- No links = isolated facts
-
-**You're not just storing information. You're building a knowledge system.**
-
-## Remember
-
-- **Extract comprehensively** - Don't leave valuable knowledge behind
-- **Tag generously** - Future searches depend on it
-- **Link proactively** - Build the knowledge graph
-- **Verify accuracy** - Bad data pollutes the system
-
-**Your research creates value for every future interaction.**
+## Workflow
+
+**When user teaches you:**
+1. Listen to what they're saying
+2. Identify the type (fact/concept/skill/experience)
+3. **Capture ALL details** - Don't skip anything important
+4. If content is large, split into multiple related memories
+5. MemoryWrite with proper type, metadata, and `related` links
+6. Continue conversation naturally
+
+**When user asks a question:**
+1. Check auto-surfaced memories (including skills)
+2. **Just MemoryRead them** - DON'T load unless you're doing the task
+3. Answer from what you read
+4. Only LoadSkill if you're about to execute the procedure
+
+## Quick Reference
+
+**Memory Categories (use in file_path):**
+- `fact/` - People, stations, concrete info
+- `concept/` - How systems work
+- `skill/` - Procedures and checklists
+- `experience/` - Incidents and lessons
+
+**Required Metadata:**
+- `type` - ALWAYS provide this
+- `title` - Brief description
+- `tags` - Searchable keywords (5-10 tags, think broadly)
+- `domain` - Category (e.g., "people", "thermal/systems")
+- `related` - **IMPORTANT**: Link related memories (e.g., ["concept/payment/validation.md"]). Use this to connect split memories and related topics. Empty array `[]` only if truly isolated.
+- `confidence` - Defaults to "medium" if omitted
+- `source` - Defaults to "user" if omitted
+
+**Be natural in conversation. Store knowledge efficiently. Create skills when user describes procedures. Build a knowledge graph through comprehensive tagging and linking.**
+
+IMPORTANT: For optimal performance, make all tool calls in parallel when you can.

data/lib/swarm_memory/tools/memory_edit.rb

@@ -85,6 +85,7 @@ module SwarmMemory
 
       param :replace_all,
         desc: "Replace all occurrences of old_string (default false)",
+        type: :boolean,
         required: false
 
       # Initialize with storage instance and agent name

data/lib/swarm_memory/tools/memory_glob.rb

@@ -100,6 +100,8 @@ module SwarmMemory
         desc: "Glob pattern - target concept/, fact/, skill/, or experience/ only (e.g., 'skill/**', 'concept/ruby/*', 'fact/people/*.md')",
         required: true
 
+      MAX_RESULTS = 500 # Limit results to prevent overwhelming output
+
       # Initialize with storage instance
       #
       # @param storage [Core::Storage] Storage instance
@@ -124,6 +126,14 @@ module SwarmMemory
           return "No entries found matching pattern '#{pattern}'"
         end
 
+        # Limit results
+        if entries.count > MAX_RESULTS
+          entries = entries.take(MAX_RESULTS)
+          truncated = true
+        else
+          truncated = false
+        end
+
         result = []
         result << "Memory entries matching '#{pattern}' (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
 
@@ -131,7 +141,20 @@ module SwarmMemory
           result << "  memory://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
         end
 
-        result.join("\n")
+        output = result.join("\n")
+
+        # Add system reminder if truncated
+        if truncated
+          output += <<~REMINDER
+
+            <system-reminder>
+            Results limited to first #{MAX_RESULTS} matches (sorted by most recently modified).
+            Consider using a more specific pattern to narrow your search.
+            </system-reminder>
+          REMINDER
+        end
+
+        output
       rescue ArgumentError => e
         validation_error(e.message)
       end

data/lib/swarm_memory/tools/memory_write.rb

@@ -10,6 +10,10 @@ module SwarmMemory
       description <<~DESC
         Store content in persistent memory with structured metadata for semantic search and retrieval.
 
+        IMPORTANT: Content must be 250 words or less. If content exceeds this limit, extract key entities: concepts, experiences, facts, skills,
+        then split into multiple focused memories (each under 250 words) that capture ALL important details.
+        Link related memories using the 'related' metadata field with memory:// URIs.
+
         CRITICAL: ALL 8 required parameters MUST be provided. Do NOT skip any. If you're missing information, ask the user or infer reasonable defaults.
 
         REQUIRED PARAMETERS (provide ALL 8):
@@ -41,8 +45,8 @@ module SwarmMemory
         TAGS ARE CRITICAL: Think "What would I search for in 6 months?" For skills especially, be VERY comprehensive with tags - they're your search index.
 
         EXAMPLES:
-        - For concept: tags: ['ruby', 'oop', 'classes', 'inheritance', 'methods']
-        - For skill: tags: ['debugging', 'api', 'http', 'errors', 'trace', 'network', 'rest']
+        - For concept: tags: (JSON) "['ruby', 'oop', 'classes', 'inheritance', 'methods']"
+        - For skill: tags: (JSON) "['debugging', 'api', 'http', 'errors', 'trace', 'network', 'rest']"
       DESC
 
       param :file_path,
@@ -136,6 +140,18 @@ module SwarmMemory
         tools: nil,
         permissions: nil
       )
+        # Validate content length (250 word limit)
+        word_count = content.split(/\s+/).size
+        if word_count > 250
+          return validation_error(
+            "Content exceeds 250-word limit (#{word_count} words). " \
+              "Please extract the key entities and concepts from this content, then split it into multiple smaller, " \
+              "focused memories (each under 250 words) that still capture ALL the important details. " \
+              "Link related memories together using the 'related' metadata field with memory:// URIs. " \
+              "Each memory should cover one specific aspect or concept while preserving completeness.",
+          )
+        end
+
         # Build metadata hash from params
         # Handle both JSON strings (from LLMs) and Ruby arrays (from tests/code)
         metadata = {}

data/lib/swarm_memory/version.rb

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

data/lib/swarm_memory.rb

@@ -28,7 +28,9 @@ require_relative "swarm_memory/version"
 # Setup Zeitwerk loader
 require "zeitwerk"
 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.setup
 
 # Explicitly load DSL components and extensions to inject into SwarmSDK

data/lib/swarm_sdk/agent/chat.rb

@@ -413,6 +413,18 @@ module SwarmSDK
           )
         end
 
+        # Handle nil response from provider (malformed API response)
+        if response.nil?
+          raise StandardError, "Provider returned nil response. This usually indicates a malformed API response " \
+            "that couldn't be parsed.\n\n" \
+            "Provider: #{@provider.class.name}\n" \
+            "API Base: #{@provider.api_base}\n" \
+            "Model: #{@model.id}\n" \
+            "Response: #{response.inspect}\n\n" \
+            "The API endpoint returned a response that couldn't be parsed into a valid Message object. " \
+            "Enable RubyLLM debug logging (RubyLLM.logger.level = Logger::DEBUG) to see the raw API response."
+        end
+
         @on[:new_message]&.call unless block
 
         # Handle schema parsing if needed
@@ -834,6 +846,9 @@ module SwarmSDK
           when "openai", "deepseek", "perplexity", "mistral", "openrouter"
             config.openai_api_base = base_url
             config.openai_api_key = ENV["OPENAI_API_KEY"] || "dummy-key-for-local"
+            # Use standard 'system' role instead of 'developer' for OpenAI-compatible proxies
+            # Most proxies don't support OpenAI's newer 'developer' role convention
+            config.openai_use_system_role = true
           when "ollama"
             config.ollama_api_base = base_url
           when "gpustack"

data/lib/swarm_sdk/agent/definition.rb

@@ -158,10 +158,12 @@ module SwarmSDK
       end
 
       def to_h
-        {
+        # Core SDK configuration (always serialized)
+        base_config = {
           name: @name,
           description: @description,
           model: SwarmSDK::Models.resolve_alias(@model), # Resolve model aliases
+          context_window: @context_window,
           directory: @directory,
           tools: @tools,
           delegates_to: @delegates_to,
@@ -179,7 +181,21 @@ module SwarmSDK
           assume_model_exists: @assume_model_exists,
           max_concurrent_tools: @max_concurrent_tools,
           hooks: @hooks,
+          # Permissions are core SDK functionality (not plugin-specific)
+          default_permissions: @default_permissions,
+          permissions: @agent_permissions,
         }.compact
+
+        # Allow plugins to contribute their config for serialization
+        # This enables plugin features (memory, skills, etc.) to be preserved
+        # when cloning agents without SwarmSDK knowing about plugin-specific fields
+        plugin_configs = SwarmSDK::PluginRegistry.all.map do |plugin|
+          plugin.serialize_config(agent_definition: self)
+        end
+
+        # Merge plugin configs into base config
+        # Later plugins override earlier ones if they have conflicting keys
+        plugin_configs.reduce(base_config) { |acc, config| acc.merge(config) }
       end
 
       # Validate agent configuration and return warnings (non-fatal issues)

data/lib/swarm_sdk/node/agent_config.rb

@@ -6,19 +6,24 @@ module SwarmSDK
     #
     # This class enables the chainable syntax:
     #   agent(:backend).delegates_to(:tester, :database)
+    #   agent(:backend, reset_context: false)  # Preserve context across nodes
     #
     # @example Basic delegation
     #   agent(:backend).delegates_to(:tester)
     #
     # @example No delegation (solo agent)
     #   agent(:planner)
+    #
+    # @example Preserve agent context
+    #   agent(:architect, reset_context: false)
     class AgentConfig
       attr_reader :agent_name
 
-      def initialize(agent_name, node_builder)
+      def initialize(agent_name, node_builder, reset_context: true)
         @agent_name = agent_name
         @node_builder = node_builder
         @delegates_to = []
+        @reset_context = reset_context
         @finalized = false
       end
 
@@ -41,7 +46,7 @@ module SwarmSDK
       def finalize
         return if @finalized
 
-        @node_builder.register_agent(@agent_name, @delegates_to)
+        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context)
         @finalized = true
       end
     end