htm 0.0.18 → 0.0.20

data/docs/{architecture → robots}/two-tier-memory.md

@@ -6,64 +6,10 @@ HTM implements a sophisticated two-tier memory architecture that balances the co
 
 The two-tier architecture addresses a fundamental challenge in LLM-based applications: LLMs have limited context windows but need to maintain awareness across long conversations spanning days, weeks, or months.
 
-<svg viewBox="0 0 800 500" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="18" font-weight="bold">Two-Tier Memory Architecture</text>
-
-  <!-- Working Memory (Hot Tier) -->
-  <rect x="50" y="80" width="300" height="180" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="5"/>
-  <text x="200" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Working Memory (Hot)</text>
-  <text x="80" y="140" fill="#B0B0B0" font-size="12">Capacity: Token-limited (128K)</text>
-  <text x="80" y="160" fill="#B0B0B0" font-size="12">Storage: In-memory Ruby Hash</text>
-  <text x="80" y="180" fill="#B0B0B0" font-size="12">Speed: O(1) lookups</text>
-  <text x="80" y="200" fill="#B0B0B0" font-size="12">Lifetime: Process lifetime</text>
-  <text x="80" y="220" fill="#B0B0B0" font-size="12">Eviction: Importance + Recency</text>
-  <text x="80" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Fast, Token-Aware, Volatile</text>
-
-  <!-- Long-Term Memory (Cold Tier) -->
-  <rect x="450" y="80" width="300" height="180" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3" rx="5"/>
-  <text x="600" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory (Cold)</text>
-  <text x="480" y="140" fill="#B0B0B0" font-size="12">Capacity: Unlimited</text>
-  <text x="480" y="160" fill="#B0B0B0" font-size="12">Storage: PostgreSQL + TimescaleDB</text>
-  <text x="480" y="180" fill="#B0B0B0" font-size="12">Speed: O(log n) with indexes</text>
-  <text x="480" y="200" fill="#B0B0B0" font-size="12">Lifetime: Permanent</text>
-  <text x="480" y="220" fill="#B0B0B0" font-size="12">Retrieval: RAG (semantic + temporal)</text>
-  <text x="480" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Durable, Searchable, Persistent</text>
-
-  <!-- Data Flow: Add Memory -->
-  <path d="M 200 280 L 200 320 L 400 320 L 400 280" stroke="#4CAF50" stroke-width="3" fill="none" marker-end="url(#arrow-green)"/>
-  <text x="300" y="310" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Add Memory</text>
-  <text x="300" y="330" text-anchor="middle" fill="#B0B0B0" font-size="10">(Stored in both tiers)</text>
-
-  <!-- Data Flow: Eviction -->
-  <path d="M 350 360 L 600 360" stroke="#FF9800" stroke-width="3" marker-end="url(#arrow-orange)"/>
-  <text x="475" y="350" text-anchor="middle" fill="#FF9800" font-size="12" font-weight="bold">Eviction</text>
-  <text x="475" y="380" text-anchor="middle" fill="#B0B0B0" font-size="10">(Token limit → move to LTM only)</text>
-
-  <!-- Data Flow: Recall -->
-  <path d="M 600 400 L 200 400" stroke="#9C27B0" stroke-width="3" marker-end="url(#arrow-purple)"/>
-  <text x="400" y="390" text-anchor="middle" fill="#9C27B0" font-size="12" font-weight="bold">Recall</text>
-  <text x="400" y="420" text-anchor="middle" fill="#B0B0B0" font-size="10">(RAG search → load back to WM)</text>
-
-  <!-- Never Forget Note -->
-  <rect x="150" y="450" width="500" height="40" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
-  <text x="400" y="475" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">Never Forget: Evicted memories stay in LTM forever (explicit deletion only)</text>
-
-  <defs>
-    <marker id="arrow-green" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
-    </marker>
-    <marker id="arrow-orange" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
-    </marker>
-    <marker id="arrow-purple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
-    </marker>
-  </defs>
-</svg>
+![Two-Tier Memory Architecture](../assets/images/two-tier-memory-architecture.svg)
 
 !!! info "Related ADR"
