htm 0.0.1

data/docs/assets/images/htm-long-term-memory-architecture.svg

@@ -0,0 +1,115 @@
+<svg viewBox="0 0 950 700" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <defs>
+    <style>
+      .ltm-box { fill: rgba(33, 150, 243, 0.2); stroke: #2196F3; stroke-width: 3; }
+      .table-box { fill: rgba(76, 175, 80, 0.2); stroke: #4CAF50; stroke-width: 2; }
+      .index-box { fill: rgba(255, 152, 0, 0.2); stroke: #FF9800; stroke-width: 2; }
+      .hypertable { fill: rgba(156, 39, 176, 0.2); stroke: #9C27B0; stroke-width: 2; }
+      .text-header { fill: #E0E0E0; font-size: 18px; font-weight: bold; }
+      .text-label { fill: #E0E0E0; font-size: 14px; font-weight: bold; }
+      .text-small { fill: #B0B0B0; font-size: 12px; }
+      .text-tiny { fill: #A0A0A0; font-size: 10px; }
+    </style>
+  </defs>
+
+  <!-- Title -->
+  <text x="475" y="30" text-anchor="middle" class="text-header">Long-term Memory Architecture</text>
+  <text x="475" y="50" text-anchor="middle" class="text-small">PostgreSQL</text>
+
+  <!-- Main Container -->
+  <rect x="50" y="75" width="850" height="590" class="ltm-box" rx="5"/>
+
+  <!-- Tables Section -->
+  <text x="70" y="105" class="text-label">Database Tables</text>
+
+  <!-- nodes table -->
+  <rect x="70" y="120" width="250" height="180" class="table-box" rx="3"/>
+  <text x="195" y="140" text-anchor="middle" class="text-label" fill="#4CAF50">nodes</text>
+  <text x="80" y="165" class="text-small">Memories + Embeddings</text>
+  <text x="80" y="185" class="text-tiny">• id, key, value</text>
+  <text x="80" y="200" class="text-tiny">• type, category, importance</text>
+  <text x="80" y="215" class="text-tiny">• token_count, robot_id</text>
+  <text x="80" y="230" class="text-tiny">• embedding vector(1536)</text>
+  <text x="80" y="245" class="text-tiny">• created_at, last_accessed</text>
+  <text x="80" y="260" class="text-tiny">• in_working_memory flag</text>
+  <text x="80" y="280" class="text-small" fill="#66BB6A">Primary storage</text>
+
+  <!-- relationships table -->
+  <rect x="340" y="120" width="250" height="100" class="table-box" rx="3"/>
+  <text x="465" y="140" text-anchor="middle" class="text-label" fill="#4CAF50">relationships</text>
+  <text x="350" y="165" class="text-small">Knowledge Graph</text>
+  <text x="350" y="185" class="text-tiny">• from_node_id → to_node_id</text>
+  <text x="350" y="200" class="text-tiny">• relationship_type, strength</text>
+
+  <!-- tags table -->
+  <rect x="610" y="120" width="250" height="100" class="table-box" rx="3"/>
+  <text x="735" y="140" text-anchor="middle" class="text-label" fill="#4CAF50">tags</text>
+  <text x="620" y="165" class="text-small">Categorization</text>
+  <text x="620" y="185" class="text-tiny">• node_id, tag</text>
+  <text x="620" y="200" class="text-tiny">• Flexible tagging system</text>
+
+  <!-- robots table -->
+  <rect x="340" y="240" width="250" height="100" class="table-box" rx="3"/>
+  <text x="465" y="260" text-anchor="middle" class="text-label" fill="#4CAF50">robots</text>
+  <text x="350" y="285" class="text-small">Identity Registry</text>
+  <text x="350" y="305" class="text-tiny">• id, name, created_at</text>
+  <text x="350" y="320" class="text-tiny">• last_active, metadata</text>
+
+  <!-- operations_log table (hypertable) -->
+  <rect x="610" y="240" width="250" height="100" class="hypertable" rx="3"/>
+  <text x="735" y="260" text-anchor="middle" class="text-label" fill="#9C27B0">operations_log</text>
+  <text x="620" y="285" class="text-small">Audit Trail (Hypertable)</text>
+  <text x="620" y="305" class="text-tiny">• timestamp, operation</text>
+  <text x="620" y="320" class="text-tiny">• node_id, robot_id, details</text>
+
+  <!-- Indexes Section -->
+  <text x="70" y="375" class="text-label">Indexes &amp; Optimization</text>
+
+  <!-- HNSW Vector Index -->
+  <rect x="70" y="390" width="250" height="120" class="index-box" rx="3"/>
+  <text x="195" y="410" text-anchor="middle" class="text-label" fill="#FF9800">HNSW Vector Index</text>
+  <text x="80" y="435" class="text-small">Semantic Similarity</text>
+  <text x="80" y="455" class="text-tiny">• idx_nodes_embedding</text>
+  <text x="80" y="470" class="text-tiny">• vector_cosine_ops</text>
+  <text x="80" y="485" class="text-tiny">• m=16, ef_construction=64</text>
+  <text x="80" y="500" class="text-tiny">⚡ Fast nearest-neighbor search</text>
+
+  <!-- GIN Full-text Index -->
+  <rect x="340" y="390" width="250" height="120" class="index-box" rx="3"/>
+  <text x="465" y="410" text-anchor="middle" class="text-label" fill="#FF9800">GIN Full-text Index</text>
+  <text x="350" y="435" class="text-small">Keyword Search</text>
+  <text x="350" y="455" class="text-tiny">• idx_nodes_fulltext</text>
+  <text x="350" y="470" class="text-tiny">• to_tsvector('english')</text>
+  <text x="350" y="485" class="text-tiny">• Supports ts_rank scoring</text>
+  <text x="350" y="500" class="text-tiny">⚡ Fast keyword matching</text>
+
+  <!-- PostgreSQL Chunks -->
+  <rect x="610" y="390" width="250" height="120" class="hypertable" rx="3"/>
+  <text x="735" y="410" text-anchor="middle" class="text-label" fill="#9C27B0">PostgreSQL Chunks</text>
+  <text x="620" y="435" class="text-small">Time-series Partitioning</text>
+  <text x="620" y="455" class="text-tiny">• Auto-partitioning by time</text>
+  <text x="620" y="470" class="text-tiny">• Compression policies</text>
+  <text x="620" y="485" class="text-tiny">• Retention policies</text>
+  <text x="620" y="500" class="text-tiny">⚡ Fast time-range queries</text>
+
+  <!-- Features Section -->
+  <text x="70" y="545" class="text-label">Key Features</text>
+
+  <rect x="70" y="560" width="250" height="90" fill="rgba(33, 150, 243, 0.15)" stroke="#2196F3" stroke-width="1.5" rx="3"/>
+  <text x="80" y="585" class="text-small">✓ Permanent storage</text>
+  <text x="80" y="605" class="text-small">✓ ACID compliant</text>
+  <text x="80" y="625" class="text-small">✓ Never forgets</text>
+  <text x="80" y="645" class="text-small">✓ Unlimited capacity</text>
+
+  <rect x="340" y="560" width="250" height="90" fill="rgba(33, 150, 243, 0.15)" stroke="#2196F3" stroke-width="1.5" rx="3"/>
+  <text x="350" y="585" class="text-small">✓ Vector similarity search</text>
+  <text x="350" y="605" class="text-small">✓ Full-text search</text>
+  <text x="350" y="625" class="text-small">✓ Hybrid retrieval</text>
+  <text x="350" y="645" class="text-small">✓ RAG-optimized</text>
+
+  <rect x="610" y="560" width="250" height="90" fill="rgba(33, 150, 243, 0.15)" stroke="#2196F2" stroke-width="1.5" rx="3"/>
+  <text x="620" y="585" class="text-small">✓ Multi-robot support</text>
+  <text x="620" y="605" class="text-small">✓ Relationship graphs</text>
+  <text x="620" y="625" class="text-small">✓ Tag-based filtering</text>
+  <text x="620" y="645" class="text-small">✓ Complete audit trail</text>
+</svg>

data/docs/assets/images/htm-working-memory-architecture.svg

@@ -0,0 +1,120 @@
+<svg viewBox="0 0 900 650" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <defs>
+    <style>
+      .wm-box { fill: rgba(33, 150, 243, 0.2); stroke: #2196F3; stroke-width: 3; }
+      .ltm-box { fill: rgba(76, 175, 80, 0.2); stroke: #4CAF50; stroke-width: 3; }
+      .memory-item { fill: rgba(255, 152, 0, 0.3); stroke: #FF9800; stroke-width: 1.5; }
+      .evicted-item { fill: rgba(244, 67, 54, 0.3); stroke: #F44336; stroke-width: 1.5; }
+      .text-header { fill: #E0E0E0; font-size: 18px; font-weight: bold; }
+      .text-label { fill: #E0E0E0; font-size: 13px; }
+      .text-small { fill: #B0B0B0; font-size: 11px; }
+      .arrow { stroke: #4A9EFF; stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
+      .arrow-evict { stroke: #F44336; stroke-width: 2; fill: none; marker-end: url(#arrowhead-red); stroke-dasharray: 5,3; }
+      .arrow-recall { stroke: #4CAF50; stroke-width: 2; fill: none; marker-end: url(#arrowhead-green); stroke-dasharray: 5,3; }
+    </style>
+    <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#4A9EFF" />
+    </marker>
+    <marker id="arrowhead-red" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#F44336" />
+    </marker>
+    <marker id="arrowhead-green" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50" />
+    </marker>
+  </defs>
+
+  <!-- Title -->
+  <text x="450" y="30" text-anchor="middle" class="text-header">Working Memory Architecture</text>
+
+  <!-- Working Memory Box -->
+  <rect x="50" y="70" width="800" height="220" class="wm-box" rx="5"/>
+  <text x="450" y="100" text-anchor="middle" class="text-header">Working Memory</text>
+  <text x="450" y="120" text-anchor="middle" class="text-small">(In-memory, Token-limited)</text>
+
+  <!-- Capacity bar -->
+  <rect x="70" y="140" width="760" height="25" fill="rgba(255, 255, 255, 0.1)" stroke="#666" stroke-width="1" rx="3"/>
+  <rect x="70" y="140" width="608" height="25" fill="rgba(76, 175, 80, 0.4)" rx="3"/>
+  <text x="450" y="157" text-anchor="middle" class="text-small">102,400 / 128,000 tokens (80% full)</text>
+
+  <!-- Memory items in working memory -->
+  <rect x="70" y="180" width="150" height="40" class="memory-item" rx="3"/>
+  <text x="80" y="197" class="text-label">Critical Decision</text>
+  <text x="210" y="197" text-anchor="end" class="text-small">imp: 10.0</text>
+  <text x="210" y="212" text-anchor="end" class="text-small">2000 tok</text>
+
+  <rect x="235" y="180" width="150" height="40" class="memory-item" rx="3"/>
+  <text x="245" y="197" class="text-label">User Preference</text>
+  <text x="375" y="197" text-anchor="end" class="text-small">imp: 8.0</text>
+  <text x="375" y="212" text-anchor="end" class="text-small">500 tok</text>
+
+  <rect x="400" y="180" width="150" height="40" class="memory-item" rx="3"/>
+  <text x="410" y="197" class="text-label">Recent Context</text>
+  <text x="540" y="197" text-anchor="end" class="text-small">imp: 6.0</text>
+  <text x="540" y="212" text-anchor="end" class="text-small">1500 tok</text>
+
+  <rect x="565" y="180" width="150" height="40" class="evicted-item" rx="3"/>
+  <text x="575" y="197" class="text-label">Old Note</text>
+  <text x="705" y="197" text-anchor="end" class="text-small">imp: 2.0</text>
+  <text x="705" y="212" text-anchor="end" class="text-small">800 tok</text>
+  <text x="640" y="235" text-anchor="middle" class="text-small" fill="#F44336">← Being evicted</text>
+
+  <!-- Features list -->
+  <text x="70" y="260" class="text-small">✓ Fast access</text>
+  <text x="250" y="260" class="text-small">✓ Token-based capacity</text>
+  <text x="450" y="260" class="text-small">✓ Automatic eviction</text>
+  <text x="650" y="260" class="text-small">✓ Importance-based retention</text>
+
+  <!-- Arrow down (Eviction) -->
+  <path d="M 640 290 L 640 350" class="arrow-evict"/>
+  <text x="660" y="325" class="text-small" fill="#F44336">Eviction</text>
+  <text x="660" y="340" class="text-small" fill="#F44336">(when full)</text>
+
+  <!-- Arrow up (Recall) -->
+  <path d="M 260 350 L 260 290" class="arrow-recall"/>
+  <text x="280" y="315" class="text-small" fill="#4CAF50">Recall</text>
+  <text x="280" y="330" class="text-small" fill="#4CAF50">(RAG retrieval)</text>
+
+  <!-- Long-term Memory Box -->
+  <rect x="50" y="370" width="800" height="240" class="ltm-box" rx="5"/>
+  <text x="450" y="400" text-anchor="middle" class="text-header">Long-term Memory</text>
+  <text x="450" y="420" text-anchor="middle" class="text-small">(PostgreSQL, Unlimited)</text>
+
+  <!-- Database tables visualization -->
+  <rect x="70" y="440" width="180" height="150" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
+  <text x="160" y="460" text-anchor="middle" class="text-label">nodes</text>
+  <text x="80" y="480" class="text-small">All memories</text>
+  <text x="80" y="495" class="text-small">Vector embeddings</text>
+  <text x="80" y="510" class="text-small">Full-text search</text>
+  <text x="80" y="525" class="text-small">Timestamps</text>
+  <text x="80" y="540" class="text-small">Importance scores</text>
+  <text x="80" y="555" class="text-small">Robot attribution</text>
+  <text x="80" y="570" class="text-small">in_working_memory flag</text>
+
+  <rect x="265" y="440" width="180" height="70" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
+  <text x="355" y="460" text-anchor="middle" class="text-label">relationships</text>
+  <text x="275" y="480" class="text-small">Knowledge graph</text>
+  <text x="275" y="495" class="text-small">Node connections</text>
+
+  <rect x="460" y="440" width="180" height="70" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
+  <text x="550" y="460" text-anchor="middle" class="text-label">tags</text>
+  <text x="470" y="480" class="text-small">Categorization</text>
+  <text x="470" y="495" class="text-small">Flexible tagging</text>
+
+  <rect x="655" y="440" width="180" height="70" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
+  <text x="745" y="460" text-anchor="middle" class="text-label">operations_log</text>
+  <text x="665" y="480" class="text-small">Audit trail</text>
+  <text x="665" y="495" class="text-small">PostgreSQL table</text>
+
+  <!-- Evicted item in long-term memory -->
+  <rect x="265" y="520" width="380" height="70" class="evicted-item" rx="3"/>
+  <text x="275" y="540" class="text-label">Evicted: Old Note</text>
+  <text x="635" y="540" text-anchor="end" class="text-small">in_working_memory: false</text>
+  <text x="275" y="560" class="text-small">Still stored, can be recalled when needed</text>
+  <text x="275" y="575" class="text-small">Full history preserved • Never forgotten</text>
+
+  <!-- Features list -->
+  <text x="70" y="335" class="text-small" fill="#4CAF50">✓ Durable storage</text>
+  <text x="270" y="335" class="text-small" fill="#4CAF50">✓ Full history</text>
+  <text x="450" y="335" class="text-small" fill="#4CAF50">✓ RAG retrieval</text>
+  <text x="610" y="335" class="text-small" fill="#4CAF50">✓ Never forgets</text>
+</svg>

data/docs/assets/js/mathjax.js

@@ -0,0 +1,18 @@
+/* MathJax Configuration for HTM Documentation */
+
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})

data/docs/database_rake_tasks.md

@@ -0,0 +1,322 @@
+# HTM Database Rake Tasks Reference
+
+Complete reference for HTM database management tasks.
+
+## Quick Start
+
+```bash
+# First time setup
+cd /path/to/htm
+direnv allow                  # Load environment variables from .envrc
+rake htm:db:setup            # Create schema and run migrations
+```
+
+## Available Tasks
+
+### Setup and Schema
+
+#### `rake htm:db:setup`
+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)
+- 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
+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
+```
+
+---
+
+### Migrations
+
+#### `rake htm:db:migrate`
+Runs pending database migrations only.
+
+**What it does:**
+- Checks which migrations have been applied
+- Runs any new migrations in `sql/migrations/`
+- Updates the `schema_migrations` table
+
+**When to use:** After pulling new code with migrations
+
+```bash
+$ rake htm:db:migrate
+Running migration: 002_ontology_topic_extraction
+  ✓ Migration 002_ontology_topic_extraction applied
+✓ Database migrations completed
+```
+
+#### `rake htm:db:status`
+Shows which migrations have been applied and which are pending.
+
+**Example output:**
+```bash
+$ rake htm:db:status
+
+Migration Status
+================================================================================
+✓ 001_support_variable_dimensions (applied: 2025-10-26 04:27:15.428951+00)
+✓ 002_ontology_topic_extraction (applied: 2025-10-27 03:44:15.012345+00)
+
+Summary: 2 applied, 0 pending
+================================================================================
+```
+
+---
+
+### Information
+
+#### `rake htm:db:info`
+Shows comprehensive database information.
+
+**Example output:**
+```bash
+$ rake htm:db:info
+
+HTM Database Information
+================================================================================
+
+Connection:
+  Host: cw7rxj91bm.srbbwwxn56.tsdb.cloud.timescale.com
+  Port: 37807
+  Database: tsdb
+  User: tsdbadmin
+
+PostgreSQL Version:
+  PostgreSQL 17.6 (Ubuntu 17.6-2.pgdg22.04+1) on aarch64-unknown-linux-gnu
+
+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)
+
+HTM Tables:
+  nodes: 42 rows
+  tags: 156 rows
+  robots: 3 rows
+  operations_log: 289 rows
+  schema_migrations: 2 rows
+
+Database Size: 14 MB
+================================================================================
+```
+
+#### `rake htm:db:test`
+Tests database connection by running `test_connection.rb`.
+
+**Example output:**
+```bash
+$ rake htm:db:test
+Connecting to TimescaleDB...
+✓ Connected successfully!
+✓ TimescaleDB Extension: Version 2.22.1
+✓ pgvector Extension: Version 0.8.1
+✓ pg_trgm Extension: Version 1.6
+```
+
+---
+
+### Utilities
+
+#### `rake htm:db:console`
+Opens an interactive PostgreSQL console (psql).
+
+**What it does:**
+- Launches `psql` connected to your HTM database
+- Uses connection parameters from `HTM_DBURL` or `.envrc`
+- Allows you to run SQL queries directly
+
+**Example:**
+```bash
+$ rake htm:db:console
+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;
+ count
+-------
+    42
+(1 row)
+
+tsdb=> \d nodes
+tsdb=> \q
+```
+
+#### `rake htm:db:seed`
+Seeds the database with sample data.
+
+**What it does:**
+- Creates a sample robot
+- Adds 3 sample nodes with different topics
+- Useful for testing or demos
+
+**Example:**
+```bash
+$ rake htm:db:seed
+Seeding database with sample data...
+  Creating sample nodes...
+✓ Database seeded with 3 sample nodes
+```
+
+---
+
+### Destructive Operations
+
+⚠️ **WARNING**: These tasks delete data and cannot be undone!
+
+#### `rake htm:db:drop`
+Drops all HTM tables, functions, triggers, and views.
+
+**What it does:**
+- Drops tables: nodes, tags, robots, operations_log, schema_migrations
+- Drops ontology functions and triggers
+- Drops views: ontology_structure, topic_relationships
+
+**Safety:** Prompts for confirmation ("yes" must be typed)
+
+```bash
+$ rake htm:db:drop
+Are you sure you want to drop all tables? This cannot be undone! (yes/no): yes
+Dropping HTM tables...
+  ✓ Dropped nodes
+  ✓ Dropped tags
+  ✓ Dropped robots
+  ✓ Dropped operations_log
+  ✓ Dropped schema_migrations
+  ✓ Dropped ontology functions and triggers
+  ✓ Dropped ontology views
+✓ All HTM tables dropped
+```
+
+#### `rake htm:db:reset`
+Drops and recreates the entire database (equivalent to `drop` + `setup`).
+
+**When to use:** Development only, to start fresh
+
+```bash
+$ rake htm:db:reset
+# Runs drop (with confirmation) then setup
+```
+
+---
+
+## Environment Variables
+
+All tasks require database configuration via environment variables. Use one of these methods:
+
+### Method 1: direnv (Recommended)
+```bash
+# One-time setup
+cd /path/to/htm
+direnv allow
+
+# Variables are automatically loaded from .envrc
+rake htm:db:info
+```
+
+### Method 2: Manual Export
+```bash
+export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
+rake htm:db:info
+```
+
+### Method 3: Source Tiger Credentials
+```bash
+source ~/.bashrc__tiger    # If using TimescaleDB Cloud
+rake htm:db:info
+```
+
+---
+
+## Common Workflows
+
+### Initial Project Setup
+```bash
+cd /path/to/htm
+direnv allow
+bundle install
+rake htm:db:setup
+rake htm:db:seed          # Optional: add sample data
+rake htm:db:info          # Verify setup
+```
+
+### After Pulling New Code
+```bash
+git pull
+rake htm:db:status        # Check for new migrations
+rake htm:db:migrate       # Run pending migrations
+```
+
+### Development Reset
+```bash
+rake htm:db:reset         # Drop and recreate (type 'yes' to confirm)
+rake htm:db:seed          # Re-add sample data
+```
+
+### Debugging
+```bash
+rake htm:db:info          # Check database state
+rake htm:db:status        # Check migration status
+rake htm:db:console       # Open psql for SQL queries
+```
+
+### Production Deployment
+```bash
+# NEVER use reset or drop in production!
+rake htm:db:migrate       # Run new migrations only
+```
+
+---
+
+## Troubleshooting
+
+### "Database configuration not found"
+- Run `direnv allow` in the project directory
+- Or manually export `HTM_DBURL`
+- Verify: `echo $HTM_DBURL`
+
+### "Connection refused"
+- Check database is running
+- Verify host/port in `HTM_DBURL`
+- Test: `rake htm:db:test`
+
+### "Extension not found"
+- Ensure TimescaleDB Cloud instance has required extensions
+- Check with: `rake htm:db:info`
+- Extensions needed: timescaledb, pgvector, pg_trgm
+
+### Migrations not running
+- Check migration files exist: `ls -la sql/migrations/`
+- Verify migrations table: `rake htm:db:console` then `SELECT * FROM schema_migrations;`
+- Force re-run: `rake htm:db:drop` then `rake htm:db:setup`
+
+---
+
+## Legacy Tasks (Deprecated)
+
+These tasks still work but will be removed in a future version:
+
+- `rake db_setup` → Use `rake htm:db:setup`
+- `rake db_test` → Use `rake htm:db:test`
+