htm 0.0.31 → 0.0.32

data/docs/guides/context-assembly.md

@@ -52,10 +52,10 @@ Context assembly transforms working memory into LLM-ready context:
   <text x="350" y="120" class="text-label">:recent</text>
   <text x="550" y="120" text-anchor="end" class="text-small">Sort by access time</text>
 
-  <!-- Strategy 2: Important -->
+  <!-- Strategy 2: Frequent -->
   <rect x="340" y="145" width="220" height="35" fill="rgba(76, 175, 80, 0.3)" rx="3"/>
-  <text x="350" y="165" class="text-label">:important</text>
-  <text x="550" y="165" text-anchor="end" class="text-small">Sort by importance</text>
+  <text x="350" y="165" class="text-label">:frequent</text>
+  <text x="550" y="165" text-anchor="end" class="text-small">Sort by access count</text>
 
   <!-- Strategy 3: Balanced -->
   <rect x="340" y="190" width="220" height="35" fill="rgba(76, 175, 80, 0.3)" rx="3"/>
@@ -70,7 +70,7 @@ Context assembly transforms working memory into LLM-ready context:
   <text x="750" y="105" text-anchor="middle" class="text-small">(Ordered)</text>
 
   <text x="660" y="135" class="text-label">Node 3</text>
-  <text x="840" y="135" text-anchor="end" class="text-small">(important)</text>
+  <text x="840" y="135" text-anchor="end" class="text-small">(frequent)</text>
   <text x="660" y="155" class="text-label">Node 1</text>
   <text x="840" y="155" text-anchor="end" class="text-small">(recent)</text>
   <text x="660" y="175" class="text-label">Node 5</text>

data/docs/guides/file-loading.md

@@ -125,7 +125,7 @@ Content starts here...
 Access frontmatter via the FileSource model:
 
 ```ruby
-source = HTM::Models::FileSource.find_by(file_path: "docs/guide.md")
+source = HTM::Models::FileSource.first(file_path: "docs/guide.md")
 source.title            # => "PostgreSQL Guide"
 source.author           # => "HTM Team"
 source.frontmatter_tags # => ["database", "postgresql"]
@@ -146,13 +146,13 @@ HTM uses the [Baran gem](https://github.com/baran) with `MarkdownSplitter` for i
 ```ruby
 # Global configuration
 HTM.configure do |config|
-  config.chunk_size = 1024    # Characters per chunk (default: 1024)
-  config.chunk_overlap = 64   # Overlap between chunks (default: 64)
+  config.chunking.chunk_size = 1024    # Characters per chunk (default: 1024)
+  config.chunking.chunk_overlap = 64   # Overlap between chunks (default: 64)
 end
 
 # Or via environment variables
-# HTM_CHUNK_SIZE=512
-# HTM_CHUNK_OVERLAP=50
+# HTM_CHUNKING__CHUNK_SIZE=512
+# HTM_CHUNKING__CHUNK_OVERLAP=50
 ```
 
 ### Per-Loader Configuration
@@ -198,7 +198,7 @@ htm.load_file("docs/guide.md", force: true)
 The `HTM::Models::FileSource` tracks loaded files:
 
 ```ruby
-source = HTM::Models::FileSource.find_by(file_path: "docs/guide.md")
+source = HTM::Models::FileSource.first(file_path: "docs/guide.md")
 
 source.file_path       # Full path to file
 source.mtime           # Last modification time
@@ -269,17 +269,17 @@ priority: high
 
 ```ruby
 # Smaller chunks for dense technical content
-HTM.configure { |c| c.chunk_size = 512 }
+HTM.configure { |c| c.chunking.chunk_size = 512 }
 
 # Larger chunks for narrative content
-HTM.configure { |c| c.chunk_size = 2048 }
+HTM.configure { |c| c.chunking.chunk_size = 2048 }
 ```
 
 ### Regular Sync for Updated Content
 
 ```ruby
-# Sync all loaded files periodically
-htm.sync_files  # Re-checks all FileSource records
+# Sync all loaded files periodically (via rake task)
+# rake htm:files:sync  # Re-checks all FileSource records
 ```
 
 ## Example: Building a Knowledge Base
@@ -292,8 +292,8 @@ htm = HTM.new(robot_name: "Knowledge Base")
 
 # Configure chunking for technical docs
 HTM.configure do |config|