-    See [ADR-002: Two-Tier Memory Architecture](adrs/002-two-tier-memory.md) for the complete architectural decision record.
+    See [ADR-002: Two-Tier Memory Architecture](../architecture/adrs/002-two-tier-memory.md) for the complete architectural decision record.
 
 ## Working Memory (Hot Tier)
 
@@ -209,55 +155,13 @@ Nodes are evicted in this order:
 3. **High importance, old** (e.g., importance: 9.0, age: 5 days)
 4. **High importance, recent** (e.g., importance: 9.0, age: 1 hour) ← **Kept longest**
 
-<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Eviction Priority (Lower → Higher retention)</text>
-
-  <!-- Priority bars -->
-  <rect x="50" y="80" width="150" height="50" fill="rgba(244, 67, 54, 0.6)" stroke="#F44336" stroke-width="2" rx="3"/>
-  <text x="125" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 1: Evict First</text>
-
-  <rect x="220" y="80" width="150" height="50" fill="rgba(255, 152, 0, 0.6)" stroke="#FF9800" stroke-width="2" rx="3"/>
-  <text x="295" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 2</text>
-
-  <rect x="390" y="80" width="150" height="50" fill="rgba(255, 193, 7, 0.6)" stroke="#FFC107" stroke-width="2" rx="3"/>
-  <text x="465" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 3</text>
-
-  <rect x="560" y="80" width="150" height="50" fill="rgba(76, 175, 80, 0.6)" stroke="#4CAF50" stroke-width="2" rx="3"/>
-  <text x="635" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 4: Keep Longest</text>
-
-  <!-- Details -->
-  <text x="125" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
-  <text x="125" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
-  <text x="125" y="200" text-anchor="middle" fill="#F44336" font-size="10" font-weight="bold">Low value, stale</text>
-
-  <text x="295" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
-  <text x="295" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
-  <text x="295" y="200" text-anchor="middle" fill="#FF9800" font-size="10" font-weight="bold">Low value, recent</text>
-
-  <text x="465" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
-  <text x="465" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
-  <text x="465" y="200" text-anchor="middle" fill="#FFC107" font-size="10" font-weight="bold">High value, older</text>
-
-  <text x="635" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
-  <text x="635" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
-  <text x="635" y="200" text-anchor="middle" fill="#4CAF50" font-size="10" font-weight="bold">High value, fresh</text>
-
-  <!-- Example scenario -->
-  <text x="50" y="250" fill="#E0E0E0" font-size="13" font-weight="bold">Example Eviction Scenario:</text>
-  <text x="50" y="280" fill="#B0B0B0" font-size="11">Working Memory: 127,500 / 128,000 tokens (99% full)</text>
-  <text x="50" y="300" fill="#B0B0B0" font-size="11">New memory to add: 5,000 tokens</text>
-  <text x="50" y="320" fill="#B0B0B0" font-size="11">Need to free: 4,500 tokens</text>
-
-  <text x="50" y="350" fill="#4CAF50" font-size="11">Eviction: Remove Tier 1 and Tier 2 nodes until 4,500+ tokens freed</text>
-  <text x="50" y="370" fill="#4CAF50" font-size="11">Result: Tier 3 and Tier 4 nodes preserved (high importance)</text>
-</svg>
+![Eviction Priority](../assets/images/eviction-priority.svg)
 
 !!! warning "Importance Matters"
     **Assign meaningful importance scores!** Low-importance memories (1.0-3.0) will be evicted first. Use higher scores (7.0-10.0) for critical information like architectural decisions, user preferences, and long-term facts.
 
 !!! info "Related ADR"
-    See [ADR-007: Working Memory Eviction Strategy](adrs/007-eviction-strategy.md) for detailed rationale and alternatives considered.
+    See [ADR-007: Working Memory Eviction Strategy](../architecture/adrs/007-eviction-strategy.md) for detailed rationale and alternatives considered.
 
 ### Context Assembly Strategies
 
