htm 0.0.14 → 0.0.15

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 (71) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +33 -0
  3. data/README.md +269 -79
  4. data/db/migrate/00003_create_file_sources.rb +5 -0
  5. data/db/migrate/00004_create_nodes.rb +17 -0
  6. data/db/migrate/00005_create_tags.rb +7 -0
  7. data/db/migrate/00006_create_node_tags.rb +2 -0
  8. data/db/migrate/00007_create_robot_nodes.rb +7 -0
  9. data/db/schema.sql +41 -29
  10. data/docs/api/yard/HTM/Configuration.md +54 -0
  11. data/docs/api/yard/HTM/Database.md +13 -10
  12. data/docs/api/yard/HTM/EmbeddingService.md +5 -1
  13. data/docs/api/yard/HTM/LongTermMemory.md +18 -277
  14. data/docs/api/yard/HTM/PropositionError.md +18 -0
  15. data/docs/api/yard/HTM/PropositionService.md +66 -0
  16. data/docs/api/yard/HTM/QueryCache.md +88 -0
  17. data/docs/api/yard/HTM/RobotGroup.md +481 -0
  18. data/docs/api/yard/HTM/SqlBuilder.md +108 -0
  19. data/docs/api/yard/HTM/TagService.md +4 -0
  20. data/docs/api/yard/HTM/Telemetry/NullInstrument.md +13 -0
  21. data/docs/api/yard/HTM/Telemetry/NullMeter.md +15 -0
  22. data/docs/api/yard/HTM/Telemetry.md +109 -0
  23. data/docs/api/yard/HTM/WorkingMemoryChannel.md +176 -0
  24. data/docs/api/yard/HTM.md +11 -23
  25. data/docs/api/yard/index.csv +102 -25
  26. data/docs/api/yard-reference.md +8 -0
  27. data/docs/assets/images/multi-provider-failover.svg +51 -0
  28. data/docs/assets/images/robot-group-architecture.svg +65 -0
  29. data/docs/database/README.md +3 -3
  30. data/docs/database/public.file_sources.svg +29 -21
  31. data/docs/database/public.node_tags.md +2 -0
  32. data/docs/database/public.node_tags.svg +53 -41
  33. data/docs/database/public.nodes.md +2 -0
  34. data/docs/database/public.nodes.svg +52 -40
  35. data/docs/database/public.robot_nodes.md +2 -0
  36. data/docs/database/public.robot_nodes.svg +30 -22
  37. data/docs/database/public.robots.svg +16 -12
  38. data/docs/database/public.tags.md +3 -0
  39. data/docs/database/public.tags.svg +41 -33
  40. data/docs/database/schema.json +66 -0
  41. data/docs/database/schema.svg +60 -48
  42. data/docs/development/index.md +13 -0
  43. data/docs/development/rake-tasks.md +1068 -0
  44. data/docs/getting-started/quick-start.md +144 -155
  45. data/docs/guides/adding-memories.md +2 -3
  46. data/docs/guides/context-assembly.md +185 -184
  47. data/docs/guides/getting-started.md +154 -148
  48. data/docs/guides/index.md +7 -0
  49. data/docs/guides/long-term-memory.md +60 -92
  50. data/docs/guides/mcp-server.md +617 -0
  51. data/docs/guides/multi-robot.md +249 -345
  52. data/docs/guides/recalling-memories.md +153 -163
  53. data/docs/guides/robot-groups.md +604 -0
  54. data/docs/guides/search-strategies.md +61 -58
  55. data/docs/guides/working-memory.md +103 -136
  56. data/docs/index.md +30 -26
  57. data/examples/robot_groups/robot_worker.rb +1 -2
  58. data/examples/robot_groups/same_process.rb +1 -4
  59. data/lib/htm/robot_group.rb +721 -0
  60. data/lib/htm/version.rb +1 -1
  61. data/lib/htm/working_memory_channel.rb +250 -0
  62. data/lib/htm.rb +2 -0
  63. data/mkdocs.yml +2 -0
  64. metadata +18 -9
  65. data/db/migrate/00009_add_working_memory_to_robot_nodes.rb +0 -12
  66. data/db/migrate/00010_add_soft_delete_to_associations.rb +0 -29
  67. data/db/migrate/00011_add_performance_indexes.rb +0 -21
  68. data/db/migrate/00012_add_tags_trigram_index.rb +0 -18
  69. data/db/migrate/00013_enable_lz4_compression.rb +0 -43
  70. data/examples/robot_groups/lib/robot_group.rb +0 -419
  71. data/examples/robot_groups/lib/working_memory_channel.rb +0 -140
data/docs/database/public.tags.svg CHANGED
@@ -4,46 +4,54 @@
4
4
  <!-- Generated by graphviz version 12.1.2 (20240928.0832)
5
5
  -->
6
6
  <!-- Title: public.tags Pages: 1 -->
