RubyGems - htm - Versions diffs - 0.0.1 → 0.0.2 - Mend

htm 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (109) hide show

checksums.yaml +4 -4
data/.envrc +1 -0
data/.tbls.yml +30 -0
data/CHANGELOG.md +30 -0
data/SETUP.md +132 -101
data/db/migrate/20250125000001_add_content_hash_to_nodes.rb +14 -0
data/db/migrate/20250125000002_create_robot_nodes.rb +35 -0
data/db/migrate/20250125000003_remove_source_and_robot_id_from_nodes.rb +28 -0
data/db/migrate/20250126000001_create_working_memories.rb +19 -0
data/db/migrate/20250126000002_remove_unused_columns.rb +12 -0
data/db/schema.sql +226 -43
data/docs/api/database.md +20 -232
data/docs/api/embedding-service.md +1 -7
data/docs/api/htm.md +195 -449
data/docs/api/index.md +1 -7
data/docs/api/long-term-memory.md +342 -590
data/docs/architecture/adrs/001-postgresql-timescaledb.md +1 -1
data/docs/architecture/adrs/003-ollama-embeddings.md +1 -1
data/docs/architecture/adrs/010-redis-working-memory-rejected.md +2 -27
data/docs/architecture/adrs/index.md +2 -13
data/docs/architecture/hive-mind.md +165 -166
data/docs/architecture/index.md +2 -2
data/docs/architecture/overview.md +5 -171
data/docs/architecture/two-tier-memory.md +1 -35
data/docs/assets/images/adr-010-current-architecture.svg +37 -0
data/docs/assets/images/adr-010-proposed-architecture.svg +48 -0
data/docs/assets/images/adr-dependency-tree.svg +93 -0
data/docs/assets/images/class-hierarchy.svg +55 -0
data/docs/assets/images/exception-hierarchy.svg +45 -0
data/docs/assets/images/htm-architecture-overview.svg +83 -0
data/docs/assets/images/htm-complete-memory-flow.svg +160 -0
data/docs/assets/images/htm-context-assembly-flow.svg +148 -0
data/docs/assets/images/htm-eviction-process.svg +141 -0
data/docs/assets/images/htm-memory-addition-flow.svg +138 -0
data/docs/assets/images/htm-memory-recall-flow.svg +152 -0
data/docs/assets/images/htm-node-states.svg +123 -0
data/docs/assets/images/project-structure.svg +78 -0
data/docs/assets/images/test-directory-structure.svg +38 -0
data/{dbdoc → docs/database}/README.md +5 -3
data/{dbdoc → docs/database}/public.node_tags.md +4 -5
data/docs/database/public.node_tags.svg +106 -0
data/{dbdoc → docs/database}/public.nodes.md +3 -8
data/docs/database/public.nodes.svg +152 -0
data/docs/database/public.robot_nodes.md +44 -0
data/docs/database/public.robot_nodes.svg +121 -0
data/{dbdoc → docs/database}/public.robots.md +1 -2
data/docs/database/public.robots.svg +106 -0
data/docs/database/public.working_memories.md +40 -0
data/docs/database/public.working_memories.svg +112 -0
data/{dbdoc → docs/database}/schema.json +342 -110
data/docs/database/schema.svg +223 -0
data/docs/development/index.md +1 -29
data/docs/development/schema.md +84 -324
data/docs/development/testing.md +1 -9
data/docs/getting-started/index.md +47 -0
data/docs/{installation.md → getting-started/installation.md} +2 -2
data/docs/{quick-start.md → getting-started/quick-start.md} +5 -5
data/docs/guides/adding-memories.md +221 -655
data/docs/guides/search-strategies.md +85 -51
data/docs/images/htm-er-diagram.svg +156 -0
data/docs/index.md +16 -31
data/docs/multi_framework_support.md +4 -4
data/examples/basic_usage.rb +18 -16
data/examples/cli_app/htm_cli.rb +86 -8
data/examples/custom_llm_configuration.rb +1 -2
data/examples/example_app/app.rb +11 -14
data/examples/sinatra_app/Gemfile +1 -0
data/examples/sinatra_app/Gemfile.lock +166 -0
data/examples/sinatra_app/app.rb +219 -24
data/lib/htm/active_record_config.rb +10 -3
data/lib/htm/configuration.rb +265 -78
data/lib/htm/{sinatra.rb → integrations/sinatra.rb} +87 -12
data/lib/htm/job_adapter.rb +10 -3
data/lib/htm/long_term_memory.rb +220 -57
data/lib/htm/models/node.rb +36 -7
data/lib/htm/models/robot.rb +30 -4
data/lib/htm/models/robot_node.rb +50 -0
data/lib/htm/models/tag.rb +52 -0
data/lib/htm/models/working_memory_entry.rb +88 -0
data/lib/htm/tasks.rb +4 -0
data/lib/htm/version.rb +1 -1
data/lib/htm.rb +34 -13
data/lib/tasks/htm.rake +32 -1
data/lib/tasks/jobs.rake +7 -3
data/lib/tasks/tags.rake +34 -0
data/mkdocs.yml +56 -9
metadata +61 -31
data/dbdoc/public.node_tags.svg +0 -112
data/dbdoc/public.nodes.svg +0 -118
data/dbdoc/public.robots.svg +0 -90
data/dbdoc/schema.svg +0 -154
/data/{dbdoc → docs/database}/public.node_stats.md +0 -0
/data/{dbdoc → docs/database}/public.node_stats.svg +0 -0
/data/{dbdoc → docs/database}/public.nodes_tags.md +0 -0
/data/{dbdoc → docs/database}/public.nodes_tags.svg +0 -0
/data/{dbdoc → docs/database}/public.ontology_structure.md +0 -0
/data/{dbdoc → docs/database}/public.ontology_structure.svg +0 -0
/data/{dbdoc → docs/database}/public.operations_log.md +0 -0
/data/{dbdoc → docs/database}/public.operations_log.svg +0 -0
/data/{dbdoc → docs/database}/public.relationships.md +0 -0
/data/{dbdoc → docs/database}/public.relationships.svg +0 -0
/data/{dbdoc → docs/database}/public.robot_activity.md +0 -0
/data/{dbdoc → docs/database}/public.robot_activity.svg +0 -0
/data/{dbdoc → docs/database}/public.schema_migrations.md +0 -0
/data/{dbdoc → docs/database}/public.schema_migrations.svg +0 -0
/data/{dbdoc → docs/database}/public.tags.md +0 -0
/data/{dbdoc → docs/database}/public.tags.svg +0 -0
/data/{dbdoc → docs/database}/public.topic_relationships.md +0 -0
/data/{dbdoc → docs/database}/public.topic_relationships.svg +0 -0

