htm 0.0.17 → 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 (130) hide show
  1. checksums.yaml +4 -4
  2. data/.architecture/decisions/adrs/001-use-postgresql-timescaledb-storage.md +1 -1
  3. data/.architecture/decisions/adrs/011-database-side-embedding-generation-with-pgai.md +4 -4
  4. data/.architecture/decisions/adrs/012-llm-driven-ontology-topic-extraction.md +1 -1
  5. data/.envrc +12 -25
  6. data/.irbrc +7 -7
  7. data/.tbls.yml +2 -2
  8. data/CHANGELOG.md +130 -1
  9. data/README.md +13 -1
  10. data/Rakefile +8 -3
  11. data/SETUP.md +12 -12
  12. data/bin/htm_mcp +0 -4
  13. data/db/seed_data/README.md +2 -2
  14. data/db/seeds.rb +3 -3
  15. data/docs/api/database.md +37 -37
  16. data/docs/api/embedding-service.md +140 -110
  17. data/docs/api/htm.md +1 -1
  18. data/docs/api/yard/HTM/ActiveRecordConfig.md +8 -2
  19. data/docs/api/yard/HTM/Config.md +173 -0
  20. data/docs/api/yard/HTM/ConfigSection.md +28 -0
  21. data/docs/api/yard/HTM/Database.md +7 -8
  22. data/docs/api/yard/HTM/JobAdapter.md +1 -1
  23. data/docs/api/yard/HTM.md +0 -57
  24. data/docs/api/yard/index.csv +76 -61
  25. data/docs/api/yard-reference.md +2 -1
  26. data/docs/architecture/adrs/001-postgresql-timescaledb.md +1 -1
  27. data/docs/architecture/adrs/003-ollama-embeddings.md +45 -36
  28. data/docs/architecture/adrs/004-hive-mind.md +1 -1
  29. data/docs/architecture/adrs/008-robot-identification.md +1 -1
  30. data/docs/architecture/adrs/011-pgai-integration.md +4 -4
  31. data/docs/architecture/index.md +11 -9
  32. data/docs/architecture/overview.md +11 -7
  33. data/docs/assets/images/balanced-strategy-decay.svg +41 -0
  34. data/docs/assets/images/class-hierarchy.svg +1 -1
  35. data/docs/assets/images/eviction-priority.svg +43 -0
  36. data/docs/assets/images/exception-hierarchy.svg +2 -2
  37. data/docs/assets/images/hive-mind-shared-memory.svg +52 -0
  38. data/docs/assets/images/htm-architecture-overview.svg +3 -3
  39. data/docs/assets/images/htm-core-components.svg +4 -4
  40. data/docs/assets/images/htm-layered-architecture.svg +1 -1
  41. data/docs/assets/images/htm-memory-addition-flow.svg +2 -2
  42. data/docs/assets/images/htm-memory-recall-flow.svg +2 -2
  43. data/docs/assets/images/memory-topology.svg +53 -0
  44. data/docs/assets/images/two-tier-memory-architecture.svg +55 -0
  45. data/docs/database_rake_tasks.md +5 -5
  46. data/docs/development/rake-tasks.md +11 -11
  47. data/docs/development/setup.md +97 -65
  48. data/docs/development/testing.md +1 -1
  49. data/docs/examples/basic-usage.md +133 -0
  50. data/docs/examples/config-files.md +170 -0
  51. data/docs/examples/file-loading.md +208 -0
  52. data/docs/examples/index.md +116 -0
  53. data/docs/examples/llm-configuration.md +168 -0
  54. data/docs/examples/mcp-client.md +172 -0
  55. data/docs/examples/rails-integration.md +173 -0
  56. data/docs/examples/robot-groups.md +210 -0
  57. data/docs/examples/sinatra-integration.md +218 -0
  58. data/docs/examples/standalone-app.md +216 -0
  59. data/docs/examples/telemetry.md +224 -0
  60. data/docs/examples/timeframes.md +143 -0
  61. data/docs/getting-started/installation.md +117 -60
  62. data/docs/getting-started/quick-start.md +35 -18
  63. data/docs/guides/configuration.md +515 -0
  64. data/docs/guides/file-loading.md +322 -0
  65. data/docs/guides/getting-started.md +42 -11
  66. data/docs/guides/index.md +3 -3
  67. data/docs/guides/long-term-memory.md +1 -1
  68. data/docs/guides/mcp-server.md +47 -29
  69. data/docs/guides/propositions.md +264 -0
  70. data/docs/guides/recalling-memories.md +4 -4
  71. data/docs/guides/search-strategies.md +3 -3
  72. data/docs/guides/tags.md +318 -0
  73. data/docs/guides/telemetry.md +229 -0
  74. data/docs/index.md +10 -18
  75. data/docs/multi_framework_support.md +8 -8
  76. data/docs/{architecture → robots}/hive-mind.md +8 -111
  77. data/docs/robots/index.md +73 -0
  78. data/docs/{guides → robots}/multi-robot.md +3 -3
  79. data/docs/{guides → robots}/robot-groups.md +14 -13
  80. data/docs/{architecture → robots}/two-tier-memory.md +13 -149
  81. data/docs/robots/why-robots.md +85 -0
  82. data/docs/setup_local_database.md +19 -19
  83. data/docs/using_rake_tasks_in_your_app.md +14 -14
  84. data/examples/README.md +50 -6
  85. data/examples/basic_usage.rb +31 -21
  86. data/examples/cli_app/README.md +8 -8
  87. data/examples/cli_app/htm_cli.rb +5 -5
  88. data/examples/config_file_example/README.md +256 -0
  89. data/examples/config_file_example/config/htm.local.yml +34 -0
  90. data/examples/config_file_example/custom_config.yml +22 -0
  91. data/examples/config_file_example/show_config.rb +125 -0
  92. data/examples/custom_llm_configuration.rb +7 -7
  93. data/examples/example_app/Rakefile +2 -2
  94. data/examples/example_app/app.rb +8 -8
  95. data/examples/file_loader_usage.rb +9 -9
  96. data/examples/mcp_client.rb +5 -5
  97. data/examples/rails_app/Gemfile.lock +48 -56
  98. data/examples/rails_app/README.md +1 -1
  99. data/examples/robot_groups/multi_process.rb +5 -5
  100. data/examples/robot_groups/robot_worker.rb +5 -5
  101. data/examples/robot_groups/same_process.rb +9 -9
  102. data/examples/sinatra_app/app.rb +1 -1
  103. data/examples/timeframe_demo.rb +1 -1
  104. data/lib/htm/active_record_config.rb +12 -25
  105. data/lib/htm/circuit_breaker.rb +0 -2
  106. data/lib/htm/config/defaults.yml +246 -0
  107. data/lib/htm/config.rb +888 -0
  108. data/lib/htm/database.rb +23 -27
  109. data/lib/htm/embedding_service.rb +0 -4
  110. data/lib/htm/integrations/sinatra.rb +3 -7
  111. data/lib/htm/job_adapter.rb +76 -16
  112. data/lib/htm/jobs/generate_embedding_job.rb +1 -7
  113. data/lib/htm/jobs/generate_propositions_job.rb +2 -12
  114. data/lib/htm/jobs/generate_tags_job.rb +1 -8
  115. data/lib/htm/loaders/defaults_loader.rb +143 -0
  116. data/lib/htm/loaders/xdg_config_loader.rb +116 -0
  117. data/lib/htm/mcp/cli.rb +200 -58
  118. data/lib/htm/mcp/server.rb +3 -3
  119. data/lib/htm/proposition_service.rb +2 -12
  120. data/lib/htm/railtie.rb +3 -4
  121. data/lib/htm/tag_service.rb +1 -8
  122. data/lib/htm/version.rb +1 -1
  123. data/lib/htm/workflows/remember_workflow.rb +212 -0
  124. data/lib/htm.rb +125 -5
  125. data/mkdocs.yml +33 -8
  126. metadata +83 -10
  127. data/config/database.yml +0 -77
  128. data/docs/api/yard/HTM/Configuration.md +0 -229
  129. data/docs/telemetry.md +0 -391
  130. data/lib/htm/configuration.rb +0 -799
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>
data/docs/database_rake_tasks.md CHANGED
@@ -143,7 +143,7 @@ Opens an interactive PostgreSQL console (psql).
143
143
 
