htm 0.0.18 → 0.0.20

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 (72) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +59 -1
  3. data/README.md +12 -0
  4. data/db/seeds.rb +1 -1
  5. data/docs/api/embedding-service.md +140 -110
  6. data/docs/api/yard/HTM/ActiveRecordConfig.md +6 -0
  7. data/docs/api/yard/HTM/Config.md +173 -0
  8. data/docs/api/yard/HTM/ConfigSection.md +28 -0
  9. data/docs/api/yard/HTM/Database.md +1 -1
  10. data/docs/api/yard/HTM/Railtie.md +2 -2
  11. data/docs/api/yard/HTM.md +0 -57
  12. data/docs/api/yard/index.csv +76 -61
  13. data/docs/api/yard-reference.md +2 -1
  14. data/docs/architecture/adrs/003-ollama-embeddings.md +45 -36
  15. data/docs/architecture/adrs/004-hive-mind.md +1 -1
  16. data/docs/architecture/adrs/008-robot-identification.md +1 -1
  17. data/docs/architecture/index.md +11 -9
  18. data/docs/architecture/overview.md +11 -7
  19. data/docs/assets/images/balanced-strategy-decay.svg +41 -0
  20. data/docs/assets/images/class-hierarchy.svg +1 -1
  21. data/docs/assets/images/eviction-priority.svg +43 -0
  22. data/docs/assets/images/exception-hierarchy.svg +2 -2
  23. data/docs/assets/images/hive-mind-shared-memory.svg +52 -0
  24. data/docs/assets/images/htm-architecture-overview.svg +3 -3
  25. data/docs/assets/images/htm-core-components.svg +4 -4
  26. data/docs/assets/images/htm-layered-architecture.svg +1 -1
  27. data/docs/assets/images/htm-memory-addition-flow.svg +2 -2
  28. data/docs/assets/images/htm-memory-recall-flow.svg +2 -2
  29. data/docs/assets/images/memory-topology.svg +53 -0
  30. data/docs/assets/images/two-tier-memory-architecture.svg +55 -0
  31. data/docs/development/setup.md +76 -44
  32. data/docs/examples/basic-usage.md +133 -0
  33. data/docs/examples/config-files.md +170 -0
  34. data/docs/examples/file-loading.md +208 -0
  35. data/docs/examples/index.md +116 -0
  36. data/docs/examples/llm-configuration.md +168 -0
  37. data/docs/examples/mcp-client.md +172 -0
  38. data/docs/examples/rails-integration.md +173 -0
  39. data/docs/examples/robot-groups.md +210 -0
  40. data/docs/examples/sinatra-integration.md +218 -0
  41. data/docs/examples/standalone-app.md +216 -0
  42. data/docs/examples/telemetry.md +224 -0
  43. data/docs/examples/timeframes.md +143 -0
  44. data/docs/getting-started/installation.md +97 -40
  45. data/docs/getting-started/quick-start.md +28 -11
  46. data/docs/guides/configuration.md +515 -0
  47. data/docs/guides/file-loading.md +322 -0
  48. data/docs/guides/getting-started.md +40 -9
  49. data/docs/guides/index.md +3 -3
  50. data/docs/guides/mcp-server.md +30 -12
  51. data/docs/guides/propositions.md +264 -0
  52. data/docs/guides/recalling-memories.md +4 -4
  53. data/docs/guides/search-strategies.md +3 -3
  54. data/docs/guides/tags.md +318 -0
  55. data/docs/guides/telemetry.md +229 -0
  56. data/docs/index.md +8 -16
  57. data/docs/{architecture → robots}/hive-mind.md +8 -111
  58. data/docs/robots/index.md +73 -0
  59. data/docs/{guides → robots}/multi-robot.md +3 -3
  60. data/docs/{guides → robots}/robot-groups.md +8 -7
  61. data/docs/{architecture → robots}/two-tier-memory.md +13 -149
  62. data/docs/robots/why-robots.md +85 -0
  63. data/lib/htm/config/defaults.yml +4 -4
  64. data/lib/htm/config.rb +2 -2
  65. data/lib/htm/job_adapter.rb +75 -1
  66. data/lib/htm/version.rb +1 -1
  67. data/lib/htm/workflows/remember_workflow.rb +212 -0
  68. data/lib/htm.rb +1 -0
  69. data/mkdocs.yml +33 -8
  70. metadata +60 -7
  71. data/docs/api/yard/HTM/Configuration.md +0 -240
  72. data/docs/telemetry.md +0 -391