-  config.chunk_size = 768
-  config.chunk_overlap = 100
+  config.chunking.chunk_size = 768
+  config.chunking.chunk_overlap = 100
 end
 
 # Load documentation

data/docs/guides/getting-started.md

@@ -7,7 +7,7 @@ Welcome to HTM! This guide will help you build your first intelligent memory sys
 Before starting, ensure you have:
 
 1. **Ruby 3.0+** installed
-2. **PostgreSQL with TimescaleDB** (or access to a TimescaleDB cloud instance)
+2. **PostgreSQL 16+** with pgvector and pg_trgm extensions
 3. **LLM Provider** configured - Ollama (default for local development), OpenAI, Anthropic, Gemini, or others via RubyLLM
 4. Basic understanding of Ruby and LLMs
 
@@ -72,7 +72,7 @@ gem install htm
 
 ## Database Setup
 
-HTM requires a TimescaleDB database. Set your database connection:
+HTM requires a PostgreSQL database with pgvector and pg_trgm. Set your database connection:
 
 ```bash
 # Add to your .bashrc or .zshrc

data/docs/guides/long-term-memory.md

@@ -9,7 +9,7 @@ Long-term memory provides:
 - **Permanent storage** for all memories
 - **Vector embeddings** via pgvector
 - **Full-text search** via PostgreSQL's ts_vector
-- **Time-series optimization** via TimescaleDB hypertables
+- **Temporal filtering** via created_at index and Chronic gem for natural language timeframes
 - **Relationship graphs** for knowledge connections
 - **Audit logging** for all operations
 
@@ -383,33 +383,13 @@ conn.close
 puts "Reindexing completed"
 ```
 
-### Compression (TimescaleDB)
+### Cleanup Old Soft-Deleted Nodes
 
-TimescaleDB can compress old data:
+Periodically purge soft-deleted nodes to reclaim storage:
 
 ```ruby
-# Enable compression on operations_log hypertable
-conn = PG.connect(HTM::Database.default_config)
-
-conn.exec(
-  <<~SQL
-    ALTER TABLE operations_log SET (
-      timescaledb.compress,
-      timescaledb.compress_segmentby = 'robot_id'
-    )
-  SQL
-)
-
-# Add compression policy (compress data older than 7 days)
-conn.exec(
-  <<~SQL
-    SELECT add_compression_policy('operations_log', INTERVAL '7 days')
-  SQL
-)
-
-conn.close
-
-puts "Compression policy enabled"
+# Purge nodes soft-deleted more than 90 days ago
+htm.purge_deleted(older_than: Time.now - (90 * 24 * 60 * 60), confirm: :confirmed)
 ```
 
 ### Cleanup Old Logs
@@ -882,9 +862,9 @@ puts "Total nodes: #{HTM::Models::Node.count}"
 puts "Total tags: #{HTM::Models::Tag.count}"
 puts "Active robots: #{HTM::Models::Robot.count}"
 
-# Query by tag using ActiveRecord
+# Query by tag
 puts "\n=== Query by Tag ==="
-test_tag = HTM::Models::Tag.find_by(name: "test")
+test_tag = HTM::Models::Tag.first(name: "test")
 if test_tag
   tagged_nodes = test_tag.nodes
   puts "Found #{tagged_nodes.count} nodes with tag 'test'"

data/docs/guides/propositions.md

@@ -40,13 +40,13 @@ A proposition is an atomic factual statement that:
 ```ruby
 # Via configuration block
 HTM.configure do |config|
-  config.extract_propositions = true
-  config.proposition_provider = :ollama  # or :openai, :anthropic, etc.
-  config.proposition_model = 'gemma3:latest'
+  config.proposition.enabled = true
+  config.proposition.provider = :ollama  # or :openai, :anthropic, etc.
+  config.proposition.model = 'gemma3:latest'
 end
 
 # Or via environment variable
-# HTM_EXTRACT_PROPOSITIONS=true
+# HTM_PROPOSITION__ENABLED=true
 ```
 
 ### Provider Options
