htm 0.0.14 → 0.0.15

data/docs/getting-started/quick-start.md

@@ -23,7 +23,7 @@ Get started with HTM in just 5 minutes! This guide will walk you through buildin
   <rect x="270" y="70" width="180" height="100" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="5"/>
   <text x="360" y="95" text-anchor="middle" fill="#2196F3" font-size="16" font-weight="bold">Step 2</text>
   <text x="360" y="115" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Add Memories</text>
-  <text x="360" y="140" text-anchor="middle" fill="#B0B0B0" font-size="11">add_node()</text>
+  <text x="360" y="140" text-anchor="middle" fill="#B0B0B0" font-size="11">remember()</text>
   <text x="360" y="160" text-anchor="middle" fill="#B0B0B0" font-size="10">Store knowledge</text>
 
   <!-- Arrow 2 to 3 -->
@@ -43,7 +43,7 @@ Get started with HTM in just 5 minutes! This guide will walk you through buildin
   <rect x="710" y="70" width="180" height="100" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="3" rx="5"/>
   <text x="800" y="95" text-anchor="middle" fill="#FF9800" font-size="16" font-weight="bold">Step 4</text>
   <text x="800" y="115" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Use Context</text>
-  <text x="800" y="140" text-anchor="middle" fill="#B0B0B0" font-size="11">create_context()</text>
+  <text x="800" y="140" text-anchor="middle" fill="#B0B0B0" font-size="11">assemble_context()</text>
   <text x="800" y="160" text-anchor="middle" fill="#B0B0B0" font-size="10">For LLM prompts</text>
 
   <!-- Memory Layers Visualization -->
@@ -79,8 +79,8 @@ Get started with HTM in just 5 minutes! This guide will walk you through buildin
   <rect x="50" y="490" width="800" height="90" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="2" rx="5"/>
   <text x="450" y="515" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">Quick Example Code:</text>
   <text x="70" y="540" fill="#B0B0B0" font-family="monospace" font-size="10">htm = HTM.new(robot_name: "My Assistant")</text>
-  <text x="70" y="555" fill="#B0B0B0" font-family="monospace" font-size="10">htm.add_node("key1", "Remember this fact", type: :fact)</text>
-  <text x="70" y="570" fill="#B0B0B0" font-family="monospace" font-size="10">memories = htm.recall(timeframe: "today", topic: "fact")</text>
+  <text x="70" y="555" fill="#B0B0B0" font-family="monospace" font-size="10">htm.remember("Remember this fact", tags: ["fact"])</text>
+  <text x="70" y="570" fill="#B0B0B0" font-family="monospace" font-size="10">memories = htm.recall("fact", timeframe: "today")</text>
 
   <!-- Arrow markers -->
   <defs>
@@ -123,12 +123,18 @@ puts "=" * 60
 Create an HTM instance for your robot:
 
 ```ruby
+# Configure HTM globally (optional - uses Ollama by default)
+HTM.configure do |config|
+  config.embedding_provider = :ollama
+  config.embedding_model = 'nomic-embed-text:latest'
+  config.tag_provider = :ollama
+  config.tag_model = 'gemma3:latest'
+end
+
 # Initialize HTM with a robot name
 htm = HTM.new(
   robot_name: "Code Helper",
-  working_memory_size: 128_000,    # 128k tokens
-  embedding_service: :ollama,       # Use Ollama for embeddings
-  embedding_model: 'gpt-oss'        # Default embedding model
+  working_memory_size: 128_000    # 128k tokens
 )
 
 puts "✓ HTM initialized for '#{htm.robot_name}'"
@@ -140,11 +146,10 @@ puts "  Working Memory: #{htm.working_memory.max_tokens} tokens"
 
 - `robot_name`: A human-readable name for your AI robot
 - `working_memory_size`: Maximum tokens for active context (128k is typical)
-- `embedding_service`: Service to generate vector embeddings (`:ollama` is default)
-- `embedding_model`: Which model to use for embeddings (`gpt-oss` is default)
+- Configuration is set globally via `HTM.configure` block
 
 !!! tip "Robot Identity"
-    Each HTM instance represents one robot. The `robot_id` is automatically generated (UUID) and used to track which robot created each memory.
+    Each HTM instance represents one robot. The `robot_id` is an integer database ID used to track which robot created each memory.
 
 ### Step 3: Add Your First Memory
 
@@ -153,31 +158,25 @@ Add a project decision to HTM's memory:
 ```ruby
 puts "\n1. Adding a project decision..."
 