144
144
  **What it does:**
145
145
  - Launches `psql` connected to your HTM database
146
- - Uses connection parameters from `HTM_DBURL` or `.envrc`
146
+ - Uses connection parameters from `HTM_DATABASE__URL` or `.envrc`
147
147
  - Allows you to run SQL queries directly
148
148
 
149
149
  **Example:**
@@ -237,7 +237,7 @@ rake htm:db:info
237
237
 
238
238
  ### Method 2: Manual Export
239
239
  ```bash
240
- export HTM_DBURL="postgresql://user:password@host:port/dbname?sslmode=require"
240
+ export HTM_DATABASE__URL="postgresql://user:password@host:port/dbname?sslmode=require"
241
241
  rake htm:db:info
242
242
  ```
243
243
 
@@ -293,12 +293,12 @@ rake htm:db:migrate # Run new migrations only
293
293
 
294
294
  ### "Database configuration not found"
295
295
  - Run `direnv allow` in the project directory
296
- - Or manually export `HTM_DBURL`
297
- - Verify: `echo $HTM_DBURL`
296
+ - Or manually export `HTM_DATABASE__URL`
297
+ - Verify: `echo $HTM_DATABASE__URL`
298
298
 
299
299
  ### "Connection refused"
300
300
  - Check database is running