@@ -62,11 +62,11 @@ Proposition extraction uses LLM chat completion. Configure your preferred provid
 
 ```ruby
 HTM.configure do |config|
-  config.extract_propositions = true
+  config.proposition.enabled = true
 
   # Use OpenAI for higher quality extraction
-  config.proposition_provider = :openai
-  config.proposition_model = 'gpt-4o-mini'
+  config.proposition.provider = :openai
+  config.proposition.model = 'gpt-4o-mini'
 end
 ```
 
@@ -150,13 +150,14 @@ propositions.each { |p| htm.remember(p) }
 
 ```ruby
 # Find all proposition nodes
-propositions = HTM::Models::Node.where("metadata->>'is_proposition' = ?", 'true')
+propositions = HTM::Models::Node.where(
+  Sequel.lit("metadata->>'is_proposition' = ?", 'true')
+)
 
 # Find propositions from a specific source
 source_node_id = 123
 related = HTM::Models::Node.where(
-  "metadata->>'source_node_id' = ?",
-  source_node_id.to_s
+  Sequel.lit("metadata->>'source_node_id' = ?", source_node_id.to_s)
 )
 
 # Include propositions in recall (default behavior)
@@ -193,8 +194,8 @@ With async job backend, extraction happens in background:
 
 ```ruby
 HTM.configure do |config|
-  config.extract_propositions = true
-  config.job.backend = :thread  # or :sidekiq
+  config.proposition.enabled = true
+  config.job.backend = :fiber  # or :sidekiq
 end
 
 # Returns immediately, propositions created async
@@ -229,12 +230,12 @@ Use a capable model for better extraction:
 
 ```ruby
 # Higher quality (slower, costs more)
-config.proposition_provider = :openai
-config.proposition_model = 'gpt-4o'
+config.proposition.provider = :openai
+config.proposition.model = 'gpt-4o'
 
 # Balanced (faster, local)
-config.proposition_provider = :ollama
-config.proposition_model = 'gemma3:latest'
+config.proposition.provider = :ollama
+config.proposition.model = 'gemma3:latest'
 ```
 
 ### Selective Extraction
@@ -243,10 +244,10 @@ Enable/disable per operation if needed:
 
 ```ruby
 # Temporarily disable for specific content
-original_setting = HTM.configuration.extract_propositions
-HTM.configuration.extract_propositions = false
+original_setting = HTM.config.proposition.enabled
+HTM.config.proposition.enabled = false
 htm.remember("Simple fact that doesn't need decomposition.")
-HTM.configuration.extract_propositions = original_setting
+HTM.config.proposition.enabled = original_setting
 ```
 
 ## Rake Tasks

data/docs/guides/recalling-memories.md

@@ -625,11 +625,11 @@ For known node IDs, access the node directly via the model:
 
 ```ruby
 # Look up by node ID
-node = HTM::Models::Node.find_by(id: node_id)
+node = HTM::Models::Node.first(id: node_id)
 
 if node
   puts node.content
-  puts "Tags: #{node.tags.pluck(:name).join(', ')}"
+  puts "Tags: #{node.tag_names.join(', ')}"
   puts "Created: #{node.created_at}"
 else
   puts "Memory not found"
@@ -792,10 +792,10 @@ Times vary based on database size and query complexity.
 
 ```ruby
 # Slow: Wide timeframe + high limit
-htm.recall(timeframe: "last 5 years", topic: "...", limit: 1000)
+htm.recall("...", timeframe: "last 5 years", limit: 1000)
 
 # Fast: Narrow timeframe + reasonable limit
-htm.recall(timeframe: "last week", topic: "...", limit: 20)
+htm.recall("...", timeframe: "last week", limit: 20)
 ```
 
 ### Caching Results
@@ -860,7 +860,7 @@ good_results = results.select do |m|
 end
 
 # Or boost limit and take top results
-htm.recall(timeframe: "...", topic: "...", limit: 100)
+htm.recall("...", timeframe: "...", limit: 100, raw: true)
   .sort_by { |m| -m['similarity'].to_f }
   .first(10)
 ```

data/docs/guides/tags.md

@@ -121,11 +121,19 @@ htm.long_term_memory.add_tag(node_id: node.id, tag: "new:tag")
 tags = htm.long_term_memory.node_topics(node.id)
 # => ["database:postgresql", "search:vector"]
 
-# Find nodes by tag
-nodes = HTM::Models::Node.joins(:tags).where(tags: { name: "database:postgresql" })
+# Find nodes by tag (via Sequel)
+nodes = HTM::Models::Node
+  .join(:nodes_tags, node_id: :id)
+  .join(:tags, id: :tag_id)
+  .where(Sequel[:tags][:name] => "database:postgresql")
+  .all
 
 # Find by tag prefix
-nodes = HTM::Models::Node.joins(:tags).where("tags.name LIKE ?", "database:%")
+nodes = HTM::Models::Node
+  .join(:nodes_tags, node_id: :id)
+  .join(:tags, id: :tag_id)
+  .where(Sequel.like(Sequel[:tags][:name], "database:%"))
+  .all
 ```
 
 ### Tag Relationships
@@ -218,15 +226,15 @@ rake htm:tags:rebuild
 
 ```ruby
 # Filter by specific tag
-results = htm.recall("query", tags: ["database:postgresql"])
+results = htm.recall("query", query_tags: ["database:postgresql"])
 
 # Filter by multiple tags (AND)
-results = htm.recall("query", tags: ["database:postgresql", "search:vector"])
+results = htm.recall("query", query_tags: ["database:postgresql", "search:vector"])
 
 # Combine with other filters
 results = htm.recall(
   "performance optimization",
-  tags: ["database:postgresql"],
+  query_tags: ["database:postgresql"],
   timeframe: "last week",
   strategy: :hybrid,
   limit: 10
@@ -236,14 +244,11 @@ results = htm.recall(
 ### Direct Queries
 
 ```ruby
-# Find all nodes with a tag
-HTM::Models::Node.with_tag("database:postgresql")
+# Find all nodes with a specific tag (via LongTermMemory)
+results = htm.long_term_memory.search_by_tags(tags: ["database:postgresql"])
 
-# Find nodes with any of several tags
-HTM::Models::Node.with_any_tags(["database:postgresql", "database:mysql"])
-
-# Find nodes with all specified tags
-HTM::Models::Node.with_all_tags(["database:postgresql", "search:vector"])
+# Find nodes with multiple tags
+results = htm.long_term_memory.search_by_tags(tags: ["database:postgresql", "search:vector"])
 ```
 
 ## Database Schema

data/docs/multi_framework_support.md

@@ -75,7 +75,7 @@ end
 class MemoriesController < ApplicationController
   def create
     htm = HTM.new(robot_name: "user_#{current_user.id}")
-    node_id = htm.remember(params[:content], source: 'user')
+    node_id = htm.remember(params[:content], metadata: { source: 'user' })
 
     render json: { status: 'ok', node_id: node_id }
   end

data/docs/robots/hive-mind.md

@@ -188,7 +188,7 @@ def remember(content, tags: [])
   content_hash = Digest::SHA256.hexdigest(content)
 
   # 2. Check if node with same hash exists
-  existing_node = HTM::Models::Node.find_by(content_hash: content_hash)
+  existing_node = HTM::Models::Node.first(content_hash: content_hash)
 
   if existing_node
     # 3a. Link robot to existing node (or update remember_count)

data/docs/robots/multi-robot.md

@@ -187,7 +187,7 @@ timeline = memory_timeline("architecture decisions", limit: 50)
 puts "Architecture discussion timeline:"
 timeline.each do |node|
   robot_ids = node.robot_nodes.map(&:robot_id)
-  robots = HTM::Models::Robot.where(id: robot_ids).pluck(:name)
+  robots = HTM::Models::Robot.where(id: robot_ids).select_map(:name)
 
   puts "#{node.created_at} - #{robots.join(', ')}"
   puts "  #{node.content[0..100]}..."
@@ -738,7 +738,7 @@ class DevTeam
 
     nodes.each do |node|
       robot_ids = node.robot_nodes.map(&:robot_id)
-      robots = HTM::Models::Robot.where(id: robot_ids).pluck(:name)
+      robots = HTM::Models::Robot.where(id: robot_ids).select_map(:name)
       puts "- #{robots.join(', ')}: #{node.content[0..50]}..."
     end
 

data/docs/robots/robot-groups.md

@@ -404,7 +404,7 @@ channel.on_change do |event, node_id, origin_robot_id|
 
   case event
   when :added
-    node = HTM::Models::Node.find_by(id: node_id)
+    node = HTM::Models::Node.first(id: node_id)
     if node
       htm.working_memory.add_from_sync(
         id: node.id,