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
  1. checksums.yaml +4 -4
  2. data/.aigcm_msg +1 -0
  3. data/.architecture/reviews/comprehensive-codebase-review.md +577 -0
  4. data/.claude/settings.local.json +92 -0
  5. data/.envrc +1 -0
  6. data/.irbrc +283 -80
  7. data/.tbls.yml +31 -0
  8. data/CHANGELOG.md +314 -16
  9. data/CLAUDE.md +603 -0
  10. data/README.md +76 -5
  11. data/Rakefile +5 -0
  12. data/SETUP.md +132 -101
  13. data/db/migrate/{20250101000001_enable_extensions.rb → 00001_enable_extensions.rb} +0 -1
  14. data/db/migrate/00002_create_robots.rb +11 -0
  15. data/db/migrate/00003_create_file_sources.rb +20 -0
  16. data/db/migrate/00004_create_nodes.rb +65 -0
  17. data/db/migrate/00005_create_tags.rb +13 -0
  18. data/db/migrate/00006_create_node_tags.rb +18 -0
  19. data/db/migrate/00007_create_robot_nodes.rb +26 -0
  20. data/db/migrate/00009_add_working_memory_to_robot_nodes.rb +12 -0
  21. data/db/schema.sql +390 -36
  22. data/docs/api/database.md +19 -232
  23. data/docs/api/embedding-service.md +1 -7
  24. data/docs/api/htm.md +305 -364
  25. data/docs/api/index.md +1 -7
  26. data/docs/api/long-term-memory.md +342 -590
  27. data/docs/api/yard/HTM/ActiveRecordConfig.md +23 -0
  28. data/docs/api/yard/HTM/AuthorizationError.md +11 -0
  29. data/docs/api/yard/HTM/CircuitBreaker.md +92 -0
  30. data/docs/api/yard/HTM/CircuitBreakerOpenError.md +34 -0
  31. data/docs/api/yard/HTM/Configuration.md +175 -0
  32. data/docs/api/yard/HTM/Database.md +99 -0
  33. data/docs/api/yard/HTM/DatabaseError.md +14 -0
  34. data/docs/api/yard/HTM/EmbeddingError.md +18 -0
  35. data/docs/api/yard/HTM/EmbeddingService.md +58 -0
  36. data/docs/api/yard/HTM/Error.md +11 -0
  37. data/docs/api/yard/HTM/JobAdapter.md +39 -0
  38. data/docs/api/yard/HTM/LongTermMemory.md +342 -0
  39. data/docs/api/yard/HTM/NotFoundError.md +17 -0
  40. data/docs/api/yard/HTM/Observability.md +107 -0
  41. data/docs/api/yard/HTM/QueryTimeoutError.md +19 -0
  42. data/docs/api/yard/HTM/Railtie.md +27 -0
  43. data/docs/api/yard/HTM/ResourceExhaustedError.md +13 -0
  44. data/docs/api/yard/HTM/TagError.md +18 -0
  45. data/docs/api/yard/HTM/TagService.md +67 -0
  46. data/docs/api/yard/HTM/Timeframe/Result.md +24 -0
  47. data/docs/api/yard/HTM/Timeframe.md +40 -0
  48. data/docs/api/yard/HTM/TimeframeExtractor/Result.md +24 -0
  49. data/docs/api/yard/HTM/TimeframeExtractor.md +45 -0
  50. data/docs/api/yard/HTM/ValidationError.md +20 -0
  51. data/docs/api/yard/HTM/WorkingMemory.md +131 -0
  52. data/docs/api/yard/HTM.md +80 -0
  53. data/docs/api/yard/index.csv +179 -0
  54. data/docs/api/yard-reference.md +51 -0
  55. data/docs/architecture/adrs/001-postgresql-timescaledb.md +1 -1
  56. data/docs/architecture/adrs/003-ollama-embeddings.md +1 -1
  57. data/docs/architecture/adrs/010-redis-working-memory-rejected.md +2 -27
  58. data/docs/architecture/adrs/index.md +2 -13
  59. data/docs/architecture/hive-mind.md +165 -166
  60. data/docs/architecture/index.md +2 -2
  61. data/docs/architecture/overview.md +5 -171
  62. data/docs/architecture/two-tier-memory.md +1 -35
  63. data/docs/assets/images/adr-010-current-architecture.svg +37 -0
  64. data/docs/assets/images/adr-010-proposed-architecture.svg +48 -0
  65. data/docs/assets/images/adr-dependency-tree.svg +93 -0
  66. data/docs/assets/images/class-hierarchy.svg +55 -0
  67. data/docs/assets/images/exception-hierarchy.svg +45 -0
  68. data/docs/assets/images/htm-architecture-overview.svg +83 -0
  69. data/docs/assets/images/htm-complete-memory-flow.svg +160 -0
  70. data/docs/assets/images/htm-context-assembly-flow.svg +148 -0
  71. data/docs/assets/images/htm-eviction-process.svg +141 -0
  72. data/docs/assets/images/htm-memory-addition-flow.svg +138 -0
  73. data/docs/assets/images/htm-memory-recall-flow.svg +152 -0
  74. data/docs/assets/images/htm-node-states.svg +123 -0
  75. data/docs/assets/images/project-structure.svg +78 -0
  76. data/docs/assets/images/test-directory-structure.svg +38 -0
  77. data/{dbdoc → docs/database}/README.md +127 -125
  78. data/docs/database/public.file_sources.md +42 -0
  79. data/docs/database/public.file_sources.svg +211 -0
  80. data/{dbdoc → docs/database}/public.node_tags.md +7 -8
  81. data/docs/database/public.node_tags.svg +239 -0
  82. data/{dbdoc → docs/database}/public.nodes.md +22 -17
  83. data/docs/database/public.nodes.svg +271 -0
  84. data/docs/database/public.robot_nodes.md +46 -0
  85. data/docs/database/public.robot_nodes.svg +243 -0
  86. data/{dbdoc → docs/database}/public.robots.md +2 -3
  87. data/docs/database/public.robots.svg +161 -0
  88. data/docs/database/public.tags.svg +139 -0
  89. data/{dbdoc → docs/database}/schema.json +941 -630
  90. data/docs/database/schema.svg +282 -0
  91. data/docs/development/index.md +1 -29
  92. data/docs/development/schema.md +134 -309
  93. data/docs/development/testing.md +1 -9
  94. data/docs/getting-started/index.md +47 -0
  95. data/docs/{installation.md → getting-started/installation.md} +2 -2
  96. data/docs/{quick-start.md → getting-started/quick-start.md} +5 -5
  97. data/docs/guides/adding-memories.md +295 -643
  98. data/docs/guides/recalling-memories.md +36 -1
  99. data/docs/guides/search-strategies.md +85 -51
  100. data/docs/images/htm-er-diagram.svg +156 -0
  101. data/docs/index.md +16 -31
  102. data/docs/multi_framework_support.md +4 -4
  103. data/examples/README.md +280 -0
  104. data/examples/basic_usage.rb +18 -16
  105. data/examples/cli_app/htm_cli.rb +146 -8
  106. data/examples/cli_app/temp.log +93 -0
  107. data/examples/custom_llm_configuration.rb +1 -2
  108. data/examples/example_app/app.rb +11 -14
  109. data/examples/file_loader_usage.rb +177 -0
  110. data/examples/robot_groups/lib/robot_group.rb +419 -0
  111. data/examples/robot_groups/lib/working_memory_channel.rb +140 -0
  112. data/examples/robot_groups/multi_process.rb +286 -0
  113. data/examples/robot_groups/robot_worker.rb +136 -0
  114. data/examples/robot_groups/same_process.rb +229 -0
  115. data/examples/sinatra_app/Gemfile +1 -0
  116. data/examples/sinatra_app/Gemfile.lock +166 -0
  117. data/examples/sinatra_app/app.rb +219 -24
  118. data/examples/timeframe_demo.rb +276 -0
  119. data/lib/htm/active_record_config.rb +10 -3
  120. data/lib/htm/circuit_breaker.rb +202 -0
  121. data/lib/htm/configuration.rb +313 -80
  122. data/lib/htm/database.rb +67 -36
  123. data/lib/htm/embedding_service.rb +39 -2
  124. data/lib/htm/errors.rb +131 -11
  125. data/lib/htm/{sinatra.rb → integrations/sinatra.rb} +87 -12
  126. data/lib/htm/job_adapter.rb +10 -3
  127. data/lib/htm/jobs/generate_embedding_job.rb +5 -4
  128. data/lib/htm/jobs/generate_tags_job.rb +4 -0
  129. data/lib/htm/loaders/markdown_loader.rb +263 -0
  130. data/lib/htm/loaders/paragraph_chunker.rb +112 -0
  131. data/lib/htm/long_term_memory.rb +601 -321
  132. data/lib/htm/models/file_source.rb +99 -0
  133. data/lib/htm/models/node.rb +116 -12
  134. data/lib/htm/models/robot.rb +53 -4
  135. data/lib/htm/models/robot_node.rb +51 -0
  136. data/lib/htm/models/tag.rb +302 -0
  137. data/lib/htm/observability.rb +395 -0
  138. data/lib/htm/tag_service.rb +60 -3
  139. data/lib/htm/tasks.rb +29 -0
  140. data/lib/htm/timeframe.rb +194 -0
  141. data/lib/htm/timeframe_extractor.rb +307 -0
  142. data/lib/htm/version.rb +1 -1
  143. data/lib/htm/working_memory.rb +165 -70
  144. data/lib/htm.rb +352 -133
  145. data/lib/tasks/doc.rake +300 -0
  146. data/lib/tasks/files.rake +299 -0
  147. data/lib/tasks/htm.rake +188 -2
  148. data/lib/tasks/jobs.rake +10 -12
  149. data/lib/tasks/tags.rake +194 -0
  150. data/mkdocs.yml +91 -9
  151. data/notes/ARCHITECTURE_REVIEW.md +1167 -0
  152. data/notes/IMPLEMENTATION_SUMMARY.md +606 -0
  153. data/notes/MULTI_FRAMEWORK_IMPLEMENTATION.md +451 -0
  154. data/notes/next_steps.md +100 -0
  155. data/notes/plan.md +627 -0
  156. data/notes/tag_ontology_enhancement_ideas.md +222 -0
  157. data/notes/timescaledb_removal_summary.md +200 -0
  158. metadata +177 -37
  159. data/db/migrate/20250101000002_create_robots.rb +0 -14
  160. data/db/migrate/20250101000003_create_nodes.rb +0 -42
  161. data/db/migrate/20250101000005_create_tags.rb +0 -38
  162. data/db/migrate/20250101000007_add_node_vector_indexes.rb +0 -30
  163. data/dbdoc/public.node_tags.svg +0 -112
  164. data/dbdoc/public.nodes.svg +0 -118
  165. data/dbdoc/public.robots.svg +0 -90
  166. data/dbdoc/public.tags.svg +0 -60
  167. data/dbdoc/schema.svg +0 -154
  168. data/{dbdoc → docs/database}/public.node_stats.md +0 -0
  169. data/{dbdoc → docs/database}/public.node_stats.svg +0 -0
  170. data/{dbdoc → docs/database}/public.nodes_tags.md +0 -0
  171. data/{dbdoc → docs/database}/public.nodes_tags.svg +0 -0
  172. data/{dbdoc → docs/database}/public.ontology_structure.md +0 -0
  173. data/{dbdoc → docs/database}/public.ontology_structure.svg +0 -0
  174. data/{dbdoc → docs/database}/public.operations_log.md +0 -0
  175. data/{dbdoc → docs/database}/public.operations_log.svg +0 -0
  176. data/{dbdoc → docs/database}/public.relationships.md +0 -0
  177. data/{dbdoc → docs/database}/public.relationships.svg +0 -0
  178. data/{dbdoc → docs/database}/public.robot_activity.md +0 -0
  179. data/{dbdoc → docs/database}/public.robot_activity.svg +0 -0
  180. data/{dbdoc → docs/database}/public.schema_migrations.md +0 -0
  181. data/{dbdoc → docs/database}/public.schema_migrations.svg +0 -0
  182. data/{dbdoc → docs/database}/public.tags.md +3 -3
  183. /data/{dbdoc → docs/database}/public.topic_relationships.md +0 -0
  184. /data/{dbdoc → docs/database}/public.topic_relationships.svg +0 -0
