htm 0.0.14 → 0.0.15

data/docs/guides/context-assembly.md

@@ -110,11 +110,11 @@ Context assembly transforms working memory into LLM-ready context:
 
 ## Basic Usage
 
-The `create_context` method assembles context from working memory:
+The `assemble_context` method on working memory creates a context string:
 
 ```ruby
 # Basic context assembly
-context = htm.create_context(
+context = htm.working_memory.assemble_context(
   strategy: :balanced,    # Assembly strategy
   max_tokens: nil        # Optional token limit
 )
@@ -142,7 +142,7 @@ HTM provides three strategies for assembling context, each optimized for differe
 The `:recent` strategy prioritizes newest memories first.
 
 ```ruby
-context = htm.create_context(strategy: :recent)
+context = htm.working_memory.assemble_context(strategy: :recent)
 ```
 
 **How it works:**
@@ -172,15 +172,13 @@ class ChatBot
     @turn += 1
 
     # Add user message
-    @htm.add_node(
-      "turn_#{@turn}_user",
+    @htm.remember(
       "User: #{user_message}",
-      type: :context,
-      importance: 6.0
+      metadata: { turn: @turn, role: "user" }
     )
 
     # Get recent context
-    context = @htm.create_context(
+    context = @htm.working_memory.assemble_context(
       strategy: :recent,
       max_tokens: 10_000
     )
@@ -189,11 +187,9 @@ class ChatBot
     response = llm_generate(context, user_message)
 
     # Store assistant response
-    @htm.add_node(
-      "turn_#{@turn}_assistant",
+    @htm.remember(
       "Assistant: #{response}",
-      type: :context,
-      importance: 6.0
+      metadata: { turn: @turn, role: "assistant" }
     )
 
     response
@@ -208,17 +204,17 @@ class ChatBot
 end
 ```
 
-### Important Strategy
+### Frequent Strategy
 
-The `:important` strategy prioritizes high-importance memories.
+The `:frequent` strategy prioritizes frequently accessed memories.
 
 ```ruby
-context = htm.create_context(strategy: :important)
+context = htm.working_memory.assemble_context(strategy: :frequent)
 ```
 
 **How it works:**
 
-1. Sort memories by importance (highest first)
+1. Sort memories by access count (highest first)
 2. Add memories in order until token limit reached
 3. Return assembled context
 
@@ -233,44 +229,38 @@ context = htm.create_context(strategy: :important)
 **Example:**
 
 ```ruby
-# Knowledge base with priorities
+# Knowledge base with priorities tracked via access patterns
 class KnowledgeBot
   def initialize
     @htm = HTM.new(robot_name: "Knowledge")
 
     # Add critical system constraints
-    @htm.add_node(
-      "constraint_001",
+    @htm.remember(
       "CRITICAL: Never expose API keys in responses",
-      type: :fact,
-      importance: 10.0
+      metadata: { priority: "critical", category: "constraint" }
     )
 
     # Add important user preferences
-    @htm.add_node(
-      "pref_001",
+    @htm.remember(
       "User prefers concise explanations",
-      type: :preference,
-      importance: 8.0
+      metadata: { priority: "high", category: "preference" }
     )
 
     # Add general knowledge
-    @htm.add_node(
-      "fact_001",
+    @htm.remember(
       "Python uses indentation for code blocks",
-      type: :fact,
-      importance: 5.0
+      metadata: { priority: "medium", category: "fact" }
     )
   end
 
   def answer_question(question)
-    # Get most important context first
-    context = @htm.create_context(
-      strategy: :important,
+    # Get most frequently accessed context first
+    context = @htm.working_memory.assemble_context(
+      strategy: :frequent,
       max_tokens: 5_000
     )
 
-    # Critical constraints and preferences are included first
+    # Frequently accessed constraints and preferences are included first
     generate_answer(context, question)
   end
 
@@ -278,22 +268,22 @@ class KnowledgeBot
 
   def generate_answer(context, question)
     # LLM integration
-    "Answer based on important context"
+    "Answer based on frequently accessed context"
   end
 end
 ```
 
 ### Balanced Strategy (Recommended)
 
-The `:balanced` strategy combines importance and recency using a weighted formula.
+The `:balanced` strategy combines access frequency and recency using a weighted formula.
 
 ```ruby
-context = htm.create_context(strategy: :balanced)
+context = htm.working_memory.assemble_context(strategy: :balanced)
 ```
 
 **How it works:**
 