data/docs/architecture/overview.md CHANGED Viewed

@@ -98,41 +98,7 @@ This diagram shows the complete flow of adding a new memory node to HTM with **c
 !!! info "Architecture Note"
     With client-side generation (October 2025), embeddings are generated in Ruby before database insertion. This provides reliable, cross-platform operation.
-```mermaid
-graph TD
-    A[User: add_message] -->|1. Request| B[HTM]
-    B -->|2. Count tokens| C[EmbeddingService]
-    C -->|3. Return count| B
-    B -->|4. Generate embedding| C
-    C -->|5. HTTP call| D[Ollama/OpenAI]
-    D -->|6. Return vector| C
-    C -->|7. Return embedding| B
-    B -->|8. Persist with embedding| E[LongTermMemory]
-    E -->|9. INSERT nodes with embedding| F[PostgreSQL]
-    F -->|10. Return node_id| E
-    E -->|11. Return node_id| B
-    B -->|12. Check space| G[WorkingMemory]
-    G -->|13. Space available?| H{Has Space?}
-    H -->|No| I[Evict nodes]
-    I -->|14. Mark evicted| E
-    H -->|Yes| J[Add to WM]
-    I --> J
-    J -->|15. Success| B
-    B -->|16. Log operation| E
-    B -->|17. Return node_id| A
-    style A fill:rgba(76,175,80,0.3)
-    style B fill:rgba(33,150,243,0.3)
-    style C fill:rgba(255,152,0,0.3)
-    style D fill:rgba(255,193,7,0.3)
-    style E fill:rgba(156,39,176,0.3)
-    style F fill:rgba(156,39,176,0.3)
-    style G fill:rgba(33,150,243,0.3)
-```
+![Memory Addition Flow](../assets/images/htm-memory-addition-flow.svg)
 ### Memory Recall Flow
@@ -141,79 +107,13 @@ This diagram illustrates the RAG-based retrieval process with **client-side quer
 !!! info "Architecture Note"
     With client-side generation, query embeddings are generated in Ruby before being passed to SQL for vector similarity search.