7
- <svg width="1466pt" height="863pt"
8
- viewBox="0.00 0.00 1465.73 863.20" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
9
- <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 859.2)">
7
+ <svg width="1466pt" height="894pt"
8
+ viewBox="0.00 0.00 1465.73 894.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
9
+ <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 890)">
10
10
  <title>public.tags</title>
11
- <polygon fill="white" stroke="none" points="-4,4 -4,-859.2 1461.73,-859.2 1461.73,4 -4,4"/>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-890 1461.73,-890 1461.73,4 -4,4"/>
12
12
  <!-- public.tags -->
13
13
  <g id="node1" class="node">
14
14
  <title>public.tags</title>
15
- <polygon fill="#efefef" stroke="none" points="46.2,-305 46.2,-351 650.83,-351 650.83,-305 46.2,-305"/>
16
- <polygon fill="none" stroke="black" points="46.2,-305 46.2,-351 650.83,-351 650.83,-305 46.2,-305"/>
17
- <text text-anchor="start" x="247.02" y="-328.8" font-family="Arial Bold" font-size="18.00">public.tags</text>
18
- <text text-anchor="start" x="325.51" y="-328.8" font-family="Arial" font-size="14.00">    </text>
19
- <text text-anchor="start" x="356.63" y="-328.8" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
- <text text-anchor="start" x="236.06" y="-314.4" font-family="Arial" font-size="14.00" fill="#333333">Unique tag names for categorization</text>
21
- <polygon fill="none" stroke="black" points="46.2,-274.2 46.2,-305 650.83,-305 650.83,-274.2 46.2,-274.2"/>
22
- <text text-anchor="start" x="53.2" y="-286.4" font-family="Arial" font-size="14.00">created_at </text>
23
- <text text-anchor="start" x="123.25" y="-286.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
24
- <text text-anchor="start" x="288.97" y="-286.4" font-family="Arial" font-size="14.00"> When this tag was created</text>
25
- <polygon fill="none" stroke="black" points="46.2,-243.4 46.2,-274.2 650.83,-274.2 650.83,-243.4 46.2,-243.4"/>
26
- <text text-anchor="start" x="53.2" y="-255.6" font-family="Arial" font-size="14.00">id </text>
27
- <text text-anchor="start" x="67.99" y="-255.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
28
- <polygon fill="none" stroke="black" points="46.2,-212.6 46.2,-243.4 650.83,-243.4 650.83,-212.6 46.2,-212.6"/>
29
- <text text-anchor="start" x="53.2" y="-224.8" font-family="Arial" font-size="14.00">name </text>
30
- <text text-anchor="start" x="92.11" y="-224.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
31
- <text text-anchor="start" x="122.45" y="-224.8" font-family="Arial" font-size="14.00"> Hierarchical tag in format: root:level1:level2 (e.g., database:postgresql:timescaledb)</text>
32
- <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-211.1 44.7,-352.5 652.33,-352.5 652.33,-211.1 44.7,-211.1"/>
15
+ <polygon fill="#efefef" stroke="none" points="46.2,-320.4 46.2,-366.4 650.83,-366.4 650.83,-320.4 46.2,-320.4"/>
16
+ <polygon fill="none" stroke="black" points="46.2,-320.4 46.2,-366.4 650.83,-366.4 650.83,-320.4 46.2,-320.4"/>
17
+ <text text-anchor="start" x="247.02" y="-344.2" font-family="Arial Bold" font-size="18.00">public.tags</text>
18
+ <text text-anchor="start" x="325.51" y="-344.2" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="356.63" y="-344.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <text text-anchor="start" x="236.06" y="-329.8" font-family="Arial" font-size="14.00" fill="#333333">Unique tag names for categorization</text>
21
+ <polygon fill="none" stroke="black" points="46.2,-289.6 46.2,-320.4 650.83,-320.4 650.83,-289.6 46.2,-289.6"/>
22
+ <text text-anchor="start" x="53.2" y="-301.8" font-family="Arial" font-size="14.00">created_at </text>
23
+ <text text-anchor="start" x="123.25" y="-301.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
24
+ <text text-anchor="start" x="288.97" y="-301.8" font-family="Arial" font-size="14.00"> When this tag was created</text>
25
+ <polygon fill="none" stroke="black" points="46.2,-258.8 46.2,-289.6 650.83,-289.6 650.83,-258.8 46.2,-258.8"/>
26
+ <text text-anchor="start" x="53.2" y="-271" font-family="Arial" font-size="14.00">deleted_at </text>
27
+ <text text-anchor="start" x="122.48" y="-271" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
28
+ <text text-anchor="start" x="288.21" y="-271" font-family="Arial" font-size="14.00"> Soft delete timestamp</text>
29
+ <polygon fill="none" stroke="black" points="46.2,-228 46.2,-258.8 650.83,-258.8 650.83,-228 46.2,-228"/>
30
+ <text text-anchor="start" x="53.2" y="-240.2" font-family="Arial" font-size="14.00">id </text>
31
+ <text text-anchor="start" x="67.99" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
32
+ <polygon fill="none" stroke="black" points="46.2,-197.2 46.2,-228 650.83,-228 650.83,-197.2 46.2,-197.2"/>
33
+ <text text-anchor="start" x="53.2" y="-209.4" font-family="Arial" font-size="14.00">name </text>
34
+ <text text-anchor="start" x="92.11" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
35
+ <text text-anchor="start" x="122.45" y="-209.4" font-family="Arial" font-size="14.00"> Hierarchical tag in format: root:level1:level2 (e.g., database:postgresql:timescaledb)</text>
36
+ <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-195.7 44.7,-367.9 652.33,-367.9 652.33,-195.7 44.7,-195.7"/>
33
37
  </g>