-1. Calculate score: `importance × (1 / (1 + age_in_hours))`
+1. Calculate score: `log(1 + access_count) × recency_factor`
 2. Sort by score (highest first)
 3. Add memories until token limit reached
 4. Return assembled context
@@ -301,21 +291,21 @@ context = htm.create_context(strategy: :balanced)
 **Scoring examples:**
 
 ```ruby
-# Recent + Important: High score
-# Importance: 9.0, Age: 1 hour
-# Score: 9.0 × (1 / (1 + 1)) = 4.5 ✓ Included
+# Recent + Frequently accessed: High score
+# Access count: 10, Age: 1 hour
+# Score: log(11) × (1 / (1 + 1/3600)) ≈ 2.4 ✓ Included
 
-# Old + Important: Medium score
-# Importance: 9.0, Age: 24 hours
-# Score: 9.0 × (1 / (1 + 24)) = 0.36 ≈ Maybe
+# Old + Frequently accessed: Medium score
+# Access count: 10, Age: 24 hours
+# Score: log(11) × (1 / (1 + 24)) ≈ 0.10 ≈ Maybe
 
-# Recent + Unimportant: Low score
-# Importance: 2.0, Age: 1 hour
-# Score: 2.0 × (1 / (1 + 1)) = 1.0 ≈ Maybe
+# Recent + Rarely accessed: Low score
+# Access count: 1, Age: 1 hour
+# Score: log(2) × (1 / (1 + 1/3600)) ≈ 0.69 ≈ Maybe
 
-# Old + Unimportant: Very low score
-# Importance: 2.0, Age: 24 hours
-# Score: 2.0 × (1 / (1 + 24)) = 0.08 ✗ Excluded
+# Old + Rarely accessed: Very low score
+# Access count: 1, Age: 24 hours
+# Score: log(2) × (1 / (1 + 24)) ≈ 0.03 ✗ Excluded
 ```
 
 **Best for:**
@@ -339,15 +329,13 @@ class Assistant
 
   def process(user_input)
     # Add user input
