htm 0.0.31 → 0.0.32

data/docs/database_rake_tasks.md

@@ -19,24 +19,22 @@ rake htm:db:setup            # Create schema and run migrations
 Sets up the HTM database schema and runs all migrations.
 
 **What it does:**
-- Verifies required extensions (timescaledb, pgvector, pg_trgm)
-- Creates all HTM tables (nodes, tags, robots, operations_log)
+- Verifies required extensions (pgvector, pg_trgm)
+- Creates all HTM tables (nodes, tags, robots, file_sources)
 - Runs all pending migrations
-- Sets up hypertables for time-series optimization
 
 **When to use:** First-time setup or after dropping the database
 
 ```bash
 $ rake htm:db:setup
-✓ TimescaleDB version: 2.22.1
-✓ pgvector version: 0.8.1
+✓ pgvector version: 0.8.1+
+✓ pg_trgm version: 1.6
 Creating HTM schema...
 ✓ Schema created
 Running migration: 001_support_variable_dimensions
   ✓ Migration 001_support_variable_dimensions applied
 Running migration: 002_ontology_topic_extraction
   ✓ Migration 002_ontology_topic_extraction applied
-✓ Created hypertable for operations_log
 ✓ HTM database schema created successfully
 ```
 
@@ -92,29 +90,24 @@ HTM Database Information
 ================================================================================
 
 Connection:
-  Host: cw7rxj91bm.srbbwwxn56.tsdb.cloud.timescale.com
-  Port: 37807
-  Database: tsdb
-  User: tsdbadmin
+  Host: localhost
+  Port: 5432
+  Database: htm_development
+  User: postgres
 
 PostgreSQL Version:
-  PostgreSQL 17.6 (Ubuntu 17.6-2.pgdg22.04+1) on aarch64-unknown-linux-gnu
+  PostgreSQL 17.x
 
 Extensions:
-  ai (0.11.2)
-  pg_stat_statements (1.11)
   pg_trgm (1.6)
   plpgsql (1.0)
-  timescaledb (2.22.1)
-  timescaledb_toolkit (1.21.0)
-  vector (0.8.1)
-  vectorscale (0.8.0)
+  vector (0.8.1+)
 
 HTM Tables:
   nodes: 42 rows
   tags: 156 rows
   robots: 3 rows
-  operations_log: 289 rows
+  file_sources: 5 rows
   schema_migrations: 2 rows
 
 Database Size: 14 MB
@@ -127,10 +120,9 @@ Tests database connection by running `test_connection.rb`.
 **Example output:**
 ```bash
 $ rake htm:db:test
-Connecting to TimescaleDB...
+Connecting to PostgreSQL...
 ✓ Connected successfully!
-✓ TimescaleDB Extension: Version 2.22.1
-✓ pgvector Extension: Version 0.8.1
+✓ pgvector Extension: Version 0.8.1+
 ✓ pg_trgm Extension: Version 1.6
 ```
 
@@ -153,14 +145,14 @@ psql (17.6)
 SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)
 Type "help" for help.
 
-tsdb=> SELECT COUNT(*) FROM nodes;
+htm_development=> SELECT COUNT(*) FROM nodes;
  count
 -------
     42
 (1 row)
 
-tsdb=> \d nodes
-tsdb=> \q
+htm_development=> \d nodes
+htm_development=> \q
 ```
 
 #### `rake htm:db:seed`
@@ -272,9 +264,9 @@ export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=re
 rake htm:db:info
 ```
 
-### Method 3: Source Tiger Credentials
+### Method 3: Source Credentials File
 ```bash
-source ~/.bashrc__tiger    # If using TimescaleDB Cloud
+source ~/.envrc    # Load environment from credentials file
 rake htm:db:info
 ```
 
@@ -333,9 +325,9 @@ rake htm:db:migrate       # Run new migrations only
 - Test: `rake htm:db:test`
 
 ### "Extension not found"
-- Ensure TimescaleDB Cloud instance has required extensions
+- Enable required extensions manually: `psql $HTM_DATABASE__URL -c "CREATE EXTENSION IF NOT EXISTS vector;"`
 - Check with: `rake htm:db:info`
-- Extensions needed: timescaledb, pgvector, pg_trgm
+- Extensions needed: pgvector, pg_trgm
 
 ### Migrations not running
 - Check migration files exist: `ls -la sql/migrations/`

data/docs/development/contributing.md