-```mermaid
-graph TD
-    A[User: recall] -->|1. Request| B[HTM]
-    B -->|2. Parse timeframe| C[Parse Natural Language]
-    C -->|3. Return range| B
-    B -->|4. Generate query embedding| D[EmbeddingService]
-    D -->|5. HTTP call| E[Ollama/OpenAI]
-    E -->|6. Return vector| D
-    D -->|7. Return embedding| B
-    B -->|8. Search with embedding| F[LongTermMemory]
-    F -->|9. Vector similarity| G{Search Strategy}
-    G -->|:vector| H[Vector Search]
-    G -->|:fulltext| I[Full-Text Search]
-    G -->|:hybrid| J[Hybrid Search]
-    H -->|10. pgvector HNSW| K[Return results]
-    I -->|10. ts_rank GIN| K
-    J -->|10. Hybrid + RRF| K
-    K -->|11. Results| F
-    F -->|12. Results| B
-    B -->|13. For each result| L[WorkingMemory]
-    L -->|14. Add to WM| M{Has Space?}
-    M -->|No| N[Evict old nodes]
-    P -->|Yes| R[Add node]
-    Q --> R
-    R -->|12. Log operation| E
-    B -->|13. Return memories| A
-    style A fill:rgba(76,175,80,0.3)
-    style B fill:rgba(33,150,243,0.3)
-    style E fill:rgba(156,39,176,0.3)
-    style J fill:rgba(255,193,7,0.3)
-    style O fill:rgba(33,150,243,0.3)
-```
+![Memory Recall Flow](../assets/images/htm-memory-recall-flow.svg)
 ### Context Assembly Flow
 This diagram shows how working memory assembles context for LLM consumption using different strategies.
-```mermaid
-graph TD
-    A[User: create_context] -->|1. Request with strategy| B[HTM]
-    B -->|2. Assemble| C[WorkingMemory]
-    C -->|3. Strategy?| D{Strategy Type}
-    D -->|:recent| E[Sort by access order]
-    D -->|:important| F[Sort by importance]
-    D -->|:balanced| G[Hybrid score]
-    E --> H[Sorted nodes]
-    F --> H
-    G --> H
-    H -->|4. Build context| I[Token budget loop]
-    I -->|5. Check tokens| J{Tokens < max?}
-    J -->|Yes| K[Add node to context]
-    J -->|No| L[Stop, return context]
-    K --> I
-    L -->|6. Join nodes| M[Assembled context string]
-    M -->|7. Return| C
-    C -->|8. Return| B
-    B -->|9. Return| A
-    style A fill:rgba(76,175,80,0.3)
-    style C fill:rgba(33,150,243,0.3)
-    style G fill:rgba(255,193,7,0.3)
-```
+![Context Assembly Flow](../assets/images/htm-context-assembly-flow.svg)
 ## Memory Lifecycle
@@ -221,79 +121,13 @@ graph TD
 A memory node transitions through several states during its lifetime in HTM:
-```mermaid
-stateDiagram-v2
-    [*] --> Created: add_node()
-    Created --> InBothMemories: Initial state
-    InBothMemories --> WorkingMemoryOnly: Evicted from WM
-    InBothMemories --> LongTermMemoryOnly: WM cleared
-    WorkingMemoryOnly --> InBothMemories: Recalled
-    LongTermMemoryOnly --> InBothMemories: Recalled
-    InBothMemories --> Forgotten: forget(confirm: :confirmed)
-    WorkingMemoryOnly --> Forgotten: forget(confirm: :confirmed)
-    LongTermMemoryOnly --> Forgotten: forget(confirm: :confirmed)
-    Forgotten --> [*]
-    note right of InBothMemories
-        Node exists in:
-        - Working Memory (fast access)
-        - Long-Term Memory (persistent)
-        in_working_memory = TRUE
-    end note
-    note right of WorkingMemoryOnly
-        Node exists only in:
-        - Long-Term Memory
-        in_working_memory = FALSE
-        (Evicted due to token limit)
-    end note
-    note right of Forgotten
-        Node permanently deleted
-        from both memories
-        (Explicit user action)
-    end note
-```
+![Node States](../assets/images/htm-node-states.svg)
 ### Eviction Process
 When working memory reaches its token limit, the eviction process runs to free up space:
-```mermaid
-sequenceDiagram
-    participant User
-    participant HTM
-    participant WM as WorkingMemory
-    participant LTM as LongTermMemory
-    participant DB as Database
-    User->>HTM: add_node(large_memory)
-    HTM->>WM: add(key, value, token_count)
-    WM->>WM: Check: token_count + current > max?
-    alt Space Available
-        WM->>WM: Add node directly
-        WM-->>HTM: Success
-    else No Space
-        WM->>WM: Sort by [importance, -recency]
-        WM->>WM: Evict low-importance old nodes
-        Note over WM: Free enough tokens
-        WM->>HTM: Return evicted nodes
-        HTM->>LTM: mark_evicted(keys)
-        LTM->>DB: UPDATE in_working_memory = FALSE
-        DB-->>LTM: Updated
-        WM->>WM: Add new node
-        WM-->>HTM: Success
-    end
-    HTM-->>User: node_id
-```
+![Eviction Process](../assets/images/htm-eviction-process.svg)
 ## Database Schema

data/docs/architecture/two-tier-memory.md CHANGED Viewed

@@ -645,41 +645,7 @@ With TimescaleDB compression (after 30 days):
 ### Complete Flow Diagram