-    @htm.add_node(
-      "input_#{Time.now.to_i}",
+    @htm.remember(
       user_input,
-      type: :context,
-      importance: 7.0
+      metadata: { role: "user", timestamp: Time.now.to_i }
     )
 
-    # Get balanced context (recent + important)
-    context = @htm.create_context(
+    # Get balanced context (frequent + recent)
+    context = @htm.working_memory.assemble_context(
       strategy: :balanced,
       max_tokens: 50_000
     )
@@ -387,23 +375,23 @@ Control context size with token limits:
 
 ```ruby
 # Use default (working memory size)
-context = htm.create_context(strategy: :balanced)
+context = htm.working_memory.assemble_context(strategy: :balanced)
 
 # Custom limit
-context = htm.create_context(
+context = htm.working_memory.assemble_context(
   strategy: :balanced,
   max_tokens: 50_000
 )
 
 # Small context for simple queries
-context = htm.create_context(
+context = htm.working_memory.assemble_context(
   strategy: :recent,
   max_tokens: 5_000
 )
 
 # Large context for complex tasks
-context = htm.create_context(
-  strategy: :important,
+context = htm.working_memory.assemble_context(
+  strategy: :frequent,
   max_tokens: 200_000
 )
 ```
@@ -433,76 +421,72 @@ require 'benchmark'
 
 # Add 1000 test memories
 1000.times do |i|
-  htm.add_node(
-    "test_#{i}",
-    "Memory #{i}",
-    importance: rand(1.0..10.0)
-  )
+  htm.remember("Memory #{i}")
 end
 
 # Benchmark strategies
 Benchmark.bm(15) do |x|
   x.report("Recent:") do
-    100.times { htm.create_context(strategy: :recent) }
+    100.times { htm.working_memory.assemble_context(strategy: :recent) }
   end
 
-  x.report("Important:") do
-    100.times { htm.create_context(strategy: :important) }
+  x.report("Frequent:") do
+    100.times { htm.working_memory.assemble_context(strategy: :frequent) }
   end
 
   x.report("Balanced:") do
-    100.times { htm.create_context(strategy: :balanced) }
+    100.times { htm.working_memory.assemble_context(strategy: :balanced) }
   end
 end
 
 # Typical results:
 #                       user     system      total        real
 # Recent:           0.050000   0.000000   0.050000 (  0.051234)
-# Important:        0.045000   0.000000   0.045000 (  0.047891)
+# Frequent:         0.045000   0.000000   0.045000 (  0.047891)
 # Balanced:         0.080000   0.000000   0.080000 (  0.082456)
 ```
 
 **Notes:**
 
 - `:recent` is fastest (simple sort)
-- `:important` is fast (simple sort)
+- `:frequent` is fast (simple sort)
 - `:balanced` is slower (complex calculation)
 - All are typically < 100ms for normal working memory sizes
 
 ### Quality Comparison
 
 ```ruby
-# Test scenario: Mix of old important and recent unimportant data
+# Test scenario: Mix of frequently accessed old data and recent rarely accessed data
 
 # Setup
 htm = HTM.new(robot_name: "Test")
 
-# Add old important data
-htm.add_node("old_critical", "Critical system constraint", importance: 10.0)
+# Add frequently accessed data (simulate high access count)
+htm.remember("Critical system constraint", metadata: { priority: "critical" })
 sleep 1  # Simulate age
 
-# Add recent unimportant data
+# Add recent but rarely accessed data
 20.times do |i|
-  htm.add_node("recent_#{i}", "Recent note #{i}", importance: 2.0)
+  htm.remember("Recent note #{i}", metadata: { priority: "low" })
 end
 
 # Compare strategies
 puts "=== Recent Strategy ==="
-context = htm.create_context(strategy: :recent, max_tokens: 1000)
+context = htm.working_memory.assemble_context(strategy: :recent, max_tokens: 1000)
 puts context.include?("Critical system constraint") ? "✓ Has critical" : "✗ Missing critical"
 
-puts "\n=== Important Strategy ==="
-context = htm.create_context(strategy: :important, max_tokens: 1000)
+puts "\n=== Frequent Strategy ==="
+context = htm.working_memory.assemble_context(strategy: :frequent, max_tokens: 1000)
 puts context.include?("Critical system constraint") ? "✓ Has critical" : "✗ Missing critical"
 
 puts "\n=== Balanced Strategy ==="
-context = htm.create_context(strategy: :balanced, max_tokens: 1000)
+context = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: 1000)
 puts context.include?("Critical system constraint") ? "✓ Has critical" : "✗ Missing critical"
 
-# Results:
-# Recent: ✗ Missing critical (prioritized recent notes)
-# Important: ✓ Has critical (prioritized by importance)
-# Balanced: ✓ Has critical (balanced approach)
+# Results depend on actual access patterns:
+# Recent: May miss older frequently accessed data
+# Frequent: Prioritizes frequently accessed items
+# Balanced: Combines frequency and recency
 ```
 
 ## Advanced Techniques
@@ -514,13 +498,13 @@ Use multiple strategies for comprehensive context:
 ```ruby
 def multi_strategy_context(max_tokens_per_strategy: 10_000)
   # Get different perspectives
-  recent = htm.create_context(
+  recent = htm.working_memory.assemble_context(
     strategy: :recent,
     max_tokens: max_tokens_per_strategy
   )
 
-  important = htm.create_context(
-    strategy: :important,
+  frequent = htm.working_memory.assemble_context(
+    strategy: :frequent,
     max_tokens: max_tokens_per_strategy
   )
 
@@ -529,8 +513,8 @@ def multi_strategy_context(max_tokens_per_strategy: 10_000)
     === Recent Context ===
     #{recent}
 
-    === Important Context ===
-    #{important}
+    === Frequently Accessed Context ===
+    #{frequent}
   CONTEXT
 
   combined
@@ -545,45 +529,44 @@ Choose strategy based on query type:
 def smart_context(query)
   strategy = if query.match?(/recent|latest|current/)
     :recent
-  elsif query.match?(/important|critical|must/)
-    :important
+  elsif query.match?(/important|critical|must|frequent/)
+    :frequent
   else
     :balanced
   end
 
-  htm.create_context(strategy: strategy, max_tokens: 20_000)
+  htm.working_memory.assemble_context(strategy: strategy, max_tokens: 20_000)
 end
 
 # Usage
 context = smart_context("What are the recent changes?")    # Uses :recent
-context = smart_context("What are critical constraints?")  # Uses :important
+context = smart_context("What are critical constraints?")  # Uses :frequent
 context = smart_context("How do we handle auth?")         # Uses :balanced
 ```
 
 ### 3. Filtered Context
 
-Include only specific types of memories:
+Include only memories matching specific metadata:
 
 ```ruby
-def filtered_context(type:, strategy: :balanced)
-  # This requires custom implementation
-  # HTM doesn't expose working memory internals directly
-
-  # Workaround: Recall specific types
+def filtered_context(category:)
+  # Recall memories with specific metadata
   memories = htm.recall(
+    category,
     timeframe: "last 24 hours",
-    topic: "type:#{type}",  # Pseudo-filter
+    metadata: { category: category },
     strategy: :hybrid,
-    limit: 50
-  ).select { |m| m['type'] == type.to_s }
+    limit: 50,
+    raw: true
+  )
 
-  # Manually assemble context
-  memories.map { |m| m['value'] }.join("\n\n")
+  # Manually assemble context from results
+  memories.map { |m| m['content'] }.join("\n\n")
 end
 
 # Usage
-facts_only = filtered_context(type: :fact)
-decisions_only = filtered_context(type: :decision)
+facts_only = filtered_context(category: "fact")
+decisions_only = filtered_context(category: "decision")
 ```
 
 ### 4. Sectioned Context
@@ -592,27 +575,40 @@ Organize context into sections:
 
 ```ruby
 def sectioned_context
-  # Get different types of context
-  facts = htm.recall(timeframe: "all time", topic: "fact")
-    .select { |m| m['type'] == 'fact' }
-    .first(5)
+  # Get different types of context using metadata filtering
+  facts = htm.recall(
+    "facts",
+    timeframe: "all time",
+    metadata: { category: "fact" },
+    limit: 5,
+    raw: true
+  )
 
-  decisions = htm.recall(timeframe: "all time", topic: "decision")
-    .select { |m| m['type'] == 'decision' }
-    .first(5)
+  decisions = htm.recall(
+    "decisions",
+    timeframe: "all time",
+    metadata: { category: "decision" },
+    limit: 5,
+    raw: true
+  )
 
-  recent = htm.recall(timeframe: "last hour", topic: "", limit: 5)
+  recent = htm.recall(
+    "recent",
+    timeframe: "last hour",
+    limit: 5,
+    raw: true
+  )
 
   # Format as sections
   <<~CONTEXT
     === Core Facts ===
-    #{facts.map { |f| "- #{f['value']}" }.join("\n")}
+    #{facts.map { |f| "- #{f['content']}" }.join("\n")}
 
     === Key Decisions ===
-    #{decisions.map { |d| "- #{d['value']}" }.join("\n")}
+    #{decisions.map { |d| "- #{d['content']}" }.join("\n")}
 
     === Recent Activity ===
-    #{recent.map { |r| "- #{r['value']}" }.join("\n")}
+    #{recent.map { |r| "- #{r['content']}" }.join("\n")}
   CONTEXT
 end
 ```
@@ -623,9 +619,8 @@ Ensure context fits LLM limits:
 
 ```ruby
 class TokenAwareContext
-  def initialize(htm, embedding_service)
+  def initialize(htm)
     @htm = htm
-    @embedding_service = embedding_service
   end
 
   def create(strategy:, llm_context_window:, reserve_for_prompt: 1000)
@@ -633,20 +628,20 @@ class TokenAwareContext
     available = llm_context_window - reserve_for_prompt
 
     # Get context
-    context = @htm.create_context(
+    context = @htm.working_memory.assemble_context(
       strategy: strategy,
       max_tokens: available
     )
 
     # Verify token count
-    actual_tokens = @embedding_service.count_tokens(context)
+    actual_tokens = HTM.configuration.count_tokens(context)
 
     if actual_tokens > available
       warn "Context exceeded limit! Truncating..."
       # Retry with smaller limit
-      context = @htm.create_context(
+      context = @htm.working_memory.assemble_context(
         strategy: strategy,
-        max_tokens: available * 0.9  # 90% to be safe
+        max_tokens: (available * 0.9).to_i  # 90% to be safe
       )
     end
 
@@ -655,8 +650,7 @@ class TokenAwareContext
 end
 
 # Usage
-embedding_service = HTM::EmbeddingService.new
-context_builder = TokenAwareContext.new(htm, embedding_service)
+context_builder = TokenAwareContext.new(htm)
 
 context = context_builder.create(
   strategy: :balanced,
@@ -671,7 +665,7 @@ context = context_builder.create(
 
 ```ruby
 def generate_with_context(user_query)
-  context = htm.create_context(strategy: :balanced, max_tokens: 50_000)
+  context = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: 50_000)
 
   system_prompt = <<~SYSTEM
     You are a helpful AI assistant with access to memory.
@@ -706,26 +700,22 @@ class ConversationManager
   def add_turn(user_msg, assistant_msg)
     timestamp = Time.now.to_i
 
-    @htm.add_node(
-      "#{@conversation_id}_#{timestamp}_user",
+    @htm.remember(
       user_msg,
-      type: :context,
-      importance: 6.0,
-      tags: ["conversation", @conversation_id]
+      tags: ["conversation:#{@conversation_id}"],
+      metadata: { role: "user", timestamp: timestamp }
     )
 
-    @htm.add_node(
-      "#{@conversation_id}_#{timestamp}_assistant",
+    @htm.remember(
       assistant_msg,
-      type: :context,
-      importance: 6.0,
-      tags: ["conversation", @conversation_id]
+      tags: ["conversation:#{@conversation_id}"],
+      metadata: { role: "assistant", timestamp: timestamp }
     )
   end
 
   def get_context_for_llm
     # Get recent conversation
-    @htm.create_context(
+    @htm.working_memory.assemble_context(
       strategy: :recent,
       max_tokens: 10_000
     )
@@ -737,16 +727,16 @@ end
 
 ```ruby
 def rag_query(question)
-  # 1. Retrieve relevant memories
+  # 1. Retrieve relevant memories (adds to working memory)
   relevant = htm.recall(
+    question,
     timeframe: "last month",
-    topic: question,
     strategy: :hybrid,
     limit: 10
   )
 
   # 2. Create context from working memory (includes retrieved + existing)
-  context = htm.create_context(
+  context = htm.working_memory.assemble_context(
     strategy: :balanced,
     max_tokens: 30_000
   )
@@ -788,7 +778,7 @@ class ContextCache
     end
 
     # Generate new context
-    context = @htm.create_context(
+    context = @htm.working_memory.assemble_context(
       strategy: strategy,
       max_tokens: max_tokens
     )
@@ -817,17 +807,17 @@ context = cache.get_context(strategy: :balanced)  # Cached for 30s
 ```ruby
 def progressive_context(start_tokens: 5_000, max_tokens: 50_000)
   # Start small
-  context = htm.create_context(strategy: :balanced, max_tokens: start_tokens)
+  context = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: start_tokens)
 
   # Check if more context needed (based on your logic)
   if needs_more_context?(context)
     # Expand gradually
-    context = htm.create_context(strategy: :balanced, max_tokens: start_tokens * 2)
+    context = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: start_tokens * 2)
   end
 
   if still_needs_more?(context)
     # Expand to max
-    context = htm.create_context(strategy: :balanced, max_tokens: max_tokens)
+    context = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: max_tokens)
   end
 
   context
@@ -848,33 +838,45 @@ end
 
 ```ruby
 def selective_context(query)
-  # Determine what's relevant
+  # Determine what's relevant based on query
   include_facts = query.match?(/fact|truth|information/)
   include_decisions = query.match?(/decision|choice|why/)
   include_code = query.match?(/code|implement|example/)
 
-  # Build custom context
+  # Build custom context using metadata filtering
   parts = []
 
   if include_facts
-    facts = htm.recall(timeframe: "all time", topic: query)
-      .select { |m| m['type'] == 'fact' }
-      .first(5)
-    parts << "Facts:\n" + facts.map { |f| "- #{f['value']}" }.join("\n")
+    facts = htm.recall(
+      query,
+      timeframe: "all time",
+      metadata: { category: "fact" },
+      limit: 5,
+      raw: true
+    )
+    parts << "Facts:\n" + facts.map { |f| "- #{f['content']}" }.join("\n")
   end
 
   if include_decisions
-    decisions = htm.recall(timeframe: "all time", topic: query)
-      .select { |m| m['type'] == 'decision' }
-      .first(5)
-    parts << "Decisions:\n" + decisions.map { |d| "- #{d['value']}" }.join("\n")
+    decisions = htm.recall(
+      query,
+      timeframe: "all time",
+      metadata: { category: "decision" },
+      limit: 5,
+      raw: true
+    )
+    parts << "Decisions:\n" + decisions.map { |d| "- #{d['content']}" }.join("\n")
   end
 
   if include_code
-    code = htm.recall(timeframe: "all time", topic: query)
-      .select { |m| m['type'] == 'code' }
-      .first(3)
-    parts << "Code Examples:\n" + code.map { |c| c['value'] }.join("\n\n")
+    code = htm.recall(
+      query,
+      timeframe: "all time",
+      metadata: { category: "code" },
+      limit: 3,
+      raw: true
+    )
+    parts << "Code Examples:\n" + code.map { |c| c['content'] }.join("\n\n")
   end
 
   parts.join("\n\n")
@@ -887,26 +889,26 @@ end
 
 ```ruby
 # Use :recent for conversations
-context = htm.create_context(strategy: :recent)
+context = htm.working_memory.assemble_context(strategy: :recent)
 
-# Use :important for critical operations
-context = htm.create_context(strategy: :important)
+# Use :frequent for critical operations
+context = htm.working_memory.assemble_context(strategy: :frequent)
 
 # Use :balanced as default (recommended)
-context = htm.create_context(strategy: :balanced)
+context = htm.working_memory.assemble_context(strategy: :balanced)
 ```
 
 ### 2. Set Appropriate Token Limits
 
 ```ruby
 # Don't exceed LLM context window
-context = htm.create_context(
+context = htm.working_memory.assemble_context(
   strategy: :balanced,
   max_tokens: 100_000  # Leave room for prompt
 )
 
 # Smaller contexts are faster
-context = htm.create_context(
+context = htm.working_memory.assemble_context(
   strategy: :recent,
   max_tokens: 5_000  # Quick queries
 )
@@ -916,13 +918,12 @@ context = htm.create_context(
 
 ```ruby
 def monitor_context
-  context = htm.create_context(strategy: :balanced)
+  context = htm.working_memory.assemble_context(strategy: :balanced)
 
   puts "Context length: #{context.length} characters"
 
-  # Count token estimate
-  embedding_service = HTM::EmbeddingService.new
-  tokens = embedding_service.count_tokens(context)
+  # Count tokens
+  tokens = HTM.configuration.count_tokens(context)
   puts "Estimated tokens: #{tokens}"
 
   # Check if too small or too large
@@ -935,15 +936,15 @@ end
 
 ```ruby
 def context_with_metadata
-  context = htm.create_context(strategy: :balanced, max_tokens: 20_000)
+  context = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: 20_000)
 
   # Add metadata header
-  stats = htm.memory_stats
+  wm = htm.working_memory
 
   <<~CONTEXT
     [Context assembled at #{Time.now}]
     [Strategy: balanced]
-    [Working memory: #{stats[:working_memory][:node_count]} nodes]
+    [Working memory: #{wm.node_count} nodes]
     [Robot: #{htm.robot_name}]
 
     #{context}
@@ -962,27 +963,27 @@ htm = HTM.new(
   working_memory_size: 128_000
 )
 
-# Add various memories
-htm.add_node("fact_001", "User prefers Ruby", type: :fact, importance: 9.0)
-htm.add_node("decision_001", "Use PostgreSQL", type: :decision, importance: 8.0)
-htm.add_node("context_001", "Currently debugging auth", type: :context, importance: 7.0)
-htm.add_node("code_001", "def auth...", type: :code, importance: 6.0)
-htm.add_node("note_001", "Check logs later", type: :context, importance: 2.0)
+# Add various memories with metadata for categorization
+htm.remember("User prefers Ruby", metadata: { category: "fact", priority: "high" })
+htm.remember("Use PostgreSQL for database", metadata: { category: "decision", priority: "high" })
+htm.remember("Currently debugging auth module", metadata: { category: "context", priority: "medium" })
+htm.remember("def authenticate(token)...", metadata: { category: "code", priority: "medium" })
+htm.remember("Check logs later", metadata: { category: "note", priority: "low" })
 
 puts "=== Recent Strategy ==="
-recent = htm.create_context(strategy: :recent, max_tokens: 5_000)
+recent = htm.working_memory.assemble_context(strategy: :recent, max_tokens: 5_000)
 puts recent
 puts "\n(Newest first)"
 
-puts "\n=== Important Strategy ==="
-important = htm.create_context(strategy: :important, max_tokens: 5_000)
-puts important
-puts "\n(Most important first)"
+puts "\n=== Frequent Strategy ==="
+frequent = htm.working_memory.assemble_context(strategy: :frequent, max_tokens: 5_000)
+puts frequent
+puts "\n(Most frequently accessed first)"
 
 puts "\n=== Balanced Strategy ==="
-balanced = htm.create_context(strategy: :balanced, max_tokens: 5_000)
+balanced = htm.working_memory.assemble_context(strategy: :balanced, max_tokens: 5_000)
 puts balanced
-puts "\n(Recent + important)"
+puts "\n(Balanced frequency + recency)"
 
 # Use with LLM
 def ask_llm(context, question)