data/docs/architecture/overview.md CHANGED
@@ -64,7 +64,7 @@ HTM implements a layered architecture with clear separation of concerns between
64
64
  - **Client-Side Generation**: Generate embeddings before database insertion
65
65
  - **Token Counting**: Estimate token counts for strings
66
66
  - **Model Management**: Handle different models per provider
67
- - **Provider Support**: Ollama (default) and OpenAI
67
+ - **Multi-Provider Support**: Ollama (default), OpenAI, Anthropic, Gemini, Azure, Bedrock, DeepSeek via RubyLLM
68
68
 
69
69
  !!! info "Architecture Change (October 2025)"
70
70
  Embeddings are generated client-side in Ruby before database insertion. This provides reliable, cross-platform operation without complex database extension dependencies.
@@ -257,13 +257,17 @@ gem 'tiktoken_ruby', '~> 0.0.6' # Token counting (OpenAI-compatible)
257
257
 
258
258
  ### Embedding Providers
259
259
 
260
- !!! info "Client-Side Generation"
261
- Embeddings are generated client-side in Ruby before database insertion. This provides reliable, cross-platform operation.
260
+ !!! info "Multi-Provider Support via RubyLLM"
261
+ HTM uses RubyLLM for embedding generation, supporting multiple providers. Choose based on your requirements for privacy, cost, and quality.
262
262
 
263
263
  | Provider | Models | Dimensions | Speed | Cost |
264
264
  |----------|--------|------------|-------|------|
265
- | **Ollama** (default) | nomic-embed-text, mxbai-embed-large, all-minilm | 384-1024 | Fast (local HTTP) | Free |
266
- | **OpenAI** | text-embedding-3-small, text-embedding-ada-002 | 1536 | Fast (API) | $0.0001/1K tokens |
265
+ | **Ollama** (default) | nomic-embed-text, mxbai-embed-large | 384-1024 | Fast (local) | Free |
266
+ | **OpenAI** | text-embedding-3-small, text-embedding-3-large | 1536-3072 | Fast (API) | $0.0001/1K tokens |
267
+ | **Gemini** | text-embedding-004 | 768 | Fast (API) | Varies |
268
+ | **Azure** | OpenAI models via Azure | 1536 | Fast (API) | Enterprise pricing |
269
+ | **Bedrock** | Amazon Titan, Cohere | Varies | Fast (API) | AWS pricing |
270
+ | **DeepSeek** | DeepSeek embeddings | Varies | Fast (API) | Competitive |
267
271
 
268
272
  ## Performance Characteristics
269
273
 