34
38
  <!-- public.node_tags -->
35
39
  <g id="node2" class="node">
36
40
  <title>public.node_tags</title>
37
- <polygon fill="#efefef" stroke="none" points="482.91,-766 482.91,-812 952.12,-812 952.12,-766 482.91,-766"/>
38
- <polygon fill="none" stroke="black" points="482.91,-766 482.91,-812 952.12,-812 952.12,-766 482.91,-766"/>
39
- <text text-anchor="start" x="594.03" y="-789.8" font-family="Arial Bold" font-size="18.00">public.node_tags</text>
40
- <text text-anchor="start" x="716.51" y="-789.8" font-family="Arial" font-size="14.00">    </text>
41
- <text text-anchor="start" x="747.62" y="-789.8" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
42
- <text text-anchor="start" x="556.43" y="-775.4" font-family="Arial" font-size="14.00" fill="#333333">Join table connecting nodes to tags (many&#45;to&#45;many)</text>
41
+ <polygon fill="#efefef" stroke="none" points="482.91,-796.8 482.91,-842.8 952.12,-842.8 952.12,-796.8 482.91,-796.8"/>
42
+ <polygon fill="none" stroke="black" points="482.91,-796.8 482.91,-842.8 952.12,-842.8 952.12,-796.8 482.91,-796.8"/>
43
+ <text text-anchor="start" x="594.03" y="-820.6" font-family="Arial Bold" font-size="18.00">public.node_tags</text>
44
+ <text text-anchor="start" x="716.51" y="-820.6" font-family="Arial" font-size="14.00">    </text>
45
+ <text text-anchor="start" x="747.62" y="-820.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
46
+ <text text-anchor="start" x="556.43" y="-806.2" font-family="Arial" font-size="14.00" fill="#333333">Join table connecting nodes to tags (many&#45;to&#45;many)</text>
47
+ <polygon fill="none" stroke="black" points="482.91,-766 482.91,-796.8 952.12,-796.8 952.12,-766 482.91,-766"/>
48
+ <text text-anchor="start" x="489.91" y="-778.2" font-family="Arial" font-size="14.00">created_at </text>
49
+ <text text-anchor="start" x="559.95" y="-778.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
50
+ <text text-anchor="start" x="725.68" y="-778.2" font-family="Arial" font-size="14.00"> When this association was created</text>
43
51
  <polygon fill="none" stroke="black" points="482.91,-735.2 482.91,-766 952.12,-766 952.12,-735.2 482.91,-735.2"/>
44
- <text text-anchor="start" x="489.91" y="-747.4" font-family="Arial" font-size="14.00">created_at </text>
45
- <text text-anchor="start" x="559.95" y="-747.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
46
- <text text-anchor="start" x="725.68" y="-747.4" font-family="Arial" font-size="14.00"> When this association was created</text>
52
+ <text text-anchor="start" x="489.91" y="-747.4" font-family="Arial" font-size="14.00">deleted_at </text>
53
+ <text text-anchor="start" x="559.19" y="-747.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
54
+ <text text-anchor="start" x="724.91" y="-747.4" font-family="Arial" font-size="14.00"> Soft delete timestamp</text>
47
55
  <polygon fill="none" stroke="black" points="482.91,-704.4 482.91,-735.2 952.12,-735.2 952.12,-704.4 482.91,-704.4"/>
48
56
  <text text-anchor="start" x="489.91" y="-716.6" font-family="Arial" font-size="14.00">id </text>
49
57
  <text text-anchor="start" x="504.69" y="-716.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
@@ -59,8 +67,8 @@
59
67
  <!-- public.node_tags&#45;&gt;public.tags -->
60
68
  <g id="edge1" class="edge">
61
69
  <title>public.node_tags:tag_id&#45;&gt;public.tags:id</title>
62
- <path fill="none" stroke="black" d="M472.11,-655.39C461.78,-646.74 475.41,-619.83 482.91,-599.6 523.51,-490 610.76,-507 650.83,-397.2 671.91,-339.41 713.34,-258.8 651.83,-258.8"/>
63
- <polygon fill="black" stroke="black" points="471.97,-655.35 480.35,-662.43 477.1,-656.82 481.26,-658.02 481.26,-658.02 481.26,-658.02 477.1,-656.82 482.82,-653.78 471.97,-655.35"/>
70
+ <path fill="none" stroke="black" d="M472.07,-655.38C461.65,-646.69 475.02,-619.68 482.91,-599.6 523.75,-495.64 610.56,-516.79 650.83,-412.6 677.93,-342.46 727.03,-243.4 651.83,-243.4"/>
71
+ <polygon fill="black" stroke="black" points="471.97,-655.35 480.34,-662.43 477.1,-656.82 481.26,-658.02 481.26,-658.02 481.26,-658.02 477.1,-656.82 482.83,-653.78 471.97,-655.35"/>
64
72
  <text text-anchor="start" x="152.05" y="-668.2" font-family="Arial" font-size="10.00">FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE</text>
65
73
  </g>
66
74
  <!-- public.nodes -->
data/docs/database/schema.json CHANGED
@@ -121,6 +121,12 @@
121
121
  "default": "CURRENT_TIMESTAMP",
122
122
  "comment": "When this association was created"
123
123
  },
124
+ {
125
+ "name": "deleted_at",
126
+ "type": "timestamp with time zone",
127
+ "nullable": true,
128
+ "comment": "Soft delete timestamp"
129
+ },
124
130
  {
125
131
  "name": "id",
126
132
  "type": "bigint",
@@ -141,6 +147,14 @@
141
147
  }
142
148
  ],