-```mermaid
-graph TB
-    subgraph "1. Add Memory"
-        A[User: add_node] --> B[Generate embedding]
-        B --> C[Store in LTM]
-        C --> D{WM has space?}
-        D -->|Yes| E[Add to WM]
-        D -->|No| F[Evict from WM]
-        F --> G[Mark evicted in LTM]
-        G --> E
-    end
-    subgraph "2. Memory States"
-        E --> H[In Both Memories]
-        G --> I[In LTM Only]
-    end
-    subgraph "3. Recall Memory"
-        J[User: recall] --> K[RAG Search in LTM]
-        K --> L[Results found]
-        L --> M{WM has space?}
-        M -->|Yes| N[Add to WM]
-        M -->|No| O[Evict from WM]
-        O --> N
-        N --> H
-    end
-    I -.recall.-> J
-    H -.already loaded.-> P[Return from WM]
-    style A fill:rgba(76,175,80,0.3)
-    style J fill:rgba(33,150,243,0.3)
-    style H fill:rgba(255,193,7,0.3)
-    style I fill:rgba(156,39,176,0.3)
-```
+![Complete Memory Flow](../assets/images/htm-complete-memory-flow.svg)
 ### Example: Adding 5000-Token Memory to Full Working Memory

data/docs/assets/images/adr-010-current-architecture.svg ADDED Viewed

@@ -0,0 +1,37 @@
+<svg viewBox="0 0 700 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="350" y="30" text-anchor="middle" fill="#FFFFFF" font-size="18" font-weight="bold">Current Two-Tier Architecture</text>
+  <!-- HTM Instance outer box -->
+  <rect x="50" y="70" width="300" height="280" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="200" y="100" text-anchor="middle" fill="#FFFFFF" font-size="15" font-weight="bold">HTM Instance</text>
+  <!-- Working Memory -->
+  <rect x="90" y="140" width="180" height="100" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="180" y="170" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Working Memory</text>
+  <text x="180" y="195" text-anchor="middle" fill="#B0B0B0" font-size="12">(Hash)</text>
+  <text x="180" y="220" text-anchor="middle" fill="#FFC107" font-size="11" font-style="italic">volatile</text>
+  <!-- PostgreSQL -->
+  <rect x="450" y="140" width="200" height="100" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="550" y="170" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">PostgreSQL</text>
+  <text x="550" y="195" text-anchor="middle" fill="#B0B0B0" font-size="12">(Long-Term)</text>
+  <text x="550" y="220" text-anchor="middle" fill="#4CAF50" font-size="11" font-style="italic">persistent</text>
+  <!-- Arrow from Working Memory to PostgreSQL -->
+  <path d="M 270 190 L 450 190" stroke="#2196F3" stroke-width="3" fill="none" marker-end="url(#arrow1)"/>
+  <text x="360" y="180" text-anchor="middle" fill="#2196F3" font-size="11">syncs to</text>
+  <!-- Notes -->
+  <rect x="50" y="280" width="300" height="60" fill="rgba(255, 193, 7, 0.1)" stroke="#FFC107" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="60" y="300" fill="#B0B0B0" font-size="11">• <tspan fill="#4CAF50" font-weight="bold">Working Memory</tspan>: Fast, in-memory hash</text>
+  <text x="60" y="318" fill="#B0B0B0" font-size="11">• <tspan fill="#9C27B0" font-weight="bold">Long-Term Memory</tspan>: Durable PostgreSQL</text>
+  <text x="60" y="336" fill="#B0B0B0" font-size="11">• Simple, proven architecture</text>
+  <!-- Markers -->
+  <defs>
+    <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
+    </marker>
+  </defs>
+</svg>

data/docs/assets/images/adr-010-proposed-architecture.svg ADDED Viewed

