htm 0.0.1 → 0.0.10

data/docs/guides/adding-memories.md

@@ -4,744 +4,425 @@ This guide covers everything you need to know about storing information in HTM e
 
 ## Basic Usage
 
-The primary method for adding memories is `add_node`:
+The primary method for adding memories is `remember`:
 
 ```ruby
-node_id = htm.add_node(
-  key,                    # Unique identifier
-  value,                  # Content (string)
-  type: :fact,           # Memory type
-  category: nil,         # Optional category
-  importance: 1.0,       # Importance score (0.0-10.0)
-  related_to: [],        # Array of related node keys
-  tags: []              # Array of tags
-)
+node_id = htm.remember(content, tags: [], metadata: {})
 ```
 
-The method returns the database ID of the created node.
-
-## Memory Types Deep Dive
-
-HTM supports six memory types, each optimized for specific use cases.
-
-### :fact - Immutable Facts
-
-Facts are unchanging truths about the world, users, or systems.
-
-```ruby
-# User information
-htm.add_node(
-  "user_name",
-  "The user's name is Alice Thompson",
-  type: :fact,
-  importance: 9.0,
-  tags: ["user", "identity"]
-)
+**Parameters:**
 
-# System configuration
-htm.add_node(
-  "system_timezone",
-  "System timezone is UTC",
-  type: :fact,
-  importance: 6.0,
-  tags: ["system", "config"]
-)
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `content` | String | *required* | The information to remember |
+| `tags` | Array\<String\> | `[]` | Manual tags to assign (in addition to auto-extracted tags) |
+| `metadata` | Hash | `{}` | Arbitrary key-value metadata stored as JSONB |
 
-# Domain knowledge
-htm.add_node(
-  "fact_photosynthesis",
-  "Photosynthesis converts light energy into chemical energy in plants",
-  type: :fact,
-  importance: 7.0,
-  tags: ["biology", "science"]
-)
-```
+The method returns the database ID of the created node.
 
-!!! tip "When to Use :fact"
-    - User profile information (name, email, preferences)
-    - System configuration that rarely changes
-    - Scientific facts or domain knowledge
-    - Historical events
-    - API endpoints and credentials
+## How Remember Works
 
-### :context - Conversation State
+When you call `remember()`:
 
-Context captures the current state of conversations or sessions.
+1. **Content hashing**: A SHA-256 hash of the content is computed
+2. **Deduplication check**: If a node with the same hash exists, reuse it
+3. **Node creation/linking**: Create new node OR link robot to existing node
+4. **Working memory**: Add node to working memory (evict if needed)
+5. **Background jobs**: Enqueue embedding and tag generation (async)
 
 ```ruby
-# Current conversation topic
-htm.add_node(
-  "context_#{session_id}_001",
-  "User is asking about database performance optimization",
-  type: :context,
-  importance: 6.0,
-  tags: ["conversation", "current"]
-)
-
-# Conversation mood
-htm.add_node(
-  "context_mood",
-  "User seems frustrated with slow query times",
-  type: :context,
-  importance: 7.0,
-  tags: ["conversation", "sentiment"]
-)
+# First robot remembers something
+node_id = htm.remember("PostgreSQL supports vector similarity search")
+# => 123 (new node created)
 
-# Current task
-htm.add_node(
-  "context_task",
-  "Helping user optimize their PostgreSQL queries",
-  type: :context,
-  importance: 8.0,
-  tags: ["task", "active"]
-)
+# Same content remembered again (by same or different robot)
+node_id = htm.remember("PostgreSQL supports vector similarity search")
+# => 123 (same node_id returned, just updates remember_count)
 ```
 
-!!! tip "When to Use :context"
-    - Current conversation topics
-    - Session state
-    - Temporary workflow status
-    - User's current goals or questions
-    - Conversation sentiment or mood
+## Content Types
 
-!!! note
-    Context memories are typically lower importance (4-6) since they become outdated quickly. They'll naturally get evicted from working memory as new context arrives.
+HTM doesn't enforce content types - just store meaningful text that stands alone:
 