143
149
  "indexes": [
150
+ {
151
+ "name": "idx_node_tags_deleted_at",
152
+ "def": "CREATE INDEX idx_node_tags_deleted_at ON public.node_tags USING btree (deleted_at)",
153
+ "table": "public.node_tags",
154
+ "columns": [
155
+ "deleted_at"
156
+ ]
157
+ },
144
158
  {
145
159
  "name": "idx_node_tags_node_id",
146
160
  "def": "CREATE INDEX idx_node_tags_node_id ON public.node_tags USING btree (node_id)",
@@ -318,6 +332,22 @@
318
332
  "access_count"
319
333
  ]
320
334
  },
335
+ {
336
+ "name": "idx_nodes_active",
337
+ "def": "CREATE INDEX idx_nodes_active ON public.nodes USING btree (id) WHERE (deleted_at IS NULL)",
338
+ "table": "public.nodes",
339
+ "columns": [
340
+ "id"
341
+ ]
342
+ },
343
+ {
344
+ "name": "idx_nodes_active_with_embedding",
345
+ "def": "CREATE INDEX idx_nodes_active_with_embedding ON public.nodes USING btree (id) WHERE ((deleted_at IS NULL) AND (embedding IS NOT NULL))",
346
+ "table": "public.nodes",
347
+ "columns": [
348
+ "id"
349
+ ]
350
+ },
321
351
  {
322
352
  "name": "idx_nodes_content_gin",
323
353
  "def": "CREATE INDEX idx_nodes_content_gin ON public.nodes USING gin (to_tsvector('english'::regconfig, content))",
@@ -471,6 +501,12 @@
471
501
  "nullable": true,
472
502
  "default": "CURRENT_TIMESTAMP"
473
503
  },
504
+ {
505
+ "name": "deleted_at",
506
+ "type": "timestamp with time zone",
507
+ "nullable": true,
508
+ "comment": "Soft delete timestamp"
509
+ },
474
510
  {
475
511
  "name": "first_remembered_at",
476
512
  "type": "timestamp with time zone",
@@ -525,6 +561,14 @@
525
561
  }
526
562
  ],
527
563
  "indexes": [
564
+ {
565
+ "name": "idx_robot_nodes_deleted_at",
566
+ "def": "CREATE INDEX idx_robot_nodes_deleted_at ON public.robot_nodes USING btree (deleted_at)",
567
+ "table": "public.robot_nodes",
568
+ "columns": [
569
+ "deleted_at"
570
+ ]
571
+ },
528
572
  {
529
573
  "name": "idx_robot_nodes_last_remembered_at",
530
574
  "def": "CREATE INDEX idx_robot_nodes_last_remembered_at ON public.robot_nodes USING btree (last_remembered_at)",
@@ -715,6 +759,12 @@
715
759
  "default": "CURRENT_TIMESTAMP",
716
760
  "comment": "When this tag was created"
717
761
  },
762
+ {
763
+ "name": "deleted_at",
764
+ "type": "timestamp with time zone",
765
+ "nullable": true,
766
+ "comment": "Soft delete timestamp"
767
+ },
718
768
  {
719
769
  "name": "id",
720
770
  "type": "bigint",
@@ -729,6 +779,14 @@
729
779
  }
730
780
  ],
