htm 0.0.1 → 0.0.2

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 (109) hide show
  1. checksums.yaml +4 -4
  2. data/.envrc +1 -0
  3. data/.tbls.yml +30 -0
  4. data/CHANGELOG.md +30 -0
  5. data/SETUP.md +132 -101
  6. data/db/migrate/20250125000001_add_content_hash_to_nodes.rb +14 -0
  7. data/db/migrate/20250125000002_create_robot_nodes.rb +35 -0
  8. data/db/migrate/20250125000003_remove_source_and_robot_id_from_nodes.rb +28 -0
  9. data/db/migrate/20250126000001_create_working_memories.rb +19 -0
  10. data/db/migrate/20250126000002_remove_unused_columns.rb +12 -0
  11. data/db/schema.sql +226 -43
  12. data/docs/api/database.md +20 -232
  13. data/docs/api/embedding-service.md +1 -7
  14. data/docs/api/htm.md +195 -449
  15. data/docs/api/index.md +1 -7
  16. data/docs/api/long-term-memory.md +342 -590
  17. data/docs/architecture/adrs/001-postgresql-timescaledb.md +1 -1
  18. data/docs/architecture/adrs/003-ollama-embeddings.md +1 -1
  19. data/docs/architecture/adrs/010-redis-working-memory-rejected.md +2 -27
  20. data/docs/architecture/adrs/index.md +2 -13
  21. data/docs/architecture/hive-mind.md +165 -166
  22. data/docs/architecture/index.md +2 -2
  23. data/docs/architecture/overview.md +5 -171
  24. data/docs/architecture/two-tier-memory.md +1 -35
  25. data/docs/assets/images/adr-010-current-architecture.svg +37 -0
  26. data/docs/assets/images/adr-010-proposed-architecture.svg +48 -0
  27. data/docs/assets/images/adr-dependency-tree.svg +93 -0
  28. data/docs/assets/images/class-hierarchy.svg +55 -0
  29. data/docs/assets/images/exception-hierarchy.svg +45 -0
  30. data/docs/assets/images/htm-architecture-overview.svg +83 -0
  31. data/docs/assets/images/htm-complete-memory-flow.svg +160 -0
  32. data/docs/assets/images/htm-context-assembly-flow.svg +148 -0
  33. data/docs/assets/images/htm-eviction-process.svg +141 -0
  34. data/docs/assets/images/htm-memory-addition-flow.svg +138 -0
  35. data/docs/assets/images/htm-memory-recall-flow.svg +152 -0
  36. data/docs/assets/images/htm-node-states.svg +123 -0
  37. data/docs/assets/images/project-structure.svg +78 -0
  38. data/docs/assets/images/test-directory-structure.svg +38 -0
  39. data/{dbdoc → docs/database}/README.md +5 -3
  40. data/{dbdoc → docs/database}/public.node_tags.md +4 -5
  41. data/docs/database/public.node_tags.svg +106 -0
  42. data/{dbdoc → docs/database}/public.nodes.md +3 -8
  43. data/docs/database/public.nodes.svg +152 -0
  44. data/docs/database/public.robot_nodes.md +44 -0
  45. data/docs/database/public.robot_nodes.svg +121 -0
  46. data/{dbdoc → docs/database}/public.robots.md +1 -2
  47. data/docs/database/public.robots.svg +106 -0
  48. data/docs/database/public.working_memories.md +40 -0
  49. data/docs/database/public.working_memories.svg +112 -0
  50. data/{dbdoc → docs/database}/schema.json +342 -110
  51. data/docs/database/schema.svg +223 -0
  52. data/docs/development/index.md +1 -29
  53. data/docs/development/schema.md +84 -324
  54. data/docs/development/testing.md +1 -9
  55. data/docs/getting-started/index.md +47 -0
  56. data/docs/{installation.md → getting-started/installation.md} +2 -2
  57. data/docs/{quick-start.md → getting-started/quick-start.md} +5 -5
  58. data/docs/guides/adding-memories.md +221 -655
  59. data/docs/guides/search-strategies.md +85 -51
  60. data/docs/images/htm-er-diagram.svg +156 -0
  61. data/docs/index.md +16 -31
  62. data/docs/multi_framework_support.md +4 -4
  63. data/examples/basic_usage.rb +18 -16
  64. data/examples/cli_app/htm_cli.rb +86 -8
  65. data/examples/custom_llm_configuration.rb +1 -2
  66. data/examples/example_app/app.rb +11 -14
  67. data/examples/sinatra_app/Gemfile +1 -0
  68. data/examples/sinatra_app/Gemfile.lock +166 -0
  69. data/examples/sinatra_app/app.rb +219 -24
  70. data/lib/htm/active_record_config.rb +10 -3
  71. data/lib/htm/configuration.rb +265 -78
  72. data/lib/htm/{sinatra.rb → integrations/sinatra.rb} +87 -12
  73. data/lib/htm/job_adapter.rb +10 -3
  74. data/lib/htm/long_term_memory.rb +220 -57
  75. data/lib/htm/models/node.rb +36 -7
  76. data/lib/htm/models/robot.rb +30 -4
  77. data/lib/htm/models/robot_node.rb +50 -0
  78. data/lib/htm/models/tag.rb +52 -0
  79. data/lib/htm/models/working_memory_entry.rb +88 -0
  80. data/lib/htm/tasks.rb +4 -0
  81. data/lib/htm/version.rb +1 -1
  82. data/lib/htm.rb +34 -13
  83. data/lib/tasks/htm.rake +32 -1
  84. data/lib/tasks/jobs.rake +7 -3
  85. data/lib/tasks/tags.rake +34 -0
  86. data/mkdocs.yml +56 -9
  87. metadata +61 -31
  88. data/dbdoc/public.node_tags.svg +0 -112
  89. data/dbdoc/public.nodes.svg +0 -118
  90. data/dbdoc/public.robots.svg +0 -90
  91. data/dbdoc/schema.svg +0 -154
  92. /data/{dbdoc → docs/database}/public.node_stats.md +0 -0
  93. /data/{dbdoc → docs/database}/public.node_stats.svg +0 -0
  94. /data/{dbdoc → docs/database}/public.nodes_tags.md +0 -0
  95. /data/{dbdoc → docs/database}/public.nodes_tags.svg +0 -0
  96. /data/{dbdoc → docs/database}/public.ontology_structure.md +0 -0
  97. /data/{dbdoc → docs/database}/public.ontology_structure.svg +0 -0
  98. /data/{dbdoc → docs/database}/public.operations_log.md +0 -0
  99. /data/{dbdoc → docs/database}/public.operations_log.svg +0 -0
  100. /data/{dbdoc → docs/database}/public.relationships.md +0 -0
  101. /data/{dbdoc → docs/database}/public.relationships.svg +0 -0
  102. /data/{dbdoc → docs/database}/public.robot_activity.md +0 -0
  103. /data/{dbdoc → docs/database}/public.robot_activity.svg +0 -0
  104. /data/{dbdoc → docs/database}/public.schema_migrations.md +0 -0
  105. /data/{dbdoc → docs/database}/public.schema_migrations.svg +0 -0
  106. /data/{dbdoc → docs/database}/public.tags.md +0 -0
  107. /data/{dbdoc → docs/database}/public.tags.svg +0 -0
  108. /data/{dbdoc → docs/database}/public.topic_relationships.md +0 -0
  109. /data/{dbdoc → docs/database}/public.topic_relationships.svg +0 -0