-### :code - Code Snippets and Patterns
-
-Store code examples, patterns, and technical solutions.
+### Facts
 
 ```ruby
-# Function example
-htm.add_node(
-  "code_date_parser",
-  <<~CODE,
-    def parse_date(date_string)
-      Date.parse(date_string)
-    rescue ArgumentError
-      nil
-    end
-  CODE
-  type: :code,
-  importance: 6.0,
-  tags: ["ruby", "date", "parsing"]
-)
+# User information
+htm.remember("The user's name is Alice Thompson")
 
-# SQL query pattern
-htm.add_node(
-  "code_user_query",
-  <<~SQL,
-    SELECT u.id, u.name, COUNT(o.id) as order_count
-    FROM users u
-    LEFT JOIN orders o ON u.id = o.user_id
-    GROUP BY u.id, u.name
-    HAVING COUNT(o.id) > 10
-  SQL
-  type: :code,
-  category: "sql",
-  importance: 7.0,
-  tags: ["sql", "aggregation", "joins"]
-)
+# System configuration
+htm.remember("System timezone is UTC")
 
-# Configuration example
-htm.add_node(
-  "code_redis_config",
-  <<~YAML,
-    redis:
-      host: localhost
-      port: 6379
-      pool_size: 5
-      timeout: 2
-  YAML
-  type: :code,
-  category: "config",
-  importance: 5.0,
-  tags: ["redis", "configuration", "yaml"]
-)
+# Domain knowledge
+htm.remember("Photosynthesis converts light energy into chemical energy in plants")
 ```
 
-!!! tip "When to Use :code"
-    - Reusable code snippets
-    - Configuration examples
-    - SQL queries and patterns
-    - API request/response examples
-    - Algorithm implementations
-    - Regular expressions
-
-### :preference - User Preferences
-
-Store user preferences and settings.
+### Preferences
 
 ```ruby
 # Communication style
-htm.add_node(
-  "pref_communication",
-  "User prefers concise answers with bullet points",
-  type: :preference,
-  importance: 8.0,
-  tags: ["user", "communication", "style"]
-)
+htm.remember("User prefers concise answers with bullet points")
 
 # Technical preferences
-htm.add_node(
-  "pref_language",
-  "User prefers Ruby over Python for scripting tasks",
-  type: :preference,
-  importance: 7.0,
-  tags: ["user", "programming", "language"]
-)
-
-# UI preferences
-htm.add_node(
-  "pref_theme",
-  "User uses dark theme in their IDE",
-  type: :preference,
-  importance: 4.0,
-  tags: ["user", "ui", "theme"]
-)
-
-# Work preferences
-htm.add_node(
-  "pref_working_hours",
-  "User typically codes in the morning, prefers design work in afternoon",
-  type: :preference,
-  importance: 5.0,
-  tags: ["user", "schedule", "productivity"]
-)
+htm.remember("User prefers Ruby over Python for scripting tasks")
 ```
 
-!!! tip "When to Use :preference"
-    - Communication style preferences
-    - Technical tool preferences
-    - UI/UX preferences
-    - Work habits and patterns
-    - Learning style preferences
-
-### :decision - Architectural Decisions
-
-Track important decisions with rationale.
+### Decisions
 
 ```ruby
 # Technology choice
-htm.add_node(
-  "decision_database",
-  <<~DECISION,
-    Decision: Use PostgreSQL with TimescaleDB for HTM storage
-
-    Rationale:
-    - Excellent time-series optimization
-    - Native vector search with pgvector
-    - Strong consistency guarantees
-    - Mature ecosystem
-
-    Alternatives considered:
-    - MongoDB (rejected: eventual consistency issues)
-    - Redis (rejected: limited persistence)
-  DECISION
-  type: :decision,
-  category: "architecture",
-  importance: 9.5,
-  tags: ["architecture", "database", "timescaledb"]
-)
+htm.remember(<<~DECISION)
+  Decision: Use PostgreSQL with pgvector for HTM storage
+
+  Rationale:
+  - Excellent vector search via pgvector
+  - Strong consistency guarantees
+  - Mature ecosystem
+
+  Alternatives considered:
+  - MongoDB (rejected: eventual consistency issues)
+  - Redis (rejected: limited persistence)
+DECISION
+```
 
-# Design pattern choice
-htm.add_node(
-  "decision_memory_architecture",
-  <<~DECISION,
-    Decision: Implement two-tier memory (working + long-term)
-
-    Rationale:
-    - Working memory provides fast access
-    - Long-term memory ensures durability
-    - Mirrors human memory architecture
-    - Allows token-limited LLM context
-
-    Trade-offs:
-    - Added complexity in synchronization
-    - Eviction strategy needs tuning
-  DECISION
-  type: :decision,
-  category: "architecture",
-  importance: 10.0,
-  tags: ["architecture", "memory", "design-pattern"]
-)
+### Code Snippets
 