731
781
  "indexes": [
782
+ {
783
+ "name": "idx_tags_deleted_at",
784
+ "def": "CREATE INDEX idx_tags_deleted_at ON public.tags USING btree (deleted_at)",
785
+ "table": "public.tags",
786
+ "columns": [
787
+ "deleted_at"
788
+ ]
789
+ },
732
790
  {
733
791
  "name": "idx_tags_name_pattern",
734
792
  "def": "CREATE INDEX idx_tags_name_pattern ON public.tags USING btree (name text_pattern_ops)",
@@ -737,6 +795,14 @@
737
795
  "name"
738
796
  ]
739
797
  },
798
+ {
799
+ "name": "idx_tags_name_trgm",
800
+ "def": "CREATE INDEX idx_tags_name_trgm ON public.tags USING gin (name gin_trgm_ops)",
801
+ "table": "public.tags",
802
+ "columns": [
803
+ "name"
804
+ ]
805
+ },
740
806
  {
741
807
  "name": "idx_tags_name_unique",
742
808
  "def": "CREATE UNIQUE INDEX idx_tags_name_unique ON public.tags USING btree (name)",
data/docs/database/schema.svg CHANGED
@@ -4,11 +4,11 @@
4
4
  <!-- Generated by graphviz version 12.1.2 (20240928.0832)
5
5
  -->
6
6
  <!-- Title: htm_development Pages: 1 -->
7
- <svg width="2221pt" height="1463pt"
8
- viewBox="0.00 0.00 2220.69 1462.80" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
9
- <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 1458.8)">
7
+ <svg width="2221pt" height="1494pt"
8
+ viewBox="0.00 0.00 2220.69 1493.60" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
9
+ <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 1489.6)">
10
10
  <title>htm_development</title>
11
- <polygon fill="white" stroke="none" points="-4,4 -4,-1458.8 2216.69,-1458.8 2216.69,4 -4,4"/>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-1489.6 2216.69,-1489.6 2216.69,4 -4,4"/>
12
12
  <!-- public.file_sources -->
13
13
  <g id="node1" class="node">
14
14
  <title>public.file_sources</title>
@@ -55,16 +55,20 @@
55
55
  <!-- public.node_tags -->
56
56
  <g id="node2" class="node">
57
57
  <title>public.node_tags</title>