data/docs/assets/images/htm-context-assembly-flow.svg ADDED
@@ -0,0 +1,148 @@
1
+ <svg viewBox="0 0 900 650" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="450" y="30" text-anchor="middle" fill="#FFFFFF" font-size="20" font-weight="bold">Context Assembly Flow</text>
4
+
5
+ <!-- User -->
6
+ <rect x="50" y="80" width="200" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
7
+ <text x="150" y="110" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">User: create_context</text>
8
+ <text x="150" y="128" text-anchor="middle" fill="#B0B0B0" font-size="11">(with strategy)</text>
9
+
10
+ <!-- HTM -->
11
+ <rect x="300" y="80" width="140" height="60" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
12
+ <text x="370" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">HTM</text>
13
+
14
+ <!-- WorkingMemory -->
15
+ <rect x="490" y="80" width="160" height="60" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
16
+ <text x="570" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">WorkingMemory</text>
17
+
18
+ <!-- Strategy Diamond -->
19
+ <polygon points="570,210 620,160 670,210 620,260" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3"/>
20
+ <text x="620" y="210" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Strategy</text>
21
+ <text x="620" y="225" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Type?</text>
22
+
23
+ <!-- Recent Strategy -->
24
+ <rect x="720" y="140" width="150" height="60" fill="rgba(103, 58, 183, 0.3)" stroke="#673AB7" stroke-width="3" rx="8"/>
25
+ <text x="795" y="165" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Sort by access</text>
26
+ <text x="795" y="185" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">order (:recent)</text>
27
+
28
+ <!-- Important Strategy -->
29
+ <rect x="720" y="220" width="150" height="60" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8"/>
30
+ <text x="795" y="245" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Sort by</text>
31
+ <text x="795" y="265" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">importance</text>
32
+
33
+ <!-- Balanced Strategy -->
34
+ <rect x="720" y="300" width="150" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
35
+ <text x="795" y="325" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Hybrid score</text>
36
+ <text x="795" y="345" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">(:balanced)</text>
37
+
38
+ <!-- Sorted nodes -->
39
+ <rect x="580" y="410" width="140" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
40
+ <text x="650" y="445" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Sorted nodes</text>
41
+
42
+ <!-- Token budget loop -->
43
+ <rect x="350" y="410" width="180" height="60" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="3" rx="8"/>
44
+ <text x="440" y="445" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Token budget loop</text>
45
+
46
+ <!-- Token check Diamond -->
47
+ <polygon points="300,540 350,490 400,540 350,590" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3"/>
48
+ <text x="350" y="540" text-anchor="middle" fill="#FFFFFF" font-size="11" font-weight="bold">Tokens</text>
49
+ <text x="350" y="555" text-anchor="middle" fill="#FFFFFF" font-size="11" font-weight="bold">&lt; max?</text>
50
+
51
+ <!-- Add node -->
52
+ <rect x="480" y="510" width="140" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
53
+ <text x="550" y="535" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Add node to</text>
54
+ <text x="550" y="555" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">context</text>
55
+
56
+ <!-- Stop -->
57
+ <rect x="140" y="510" width="150" height="60" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8"/>
58
+ <text x="215" y="535" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Stop, return</text>
59
+ <text x="215" y="555" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">context</text>
60
+
61
+ <!-- Final context -->
62
+ <rect x="190" y="300" width="200" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
63
+ <text x="290" y="325" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Assembled context</text>
64
+ <text x="290" y="345" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">string</text>
65
+
66
+ <!-- Flow arrows -->
67
+ <!-- 1. Request -->
68
+ <path d="M 250 110 L 300 110" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowG)"/>
69
+ <text x="275" y="105" text-anchor="middle" fill="#4CAF50" font-size="11">1. Request</text>
70
+
71
+ <!-- 2. Assemble -->
72
+ <path d="M 440 110 L 490 110" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrowB)"/>
73
+ <text x="465" y="105" text-anchor="middle" fill="#2196F3" font-size="11">2. Assemble</text>
74
+
75
+ <!-- 3. Strategy -->
76
+ <path d="M 570 140 L 570 160 L 590 160 L 590 190 L 620 190" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrowY)"/>
77
+ <text x="545" y="165" text-anchor="middle" fill="#FFC107" font-size="11">3. Strategy?</text>
78
+
79
+ <!-- Strategy paths -->
80
+ <path d="M 670 175 L 720 170" stroke="#673AB7" stroke-width="2" fill="none" marker-end="url(#arrowP)"/>
81
+ <text x="695" y="165" text-anchor="middle" fill="#673AB7" font-size="10">:recent</text>
82
+
83
+ <path d="M 670 210 L 720 210 L 720 250" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrowR)"/>
84
+ <text x="695" y="215" text-anchor="middle" fill="#F44336" font-size="10">:important</text>
85
+
86
+ <path d="M 670 245 L 720 245 L 720 330" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowG)"/>
87
+ <text x="695" y="260" text-anchor="middle" fill="#4CAF50" font-size="10">:balanced</text>
88
+
89
+ <!-- To sorted nodes -->
90
+ <path d="M 795 200 L 795 375 L 650 375 L 650 410" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrowPu)"/>
91
+ <path d="M 795 280 L 795 375" stroke="#9C27B0" stroke-width="2" fill="none"/>
92
+ <path d="M 795 360 L 795 375" stroke="#9C27B0" stroke-width="2" fill="none"/>
93
+
94
+ <!-- 4. Build context -->
95
+ <path d="M 580 440 L 530 440" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrowO)"/>
96
+ <text x="555" y="435" text-anchor="middle" fill="#FF9800" font-size="11">4. Build</text>
97
+
98
+ <!-- 5. Check tokens -->
99
+ <path d="M 410 470 L 410 490 L 380 490 L 380 520 L 350 520 L 350 540" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrowY)"/>
100
+ <text x="385" y="495" text-anchor="middle" fill="#FFC107" font-size="11">5. Check</text>
101
+
102
+ <!-- Yes path -->
103
+ <path d="M 400 540 L 480 540" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowG)"/>
104
+ <text x="440" y="535" text-anchor="middle" fill="#4CAF50" font-size="11">Yes</text>
105
+
106
+ <!-- Loop back -->
107
+ <path d="M 550 570 L 550 595 L 440 595 L 440 470" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrowB)"/>
108
+
109
+ <!-- No path -->
110
+ <path d="M 300 540 L 290 540" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrowR)"/>
111
+ <text x="295" y="535" text-anchor="middle" fill="#F44336" font-size="11">No</text>
112
+
113
+ <!-- 6. Join nodes -->
114
+ <path d="M 215 510 L 215 385 L 290 385 L 290 360" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowG)"/>
115
+ <text x="170" y="460" text-anchor="middle" fill="#4CAF50" font-size="11">6. Join</text>
116
+ <text x="170" y="475" text-anchor="middle" fill="#4CAF50" font-size="11">nodes</text>
117
+
118
+ <!-- 7-9 Return path -->
119
+ <path d="M 290 300 L 290 260 L 370 260 L 370 140" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrowB)"/>
120
+ <text x="250" y="275" text-anchor="middle" fill="#2196F3" font-size="11">7-9. Return</text>
121
+
122
+ <path d="M 370 80 L 370 65 L 150 65 L 150 80" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowG)"/>
123
+
124
+ <!-- Markers -->
125
+ <defs>
126
+ <marker id="arrowG" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
127
+ <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
128
+ </marker>
129
+ <marker id="arrowB" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
130
+ <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
131
+ </marker>
132
+ <marker id="arrowO" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
133
+ <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
134
+ </marker>
135
+ <marker id="arrowY" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
136
+ <polygon points="0 0, 10 3, 0 6" fill="#FFC107"/>
137
+ </marker>
138
+ <marker id="arrowPu" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
139
+ <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
140
+ </marker>
141
+ <marker id="arrowP" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
142
+ <polygon points="0 0, 10 3, 0 6" fill="#673AB7"/>
143
+ </marker>
144
+ <marker id="arrowR" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
145
+ <polygon points="0 0, 10 3, 0 6" fill="#F44336"/>
146
+ </marker>
147
+ </defs>
148
+ </svg>
data/docs/assets/images/htm-eviction-process.svg ADDED
@@ -0,0 +1,141 @@
1
+ <svg viewBox="0 0 900 750" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="450" y="30" text-anchor="middle" fill="#FFFFFF" font-size="20" font-weight="bold">Eviction Process Sequence</text>
4
+
5
+ <!-- Lifelines -->
6
+ <!-- User -->
7
+ <rect x="50" y="70" width="100" height="50" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="5"/>
8
+ <text x="100" y="100" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">User</text>
9
+ <line x1="100" y1="120" x2="100" y2="700" stroke="#4CAF50" stroke-width="2" stroke-dasharray="5,5"/>
10
+
11
+ <!-- HTM -->
12
+ <rect x="200" y="70" width="100" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="5"/>
13
+ <text x="250" y="100" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">HTM</text>
14
+ <line x1="250" y1="120" x2="250" y2="700" stroke="#2196F3" stroke-width="2" stroke-dasharray="5,5"/>
15
+
16
+ <!-- WorkingMemory -->
17
+ <rect x="350" y="70" width="140" height="50" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="5"/>
18
+ <text x="420" y="95" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Working</text>
19
+ <text x="420" y="110" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Memory</text>
20
+ <line x1="420" y1="120" x2="420" y2="700" stroke="#2196F3" stroke-width="2" stroke-dasharray="5,5"/>
21
+
22
+ <!-- LongTermMemory -->
23
+ <rect x="540" y="70" width="140" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="5"/>
24
+ <text x="610" y="95" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">LongTerm</text>
25
+ <text x="610" y="110" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Memory</text>
26
+ <line x1="610" y1="120" x2="610" y2="700" stroke="#9C27B0" stroke-width="2" stroke-dasharray="5,5"/>
27
+
28
+ <!-- Database -->
29
+ <rect x="730" y="70" width="120" height="50" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="5"/>
30
+ <text x="790" y="95" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Database</text>
31
+ <line x1="790" y1="120" x2="790" y2="700" stroke="#9C27B0" stroke-width="2" stroke-dasharray="5,5"/>
32
+
33
+ <!-- Sequence interactions -->
34
+ <!-- 1. add_node -->
35
+ <path d="M 100 160 L 250 160" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
36
+ <text x="175" y="155" text-anchor="middle" fill="#4CAF50" font-size="11">add_node(large_memory)</text>
37
+
38
+ <!-- 2. add -->
39
+ <path d="M 250 190 L 420 190" stroke="#2196F3" stroke-width="2" marker-end="url(#arr2)"/>
40
+ <text x="335" y="185" text-anchor="middle" fill="#2196F3" font-size="11">add(key, value, token_count)</text>
41
+
42
+ <!-- 3. Check -->
43
+ <rect x="360" y="210" width="120" height="60" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="5"/>
44
+ <text x="420" y="235" text-anchor="middle" fill="#FFFFFF" font-size="11">Check:</text>
45
+ <text x="420" y="250" text-anchor="middle" fill="#FFFFFF" font-size="11">token_count +</text>
46
+ <text x="420" y="265" text-anchor="middle" fill="#FFFFFF" font-size="11">current > max?</text>
47
+
48
+ <!-- Decision boxes -->
49
+ <rect x="520" y="300" width="180" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="5"/>
50
+ <text x="610" y="325" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Space Available</text>
51
+ <text x="610" y="345" text-anchor="middle" fill="#B0B0B0" font-size="10">(Add directly)</text>
52
+
53
+ <rect x="210" y="300" width="180" height="60" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="5"/>
54
+ <text x="300" y="325" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">No Space</text>
55
+ <text x="300" y="345" text-anchor="middle" fill="#B0B0B0" font-size="10">(Eviction needed)</text>
56
+
57
+ <!-- Space available path -->
58
+ <path d="M 480 240 L 610 240 L 610 300" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
59
+ <text x="545" y="235" text-anchor="middle" fill="#4CAF50" font-size="10">Space OK</text>
60
+
61
+ <rect x="550" y="380" width="120" height="40" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="2" rx="5"/>
62
+ <text x="610" y="405" text-anchor="middle" fill="#FFFFFF" font-size="11">Add node directly</text>
63
+
64
+ <path d="M 610 360 L 610 380" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
65
+ <path d="M 610 420 L 610 440 L 250 440" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
66
+ <text x="430" y="435" text-anchor="middle" fill="#4CAF50" font-size="11">Success</text>
67
+
68
+ <!-- No space path -->
69
+ <path d="M 360 240 L 300 240 L 300 300" stroke="#F44336" stroke-width="2" marker-end="url(#arr5)"/>
70
+ <text x="330" y="235" text-anchor="middle" fill="#F44336" font-size="10">No space</text>
71
+
72
+ <!-- Eviction steps -->
73
+ <rect x="250" y="380" width="150" height="40" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="5"/>
74
+ <text x="325" y="405" text-anchor="middle" fill="#FFFFFF" font-size="11">Sort by [importance,</text>
75
+
76
+ <rect x="250" y="435" width="150" height="40" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="5"/>
77
+ <text x="325" y="460" text-anchor="middle" fill="#FFFFFF" font-size="11">-recency]</text>
78
+
79
+ <path d="M 300 360 L 300 380" stroke="#FF9800" stroke-width="2" marker-end="url(#arr3)"/>
80
+ <path d="M 325 420 L 325 435" stroke="#FF9800" stroke-width="2" marker-end="url(#arr3)"/>
81
+
82
+ <rect x="250" y="490" width="150" height="40" fill="rgba(255, 152, 0, 0.3)" stroke="#FF9800" stroke-width="2" rx="5"/>
83
+ <text x="325" y="515" text-anchor="middle" fill="#FFFFFF" font-size="11">Evict low-importance</text>
84
+
85
+ <path d="M 325 475 L 325 490" stroke="#FF9800" stroke-width="2" marker-end="url(#arr3)"/>
86
+
87
+ <!-- Note box -->
88
+ <rect x="50" y="480" width="150" height="60" fill="rgba(255, 193, 7, 0.1)" stroke="#FFC107" stroke-width="2" rx="5" stroke-dasharray="5,5"/>
89
+ <text x="125" y="500" text-anchor="middle" fill="#FFC107" font-size="10" font-weight="bold">Note:</text>
90
+ <text x="125" y="515" text-anchor="middle" fill="#B0B0B0" font-size="9">Free enough tokens</text>
91
+ <text x="125" y="530" text-anchor="middle" fill="#B0B0B0" font-size="9">for new memory</text>
92
+
93
+ <!-- Return evicted nodes -->
94
+ <path d="M 350 510 L 250 510" stroke="#F44336" stroke-width="2" marker-end="url(#arr5)"/>
95
+ <text x="300" y="505" text-anchor="middle" fill="#F44336" font-size="10">evicted_nodes</text>
96
+
97
+ <!-- mark_evicted -->
98
+ <path d="M 250 560 L 610 560" stroke="#9C27B0" stroke-width="2" marker-end="url(#arr4)"/>
99
+ <text x="430" y="555" text-anchor="middle" fill="#9C27B0" font-size="11">mark_evicted(keys)</text>
100
+
101
+ <!-- UPDATE in_working_memory -->
102
+ <path d="M 610 580 L 790 580" stroke="#9C27B0" stroke-width="2" marker-end="url(#arr4)"/>
103
+ <text x="700" y="575" text-anchor="middle" fill="#9C27B0" font-size="11">UPDATE in_working_memory=FALSE</text>
104
+
105
+ <!-- Database response -->
106
+ <path d="M 790 600 L 610 600" stroke="#9C27B0" stroke-width="2" marker-end="url(#arr4)"/>
107
+ <text x="700" y="595" text-anchor="middle" fill="#9C27B0" font-size="10">Updated</text>
108
+
109
+ <!-- Add new node -->
110
+ <rect x="360" y="620" width="120" height="40" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="2" rx="5"/>
111
+ <text x="420" y="645" text-anchor="middle" fill="#FFFFFF" font-size="11">Add new node</text>
112
+
113
+ <path d="M 325 530 L 325 640 L 360 640" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
114
+ <path d="M 480 640 L 530 640 L 530 600 L 610 600" stroke="#4CAF50" stroke-width="2"/>
115
+
116
+ <path d="M 480 640 L 540 640 L 540 670 L 250 670" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
117
+ <text x="390" y="665" text-anchor="middle" fill="#4CAF50" font-size="11">Success</text>
118
+
119
+ <!-- Return to user -->
120
+ <path d="M 250 680 L 100 680" stroke="#4CAF50" stroke-width="2" marker-end="url(#arr1)"/>
121
+ <text x="175" y="675" text-anchor="middle" fill="#4CAF50" font-size="11">node_id</text>
122
+
123
+ <!-- Markers -->
124
+ <defs>
125
+ <marker id="arr1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
126
+ <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
127
+ </marker>
128
+ <marker id="arr2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
129
+ <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
130
+ </marker>
131
+ <marker id="arr3" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
132
+ <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
133
+ </marker>
134
+ <marker id="arr4" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
135
+ <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
136
+ </marker>
137
+ <marker id="arr5" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
138
+ <polygon points="0 0, 10 3, 0 6" fill="#F44336"/>
139
+ </marker>
140
+ </defs>
141
+ </svg>
data/docs/assets/images/htm-memory-addition-flow.svg ADDED
@@ -0,0 +1,138 @@
1
+ <svg viewBox="0 0 1000 800" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="500" y="30" text-anchor="middle" fill="#FFFFFF" font-size="20" font-weight="bold">Memory Addition Flow (Client-Side Embedding Generation)</text>
4
+
5
+ <!-- User -->
6
+ <rect x="50" y="80" width="180" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
7
+ <text x="140" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">User: add_message</text>
8
+
9
+ <!-- HTM -->
10
+ <rect x="280" y="80" width="140" height="60" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
11
+ <text x="350" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">HTM</text>
12
+
13
+ <!-- EmbeddingService -->
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
+ <text x="565" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">EmbeddingService</text>
16
+
17
+ <!-- Ollama/OpenAI -->
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>
20
+
21
+ <!-- LongTermMemory -->
22
+ <rect x="280" y="260" width="180" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
23
+ <text x="370" y="295" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">LongTermMemory</text>
24
+
25
+ <!-- PostgreSQL -->
26
+ <rect x="510" y="260" width="140" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
27
+ <text x="580" y="295" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">PostgreSQL</text>
28
+
29
+ <!-- WorkingMemory -->
30
+ <rect x="280" y="420" width="180" height="60" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
31
+ <text x="370" y="455" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">WorkingMemory</text>
32
+
33
+ <!-- Flow arrows and labels -->
34
+ <!-- 1. Request -->
35
+ <path d="M 230 110 L 280 110" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>
36
+ <text x="255" y="105" text-anchor="middle" fill="#4CAF50" font-size="11">1. Request</text>
37
+
38
+ <!-- 2. Count tokens -->
39
+ <path d="M 350 140 L 490 140 L 490 135" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrowOrange)"/>
40
+ <text x="420" y="135" text-anchor="middle" fill="#FF9800" font-size="11">2. Count tokens</text>
41
+
42
+ <!-- 3. Return count -->
43
+ <path d="M 535 135 L 535 160 L 350 160 L 350 145" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrowOrange)"/>
44
+ <text x="440" y="155" text-anchor="middle" fill="#FF9800" font-size="11">3. Return count</text>
45
+
46
+ <!-- 4. Generate embedding -->
47
+ <path d="M 420 110 L 470 110" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrowOrange)"/>
48
+ <text x="445" y="105" text-anchor="middle" fill="#FF9800" font-size="11">4. Generate</text>
49
+
50
+ <!-- 5. HTTP call -->
51
+ <path d="M 660 110 L 710 110" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrowYellow)"/>
52
+ <text x="685" y="105" text-anchor="middle" fill="#FFC107" font-size="11">5. HTTP call</text>
53
+
54
+ <!-- 6. Return vector -->
55
+ <path d="M 800 140 L 800 180 L 565 180 L 565 145" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrowYellow)"/>
56
+ <text x="680" y="175" text-anchor="middle" fill="#FFC107" font-size="11">6. Return vector</text>
57
+
58
+ <!-- 7. Return embedding -->
59
+ <path d="M 540 140 L 540 200 L 350 200 L 350 145" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrowOrange)"/>
60
+ <text x="445" y="195" text-anchor="middle" fill="#FF9800" font-size="11">7. Return embedding</text>
61
+
62
+ <!-- 8. Persist with embedding -->
63
+ <path d="M 350 145 L 350 260" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrowPurple)"/>
64
+ <text x="300" y="210" text-anchor="middle" fill="#9C27B0" font-size="11">8. Persist with</text>
65
+ <text x="300" y="225" text-anchor="middle" fill="#9C27B0" font-size="11">embedding</text>
66
+
67
+ <!-- 9. INSERT with embedding -->
68
+ <path d="M 460 290 L 510 290" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrowPurple)"/>
69
+ <text x="485" y="285" text-anchor="middle" fill="#9C27B0" font-size="11">9. INSERT</text>
70
+
71
+ <!-- 10. Return node_id -->
72
+ <path d="M 580 260 L 580 240 L 370 240 L 370 255" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrowPurple)"/>
73
+ <text x="475" y="235" text-anchor="middle" fill="#9C27B0" font-size="11">10. Return node_id</text>
74
+
75
+ <!-- 11. Return node_id -->
76
+ <path d="M 340 260 L 340 230 L 350 230 L 350 220 L 350 145" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrowBlue)"/>
77
+ <text x="250" y="235" text-anchor="middle" fill="#2196F3" font-size="11">11. node_id</text>
78
+
79
+ <!-- 12. Check space -->
80
+ <path d="M 350 230 L 350 340 L 320 340 L 320 420" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrowBlue)"/>
81
+ <text x="280" y="375" text-anchor="middle" fill="#2196F3" font-size="11">12. Check</text>
82
+ <text x="280" y="390" text-anchor="middle" fill="#2196F3" font-size="11">space</text>
83
+
84
+ <!-- Decision diamond -->
85
+ <polygon points="370,500 420,450 470,500 420,550" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3"/>
86
+ <text x="420" y="505" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Has</text>
87
+ <text x="420" y="520" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Space?</text>
88
+
89
+ <!-- No path - Evict -->
90
+ <rect x="520" y="470" width="140" height="60" fill="rgba(244, 67, 54, 0.3)" stroke="#F44336" stroke-width="3" rx="8"/>
91
+ <text x="590" y="505" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Evict nodes</text>
92
+
93
+ <path d="M 470 500 L 520 500" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrowRed)"/>
94
+ <text x="495" y="495" text-anchor="middle" fill="#F44336" font-size="11">No</text>
95
+
96
+ <!-- 14. Mark evicted -->
97
+ <path d="M 590 470 L 590 340 L 370 340 L 370 320" stroke="#F44336" stroke-width="2" fill="none" marker-end="url(#arrowRed)"/>
98
+ <text x="480" y="335" text-anchor="middle" fill="#F44336" font-size="11">14. Mark evicted</text>
99
+
100
+ <!-- Yes path -->
101
+ <rect x="280" y="600" width="180" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
102
+ <text x="370" y="635" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Add to WM</text>
103
+
104
+ <path d="M 420 550 L 420 600" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>
105
+ <text x="435" y="580" text-anchor="middle" fill="#4CAF50" font-size="11">Yes</text>
106
+
107
+ <path d="M 590 530 L 590 630 L 460 630" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>
108
+
109
+ <!-- 15. Success -->
110
+ <path d="M 280 630 L 230 630 L 230 110" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>
111
+ <text x="200" y="375" text-anchor="middle" fill="#4CAF50" font-size="11">15. Success</text>
112
+
113
+ <!-- 17. Return node_id -->
114
+ <text x="200" y="140" text-anchor="middle" fill="#4CAF50" font-size="11">17. Return</text>
115
+ <text x="200" y="155" text-anchor="middle" fill="#4CAF50" font-size="11">node_id</text>
116
+
117
+ <!-- Markers -->
118
+ <defs>
119
+ <marker id="arrowGreen" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
120
+ <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
121
+ </marker>
122
+ <marker id="arrowBlue" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
123
+ <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
124
+ </marker>
125
+ <marker id="arrowOrange" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
126
+ <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
127
+ </marker>
128
+ <marker id="arrowYellow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
129
+ <polygon points="0 0, 10 3, 0 6" fill="#FFC107"/>
130
+ </marker>
131
+ <marker id="arrowPurple" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
132
+ <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
133
+ </marker>
134
+ <marker id="arrowRed" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
135
+ <polygon points="0 0, 10 3, 0 6" fill="#F44336"/>
136
+ </marker>
137
+ </defs>
138
+ </svg>
data/docs/assets/images/htm-memory-recall-flow.svg ADDED
@@ -0,0 +1,152 @@
1
+ <svg viewBox="0 0 1000 700" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
2
+ <!-- Title -->
3
+ <text x="500" y="30" text-anchor="middle" fill="#FFFFFF" font-size="20" font-weight="bold">Memory Recall Flow (RAG-Based Retrieval)</text>
4
+
5
+ <!-- User -->
6
+ <rect x="50" y="80" width="140" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
7
+ <text x="120" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">User: recall</text>
8
+
9
+ <!-- HTM -->
10
+ <rect x="240" y="80" width="140" height="60" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
11
+ <text x="310" y="115" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">HTM</text>
12
+
13
+ <!-- Parse Time -->
14
+ <rect x="430" y="80" width="180" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
15
+ <text x="520" y="110" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Parse Natural</text>
16
+ <text x="520" y="130" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Language</text>
17
+
18
+ <!-- EmbeddingService -->
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
+ <text x="335" y="215" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">EmbeddingService</text>
21
+
22
+ <!-- Ollama/OpenAI -->
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>
25
+
26
+ <!-- LongTermMemory -->
27
+ <rect x="240" y="300" width="180" height="60" fill="rgba(156, 39, 176, 0.3)" stroke="#9C27B0" stroke-width="3" rx="8"/>
28
+ <text x="330" y="335" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">LongTermMemory</text>
29
+
30
+ <!-- Search Strategy Diamond -->
31
+ <polygon points="520,380 570,330 620,380 570,430" fill="rgba(255, 193, 7, 0.3)" stroke="#FFC107" stroke-width="3"/>
32
+ <text x="570" y="380" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Search</text>
33
+ <text x="570" y="395" text-anchor="middle" fill="#FFFFFF" font-size="12" font-weight="bold">Strategy</text>
34
+
35
+ <!-- Vector Search -->
36
+ <rect x="700" y="300" width="150" height="60" fill="rgba(103, 58, 183, 0.3)" stroke="#673AB7" stroke-width="3" rx="8"/>
37
+ <text x="775" y="330" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Vector Search</text>
38
+ <text x="775" y="348" text-anchor="middle" fill="#B0B0B0" font-size="11">(pgvector HNSW)</text>
39
+
40
+ <!-- Full-text Search -->
41
+ <rect x="700" y="380" width="150" height="60" fill="rgba(3, 169, 244, 0.3)" stroke="#03A9F4" stroke-width="3" rx="8"/>
42
+ <text x="775" y="410" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Full-Text Search</text>
43
+ <text x="775" y="428" text-anchor="middle" fill="#B0B0B0" font-size="11">(ts_rank GIN)</text>
44
+
45
+ <!-- Hybrid Search -->
46
+ <rect x="700" y="460" width="150" height="60" fill="rgba(255, 87, 34, 0.3)" stroke="#FF5722" stroke-width="3" rx="8"/>
47
+ <text x="775" y="490" text-anchor="middle" fill="#FFFFFF" font-size="13" font-weight="bold">Hybrid Search</text>
48
+ <text x="775" y="508" text-anchor="middle" fill="#B0B0B0" font-size="11">(Hybrid + RRF)</text>
49
+
50
+ <!-- Results -->
51
+ <rect x="700" y="550" width="150" height="60" fill="rgba(76, 175, 80, 0.3)" stroke="#4CAF50" stroke-width="3" rx="8"/>
52
+ <text x="775" y="585" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">Return Results</text>
53
+
54
+ <!-- WorkingMemory -->
55
+ <rect x="240" y="550" width="180" height="60" fill="rgba(33, 150, 243, 0.3)" stroke="#2196F3" stroke-width="3" rx="8"/>
56
+ <text x="330" y="585" text-anchor="middle" fill="#FFFFFF" font-size="14" font-weight="bold">WorkingMemory</text>
57
+
58
+ <!-- Flow arrows -->
59
+ <!-- 1. Request -->
60
+ <path d="M 190 110 L 240 110" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
61
+ <text x="215" y="105" text-anchor="middle" fill="#4CAF50" font-size="11">1. Request</text>
62
+
63
+ <!-- 2. Parse timeframe -->
64
+ <path d="M 380 110 L 430 110" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
65
+ <text x="405" y="105" text-anchor="middle" fill="#9C27B0" font-size="11">2. Parse</text>
66
+
67
+ <!-- 3. Return range -->
68
+ <path d="M 520 140 L 520 160 L 310 160 L 310 145" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
69
+ <text x="415" y="155" text-anchor="middle" fill="#9C27B0" font-size="11">3. Return range</text>
70
+
71
+ <!-- 4. Generate query embedding -->
72
+ <path d="M 310 145 L 310 180" stroke="#FF9800" stroke-width="2" fill="none" marker-end="url(#arrow3)"/>
73
+ <text x="250" y="165" text-anchor="middle" fill="#FF9800" font-size="11">4. Generate</text>
74
+ <text x="250" y="178" text-anchor="middle" fill="#FF9800" font-size="11">embedding</text>
75
+
76
+ <!-- 5. HTTP call -->
77
+ <path d="M 430 210 L 480 210" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
78
+ <text x="455" y="205" text-anchor="middle" fill="#FFC107" font-size="11">5. HTTP</text>
79
+
80
+ <!-- 6. Return vector -->
81
+ <path d="M 570 240 L 570 260 L 335 260 L 335 245" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
82
+ <text x="455" y="255" text-anchor="middle" fill="#FFC107" font-size="11">6. Return vector</text>
83
+
84
+ <!-- 7. Return embedding -->
85
+ <path d="M 285 240 L 285 280 L 310 280 L 310 265 L 310 145" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrow5)"/>
86
+ <text x="255" y="265" text-anchor="middle" fill="#2196F3" font-size="11">7. embedding</text>
87
+
88
+ <!-- 8. Search -->
89
+ <path d="M 330 260 L 330 300" stroke="#9C27B0" stroke-width="2" fill="none" marker-end="url(#arrow2)"/>
90
+ <text x="345" y="285" text-anchor="middle" fill="#9C27B0" font-size="11">8. Search</text>
91
+
92
+ <!-- 9. Strategy paths -->
93
+ <path d="M 420 330 L 520 330 L 520 350 L 570 350 L 570 380" stroke="#FFC107" stroke-width="2" fill="none" marker-end="url(#arrow4)"/>
94
+
95
+ <path d="M 620 380 L 700 380 L 700 330" stroke="#673AB7" stroke-width="2" fill="none" marker-end="url(#arrow6)"/>
96
+ <text x="660" y="360" text-anchor="middle" fill="#673AB7" font-size="11">:vector</text>
97
+
98
+ <path d="M 620 390 L 700 390 L 700 410" stroke="#03A9F4" stroke-width="2" fill="none" marker-end="url(#arrow7)"/>
99
+ <text x="660" y="398" text-anchor="middle" fill="#03A9F4" font-size="11">:fulltext</text>
100
+
101
+ <path d="M 615 410 L 700 410 L 700 490" stroke="#FF5722" stroke-width="2" fill="none" marker-end="url(#arrow8)"/>
102
+ <text x="660" y="450" text-anchor="middle" fill="#FF5722" font-size="11">:hybrid</text>
103
+
104
+ <!-- 10. Return results -->
105
+ <path d="M 775 360 L 775 550" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
106
+ <path d="M 775 440 L 775 550" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
107
+ <path d="M 775 520 L 775 550" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
108
+ <text x="795" y="475" text-anchor="start" fill="#4CAF50" font-size="11">10. Results</text>
109
+
110
+ <!-- 11. Results -->
111
+ <path d="M 700 580 L 420 580 L 420 330 L 420 360" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
112
+ <text x="560" y="575" text-anchor="middle" fill="#4CAF50" font-size="11">11. Results</text>
113
+
114
+ <!-- 13. Add to WM -->
115
+ <path d="M 285 360 L 285 490 L 265 490 L 265 540 L 280 540 L 280 550" stroke="#2196F3" stroke-width="2" fill="none" marker-end="url(#arrow5)"/>
116
+ <text x="240" y="475" text-anchor="middle" fill="#2196F3" font-size="11">13. For</text>
117
+ <text x="240" y="490" text-anchor="middle" fill="#2196F3" font-size="11">each</text>
118
+ <text x="240" y="505" text-anchor="middle" fill="#2196F3" font-size="11">result</text>
119
+
120
+ <!-- 13. Return memories -->
121
+ <path d="M 240 580 L 120 580 L 120 140" stroke="#4CAF50" stroke-width="2" fill="none" marker-end="url(#arrow1)"/>
122
+ <text x="180" y="375" text-anchor="middle" fill="#4CAF50" font-size="11">13. Return</text>
123
+ <text x="180" y="390" text-anchor="middle" fill="#4CAF50" font-size="11">memories</text>
124
+
125
+ <!-- Markers -->
126
+ <defs>
127
+ <marker id="arrow1" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
128
+ <polygon points="0 0, 10 3, 0 6" fill="#4CAF50"/>
129
+ </marker>
130
+ <marker id="arrow2" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
131
+ <polygon points="0 0, 10 3, 0 6" fill="#9C27B0"/>
132
+ </marker>
133
+ <marker id="arrow3" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
134
+ <polygon points="0 0, 10 3, 0 6" fill="#FF9800"/>
135
+ </marker>
136
+ <marker id="arrow4" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
137
+ <polygon points="0 0, 10 3, 0 6" fill="#FFC107"/>
138
+ </marker>
139
+ <marker id="arrow5" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
140
+ <polygon points="0 0, 10 3, 0 6" fill="#2196F3"/>
141
+ </marker>
142
+ <marker id="arrow6" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
143
+ <polygon points="0 0, 10 3, 0 6" fill="#673AB7"/>
144
+ </marker>
145
+ <marker id="arrow7" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
146
+ <polygon points="0 0, 10 3, 0 6" fill="#03A9F4"/>
147
+ </marker>
148
+ <marker id="arrow8" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
149
+ <polygon points="0 0, 10 3, 0 6" fill="#FF5722"/>
150
+ </marker>
151
+ </defs>
152
+ </svg>