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/public.working_memories.svg ADDED
@@ -0,0 +1,112 @@
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: public.working_memories Pages: 1 -->
7
+ <svg width="1046pt" height="756pt"
8
+ viewBox="0.00 0.00 1046.14 756.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 752)">
10
+ <title>public.working_memories</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-752 1042.14,-752 1042.14,4 -4,4"/>
12
+ <!-- public.working_memories -->
13
+ <g id="node1" class="node">
14
+ <title>public.working_memories</title>
15
+ <polygon fill="#efefef" stroke="none" points="355.64,-666.2 355.64,-701.8 683.59,-701.8 683.59,-666.2 355.64,-666.2"/>
16
+ <polygon fill="none" stroke="black" points="355.64,-666.2 355.64,-701.8 683.59,-701.8 683.59,-666.2 355.64,-666.2"/>
17
+ <text text-anchor="start" x="362.64" y="-679.6" font-family="Arial Bold" font-size="18.00">public.working_memories</text>
18
+ <text text-anchor="start" x="552.11" y="-679.6" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="583.22" y="-679.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="355.64,-635.4 355.64,-666.2 683.59,-666.2 683.59,-635.4 355.64,-635.4"/>
21
+ <text text-anchor="start" x="362.64" y="-647.6" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="377.43" y="-647.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="355.64,-604.6 355.64,-635.4 683.59,-635.4 683.59,-604.6 355.64,-604.6"/>
24
+ <text text-anchor="start" x="362.64" y="-616.8" font-family="Arial" font-size="14.00">robot_id </text>
25
+ <text text-anchor="start" x="417.12" y="-616.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
26
+ <polygon fill="none" stroke="black" points="355.64,-573.8 355.64,-604.6 683.59,-604.6 683.59,-573.8 355.64,-573.8"/>
27
+ <text text-anchor="start" x="362.64" y="-586" font-family="Arial" font-size="14.00">node_id </text>
28
+ <text text-anchor="start" x="416.36" y="-586" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
29
+ <polygon fill="none" stroke="black" points="355.64,-543 355.64,-573.8 683.59,-573.8 683.59,-543 355.64,-543"/>
30
+ <text text-anchor="start" x="362.64" y="-555.2" font-family="Arial" font-size="14.00">added_at </text>
31
+ <text text-anchor="start" x="424.92" y="-555.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
32
+ <polygon fill="none" stroke="black" points="355.64,-512.2 355.64,-543 683.59,-543 683.59,-512.2 355.64,-512.2"/>
33
+ <text text-anchor="start" x="362.64" y="-524.4" font-family="Arial" font-size="14.00">token_count </text>
34
+ <text text-anchor="start" x="442.81" y="-524.4" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
35
+ <polygon fill="none" stroke="black" stroke-width="3" points="354.14,-510.7 354.14,-703.3 685.09,-703.3 685.09,-510.7 354.14,-510.7"/>
36
+ </g>
37
+ <!-- public.robots -->
38
+ <g id="node2" class="node">
39
+ <title>public.robots</title>
40
+ <polygon fill="#efefef" stroke="none" points="212.73,-258.8 212.73,-294.4 462.5,-294.4 462.5,-258.8 212.73,-258.8"/>
41
+ <polygon fill="none" stroke="black" points="212.73,-258.8 212.73,-294.4 462.5,-294.4 462.5,-258.8 212.73,-258.8"/>
42
+ <text text-anchor="start" x="228.13" y="-272.2" font-family="Arial Bold" font-size="18.00">public.robots</text>
43
+ <text text-anchor="start" x="322.62" y="-272.2" font-family="Arial" font-size="14.00">    </text>
44
+ <text text-anchor="start" x="353.74" y="-272.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
45
+ <polygon fill="none" stroke="black" points="212.73,-228 212.73,-258.8 462.5,-258.8 462.5,-228 212.73,-228"/>
46
+ <text text-anchor="start" x="219.73" y="-240.2" font-family="Arial" font-size="14.00">id </text>
47
+ <text text-anchor="start" x="234.52" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
48
+ <polygon fill="none" stroke="black" points="212.73,-197.2 212.73,-228 462.5,-228 462.5,-197.2 212.73,-197.2"/>
49
+ <text text-anchor="start" x="219.73" y="-209.4" font-family="Arial" font-size="14.00">name </text>
50
+ <text text-anchor="start" x="258.64" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
51
+ <polygon fill="none" stroke="black" points="212.73,-166.4 212.73,-197.2 462.5,-197.2 462.5,-166.4 212.73,-166.4"/>
52
+ <text text-anchor="start" x="219.73" y="-178.6" font-family="Arial" font-size="14.00">created_at </text>
53
+ <text text-anchor="start" x="289.78" y="-178.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
54
+ <polygon fill="none" stroke="black" points="212.73,-135.6 212.73,-166.4 462.5,-166.4 462.5,-135.6 212.73,-135.6"/>
55
+ <text text-anchor="start" x="219.73" y="-147.8" font-family="Arial" font-size="14.00">last_active </text>
56
+ <text text-anchor="start" x="289.77" y="-147.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
57
+ </g>
58
+ <!-- public.working_memories&#45;&gt;public.robots -->
59
+ <g id="edge1" class="edge">
60
+ <title>public.working_memories:robot_id&#45;&gt;public.robots:id</title>
61
+ <path fill="none" stroke="black" d="M344.41,-619.21C291.15,-610.26 333.43,-526.77 355.64,-466 381.12,-396.26 436.88,-407.28 462.5,-337.6 476.95,-298.3 505.37,-243.4 463.5,-243.4"/>
62
+ <polygon fill="black" stroke="black" points="344.34,-619.21 353.96,-624.46 349.65,-619.62 353.97,-619.95 353.97,-619.95 353.97,-619.95 349.65,-619.62 354.65,-615.49 344.34,-619.21"/>
63
+ <text text-anchor="start" x="7" y="-630" font-family="Arial" font-size="10.00">FOREIGN KEY (robot_id) REFERENCES robots(id) ON DELETE CASCADE</text>
64
+ </g>
65
+ <!-- public.nodes -->
66
+ <g id="node3" class="node">
67
+ <title>public.nodes</title>
68
+ <polygon fill="#efefef" stroke="none" points="566.45,-351.2 566.45,-386.8 838.78,-386.8 838.78,-351.2 566.45,-351.2"/>
69
+ <polygon fill="none" stroke="black" points="566.45,-351.2 566.45,-386.8 838.78,-386.8 838.78,-351.2 566.45,-351.2"/>
70
+ <text text-anchor="start" x="594.63" y="-364.6" font-family="Arial Bold" font-size="18.00">public.nodes</text>
71
+ <text text-anchor="start" x="686.12" y="-364.6" font-family="Arial" font-size="14.00">    </text>
72
+ <text text-anchor="start" x="717.23" y="-364.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
73
+ <polygon fill="none" stroke="black" points="566.45,-320.4 566.45,-351.2 838.78,-351.2 838.78,-320.4 566.45,-320.4"/>
74
+ <text text-anchor="start" x="573.45" y="-332.6" font-family="Arial" font-size="14.00">id </text>
75
+ <text text-anchor="start" x="588.24" y="-332.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
76
+ <polygon fill="none" stroke="black" points="566.45,-289.6 566.45,-320.4 838.78,-320.4 838.78,-289.6 566.45,-289.6"/>
77
+ <text text-anchor="start" x="573.45" y="-301.8" font-family="Arial" font-size="14.00">content </text>
78
+ <text text-anchor="start" x="623.27" y="-301.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
79
+ <polygon fill="none" stroke="black" points="566.45,-258.8 566.45,-289.6 838.78,-289.6 838.78,-258.8 566.45,-258.8"/>
80
+ <text text-anchor="start" x="573.45" y="-271" font-family="Arial" font-size="14.00">access_count </text>
81
+ <text text-anchor="start" x="662.95" y="-271" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
82
+ <polygon fill="none" stroke="black" points="566.45,-228 566.45,-258.8 838.78,-258.8 838.78,-228 566.45,-228"/>
83
+ <text text-anchor="start" x="573.45" y="-240.2" font-family="Arial" font-size="14.00">created_at </text>
84
+ <text text-anchor="start" x="643.5" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
85
+ <polygon fill="none" stroke="black" points="566.45,-197.2 566.45,-228 838.78,-228 838.78,-197.2 566.45,-197.2"/>
86
+ <text text-anchor="start" x="573.45" y="-209.4" font-family="Arial" font-size="14.00">updated_at </text>
87
+ <text text-anchor="start" x="647.41" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
88
+ <polygon fill="none" stroke="black" points="566.45,-166.4 566.45,-197.2 838.78,-197.2 838.78,-166.4 566.45,-166.4"/>
89
+ <text text-anchor="start" x="573.45" y="-178.6" font-family="Arial" font-size="14.00">last_accessed </text>
90
+ <text text-anchor="start" x="666.06" y="-178.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
91
+ <polygon fill="none" stroke="black" points="566.45,-135.6 566.45,-166.4 838.78,-166.4 838.78,-135.6 566.45,-135.6"/>
92
+ <text text-anchor="start" x="573.45" y="-147.8" font-family="Arial" font-size="14.00">token_count </text>
93
+ <text text-anchor="start" x="653.62" y="-147.8" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
94
+ <polygon fill="none" stroke="black" points="566.45,-104.8 566.45,-135.6 838.78,-135.6 838.78,-104.8 566.45,-104.8"/>
95
+ <text text-anchor="start" x="573.45" y="-117" font-family="Arial" font-size="14.00">embedding </text>
96
+ <text text-anchor="start" x="646.62" y="-117" font-family="Arial" font-size="14.00" fill="#666666">[vector(2000)]</text>
97
+ <polygon fill="none" stroke="black" points="566.45,-74 566.45,-104.8 838.78,-104.8 838.78,-74 566.45,-74"/>
98
+ <text text-anchor="start" x="573.45" y="-86.2" font-family="Arial" font-size="14.00">embedding_dimension </text>
99
+ <text text-anchor="start" x="718.22" y="-86.2" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
100
+ <polygon fill="none" stroke="black" points="566.45,-43.2 566.45,-74 838.78,-74 838.78,-43.2 566.45,-43.2"/>
101
+ <text text-anchor="start" x="573.45" y="-55.4" font-family="Arial" font-size="14.00">content_hash </text>
102
+ <text text-anchor="start" x="661.41" y="-55.4" font-family="Arial" font-size="14.00" fill="#666666">[varchar(64)]</text>
103
+ </g>
104
+ <!-- public.working_memories&#45;&gt;public.nodes -->
105
+ <g id="edge2" class="edge">
106
+ <title>public.working_memories:node_id&#45;&gt;public.nodes:id</title>
107
+ <path fill="none" stroke="black" d="M694.76,-588.13C736.16,-578.52 714.08,-506.91 683.59,-466 651.05,-422.32 599.05,-473.63 566.45,-430 541.39,-396.46 523.58,-335.8 565.45,-335.8"/>
108
+ <polygon fill="black" stroke="black" points="694.87,-588.11 684.45,-584.69 689.57,-588.67 685.26,-589.13 685.26,-589.13 685.26,-589.13 689.57,-588.67 685.4,-593.64 694.87,-588.11"/>
109
+ <text text-anchor="start" x="691.59" y="-599.2" font-family="Arial" font-size="10.00">FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE</text>
110
+ </g>
111
+ </g>
112
+ </svg>