58
- <polygon fill="#efefef" stroke="none" points="493.91,-1288.6 493.91,-1334.6 963.12,-1334.6 963.12,-1288.6 493.91,-1288.6"/>
59
- <polygon fill="none" stroke="black" points="493.91,-1288.6 493.91,-1334.6 963.12,-1334.6 963.12,-1288.6 493.91,-1288.6"/>
60
- <text text-anchor="start" x="605.03" y="-1312.4" font-family="Arial Bold" font-size="18.00">public.node_tags</text>
61
- <text text-anchor="start" x="727.51" y="-1312.4" font-family="Arial" font-size="14.00">    </text>
62
- <text text-anchor="start" x="758.62" y="-1312.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
63
- <text text-anchor="start" x="567.43" y="-1298" font-family="Arial" font-size="14.00" fill="#333333">Join table connecting nodes to tags (many&#45;to&#45;many)</text>
58
+ <polygon fill="#efefef" stroke="none" points="493.91,-1319.4 493.91,-1365.4 963.12,-1365.4 963.12,-1319.4 493.91,-1319.4"/>
59
+ <polygon fill="none" stroke="black" points="493.91,-1319.4 493.91,-1365.4 963.12,-1365.4 963.12,-1319.4 493.91,-1319.4"/>
60
+ <text text-anchor="start" x="605.03" y="-1343.2" font-family="Arial Bold" font-size="18.00">public.node_tags</text>
61
+ <text text-anchor="start" x="727.51" y="-1343.2" font-family="Arial" font-size="14.00">    </text>
62
+ <text text-anchor="start" x="758.62" y="-1343.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
63
+ <text text-anchor="start" x="567.43" y="-1328.8" font-family="Arial" font-size="14.00" fill="#333333">Join table connecting nodes to tags (many&#45;to&#45;many)</text>
64
+ <polygon fill="none" stroke="black" points="493.91,-1288.6 493.91,-1319.4 963.12,-1319.4 963.12,-1288.6 493.91,-1288.6"/>
65
+ <text text-anchor="start" x="500.91" y="-1300.8" font-family="Arial" font-size="14.00">created_at </text>
66
+ <text text-anchor="start" x="570.95" y="-1300.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
67
+ <text text-anchor="start" x="736.68" y="-1300.8" font-family="Arial" font-size="14.00"> When this association was created</text>
64
68
  <polygon fill="none" stroke="black" points="493.91,-1257.8 493.91,-1288.6 963.12,-1288.6 963.12,-1257.8 493.91,-1257.8"/>
65
- <text text-anchor="start" x="500.91" y="-1270" font-family="Arial" font-size="14.00">created_at </text>
66
- <text text-anchor="start" x="570.95" y="-1270" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
67
- <text text-anchor="start" x="736.68" y="-1270" font-family="Arial" font-size="14.00"> When this association was created</text>
69
+ <text text-anchor="start" x="500.91" y="-1270" font-family="Arial" font-size="14.00">deleted_at </text>
70
+ <text text-anchor="start" x="570.19" y="-1270" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
71
+ <text text-anchor="start" x="735.91" y="-1270" font-family="Arial" font-size="14.00"> Soft delete timestamp</text>
68
72
  <polygon fill="none" stroke="black" points="493.91,-1227 493.91,-1257.8 963.12,-1257.8 963.12,-1227 493.91,-1227"/>
69
73
  <text text-anchor="start" x="500.91" y="-1239.2" font-family="Arial" font-size="14.00">id </text>
70
74
  <text text-anchor="start" x="515.69" y="-1239.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
@@ -152,29 +156,33 @@
152
156
  <!-- public.tags -->
153
157
  <g id="node7" class="node">
154
158
  <title>public.tags</title>
155
- <polygon fill="#efefef" stroke="none" points="43.2,-750.6 43.2,-796.6 647.83,-796.6 647.83,-750.6 43.2,-750.6"/>
156
- <polygon fill="none" stroke="black" points="43.2,-750.6 43.2,-796.6 647.83,-796.6 647.83,-750.6 43.2,-750.6"/>
157
- <text text-anchor="start" x="244.02" y="-774.4" font-family="Arial Bold" font-size="18.00">public.tags</text>
158
- <text text-anchor="start" x="322.51" y="-774.4" font-family="Arial" font-size="14.00">    </text>
159
- <text text-anchor="start" x="353.63" y="-774.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
160
- <text text-anchor="start" x="233.06" y="-760" font-family="Arial" font-size="14.00" fill="#333333">Unique tag names for categorization</text>
161
- <polygon fill="none" stroke="black" points="43.2,-719.8 43.2,-750.6 647.83,-750.6 647.83,-719.8 43.2,-719.8"/>
162
- <text text-anchor="start" x="50.2" y="-732" font-family="Arial" font-size="14.00">created_at </text>
163
- <text text-anchor="start" x="120.25" y="-732" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
164
- <text text-anchor="start" x="285.97" y="-732" font-family="Arial" font-size="14.00"> When this tag was created</text>
165
- <polygon fill="none" stroke="black" points="43.2,-689 43.2,-719.8 647.83,-719.8 647.83,-689 43.2,-689"/>
166
- <text text-anchor="start" x="50.2" y="-701.2" font-family="Arial" font-size="14.00">id </text>
167
- <text text-anchor="start" x="64.99" y="-701.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
168
- <polygon fill="none" stroke="black" points="43.2,-658.2 43.2,-689 647.83,-689 647.83,-658.2 43.2,-658.2"/>
169
- <text text-anchor="start" x="50.2" y="-670.4" font-family="Arial" font-size="14.00">name </text>
170
- <text text-anchor="start" x="89.11" y="-670.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
171
- <text text-anchor="start" x="119.45" y="-670.4" font-family="Arial" font-size="14.00"> Hierarchical tag in format: root:level1:level2 (e.g., database:postgresql:timescaledb)</text>
159
+ <polygon fill="#efefef" stroke="none" points="43.2,-766 43.2,-812 647.83,-812 647.83,-766 43.2,-766"/>
160
+ <polygon fill="none" stroke="black" points="43.2,-766 43.2,-812 647.83,-812 647.83,-766 43.2,-766"/>
161
+ <text text-anchor="start" x="244.02" y="-789.8" font-family="Arial Bold" font-size="18.00">public.tags</text>
162
+ <text text-anchor="start" x="322.51" y="-789.8" font-family="Arial" font-size="14.00">    </text>
163
+ <text text-anchor="start" x="353.63" y="-789.8" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
164
+ <text text-anchor="start" x="233.06" y="-775.4" font-family="Arial" font-size="14.00" fill="#333333">Unique tag names for categorization</text>
165
+ <polygon fill="none" stroke="black" points="43.2,-735.2 43.2,-766 647.83,-766 647.83,-735.2 43.2,-735.2"/>
166
+ <text text-anchor="start" x="50.2" y="-747.4" font-family="Arial" font-size="14.00">created_at </text>
167
+ <text text-anchor="start" x="120.25" y="-747.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
168
+ <text text-anchor="start" x="285.97" y="-747.4" font-family="Arial" font-size="14.00"> When this tag was created</text>
169
+ <polygon fill="none" stroke="black" points="43.2,-704.4 43.2,-735.2 647.83,-735.2 647.83,-704.4 43.2,-704.4"/>
170
+ <text text-anchor="start" x="50.2" y="-716.6" font-family="Arial" font-size="14.00">deleted_at </text>
171
+ <text text-anchor="start" x="119.48" y="-716.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
172
+ <text text-anchor="start" x="285.21" y="-716.6" font-family="Arial" font-size="14.00"> Soft delete timestamp</text>
173
+ <polygon fill="none" stroke="black" points="43.2,-673.6 43.2,-704.4 647.83,-704.4 647.83,-673.6 43.2,-673.6"/>
174
+ <text text-anchor="start" x="50.2" y="-685.8" font-family="Arial" font-size="14.00">id </text>
175
+ <text text-anchor="start" x="64.99" y="-685.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
176
+ <polygon fill="none" stroke="black" points="43.2,-642.8 43.2,-673.6 647.83,-673.6 647.83,-642.8 43.2,-642.8"/>
177
+ <text text-anchor="start" x="50.2" y="-655" font-family="Arial" font-size="14.00">name </text>
178
+ <text text-anchor="start" x="89.11" y="-655" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
179
+ <text text-anchor="start" x="119.45" y="-655" font-family="Arial" font-size="14.00"> Hierarchical tag in format: root:level1:level2 (e.g., database:postgresql:timescaledb)</text>
172
180
  </g>
173
181
  <!-- public.node_tags&#45;&gt;public.tags -->
174
182
  <g id="edge2" class="edge">
175
183
  <title>public.node_tags:tag_id&#45;&gt;public.tags:id</title>
176
- <path fill="none" stroke="black" d="M482.48,-1180.41C289.87,-1165.11 867.91,-704.4 648.83,-704.4"/>
177
- <polygon fill="black" stroke="black" points="482.58,-1180.41 492.4,-1185.28 487.91,-1180.61 492.24,-1180.78 492.24,-1180.78 492.24,-1180.78 487.91,-1180.61 492.74,-1176.29 482.58,-1180.41"/>
184
+ <path fill="none" stroke="black" d="M482.99,-1177.8C473.66,-1169.03 488.21,-1142.79 493.91,-1122.2 530.44,-990.19 612.02,-987.41 647.83,-855.2 667.13,-783.9 722.69,-689 648.83,-689"/>
185
+ <polygon fill="black" stroke="black" points="483.02,-1177.81 491.28,-1185.01 488.12,-1179.35 492.27,-1180.61 492.27,-1180.61 492.27,-1180.61 488.12,-1179.35 493.89,-1176.4 483.02,-1177.81"/>
178
186
  <text text-anchor="start" x="163.05" y="-1190.8" font-family="Arial" font-size="10.00">FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE</text>
179
187
  </g>
180
188
  <!-- public.nodes&#45;&gt;public.file_sources -->
@@ -187,15 +195,19 @@
187
195
  <!-- public.robot_nodes -->
188
196
  <g id="node4" class="node">
189
197
  <title>public.robot_nodes</title>
190
- <polygon fill="#efefef" stroke="none" points="1107.77,-1365.6 1107.77,-1411.6 1737.26,-1411.6 1737.26,-1365.6 1107.77,-1365.6"/>
191
- <polygon fill="none" stroke="black" points="1107.77,-1365.6 1107.77,-1411.6 1737.26,-1411.6 1737.26,-1365.6 1107.77,-1365.6"/>
192
- <text text-anchor="start" x="1291.03" y="-1389.4" font-family="Arial Bold" font-size="18.00">public.robot_nodes</text>
193
- <text text-anchor="start" x="1429.51" y="-1389.4" font-family="Arial" font-size="14.00">    </text>
194
- <text text-anchor="start" x="1460.63" y="-1389.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
195
- <text text-anchor="start" x="1255.2" y="-1375" font-family="Arial" font-size="14.00" fill="#333333">Join table connecting robots to nodes (many&#45;to&#45;many)</text>
198
+ <polygon fill="#efefef" stroke="none" points="1107.77,-1396.4 1107.77,-1442.4 1737.26,-1442.4 1737.26,-1396.4 1107.77,-1396.4"/>
199
+ <polygon fill="none" stroke="black" points="1107.77,-1396.4 1107.77,-1442.4 1737.26,-1442.4 1737.26,-1396.4 1107.77,-1396.4"/>
200
+ <text text-anchor="start" x="1291.03" y="-1420.2" font-family="Arial Bold" font-size="18.00">public.robot_nodes</text>
201
+ <text text-anchor="start" x="1429.51" y="-1420.2" font-family="Arial" font-size="14.00">    </text>
202
+ <text text-anchor="start" x="1460.63" y="-1420.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
203
+ <text text-anchor="start" x="1255.2" y="-1405.8" font-family="Arial" font-size="14.00" fill="#333333">Join table connecting robots to nodes (many&#45;to&#45;many)</text>
204
+ <polygon fill="none" stroke="black" points="1107.77,-1365.6 1107.77,-1396.4 1737.26,-1396.4 1737.26,-1365.6 1107.77,-1365.6"/>
205
+ <text text-anchor="start" x="1114.77" y="-1377.8" font-family="Arial" font-size="14.00">created_at </text>
206
+ <text text-anchor="start" x="1184.82" y="-1377.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
196
207
  <polygon fill="none" stroke="black" points="1107.77,-1334.8 1107.77,-1365.6 1737.26,-1365.6 1737.26,-1334.8 1107.77,-1334.8"/>
197
- <text text-anchor="start" x="1114.77" y="-1347" font-family="Arial" font-size="14.00">created_at </text>
198
- <text text-anchor="start" x="1184.82" y="-1347" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
208
+ <text text-anchor="start" x="1114.77" y="-1347" font-family="Arial" font-size="14.00">deleted_at </text>
209
+ <text text-anchor="start" x="1184.05" y="-1347" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
210
+ <text text-anchor="start" x="1349.77" y="-1347" font-family="Arial" font-size="14.00"> Soft delete timestamp</text>
199
211
  <polygon fill="none" stroke="black" points="1107.77,-1304 1107.77,-1334.8 1737.26,-1334.8 1737.26,-1304 1107.77,-1304"/>
200
212
  <text text-anchor="start" x="1114.77" y="-1316.2" font-family="Arial" font-size="14.00">first_remembered_at </text>
201
213
  <text text-anchor="start" x="1247.82" y="-1316.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
@@ -269,14 +281,14 @@
269
281
  <!-- public.schema_migrations -->
270
282
  <g id="node6" class="node">
271
283
  <title>public.schema_migrations</title>
272
- <polygon fill="#efefef" stroke="none" points="1841.54,-1247.6 1841.54,-1283.2 2169.49,-1283.2 2169.49,-1247.6 1841.54,-1247.6"/>
273
- <polygon fill="none" stroke="black" points="1841.54,-1247.6 1841.54,-1283.2 2169.49,-1283.2 2169.49,-1247.6 1841.54,-1247.6"/>
274
- <text text-anchor="start" x="1848.54" y="-1261" font-family="Arial Bold" font-size="18.00">public.schema_migrations</text>
275
- <text text-anchor="start" x="2038" y="-1261" font-family="Arial" font-size="14.00">    </text>
276
- <text text-anchor="start" x="2069.11" y="-1261" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
277
- <polygon fill="none" stroke="black" points="1841.54,-1216.8 1841.54,-1247.6 2169.49,-1247.6 2169.49,-1216.8 1841.54,-1216.8"/>
278
- <text text-anchor="start" x="1848.54" y="-1229" font-family="Arial" font-size="14.00">version </text>
279
- <text text-anchor="start" x="1897.56" y="-1229" font-family="Arial" font-size="14.00" fill="#666666">[varchar]</text>
284
+ <polygon fill="#efefef" stroke="none" points="1841.54,-1263 1841.54,-1298.6 2169.49,-1298.6 2169.49,-1263 1841.54,-1263"/>
285
+ <polygon fill="none" stroke="black" points="1841.54,-1263 1841.54,-1298.6 2169.49,-1298.6 2169.49,-1263 1841.54,-1263"/>
286
+ <text text-anchor="start" x="1848.54" y="-1276.4" font-family="Arial Bold" font-size="18.00">public.schema_migrations</text>
287
+ <text text-anchor="start" x="2038" y="-1276.4" font-family="Arial" font-size="14.00">    </text>
288
+ <text text-anchor="start" x="2069.11" y="-1276.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
289
+ <polygon fill="none" stroke="black" points="1841.54,-1232.2 1841.54,-1263 2169.49,-1263 2169.49,-1232.2 1841.54,-1232.2"/>
290
+ <text text-anchor="start" x="1848.54" y="-1244.4" font-family="Arial" font-size="14.00">version </text>
291
+ <text text-anchor="start" x="1897.56" y="-1244.4" font-family="Arial" font-size="14.00" fill="#666666">[varchar]</text>
280
292
  </g>
281
293
  </g>
282
294
  </svg>
data/docs/development/index.md CHANGED
@@ -59,6 +59,19 @@ Everything you need to know about contributing code, documentation, or bug repor
59
59
  - Code review expectations
60
60
  - Documentation requirements
61
61
 
62
+ ### [Rake Tasks Reference](rake-tasks.md)
63
+ Complete reference for all 44 HTM rake tasks covering database management, documentation, file loading, background jobs, and tag management.
64
+
65
+ **Topics covered:**
66
+
67
+ - Database tasks (`htm:db:*`) - setup, migrations, maintenance
68
+ - Documentation tasks (`htm:doc:*`) - YARD, MkDocs, diagrams
69
+ - File loading tasks (`htm:files:*`) - load, sync, unload files
70
+ - Job tasks (`htm:jobs:*`) - process embeddings, tags, propositions
71
+ - Tag tasks (`htm:tags:*`) - visualization and management
72
+ - Common workflows and examples
73
+ - Troubleshooting guide
74
+
62
75
  ### [Database Schema](schema.md)
63
76
  Deep dive into HTM's database architecture, tables, indexes, and TimescaleDB optimization strategies.
64
77