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

htm 0.0.1 → 0.0.10

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 (184) hide show

checksums.yaml +4 -4
data/.aigcm_msg +1 -0
data/.architecture/reviews/comprehensive-codebase-review.md +577 -0
data/.claude/settings.local.json +92 -0
data/.envrc +1 -0
data/.irbrc +283 -80
data/.tbls.yml +31 -0
data/CHANGELOG.md +314 -16
data/CLAUDE.md +603 -0
data/README.md +76 -5
data/Rakefile +5 -0
data/SETUP.md +132 -101
data/db/migrate/{20250101000001_enable_extensions.rb → 00001_enable_extensions.rb} +0 -1
data/db/migrate/00002_create_robots.rb +11 -0
data/db/migrate/00003_create_file_sources.rb +20 -0
data/db/migrate/00004_create_nodes.rb +65 -0
data/db/migrate/00005_create_tags.rb +13 -0
data/db/migrate/00006_create_node_tags.rb +18 -0
data/db/migrate/00007_create_robot_nodes.rb +26 -0
data/db/migrate/00009_add_working_memory_to_robot_nodes.rb +12 -0
data/db/schema.sql +390 -36
data/docs/api/database.md +19 -232
data/docs/api/embedding-service.md +1 -7
data/docs/api/htm.md +305 -364
data/docs/api/index.md +1 -7
data/docs/api/long-term-memory.md +342 -590
data/docs/api/yard/HTM/ActiveRecordConfig.md +23 -0
data/docs/api/yard/HTM/AuthorizationError.md +11 -0
data/docs/api/yard/HTM/CircuitBreaker.md +92 -0
data/docs/api/yard/HTM/CircuitBreakerOpenError.md +34 -0
data/docs/api/yard/HTM/Configuration.md +175 -0
data/docs/api/yard/HTM/Database.md +99 -0
data/docs/api/yard/HTM/DatabaseError.md +14 -0
data/docs/api/yard/HTM/EmbeddingError.md +18 -0
data/docs/api/yard/HTM/EmbeddingService.md +58 -0
data/docs/api/yard/HTM/Error.md +11 -0
data/docs/api/yard/HTM/JobAdapter.md +39 -0
data/docs/api/yard/HTM/LongTermMemory.md +342 -0
data/docs/api/yard/HTM/NotFoundError.md +17 -0
data/docs/api/yard/HTM/Observability.md +107 -0
data/docs/api/yard/HTM/QueryTimeoutError.md +19 -0
data/docs/api/yard/HTM/Railtie.md +27 -0
data/docs/api/yard/HTM/ResourceExhaustedError.md +13 -0
data/docs/api/yard/HTM/TagError.md +18 -0
data/docs/api/yard/HTM/TagService.md +67 -0
data/docs/api/yard/HTM/Timeframe/Result.md +24 -0
data/docs/api/yard/HTM/Timeframe.md +40 -0
data/docs/api/yard/HTM/TimeframeExtractor/Result.md +24 -0
data/docs/api/yard/HTM/TimeframeExtractor.md +45 -0
data/docs/api/yard/HTM/ValidationError.md +20 -0
data/docs/api/yard/HTM/WorkingMemory.md +131 -0
data/docs/api/yard/HTM.md +80 -0
data/docs/api/yard/index.csv +179 -0
data/docs/api/yard-reference.md +51 -0
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 +127 -125
data/docs/database/public.file_sources.md +42 -0
data/docs/database/public.file_sources.svg +211 -0
data/{dbdoc → docs/database}/public.node_tags.md +7 -8
data/docs/database/public.node_tags.svg +239 -0
data/{dbdoc → docs/database}/public.nodes.md +22 -17
data/docs/database/public.nodes.svg +271 -0
data/docs/database/public.robot_nodes.md +46 -0
data/docs/database/public.robot_nodes.svg +243 -0
data/{dbdoc → docs/database}/public.robots.md +2 -3
data/docs/database/public.robots.svg +161 -0
data/docs/database/public.tags.svg +139 -0
data/{dbdoc → docs/database}/schema.json +941 -630
data/docs/database/schema.svg +282 -0
data/docs/development/index.md +1 -29
data/docs/development/schema.md +134 -309
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 +295 -643
data/docs/guides/recalling-memories.md +36 -1
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/README.md +280 -0
data/examples/basic_usage.rb +18 -16
data/examples/cli_app/htm_cli.rb +146 -8
data/examples/cli_app/temp.log +93 -0
data/examples/custom_llm_configuration.rb +1 -2
data/examples/example_app/app.rb +11 -14
data/examples/file_loader_usage.rb +177 -0
data/examples/robot_groups/lib/robot_group.rb +419 -0
data/examples/robot_groups/lib/working_memory_channel.rb +140 -0
data/examples/robot_groups/multi_process.rb +286 -0
data/examples/robot_groups/robot_worker.rb +136 -0
data/examples/robot_groups/same_process.rb +229 -0
data/examples/sinatra_app/Gemfile +1 -0
data/examples/sinatra_app/Gemfile.lock +166 -0
data/examples/sinatra_app/app.rb +219 -24
data/examples/timeframe_demo.rb +276 -0
data/lib/htm/active_record_config.rb +10 -3
data/lib/htm/circuit_breaker.rb +202 -0
data/lib/htm/configuration.rb +313 -80
data/lib/htm/database.rb +67 -36
data/lib/htm/embedding_service.rb +39 -2
data/lib/htm/errors.rb +131 -11
data/lib/htm/{sinatra.rb → integrations/sinatra.rb} +87 -12
data/lib/htm/job_adapter.rb +10 -3
data/lib/htm/jobs/generate_embedding_job.rb +5 -4
data/lib/htm/jobs/generate_tags_job.rb +4 -0
data/lib/htm/loaders/markdown_loader.rb +263 -0
data/lib/htm/loaders/paragraph_chunker.rb +112 -0
data/lib/htm/long_term_memory.rb +601 -321
data/lib/htm/models/file_source.rb +99 -0
data/lib/htm/models/node.rb +116 -12
data/lib/htm/models/robot.rb +53 -4
data/lib/htm/models/robot_node.rb +51 -0
data/lib/htm/models/tag.rb +302 -0
data/lib/htm/observability.rb +395 -0
data/lib/htm/tag_service.rb +60 -3
data/lib/htm/tasks.rb +29 -0
data/lib/htm/timeframe.rb +194 -0
data/lib/htm/timeframe_extractor.rb +307 -0
data/lib/htm/version.rb +1 -1
data/lib/htm/working_memory.rb +165 -70
data/lib/htm.rb +352 -133
data/lib/tasks/doc.rake +300 -0
data/lib/tasks/files.rake +299 -0
data/lib/tasks/htm.rake +188 -2
data/lib/tasks/jobs.rake +10 -12
data/lib/tasks/tags.rake +194 -0
data/mkdocs.yml +91 -9
data/notes/ARCHITECTURE_REVIEW.md +1167 -0
data/notes/IMPLEMENTATION_SUMMARY.md +606 -0
data/notes/MULTI_FRAMEWORK_IMPLEMENTATION.md +451 -0
data/notes/next_steps.md +100 -0
data/notes/plan.md +627 -0
data/notes/tag_ontology_enhancement_ideas.md +222 -0
data/notes/timescaledb_removal_summary.md +200 -0
metadata +177 -37
data/db/migrate/20250101000002_create_robots.rb +0 -14
data/db/migrate/20250101000003_create_nodes.rb +0 -42
data/db/migrate/20250101000005_create_tags.rb +0 -38
data/db/migrate/20250101000007_add_node_vector_indexes.rb +0 -30
data/dbdoc/public.node_tags.svg +0 -112
data/dbdoc/public.nodes.svg +0 -118
data/dbdoc/public.robots.svg +0 -90
data/dbdoc/public.tags.svg +0 -60
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 +3 -3
/data/{dbdoc → docs/database}/public.topic_relationships.md +0 -0
/data/{dbdoc → docs/database}/public.topic_relationships.svg +0 -0

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>