@@ -252,11 +252,11 @@ git commit -m "wip"
 For more complex changes, include a body:
 
 ```bash
-git commit -m "feat: add compression policy for old memories
+git commit -m "feat: add partial index for active memories
+
+Implements partial index for active (non-deleted) memories to improve
+query performance. This reduces index size and speeds up reads.
 
-Implements automatic compression for memories older than 30 days
-using TimescaleDB compression policies. This reduces storage costs
-and improves query performance for recent data.
 
 - Adds compress_old_memories rake task
 - Updates schema with compression settings
@@ -672,7 +672,7 @@ HTM's hybrid search combines vector similarity search with full-text search for
 
 ```ruby
 memories = htm.recall(
-  topic: "database decisions",
+  "database decisions",
   strategy: :hybrid,
   timeframe: "last week"
 )

data/docs/development/index.md

@@ -25,7 +25,7 @@ Learn how to set up your development environment, clone the repository, install
 
 - Cloning the repository
 - Installing Ruby and dependencies
-- Setting up TimescaleDB for development
+- Setting up PostgreSQL for development
 - Configuring Ollama for embeddings
 - Running tests and examples
 - Development tools and rake tasks
@@ -73,7 +73,7 @@ Complete reference for all 44 HTM rake tasks covering database management, docum
 - Troubleshooting guide
 
 ### [Database Schema](schema.md)
-Deep dive into HTM's database architecture, tables, indexes, and TimescaleDB optimization strategies.
+Deep dive into HTM's database architecture, tables, indexes, and PostgreSQL optimization strategies.
 
 **Topics covered:**
 
@@ -82,8 +82,6 @@ Deep dive into HTM's database architecture, tables, indexes, and TimescaleDB opt
 - Table definitions and column details
 - Indexes and constraints
 - Views and functions
-- TimescaleDB hypertables
-- Compression policies
 - Migration strategies
 
 ## Quick Start for Contributors
@@ -202,7 +200,7 @@ A: Check out issues labeled `good-first-issue` on GitHub. These are specifically
 
 **Q: How do I run tests without a database?**
 
-A: Unit tests (like `test/htm_test.rb`) don't require a database. Integration tests require TimescaleDB. See the [Testing Guide](testing.md) for details.
+A: Unit tests (like `test/htm_test.rb`) don't require a database. Integration tests require PostgreSQL with pgvector. See the [Testing Guide](testing.md) for details.
 
 **Q: What's the preferred debugging approach?**
 
@@ -277,8 +275,7 @@ HTM is built with modern Ruby tools:
 ### Core Technologies
 
 - **Ruby 3.0+**: Modern Ruby with pattern matching and better performance
-- **PostgreSQL 17**: Robust relational database
-- **TimescaleDB**: Time-series optimization for PostgreSQL
+- **PostgreSQL 17**: Robust relational database with pgvector and pg_trgm
 - **pgvector**: Vector similarity search
 - **RubyLLM**: LLM client library for embeddings
 - **Ollama**: Local embedding generation

data/docs/development/schema.md

@@ -45,6 +45,7 @@ For detailed table definitions, columns, indexes, and constraints, see the auto-
 |-------|-------------|---------|
 | [robot_nodes](../database/public.robot_nodes.md) | Links robots to nodes (many-to-many) | Enables "hive mind" shared memory; includes `working_memory` boolean for per-robot working memory state |
 | [node_tags](../database/public.node_tags.md) | Links nodes to tags (many-to-many) | Flexible multi-tag categorization |
+| node_relationships | Weighted directed edges between related nodes | Stores Jaccard-similarity edges in both directions (A→B and B→A) for CTE graph traversal; populated by `GenerateRelationshipsJob` |
 
 ### System Tables
 
