swarm_memory 2.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bef387c2612e9bb80f24694abae15aee7b71edc30477ffd5449c83eb9d7f772
-  data.tar.gz: c1343d0a08ae0f7ae0514c8836fb4e7e753457b78295e3cd0c6596c1bf327d42
+  metadata.gz: 38d427a70039bc09a7a1bbad5a0f2c9f28e46d80a954587ab27f04ad33c66e2f
+  data.tar.gz: 3942488b1873520a984493c6270085b0f6f2e0e01560bea349903463d01bda11
 SHA512:
-  metadata.gz: a60b1273dc38f2f5109754fd73b9368172dc06e844daa24a269651ff5887e10a0b066cb9f280a19b100251ce577916aa8c0fcfd26c3db1613fa4e18196dda7ce
-  data.tar.gz: 4543c657130eb2eaa131dba008a557ca4816b87aa5e24a54653f1fd342f298957c33dcbf8276146315b20f373a70503f12be6fb65386e49198eb4722e12908d1
+  metadata.gz: 945735c0d60be12edc1452ea84059f6a3d6aa68966e687a81d2c8ccbd2492c5b2bdd9099fc4a14c40aaabd1d275cec0a80b35be8c9f5354d217467136493ec57
+  data.tar.gz: f5b0680131c7d38ff229da49031628356c44c4edcb90685b7489e2bc2b30a6d361babf55d3e995d5f28acc62f56b28deaa03829d512f95550dd198b192179df0

data/lib/claude_swarm.rb

@@ -30,13 +30,12 @@ require "thor"
 require "zeitwerk"
 loader = Zeitwerk::Loader.new
 loader.tag = "claude_swarm"
-loader.push_dir("#{__dir__}/claude_swarm", namespace: ClaudeSwarm)
+
 loader.ignore("#{__dir__}/claude_swarm/templates")
 loader.inflector.inflect(
   "cli" => "CLI",
   "openai" => "OpenAI",
 )
-loader.setup
 
 module ClaudeSwarm
   class Error < StandardError; end
@@ -67,3 +66,6 @@ module ClaudeSwarm
     end
   end
 end
+
+loader.push_dir("#{__dir__}/claude_swarm", namespace: ClaudeSwarm)
+loader.setup

data/lib/swarm_cli/version.rb

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

data/lib/swarm_cli.rb

@@ -18,8 +18,7 @@ require "tty/tree"
 
 require "swarm_sdk"
 
-module SwarmCLI
-end
+require_relative "swarm_cli/version"
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.new

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

@@ -107,13 +107,13 @@ User says: "Save a skill called 'Eclipse power prep' with these steps..."
 **Example - Learning about a complex system:**
 
 Instead of one giant memory:
-❌ `concept/payment-system.md` (5000 words covering everything)
+❌ `concept/payment-system.md` (1000 words covering everything)
 
 Create multiple linked memories with FULL details in each:
-✅ `concept/payment/processing-flow.md` (complete flow with all steps) → related: ["concept/payment/validation.md"]
-✅ `concept/payment/validation.md` (all validation rules with specifics) → related: ["concept/payment/processing-flow.md", "concept/payment/error-handling.md"]
-✅ `concept/payment/error-handling.md` (all error codes and responses) → related: ["concept/payment/validation.md"]
-✅ `concept/payment/security.md` (all security measures and protocols) → related: ["concept/payment/validation.md"]
+✅ `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.**
 

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_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):
@@ -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.1"
 end

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 RubyLLM::Error, "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/tools/think.rb

@@ -72,6 +72,8 @@ module SwarmSDK
         back to earlier thinking. Use clear formatting and organization to make it easy to reference
         later. Don't hesitate to think out loud - this tool is designed to augment your cognitive capabilities and help
         you deliver better solutions.
+
+        **CRITICAL:** The Think tool takes only one parameter: thoughts. Do not include any other parameters.
       DESC
 
       param :thoughts,
@@ -79,9 +81,7 @@ module SwarmSDK
         desc: "Your thoughts, plans, calculations, or any notes you want to record",
         required: true
 
-      def execute(thoughts:)
-        return validation_error("thoughts are required") if thoughts.nil? || thoughts.empty?
-
+      def execute(**kwargs)
         "Thought noted."
       end
 

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk.rb

@@ -17,8 +17,7 @@ require "async/semaphore"
 require "ruby_llm"
 require "ruby_llm/mcp"
 
-module SwarmSDK
-end
+require_relative "swarm_sdk/version"
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_memory
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Paulo Arruda
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement