htm 0.0.17 → 0.0.20

data/docs/{architecture → robots}/two-tier-memory.md

@@ -6,64 +6,10 @@ HTM implements a sophisticated two-tier memory architecture that balances the co
 
 The two-tier architecture addresses a fundamental challenge in LLM-based applications: LLMs have limited context windows but need to maintain awareness across long conversations spanning days, weeks, or months.
 
-<svg viewBox="0 0 800 500" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="18" font-weight="bold">Two-Tier Memory Architecture</text>
-
-  <!-- Working Memory (Hot Tier) -->
-  <rect x="50" y="80" width="300" height="180" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="5"/>
-  <text x="200" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Working Memory (Hot)</text>
-  <text x="80" y="140" fill="#B0B0B0" font-size="12">Capacity: Token-limited (128K)</text>
-  <text x="80" y="160" fill="#B0B0B0" font-size="12">Storage: In-memory Ruby Hash</text>
-  <text x="80" y="180" fill="#B0B0B0" font-size="12">Speed: O(1) lookups</text>
-  <text x="80" y="200" fill="#B0B0B0" font-size="12">Lifetime: Process lifetime</text>
-  <text x="80" y="220" fill="#B0B0B0" font-size="12">Eviction: Importance + Recency</text>
-  <text x="80" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Fast, Token-Aware, Volatile</text>
-
-  <!-- Long-Term Memory (Cold Tier) -->
-  <rect x="450" y="80" width="300" height="180" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3" rx="5"/>
-  <text x="600" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory (Cold)</text>
-  <text x="480" y="140" fill="#B0B0B0" font-size="12">Capacity: Unlimited</text>
-  <text x="480" y="160" fill="#B0B0B0" font-size="12">Storage: PostgreSQL + TimescaleDB</text>
-  <text x="480" y="180" fill="#B0B0B0" font-size="12">Speed: O(log n) with indexes</text>
-  <text x="480" y="200" fill="#B0B0B0" font-size="12">Lifetime: Permanent</text>
-  <text x="480" y="220" fill="#B0B0B0" font-size="12">Retrieval: RAG (semantic + temporal)</text>
-  <text x="480" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Durable, Searchable, Persistent</text>
-
-  <!-- Data Flow: Add Memory -->
-  <path d="M 200 280 L 200 320 L 400 320 L 400 280" stroke="#4CAF50" stroke-width="3" fill="none" marker-end="url(#arrow-green)"/>
-  <text x="300" y="310" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Add Memory</text>
-  <text x="300" y="330" text-anchor="middle" fill="#B0B0B0" font-size="10">(Stored in both tiers)</text>
-
-  <!-- Data Flow: Eviction -->
-  <path d="M 350 360 L 600 360" stroke="#FF9800" stroke-width="3" marker-end="url(#arrow-orange)"/>
-  <text x="475" y="350" text-anchor="middle" fill="#FF9800" font-size="12" font-weight="bold">Eviction</text>
-  <text x="475" y="380" text-anchor="middle" fill="#B0B0B0" font-size="10">(Token limit → move to LTM only)</text>
-
-  <!-- Data Flow: Recall -->
-  <path d="M 600 400 L 200 400" stroke="#9C27B0" stroke-width="3" marker-end="url(#arrow-purple)"/>
-  <text x="400" y="390" text-anchor="middle" fill="#9C27B0" font-size="12" font-weight="bold">Recall</text>
-  <text x="400" y="420" text-anchor="middle" fill="#B0B0B0" font-size="10">(RAG search → load back to WM)</text>
-
-  <!-- Never Forget Note -->
-  <rect x="150" y="450" width="500" height="40" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
-  <text x="400" y="475" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">Never Forget: Evicted memories stay in LTM forever (explicit deletion only)</text>
-
-  <defs>
-    <marker id="arrow-green" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
-    </marker>
-    <marker id="arrow-orange" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
-    </marker>
-    <marker id="arrow-purple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
-      <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
-    </marker>
-  </defs>
-</svg>
+![Two-Tier Memory Architecture](../assets/images/two-tier-memory-architecture.svg)
 
 !!! info "Related ADR"
-    See [ADR-002: Two-Tier Memory Architecture](adrs/002-two-tier-memory.md) for the complete architectural decision record.
+    See [ADR-002: Two-Tier Memory Architecture](../architecture/adrs/002-two-tier-memory.md) for the complete architectural decision record.
 
 ## Working Memory (Hot Tier)
 
@@ -209,55 +155,13 @@ Nodes are evicted in this order:
 3. **High importance, old** (e.g., importance: 9.0, age: 5 days)
 4. **High importance, recent** (e.g., importance: 9.0, age: 1 hour) ← **Kept longest**
 
-<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Eviction Priority (Lower → Higher retention)</text>
-
-  <!-- Priority bars -->
-  <rect x="50" y="80" width="150" height="50" fill="rgba(244, 67, 54, 0.6)" stroke="#F44336" stroke-width="2" rx="3"/>
-  <text x="125" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 1: Evict First</text>
-
-  <rect x="220" y="80" width="150" height="50" fill="rgba(255, 152, 0, 0.6)" stroke="#FF9800" stroke-width="2" rx="3"/>
-  <text x="295" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 2</text>
-
-  <rect x="390" y="80" width="150" height="50" fill="rgba(255, 193, 7, 0.6)" stroke="#FFC107" stroke-width="2" rx="3"/>
-  <text x="465" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 3</text>
-
-  <rect x="560" y="80" width="150" height="50" fill="rgba(76, 175, 80, 0.6)" stroke="#4CAF50" stroke-width="2" rx="3"/>
-  <text x="635" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 4: Keep Longest</text>
-
-  <!-- Details -->
-  <text x="125" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
-  <text x="125" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
-  <text x="125" y="200" text-anchor="middle" fill="#F44336" font-size="10" font-weight="bold">Low value, stale</text>
-
-  <text x="295" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
-  <text x="295" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
-  <text x="295" y="200" text-anchor="middle" fill="#FF9800" font-size="10" font-weight="bold">Low value, recent</text>
-
-  <text x="465" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
-  <text x="465" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
-  <text x="465" y="200" text-anchor="middle" fill="#FFC107" font-size="10" font-weight="bold">High value, older</text>
-
-  <text x="635" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
-  <text x="635" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
-  <text x="635" y="200" text-anchor="middle" fill="#4CAF50" font-size="10" font-weight="bold">High value, fresh</text>
-
-  <!-- Example scenario -->
-  <text x="50" y="250" fill="#E0E0E0" font-size="13" font-weight="bold">Example Eviction Scenario:</text>
-  <text x="50" y="280" fill="#B0B0B0" font-size="11">Working Memory: 127,500 / 128,000 tokens (99% full)</text>
-  <text x="50" y="300" fill="#B0B0B0" font-size="11">New memory to add: 5,000 tokens</text>
-  <text x="50" y="320" fill="#B0B0B0" font-size="11">Need to free: 4,500 tokens</text>
-
-  <text x="50" y="350" fill="#4CAF50" font-size="11">Eviction: Remove Tier 1 and Tier 2 nodes until 4,500+ tokens freed</text>
-  <text x="50" y="370" fill="#4CAF50" font-size="11">Result: Tier 3 and Tier 4 nodes preserved (high importance)</text>
-</svg>
+![Eviction Priority](../assets/images/eviction-priority.svg)
 
 !!! warning "Importance Matters"
     **Assign meaningful importance scores!** Low-importance memories (1.0-3.0) will be evicted first. Use higher scores (7.0-10.0) for critical information like architectural decisions, user preferences, and long-term facts.
 
 !!! info "Related ADR"
-    See [ADR-007: Working Memory Eviction Strategy](adrs/007-eviction-strategy.md) for detailed rationale and alternatives considered.
+    See [ADR-007: Working Memory Eviction Strategy](../architecture/adrs/007-eviction-strategy.md) for detailed rationale and alternatives considered.
 
 ### Context Assembly Strategies
 
@@ -352,50 +256,10 @@ context = htm.create_context(strategy: :balanced)
 # Recent debugging context + important architectural decisions
 ```
 
-<svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
-  <!-- Title -->
-  <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Balanced Strategy: Importance Decay Over Time</text>
-
-  <!-- Axes -->
-  <line x1="100" y1="350" x2="700" y2="350" stroke="#808080" stroke-width="2"/>
-  <line x1="100" y1="350" x2="100" y2="80" stroke="#808080" stroke-width="2"/>
-
-  <!-- X-axis labels -->
-  <text x="100" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">0h</text>
-  <text x="250" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">1h</text>
-  <text x="400" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">3h</text>
-  <text x="550" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">6h</text>
-  <text x="700" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">24h</text>
-  <text x="400" y="395" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Time Since Added (hours)</text>
-
-  <!-- Y-axis labels -->
-  <text x="85" y="355" text-anchor="end" fill="#B0B0B0" font-size="11">0</text>
-  <text x="85" y="280" text-anchor="end" fill="#B0B0B0" font-size="11">3</text>
-  <text x="85" y="205" text-anchor="end" fill="#B0B0B0" font-size="11">6</text>
-  <text x="85" y="130" text-anchor="end" fill="#B0B0B0" font-size="11">9</text>
-  <text x="85" y="85" text-anchor="end" fill="#B0B0B0" font-size="11">10</text>
-  <text x="40" y="220" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold" transform="rotate(-90 40 220)">Effective Score</text>
-
-  <!-- Decay curves for different importance levels -->
-  <!-- Importance 10.0 -->
-  <path d="M 100 80 Q 250 105 400 155 T 700 320" stroke="#4CAF50" stroke-width="3" fill="none"/>
-  <text x="710" y="320" fill="#4CAF50" font-size="11" font-weight="bold">Imp: 10.0</text>
-
-  <!-- Importance 5.0 -->
-  <path d="M 100 205 Q 250 230 400 255 T 700 335" stroke="#2196F3" stroke-width="3" fill="none"/>
-  <text x="710" y="335" fill="#2196F3" font-size="11" font-weight="bold">Imp: 5.0</text>
-
-  <!-- Importance 1.0 -->
-  <path d="M 100 330 Q 250 340 400 345 T 700 348" stroke="#FF9800" stroke-width="3" fill="none"/>
-  <text x="710" y="348" fill="#FF9800" font-size="11" font-weight="bold">Imp: 1.0</text>
-
-  <!-- Key insight -->
-  <rect x="150" y="50" width="500" height="25" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
-  <text x="400" y="68" text-anchor="middle" fill="#4CAF50" font-size="12">High-importance memories retain value longer, but recency still matters</text>
-</svg>
+![Balanced Strategy: Importance Decay Over Time](../assets/images/balanced-strategy-decay.svg)
 
 !!! info "Related ADR"
-    See [ADR-006: Context Assembly Strategies](adrs/006-context-assembly.md) for detailed strategy analysis.
+    See [ADR-006: Context Assembly Strategies](../architecture/adrs/006-context-assembly.md) for detailed strategy analysis.
 
 ### Performance Characteristics
 
@@ -474,7 +338,7 @@ CREATE INDEX idx_nodes_value_gin ON nodes
 - Retention policies for data lifecycle
 
 !!! info "Related ADR"
-    See [ADR-001: Use PostgreSQL with TimescaleDB for Storage](adrs/001-postgresql-timescaledb.md) for complete rationale.
+    See [ADR-001: Use PostgreSQL with TimescaleDB for Storage](../architecture/adrs/001-postgresql-timescaledb.md) for complete rationale.
 
 ### Long-Term Memory Operations
 
@@ -560,7 +424,7 @@ end
 ```
 
 !!! info "Related ADR"
-    See [ADR-005: RAG-Based Retrieval with Hybrid Search](adrs/005-rag-retrieval.md) for search strategy details.
+    See [ADR-005: RAG-Based Retrieval with Hybrid Search](../architecture/adrs/005-rag-retrieval.md) for search strategy details.
 
 ### RAG-Based Retrieval
 
@@ -831,9 +695,9 @@ LIMIT 20;
 
 ## Related Documentation
 
-- [Architecture Index](index.md) - System overview and component summary
-- [Architecture Overview](overview.md) - Detailed architecture and data flows
+- [Architecture Index](../architecture/index.md) - System overview and component summary
+- [Architecture Overview](../architecture/overview.md) - Detailed architecture and data flows
 - [Hive Mind Architecture](hive-mind.md) - Multi-robot shared memory
-- [ADR-002: Two-Tier Memory Architecture](adrs/002-two-tier-memory.md)
-- [ADR-006: Context Assembly Strategies](adrs/006-context-assembly.md)
-- [ADR-007: Working Memory Eviction Strategy](adrs/007-eviction-strategy.md)
+- [ADR-002: Two-Tier Memory Architecture](../architecture/adrs/002-two-tier-memory.md)
+- [ADR-006: Context Assembly Strategies](../architecture/adrs/006-context-assembly.md)
+- [ADR-007: Working Memory Eviction Strategy](../architecture/adrs/007-eviction-strategy.md)

data/docs/robots/why-robots.md

@@ -0,0 +1,85 @@
+# Why "Robots" Instead of "Agents"?
+
+> "What's in a name? That which we call a rose
+> By any other name would smell as sweet."
+> — Shakespeare, *Romeo and Juliet*
+
+Shakespeare argues names are arbitrary. In software, we respectfully disagree—names shape expectations and understanding. The words we choose frame how we think about systems, what we expect from them, and how we architect their capabilities.
+
+HTM uses **robots** rather than the fashionable "agents" deliberately and thoughtfully.
+
+## The Problem with "Agent"
+
+The term "agent" carries philosophical baggage it cannot support:
+
+- **Semantic overload**: User agents, software agents, real estate agents, secret agents, FBI agents, travel agents. The word means everything and therefore nothing. When you say "AI agent," what mental model does your listener construct?
+
+- **False autonomy**: "Agent" implies genuine decision-making, independent action, perhaps even free will. These systems follow instructions. They predict the next token. They don't have *agency* in any meaningful philosophical sense. Calling them agents sets expectations the technology cannot meet.
+
+- **The hype cycle problem**: "AI Agent" and "Agentic AI" became buzzwords in 2023-2024, often meaning nothing more than "LLM with a prompt and a while loop." We prefer terminology that will age gracefully rather than become an embarrassing artifact of a particular moment's enthusiasm.
+
+- **Implementation reality**: Look under the hood of popular "agent" frameworks. You'll often find a system prompt, a for-loop, and some JSON parsing. Calling that an "agent" is marketing, not engineering.
+
+## The Case for "Robot"
+
+"Robot" has heritage, honesty, and heart:
+
+- **Rich literary tradition**: The word comes from Karel Čapek's 1920 play *R.U.R.* (Rossum's Universal Robots), derived from Czech *robota*, meaning forced labor or drudgery. Isaac Asimov gave us the Three Laws of Robotics and decades of thoughtful exploration of robot ethics, identity, and purpose. There's a century of serious thinking about what robots are and how they should behave. "Agent" has no comparable intellectual foundation.
+
+- **Honest about the relationship**: Robots work for us. They're tireless, reliable, and purpose-built. They don't pretend to have goals independent of their creators. This honesty about the master-worker relationship is healthier than the ambiguity of "agent."
+
+- **Cultural resonance**: Robots are endearing. R2-D2. Wall-E. Bender. Data. The Iron Giant. Baymax. We've spent a century telling stories about robots, developing affection for them, and exploring their place alongside humanity. "Agent" has no such cultural weight—it's the language of bureaucracy and espionage.
+
+- **Technical precision**: In HTM, each robot has an identity (`robot_id`), a name, and a history of contributions. Robots are registered in a table. They're tracked. They're *things* with identity and persistence. "Agent" suggests ephemerality; "robot" suggests durability.
+
+## Robots in the Hive Mind
+
+HTM's architecture reinforces the robot metaphor in a specific way: **all robots share a common long-term memory**.
+
+This is the *hive mind* pattern. Individual robots have their own working memory—their own immediate context and focus—but they draw from and contribute to a shared pool of knowledge. Like worker bees serving a hive, each robot is both individual and part of something larger.
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Shared Long-Term Memory            │
+│              (The Hive Mind / Collective)           │
+│                                                     │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐              │
+│  │ Memory  │  │ Memory  │  │ Memory  │  ...         │
+│  └─────────┘  └─────────┘  └─────────┘              │
+└─────────────────────────────────────────────────────┘
+        ▲              ▲              ▲
+        │              │              │
+   ┌────┴────┐    ┌────┴────┐    ┌────┴────┐
+   │ Robot A │    │ Robot B │    │ Robot C │
+   │         │    │         │    │         │
+   │ Working │    │ Working │    │ Working │
+   │ Memory  │    │ Memory  │    │ Memory  │
+   └─────────┘    └─────────┘    └─────────┘
+```
+
+This architecture maps naturally to the robot metaphor:
+
+- **Robots are workers**: They execute tasks, store memories, recall information
+- **Robots are individuals**: Each has its own name, identity, and working context
+- **Robots are collective**: They share knowledge, learn from each other's experiences
+- **Robots are persistent**: They're registered, tracked, and their contributions are attributed
+
+"Agent" suggests independence and autonomy. "Robot" suggests collaboration and purpose. HTM's robots work together, building collective intelligence. That's what the terminology should convey.
+
+## Robots Never Forget
+
+HTM follows a **never-forget philosophy** (see [ADR-009](../architecture/adrs/009-never-forget.md)). Memories are never truly deleted—only soft-deleted, always recoverable. This aligns with the robot metaphor:
+
+A good robot doesn't lose your data. A good robot remembers what you told it, years later if necessary. A good robot is *reliable* in a way that ephemeral "agents" are not.
+
+When you tell an HTM robot something important, it stores that information in the collective memory. Other robots can access it. Future robots can learn from it. The knowledge persists, attributed to the robot that first contributed it.
+
+This is robot memory done right: durable, shared, and faithful.
+
+## Honest Terminology, Clear Thinking
+
+Language shapes thought. When we call these systems "agents," we prime ourselves to expect agency—goals, autonomy, perhaps even consciousness. When we call them "robots," we remind ourselves what they actually are: sophisticated tools, tireless workers, faithful servants of the instructions we give them.
+
+HTM helps robots do their job better: remember perfectly, recall intelligently, share knowledge generously, and serve reliably. That's not agency. That's good engineering.
+
+These are robots. Let's call them what they are.

data/docs/setup_local_database.md

@@ -63,12 +63,12 @@ Update your `.envrc` file (already done):
 
 ```bash
 # Database connection - Localhost PostgreSQL
-export HTM_DBHOST=localhost
-export HTM_DBPORT=5432
-export HTM_DBNAME=htm_development
-export HTM_DBUSER=${USER}
-export HTM_DBPASS=
-export HTM_DBURL="postgresql://${HTM_DBUSER}@${HTM_DBHOST}:${HTM_DBPORT}/${HTM_DBNAME}?sslmode=prefer"
+export HTM_DATABASE__HOST=localhost
+export HTM_DATABASE__PORT=5432
+export HTM_DATABASE__NAME=htm_development
+export HTM_DATABASE__USER=${USER}
+export HTM_DATABASE__PASSWORD=
+export HTM_DATABASE__URL="postgresql://${HTM_DATABASE__USER}@${HTM_DATABASE__HOST}:${HTM_DATABASE__PORT}/${HTM_DATABASE__NAME}?sslmode=prefer"
 
 # Client-side embedding generation
 export HTM_EMBEDDINGS_PROVIDER=ollama
@@ -209,7 +209,7 @@ ollama serve
 **Solution:**
 ```bash
 direnv allow
-echo $HTM_DBURL  # Verify it's set
+echo $HTM_DATABASE__URL  # Verify it's set
 ```
 
 ## Switching Back to TimescaleDB Cloud
@@ -218,21 +218,21 @@ To switch back to TimescaleDB Cloud (production), edit `.envrc`:
 
 ```bash
 # Comment out localhost config
-# export HTM_DBHOST=localhost
-# export HTM_DBPORT=5432
-# export HTM_DBNAME=htm_development
-# export HTM_DBUSER=${USER}
-# export HTM_DBPASS=
-# export HTM_DBURL="postgresql://${HTM_DBUSER}@${HTM_DBHOST}:${HTM_DBPORT}/${HTM_DBNAME}?sslmode=prefer"
+# export HTM_DATABASE__HOST=localhost
+# export HTM_DATABASE__PORT=5432
+# export HTM_DATABASE__NAME=htm_development
+# export HTM_DATABASE__USER=${USER}
+# export HTM_DATABASE__PASSWORD=
+# export HTM_DATABASE__URL="postgresql://${HTM_DATABASE__USER}@${HTM_DATABASE__HOST}:${HTM_DATABASE__PORT}/${HTM_DATABASE__NAME}?sslmode=prefer"
 
 # Uncomment TimescaleDB Cloud config
 export HTM_SERVICE_NAME=$TIGER_SERVICE_NAME
-export HTM_DBURL=$TIGER_DBURL
-export HTM_DBNAME=$TIGER_DBNAME
-export HTM_DBUSER=$TIGER_DBUSER
-export HTM_DBPASS=$TIGER_DBPASS
-export HTM_DBHOST=$TIGER_DBHOST
-export HTM_DBPORT=$TIGER_DBPORT
+export HTM_DATABASE__URL=$TIGER_DBURL
+export HTM_DATABASE__NAME=$TIGER_DBNAME
+export HTM_DATABASE__USER=$TIGER_DBUSER
+export HTM_DATABASE__PASSWORD=$TIGER_DBPASS
+export HTM_DATABASE__HOST=$TIGER_DBHOST
+export HTM_DATABASE__PORT=$TIGER_DBPORT
 ```
 
 Then reload:

data/docs/using_rake_tasks_in_your_app.md

@@ -63,14 +63,14 @@ Create a `.envrc` file in your application's root:
 
 ```bash
 # .envrc
-export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=require"
 
 # Or use individual parameters
-export HTM_DBHOST="your-host.tsdb.cloud.timescale.com"
-export HTM_DBPORT="37807"
-export HTM_DBNAME="tsdb"
-export HTM_DBUSER="tsdbadmin"
-export HTM_DBPASS="your_password"
+export HTM_DATABASE__HOST="your-host.tsdb.cloud.timescale.com"
+export HTM_DATABASE__PORT="37807"
+export HTM_DATABASE__NAME="tsdb"
+export HTM_DATABASE__USER="tsdbadmin"
+export HTM_DATABASE__PASSWORD="your_password"
 
 # Embedding configuration
 export HTM_EMBEDDINGS_PROVIDER=ollama
@@ -93,7 +93,7 @@ direnv allow
 ### Option 2: Export in Shell
 
 ```bash
-export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=require"
 rake htm:db:info
 ```
 
@@ -103,7 +103,7 @@ rake htm:db:info
 # Rakefile
 
 # Set environment variables programmatically
-ENV['HTM_DBURL'] = "postgresql://user:password@host:port/dbname?sslmode=require"
+ENV['HTM_DATABASE__URL'] = "postgresql://user:password@host:port/dbname?sslmode=require"
 
 # Then load tasks
 require 'htm/tasks'
@@ -122,7 +122,7 @@ require 'htm/tasks'
 
 ```bash
 # .env
-HTM_DBURL=postgresql://user:password@host:port/dbname?sslmode=require
+HTM_DATABASE__URL=postgresql://user:password@host:port/dbname?sslmode=require
 ```
 
 ## Real-World Example
@@ -297,13 +297,13 @@ jobs:
 
       - name: Setup database
         env:
-          HTM_DBURL: postgresql://postgres:postgres@localhost:5432/test
+          HTM_DATABASE__URL: postgresql://postgres:postgres@localhost:5432/test
         run: |
           bundle exec rake htm:db:setup
 
       - name: Run tests
         env:
-          HTM_DBURL: postgresql://postgres:postgres@localhost:5432/test
+          HTM_DATABASE__URL: postgresql://postgres:postgres@localhost:5432/test
         run: |
           bundle exec rake test
 ```
@@ -317,7 +317,7 @@ services:
   app:
     build: .
     environment:
-      - HTM_DBURL=postgresql://postgres:postgres@db:5432/myapp
+      - HTM_DATABASE__URL=postgresql://postgres:postgres@db:5432/myapp
     depends_on:
       - db
     command: bash -c "rake htm:db:setup && rake app:start"
@@ -347,10 +347,10 @@ rake -T
 Error: Database configuration not found
 ```
 
-Solution: Set `HTM_DBURL` environment variable
+Solution: Set `HTM_DATABASE__URL` environment variable
 
 ```bash
-export HTM_DBURL="postgresql://user:password@host:port/dbname"
+export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname"
 rake htm:db:info
 ```
 

data/examples/README.md

@@ -8,12 +8,12 @@ All examples require:
 
 1. **PostgreSQL Database** with pgvector extension:
    ```bash