@@ -141,6 +142,40 @@ WHERE fs.file_path = '/path/to/file.md'
 ORDER BY n.chunk_position;
 ```
 
+### Node Relationships (Graph Edges)
+
+The `node_relationships` table stores weighted directed edges between nodes. Edges are created automatically by `GenerateRelationshipsJob` after tags are assigned.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | bigint | Primary key |
+| `source_id` | bigint | FK → nodes.id (ON DELETE CASCADE) |
+| `target_id` | bigint | FK → nodes.id (ON DELETE CASCADE) |
+| `rel_type` | varchar | Edge type: `related_to`, `supports`, `contradicts`, `derived_from` |
+| `origin` | varchar | How the edge was created: `tag_cooccurrence`, `tag_hierarchy`, `explicit` |
+| `weight` | float | Jaccard similarity score [0.0 – 1.0] |
+| `created_at` | timestamptz | When edge was first created |
+| `updated_at` | timestamptz | When edge weight was last refreshed |
+
+**Design principles:**
+- Both directions stored explicitly (A→B and B→A) so traversal only needs `WHERE source_id IN (seeds)` — no OR across columns
+- Unique constraint on `(source_id, target_id, rel_type)` — re-running the job refreshes weights via upsert
+- Self-loops rejected by a DB CHECK constraint
+- Edges with Jaccard weight < 0.1 are skipped; at most 50 edges per source node
+
+**Ruby model:** `HTM::Models::NodeRelationship`
+
+```ruby
+# Direct neighbors by weight
+HTM::Models::NodeRelationship.neighbors_of(node_id).limit(10).all
+
+# Edges above a threshold
+HTM::Models::NodeRelationship.above_weight(0.5).where(source_id: node_id).all
+
+# Edges of a specific type
+HTM::Models::NodeRelationship.by_rel_type('related_to').where(source_id: node_id).all
+```
+
 ### Remember Tracking
 
 The `robot_nodes` table tracks per-robot remember metadata:
@@ -221,6 +256,38 @@ WHERE t.name LIKE 'ai:llm:%'
 ORDER BY n.created_at DESC;
 ```
 
+### Finding Related Nodes via Relationship Graph
+
+```sql
+-- Direct neighbors (1 hop), ordered by Jaccard weight
+SELECT nr.target_id, nr.weight, n.content
+FROM node_relationships nr
+JOIN nodes n ON n.id = nr.target_id
+WHERE nr.source_id = $1
+  AND nr.rel_type = 'related_to'
+ORDER BY nr.weight DESC
+LIMIT 10;
+
+-- Two-hop traversal using a recursive CTE
+WITH RECURSIVE graph AS (
+  SELECT target_id, weight, 1 AS depth
+  FROM node_relationships
+  WHERE source_id = $1
+    AND rel_type = 'related_to'
+    AND weight >= 0.1
+  UNION ALL
+  SELECT nr.target_id, nr.weight * g.weight, g.depth + 1
+  FROM node_relationships nr
+  JOIN graph g ON g.target_id = nr.source_id
+  WHERE g.depth < 2
+    AND nr.rel_type = 'related_to'
+    AND nr.weight >= 0.1
+)
+SELECT DISTINCT ON (target_id) target_id, weight
+FROM graph
+ORDER BY target_id, weight DESC;
+```
+
 ### Finding Related Topics by Shared Nodes
 
 ```sql
@@ -336,13 +403,15 @@ REINDEX INDEX CONCURRENTLY idx_nodes_content_gin;
 
 ## Schema Migration
 
-The schema is managed through ActiveRecord migrations located in `db/migrate/`:
+The schema is managed through Sequel migrations located in `db/migrate/`:
 
 1. `20250101000001_create_robots.rb` - Creates robots table
 2. `20250101000002_create_nodes.rb` - Creates nodes table with all indexes
 3. `20250101000005_create_tags.rb` - Creates tags and nodes_tags tables
 4. `20251128000002_create_file_sources.rb` - Creates file_sources table for document tracking
 5. `20251128000003_add_source_to_nodes.rb` - Adds source_id and chunk_position to nodes
+6. `00008_create_node_relationships.rb` - Creates node_relationships table with FK constraints and weight check
+7. `00009_fix_node_relationships_column_types.rb` - Promotes id to bigint and timestamps to timestamptz
 
 To apply migrations:
 ```bash
@@ -412,6 +481,7 @@ SELECT content ILIKE '%pattern%' FROM nodes;          -- Pattern matching (uses
 2. **Full-text search**: Best for keyword matching ("documents containing Y")
 3. **Fuzzy search**: Best for typo tolerance and pattern matching
 4. **Hybrid search**: Combine vector + full-text with weighted scores
+5. **Graph traversal**: Follow `node_relationships` edges via CTE for association-based retrieval
 
 ### Performance Tuning
 

data/docs/development/setup.md

@@ -9,7 +9,7 @@ Setting up HTM for development involves:
 1. Cloning the repository
 2. Installing Ruby and system dependencies
 3. Installing Ruby gem dependencies
-4. Setting up TimescaleDB database
+4. Setting up PostgreSQL database
 5. Configuring an LLM provider (Ollama, OpenAI, etc.)
 6. Verifying your setup
 7. Running tests and examples
@@ -154,96 +154,57 @@ bundle exec ruby -e "require 'htm'; puts HTM::VERSION"
 # Should output: 0.1.0 (or current version)
 ```
 
-## Step 4: Set Up TimescaleDB Database
+## Step 4: Set Up PostgreSQL Database
 
-HTM requires PostgreSQL with TimescaleDB and pgvector extensions. You have two options:
+HTM requires PostgreSQL 16+ with pgvector and pg_trgm extensions. You have two options:
 
-### Option A: TimescaleDB Cloud (Recommended for Quick Start)
-
-This is the fastest way to get a working database:
-
-#### 1. Create Account
-
-Visit [https://www.timescale.com/](https://www.timescale.com/) and sign up for a free account.
-
-#### 2. Create Service
-
-- Click "Create Service"
-- Select your region (choose closest to you)
-- Choose the **Free Tier** (or your preferred plan)
-- Click "Create Service"
-- Wait 2-3 minutes for provisioning
-
-#### 3. Get Connection Details
-
-- Click on your new service
-- Click "Connection Info"
-- Copy the full connection string (looks like `postgres://username:password@host:port/database?sslmode=require`)
-
-#### 4. Configure Environment Variables
-
-Create or edit `~/.bashrc__tiger`:
+### Option A: Local PostgreSQL (macOS/Homebrew)
 
 ```bash
-# TimescaleDB Connection Configuration
-export HTM_SERVICE_NAME="db-67977"  # Your service name
-export HTM_DATABASE__NAME="tsdb"
-export HTM_DATABASE__USER="tsdbadmin"
-export HTM_DATABASE__PASSWORD="your_password_here"
-export HTM_DATABASE__PORT="37807"  # Your port number
-export HTM_DATABASE__URL="postgres://tsdbadmin:your_password@host:port/tsdb?sslmode=require"
-```
+# Install PostgreSQL 17
+brew install postgresql@17
+brew services start postgresql@17
 
-Replace the placeholders with your actual connection details.
+# Create development database
+createdb htm_development
 
-#### 5. Load Environment Variables
+# Enable required extensions
+psql htm_development -c "CREATE EXTENSION IF NOT EXISTS vector;"
+psql htm_development -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
 
-```bash
-# Load configuration
-source ~/.bashrc__tiger
-
-# Optionally, add to your ~/.bashrc for automatic loading
-echo 'source ~/.bashrc__tiger' >> ~/.bashrc
+# Configure environment variables
+export HTM_DATABASE__URL="postgresql://$(whoami)@localhost:5432/htm_development"
 ```
 
-### Option B: Local PostgreSQL with Docker (Advanced)
+### Option B: Local PostgreSQL with Docker
 
-For local development with Docker:
+For Docker-based development:
 
 ```bash
 # Create docker-compose.yml
 cat > docker-compose.yml <<'EOF'
 version: '3.8'
 services:
-  timescaledb:
-    image: timescale/timescaledb-ha:pg17
+  postgres:
+    image: pgvector/pgvector:pg17
     environment:
-      POSTGRES_USER: tsdbadmin
+      POSTGRES_USER: htm
       POSTGRES_PASSWORD: devpassword
-      POSTGRES_DB: tsdb
+      POSTGRES_DB: htm_development
     ports:
       - "5432:5432"
     volumes:
-      - timescale_data:/var/lib/postgresql/data
+      - pg_data:/var/lib/postgresql/data
 
 volumes:
-  timescale_data:
+  pg_data:
 EOF
 
-# Start TimescaleDB
+# Start PostgreSQL
 docker-compose up -d
 
 # Configure environment variables
-cat > ~/.bashrc__tiger <<'EOF'
-export HTM_SERVICE_NAME="local-dev"
-export HTM_DATABASE__NAME="tsdb"
-export HTM_DATABASE__USER="tsdbadmin"
-export HTM_DATABASE__PASSWORD="devpassword"
-export HTM_DATABASE__PORT="5432"
-export HTM_DATABASE__URL="postgres://tsdbadmin:devpassword@localhost:5432/tsdb?sslmode=disable"
-EOF
-
-source ~/.bashrc__tiger
+export HTM_DATABASE__URL="postgresql://htm:devpassword@localhost:5432/htm_development"
 ```
 
 ### Verify Database Connection
@@ -252,27 +213,26 @@ Test your database connection:
 
 ```bash
 # From the htm directory
-ruby test_connection.rb
+rake htm:db:verify
 ```
 
 Expected output:
 
 ```
 Connected successfully!
-TimescaleDB Extension: Version 2.22.1
-pgvector Extension: Version 0.8.1
+pgvector Extension: Version 0.8.0+
 pg_trgm Extension: Version 1.6
 ```
 
 ### Enable Required Extensions
 
-Run the extension setup script:
+Run the extension setup script if needed:
 
 ```bash
 ruby enable_extensions.rb
 ```
 
-This ensures that TimescaleDB, pgvector, and pg_trgm extensions are enabled.
+This ensures that pgvector and pg_trgm extensions are enabled.
 
 ## Step 5: Configure LLM Provider
 
@@ -495,12 +455,12 @@ HTM uses environment variables for configuration. Here's a complete reference:
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) | `postgres://user:pass@host:port/db?sslmode=require` |
-| `HTM_DATABASE__NAME` | Database name | `tsdb` |
-| `HTM_DATABASE__USER` | Database username | `tsdbadmin` |
+| `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) | `postgresql://user:pass@localhost:5432/htm_development` |
+| `HTM_DATABASE__NAME` | Database name | `htm_development` |
+| `HTM_DATABASE__USER` | Database username | `postgres` |
 | `HTM_DATABASE__PASSWORD` | Database password | `your_password` |
-| `HTM_DATABASE__PORT` | Database port | `37807` |
-| `HTM_SERVICE_NAME` | Service identifier (informational) | `db-67977` |
+| `HTM_DATABASE__PORT` | Database port | `5432` |
+| `HTM_SERVICE__NAME` | Service identifier (for DB naming) | `htm` |
 
 ### LLM Provider Variables
 
@@ -540,11 +500,8 @@ echo $HTM_DATABASE__URL
 # Test connection directly with psql
 psql $HTM_DATABASE__URL
 
-# Check if service is running (TimescaleDB Cloud)
-# Visit your Timescale Cloud dashboard
-
 # For Docker, check if container is running
-docker ps | grep timescale
+docker ps | grep postgres
 ```
 
 #### "LLM provider connection failed"
@@ -582,7 +539,7 @@ curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
 
 #### "Extension not available"
 
-**Symptoms**: Errors about missing TimescaleDB or pgvector
+**Symptoms**: Errors about missing pgvector or pg_trgm
 
 **Solutions**:
 
@@ -593,8 +550,9 @@ ruby enable_extensions.rb
 # Check extension status
 psql $HTM_DATABASE__URL -c "SELECT extname, extversion FROM pg_extension ORDER BY extname"
 
-# For TimescaleDB Cloud, extensions should be pre-installed
-# For local PostgreSQL, ensure you're using timescale/timescaledb-ha image
+# For local PostgreSQL, install extensions manually:
+psql $HTM_DATABASE__URL -c "CREATE EXTENSION IF NOT EXISTS vector;"
+psql $HTM_DATABASE__URL -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
 ```
 
 #### "Bundle install fails"
@@ -650,8 +608,8 @@ If you see SSL certificate errors:
 echo $HTM_DATABASE__URL | grep sslmode
 # Should show: sslmode=require
 
-# For local development without SSL
-export HTM_DATABASE__URL="postgres://user:pass@localhost:5432/tsdb?sslmode=disable"
+# For local development
+export HTM_DATABASE__URL="postgresql://user:pass@localhost:5432/htm_development"
 ```
 
 ### Ruby Version Issues

data/docs/development/testing.md

@@ -535,7 +535,7 @@ jobs:
 
     services:
       postgres:
-        image: timescale/timescaledb-ha:pg17
+        image: pgvector/pgvector:pg17
         env:
           POSTGRES_PASSWORD: testpass
         options: >-

data/docs/examples/file-loading.md

@@ -125,16 +125,16 @@ puts "Removed #{count} chunks"
 
 ```ruby
 HTM.configure do |config|
-  config.chunk_size = 1024    # Characters per chunk (default)
-  config.chunk_overlap = 64   # Overlap between chunks (default)
+  config.chunking.chunk_size = 1024    # Characters per chunk (default)
+  config.chunking.chunk_overlap = 64   # Overlap between chunks (default)
 end
 ```
 
 Or via environment variables:
 
 ```bash
-export HTM_CHUNK_SIZE=512
-export HTM_CHUNK_OVERLAP=50
+export HTM_CHUNKING__CHUNK_SIZE=512
+export HTM_CHUNKING__CHUNK_OVERLAP=50
 ```
 
 ## Expected Output

data/docs/examples/mcp-client.md

@@ -142,7 +142,7 @@ Assistant> I've stored that information about the PostgreSQL connection string.
 you> What do you know about databases?
 
 [Tool Call] RecallTool
-  Arguments: {topic: "databases", limit: 5}
+  Arguments: {query: "databases", limit: 5}
 [Tool Result] RecallTool
   Result: {"memories": [...]}
 

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

@@ -216,13 +216,13 @@ Look up a memory by its node ID:
 puts "\n4. Looking up specific memory..."
 
 # Use the node_id returned from remember()
-node = HTM::Models::Node.find_by(id: node_id)
+node = HTM::Models::Node.first(id: node_id)
 
 if node
   puts "✓ Found memory:"
   puts "  ID: #{node.id}"
   puts "  Content: #{node.content[0..100]}..."
-  puts "  Tags: #{node.tags.pluck(:name).join(', ')}"
+  puts "  Tags: #{node.tag_names.join(', ')}"
   puts "  Created: #{node.created_at}"
 else
   puts "✗ Memory not found"
@@ -471,8 +471,8 @@ puts HTM::Models::Tag.tree_string
 #       └── postgresql
 #           └── features
 
-# Find all memories under a tag prefix
-nodes = HTM::Models::Tag.find_by(name: 'knowledge:databases')&.nodes
+# Find all memories with a specific tag
+nodes = HTM::Models::Tag.first(name: 'knowledge:databases')&.nodes
 ```
 
 ## Forget (Explicit Deletion)

data/docs/guides/adding-memories.md

@@ -266,7 +266,7 @@ Each robot-node relationship is tracked in `robot_nodes`:
 
 ```ruby
 # 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 = HTM::Models::RobotNode.first(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
@@ -342,12 +342,24 @@ node_id = htm.remember("Important fact about databases")
 # 2. Background jobs enqueue (async)
 # - GenerateEmbeddingJob runs (~100ms)
 # - GenerateTagsJob runs (~1 second)
+# - GenerateRelationshipsJob runs after tags (~1-2 seconds total)
 
 # 3. Node is eventually enriched
 # - embedding field populated (enables vector search)
 # - tags associated (enables tag navigation and boosting)
+# - relationship edges computed (enables graph traversal)
 ```
 
+### Job Chain
+
+The three background jobs run in a chain so each job can depend on prior results:
+
+1. **`GenerateEmbeddingJob`** — generates a vector embedding for the node
+2. **`GenerateTagsJob`** — extracts hierarchical tags using an LLM; on success, enqueues step 3
+3. **`GenerateRelationshipsJob`** — computes Jaccard-weighted edges to all tag-sharing nodes and upserts both directions (A→B and B→A) into `node_relationships`
+
+Edges below `MIN_WEIGHT_THRESHOLD` (0.1) are skipped; at most `MAX_EDGES_PER_NODE` (50) edges are stored per node.
+
 ### Immediate vs Eventual Capabilities
 
 | Capability | Available | Notes |
@@ -357,6 +369,7 @@ node_id = htm.remember("Important fact about databases")
 | Vector search | After ~100ms | Needs embedding |
 | Tag-enhanced search | After ~1s | Needs tags |
 | Hybrid search | After ~1s | Needs embedding + tags |
+| Graph traversal | After ~1-2s | Needs relationship edges |
 
 ## Working Memory Integration
 

data/docs/guides/configuration.md

@@ -207,18 +207,18 @@ HTM_PROPOSITION__MODEL=gpt-4o-mini
 
 ### Chunking Configuration
 
-Access: `HTM.config.chunking.size`, `HTM.config.chunking.overlap`
+Access: `HTM.config.chunking.chunk_size`, `HTM.config.chunking.chunk_overlap`
 
 ```yaml
 chunking:
-  size: 1024                # Characters per chunk
-  overlap: 64               # Overlap between chunks
+  chunk_size: 1024          # Characters per chunk
+  chunk_overlap: 64         # Overlap between chunks
 ```
 
 **Environment variables:**
 ```bash
-HTM_CHUNKING__SIZE=512
-HTM_CHUNKING__OVERLAP=50
+HTM_CHUNKING__CHUNK_SIZE=512
+HTM_CHUNKING__CHUNK_OVERLAP=50
 ```
 
 ### Job Backend Configuration