htm 0.0.1 → 0.0.2

data/docs/guides/search-strategies.md

@@ -1,6 +1,6 @@
 # Search Strategies Deep Dive
 
-HTM provides three search strategies for retrieving memories: vector search, full-text search, and hybrid search. This guide explores each strategy in depth, when to use them, and how to optimize performance.
+HTM provides three search strategies for retrieving memories: vector search, full-text search, and tag-enhanced hybrid search. This guide explores each strategy in depth, when to use them, and how to optimize performance.
 
 ## Overview
 
@@ -8,7 +8,7 @@ HTM provides three search strategies for retrieving memories: vector search, ful
 |----------|--------|----------|----------|
 | **Vector** | Semantic similarity via embeddings | Understanding meaning | Conceptual queries, related topics |
 | **Full-text** | PostgreSQL text search | Exact keyword matching | Specific terms, proper nouns |
-| **Hybrid** | Combines both approaches | Best overall accuracy | General purpose queries |
+| **Hybrid** | Vector + fulltext + tag matching | Best overall accuracy | General purpose queries |
 
 <svg viewBox="0 0 900 650" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
   <!-- Title -->
@@ -123,14 +123,15 @@ User Query: "database optimization techniques"
 
 ```ruby
 memories = htm.recall(
+  "improving application performance",
   timeframe: "last month",
-  topic: "improving application performance",
   strategy: :vector,
-  limit: 10
+  limit: 10,
+  raw: true  # Get full node data with scores
 )
 
 memories.each do |m|
-  puts "#{m['value']}"
+  puts "#{m['content']}"
   puts "Similarity: #{m['similarity']}"  # 0.0 to 1.0
   puts
 end
@@ -496,45 +497,69 @@ result = conn.exec_params(
 conn.close
 ```
 
-## Hybrid Search (Combined)
+## Hybrid Search (Tag-Enhanced)
 
-Hybrid search combines full-text and vector search for optimal results.
+Hybrid search combines full-text, vector, and tag matching for optimal results. This is the recommended strategy for most use cases.
 
 ### How It Works
 
 ```
 User Query: "PostgreSQL performance tuning"
       ↓
-  Step 1: Full-text Search (Prefilter)
-  - Find all memories with keywords
-  - Limit to 100 candidates
+  Step 1: Find Matching Tags
+  - Search tags for query terms (3+ chars)
+  - E.g., finds "database:postgresql", "performance:optimization"
       ↓
-  Step 2: Vector Ranking
-  - Generate query embedding
-  - Rank candidates by similarity
+  Step 2: Build Candidate Pool
+  - Full-text matches (keyword)
+  - Nodes with matching tags (categorical)
+      ↓
+  Step 3: Score and Rank
+  - Vector similarity (semantic)
+  - Tag boost (categorical match)
+  - Combined score: (similarity × 0.7) + (tag_boost × 0.3)
       ↓
   Final Results
-  - Keyword precision + Semantic understanding
+  - Keyword precision + Semantic understanding + Tag relevance
 ```
 
 ### Basic Usage
 
 ```ruby
 memories = htm.recall(
+  "PostgreSQL performance optimization",
   timeframe: "last month",
-  topic: "PostgreSQL performance optimization",
   strategy: :hybrid,
-  limit: 10
+  limit: 10,
+  raw: true  # Get full node data with scores
 )
 
-# Results have both keyword matches AND semantic relevance
+# Results have keyword matches, semantic relevance, AND tag boosting
 memories.each do |m|
-  puts "#{m['value']}"
-  puts "Similarity: #{m['similarity']}"
+  puts "#{m['content']}"
+  puts "Similarity: #{m['similarity']}"     # Vector similarity (0-1)
+  puts "Tag Boost: #{m['tag_boost']}"        # Tag match score (0-1)
+  puts "Combined: #{m['combined_score']}"   # Weighted combination
   puts
 end
 ```
 
+### Tag-Enhanced Scoring
+
+The hybrid search automatically:
+
+1. **Finds matching tags**: Searches tags for query term matches
+2. **Includes tagged nodes**: Adds nodes with matching tags to candidate pool
+3. **Calculates combined score**: `(similarity × 0.7) + (tag_boost × 0.3)`
+
+```ruby
+# Check which tags match a query
+matching_tags = htm.long_term_memory.find_query_matching_tags("PostgreSQL database")
+# => ["database:postgresql", "database:postgresql:extensions", "database:sql"]
+
+# These tags boost relevance of associated nodes in hybrid search
+```
+
 ### When Hybrid Search Excels
 
 **1. General Purpose Queries**