@@ -366,7 +370,7 @@ Based on typical production workloads with 10,000 nodes in long-term memory (cli
366
370
  ## Related Documentation
367
371
 
368
372
  - [Architecture Index](index.md) - Architecture overview and component summary
369
- - [Two-Tier Memory System](two-tier-memory.md) - Working memory and long-term memory deep dive
370
- - [Hive Mind Architecture](hive-mind.md) - Multi-robot shared memory design
373
+ - [Two-Tier Memory System](../robots/two-tier-memory.md) - Working memory and long-term memory deep dive
374
+ - [Hive Mind Architecture](../robots/hive-mind.md) - Multi-robot shared memory design
371
375
  - [API Reference](../api/htm.md) - Complete API documentation
372
376
  - [Architecture Decision Records](adrs/index.md) - Decision history
data/docs/assets/images/balanced-strategy-decay.svg ADDED
@@ -0,0 +1,41 @@
1
+ <svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Balanced Strategy: Importance Decay Over Time</text>
4
+
5
+ <!-- Axes -->
6
+ <line x1="100" y1="350" x2="700" y2="350" stroke="#808080" stroke-width="2"/>
7
+ <line x1="100" y1="350" x2="100" y2="80" stroke="#808080" stroke-width="2"/>
8
+
9
+ <!-- X-axis labels -->
10
+ <text x="100" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">0h</text>
11
+ <text x="250" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">1h</text>
12
+ <text x="400" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">3h</text>
13
+ <text x="550" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">6h</text>
14
+ <text x="700" y="375" text-anchor="middle" fill="#B0B0B0" font-size="11">24h</text>
15
+ <text x="400" y="395" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Time Since Added (hours)</text>
16
+
17
+ <!-- Y-axis labels -->
18
+ <text x="85" y="355" text-anchor="end" fill="#B0B0B0" font-size="11">0</text>
19
+ <text x="85" y="280" text-anchor="end" fill="#B0B0B0" font-size="11">3</text>
20
+ <text x="85" y="205" text-anchor="end" fill="#B0B0B0" font-size="11">6</text>
21
+ <text x="85" y="130" text-anchor="end" fill="#B0B0B0" font-size="11">9</text>
22
+ <text x="85" y="85" text-anchor="end" fill="#B0B0B0" font-size="11">10</text>
23
+ <text x="40" y="220" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold" transform="rotate(-90 40 220)">Effective Score</text>
24
+
25
+ <!-- Decay curves for different importance levels -->
26
+ <!-- Importance 10.0 -->
27
+ <path d="M 100 80 Q 250 105 400 155 T 700 320" stroke="#4CAF50" stroke-width="3" fill="none"/>
28
+ <text x="710" y="320" fill="#4CAF50" font-size="11" font-weight="bold">Imp: 10.0</text>
29
+
30
+ <!-- Importance 5.0 -->
31
+ <path d="M 100 205 Q 250 230 400 255 T 700 335" stroke="#2196F3" stroke-width="3" fill="none"/>
32
+ <text x="710" y="335" fill="#2196F3" font-size="11" font-weight="bold">Imp: 5.0</text>
33
+
34
+ <!-- Importance 1.0 -->
35
+ <path d="M 100 330 Q 250 340 400 345 T 700 348" stroke="#FF9800" stroke-width="3" fill="none"/>
36
+ <text x="710" y="348" fill="#FF9800" font-size="11" font-weight="bold">Imp: 1.0</text>
37
+
38
+ <!-- Key insight -->
39
+ <rect x="150" y="50" width="500" height="25" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
40
+ <text x="400" y="68" text-anchor="middle" fill="#4CAF50" font-size="12">High-importance memories retain value longer, but recency still matters</text>
41
+ </svg>
data/docs/assets/images/class-hierarchy.svg CHANGED
@@ -43,7 +43,7 @@
43
43
  <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>
44
44
  <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>
45
45
  <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>
46
- <text x="380" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#FF9800" font-weight="bold">EmbeddingService</tspan>: Vector generation via Ollama/OpenAI</text>
46
+ <text x="380" y="388" fill="#B0B0B0" font-size="10">• <tspan fill="#FF9800" font-weight="bold">EmbeddingService</tspan>: Vector generation via RubyLLM</text>
47
47
  <text x="380" y="406" fill="#B0B0B0" font-size="10">• <tspan fill="#FFC107" font-weight="bold">Database</tspan>: Schema management and connections</text>
48
48
 
49
49
  <!-- Markers -->
data/docs/assets/images/eviction-priority.svg ADDED
@@ -0,0 +1,43 @@
1
+ <svg viewBox="0 0 800 400" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Eviction Priority (Lower → Higher retention)</text>
4
+
5
+ <!-- Priority bars -->
6
+ <rect x="50" y="80" width="150" height="50" fill="rgba(244, 67, 54, 0.6)" stroke="#F44336" stroke-width="2" rx="3"/>
7
+ <text x="125" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 1: Evict First</text>
8
+
9
+ <rect x="220" y="80" width="150" height="50" fill="rgba(255, 152, 0, 0.6)" stroke="#FF9800" stroke-width="2" rx="3"/>
10
+ <text x="295" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 2</text>
11
+
12
+ <rect x="390" y="80" width="150" height="50" fill="rgba(255, 193, 7, 0.6)" stroke="#FFC107" stroke-width="2" rx="3"/>
13
+ <text x="465" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 3</text>
14
+
15
+ <rect x="560" y="80" width="150" height="50" fill="rgba(76, 175, 80, 0.6)" stroke="#4CAF50" stroke-width="2" rx="3"/>
16
+ <text x="635" y="110" text-anchor="middle" fill="#E0E0E0" font-size="12" font-weight="bold">Tier 4: Keep Longest</text>
17
+
18
+ <!-- Details -->
19
+ <text x="125" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
20
+ <text x="125" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
21
+ <text x="125" y="200" text-anchor="middle" fill="#F44336" font-size="10" font-weight="bold">Low value, stale</text>
22
+
23
+ <text x="295" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 1.0</text>
24
+ <text x="295" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
25
+ <text x="295" y="200" text-anchor="middle" fill="#FF9800" font-size="10" font-weight="bold">Low value, recent</text>
26
+
27
+ <text x="465" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
28
+ <text x="465" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 5 days</text>
29
+ <text x="465" y="200" text-anchor="middle" fill="#FFC107" font-size="10" font-weight="bold">High value, older</text>
30
+
31
+ <text x="635" y="160" text-anchor="middle" fill="#B0B0B0" font-size="11">Importance: 9.0</text>
32
+ <text x="635" y="180" text-anchor="middle" fill="#B0B0B0" font-size="11">Age: 1 hour</text>
33
+ <text x="635" y="200" text-anchor="middle" fill="#4CAF50" font-size="10" font-weight="bold">High value, fresh</text>
34
+
35
+ <!-- Example scenario -->
36
+ <text x="50" y="250" fill="#E0E0E0" font-size="13" font-weight="bold">Example Eviction Scenario:</text>
37
+ <text x="50" y="280" fill="#B0B0B0" font-size="11">Working Memory: 127,500 / 128,000 tokens (99% full)</text>
38
+ <text x="50" y="300" fill="#B0B0B0" font-size="11">New memory to add: 5,000 tokens</text>
39
+ <text x="50" y="320" fill="#B0B0B0" font-size="11">Need to free: 4,500 tokens</text>
40
+
41
+ <text x="50" y="350" fill="#4CAF50" font-size="11">Eviction: Remove Tier 1 and Tier 2 nodes until 4,500+ tokens freed</text>
42
+ <text x="50" y="370" fill="#4CAF50" font-size="11">Result: Tier 3 and Tier 4 nodes preserved (high importance)</text>
43
+ </svg>
data/docs/assets/images/exception-hierarchy.svg CHANGED
@@ -13,9 +13,9 @@
13
13
  <path d="M 350 170 L 430 170 L 430 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
14
14
  <path d="M 350 170 L 580 170 L 580 200" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
15
15
 
16
- <!-- Ollama connection failed -->
16
+ <!-- Provider connection failed -->
17
17
  <rect x="20" y="200" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
18
- <text x="120" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Ollama connection failed"</text>
18
+ <text x="120" y="230" text-anchor="middle" fill="#FFFFFF" font-size="12">"Provider connection failed"</text>
19
19
 
20
20
  <!-- OpenAI API error -->
21
21
  <rect x="240" y="200" width="200" height="50" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="6"/>
data/docs/assets/images/hive-mind-shared-memory.svg ADDED
@@ -0,0 +1,52 @@
1
+ <svg viewBox="0 0 900 600" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="450" y="30" text-anchor="middle" fill="#E0E0E0" font-size="18" font-weight="bold">Hive Mind: Shared Long-Term Memory</text>
4
+
5
+ <!-- Central Database -->
6
+ <ellipse cx="450" cy="300" rx="180" ry="120" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3"/>
7
+ <text x="450" y="280" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory</text>
8
+ <text x="450" y="305" text-anchor="middle" fill="#B0B0B0" font-size="12">PostgreSQL</text>
9
+ <text x="450" y="325" text-anchor="middle" fill="#B0B0B0" font-size="12">Shared Global Database</text>
10
+ <text x="450" y="345" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">All Robots Access Here</text>
11
+
12
+ <!-- Robot 1: Code Helper -->
13
+ <rect x="50" y="80" width="200" height="100" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="2" rx="5"/>
14
+ <text x="150" y="110" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 1: Code Helper</text>
15
+ <text x="150" y="135" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-abc123</text>
16
+ <text x="150" y="155" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
17
+
18
+ <!-- Robot 2: Research Assistant -->
19
+ <rect x="650" y="80" width="200" height="100" fill="rgba(76, 175, 80, 0.2)" stroke="#4CAF50" stroke-width="2" rx="5"/>
20
+ <text x="750" y="110" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 2: Research Bot</text>
21
+ <text x="750" y="135" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-xyz789</text>
22
+ <text x="750" y="155" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
23
+
24
+ <!-- Robot 3: Chat Companion -->
25
+ <rect x="50" y="450" width="200" height="100" fill="rgba(255, 152, 0, 0.2)" stroke="#FF9800" stroke-width="2" rx="5"/>
26
+ <text x="150" y="480" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 3: Chat Bot</text>
27
+ <text x="150" y="505" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-def456</text>
28
+ <text x="150" y="525" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
29
+
30
+ <!-- Robot 4: Design Assistant -->
31
+ <rect x="650" y="450" width="200" height="100" fill="rgba(244, 67, 54, 0.2)" stroke="#F44336" stroke-width="2" rx="5"/>
32
+ <text x="750" y="480" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 4: Designer</text>
33
+ <text x="750" y="505" text-anchor="middle" fill="#B0B0B0" font-size="11">ID: robot-ghi012</text>
34
+ <text x="750" y="525" text-anchor="middle" fill="#B0B0B0" font-size="11">Own Working Memory</text>
35
+
36
+ <!-- Connections to central database -->
37
+ <line x1="150" y1="180" x2="320" y2="240" stroke="#2196F3" stroke-width="3"/>
38
+ <line x1="750" y1="180" x2="580" y2="240" stroke="#4CAF50" stroke-width="3"/>
39
+ <line x1="150" y1="450" x2="320" y2="360" stroke="#FF9800" stroke-width="3"/>
40
+ <line x1="750" y1="450" x2="580" y2="360" stroke="#F44336" stroke-width="3"/>
41
+
42
+ <!-- Labels on connections -->
43
+ <text x="235" y="210" fill="#2196F3" font-size="10">read/write</text>
44
+ <text x="650" y="210" fill="#4CAF50" font-size="10">read/write</text>
45
+ <text x="235" y="410" fill="#FF9800" font-size="10">read/write</text>
46
+ <text x="650" y="410" fill="#F44336" font-size="10">read/write</text>
47
+
48
+ <!-- Key benefit -->
49
+ <rect x="300" y="520" width="300" height="60" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="2" rx="5"/>
50
+ <text x="450" y="545" text-anchor="middle" fill="#4CAF50" font-size="13" font-weight="bold">Knowledge Sharing:</text>
51
+ <text x="450" y="565" text-anchor="middle" fill="#B0B0B0" font-size="11">All robots see all memories</text>
52
+ </svg>
data/docs/assets/images/htm-architecture-overview.svg CHANGED
@@ -46,8 +46,8 @@
46
46
  <!-- Embedding Service -->
47
47
  <rect x="500" y="520" width="280" height="100" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="3" rx="8"/>
48
48
  <text x="640" y="555" text-anchor="middle" fill="#FFFFFF" font-size="16" font-weight="bold">Embedding Service</text>
49
- <text x="640" y="580" text-anchor="middle" fill="#B0B0B0" font-size="13">(Ollama/RubyLLM)</text>
50
- <text x="640" y="603" text-anchor="middle" fill="#B0B0B0" font-size="13">gpt-oss model</text>
49
+ <text x="640" y="580" text-anchor="middle" fill="#B0B0B0" font-size="13">(RubyLLM Multi-Provider)</text>
50
+ <text x="640" y="603" text-anchor="middle" fill="#B0B0B0" font-size="13">Configurable model</text>
51
51
 
52
52
  <!-- Notes -->
53
53
  <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"/>
@@ -56,7 +56,7 @@
56
56
  <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>
57
57
  <text x="40" y="590" fill="#B0B0B0" font-size="11">• <tspan fill="#2196F3" font-weight="bold">Working Memory</tspan>: Fast, token-limited cache</text>
58
58
  <text x="40" y="610" fill="#B0B0B0" font-size="11">• <tspan fill="#9C27B0" font-weight="bold">Long-term Memory</tspan>: Durable PostgreSQL storage</text>
59
- <text x="40" y="630" fill="#B0B0B0" font-size="11">• <tspan fill="#FF9800" font-weight="bold">Embedding Service</tspan>: Vector generation via Ollama</text>
59
+ <text x="40" y="630" fill="#B0B0B0" font-size="11">• <tspan fill="#FF9800" font-weight="bold">Embedding Service</tspan>: Vector generation via RubyLLM</text>
60
60
  <text x="40" y="650" fill="#B0B0B0" font-size="11">• <tspan fill="#FFC107" font-weight="bold">Eviction/Recall</tspan>: Automatic memory management</text>
61
61
 
62
62
  <!-- Markers -->
data/docs/assets/images/htm-core-components.svg CHANGED
@@ -44,13 +44,13 @@
44
44
  <text x="630" y="310" fill="#B0B0B0" font-size="11">@provider: Symbol</text>
45
45
  <text x="630" y="330" fill="#B0B0B0" font-size="11">@model: String</text>
46
46
  <text x="630" y="350" fill="#B0B0B0" font-size="11">@dimensions: Integer</text>
47
- <text x="630" y="370" fill="#B0B0B0" font-size="11">@ollama_url: String</text>
47
+ <text x="630" y="370" fill="#B0B0B0" font-size="11">@provider_url: String</text>
48
48
  <line x1="620" y1="380" x2="840" y2="380" stroke="#FF9800" stroke-width="1"/>
49
49
  <text x="630" y="400" fill="#4CAF50" font-size="11">+embed(text)</text>
50
50
  <text x="630" y="420" fill="#B0B0B0" font-size="11">+count_tokens(text)</text>
51
- <text x="630" y="440" fill="#B0B0B0" font-size="11">+embed_with_ollama()</text>
52
- <text x="630" y="460" fill="#B0B0B0" font-size="11">+embed_with_openai()</text>
53
- <text x="630" y="480" fill="#FFC107" font-size="10" font-style="italic">// Client-side generation</text>
51
+ <text x="630" y="440" fill="#B0B0B0" font-size="11">+generate_embedding()</text>
52
+ <text x="630" y="460" fill="#B0B0B0" font-size="11">+validate_response()</text>
53
+ <text x="630" y="480" fill="#FFC107" font-size="10" font-style="italic">// RubyLLM multi-provider</text>
54
54
 
55
55
  <!-- Relationships -->
56
56
  <line x1="450" y1="150" x2="170" y2="250" stroke="#2196F3" stroke-width="2"/>
data/docs/assets/images/htm-layered-architecture.svg CHANGED
@@ -37,7 +37,7 @@
37
37
  <!-- Layer 4: Services Layer -->
38
38
  <rect x="100" y="440" width="290" height="100" fill="rgba(244, 67, 54, 0.2)" stroke="#F44336" stroke-width="2" rx="5"/>
39
39
  <text x="245" y="465" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Embedding Service</text>
40
- <text x="245" y="490" text-anchor="middle" fill="#B0B0B0" font-size="11">Ollama • OpenAI • Cohere</text>
40
+ <text x="245" y="490" text-anchor="middle" fill="#B0B0B0" font-size="11">RubyLLM (Multi-Provider)</text>
41
41
  <text x="245" y="510" text-anchor="middle" fill="#B0B0B0" font-size="11">Vector Generation</text>
42
42
  <text x="245" y="530" text-anchor="middle" fill="#B0B0B0" font-size="11">Token Counting</text>
43
43
 
data/docs/assets/images/htm-memory-addition-flow.svg CHANGED
@@ -14,9 +14,9 @@
14
14
  <rect x="470" y="80" width="190" height="60" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="3" rx="8"/>
15
15
  <text x="565" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">EmbeddingService</text>
16
16
 
17
- <!-- Ollama/OpenAI -->
17
+ <!-- LLM Provider -->
18
18
  <rect x="710" y="80" width="180" height="60" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3" rx="8"/>
19
- <text x="800" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Ollama/OpenAI</text>
19
+ <text x="800" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">LLM Provider</text>
20
20
 
21
21
  <!-- LongTermMemory -->
22
22
  <rect x="280" y="260" width="180" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
data/docs/assets/images/htm-memory-recall-flow.svg CHANGED
@@ -19,9 +19,9 @@
19
19
  <rect x="240" y="180" width="190" height="60" fill="rgba(255, 152, 0, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
20
20
  <text x="335" y="215" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">EmbeddingService</text>
21
21
 
22
- <!-- Ollama/OpenAI -->
22
+ <!-- LLM Provider -->
23
23
  <rect x="480" y="180" width="180" height="60" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3" rx="8"/>
24
- <text x="570" y="215" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Ollama/OpenAI</text>
24
+ <text x="570" y="215" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">LLM Provider</text>
25
25
 
26
26
  <!-- LongTermMemory -->
27
27
  <rect x="240" y="300" width="180" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
data/docs/assets/images/memory-topology.svg ADDED
@@ -0,0 +1,53 @@
1
+ <svg viewBox="0 0 800 500" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Memory Topology: Shared LTM + Local WM</text>
4
+
5
+ <!-- Legend -->
6
+ <rect x="50" y="50" width="20" height="20" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0"/>
7
+ <text x="80" y="65" fill="#B0B0B0" font-size="12">Shared (Global)</text>
8
+ <rect x="200" y="50" width="20" height="20" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3"/>
9
+ <text x="230" y="65" fill="#B0B0B0" font-size="12">Per-Robot (Local)</text>
10
+
11
+ <!-- Robot 1 -->
12
+ <g transform="translate(0, 100)">
13
+ <text x="150" y="0" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 1 (Process 1)</text>
14
+ <rect x="50" y="20" width="200" height="80" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="2" rx="5"/>
15
+ <text x="150" y="50" text-anchor="middle" fill="#E0E0E0" font-size="12">Working Memory</text>
16
+ <text x="150" y="70" text-anchor="middle" fill="#B0B0B0" font-size="10">In-memory, token-limited</text>
17
+ <text x="150" y="85" text-anchor="middle" fill="#B0B0B0" font-size="10">Independent</text>
18
+ </g>
19
+
20
+ <!-- Robot 2 -->
21
+ <g transform="translate(300, 100)">
22
+ <text x="150" y="0" text-anchor="middle" fill="#E0E0E0" font-size="14" font-weight="bold">Robot 2 (Process 2)</text>
23
+ <rect x="50" y="20" width="200" height="80" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="2" rx="5"/>
24
+ <text x="150" y="50" text-anchor="middle" fill="#E0E0E0" font-size="12">Working Memory</text>
25
+ <text x="150" y="70" text-anchor="middle" fill="#B0B0B0" font-size="10">In-memory, token-limited</text>
26
+ <text x="150" y="85" text-anchor="middle" fill="#B0B0B0" font-size="10">Independent</text>
27
+ </g>
28
+
29
+ <!-- Shared Long-Term Memory -->
30
+ <rect x="150" y="280" width="500" height="150" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3" rx="5"/>
31
+ <text x="400" y="310" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory (Shared)</text>
32
+ <text x="400" y="340" text-anchor="middle" fill="#B0B0B0" font-size="12">PostgreSQL</text>
33
+ <text x="400" y="365" text-anchor="middle" fill="#B0B0B0" font-size="12">All robots read/write here</text>
34
+ <text x="400" y="390" text-anchor="middle" fill="#B0B0B0" font-size="12">Memories attributed with robot_id</text>
35
+ <text x="400" y="410" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Single Source of Truth</text>
36
+
37
+ <!-- Connections -->
38
+ <line x1="150" y1="200" x2="300" y2="280" stroke="#9C27B0" stroke-width="2" marker-end="url(#arrow-purple)"/>
39
+ <line x1="450" y1="200" x2="400" y2="280" stroke="#9C27B0" stroke-width="2" marker-end="url(#arrow-purple)"/>
40
+
41
+ <text x="225" y="240" fill="#9C27B0" font-size="10">read/write</text>
42
+ <text x="425" y="240" fill="#9C27B0" font-size="10">read/write</text>
43
+
44
+ <defs>
45
+ <marker id="arrow-purple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
46
+ <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
47
+ </marker>
48
+ </defs>
49
+
50
+ <!-- Key Point -->
51
+ <rect x="100" y="460" width="600" height="30" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
52
+ <text x="400" y="480" text-anchor="middle" fill="#4CAF50" font-size="12">Each robot has fast local cache (WM) + access to global knowledge (LTM)</text>
53
+ </svg>
data/docs/assets/images/two-tier-memory-architecture.svg ADDED
@@ -0,0 +1,55 @@
1
+ <svg viewBox="0 0 800 500" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="400" y="30" text-anchor="middle" fill="#E0E0E0" font-size="18" font-weight="bold">Two-Tier Memory Architecture</text>
4
+
5
+ <!-- Working Memory (Hot Tier) -->
6
+ <rect x="50" y="80" width="300" height="180" fill="rgba(33, 150, 243, 0.2)" stroke="#2196F3" stroke-width="3" rx="5"/>
7
+ <text x="200" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Working Memory (Hot)</text>
8
+ <text x="80" y="140" fill="#B0B0B0" font-size="12">Capacity: Token-limited (128K)</text>
9
+ <text x="80" y="160" fill="#B0B0B0" font-size="12">Storage: In-memory Ruby Hash</text>
10
+ <text x="80" y="180" fill="#B0B0B0" font-size="12">Speed: O(1) lookups</text>
11
+ <text x="80" y="200" fill="#B0B0B0" font-size="12">Lifetime: Process lifetime</text>
12
+ <text x="80" y="220" fill="#B0B0B0" font-size="12">Eviction: Importance + Recency</text>
13
+ <text x="80" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Fast, Token-Aware, Volatile</text>
14
+
15
+ <!-- Long-Term Memory (Cold Tier) -->
16
+ <rect x="450" y="80" width="300" height="180" fill="rgba(156, 39, 176, 0.2)" stroke="#9C27B0" stroke-width="3" rx="5"/>
17
+ <text x="600" y="110" text-anchor="middle" fill="#E0E0E0" font-size="16" font-weight="bold">Long-Term Memory (Cold)</text>
18
+ <text x="480" y="140" fill="#B0B0B0" font-size="12">Capacity: Unlimited</text>
19
+ <text x="480" y="160" fill="#B0B0B0" font-size="12">Storage: PostgreSQL + TimescaleDB</text>
20
+ <text x="480" y="180" fill="#B0B0B0" font-size="12">Speed: O(log n) with indexes</text>
21
+ <text x="480" y="200" fill="#B0B0B0" font-size="12">Lifetime: Permanent</text>
22
+ <text x="480" y="220" fill="#B0B0B0" font-size="12">Retrieval: RAG (semantic + temporal)</text>
23
+ <text x="480" y="240" fill="#4CAF50" font-size="12" font-weight="bold">Durable, Searchable, Persistent</text>
24
+
25
+ <!-- Data Flow: Add Memory -->
26
+ <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)"/>
27
+ <text x="300" y="310" text-anchor="middle" fill="#4CAF50" font-size="12" font-weight="bold">Add Memory</text>
28
+ <text x="300" y="330" text-anchor="middle" fill="#B0B0B0" font-size="10">(Stored in both tiers)</text>
29
+
30
+ <!-- Data Flow: Eviction -->
31
+ <path d="M 350 360 L 600 360" stroke="#FF9800" stroke-width="3" marker-end="url(#arrow-orange)"/>
32
+ <text x="475" y="350" text-anchor="middle" fill="#FF9800" font-size="12" font-weight="bold">Eviction</text>
33
+ <text x="475" y="380" text-anchor="middle" fill="#B0B0B0" font-size="10">(Token limit → move to LTM only)</text>
34
+
35
+ <!-- Data Flow: Recall -->
36
+ <path d="M 600 400 L 200 400" stroke="#9C27B0" stroke-width="3" marker-end="url(#arrow-purple)"/>
37
+ <text x="400" y="390" text-anchor="middle" fill="#9C27B0" font-size="12" font-weight="bold">Recall</text>
38
+ <text x="400" y="420" text-anchor="middle" fill="#B0B0B0" font-size="10">(RAG search → load back to WM)</text>
39
+
40
+ <!-- Never Forget Note -->
41
+ <rect x="150" y="450" width="500" height="40" fill="rgba(76, 175, 80, 0.1)" stroke="#4CAF50" stroke-width="1" rx="3"/>
42
+ <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>
43
+
44
+ <defs>
45
+ <marker id="arrow-green" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
46
+ <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
47
+ </marker>
48
+ <marker id="arrow-orange" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
49
+ <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
50
+ </marker>
51
+ <marker id="arrow-purple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
52
+ <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
53
+ </marker>
54
+ </defs>
55
+ </svg>