@@ -352,50 +256,10 @@ context = htm.create_context(strategy: :balanced)
 # Recent debugging context + important architectural decisions
 ```
 
-<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Balanced Strategy: Importance Decay Over Time</text>
-
-  <!-- Axes -->
-  <line x1="100" y1="350" x2="700" y2="350" stroke="#808080" stroke-width="2"/>
-  <line x1="100" y1="350" x2="100" y2="80" stroke="#808080" stroke-width="2"/>
-
-  <!-- X-axis labels -->
-  <text x="100" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">0h</text>
-  <text x="250" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">1h</text>
-  <text x="400" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">3h</text>
-  <text x="550" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">6h</text>
-  <text x="700" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">24h</text>
-  <text x="400" y="395" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Time Since Added (hours)</text>
-
-  <!-- Y-axis labels -->
-  <text x="85" y="355" text-anchor="end" fill="#B0B0B0" font-size="11">0</text>
-  <text x="85" y="280" text-anchor="end" fill="#B0B0B0" font-size="11">3</text>
-  <text x="85" y="205" text-anchor="end" fill="#B0B0B0" font-size="11">6</text>
-  <text x="85" y="130" text-anchor="end" fill="#B0B0B0" font-size="11">9</text>
-  <text x="85" y="85" text-anchor="end" fill="#B0B0B0" font-size="11">10</text>
-  <text x="40" y="220" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold" transform="rotate(-90 40 220)">Effective Score</text>
-
-  <!-- Decay curves for different importance levels -->
-  <!-- Importance 10.0 -->
-  <path d="M 100 80 Q 250 105 400 155 T 700 320" stroke="#4CAF50" stroke-width="3" fill="none"/>
-  <text x="710" y="320" fill="#4CAF50" font-size="11" font-weight="bold">Imp: 10.0</text>
-
-  <!-- Importance 5.0 -->
-  <path d="M 100 205 Q 250 230 400 255 T 700 335" stroke="#2196F3" stroke-width="3" fill="none"/>
-  <text x="710" y="335" fill="#2196F3" font-size="11" font-weight="bold">Imp: 5.0</text>
-
-  <!-- Importance 1.0 -->
-  <path d="M 100 330 Q 250 340 400 345 T 700 348" stroke="#FF9800" stroke-width="3" fill="none"/>
-  <text x="710" y="348" fill="#FF9800" font-size="11" font-weight="bold">Imp: 1.0</text>
-
-  <!-- Key insight -->
-  <rect x="150" y="50" width="500" height="25" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
-  <text x="400" y="68" text-anchor="middle" fill="#4CAF50" font-size="12">High-importance memories retain value longer, but recency still matters</text>
-</svg>
+![Balanced Strategy: Importance Decay Over Time](../assets/images/balanced-strategy-decay.svg)
 
 !!! info "Related ADR"
-    See [ADR-006: Context Assembly Strategies](adrs/006-context-assembly.md) for detailed strategy analysis.
+    See [ADR-006: Context Assembly Strategies](../architecture/adrs/006-context-assembly.md) for detailed strategy analysis.
 
 ### Performance Characteristics
 
@@ -474,7 +338,7 @@ CREATE INDEX idx_nodes_value_gin ON nodes
 - Retention policies for data lifecycle
 
 !!! info "Related ADR"
-    See [ADR-001: Use PostgreSQL with TimescaleDB for Storage](adrs/001-postgresql-timescaledb.md) for complete rationale.
+    See [ADR-001: Use PostgreSQL with TimescaleDB for Storage](../architecture/adrs/001-postgresql-timescaledb.md) for complete rationale.
 
 ### Long-Term Memory Operations
 
@@ -560,7 +424,7 @@ end
 ```
 
 !!! info "Related ADR"
-    See [ADR-005: RAG-Based Retrieval with Hybrid Search](adrs/005-rag-retrieval.md) for search strategy details.
+    See [ADR-005: RAG-Based Retrieval with Hybrid Search](../architecture/adrs/005-rag-retrieval.md) for search strategy details.
 
 ### RAG-Based Retrieval
 