@@ -542,14 +567,16 @@ end
 ```ruby
 # Best for most use cases
 memories = htm.recall(
-  timeframe: "all time",
-  topic: "how to improve database query speed",
-  strategy: :hybrid
+  "how to improve database query speed",
+  timeframe: "last year",
+  strategy: :hybrid,
+  raw: true
 )
 
 # Combines:
 # - Keyword matches (database, query, speed)
 # - Semantic understanding (optimization, performance)
+# - Tag boost (nodes tagged with "database:*")
 ```
 
 **2. Mixed Terminology**
@@ -557,14 +584,16 @@ memories = htm.recall(
 ```ruby
 # Query with both specific and general terms
 memories = htm.recall(
-  timeframe: "all time",
-  topic: "JWT token authentication security best practices",
-  strategy: :hybrid
+  "JWT token authentication security best practices",
+  timeframe: "last year",
+  strategy: :hybrid,
+  raw: true
 )
 
 # Finds:
 # - Exact "JWT" mentions (full-text)
 # - Related security concepts (vector)
+# - Nodes tagged "auth:jwt", "security:*" (tag boost)
 ```
 
 **3. Production Applications**
@@ -572,12 +601,17 @@ memories = htm.recall(
 ```ruby
 # Recommended default for production
 class ProductionSearch
-  def search(query)
-    htm.recall(
-      timeframe: "last 90 days",
-      topic: query,
+  def initialize(htm)
+    @htm = htm
+  end
+
+  def search(query, timeframe: "last 90 days")
+    @htm.recall(
+      query,
+      timeframe: timeframe,
       strategy: :hybrid,  # Best all-around
-      limit: 20
+      limit: 20,
+      raw: true
     )
   end
 end
@@ -587,28 +621,18 @@ end
 
 **Prefilter Limit**
 
-The number of candidates from full-text search:
+The number of candidates considered from each source (fulltext and tags):
 
 ```ruby
-# Internal parameter (not exposed in public API)
-# Default: 100 candidates
-
 # In LongTermMemory#search_hybrid:
-# prefilter_limit: 100
-```
-
-For very large databases, you might want to adjust this:
-
-```ruby
-# Direct database query with custom prefilter
-ltm = HTM::LongTermMemory.new(HTM::Database.default_config)
-embedding_service = HTM::EmbeddingService.new
+# prefilter_limit: 100 (default)
 
-results = ltm.search_hybrid(
-  timeframe: Time.at(0)..Time.now,
+# Direct access with custom prefilter
+results = htm.long_term_memory.search_hybrid(
+  timeframe: (Time.now - 365*24*3600)..Time.now,
   query: "database optimization",
   limit: 10,
-  embedding_service: embedding_service,
+  embedding_service: HTM::EmbeddingService.new,
   prefilter_limit: 200  # More candidates
 )
 ```
@@ -620,15 +644,15 @@ results = ltm.search_hybrid(
 ```ruby
 # Good: Mix of specific keywords and concepts
 htm.recall(
-  topic: "PostgreSQL query optimization indexing performance",
+  "PostgreSQL query optimization indexing performance",
   strategy: :hybrid
 )
 
 # Suboptimal: Only keywords
-htm.recall(topic: "PostgreSQL SQL", strategy: :hybrid)
+htm.recall("PostgreSQL SQL", strategy: :hybrid)
 
 # Suboptimal: Only concepts
-htm.recall(topic: "making things faster", strategy: :hybrid)
+htm.recall("making things faster", strategy: :hybrid)
 ```
 
 **2. Use Appropriate Timeframes**
@@ -636,19 +660,29 @@ htm.recall(topic: "making things faster", strategy: :hybrid)
 ```ruby
 # Narrow timeframe: Faster, more recent results
 htm.recall(
+  "recent errors",
   timeframe: "last week",
-  topic: "recent errors",
   strategy: :hybrid
 )
 
 # Wide timeframe: Comprehensive, slower
 htm.recall(
+  "architecture decisions",
   timeframe: "last year",
-  topic: "architecture decisions",
   strategy: :hybrid
 )
 ```
 
+**3. Check Tag Coverage**
+
+```ruby
+# See which tags exist for better query formulation
+popular = htm.long_term_memory.popular_tags(limit: 20)
+popular.each do |tag|
+  puts "#{tag[:name]}: #{tag[:usage_count]} nodes"
+end
+```
+
 ## Strategy Comparison
 
 ### Performance Benchmarks

data/docs/images/htm-er-diagram.svg

@@ -0,0 +1,156 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 900" style="background: transparent;">
+  <defs>
+    <style>
+      .table-box { fill: #1e1e1e; stroke: #4a9eff; stroke-width: 2; }
+      .table-header { fill: #2d5a8e; }
+      .text-header { fill: #ffffff; font-family: monospace; font-size: 14px; font-weight: bold; }
+      .text-field { fill: #d4d4d4; font-family: monospace; font-size: 11px; }
+      .text-type { fill: #8cb4e8; font-family: monospace; font-size: 10px; }
+      .relation-line { stroke: #4a9eff; stroke-width: 1.5; fill: none; }
+      .arrow { fill: #4a9eff; }
+      .join-table { fill: #1e3a1e; stroke: #4a9eff; stroke-width: 2; }
+    </style>
+  </defs>
+
+  <!-- Robots Table -->
+  <rect class="table-box" x="50" y="50" width="280" height="140" rx="5"/>
+  <rect class="table-header" x="50" y="50" width="280" height="35" rx="5"/>
+  <text class="text-header" x="190" y="73" text-anchor="middle">robots</text>
+
+  <text class="text-field" x="60" y="100">id</text>
+  <text class="text-type" x="320" y="100" text-anchor="end">BIGSERIAL PK</text>
+
+  <text class="text-field" x="60" y="120">name</text>
+  <text class="text-type" x="320" y="120" text-anchor="end">TEXT</text>
+
+  <text class="text-field" x="60" y="140">created_at</text>
+  <text class="text-type" x="320" y="140" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="60" y="160">last_active</text>
+  <text class="text-type" x="320" y="160" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="60" y="180">metadata</text>
+  <text class="text-type" x="320" y="180" text-anchor="end">JSONB</text>
+
+  <!-- robot_nodes Join Table -->
+  <rect class="join-table" x="400" y="50" width="320" height="180" rx="5"/>
+  <rect class="table-header" x="400" y="50" width="320" height="35" rx="5"/>
+  <text class="text-header" x="560" y="73" text-anchor="middle">robot_nodes</text>
+
+  <text class="text-field" x="410" y="100">id</text>
+  <text class="text-type" x="710" y="100" text-anchor="end">BIGSERIAL PK</text>
+
+  <text class="text-field" x="410" y="120">robot_id</text>
+  <text class="text-type" x="710" y="120" text-anchor="end">BIGINT FK</text>
+
+  <text class="text-field" x="410" y="140">node_id</text>
+  <text class="text-type" x="710" y="140" text-anchor="end">BIGINT FK</text>
+
+  <text class="text-field" x="410" y="160">first_remembered_at</text>
+  <text class="text-type" x="710" y="160" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="410" y="180">last_remembered_at</text>
+  <text class="text-type" x="710" y="180" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="410" y="200">remember_count</text>
+  <text class="text-type" x="710" y="200" text-anchor="end">INTEGER</text>
+
+  <text class="text-field" x="410" y="220">created_at, updated_at</text>
+  <text class="text-type" x="710" y="220" text-anchor="end">TIMESTAMPTZ</text>
+
+  <!-- Nodes Table -->
+  <rect class="table-box" x="50" y="280" width="280" height="280" rx="5"/>
+  <rect class="table-header" x="50" y="280" width="280" height="35" rx="5"/>
+  <text class="text-header" x="190" y="303" text-anchor="middle">nodes</text>
+
+  <text class="text-field" x="60" y="330">id</text>
+  <text class="text-type" x="320" y="330" text-anchor="end">BIGSERIAL PK</text>
+
+  <text class="text-field" x="60" y="350">content</text>
+  <text class="text-type" x="320" y="350" text-anchor="end">TEXT NOT NULL</text>
+
+  <text class="text-field" x="60" y="370">content_hash</text>
+  <text class="text-type" x="320" y="370" text-anchor="end">VARCHAR(64) UNIQUE</text>
+
+  <text class="text-field" x="60" y="390">access_count</text>
+  <text class="text-type" x="320" y="390" text-anchor="end">INTEGER</text>
+
+  <text class="text-field" x="60" y="410">created_at</text>
+  <text class="text-type" x="320" y="410" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="60" y="430">updated_at</text>
+  <text class="text-type" x="320" y="430" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="60" y="450">last_accessed</text>
+  <text class="text-type" x="320" y="450" text-anchor="end">TIMESTAMPTZ</text>
+
+  <text class="text-field" x="60" y="470">token_count</text>
+  <text class="text-type" x="320" y="470" text-anchor="end">INTEGER</text>
+
+  <text class="text-field" x="60" y="490">in_working_memory</text>
+  <text class="text-type" x="320" y="490" text-anchor="end">BOOLEAN</text>
+
+  <text class="text-field" x="60" y="510">embedding</text>
+  <text class="text-type" x="320" y="510" text-anchor="end">vector(2000)</text>
+
+  <text class="text-field" x="60" y="530">embedding_dimension</text>
+  <text class="text-type" x="320" y="530" text-anchor="end">INTEGER</text>
+
+  <!-- Tags Table -->
+  <rect class="table-box" x="850" y="280" width="280" height="120" rx="5"/>
+  <rect class="table-header" x="850" y="280" width="280" height="35" rx="5"/>
+  <text class="text-header" x="990" y="303" text-anchor="middle">tags</text>
+
+  <text class="text-field" x="860" y="330">id</text>
+  <text class="text-type" x="1120" y="330" text-anchor="end">BIGSERIAL PK</text>
+
+  <text class="text-field" x="860" y="350">name</text>
+  <text class="text-type" x="1120" y="350" text-anchor="end">TEXT UNIQUE</text>
+
+  <text class="text-field" x="860" y="370">created_at</text>
+  <text class="text-type" x="1120" y="370" text-anchor="end">TIMESTAMPTZ</text>
+
+  <!-- node_tags Join Table -->
+  <rect class="join-table" x="450" y="420" width="280" height="140" rx="5"/>
+  <rect class="table-header" x="450" y="420" width="280" height="35" rx="5"/>
+  <text class="text-header" x="590" y="443" text-anchor="middle">node_tags</text>
+
+  <text class="text-field" x="460" y="470">id</text>
+  <text class="text-type" x="720" y="470" text-anchor="end">BIGSERIAL PK</text>
+
+  <text class="text-field" x="460" y="490">node_id</text>
+  <text class="text-type" x="720" y="490" text-anchor="end">BIGINT FK</text>
+
+  <text class="text-field" x="460" y="510">tag_id</text>
+  <text class="text-type" x="720" y="510" text-anchor="end">BIGINT FK</text>
+
+  <text class="text-field" x="460" y="530">created_at</text>
+  <text class="text-type" x="720" y="530" text-anchor="end">TIMESTAMPTZ</text>
+
+  <!-- Relationships: robots -> robot_nodes -->
+  <path class="relation-line" d="M 330 120 L 400 120"/>
+  <polygon class="arrow" points="400,120 390,115 390,125"/>
+
+  <!-- Relationships: robot_nodes -> nodes -->
+  <path class="relation-line" d="M 560 230 L 560 280 L 330 280 L 330 330"/>
+  <polygon class="arrow" points="330,280 325,290 335,290"/>
+
+  <!-- Relationships: nodes -> node_tags -->
+  <path class="relation-line" d="M 330 490 L 450 490"/>
+  <polygon class="arrow" points="450,490 440,485 440,495"/>
+
+  <!-- Relationships: tags -> node_tags -->
+  <path class="relation-line" d="M 850 350 L 730 350 L 730 510"/>
+  <polygon class="arrow" points="730,510 725,500 735,500"/>
+
+  <!-- Legend -->
+  <text class="text-field" x="50" y="620" font-weight="bold">Legend:</text>
+  <text class="text-field" x="50" y="640">PK = Primary Key</text>
+  <text class="text-field" x="200" y="640">FK = Foreign Key</text>
+  <text class="text-field" x="350" y="640">Green box = Join table (many-to-many)</text>
+
+  <!-- Annotations -->
+  <text class="text-field" x="350" y="110" font-style="italic">N:M</text>
+  <text class="text-field" x="380" y="480" font-style="italic">N:M</text>
+  <text class="text-field" x="770" y="430" font-style="italic">N:M</text>
+</svg>

data/docs/index.md

@@ -1,4 +1,15 @@
+
 <div align="center">
+  <div style="background: linear-gradient(135deg, #ff6b6b 0%, #ee5a6f 100%); border: 4px solid #ff0000; border-radius: 12px; padding: 20px; margin: 20px auto; max-width: 800px; box-shadow: 0 8px 16px rgba(255, 0, 0, 0.3);">
+    <p style="color: #ffffff; font-size: 24px; font-weight: bold; margin: 0; text-shadow: 2px 2px 4px rgba(0,0,0,0.5);">
+      ⚠️ WARNING ⚠️
+    </p>
+    <p style="color: #fff; font-size: 16px; margin: 10px 0 0 0; line-height: 1.6;">
+      This documentation is AI-generated and may contain <strong>hallucinations</strong>, <strong>inaccuracies</strong>, or <strong>outdated information</strong>.<br/>
+      Always verify critical details in the source code.
+    </p>
+  </div>
+
   <img src="assets/images/htm_demo.gif" alt="Tree of Knowledge" width="800">
 </div>
 
@@ -124,33 +135,7 @@ HTM is perfect for:
 
 HTM consists of several key components working together:
 
-```
-┌─────────────────────────────────────────────────┐
-│                    Your LLM                     │
-│              (Claude, GPT, etc.)                │
-└─────────────────┬───────────────────────────────┘
-                  │
-                  ▼
-┌─────────────────────────────────────────────────┐
-│                   HTM API                       │
-│  add_node(), recall(), create_context(), etc.  │
-└──────┬──────────────────────────────────┬──────┘
-       │                                    │
-       ▼                                    ▼
-┌─────────────────┐              ┌──────────────────┐
-│ Working Memory  │              │ Long-term Memory │
-│  (In-Memory)    │◄────────────►│  (PostgreSQL)    │
-│  128k tokens    │  Eviction    │  ∞ storage       │
-│  Fast access    │  & Recall    │                  │
-└─────────────────┘              └──────────────────┘
-                                           │
-                                           ▼
-                                  ┌──────────────────┐
-                                  │ Embedding Service│
-                                  │  (Ollama/RubyLLM)│
-                                  │   gpt-oss model  │
-                                  └──────────────────┘
-```
+![HTM Architecture Overview](assets/images/htm-architecture-overview.svg)
 
 ### Component Breakdown
 
@@ -177,8 +162,8 @@ Each type can have custom importance scores, tags, and relationships.
 
 Ready to add intelligent memory to your LLM application? Follow these steps:
 
-1. **[Installation](installation.md)**: Set up HTM, PostgreSQL, TimescaleDB, and Ollama
-2. **[Quick Start](quick-start.md)**: Build your first HTM-powered application in 5 minutes
+1. **[Installation](getting-started/installation.md)**: Set up HTM, PostgreSQL, TimescaleDB, and Ollama
+2. **[Quick Start](getting-started/quick-start.md)**: Build your first HTM-powered application in 5 minutes
 3. **[User Guide](guides/getting-started.md)**: Deep dive into all HTM features
 4. **[API Reference](api/htm.md)**: Complete API documentation
 
@@ -208,7 +193,7 @@ Licensed under the MIT License.
 
 **Next Steps:**
 
-- [Install HTM](installation.md) and set up your environment
-- Follow the [Quick Start Guide](quick-start.md) to build your first application
+- [Install HTM](getting-started/installation.md) and set up your environment
+- Follow the [Quick Start Guide](getting-started/quick-start.md) to build your first application
 - Explore the [User Guide](guides/getting-started.md) for advanced features
 - Check out the [API Reference](api/htm.md) for detailed documentation

data/docs/multi_framework_support.md

@@ -38,7 +38,7 @@ puts "Found #{memories.length} memories"
 ```ruby
 require 'sinatra'
 require 'htm'
-require 'htm/sinatra'
+require 'htm/integrations/sinatra'
 
 class MyApp < Sinatra::Base
   # Automatically configures HTM with Sidekiq
@@ -51,7 +51,7 @@ class MyApp < Sinatra::Base
   end
 
   post '/remember' do
-    node_id = remember(params[:content], source: 'user')
+    node_id = remember(params[:content])
     json status: 'ok', node_id: node_id
   end
 
@@ -209,7 +209,7 @@ gem 'redis'
 gem 'htm'
 
 # app.rb
-require 'htm/sinatra'
+require 'htm/integrations/sinatra'
 
 class MyApp < Sinatra::Base
   register_htm  # Auto-configures HTM
@@ -451,7 +451,7 @@ require 'htm'
 # Threads used (not production-ready)
 
 # After:
-require 'htm/sinatra'
+require 'htm/integrations/sinatra'
 register_htm  # Auto-configures Sidekiq
 # Production-ready background jobs
 ```

data/examples/basic_usage.rb

@@ -4,8 +4,8 @@
 # Basic usage example for HTM
 #
 # Prerequisites:
-# 1. Source environment variables: source ~/.bashrc__tiger
-# 2. Initialize database schema: ruby -r ./lib/htm -e "HTM::Database.setup"
+# 1. Set HTM_DBURL environment variable (see SETUP.md)
+# 2. Initialize database schema: rake db_setup
 # 3. Install dependencies: bundle install
 
 require_relative '../lib/htm'
@@ -15,19 +15,21 @@ puts "=" * 60
 
 # Check environment
 unless ENV['HTM_DBURL']
-  puts "ERROR: HTM_DBURL not set. Please run: source ~/.bashrc__tiger"
+  puts "ERROR: HTM_DBURL not set. Please set it:"
+  puts "  export HTM_DBURL=\"postgresql://postgres@localhost:5432/htm_development\""
+  puts "See SETUP.md for details."
   exit 1
 end
 
 begin
-  # Configure HTM globally (uses RubyLLM with Ollama by default)
+  # Configure HTM globally (uses Ollama by default)
   puts "\n1. Configuring HTM with Ollama provider..."
   HTM.configure do |config|
     config.embedding_provider = :ollama
-    config.embedding_model = 'nomic-embed-text'
+    config.embedding_model = 'nomic-embed-text:latest'  # Ollama models need :tag suffix
     config.embedding_dimensions = 768
     config.tag_provider = :ollama
-    config.tag_model = 'llama3'
+    config.tag_model = 'gemma3:latest'  # Ollama models need :tag suffix
     config.reset_to_defaults  # Apply settings
   end
   puts "✓ HTM configured with Ollama provider"
@@ -47,20 +49,17 @@ begin
   puts "\n3. Remembering information..."
 
   node_id_1 = htm.remember(
-    "We decided to use PostgreSQL for HTM storage because it provides excellent time-series optimization and native vector search with pgvector.",
-    source: "architect"
+    "We decided to use PostgreSQL for HTM storage because it provides excellent time-series optimization and native vector search with pgvector."
   )
   puts "✓ Remembered decision about database choice (node #{node_id_1})"
 
   node_id_2 = htm.remember(
-    "We chose RAG (Retrieval-Augmented Generation) for memory recall, combining temporal filtering with semantic vector search.",
-    source: "architect"
+    "We chose RAG (Retrieval-Augmented Generation) for memory recall, combining temporal filtering with semantic vector search."
   )
   puts "✓ Remembered decision about RAG approach (node #{node_id_2})"
 
   node_id_3 = htm.remember(
-    "The user's name is Dewayne and they prefer using debug_me for debugging instead of puts.",
-    source: "system"
+    "The user's name is Dewayne and they prefer using debug_me for debugging instead of puts."
   )
   puts "✓ Remembered fact about user preferences (node #{node_id_3})"
 
@@ -72,18 +71,21 @@ begin
   memories = htm.recall(
     "database",
     timeframe: (Time.now - 3600)..Time.now,  # Last hour
-    limit: 5
+    limit: 5,
+    raw: true  # Return full node data (id, content, etc.)
   )
   puts "✓ Found #{memories.length} memories"
   memories.each do |memory|
-    puts "  - Node #{memory['id']}: #{memory['content'][0..60]}..."
+    content = memory['content'] || memory[:content]
+    node_id = memory['id'] || memory[:id]
+    puts "  - Node #{node_id}: #{content[0..60]}..."
   end
 
   puts "\n" + "=" * 60
   puts "✓ Example completed successfully!"
   puts "\nThe HTM API provides 3 core methods:"
-  puts "  - htm.remember(content, source:) - Store information"
-  puts "  - htm.recall(timeframe:, topic:, ...) - Retrieve memories"
+  puts "  - htm.remember(content, tags: []) - Store information"
+  puts "  - htm.recall(topic, timeframe:, ...) - Retrieve memories"
   puts "  - htm.forget(node_id, confirm:) - Delete a memory"
 
 rescue => e