data/docs/database/schema.svg ADDED
@@ -0,0 +1,223 @@
1
+ <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2
+ <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
3
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
4
+ <!-- Generated by graphviz version 12.1.2 (20240928.0832)
5
+ -->
6
+ <!-- Title: htm_development Pages: 1 -->
7
+ <svg width="1637pt" height="842pt"
8
+ viewBox="0.00 0.00 1637.35 842.40" 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 838.4)">
10
+ <title>htm_development</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-838.4 1633.35,-838.4 1633.35,4 -4,4"/>
12
+ <!-- public.robot_nodes -->
13
+ <g id="node1" class="node">
14
+ <title>public.robot_nodes</title>
15
+ <polygon fill="#efefef" stroke="none" points="475.79,-755.6 475.79,-791.2 788.57,-791.2 788.57,-755.6 475.79,-755.6"/>
16
+ <polygon fill="none" stroke="black" points="475.79,-755.6 475.79,-791.2 788.57,-791.2 788.57,-755.6 475.79,-755.6"/>
17
+ <text text-anchor="start" x="500.69" y="-769" font-family="Arial Bold" font-size="18.00">public.robot_nodes</text>
18
+ <text text-anchor="start" x="639.17" y="-769" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="670.29" y="-769" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="475.79,-724.8 475.79,-755.6 788.57,-755.6 788.57,-724.8 475.79,-724.8"/>
21
+ <text text-anchor="start" x="482.79" y="-737" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="497.57" y="-737" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="475.79,-694 475.79,-724.8 788.57,-724.8 788.57,-694 475.79,-694"/>
24
+ <text text-anchor="start" x="482.79" y="-706.2" font-family="Arial" font-size="14.00">robot_id </text>
25
+ <text text-anchor="start" x="537.27" y="-706.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
26
+ <polygon fill="none" stroke="black" points="475.79,-663.2 475.79,-694 788.57,-694 788.57,-663.2 475.79,-663.2"/>
27
+ <text text-anchor="start" x="482.79" y="-675.4" font-family="Arial" font-size="14.00">node_id </text>
28
+ <text text-anchor="start" x="536.51" y="-675.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
29
+ <polygon fill="none" stroke="black" points="475.79,-632.4 475.79,-663.2 788.57,-663.2 788.57,-632.4 475.79,-632.4"/>
30
+ <text text-anchor="start" x="482.79" y="-644.6" font-family="Arial" font-size="14.00">first_remembered_at </text>
31
+ <text text-anchor="start" x="615.84" y="-644.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
32
+ <polygon fill="none" stroke="black" points="475.79,-601.6 475.79,-632.4 788.57,-632.4 788.57,-601.6 475.79,-601.6"/>
33
+ <text text-anchor="start" x="482.79" y="-613.8" font-family="Arial" font-size="14.00">last_remembered_at </text>
34
+ <text text-anchor="start" x="615.08" y="-613.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
35
+ <polygon fill="none" stroke="black" points="475.79,-570.8 475.79,-601.6 788.57,-601.6 788.57,-570.8 475.79,-570.8"/>
36
+ <text text-anchor="start" x="482.79" y="-583" font-family="Arial" font-size="14.00">remember_count </text>
37
+ <text text-anchor="start" x="592.51" y="-583" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
38
+ <polygon fill="none" stroke="black" points="475.79,-540 475.79,-570.8 788.57,-570.8 788.57,-540 475.79,-540"/>
39
+ <text text-anchor="start" x="482.79" y="-552.2" font-family="Arial" font-size="14.00">created_at </text>
40
+ <text text-anchor="start" x="552.84" y="-552.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
41
+ <polygon fill="none" stroke="black" points="475.79,-509.2 475.79,-540 788.57,-540 788.57,-509.2 475.79,-509.2"/>
42
+ <text text-anchor="start" x="482.79" y="-521.4" font-family="Arial" font-size="14.00">updated_at </text>
43
+ <text text-anchor="start" x="556.75" y="-521.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
44
+ </g>
45
+ <!-- public.robots -->
46
+ <g id="node3" class="node">
47
+ <title>public.robots</title>
48
+ <polygon fill="#efefef" stroke="none" points="112.29,-258.8 112.29,-294.4 362.06,-294.4 362.06,-258.8 112.29,-258.8"/>
49
+ <polygon fill="none" stroke="black" points="112.29,-258.8 112.29,-294.4 362.06,-294.4 362.06,-258.8 112.29,-258.8"/>
50
+ <text text-anchor="start" x="127.69" y="-272.2" font-family="Arial Bold" font-size="18.00">public.robots</text>
51
+ <text text-anchor="start" x="222.18" y="-272.2" font-family="Arial" font-size="14.00">    </text>
52
+ <text text-anchor="start" x="253.3" y="-272.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
53
+ <polygon fill="none" stroke="black" points="112.29,-228 112.29,-258.8 362.06,-258.8 362.06,-228 112.29,-228"/>
54
+ <text text-anchor="start" x="119.29" y="-240.2" font-family="Arial" font-size="14.00">id </text>
55
+ <text text-anchor="start" x="134.08" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
56
+ <polygon fill="none" stroke="black" points="112.29,-197.2 112.29,-228 362.06,-228 362.06,-197.2 112.29,-197.2"/>
57
+ <text text-anchor="start" x="119.29" y="-209.4" font-family="Arial" font-size="14.00">name </text>
58
+ <text text-anchor="start" x="158.2" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
59
+ <polygon fill="none" stroke="black" points="112.29,-166.4 112.29,-197.2 362.06,-197.2 362.06,-166.4 112.29,-166.4"/>
60
+ <text text-anchor="start" x="119.29" y="-178.6" font-family="Arial" font-size="14.00">created_at </text>
61
+ <text text-anchor="start" x="189.34" y="-178.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
62
+ <polygon fill="none" stroke="black" points="112.29,-135.6 112.29,-166.4 362.06,-166.4 362.06,-135.6 112.29,-135.6"/>
63
+ <text text-anchor="start" x="119.29" y="-147.8" font-family="Arial" font-size="14.00">last_active </text>
64
+ <text text-anchor="start" x="189.33" y="-147.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
65
+ </g>
66
+ <!-- public.robot_nodes&#45;&gt;public.robots -->
67
+ <g id="edge1" class="edge">
68
+ <title>public.robot_nodes:robot_id&#45;&gt;public.robots:id</title>
69
+ <path fill="none" stroke="black" d="M464.7,-706.99C421.57,-684.81 435.26,-516.18 423.18,-466 399.18,-366.37 465.54,-243.4 363.06,-243.4"/>
70
+ <polygon fill="black" stroke="black" points="464.74,-707 473.42,-713.7 469.93,-708.24 474.14,-709.24 474.14,-709.24 474.14,-709.24 469.93,-708.24 475.51,-704.95 464.74,-707"/>
71
+ <text text-anchor="start" x="481.79" y="-719.4" font-family="Arial" font-size="10.00">FOREIGN KEY (robot_id) REFERENCES robots(id) ON DELETE CASCADE</text>
72
+ </g>
73
+ <!-- public.nodes -->
74
+ <g id="node4" class="node">
75
+ <title>public.nodes</title>
76
+ <polygon fill="#efefef" stroke="none" points="496.01,-351.2 496.01,-386.8 768.34,-386.8 768.34,-351.2 496.01,-351.2"/>
77
+ <polygon fill="none" stroke="black" points="496.01,-351.2 496.01,-386.8 768.34,-386.8 768.34,-351.2 496.01,-351.2"/>
78
+ <text text-anchor="start" x="524.19" y="-364.6" font-family="Arial Bold" font-size="18.00">public.nodes</text>
79
+ <text text-anchor="start" x="615.68" y="-364.6" font-family="Arial" font-size="14.00">    </text>
80
+ <text text-anchor="start" x="646.79" y="-364.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
81
+ <polygon fill="none" stroke="black" points="496.01,-320.4 496.01,-351.2 768.34,-351.2 768.34,-320.4 496.01,-320.4"/>
82
+ <text text-anchor="start" x="503.01" y="-332.6" font-family="Arial" font-size="14.00">id </text>
83
+ <text text-anchor="start" x="517.8" y="-332.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
84
+ <polygon fill="none" stroke="black" points="496.01,-289.6 496.01,-320.4 768.34,-320.4 768.34,-289.6 496.01,-289.6"/>
85
+ <text text-anchor="start" x="503.01" y="-301.8" font-family="Arial" font-size="14.00">content </text>
86
+ <text text-anchor="start" x="552.83" y="-301.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
87
+ <polygon fill="none" stroke="black" points="496.01,-258.8 496.01,-289.6 768.34,-289.6 768.34,-258.8 496.01,-258.8"/>
88
+ <text text-anchor="start" x="503.01" y="-271" font-family="Arial" font-size="14.00">access_count </text>
89
+ <text text-anchor="start" x="592.51" y="-271" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
90
+ <polygon fill="none" stroke="black" points="496.01,-228 496.01,-258.8 768.34,-258.8 768.34,-228 496.01,-228"/>
91
+ <text text-anchor="start" x="503.01" y="-240.2" font-family="Arial" font-size="14.00">created_at </text>
92
+ <text text-anchor="start" x="573.06" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
93
+ <polygon fill="none" stroke="black" points="496.01,-197.2 496.01,-228 768.34,-228 768.34,-197.2 496.01,-197.2"/>
94
+ <text text-anchor="start" x="503.01" y="-209.4" font-family="Arial" font-size="14.00">updated_at </text>
95
+ <text text-anchor="start" x="576.97" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
96
+ <polygon fill="none" stroke="black" points="496.01,-166.4 496.01,-197.2 768.34,-197.2 768.34,-166.4 496.01,-166.4"/>
97
+ <text text-anchor="start" x="503.01" y="-178.6" font-family="Arial" font-size="14.00">last_accessed </text>
98
+ <text text-anchor="start" x="595.62" y="-178.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
99
+ <polygon fill="none" stroke="black" points="496.01,-135.6 496.01,-166.4 768.34,-166.4 768.34,-135.6 496.01,-135.6"/>
100
+ <text text-anchor="start" x="503.01" y="-147.8" font-family="Arial" font-size="14.00">token_count </text>
101
+ <text text-anchor="start" x="583.18" y="-147.8" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
102
+ <polygon fill="none" stroke="black" points="496.01,-104.8 496.01,-135.6 768.34,-135.6 768.34,-104.8 496.01,-104.8"/>
103
+ <text text-anchor="start" x="503.01" y="-117" font-family="Arial" font-size="14.00">embedding </text>
104
+ <text text-anchor="start" x="576.18" y="-117" font-family="Arial" font-size="14.00" fill="#666666">[vector(2000)]</text>
105
+ <polygon fill="none" stroke="black" points="496.01,-74 496.01,-104.8 768.34,-104.8 768.34,-74 496.01,-74"/>
106
+ <text text-anchor="start" x="503.01" y="-86.2" font-family="Arial" font-size="14.00">embedding_dimension </text>
107
+ <text text-anchor="start" x="647.78" y="-86.2" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
108
+ <polygon fill="none" stroke="black" points="496.01,-43.2 496.01,-74 768.34,-74 768.34,-43.2 496.01,-43.2"/>
109
+ <text text-anchor="start" x="503.01" y="-55.4" font-family="Arial" font-size="14.00">content_hash </text>
110
+ <text text-anchor="start" x="590.97" y="-55.4" font-family="Arial" font-size="14.00" fill="#666666">[varchar(64)]</text>
111
+ </g>
112
+ <!-- public.robot_nodes&#45;&gt;public.nodes -->
113
+ <g id="edge2" class="edge">
114
+ <title>public.robot_nodes:node_id&#45;&gt;public.nodes:id</title>
115
+ <path fill="none" stroke="black" d="M799.67,-676.41C863.86,-647.22 842.08,-335.8 769.34,-335.8"/>
116
+ <polygon fill="black" stroke="black" points="799.67,-676.41 788.94,-674.13 794.45,-677.54 790.22,-678.46 790.22,-678.46 790.22,-678.46 794.45,-677.54 790.85,-682.93 799.67,-676.41"/>
117
+ <text text-anchor="start" x="796.57" y="-688.6" font-family="Arial" font-size="10.00">FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE</text>
118
+ </g>
119
+ <!-- public.schema_migrations -->
120
+ <g id="node2" class="node">
121
+ <title>public.schema_migrations</title>
122
+ <polygon fill="#efefef" stroke="none" points="1258.2,-647.8 1258.2,-683.4 1586.15,-683.4 1586.15,-647.8 1258.2,-647.8"/>
123
+ <polygon fill="none" stroke="black" points="1258.2,-647.8 1258.2,-683.4 1586.15,-683.4 1586.15,-647.8 1258.2,-647.8"/>
124
+ <text text-anchor="start" x="1265.2" y="-661.2" font-family="Arial Bold" font-size="18.00">public.schema_migrations</text>
125
+ <text text-anchor="start" x="1454.66" y="-661.2" font-family="Arial" font-size="14.00">    </text>
126
+ <text text-anchor="start" x="1485.78" y="-661.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
127
+ <polygon fill="none" stroke="black" points="1258.2,-617 1258.2,-647.8 1586.15,-647.8 1586.15,-617 1258.2,-617"/>
128
+ <text text-anchor="start" x="1265.2" y="-629.2" font-family="Arial" font-size="14.00">version </text>
129
+ <text text-anchor="start" x="1314.22" y="-629.2" font-family="Arial" font-size="14.00" fill="#666666">[varchar]</text>
130
+ </g>
131
+ <!-- public.tags -->
132
+ <g id="node5" class="node">
133
+ <title>public.tags</title>
134
+ <polygon fill="#efefef" stroke="none" points="898.29,-243.4 898.29,-279 1148.06,-279 1148.06,-243.4 898.29,-243.4"/>
135
+ <polygon fill="none" stroke="black" points="898.29,-243.4 898.29,-279 1148.06,-279 1148.06,-243.4 898.29,-243.4"/>
136
+ <text text-anchor="start" x="921.69" y="-256.8" font-family="Arial Bold" font-size="18.00">public.tags</text>
137
+ <text text-anchor="start" x="1000.18" y="-256.8" font-family="Arial" font-size="14.00">    </text>
138
+ <text text-anchor="start" x="1031.29" y="-256.8" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
139
+ <polygon fill="none" stroke="black" points="898.29,-212.6 898.29,-243.4 1148.06,-243.4 1148.06,-212.6 898.29,-212.6"/>
140
+ <text text-anchor="start" x="905.29" y="-224.8" font-family="Arial" font-size="14.00">id </text>
141
+ <text text-anchor="start" x="920.08" y="-224.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
142
+ <polygon fill="none" stroke="black" points="898.29,-181.8 898.29,-212.6 1148.06,-212.6 1148.06,-181.8 898.29,-181.8"/>
143
+ <text text-anchor="start" x="905.29" y="-194" font-family="Arial" font-size="14.00">name </text>
144
+ <text text-anchor="start" x="944.2" y="-194" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
145
+ <polygon fill="none" stroke="black" points="898.29,-151 898.29,-181.8 1148.06,-181.8 1148.06,-151 898.29,-151"/>
146
+ <text text-anchor="start" x="905.29" y="-163.2" font-family="Arial" font-size="14.00">created_at </text>
147
+ <text text-anchor="start" x="975.34" y="-163.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
148
+ </g>
149
+ <!-- public.node_tags -->
150
+ <g id="node6" class="node">
151
+ <title>public.node_tags</title>
152
+ <polygon fill="#efefef" stroke="none" points="892.7,-694 892.7,-729.6 1153.66,-729.6 1153.66,-694 892.7,-694"/>
153
+ <polygon fill="none" stroke="black" points="892.7,-694 892.7,-729.6 1153.66,-729.6 1153.66,-694 892.7,-694"/>
154
+ <text text-anchor="start" x="899.7" y="-707.4" font-family="Arial Bold" font-size="18.00">public.node_tags</text>
155
+ <text text-anchor="start" x="1022.17" y="-707.4" font-family="Arial" font-size="14.00">    </text>
156
+ <text text-anchor="start" x="1053.29" y="-707.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
157
+ <polygon fill="none" stroke="black" points="892.7,-663.2 892.7,-694 1153.66,-694 1153.66,-663.2 892.7,-663.2"/>
158
+ <text text-anchor="start" x="899.7" y="-675.4" font-family="Arial" font-size="14.00">id </text>
159
+ <text text-anchor="start" x="914.48" y="-675.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
160
+ <polygon fill="none" stroke="black" points="892.7,-632.4 892.7,-663.2 1153.66,-663.2 1153.66,-632.4 892.7,-632.4"/>
161
+ <text text-anchor="start" x="899.7" y="-644.6" font-family="Arial" font-size="14.00">node_id </text>
162
+ <text text-anchor="start" x="953.41" y="-644.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
163
+ <polygon fill="none" stroke="black" points="892.7,-601.6 892.7,-632.4 1153.66,-632.4 1153.66,-601.6 892.7,-601.6"/>
164
+ <text text-anchor="start" x="899.7" y="-613.8" font-family="Arial" font-size="14.00">tag_id </text>
165
+ <text text-anchor="start" x="941.73" y="-613.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
166
+ <polygon fill="none" stroke="black" points="892.7,-570.8 892.7,-601.6 1153.66,-601.6 1153.66,-570.8 892.7,-570.8"/>
167
+ <text text-anchor="start" x="899.7" y="-583" font-family="Arial" font-size="14.00">created_at </text>
168
+ <text text-anchor="start" x="969.74" y="-583" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
169
+ </g>
170
+ <!-- public.node_tags&#45;&gt;public.nodes -->
171
+ <g id="edge3" class="edge">
172
+ <title>public.node_tags:node_id&#45;&gt;public.nodes:id</title>
173
+ <path fill="none" stroke="black" d="M881.27,-647.18C813.48,-638.5 871.45,-540.15 841.18,-466 816.2,-404.81 835.43,-335.8 769.34,-335.8"/>
174
+ <polygon fill="black" stroke="black" points="881.38,-647.19 891.09,-652.27 886.7,-647.5 891.03,-647.76 891.03,-647.76 891.03,-647.76 886.7,-647.5 891.63,-643.29 881.38,-647.19"/>
175
+ <text text-anchor="start" x="898.7" y="-657.8" font-family="Arial" font-size="10.00">FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE</text>
176
+ </g>
177
+ <!-- public.node_tags&#45;&gt;public.tags -->
178
+ <g id="edge4" class="edge">
179
+ <title>public.node_tags:tag_id&#45;&gt;public.tags:id</title>
180
+ <path fill="none" stroke="black" d="M1163.27,-611.2C1196.88,-562.81 1189.17,-228 1149.06,-228"/>
181
+ <polygon fill="black" stroke="black" points="1163.23,-611.23 1152.42,-613.08 1158.81,-614.21 1155.21,-616.63 1155.21,-616.63 1155.21,-616.63 1158.81,-614.21 1157.45,-620.55 1163.23,-611.23"/>
182
+ <text text-anchor="start" x="993.23" y="-601" font-family="Arial" font-size="10.00">FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE</text>
183
+ </g>
184
+ <!-- public.working_memories -->
185
+ <g id="node7" class="node">
186
+ <title>public.working_memories</title>
187
+ <polygon fill="#efefef" stroke="none" points="43.2,-709.4 43.2,-745 371.16,-745 371.16,-709.4 43.2,-709.4"/>
188
+ <polygon fill="none" stroke="black" points="43.2,-709.4 43.2,-745 371.16,-745 371.16,-709.4 43.2,-709.4"/>
189
+ <text text-anchor="start" x="50.2" y="-722.8" font-family="Arial Bold" font-size="18.00">public.working_memories</text>
190
+ <text text-anchor="start" x="239.67" y="-722.8" font-family="Arial" font-size="14.00">    </text>
191
+ <text text-anchor="start" x="270.78" y="-722.8" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
192
+ <polygon fill="none" stroke="black" points="43.2,-678.6 43.2,-709.4 371.16,-709.4 371.16,-678.6 43.2,-678.6"/>
193
+ <text text-anchor="start" x="50.2" y="-690.8" font-family="Arial" font-size="14.00">id </text>
194
+ <text text-anchor="start" x="64.99" y="-690.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
195
+ <polygon fill="none" stroke="black" points="43.2,-647.8 43.2,-678.6 371.16,-678.6 371.16,-647.8 43.2,-647.8"/>
196
+ <text text-anchor="start" x="50.2" y="-660" font-family="Arial" font-size="14.00">robot_id </text>
197
+ <text text-anchor="start" x="104.68" y="-660" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
198
+ <polygon fill="none" stroke="black" points="43.2,-617 43.2,-647.8 371.16,-647.8 371.16,-617 43.2,-617"/>
199
+ <text text-anchor="start" x="50.2" y="-629.2" font-family="Arial" font-size="14.00">node_id </text>
200
+ <text text-anchor="start" x="103.92" y="-629.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
201
+ <polygon fill="none" stroke="black" points="43.2,-586.2 43.2,-617 371.16,-617 371.16,-586.2 43.2,-586.2"/>
202
+ <text text-anchor="start" x="50.2" y="-598.4" font-family="Arial" font-size="14.00">added_at </text>
203
+ <text text-anchor="start" x="112.48" y="-598.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
204
+ <polygon fill="none" stroke="black" points="43.2,-555.4 43.2,-586.2 371.16,-586.2 371.16,-555.4 43.2,-555.4"/>
205
+ <text text-anchor="start" x="50.2" y="-567.6" font-family="Arial" font-size="14.00">token_count </text>
206
+ <text text-anchor="start" x="130.37" y="-567.6" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
207
+ </g>
208
+ <!-- public.working_memories&#45;&gt;public.robots -->
209
+ <g id="edge5" class="edge">
210
+ <title>public.working_memories:robot_id&#45;&gt;public.robots:id</title>
211
+ <path fill="none" stroke="black" d="M382.25,-662.4C435.3,-653.25 401.13,-568.12 371.16,-512.2 305.6,-389.89 178.09,-459.78 112.29,-337.6 92.44,-300.74 69.42,-243.4 111.29,-243.4"/>
212
+ <polygon fill="black" stroke="black" points="382.46,-662.38 372.13,-658.69 377.14,-662.8 372.82,-663.15 372.82,-663.15 372.82,-663.15 377.14,-662.8 372.85,-667.66 382.46,-662.38"/>
213
+ <text text-anchor="start" x="379.16" y="-673.2" font-family="Arial" font-size="10.00">FOREIGN KEY (robot_id) REFERENCES robots(id) ON DELETE CASCADE</text>
214
+ </g>
215
+ <!-- public.working_memories&#45;&gt;public.nodes -->
216
+ <g id="edge6" class="edge">
217
+ <title>public.working_memories:node_id&#45;&gt;public.nodes:id</title>
218
+ <path fill="none" stroke="black" d="M382.55,-631.73C444.2,-623.16 394.47,-533.74 423.18,-466 448.97,-405.15 428.92,-335.8 495.01,-335.8"/>
219
+ <polygon fill="black" stroke="black" points="382.47,-631.74 372.2,-627.89 377.14,-632.08 372.82,-632.36 372.82,-632.36 372.82,-632.36 377.14,-632.08 372.78,-636.87 382.47,-631.74"/>
220
+ <text text-anchor="start" x="379.16" y="-642.4" font-family="Arial" font-size="10.00">FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE</text>
221
+ </g>
222
+ </g>
223
+ </svg>
data/docs/development/index.md CHANGED
@@ -255,35 +255,7 @@ We value continuous improvement:
255
255
 