-# Process decision
-htm.add_node(
-  "decision_testing",
-  "Decided to use Minitest over RSpec for simplicity and speed",
-  type: :decision,
-  category: "process",
-  importance: 6.0,
-  tags: ["testing", "tools"]
-)
+```ruby
+# Function example
+htm.remember(<<~CODE)
+  def parse_date(date_string)
+    Date.parse(date_string)
+  rescue ArgumentError
+    nil
+  end
+CODE
+
+# SQL query pattern
+htm.remember(<<~SQL)
+  SELECT u.id, u.name, COUNT(o.id) as order_count
+  FROM users u
+  LEFT JOIN orders o ON u.id = o.user_id
+  GROUP BY u.id, u.name
+  HAVING COUNT(o.id) > 10
+SQL
 ```
 
-!!! tip "When to Use :decision"
-    - Technology selections
-    - Architecture patterns
-    - API design choices
-    - Process decisions
-    - Trade-off analysis results
+## Using Tags
 
-!!! note "Decision Template"
-    Include: what was decided, why, alternatives considered, and trade-offs. This context helps future decision-making.
+Tags provide hierarchical organization for your memories. HTM automatically extracts tags from content, but you can also specify manual tags.
 
-### :question - Unresolved Questions
+### Hierarchical Tag Convention
 
-Track questions that need answering.
+Use colons to create hierarchical namespaces:
 
 ```ruby
-# Technical question
-htm.add_node(
-  "question_caching",
-  "Should we implement Redis caching for frequently accessed memories?",
-  type: :question,
-  importance: 7.0,
-  tags: ["performance", "caching", "open"]
-)
-
-# Design question
-htm.add_node(
-  "question_auth",
-  "How should we handle authentication for multi-robot scenarios?",
-  type: :question,
-  importance: 8.0,
-  tags: ["security", "architecture", "open"]
+# Manual tags with hierarchy
+htm.remember(
+  "PostgreSQL 17 adds MERGE statement improvements",
+  tags: ["database:postgresql", "database:sql", "version:17"]
 )
 
-# Research question
-htm.add_node(
-  "question_embeddings",
-  "Would fine-tuning embeddings on our domain improve recall accuracy?",
-  type: :question,
-  importance: 6.0,
-  tags: ["embeddings", "research", "open"]
-)
+# Tags are used in hybrid search for relevance boosting
+# A recall for "postgresql" will boost nodes with matching tags
 ```
 
-!!! tip "When to Use :question"
-    - Open technical questions
-    - Design uncertainties
-    - Research topics to investigate
-    - Feature requests to evaluate
-    - Performance questions
-
-!!! tip "Closing Questions"
-    When a question is answered, add a related decision node and mark the question as resolved by updating its tags.
-
-## Importance Scoring Guidelines
+### Tag Naming Conventions
 
-The importance score (0.0-10.0) determines memory retention and eviction priority.
+```ruby
+# Good: Consistent, lowercase, hierarchical
+tags: ["database:postgresql", "architecture:api", "security:authentication"]
 
-![Importance Scoring Framework](../assets/images/htm-importance-scoring-framework.svg)
+# Avoid: Inconsistent casing, flat tags, vague terms
+tags: ["PostgreSQL", "stuff", "misc"]
+```
 
-### Scoring Framework
+### Common Tag Patterns
 
 ```ruby
-# Critical (9.0-10.0): Must never lose
-htm.add_node("api_key", "Production API key: ...", importance: 10.0)
-htm.add_node("decision_architecture", "Core architecture decision", importance: 9.5)
-
-# High (7.0-8.9): Very important, high retention
-htm.add_node("user_identity", "User's name and email", importance: 8.0)
-htm.add_node("major_decision", "Chose Rails for web framework", importance: 7.5)
-
-# Medium (4.0-6.9): Moderately important
-htm.add_node("code_snippet", "Useful utility function", importance: 6.0)
-htm.add_node("context_current", "Current conversation topic", importance: 5.0)
-htm.add_node("preference_minor", "Prefers tabs over spaces", importance: 4.0)
-
-# Low (1.0-3.9): Nice to have, can evict
-htm.add_node("temp_note", "Check logs later", importance: 3.0)
-htm.add_node("minor_context", "Mentioned weather briefly", importance: 2.0)
-htm.add_node("throwaway", "Temporary calculation result", importance: 1.0)
-```
-
-### Importance by Type
+# Domain tags
+tags: ["database:postgresql", "api:rest", "auth:jwt"]
 