@@ -0,0 +1,48 @@
+<svg viewBox="0 0 700 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="350" y="30" text-anchor="middle" fill="#FFFFFF" font-size="18" font-weight="bold">Proposed Three-Tier Architecture (Rejected)</text>
+  <!-- HTM Instance outer box -->
+  <rect x="50" y="70" width="300" height="280" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="200" y="100" text-anchor="middle" fill="#FFFFFF" font-size="15" font-weight="bold">HTM Instance</text>
+  <!-- Double arrow down -->
+  <path d="M 180 120 L 180 160" stroke="#FFC107" stroke-width="3" fill="none" marker-end="url(#arrow2)"/>
+  <path d="M 220 120 L 220 160" stroke="#FFC107" stroke-width="3" fill="none" marker-end="url(#arrow2)"/>
+  <!-- Redis (Working) -->
+  <rect x="90" y="160" width="180" height="100" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8" stroke-dasharray="5,5"/>
+  <text x="180" y="190" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Redis</text>
+  <text x="180" y="215" text-anchor="middle" fill="#B0B0B0" font-size="12">(Working)</text>
+  <text x="180" y="240" text-anchor="middle" fill="#4CAF50" font-size="11" font-style="italic">persistent</text>
+  <!-- PostgreSQL -->
+  <rect x="450" y="160" width="200" height="100" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="550" y="190" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">PostgreSQL</text>
+  <text x="550" y="215" text-anchor="middle" fill="#B0B0B0" font-size="12">(Long-Term)</text>
+  <text x="550" y="240" text-anchor="middle" fill="#4CAF50" font-size="11" font-style="italic">persistent</text>
+  <!-- Arrow from Redis to PostgreSQL -->
+  <path d="M 270 210 L 450 210" stroke="#2196F3" stroke-width="3" fill="none" marker-end="url(#arrow1)"/>
+  <text x="360" y="200" text-anchor="middle" fill="#2196F3" font-size="11">syncs to</text>
+  <!-- Rejection stamp -->
+  <rect x="220" y="60" width="160" height="40" fill="rgba(244, 67, 54, 0.2)" stroke="#F44336" stroke-width="3" rx="5" transform="rotate(-15 300 80)"/>
+  <text x="300" y="85" text-anchor="middle" fill="#F44336" font-size="18" font-weight="bold" transform="rotate(-15 300 85)">REJECTED</text>
+  <!-- Notes -->
+  <rect x="50" y="280" width="300" height="60" fill="rgba(244, 67, 54, 0.1)" stroke="#F44336" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="60" y="300" fill="#B0B0B0" font-size="11">• <tspan fill="#F44336" font-weight="bold">Redis layer</tspan>: Adds complexity</text>
+  <text x="60" y="318" fill="#B0B0B0" font-size="11">• Requires infrastructure management</text>
+  <text x="60" y="336" fill="#B0B0B0" font-size="11">• In-memory hash sufficient for working memory</text>
+  <!-- Markers -->
+  <defs>
+    <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
+    </marker>
+    <marker id="arrow2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#FFC107"/>
+    </marker>
+  </defs>
+</svg>

data/docs/assets/images/adr-dependency-tree.svg ADDED Viewed

@@ -0,0 +1,93 @@
+<svg viewBox="0 0 800 600" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="400" y="30" text-anchor="middle" fill="#FFFFFF" font-size="18" font-weight="bold">ADR Dependency Tree</text>
+  <!-- ADR-001 (Root) -->
+  <rect x="300" y="70" width="200" height="50" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="400" y="100" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">ADR-001 (Storage)</text>
+  <!-- Branch lines from ADR-001 -->
+  <path d="M 400 120 L 400 150" stroke="#4CAF50" stroke-width="2" fill="none"/>
+  <path d="M 400 150 L 150 150 L 150 180" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 400 150 L 400 180" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 400 150 L 650 150 L 650 180" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <!-- ADR-002 (Two-Tier Memory) -->
+  <rect x="50" y="180" width="200" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="150" y="210" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">ADR-002 (Two-Tier Memory)</text>
+  <!-- ADR-003 (Embeddings) -->
+  <rect x="300" y="180" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="3" rx="8"/>
+  <text x="400" y="210" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">ADR-003 (Embeddings)</text>
+  <!-- ADR-004 (Hive Mind) -->
+  <rect x="550" y="180" width="200" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="650" y="210" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">ADR-004 (Hive Mind)</text>
+  <!-- Branch lines from ADR-002 -->
+  <path d="M 150 230 L 150 270" stroke="#2196F3" stroke-width="2" fill="none"/>
+  <path d="M 150 270 L 40 270 L 40 300" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <path d="M 150 270 L 150 300" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <path d="M 150 270 L 260 270 L 260 300" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <!-- ADR-007 (Eviction Strategy) -->
+  <rect x="10" y="300" width="180" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="2" rx="6"/>
+  <text x="100" y="328" text-anchor="middle" fill="#FFFFFF" font-size="12">ADR-007 (Eviction Strategy)</text>
+  <!-- ADR-009 (Never-Forget) -->
+  <rect x="70" y="370" width="160" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="2" rx="6"/>
+  <text x="150" y="398" text-anchor="middle" fill="#FFFFFF" font-size="12">ADR-009 (Never-Forget)</text>
+  <!-- ADR-010 (Redis WM - Rejected) -->
+  <rect x="210" y="300" width="200" height="50" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="2" rx="6" stroke-dasharray="5,5"/>
+  <text x="310" y="320" text-anchor="middle" fill="#FFFFFF" font-size="11">ADR-010 (Redis WM)</text>
+  <text x="310" y="338" text-anchor="middle" fill="#F44336" font-size="10" font-weight="bold">Rejected Alternative</text>
+  <!-- Branch line from ADR-003 -->
+  <path d="M 400 230 L 400 290" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrow3)"/>
+  <!-- ADR-005 (RAG Retrieval) -->
+  <rect x="310" y="290" width="180" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
+  <text x="400" y="318" text-anchor="middle" fill="#FFFFFF" font-size="12">ADR-005 (RAG Retrieval)</text>
+  <!-- Branch line from ADR-004 -->
+  <path d="M 650 230 L 650 290" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <!-- ADR-008 (Robot ID) -->
+  <rect x="560" y="290" width="180" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="2" rx="6"/>
+  <text x="650" y="318" text-anchor="middle" fill="#FFFFFF" font-size="12">ADR-008 (Robot ID)</text>
+  <!-- ADR-006 (Context Assembly) -->
+  <rect x="310" y="480" width="180" height="50" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3" rx="8"/>
+  <text x="400" y="508" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">ADR-006 (Context Assembly)</text>
+  <!-- Branch line from ADR-001 to ADR-006 -->
+  <path d="M 400 120 L 480 120 L 480 470 L 400 470 L 400 480" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrow5)"/>
+  <!-- Legend -->
+  <rect x="30" y="480" width="220" height="100" fill="rgba(33, 150, 243, 0.1)" stroke="#2196F3" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="140" y="500" text-anchor="middle" fill="#2196F3" font-size="12" font-weight="bold">Legend</text>
+  <text x="40" y="520" fill="#B0B0B0" font-size="10">• <tspan fill="#4CAF50" font-weight="bold">Green</tspan>: Foundation</text>
+  <text x="40" y="538" fill="#B0B0B0" font-size="10">• <tspan fill="#2196F3" font-weight="bold">Blue</tspan>: Memory architecture</text>
+  <text x="40" y="556" fill="#B0B0B0" font-size="10">• <tspan fill="#FF9800" font-weight="bold">Orange</tspan>: Search/retrieval</text>
+  <text x="40" y="574" fill="#B0B0B0" font-size="10">• <tspan fill="#9C27B0" font-weight="bold">Purple</tspan>: Multi-robot features</text>
+  <!-- Markers -->
+  <defs>
+    <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
+    </marker>
+    <marker id="arrow2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
+    </marker>
+    <marker id="arrow3" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
+    </marker>
+    <marker id="arrow4" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
+    </marker>
+    <marker id="arrow5" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#FFC107"/>
+    </marker>
+  </defs>
+</svg>