-   export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
+   export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
    ```
 
    > **Note**: Database selection now respects `RAILS_ENV`. If `RAILS_ENV` is set,
-   > HTM extracts the base name from `HTM_DBURL` and appends the environment suffix.
-   > For example, with `HTM_DBURL=...htm_development` and `RAILS_ENV=test`, HTM
+   > HTM extracts the base name from `HTM_DATABASE__URL` and appends the environment suffix.
+   > For example, with `HTM_DATABASE__URL=...htm_development` and `HTM_ENV=test`, HTM
    > connects to `htm_test`. When `RAILS_ENV` is unset (typical for examples),
    > behavior is unchanged.
 
@@ -32,6 +32,43 @@ All examples require:
 
 ## Standalone Scripts
 
+### config_file_example/
+
+**Configuration management with source tracing.**
+
+Demonstrates how HTM uses `anyway_config` for layered configuration from multiple sources, with source tracing to show where each value originated.
+
+```bash
+cd examples/config_file_example
+ruby show_config.rb
+```
+
+**Features:**
+- Configuration priority order (defaults → XDG → project → local → env vars)
+- Source tracing showing origin of each config value
+- `HTM_CONF` environment variable for custom config file paths
+- Environment-specific configuration (`HTM_ENV`)
+- Generating config templates with `htm_mcp config`
+
+**Usage examples:**
+```bash
+# Basic - loads ./config/htm.local.yml automatically
+ruby show_config.rb
+
+# Use custom config file
+HTM_CONF=./custom_config.yml ruby show_config.rb
+
+# Override with environment variables
+HTM_EMBEDDING__MODEL=mxbai-embed-large ruby show_config.rb
+
+# Different environment
+HTM_ENV=production ruby show_config.rb
+```
+
+See [config_file_example/README.md](config_file_example/README.md) for detailed documentation.
+
+---
+
 ### basic_usage.rb
 
 **Getting started with HTM fundamentals.**
@@ -184,7 +221,7 @@ ruby examples/mcp_server.rb
       "command": "ruby",
       "args": ["/path/to/htm/examples/mcp_server.rb"],
       "env": {
-        "HTM_DBURL": "postgresql://user@localhost:5432/htm_development"
+        "HTM_DATABASE__URL": "postgresql://user@localhost:5432/htm_development"
       }
     }
   }
@@ -260,7 +297,7 @@ ollama pull gpt-oss  # Or your preferred model
 ```
 
 **Environment Variables:**