-htm.add_node(
-  "decision_001",                    # Unique key
+node_id = htm.remember(
   "We decided to use PostgreSQL for the database " \
   "because it provides excellent time-series optimization and " \
   "native vector search with pgvector.",
-  type: :decision,                   # Memory type
-  category: "architecture",          # Optional category
-  importance: 9.0,                   # Importance score (0-10)
-  tags: ["database", "architecture"] # Searchable tags
+  tags: ["database:postgresql", "architecture:decisions"],
+  metadata: { category: "architecture", priority: "high" }
 )
 
-puts "✓ Decision added to memory"
+puts "✓ Decision added to memory (node #{node_id})"
 ```
 
 **Memory Components:**
 
-- **Key**: Unique identifier (e.g., `"decision_001"`)
-- **Value**: The actual content/memory text
-- **Type**: Category of memory (`:decision`, `:fact`, `:code`, `:preference`, etc.)
-- **Category**: Optional grouping
-- **Importance**: Score from 0.0 to 10.0 (affects recall priority)
-- **Tags**: Searchable keywords for organization
+- **Content**: The actual memory text (first argument)
+- **Tags**: Hierarchical tags for categorization (e.g., `"database:postgresql"`)
+- **Metadata**: Arbitrary key-value data stored as JSONB
 
 !!! note "Automatic Embeddings"
-    HTM automatically generates vector embeddings for the memory content using Ollama. You don't need to handle embeddings yourself!
+    HTM automatically generates vector embeddings for the memory content in the background. You don't need to handle embeddings yourself!
 
 ### Step 4: Add More Memories
 
@@ -186,51 +185,44 @@ Let's add a few more memories:
 ```ruby
 puts "\n2. Adding user preferences..."
 
-htm.add_node(
-  "pref_001",
+htm.remember(
   "User prefers using the debug_me gem for debugging instead of puts statements.",
-  type: :preference,
-  category: "coding_style",
-  importance: 7.0,
-  tags: ["debugging", "ruby", "preferences"]
+  tags: ["debugging:ruby", "preferences:coding-style"],
+  metadata: { category: "preference" }
 )
 
 puts "✓ Preference added"
 
 puts "\n3. Adding a code pattern..."
 
-htm.add_node(
-  "code_001",
+htm.remember(
   "For database queries, use connection pooling with the connection_pool gem " \
   "to handle concurrent requests efficiently.",
-  type: :code,
-  category: "patterns",
-  importance: 8.0,
-  tags: ["database", "performance", "ruby"],
-  related_to: ["decision_001"]  # Link to related memory
+  tags: ["database:performance", "ruby:patterns"],
+  metadata: { category: "code-pattern" }
 )
 
-puts "✓ Code pattern added (linked to decision_001)"
+puts "✓ Code pattern added"
 ```
 
-**Notice the `related_to` parameter?** This creates a relationship in the knowledge graph, linking related memories together.
+**Tags create relationships** - use hierarchical tags to build a navigable knowledge graph. Tags like `database:postgresql` and `database:performance` are connected through their shared `database` prefix.
 
-### Step 5: Retrieve a Specific Memory
+### Step 5: Look Up a Specific Memory
 
-Retrieve a memory by its key:
+Look up a memory by its node ID:
 
 ```ruby
-puts "\n4. Retrieving specific memory..."
+puts "\n4. Looking up specific memory..."
 
-memory = htm.retrieve("decision_001")
+# Use the node_id returned from remember()
+node = HTM::Models::Node.find_by(id: node_id)
 
-if memory
+if node
   puts "✓ Found memory:"
-  puts "  Key: #{memory['key']}"
-  puts "  Type: #{memory['type']}"
-  puts "  Content: #{memory['value'][0..100]}..."
-  puts "  Importance: #{memory['importance']}"
-  puts "  Created: #{memory['created_at']}"
+  puts "  ID: #{node.id}"
+  puts "  Content: #{node.content[0..100]}..."
+  puts "  Tags: #{node.tags.pluck(:name).join(', ')}"
+  puts "  Created: #{node.created_at}"
 else
   puts "✗ Memory not found"
 end
@@ -244,22 +236,23 @@ Use HTM's powerful recall feature to find relevant memories:
 puts "\n5. Recalling memories about 'database'..."
 
 memories = htm.recall(
+  "database",                      # Topic (first positional argument)
   timeframe: "last week",          # Natural language time filter
-  topic: "database",               # What to search for
   limit: 10,                       # Max results
-  strategy: :hybrid                # Search strategy (vector + full-text)
+  strategy: :hybrid,               # Search strategy (vector + full-text)
+  raw: true                        # Return full node data
 )
 
 puts "✓ Found #{memories.length} relevant memories:"
 memories.each_with_index do |mem, idx|
-  puts "  #{idx + 1}. [#{mem['type']}] #{mem['value'][0..60]}..."
+  puts "  #{idx + 1}. #{mem['content'][0..60]}..."
 end
 ```
 
 **Search Strategies:**
 
 - **`:vector`**: Semantic similarity search using embeddings
-- **`:fulltext`**: Keyword-based PostgreSQL full-text search
+- **`:fulltext`**: Keyword-based PostgreSQL full-text search (default)
 - **`:hybrid`**: Combines both for best results (recommended)
 
 **Timeframe Options:**
@@ -268,7 +261,7 @@ end
 - `"yesterday"` - Previous day
 - `"last 30 days"` - Last month
 - `"this month"` - Current calendar month
-- Date ranges: `(Time.now - 7.days)..Time.now`
+- Date ranges: `7.days.ago..Time.now`
 
 ### Step 7: Create Context for Your LLM
 
@@ -277,8 +270,8 @@ Generate a context string optimized for LLM consumption:
 ```ruby
 puts "\n6. Creating context for LLM..."
 
-context = htm.create_context(
-  strategy: :balanced,             # Balance importance and recency
+context = htm.working_memory.assemble_context(
+  strategy: :balanced,             # Balance frequency and recency
   max_tokens: 50_000               # Optional token limit
 )
 
@@ -290,9 +283,9 @@ puts "..."
 
 **Context Strategies:**
 
-- **`:recent`**: Most recent memories first
-- **`:important`**: Highest importance scores first
-- **`:balanced`**: Combines importance × recency (recommended)
+- **`:recent`**: Most recently accessed memories first (LRU)
+- **`:frequent`**: Most frequently accessed memories first (LFU)
+- **`:balanced`**: Combines frequency × recency (recommended)
 
 This context can be directly injected into your LLM prompt:
 
@@ -317,14 +310,18 @@ View statistics about your memory usage:
 ```ruby
 puts "\n7. Memory Statistics:"
 
-stats = htm.memory_stats
-
-puts "  Total nodes in long-term memory: #{stats[:total_nodes]}"
-puts "  Active robots: #{stats[:active_robots]}"
-puts "  Working memory usage: #{stats[:working_memory][:current_tokens]} / " \
-     "#{stats[:working_memory][:max_tokens]} tokens " \
-     "(#{stats[:working_memory][:utilization].round(2)}%)"
-puts "  Database size: #{(stats[:database_size] / (1024.0 ** 2)).round(2)} MB"
+# Working memory stats
+wm = htm.working_memory
+puts "  Working memory:"
+puts "    Nodes: #{wm.node_count}"
+puts "    Tokens: #{wm.token_count} / #{wm.max_tokens}"
+puts "    Utilization: #{wm.utilization_percentage}%"
+
+# Long-term memory stats via models
+puts "  Long-term memory:"
+puts "    Total nodes: #{HTM::Models::Node.count}"
+puts "    Total tags: #{HTM::Models::Tag.count}"
+puts "    Active robots: #{HTM::Models::Robot.count}"
 ```
 
 ### Complete Example
@@ -339,52 +336,51 @@ require 'htm'
 puts "My First HTM Application"
 puts "=" * 60
 
-# Step 1: Initialize HTM
+# Step 1: Configure and initialize HTM
+HTM.configure do |config|
+  config.embedding_provider = :ollama
+  config.embedding_model = 'nomic-embed-text:latest'
+  config.tag_provider = :ollama
+  config.tag_model = 'gemma3:latest'
+end
+
 htm = HTM.new(
   robot_name: "Code Helper",
-  working_memory_size: 128_000,
-  embedding_service: :ollama,
-  embedding_model: 'gpt-oss'
+  working_memory_size: 128_000
 )
 
 puts "✓ HTM initialized for '#{htm.robot_name}'"
 
 # Step 2: Add memories
-htm.add_node(
-  "decision_001",
+htm.remember(
   "We decided to use PostgreSQL for the database.",
-  type: :decision,
-  category: "architecture",
-  importance: 9.0,
-  tags: ["database", "architecture"]
+  tags: ["database:postgresql", "architecture:decisions"],
+  metadata: { priority: "high" }
 )
 
-htm.add_node(
-  "pref_001",
+htm.remember(
   "User prefers using the debug_me gem for debugging.",
-  type: :preference,
-  importance: 7.0,
-  tags: ["debugging", "ruby"]
+  tags: ["debugging:ruby", "preferences"],
+  metadata: { category: "preference" }
 )
 
 puts "✓ Memories added"
 
 # Step 3: Recall memories
 memories = htm.recall(
+  "database",
   timeframe: "last week",
-  topic: "database",
   strategy: :hybrid
 )
 
 puts "✓ Found #{memories.length} memories about 'database'"
 
 # Step 4: Create context
-context = htm.create_context(strategy: :balanced)
+context = htm.working_memory.assemble_context(strategy: :balanced)
 puts "✓ Context created: #{context.length} characters"
 
 # Step 5: View statistics
-stats = htm.memory_stats
-puts "✓ Total nodes: #{stats[:total_nodes]}"
+puts "✓ Total nodes: #{HTM::Models::Node.count}"
 
 puts "\n" + "=" * 60
 puts "Success! Your first HTM application is working."
@@ -408,31 +404,32 @@ robot_a = HTM.new(robot_name: "Code Assistant")
 robot_b = HTM.new(robot_name: "Documentation Writer")
 
 # Robot A adds a memory
-robot_a.add_node(
-  "shared_001",
+robot_a.remember(
   "The API documentation is stored in the docs/ directory.",
-  type: :fact,
-  importance: 8.0
+  tags: ["docs:api", "project:structure"]
 )
 
 puts "Robot A added memory"
 
 # Robot B can access the same memory!
 memories = robot_b.recall(
+  "documentation",
   timeframe: "last week",
-  topic: "documentation",
   strategy: :hybrid
 )
 
 puts "Robot B found #{memories.length} memories"
 # Robot B sees Robot A's memory!
 
-# Track which robot said what
-breakdown = robot_b.which_robot_said("documentation")
-puts "Who mentioned 'documentation':"
-breakdown.each do |robot_id, count|
-  puts "  #{robot_id}: #{count} times"
-end
+# Query which robots have accessed which nodes
+HTM::Models::RobotNode.includes(:robot, :node)
+  .where(nodes: { content: 'documentation' })
+  .group(:robot_id)
+  .count
+  .each do |robot_id, count|
+    robot = HTM::Models::Robot.find(robot_id)
+    puts "  #{robot.name}: #{count} memories"
+  end
 ```
 
 **Use cases for multi-robot:**
@@ -444,54 +441,56 @@ end
 
 ## Working with Relationships
 
-Build a knowledge graph by linking related memories:
+Build a knowledge graph using hierarchical tags:
 
 ```ruby
 # Add parent concept
-htm.add_node(
-  "concept_databases",
+htm.remember(
   "Databases store and organize data persistently.",
-  type: :fact,
-  importance: 5.0
+  tags: ["knowledge:databases"]
 )
 
-# Add child concept with relationship
-htm.add_node(
-  "concept_postgresql",
+# Add child concept with shared tag hierarchy
+htm.remember(
   "PostgreSQL is a powerful open-source relational database.",
-  type: :fact,
-  importance: 7.0,
-  related_to: ["concept_databases"]  # Links to parent
+  tags: ["knowledge:databases:postgresql", "tech:database"]
 )
 
 # Add another related concept
-htm.add_node(
-  "concept_postgresql",
+htm.remember(
   "PostgreSQL provides robust relational database capabilities.",
-  type: :fact,
-  importance: 8.0,
-  related_to: ["concept_postgresql", "concept_databases"]
+  tags: ["knowledge:databases:postgresql:features", "tech:database"]
 )
 
-# Now you have a knowledge graph:
-# concept_databases
-#   ├── concept_postgresql
-#   │    └── concept_postgresql
+# View tag hierarchy
+puts HTM::Models::Tag.tree_string
+# knowledge
+#   └── databases
+#       └── postgresql
+#           └── features
+
+# Find all memories under a tag prefix
+nodes = HTM::Models::Tag.find_by(name: 'knowledge:databases')&.nodes
 ```
 
 ## Forget (Explicit Deletion)
 
-HTM follows a "never forget" philosophy, but you can explicitly delete memories:
+HTM follows a "never forget" philosophy with soft delete by default:
 
 ```ruby
-# Deletion requires confirmation
-htm.forget("old_decision", confirm: :confirmed)
+# Soft delete (recoverable) - default behavior
+node_id = htm.remember("Temporary note")
+htm.forget(node_id)                    # Soft delete
+htm.restore(node_id)                   # Restore it!
+
+# Permanent delete requires confirmation
+htm.forget(node_id, soft: false, confirm: :confirmed)
 
-puts "✓ Memory deleted"
+puts "✓ Memory permanently deleted"
 ```
 
-!!! warning "Deletion is Permanent"
-    The `forget()` method permanently deletes data. This is the **only** way to delete memories in HTM. Working memory evictions move data to long-term storage, they don't delete it.
+!!! info "Soft Delete by Default"
+    The `forget()` method performs a soft delete by default (sets `deleted_at` timestamp). The memory can be restored with `restore()`. Permanent deletion requires `soft: false, confirm: :confirmed`. Working memory evictions move data to long-term storage, they don't delete it.
 
 ## Next Steps
 
@@ -521,17 +520,16 @@ htm = HTM.new(
   working_memory_size: 256_000  # 256k tokens
 )
 
-# Try different embedding models
-htm = HTM.new(
-  robot_name: "Custom Embeddings",
-  embedding_service: :ollama,
-  embedding_model: 'llama2'  # Use Llama2 instead of gpt-oss
-)
+# Try different embedding models via configure
+HTM.configure do |config|
+  config.embedding_provider = :ollama
+  config.embedding_model = 'llama3:latest'  # Use Llama3
+end
 
 # Try different recall strategies
 memories = htm.recall(
+  "important decisions",
   timeframe: "last month",
-  topic: "important decisions",
   strategy: :vector  # Pure semantic search
 )
 ```
@@ -558,21 +556,17 @@ For production applications:
 
 ```ruby
 # Store user messages
-htm.add_node(
-  "msg_#{Time.now.to_i}",
+htm.remember(
   "User: How do I optimize database queries?",
-  type: :context,
-  importance: 6.0,
-  tags: ["conversation", "question"]
+  tags: ["conversation:question"],
+  metadata: { role: "user", timestamp: Time.now.to_i }
 )
 
 # Store assistant responses
-htm.add_node(
-  "response_#{Time.now.to_i}",
+htm.remember(
   "Assistant: Use indexes and connection pooling.",
-  type: :context,
-  importance: 6.0,
-  tags: ["conversation", "answer"]
+  tags: ["conversation:answer"],
+  metadata: { role: "assistant", timestamp: Time.now.to_i }
 )
 ```
 
@@ -580,12 +574,10 @@ htm.add_node(
 
 ```ruby
 # Extract patterns from code reviews
-htm.add_node(
-  "pattern_#{SecureRandom.hex(4)}",
+htm.remember(
   "Always validate user input before database queries.",
-  type: :code,
-  importance: 9.0,
-  tags: ["security", "validation", "best-practice"]
+  tags: ["security:validation", "patterns:best-practice"],
+  metadata: { source: "code-review" }
 )
 ```
 
@@ -593,14 +585,11 @@ htm.add_node(
 
 ```ruby
 # Document architectural decisions
-htm.add_node(
-  "adr_001",
+htm.remember(
   "Decision: Use microservices architecture. " \
   "Reasoning: Better scalability and independent deployment.",
-  type: :decision,
-  category: "architecture",
-  importance: 10.0,
-  tags: ["adr", "architecture", "microservices"]
+  tags: ["adr", "architecture:microservices"],
+  metadata: { category: "architecture", priority: "critical" }
 )
 ```
 
@@ -629,8 +618,8 @@ echo $HTM_DBURL
 **Solution**: Check Ollama's status and ensure the model is downloaded:
 
 ```bash
-ollama list | grep gpt-oss
-# Should show gpt-oss model
+ollama list | grep nomic-embed-text
+# Should show nomic-embed-text model
 ```
 
 ### Issue: Memory not found during recall
@@ -640,8 +629,8 @@ ollama list | grep gpt-oss
 ```ruby
 # Instead of "last week", use:
 memories = htm.recall(
-  timeframe: (Time.now - 3600)..Time.now,  # Last hour
-  topic: "your topic"
+  "your topic",
+  timeframe: (Time.now - 3600)..Time.now  # Last hour
 )
 ```
 

data/docs/guides/adding-memories.md

@@ -367,9 +367,8 @@ When you `remember()`, the node is automatically added to working memory:
 htm.remember("Important fact")
 
 # Check working memory
-stats = htm.working_memory.stats
-puts "Nodes in WM: #{stats[:node_count]}"
-puts "Token usage: #{stats[:utilization]}%"
+puts "Nodes in WM: #{htm.working_memory.node_count}"
+puts "Token usage: #{htm.working_memory.utilization_percentage}%"
 ```
 
 ### Eviction