data/docs/assets/images/class-hierarchy.svg ADDED Viewed

@@ -0,0 +1,55 @@
+<svg viewBox="0 0 700 450" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="350" y="30" text-anchor="middle" fill="#FFFFFF" font-size="18" font-weight="bold">HTM Class Hierarchy</text>
+  <!-- HTM main class -->
+  <rect x="220" y="70" width="260" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="350" y="105" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">HTM (main class)</text>
+  <!-- Branch lines -->
+  <path d="M 350 130 L 350 170" stroke="#4CAF50" stroke-width="2" fill="none"/>
+  <path d="M 350 170 L 100 170 L 100 200" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 350 170 L 250 170 L 250 200" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 350 170 L 450 170 L 450 200" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 350 170 L 600 170 L 600 200" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <!-- HTM::WorkingMemory -->
+  <rect x="10" y="200" width="180" height="80" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="2" rx="6"/>
+  <text x="100" y="225" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">HTM::WorkingMemory</text>
+  <text x="100" y="245" text-anchor="middle" fill="#B0B0B0" font-size="10">Token-limited</text>
+  <text x="100" y="263" text-anchor="middle" fill="#B0B0B0" font-size="10">active context</text>
+  <!-- HTM::LongTermMemory -->
+  <rect x="210" y="200" width="190" height="80" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="2" rx="6"/>
+  <text x="305" y="225" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">HTM::LongTermMemory</text>
+  <text x="305" y="245" text-anchor="middle" fill="#B0B0B0" font-size="10">PostgreSQL</text>
+  <text x="305" y="263" text-anchor="middle" fill="#B0B0B0" font-size="10">backend</text>
+  <!-- HTM::EmbeddingService -->
+  <rect x="420" y="200" width="190" height="80" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
+  <text x="515" y="225" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">HTM::EmbeddingService</text>
+  <text x="515" y="245" text-anchor="middle" fill="#B0B0B0" font-size="10">Vector</text>
+  <text x="515" y="263" text-anchor="middle" fill="#B0B0B0" font-size="10">embeddings</text>
+  <!-- HTM::Database -->
+  <rect x="510" y="200" width="180" height="80" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="2" rx="6"/>
+  <text x="600" y="225" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">HTM::Database</text>
+  <text x="600" y="245" text-anchor="middle" fill="#B0B0B0" font-size="10">Schema setup</text>
+  <text x="600" y="263" text-anchor="middle" fill="#B0B0B0" font-size="10">&amp; configuration</text>
+  <!-- Legend -->
+  <rect x="50" y="320" width="600" height="100" fill="rgba(33, 150, 243, 0.1)" stroke="#2196F3" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="350" y="345" text-anchor="middle" fill="#2196F3" font-size="13" font-weight="bold">Component Roles</text>
+  <text x="70" y="370" fill="#B0B0B0" font-size="10">• <tspan fill="#4CAF50" font-weight="bold">HTM</tspan>: Main API interface coordinating all components</text>
+  <text x="70" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#2196F3" font-weight="bold">WorkingMemory</tspan>: Fast, token-limited in-memory cache</text>
+  <text x="70" y="406" fill="#B0B0B0" font-size="10">• <tspan fill="#9C27B0" font-weight="bold">LongTermMemory</tspan>: Durable PostgreSQL storage with RAG search</text>
+  <text x="380" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#FF9800" font-weight="bold">EmbeddingService</tspan>: Vector generation via Ollama/OpenAI</text>
+  <text x="380" y="406" fill="#B0B0B0" font-size="10">• <tspan fill="#FFC107" font-weight="bold">Database</tspan>: Schema management and connections</text>
+  <!-- Markers -->
+  <defs>
+    <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
+    </marker>
+  </defs>
+</svg>