301
- - Verify host/port in `HTM_DBURL`
301
+ - Verify host/port in `HTM_DATABASE__URL`
302
302
  - Test: `rake htm:db:test`
303
303
 
304
304
  ### "Extension not found"
data/docs/development/rake-tasks.md CHANGED
@@ -56,7 +56,7 @@ Running migrations...
56
56
 
57
57
  **What it does:**
58
58
 
59
- - Connects to PostgreSQL using `HTM_DBURL`
59
+ - Connects to PostgreSQL using `HTM_DATABASE__URL`
60
60
  - Verifies required extensions (pgvector, pg_trgm)
61
61
  - Creates all HTM tables (robots, nodes, tags, file_sources, etc.)
62
62
  - Runs all pending ActiveRecord migrations
@@ -906,7 +906,7 @@ Rebuilding tags for 1,542 nodes...
906
906
  bundle install
907
907
 
908
908
  # Set database URL
909
- export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
909
+ export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
910
910
 
911
911
  # Create and setup database
912
912
  rake htm:db:create
@@ -1012,17 +1012,17 @@ All tasks require database configuration. Set one of these:
1012
1012
 
1013
1013
  | Variable | Description |
1014
1014
  |----------|-------------|
1015
- | `HTM_DBURL` | Full PostgreSQL connection URL (preferred) |
1016
- | `HTM_DBHOST` | Database host |
1017
- | `HTM_DBPORT` | Database port |
1018
- | `HTM_DBNAME` | Database name |
1019
- | `HTM_DBUSER` | Database username |
1020
- | `HTM_DBPASS` | Database password |
1015
+ | `HTM_DATABASE__URL` | Full PostgreSQL connection URL (preferred) |
1016
+ | `HTM_DATABASE__HOST` | Database host |
1017
+ | `HTM_DATABASE__PORT` | Database port |
1018
+ | `HTM_DATABASE__NAME` | Database name |
1019
+ | `HTM_DATABASE__USER` | Database username |
1020
+ | `HTM_DATABASE__PASSWORD` | Database password |
1021
1021
 
1022
1022
  **Example:**
1023
1023
 
1024
1024
  ```bash
1025
- export HTM_DBURL="postgresql://user:password@localhost:5432/htm_development"
1025
+ export HTM_DATABASE__URL="postgresql://user:password@localhost:5432/htm_development"
1026
1026
  ```
1027
1027
 
1028
1028
  ---
@@ -1031,10 +1031,10 @@ export HTM_DBURL="postgresql://user:password@localhost:5432/htm_development"
1031
1031
 
1032
1032
  ### "Database configuration not found"
1033
1033
 
1034
- Set the `HTM_DBURL` environment variable:
1034
+ Set the `HTM_DATABASE__URL` environment variable:
1035
1035
 
1036
1036
  ```bash
1037
- export HTM_DBURL="postgresql://user@localhost:5432/htm_development"
1037
+ export HTM_DATABASE__URL="postgresql://user@localhost:5432/htm_development"
1038
1038
  ```
1039
1039
 
1040
1040
  ### "Extension not found"