data/docs/assets/images/htm-complete-memory-flow.svg ADDED Viewed

@@ -0,0 +1,160 @@
+<svg viewBox="0 0 1200 900" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
+  <!-- Title -->
+  <text x="600" y="30" text-anchor="middle" fill="#FFFFFF" font-size="22" font-weight="bold">Complete Memory Flow: Add → State → Recall</text>
+  <!-- Section 1: Add Memory -->
+  <rect x="30" y="60" width="380" height="360" fill="rgba(33, 150, 243, 0.1)" stroke="#2196F3" stroke-width="2" rx="8" stroke-dasharray="10,5"/>
+  <text x="220" y="85" text-anchor="middle" fill="#2196F3" font-size="16" font-weight="bold">1. Add Memory</text>
+  <!-- User: add_node -->
+  <rect x="120" y="110" width="200" height="50" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="220" y="140" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">User: add_node()</text>
+  <!-- Generate embedding -->
+  <rect x="120" y="190" width="200" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="220" y="220" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Generate embedding</text>
+  <!-- Store in LTM -->
+  <rect x="120" y="270" width="200" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="220" y="300" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Store in LTM</text>
+  <!-- Decision: WM has space? -->
+  <polygon points="220,390 270,350 320,390 270,430" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3"/>
+  <text x="270" y="385" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">WM has</text>
+  <text x="270" y="402" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">space?</text>
+  <!-- Evict from WM -->
+  <rect x="50" y="470" width="130" height="50" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8"/>
+  <text x="115" y="500" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Evict from WM</text>
+  <!-- Mark evicted in LTM -->
+  <rect x="50" y="550" width="130" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="115" y="575" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Mark evicted</text>
+  <text x="115" y="590" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">in LTM</text>
+  <!-- Add to WM -->
+  <rect x="260" y="470" width="130" height="50" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="325" y="500" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Add to WM</text>
+  <!-- Arrows for Add Memory flow -->
+  <path d="M 220 160 L 220 190" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
+  <path d="M 220 240 L 220 270" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <path d="M 220 320 L 220 350" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrow3)"/>
+  <!-- Yes path -->
+  <path d="M 270 430 L 270 450 L 325 450 L 325 470" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <text x="285" y="445" text-anchor="start" fill="#4CAF50" font-size="11" font-weight="bold">Yes</text>
+  <!-- No path -->
+  <path d="M 220 390 L 180 390 L 180 465 L 115 465 L 115 470" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow5)"/>
+  <text x="160" y="385" text-anchor="end" fill="#F44336" font-size="11" font-weight="bold">No</text>
+  <path d="M 115 520 L 115 550" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <path d="M 115 600 L 115 640 L 325 640 L 325 520" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <!-- Section 2: Memory States -->
+  <rect x="460" y="60" width="280" height="360" fill="rgba(255, 193, 7, 0.1)" stroke="#FFC107" stroke-width="2" rx="8" stroke-dasharray="10,5"/>
+  <text x="600" y="85" text-anchor="middle" fill="#FFC107" font-size="16" font-weight="bold">2. Memory States</text>
+  <!-- In Both Memories -->
+  <rect x="480" y="470" width="220" height="80" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3" rx="8"/>
+  <text x="590" y="500" text-anchor="middle" fill="#FFFFFF" font-size="15" font-weight="bold">In Both Memories</text>
+  <text x="590" y="520" text-anchor="middle" fill="#B0B0B0" font-size="11">(Working + Long-Term)</text>
+  <text x="590" y="538" text-anchor="middle" fill="#B0B0B0" font-size="11">Fast access + Persistent</text>
+  <!-- In LTM Only -->
+  <rect x="480" y="580" width="220" height="80" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="590" y="610" text-anchor="middle" fill="#FFFFFF" font-size="15" font-weight="bold">In LTM Only</text>
+  <text x="590" y="630" text-anchor="middle" fill="#B0B0B0" font-size="11">(Evicted from WM)</text>
+  <text x="590" y="648" text-anchor="middle" fill="#B0B0B0" font-size="11">Persistent storage only</text>
+  <!-- Arrows to states -->
+  <path d="M 390 495 L 480 510" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <path d="M 180 620 L 400 620 L 400 700 L 590 700 L 590 660" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <!-- Section 3: Recall Memory -->
+  <rect x="790" y="60" width="380" height="360" fill="rgba(156, 39, 176, 0.1)" stroke="#9C27B0" stroke-width="2" rx="8" stroke-dasharray="10,5"/>
+  <text x="980" y="85" text-anchor="middle" fill="#9C27B0" font-size="16" font-weight="bold">3. Recall Memory</text>
+  <!-- User: recall -->
+  <rect x="880" y="110" width="200" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
+  <text x="980" y="140" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">User: recall()</text>
+  <!-- RAG Search in LTM -->
+  <rect x="880" y="190" width="200" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
+  <text x="980" y="220" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">RAG Search in LTM</text>
+  <!-- Results found -->
+  <rect x="880" y="270" width="200" height="50" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="980" y="300" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Results found</text>
+  <!-- Decision: WM has space? -->
+  <polygon points="980,390 1030,350 1080,390 1030,430" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3"/>
+  <text x="1030" y="385" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">WM has</text>
+  <text x="1030" y="402" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">space?</text>
+  <!-- Evict from WM (recall) -->
+  <rect x="810" y="470" width="130" height="50" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8"/>
+  <text x="875" y="500" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Evict from WM</text>
+  <!-- Add to WM (recall) -->
+  <rect x="1020" y="470" width="130" height="50" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="1085" y="500" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Add to WM</text>
+  <!-- Arrows for Recall flow -->
+  <path d="M 980 160 L 980 190" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
+  <path d="M 980 240 L 980 270" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <path d="M 980 320 L 980 350" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrow3)"/>
+  <!-- Yes path (recall) -->
+  <path d="M 1030 430 L 1030 450 L 1085 450 L 1085 470" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <text x="1045" y="445" text-anchor="start" fill="#4CAF50" font-size="11" font-weight="bold">Yes</text>
+  <!-- No path (recall) -->
+  <path d="M 980 390 L 940 390 L 940 465 L 875 465 L 875 470" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow5)"/>
+  <text x="920" y="385" text-anchor="end" fill="#F44336" font-size="11" font-weight="bold">No</text>
+  <path d="M 875 520 L 875 640 L 1085 640 L 1085 520" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <!-- Connection to In Both Memories -->
+  <path d="M 1020 495 L 840 495 L 840 510 L 700 510" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
+  <!-- Dotted lines for recall and already loaded -->
+  <path d="M 700 620 L 760 620 L 760 135 L 880 135" stroke="#9C27B0" stroke-width="2" fill="none" stroke-dasharray="5,5" marker-end="url(#arrow2)"/>
+  <text x="770" y="375" text-anchor="start" fill="#9C27B0" font-size="11" font-style="italic">recall</text>
+  <!-- Return from WM -->
+  <rect x="480" y="760" width="220" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
+  <text x="590" y="795" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Return from WM</text>
+  <path d="M 590 550 L 590 680 L 420 680 L 420 790 L 480 790" stroke="#4CAF50" stroke-width="2" fill="none" stroke-dasharray="5,5" marker-end="url(#arrow4)"/>
+  <text x="430" y="735" text-anchor="start" fill="#4CAF50" font-size="11" font-style="italic">already loaded</text>
+  <!-- Notes -->
+  <rect x="30" y="720" width="380" height="150" fill="rgba(33, 150, 243, 0.1)" stroke="#2196F3" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
+  <text x="220" y="745" text-anchor="middle" fill="#2196F3" font-size="13" font-weight="bold">Key Concepts</text>
+  <text x="40" y="770" fill="#B0B0B0" font-size="11">• <tspan fill="#4CAF50" font-weight="bold">Green paths</tspan>: Successful operations</text>
+  <text x="40" y="790" fill="#B0B0B0" font-size="11">• <tspan fill="#F44336" font-weight="bold">Red paths</tspan>: Eviction required (no space)</text>
+  <text x="40" y="810" fill="#B0B0B0" font-size="11">• <tspan fill="#FFC107" font-weight="bold">Yellow states</tspan>: Both memories (optimal)</text>
+  <text x="40" y="830" fill="#B0B0B0" font-size="11">• <tspan fill="#9C27B0" font-weight="bold">Purple states</tspan>: LTM only (evicted)</text>
+  <text x="40" y="850" fill="#B0B0B0" font-size="11">• <tspan fill="#2196F3" font-weight="bold">Dotted lines</tspan>: Conditional flows</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="arrow4" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
+    </marker>
+    <marker id="arrow5" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#F44336"/>
+    </marker>
+  </defs>
+</svg>