data/docs/assets/images/exception-hierarchy.svg ADDED Viewed

@@ -0,0 +1,45 @@
+<svg viewBox="0 0 700 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="350" y="30" text-anchor="middle" fill="#FFFFFF" font-size="18" font-weight="bold">HTM Exception Hierarchy</text>
+  <!-- HTM::EmbeddingError (root) -->
+  <rect x="200" y="70" width="300" height="60" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8"/>
+  <text x="350" y="105" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">HTM::EmbeddingError</text>
+  <!-- Branch lines -->
+  <path d="M 350 130 L 350 170" stroke="#F44336" stroke-width="2" fill="none"/>
+  <path d="M 350 170 L 120 170 L 120 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 350 170 L 270 170 L 270 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 350 170 L 430 170 L 430 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 350 170 L 580 170 L 580 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <!-- Ollama connection failed -->
+  <rect x="20" y="200" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
+  <text x="120" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Ollama connection failed"</text>
+  <!-- OpenAI API error -->
+  <rect x="240" y="200" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
+  <text x="340" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"OpenAI API error: ..."</text>
+  <!-- Invalid model -->
+  <rect x="460" y="200" width="160" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
+  <text x="540" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Invalid model: ..."</text>
+  <!-- Empty text provided -->
+  <rect x="460" y="200" width="190" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
+  <text x="555" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Empty text provided"</text>
+  <!-- Legend -->
+  <rect x="50" y="290" width="600" height="90" fill="rgba(244, 67, 54, 0.1)" stroke="#F44336" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="350" y="315" text-anchor="middle" fill="#F44336" font-size="13" font-weight="bold">Exception Types</text>
+  <text x="70" y="340" fill="#B0B0B0" font-size="10">• <tspan fill="#F44336" font-weight="bold">HTM::EmbeddingError</tspan>: Base class for all embedding-related errors</text>
+  <text x="70" y="360" fill="#B0B0B0" font-size="10">• All errors include descriptive messages indicating the specific failure</text>
+  <text x="70" y="378" fill="#B0B0B0" font-size="10">• Errors can occur from: Connection failures, API errors, invalid input, or configuration issues</text>
+  <!-- Markers -->
+  <defs>
+    <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#F44336"/>
+    </marker>
+  </defs>
+</svg>

data/docs/assets/images/htm-architecture-overview.svg ADDED Viewed