-Typical importance ranges for each type:
+# Layer tags
+tags: ["layer:frontend", "layer:backend", "layer:infrastructure"]
 
-| Type | Typical Range | Example |
-|------|---------------|---------|
-| `:fact` | 7.0-10.0 | User identity, system facts |
-| `:decision` | 7.0-10.0 | Architecture, major choices |
-| `:preference` | 4.0-8.0 | User preferences |
-| `:code` | 4.0-7.0 | Code snippets, examples |
-| `:context` | 3.0-6.0 | Conversation state |
-| `:question` | 5.0-8.0 | Open questions |
+# Technology tags
+tags: ["tech:ruby", "tech:javascript", "tech:docker"]
 
-!!! warning "Importance Affects Eviction"
-    When working memory is full, HTM evicts memories with lower importance first. Set importance thoughtfully based on long-term value.
+# Project tags
+tags: ["project:alpha", "project:beta"]
+```
 
-## Adding Relationships
+### Automatic Tag Extraction
 
-Link related memories to build a knowledge graph:
+When a node is created, a background job (GenerateTagsJob) automatically extracts hierarchical tags from the content using an LLM. This happens asynchronously.
 
 ```ruby
-# Add a decision
-htm.add_node(
-  "decision_database",
-  "Use PostgreSQL for data storage",
-  type: :decision,
-  importance: 9.0
-)
-
-# Add related implementation code
-htm.add_node(
-  "code_db_connection",
-  "PG.connect(ENV['DATABASE_URL'])",
-  type: :code,
-  importance: 6.0,
-  related_to: ["decision_database"]
-)
-
-# Add related configuration
-htm.add_node(
-  "fact_db_config",
-  "Database uses connection pool of size 5",
-  type: :fact,
-  importance: 7.0,
-  related_to: ["decision_database", "code_db_connection"]
-)
+# Just provide content, tags are auto-extracted
+htm.remember("We're using Redis for session caching with a 24-hour TTL")
+# Background job might extract: ["database:redis", "caching:session", "performance"]
 ```
 
-!!! tip "Relationship Patterns"
-    - Link implementation code to decisions
-    - Connect questions to related facts
-    - Link preferences to user facts
-    - Connect related decisions (e.g., database choice → ORM choice)
+## Using Metadata
 
-## Categorization with Tags
+Metadata provides flexible key-value storage for arbitrary data that doesn't fit into tags. Unlike tags (which are for hierarchical categorization), metadata is for structured data like version numbers, priorities, source systems, or any custom attributes.
 
-Tags enable flexible organization and retrieval:
+### Basic Metadata Usage
 
 ```ruby