256
256
  Understanding the codebase structure:
257
257
 
258
- ```
259
- htm/
260
- ├── lib/ # Main library code
261
- │ ├── htm.rb # HTM main class
262
- │ └── htm/
263
- │ ├── database.rb # Database setup and management
264
- │ ├── long_term_memory.rb # PostgreSQL-backed storage
265
- │ ├── working_memory.rb # In-memory active context
266
- │ ├── embedding_service.rb # Vector embedding generation
267
- │ └── version.rb # Version constant
268
- ├── test/ # Test suite
269
- │ ├── test_helper.rb # Test configuration
270
- │ ├── htm_test.rb # Unit tests
271
- │ ├── embedding_service_test.rb # Embedding tests
272
- │ └── integration_test.rb # Integration tests
273
- ├── sql/ # Database schemas
274
- │ └── schema.sql # PostgreSQL schema
275
- ├── examples/ # Usage examples
276
- │ └── basic_usage.rb # Basic usage demonstration
277
- ├── docs/ # Documentation (MkDocs)
278
- │ ├── development/ # This guide
279
- │ ├── guides/ # User guides
280
- │ ├── api/ # API reference
281
- │ └── architecture/ # Architecture docs
282
- ├── Rakefile # Rake tasks
283
- ├── Gemfile # Development dependencies
284
- ├── htm.gemspec # Gem specification
285
- └── README.md # Project overview
286
- ```
258
+ ![HTM Project Structure](../assets/images/project-structure.svg)
287
259
 
288
260
  ## Tools and Technologies
289
261