@@ -0,0 +1,83 @@
+<svg viewBox="0 0 900 700" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="450" y="30" text-anchor="middle" fill="#FFFFFF" font-size="20" font-weight="bold">HTM Architecture Overview</text>
+  <!-- Your LLM -->
+  <rect x="250" y="70" width="400" height="80" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="450" y="105" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">Your LLM</text>
+  <text x="450" y="130" text-anchor="middle" fill="#B0B0B0" font-size="13">(Claude, GPT, etc.)</text>
+  <!-- Arrow down -->
+  <path d="M 450 150 L 450 190" stroke="#2196F3" stroke-width="3" fill="none" marker-end="url(#arrow1)"/>
+  <!-- HTM API -->
+  <rect x="200" y="190" width="500" height="80" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="450" y="225" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">HTM API</text>
+  <text x="450" y="250" text-anchor="middle" fill="#B0B0B0" font-size="13">add_node(), recall(), create_context(), etc.</text>
+  <!-- Arrows down to both memories -->
+  <path d="M 320 270 L 320 330" stroke="#2196F3" stroke-width="3" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 580 270 L 580 330" stroke="#9C27B0" stroke-width="3" fill="none" marker-end="url(#arrow2)"/>
+  <!-- Working Memory -->
+  <rect x="120" y="330" width="280" height="120" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="260" y="370" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">Working Memory</text>
+  <text x="260" y="395" text-anchor="middle" fill="#B0B0B0" font-size="13">(In-Memory)</text>
+  <text x="260" y="418" text-anchor="middle" fill="#B0B0B0" font-size="13">128k tokens</text>
+  <text x="260" y="438" text-anchor="middle" fill="#B0B0B0" font-size="13">Fast access</text>
+  <!-- Long-term Memory -->
+  <rect x="500" y="330" width="280" height="120" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="640" y="370" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">Long-term Memory</text>
+  <text x="640" y="395" text-anchor="middle" fill="#B0B0B0" font-size="13">(PostgreSQL)</text>
+  <text x="640" y="418" text-anchor="middle" fill="#B0B0B0" font-size="13">∞ storage</text>
+  <text x="640" y="438" text-anchor="middle" fill="#B0B0B0" font-size="13">Persistent</text>
+  <!-- Bidirectional arrow between Working and Long-term Memory -->
+  <path d="M 400 380 L 500 380" stroke="#FFC107" stroke-width="3" fill="none" marker-end="url(#arrow3)" marker-start="url(#arrow3-start)"/>
+  <text x="450" y="370" text-anchor="middle" fill="#FFC107" font-size="12" font-weight="bold">Eviction</text>
+  <path d="M 500 400 L 400 400" stroke="#4CAF50" stroke-width="3" fill="none" marker-end="url(#arrow4)" marker-start="url(#arrow4-start)"/>
+  <text x="450" y="418" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Recall</text>
+  <!-- Arrow down from Long-term Memory -->
+  <path d="M 640 450 L 640 520" stroke="#9C27B0" stroke-width="3" fill="none" marker-end="url(#arrow2)"/>
+  <!-- Embedding Service -->
+  <rect x="500" y="520" width="280" height="100" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="3" rx="8"/>
+  <text x="640" y="555" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">Embedding Service</text>
+  <text x="640" y="580" text-anchor="middle" fill="#B0B0B0" font-size="13">(Ollama/RubyLLM)</text>
+  <text x="640" y="603" text-anchor="middle" fill="#B0B0B0" font-size="13">gpt-oss model</text>
+  <!-- Notes -->
+  <rect x="30" y="500" width="360" height="160" fill="rgba(33, 150, 243, 0.1)" stroke="#2196F3" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="210" y="525" text-anchor="middle" fill="#2196F3" font-size="14" font-weight="bold">Key Components</text>
+  <text x="40" y="550" fill="#B0B0B0" font-size="11">• <tspan fill="#4CAF50" font-weight="bold">Your LLM</tspan>: Chat interface (Claude, GPT, etc.)</text>
+  <text x="40" y="570" fill="#B0B0B0" font-size="11">• <tspan fill="#2196F3" font-weight="bold">HTM API</tspan>: Main interface for memory operations</text>
+  <text x="40" y="590" fill="#B0B0B0" font-size="11">• <tspan fill="#2196F3" font-weight="bold">Working Memory</tspan>: Fast, token-limited cache</text>
+  <text x="40" y="610" fill="#B0B0B0" font-size="11">• <tspan fill="#9C27B0" font-weight="bold">Long-term Memory</tspan>: Durable PostgreSQL storage</text>
+  <text x="40" y="630" fill="#B0B0B0" font-size="11">• <tspan fill="#FF9800" font-weight="bold">Embedding Service</tspan>: Vector generation via Ollama</text>
+  <text x="40" y="650" fill="#B0B0B0" font-size="11">• <tspan fill="#FFC107" font-weight="bold">Eviction/Recall</tspan>: Automatic memory management</text>
+  <!-- Markers -->
+  <defs>
+    <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
+    </marker>
+    <marker id="arrow2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
+    </marker>
+    <marker id="arrow3" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#FFC107"/>
+    </marker>
+    <marker id="arrow3-start" markerWidth="10" markerHeight="10" refX="1" refY="3" orient="auto">
+      <polygon points="10 0, 0 3, 10 6" fill="#FFC107"/>
+    </marker>
+    <marker id="arrow4" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
+    </marker>
+    <marker id="arrow4-start" markerWidth="10" markerHeight="10" refX="1" refY="3" orient="auto">
+      <polygon points="10 0, 0 3, 10 6" fill="#4CAF50"/>
+    </marker>
+  </defs>
+</svg>