-# Use multiple tags for rich categorization
-htm.add_node(
-  "decision_api_design",
-  "RESTful API with JSON responses",
-  type: :decision,
-  importance: 8.0,
-  tags: [
-    "api",           # Domain
-    "rest",          # Approach
-    "architecture",  # Category
-    "backend",       # Layer
-    "json",          # Format
-    "http"           # Protocol
-  ]
+# Store with metadata
+htm.remember(
+  "User prefers dark mode",
+  metadata: { category: "preference", priority: "high" }
+)
+
+# Multiple metadata fields
+htm.remember(
+  "API endpoint changed from /v1 to /v2",
+  metadata: {
+    category: "migration",
+    version: 2,
+    breaking_change: true,
+    affected_services: ["web", "mobile"]
+  }
 )
 ```
 
-### Tag Naming Conventions
+### Metadata vs Tags
 
-```ruby
-# Good: Consistent, lowercase, descriptive
-tags: ["user", "authentication", "security", "oauth"]
+| Feature | Tags | Metadata |
+|---------|------|----------|
+| Structure | Hierarchical (colon-separated) | Flat key-value pairs |
+| Type | String only | Any JSON type (string, number, boolean, array, object) |
+| Search | Prefix matching (`LIKE 'ai:%'`) | JSONB containment (`@>`) |
+| Purpose | Categorization & navigation | Arbitrary attributes & filtering |
+| Auto-extraction | Yes (via LLM) | No (always explicit) |
 
-# Avoid: Inconsistent casing, vague terms
-tags: ["User", "auth", "stuff", "misc"]
-```
-
-### Common Tag Patterns
+### Common Metadata Patterns
 
 ```ruby
-# Domain tags
-tags: ["database", "api", "ui", "auth", "billing"]
+# Version tracking
+htm.remember("API uses OAuth 2.0", metadata: { version: 3, deprecated: false })
 
-# Layer tags
-tags: ["frontend", "backend", "infrastructure", "data"]
+# Source tracking
+htm.remember("Error rate is 0.1%", metadata: { source: "monitoring", dashboard: "errors" })
 
-# Status tags
-tags: ["active", "deprecated", "experimental", "stable"]
+# Priority/importance
+htm.remember("Deploy to prod on Fridays is forbidden", metadata: { priority: "critical" })
 
-# Priority tags
-tags: ["critical", "high-priority", "low-priority"]
+# Environment-specific
+htm.remember("Database connection limit is 100", metadata: { environment: "production" })
 
-# Project tags
-tags: ["project-alpha", "project-beta"]
+# Combining with tags
+htm.remember(
+  "Use connection pooling for better performance",
+  tags: ["database:postgresql", "performance"],
+  metadata: { priority: "high", reviewed: true, author: "dba-team" }
+)
 ```
 
-## Advanced Patterns
+### Querying by Metadata
 
-### Timestamped Entries
-
-Create time-series logs:
+Use the `metadata` parameter in `recall()` to filter by metadata:
 
 ```ruby
-def log_event(event_type, description)
-  timestamp = Time.now.to_i
-
-  htm.add_node(
-    "event_#{event_type}_#{timestamp}",
-    "#{event_type.upcase}: #{description}",
-    type: :context,
-    importance: 5.0,
-    tags: ["event", event_type, "log"]
-  )
-end
+# Find all high-priority items
+htm.recall("settings", metadata: { priority: "high" })
 
-log_event("error", "Database connection timeout")
-log_event("performance", "Query took 3.2 seconds")
-```
+# Find production-specific configurations
+htm.recall("database", metadata: { environment: "production" })
 
-### Versioned Information
+# Combine with other filters
+htm.recall(
+  "API changes",
+  timeframe: "last month",
+  metadata: { breaking_change: true },
+  strategy: :hybrid
+)
+```
 
-Track changes over time:
+Metadata filtering uses PostgreSQL's JSONB containment operator (`@>`), which means the node's metadata must contain all the key-value pairs you specify.
 
-```ruby
-def update_fact(base_key, new_value, version)
-  # Add versioned node
-  htm.add_node(
-    "#{base_key}_v#{version}",
-    new_value,
-    type: :fact,
-    importance: 8.0,
-    tags: ["versioned", "v#{version}"],
-    related_to: version > 1 ? ["#{base_key}_v#{version-1}"] : []
-  )
-end
+## Content Deduplication
 
-update_fact("user_email", "alice@example.com", 1)
-update_fact("user_email", "alice@newdomain.com", 2)
-```
+HTM automatically deduplicates content across all robots using SHA-256 hashing.
 
-### Compound Memories
-
-Store structured information:
+### How It Works
 
 ```ruby
-# User profile as compound memory
-user_profile = {
-  name: "Alice Thompson",
-  email: "alice@example.com",
-  role: "Senior Engineer",
-  joined: "2023-01-15"
-}.map { |k, v| "#{k}: #{v}" }.join("\n")
-
-htm.add_node(
-  "user_profile_001",
-  user_profile,
-  type: :fact,
-  importance: 9.0,
-  tags: ["user", "profile", "complete"]
-)
+# Robot 1 remembers something
+robot1 = HTM.new(robot_name: "assistant_1")
+node_id = robot1.remember("Ruby 3.3 supports YJIT by default")
+# => 123 (new node)
+
+# Robot 2 remembers the same thing
+robot2 = HTM.new(robot_name: "assistant_2")
+node_id = robot2.remember("Ruby 3.3 supports YJIT by default")
+# => 123 (same node_id! Content matched by hash)
 ```
 
-### Conditional Importance
+### Robot-Node Association
 
-Adjust importance based on context:
+Each robot-node relationship is tracked in `robot_nodes`:
 
 ```ruby
-def add_memory_with_context(key, value, type, base_importance, current_project)
-  # Boost importance for current project
-  importance = base_importance
-  importance += 2.0 if tags.include?(current_project)
-  importance = [importance, 10.0].min  # Cap at 10.0
-
-  htm.add_node(
-    key,
-    value,
-    type: type,
-    importance: importance,
-    tags: [current_project, type.to_s]
-  )
-end
+# Check how many times a robot has "remembered" content
+rn = HTM::Models::RobotNode.find_by(robot_id: htm.robot_id, node_id: node_id)
+rn.remember_count      # => 3 (remembered 3 times)
+rn.first_remembered_at # => When first encountered
+rn.last_remembered_at  # => When last tried to remember
 ```
 
 ## Best Practices
 
-### 1. Use Descriptive Keys
-
-```ruby
-# Good: Descriptive and namespaced
-"user_profile_alice_001"
-"decision_database_selection"
-"code_authentication_jwt"
-
-# Bad: Vague or collision-prone
-"profile"
-"dec1"
-"code"
-```
-
-### 2. Be Consistent with Categories
+### 1. Make Content Self-Contained
 
 ```ruby
-# Define standard categories
-CATEGORIES = {
-  architecture: "architecture",
-  security: "security",
-  performance: "performance",
-  ui: "user-interface"
-}
-
-htm.add_node(
-  key, value,
-  category: CATEGORIES[:architecture]
+# Good: Self-contained, understandable without context
+htm.remember(
+  "Decided to use Redis for session storage because it provides fast access and automatic expiration"
 )
+
+# Bad: Requires external context
+htm.remember("Use Redis")  # Why? For what?
 ```
 
-### 3. Include Context in Values
+### 2. Include Rich Context
 
 ```ruby
-# Good: Self-contained
-htm.add_node(
-  "decision_001",
-  "Decided to use Redis for session storage because it provides fast access and automatic expiration",
-  type: :decision
-)
-
-# Bad: Requires external context
-htm.add_node(
-  "decision_001",
-  "Use Redis",  # Why? For what?
-  type: :decision
-)
+# Good: Includes rationale and alternatives
+htm.remember(<<~DECISION)
+  Decision: Use OAuth 2.0 for authentication
+
+  Rationale:
+  - Industry standard
+  - Better security than basic auth
+  - Supports SSO
+
+  Alternatives considered:
+  - Basic auth (rejected: security concerns)
+  - Custom tokens (rejected: maintenance burden)
+DECISION
 ```
 
-### 4. Tag Generously
+### 3. Use Hierarchical Tags
 
 ```ruby
 # Good: Rich tags for multiple retrieval paths
-htm.add_node(
-  "code_api_auth",
-  "...",
-  tags: ["api", "authentication", "security", "jwt", "middleware", "ruby"]
+htm.remember(
+  "JWT tokens are stateless authentication tokens",
+  tags: ["auth:jwt", "security:tokens", "architecture:stateless"]
 )
 
-# Suboptimal: Minimal tags
-htm.add_node(
-  "code_api_auth",
-  "...",
-  tags: ["code"]
-)
+# Suboptimal: Flat or minimal tags
+htm.remember("JWT info", tags: ["jwt"])
 ```
 
-### 5. Use Relationships to Build Context
+### 4. Keep Content Focused
 
 ```ruby
-# Create a narrative with relationships
-decision_id = htm.add_node("decision_api", "Use GraphQL", type: :decision)
-
-htm.add_node(
-  "question_api",
-  "How to handle file uploads in GraphQL?",
-  type: :question,
-  related_to: ["decision_api"]
-)
+# Good: One concept per memory
+htm.remember("PostgreSQL's EXPLAIN ANALYZE shows actual execution times")
+htm.remember("PostgreSQL's EXPLAIN shows the query plan without executing")
 
-htm.add_node(
-  "code_upload",
-  "GraphQL upload implementation",
-  type: :code,
-  related_to: ["decision_api", "question_api"]
-)
+# Suboptimal: Multiple unrelated concepts
+htm.remember("PostgreSQL has EXPLAIN and also supports JSON and has good performance")
 ```
 
-## Common Pitfalls
-
-### Pitfall 1: Duplicate Keys
+## Async Processing
 
-```ruby
-# This will fail - keys must be unique
-htm.add_node("user_001", "Alice")
-htm.add_node("user_001", "Bob")  # Error: key already exists
-```
+Embedding generation and tag extraction happen asynchronously:
 
-**Solution**: Use unique keys with timestamps or UUIDs:
+### Workflow
 
 ```ruby
-require 'securerandom'
+# 1. Node created immediately (~15ms)
+node_id = htm.remember("Important fact about databases")
+# Returns immediately with node_id
 
-htm.add_node("user_#{SecureRandom.hex(4)}", "Alice")
-htm.add_node("user_#{SecureRandom.hex(4)}", "Bob")
+# 2. Background jobs enqueue (async)
+# - GenerateEmbeddingJob runs (~100ms)
+# - GenerateTagsJob runs (~1 second)
+
+# 3. Node is eventually enriched
+# - embedding field populated (enables vector search)
+# - tags associated (enables tag navigation and boosting)
 ```
 
-### Pitfall 2: Too-High Importance
+### Immediate vs Eventual Capabilities
 
-```ruby
-# Don't make everything critical
-htm.add_node("note", "Random thought", importance: 10.0)  # Too high!
-```
+| Capability | Available | Notes |
+|------------|-----------|-------|
+| Full-text search | Immediately | Works on content |
+| Basic retrieval | Immediately | By node ID |
+| Vector search | After ~100ms | Needs embedding |
+| Tag-enhanced search | After ~1s | Needs tags |
+| Hybrid search | After ~1s | Needs embedding + tags |
 
-**Solution**: Reserve high importance (9-10) for truly critical data.
+## Working Memory Integration
 
-### Pitfall 3: Missing Context
+When you `remember()`, the node is automatically added to working memory:
 
 ```ruby
-# Bad: No context
-htm.add_node("decision", "Chose option A", type: :decision)
-
-# Good: Include rationale
-htm.add_node(
-  "decision_auth",
-  "Chose OAuth 2.0 for authentication because it provides better security and is industry standard",
-  type: :decision
-)
+# Remember adds to both LTM and WM
+htm.remember("Important fact")
+
+# Check working memory
+stats = htm.working_memory.stats
+puts "Nodes in WM: #{stats[:node_count]}"
+puts "Token usage: #{stats[:utilization]}%"
 ```
 
-### Pitfall 4: No Tags
+### Eviction
+
+If working memory is full, older/less important nodes are evicted to make room:
 
 ```ruby
-# Harder to find later
-htm.add_node("code_001", "def foo...", type: :code)
-
-# Better: Tags enable multiple retrieval paths
-htm.add_node(
-  "code_001",
-  "def foo...",
-  type: :code,
-  tags: ["ruby", "functions", "utilities"]
-)
+# Working memory has a token budget
+htm = HTM.new(working_memory_size: 128_000)  # 128K tokens
+
+# As you remember more, older items may be evicted from WM
+# They remain in LTM and can be recalled later
 ```
 
 ## Performance Considerations
 
 ### Batch Operations
 
-When adding many memories, consider transaction efficiency:
+Each `remember()` call is a database operation. For bulk inserts:
 
 ```ruby
-# Instead of many individual adds
-memories = [
-  {key: "fact_001", value: "...", type: :fact},
-  {key: "fact_002", value: "...", type: :fact},
-  # ... many more
+# Multiple memories
+facts = [
+  "PostgreSQL supports JSONB",
+  "PostgreSQL has excellent indexing",
+  "PostgreSQL handles concurrent writes well"
 ]
 
-# Add them efficiently
-memories.each do |m|
-  htm.add_node(m[:key], m[:value], type: m[:type], importance: m[:importance])
+facts.each do |fact|
+  htm.remember(fact)
 end
 ```
 
-!!! note
-    Each `add_node` call generates embeddings via Ollama. For large batches, this can take time. Consider adding in the background or showing progress.
-
-### Embedding Generation
+### Content Length
 
-Embedding generation has a cost:
+Longer content takes more time to process:
 
 ```ruby
-# Short text: Fast (~50ms)
-htm.add_node("fact", "User name is Alice", ...)
+# Short text: Fast (~15ms save, ~100ms embedding)
+htm.remember("User name is Alice")
 
-# Long text: Slower (~500ms)
-htm.add_node("code", "..." * 1000, ...)  # 1000 chars
+# Long text: Slower (~15ms save, ~500ms embedding)
+htm.remember("..." * 1000)  # 1000 chars
 ```
 
-!!! tip
-    For very long content (>1000 tokens), consider splitting into multiple nodes or summarizing.
+For very long content (>1000 tokens), consider splitting into multiple memories.
 
 ## Next Steps
 
 Now that you know how to add memories effectively, learn about:
 
-- [**Recalling Memories**](recalling-memories.md) - Search and retrieve memories
 - [**Search Strategies**](search-strategies.md) - Optimize retrieval with different strategies
-- [**Context Assembly**](context-assembly.md) - Use memories with your LLM
+- [**Recalling Memories**](recalling-memories.md) - Search and retrieve memories
 
 ## Complete Example
 
@@ -750,75 +431,46 @@ require 'htm'
 
 htm = HTM.new(robot_name: "Memory Demo")
 
-# Add a fact with rich metadata
-htm.add_node(
-  "user_profile",
-  "Alice Thompson is a senior software engineer specializing in distributed systems",
-  type: :fact,
-  category: "user",
-  importance: 9.0,
-  tags: ["user", "profile", "engineering"]
+# Add a fact
+htm.remember(
+  "Alice Thompson is a senior software engineer specializing in distributed systems"
 )
 
-# Add a related preference
-htm.add_node(
-  "user_pref_tools",
+# Add a preference with metadata
+htm.remember(
   "Alice prefers Vim for editing and tmux for terminal management",
-  type: :preference,
-  importance: 7.0,
-  tags: ["user", "tools", "preferences"],
-  related_to: ["user_profile"]
+  metadata: { category: "preference", source: "user-interview" }
 )
 
-# Add a decision with context
-htm.add_node(
-  "decision_messaging",
-  <<~DECISION,
-    Decision: Use RabbitMQ for async job processing
-
-    Rationale:
-    - Need reliable message delivery
-    - Support for multiple consumer patterns
-    - Excellent Ruby client library
-
-    Alternatives:
-    - Redis (simpler but less reliable)
-    - Kafka (overkill for our scale)
-  DECISION
-  type: :decision,
-  category: "architecture",
-  importance: 8.5,
-  tags: ["architecture", "messaging", "rabbitmq", "async"]
-)
+# Add a decision with context, tags, and metadata
+htm.remember(<<~DECISION, tags: ["architecture", "messaging"], metadata: { priority: "high", approved: true, version: 1 })
+  Decision: Use RabbitMQ for async job processing
 
-# Add implementation code
-htm.add_node(
-  "code_rabbitmq_setup",
-  <<~RUBY,
-    require 'bunny'
-
-    connection = Bunny.new(ENV['RABBITMQ_URL'])
-    connection.start
-
-    channel = connection.create_channel
-    queue = channel.queue('jobs', durable: true)
-  RUBY
-  type: :code,
-  importance: 6.0,
-  tags: ["ruby", "rabbitmq", "setup", "code"],
-  related_to: ["decision_messaging"]
-)
+  Rationale:
+  - Need reliable message delivery
+  - Support for multiple consumer patterns
+  - Excellent Ruby client library
 
-# Add an open question
-htm.add_node(
-  "question_scaling",
-  "Should we implement message partitioning for better scaling?",
-  type: :question,
-  importance: 7.0,
-  tags: ["rabbitmq", "scaling", "performance", "open"],
-  related_to: ["decision_messaging"]
-)
+  Alternatives:
+  - Redis (simpler but less reliable)
+  - Kafka (overkill for our scale)
+DECISION
+
+# Add implementation code with metadata
+htm.remember(<<~RUBY, tags: ["code:ruby", "messaging:rabbitmq"], metadata: { language: "ruby", tested: true })
+  require 'bunny'
+
+  connection = Bunny.new(ENV['RABBITMQ_URL'])
+  connection.start
+
+  channel = connection.create_channel
+  queue = channel.queue('jobs', durable: true)
+RUBY
+
+puts "Added memories with relationships and rich metadata"
+puts "Stats: #{HTM::Models::Node.count} total nodes"
 
-puts "Added 5 memories with relationships and rich metadata"
-puts "Stats: #{htm.memory_stats[:total_nodes]} total nodes"
+# Query by metadata
+high_priority = htm.recall("decisions", metadata: { priority: "high" })
+puts "High priority decisions: #{high_priority.count}"
 ```