-- `HTM_DBURL` - PostgreSQL connection (required)
+- `HTM_DATABASE__URL` - PostgreSQL connection (required)
 - `OLLAMA_URL` - Ollama server URL (default: http://localhost:11434)
 - `OLLAMA_MODEL` - Model to use (default: gpt-oss:latest)
 - `HTM_ROBOT_NAME` - Robot name (optional, prompts if not set)
@@ -313,7 +350,7 @@ bundle exec ruby app.rb
 - Tag tree visualization
 
 **Environment Variables:**
-- `HTM_DBURL` - PostgreSQL connection (required)
+- `HTM_DATABASE__URL` - PostgreSQL connection (required)
 - `REDIS_URL` - Redis for Sidekiq (default: redis://localhost:6379/0)
 - `SESSION_SECRET` - Session encryption key
 
@@ -405,6 +442,12 @@ examples/
 ├── custom_llm_configuration.rb    # LLM integration patterns
 ├── file_loader_usage.rb           # Document loading
 ├── timeframe_demo.rb              # Time-based filtering
+├── config_file_example/
+│   ├── show_config.rb             # Config source tracing demo
+│   ├── custom_config.yml          # Example for HTM_CONF
+│   ├── README.md                  # Configuration documentation
+│   └── config/
+│       └── htm.local.yml          # Auto-loaded local overrides
 ├── telemetry/
 │   ├── demo.rb                    # Live Grafana metrics dashboard
 │   ├── README.md
@@ -438,6 +481,7 @@ examples/
 | Use Case | Example |
 |----------|---------|
 | Learning HTM basics | `basic_usage.rb` |
+| Configuration management | `config_file_example/` |
 | Custom LLM integration | `custom_llm_configuration.rb` |
 | Loading documents/files | `file_loader_usage.rb` |
 | Time-based queries | `timeframe_demo.rb` |

data/examples/basic_usage.rb

@@ -4,8 +4,10 @@
 # Basic usage example for HTM
 #
 # Prerequisites:
-# 1. Set HTM_DBURL environment variable (see SETUP.md)
-# 2. Initialize database schema: rake db_setup
+# 1. Configure database via environment or config file:
+#    - HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
+#    - Or individual vars: HTM_DATABASE__HOST, HTM_DATABASE__NAME, etc.
+# 2. Initialize database schema: rake htm:db:setup
 # 3. Install dependencies: bundle install
 
 require_relative '../lib/htm'
@@ -13,26 +15,31 @@ require_relative '../lib/htm'
 puts "HTM Basic Usage Example"
 puts "=" * 60
 
-# Check environment
-unless ENV['HTM_DBURL']
-  puts "ERROR: HTM_DBURL not set. Please set it:"
-  puts "  export HTM_DBURL=\"postgresql://postgres@localhost:5432/htm_development\""
-  puts "See SETUP.md for details."
+# Check database configuration using the config system
+unless HTM.config.database_configured?
+  puts "ERROR: Database not configured. Set one of:"
+  puts "  export HTM_DATABASE__URL=\"postgresql://user@localhost:5432/htm_development\""
+  puts "  Or configure in ~/.config/htm/htm.yml"
+  puts "Run 'bin/htm_mcp help' for all configuration options."
   exit 1
 end
 
 begin
-  # Configure HTM globally (uses Ollama by default)
+  # Configure HTM globally (uses Ollama by default from defaults.yml)
   puts "\n1. Configuring HTM with Ollama provider..."
   HTM.configure do |config|
-    config.embedding_provider = :ollama
-    config.embedding_model = 'nomic-embed-text:latest'  # Ollama models need :tag suffix
-    config.embedding_dimensions = 768
-    config.tag_provider = :ollama
-    config.tag_model = 'gemma3:latest'  # Ollama models need :tag suffix
-    config.reset_to_defaults  # Apply settings
+    config.embedding.provider = :ollama
+    config.embedding.model = 'nomic-embed-text:latest'
+    config.embedding.dimensions = 768
+    config.tag.provider = :ollama
+    config.tag.model = 'gemma3:latest'
+    # Use inline job backend for synchronous execution in examples
+    # (In production, use :thread or :sidekiq for async processing)
+    config.job.backend = :inline
+    # Quiet the logs for cleaner output
+    config.log_level = :warn
   end
-  puts "✓ HTM configured with Ollama provider"
+  puts "✓ HTM configured with Ollama provider (inline job backend)"
 
   # Initialize HTM for 'Code Helper' robot
   puts "\n2. Initializing HTM for 'Code Helper' robot..."
@@ -43,7 +50,7 @@ begin
   puts "✓ HTM initialized"
   puts "  Robot ID: #{htm.robot_id}"
   puts "  Robot Name: #{htm.robot_name}"
-  puts "  Embedding Service: Ollama (#{HTM.configuration.embedding_model})"
+  puts "  Embedding Service: #{HTM.config.embedding.provider} (#{HTM.config.embedding.model})"
 
   # Remember some information
   puts "\n3. Remembering information..."
@@ -63,15 +70,18 @@ begin
   )
   puts "✓ Remembered fact about user preferences (node #{node_id_3})"
 
-  # Sleep briefly to allow async embedding/tag jobs to start
-  sleep 0.5
+  # With inline backend, embeddings and tags are generated synchronously
+  # No sleep needed - memories are immediately searchable
 
-  # Demonstrate recall
-  puts "\n4. Recalling memories about 'database'..."
+  # Demonstrate recall using fulltext search (keyword matching)
+  # Note: hybrid search requires fulltext matches first, so search terms
+  # must appear in the stored content. Use fulltext for keyword matching.
+  puts "\n4. Recalling memories about 'PostgreSQL'..."
   memories = htm.recall(
-    "database",
+    "PostgreSQL",  # This word appears in the stored content
     timeframe: (Time.now - 3600)..Time.now,  # Last hour
     limit: 5,
+    strategy: :fulltext,  # Keyword matching (words must appear in content)
     raw: true  # Return full node data (id, content, etc.)
   )
   puts "✓ Found #{memories.length} memories"