@@ -831,9 +695,9 @@ LIMIT 20;
 
 ## Related Documentation
 
-- [Architecture Index](index.md) - System overview and component summary
-- [Architecture Overview](overview.md) - Detailed architecture and data flows
+- [Architecture Index](../architecture/index.md) - System overview and component summary
+- [Architecture Overview](../architecture/overview.md) - Detailed architecture and data flows
 - [Hive Mind Architecture](hive-mind.md) - Multi-robot shared memory
-- [ADR-002: Two-Tier Memory Architecture](adrs/002-two-tier-memory.md)
-- [ADR-006: Context Assembly Strategies](adrs/006-context-assembly.md)
-- [ADR-007: Working Memory Eviction Strategy](adrs/007-eviction-strategy.md)
+- [ADR-002: Two-Tier Memory Architecture](../architecture/adrs/002-two-tier-memory.md)
+- [ADR-006: Context Assembly Strategies](../architecture/adrs/006-context-assembly.md)
+- [ADR-007: Working Memory Eviction Strategy](../architecture/adrs/007-eviction-strategy.md)

data/docs/robots/why-robots.md

@@ -0,0 +1,85 @@
+# Why "Robots" Instead of "Agents"?
+
+> "What's in a name? That which we call a rose
+> By any other name would smell as sweet."
+> — Shakespeare, *Romeo and Juliet*
+
+Shakespeare argues names are arbitrary. In software, we respectfully disagree—names shape expectations and understanding. The words we choose frame how we think about systems, what we expect from them, and how we architect their capabilities.
+
+HTM uses **robots** rather than the fashionable "agents" deliberately and thoughtfully.
+
+## The Problem with "Agent"
+
+The term "agent" carries philosophical baggage it cannot support:
+
+- **Semantic overload**: User agents, software agents, real estate agents, secret agents, FBI agents, travel agents. The word means everything and therefore nothing. When you say "AI agent," what mental model does your listener construct?
+
+- **False autonomy**: "Agent" implies genuine decision-making, independent action, perhaps even free will. These systems follow instructions. They predict the next token. They don't have *agency* in any meaningful philosophical sense. Calling them agents sets expectations the technology cannot meet.
+
+- **The hype cycle problem**: "AI Agent" and "Agentic AI" became buzzwords in 2023-2024, often meaning nothing more than "LLM with a prompt and a while loop." We prefer terminology that will age gracefully rather than become an embarrassing artifact of a particular moment's enthusiasm.
+
+- **Implementation reality**: Look under the hood of popular "agent" frameworks. You'll often find a system prompt, a for-loop, and some JSON parsing. Calling that an "agent" is marketing, not engineering.
+
+## The Case for "Robot"
+
+"Robot" has heritage, honesty, and heart:
+
+- **Rich literary tradition**: The word comes from Karel Čapek's 1920 play *R.U.R.* (Rossum's Universal Robots), derived from Czech *robota*, meaning forced labor or drudgery. Isaac Asimov gave us the Three Laws of Robotics and decades of thoughtful exploration of robot ethics, identity, and purpose. There's a century of serious thinking about what robots are and how they should behave. "Agent" has no comparable intellectual foundation.
+
+- **Honest about the relationship**: Robots work for us. They're tireless, reliable, and purpose-built. They don't pretend to have goals independent of their creators. This honesty about the master-worker relationship is healthier than the ambiguity of "agent."
+
+- **Cultural resonance**: Robots are endearing. R2-D2. Wall-E. Bender. Data. The Iron Giant. Baymax. We've spent a century telling stories about robots, developing affection for them, and exploring their place alongside humanity. "Agent" has no such cultural weight—it's the language of bureaucracy and espionage.
+
+- **Technical precision**: In HTM, each robot has an identity (`robot_id`), a name, and a history of contributions. Robots are registered in a table. They're tracked. They're *things* with identity and persistence. "Agent" suggests ephemerality; "robot" suggests durability.
+
+## Robots in the Hive Mind
+
+HTM's architecture reinforces the robot metaphor in a specific way: **all robots share a common long-term memory**.
+
+This is the *hive mind* pattern. Individual robots have their own working memory—their own immediate context and focus—but they draw from and contribute to a shared pool of knowledge. Like worker bees serving a hive, each robot is both individual and part of something larger.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Shared Long-Term Memory            │
+│              (The Hive Mind / Collective)           │
+│                                                     │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
+│  │ Memory  │  │ Memory  │  │ Memory  │  ...         │
+│  └─────────┘  └─────────┘  └─────────┘              │
+└─────────────────────────────────────────────────────┘
+        ▲              ▲              ▲
+        │              │              │
+   ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+   │ Robot A │    │ Robot B │    │ Robot C │
+   │         │    │         │    │         │
+   │ Working │    │ Working │    │ Working │
+   │ Memory  │    │ Memory  │    │ Memory  │
+   └─────────┘    └─────────┘    └─────────┘
+```
+
+This architecture maps naturally to the robot metaphor:
+
+- **Robots are workers**: They execute tasks, store memories, recall information
+- **Robots are individuals**: Each has its own name, identity, and working context
+- **Robots are collective**: They share knowledge, learn from each other's experiences
+- **Robots are persistent**: They're registered, tracked, and their contributions are attributed
+
+"Agent" suggests independence and autonomy. "Robot" suggests collaboration and purpose. HTM's robots work together, building collective intelligence. That's what the terminology should convey.
+
+## Robots Never Forget
+
+HTM follows a **never-forget philosophy** (see [ADR-009](../architecture/adrs/009-never-forget.md)). Memories are never truly deleted—only soft-deleted, always recoverable. This aligns with the robot metaphor:
+
+A good robot doesn't lose your data. A good robot remembers what you told it, years later if necessary. A good robot is *reliable* in a way that ephemeral "agents" are not.
+
+When you tell an HTM robot something important, it stores that information in the collective memory. Other robots can access it. Future robots can learn from it. The knowledge persists, attributed to the robot that first contributed it.
+
+This is robot memory done right: durable, shared, and faithful.
+
+## Honest Terminology, Clear Thinking
+
+Language shapes thought. When we call these systems "agents," we prime ourselves to expect agency—goals, autonomy, perhaps even consciousness. When we call them "robots," we remind ourselves what they actually are: sophisticated tools, tireless workers, faithful servants of the instructions we give them.
+
+HTM helps robots do their job better: remember perfectly, recall intelligently, share knowledge generously, and serve reliably. That's not agency. That's good engineering.
+
+These are robots. Let's call them what they are.

data/lib/htm/config/defaults.yml

@@ -112,7 +112,7 @@ defaults:
     provider: ollama
     model: gemma3:latest
     timeout: 180
-    enabled: false
+    enabled: true
 
     system_prompt: |
       You are an atomic fact extraction system. Your goal is maximum decomposition.
@@ -167,14 +167,14 @@ defaults:
   # Access: HTM.config.job.backend
   # ---------------------------------------------------------------------------
   job:
-    backend: ~
+    backend: fiber
 
   # ---------------------------------------------------------------------------
   # General Settings
   # Access: HTM.config.week_start, HTM.config.connection_timeout, etc.
   # ---------------------------------------------------------------------------
   week_start: sunday
-  connection_timeout: 30
+  connection_timeout: 60
   telemetry_enabled: false
   log_level: info
 
@@ -197,7 +197,7 @@ defaults:
     azure:
       api_key: ~
       endpoint: ~
-      api_version: '2024-02-01'
+      api_version: "2024-02-01"
 
     ollama:
       url: http://localhost:11434

data/lib/htm/config.rb

@@ -221,7 +221,7 @@ class HTM
       huggingface openrouter bedrock deepseek
     ].freeze
 
-    SUPPORTED_JOB_BACKENDS = %i[active_job sidekiq inline thread].freeze
+    SUPPORTED_JOB_BACKENDS = %i[active_job sidekiq inline thread fiber].freeze
     SUPPORTED_WEEK_STARTS = %i[sunday monday].freeze
 
     # Default embedding dimensions by provider
@@ -714,7 +714,7 @@ class HTM
       return :active_job if defined?(ActiveJob)
       return :sidekiq if defined?(Sidekiq)
 
-      :thread
+      :fiber
     end
 
     def build_default_logger

data/lib/htm/job_adapter.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'async'
+require 'async/barrier'
+
 class HTM
   # Job adapter for pluggable background job backends
   #
@@ -11,6 +14,7 @@ class HTM
   # - :sidekiq - Direct Sidekiq integration (recommended for Sinatra apps)
   # - :inline - Synchronous execution (recommended for CLI and tests)
   # - :thread - Background thread (legacy, for standalone apps)
+  # - :fiber - Fiber-based concurrency using async gem (recommended for I/O-bound jobs)
   #
   # @example Configure job backend
   #   HTM.configure do |config|
@@ -44,8 +48,10 @@ class HTM
           enqueue_inline(job_class, **params)
         when :thread
           enqueue_thread(job_class, **params)
+        when :fiber
+          enqueue_fiber(job_class, **params)
         else
-          raise HTM::Error, "Unknown job backend: #{backend}. Supported backends: :active_job, :sidekiq, :inline, :thread"
+          raise HTM::Error, "Unknown job backend: #{backend}. Supported backends: :active_job, :sidekiq, :inline, :thread, :fiber"
         end
       end
 
@@ -98,6 +104,74 @@ class HTM
         HTM.logger.error "Failed to start thread for #{job_class.name}: #{e.message}"
       end
 
+      # Execute job using async gem (fiber-based concurrency)
+      # Non-blocking for I/O-bound operations like LLM API calls
+      def enqueue_fiber(job_class, **params)
+        Async do
+          begin
+            job_class.perform(**params)
+          rescue StandardError => e
+            HTM.logger.error "Fiber job #{job_class.name} failed: #{e.class.name} - #{e.message}"
+          end
+        end
+      rescue StandardError => e
+        HTM.logger.error "Failed to start fiber for #{job_class.name}: #{e.message}"
+      end
+
+      public
+
+      # Execute multiple jobs in parallel using fibers
+      # Best for I/O-bound jobs like LLM API calls
+      #
+      # @param jobs [Array<Array>] Array of [job_class, params] pairs
+      # @return [void]
+      #
+      # @example Run embedding and tags jobs in parallel
+      #   JobAdapter.enqueue_parallel([
+      #     [GenerateEmbeddingJob, { node_id: 123 }],
+      #     [GenerateTagsJob, { node_id: 123 }]
+      #   ])
+      #
+      def enqueue_parallel(jobs)
+        return if jobs.empty?
+
+        backend = HTM.configuration.job_backend
+
+        case backend
+        when :fiber
+          enqueue_parallel_fiber(jobs)
+        when :inline
+          # Run sequentially for inline backend
+          jobs.each { |job_class, params| enqueue_inline(job_class, **params) }
+        else
+          # For other backends, enqueue each job separately
+          jobs.each { |job_class, params| enqueue(job_class, **params) }
+        end
+      end
+
+      private
+
+      # Execute multiple jobs in parallel using async fibers
+      def enqueue_parallel_fiber(jobs)
+        Async do |task|
+          barrier = Async::Barrier.new
+
+          jobs.each do |job_class, params|
+            barrier.async do
+              begin
+                job_class.perform(**params)
+              rescue StandardError => e
+                HTM.logger.error "Parallel fiber job #{job_class.name} failed: #{e.class.name} - #{e.message}"
+              end
+            end
+          end
+
+          barrier.wait
+        end
+      rescue StandardError => e
+        HTM.logger.error "Failed to start parallel fibers: #{e.message}"
+      end
+
       # Convert HTM job class to ActiveJob class
       def to_active_job_class(job_class)
         # If it's already an ActiveJob, return it

data/lib/htm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class HTM
-  VERSION = '0.0.18'
+  VERSION = '0.0.20'
 end