htm 0.0.1

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 (155) hide show
  1. checksums.yaml +7 -0
  2. data/.architecture/decisions/adrs/001-use-postgresql-timescaledb-storage.md +227 -0
  3. data/.architecture/decisions/adrs/002-two-tier-memory-architecture.md +322 -0
  4. data/.architecture/decisions/adrs/003-ollama-default-embedding-provider.md +339 -0
  5. data/.architecture/decisions/adrs/004-multi-robot-shared-memory-hive-mind.md +374 -0
  6. data/.architecture/decisions/adrs/005-rag-based-retrieval-with-hybrid-search.md +443 -0
  7. data/.architecture/decisions/adrs/006-context-assembly-strategies.md +444 -0
  8. data/.architecture/decisions/adrs/007-working-memory-eviction-strategy.md +461 -0
  9. data/.architecture/decisions/adrs/008-robot-identification-system.md +550 -0
  10. data/.architecture/decisions/adrs/009-never-forget-explicit-deletion-only.md +570 -0
  11. data/.architecture/decisions/adrs/010-redis-working-memory-rejected.md +323 -0
  12. data/.architecture/decisions/adrs/011-database-side-embedding-generation-with-pgai.md +585 -0
  13. data/.architecture/decisions/adrs/012-llm-driven-ontology-topic-extraction.md +583 -0
  14. data/.architecture/decisions/adrs/013-activerecord-orm-and-many-to-many-tagging.md +299 -0
  15. data/.architecture/decisions/adrs/014-client-side-embedding-generation-workflow.md +569 -0
  16. data/.architecture/decisions/adrs/015-hierarchical-tag-ontology-and-llm-extraction.md +701 -0
  17. data/.architecture/decisions/adrs/016-async-embedding-and-tag-generation.md +694 -0
  18. data/.architecture/members.yml +144 -0
  19. data/.architecture/reviews/2025-10-29-llm-configuration-and-async-processing-review.md +1137 -0
  20. data/.architecture/reviews/initial-system-analysis.md +330 -0
  21. data/.envrc +32 -0
  22. data/.irbrc +145 -0
  23. data/CHANGELOG.md +150 -0
  24. data/COMMITS.md +196 -0
  25. data/LICENSE +21 -0
  26. data/README.md +1347 -0
  27. data/Rakefile +51 -0
  28. data/SETUP.md +268 -0
  29. data/config/database.yml +67 -0
  30. data/db/migrate/20250101000001_enable_extensions.rb +14 -0
  31. data/db/migrate/20250101000002_create_robots.rb +14 -0
  32. data/db/migrate/20250101000003_create_nodes.rb +42 -0
  33. data/db/migrate/20250101000005_create_tags.rb +38 -0
  34. data/db/migrate/20250101000007_add_node_vector_indexes.rb +30 -0
  35. data/db/schema.sql +473 -0
  36. data/db/seed_data/README.md +100 -0
  37. data/db/seed_data/presidents.md +136 -0
  38. data/db/seed_data/states.md +151 -0
  39. data/db/seeds.rb +208 -0
  40. data/dbdoc/README.md +173 -0
  41. data/dbdoc/public.node_stats.md +48 -0
  42. data/dbdoc/public.node_stats.svg +41 -0
  43. data/dbdoc/public.node_tags.md +40 -0
  44. data/dbdoc/public.node_tags.svg +112 -0
  45. data/dbdoc/public.nodes.md +54 -0
  46. data/dbdoc/public.nodes.svg +118 -0
  47. data/dbdoc/public.nodes_tags.md +39 -0
  48. data/dbdoc/public.nodes_tags.svg +112 -0
  49. data/dbdoc/public.ontology_structure.md +48 -0
  50. data/dbdoc/public.ontology_structure.svg +38 -0
  51. data/dbdoc/public.operations_log.md +42 -0
  52. data/dbdoc/public.operations_log.svg +130 -0
  53. data/dbdoc/public.relationships.md +39 -0
  54. data/dbdoc/public.relationships.svg +41 -0
  55. data/dbdoc/public.robot_activity.md +46 -0
  56. data/dbdoc/public.robot_activity.svg +35 -0
  57. data/dbdoc/public.robots.md +35 -0
  58. data/dbdoc/public.robots.svg +90 -0
  59. data/dbdoc/public.schema_migrations.md +29 -0
  60. data/dbdoc/public.schema_migrations.svg +26 -0
  61. data/dbdoc/public.tags.md +35 -0
  62. data/dbdoc/public.tags.svg +60 -0
  63. data/dbdoc/public.topic_relationships.md +45 -0
  64. data/dbdoc/public.topic_relationships.svg +32 -0
  65. data/dbdoc/schema.json +1437 -0
  66. data/dbdoc/schema.svg +154 -0
  67. data/docs/api/database.md +806 -0
  68. data/docs/api/embedding-service.md +532 -0
  69. data/docs/api/htm.md +797 -0
  70. data/docs/api/index.md +259 -0
  71. data/docs/api/long-term-memory.md +1096 -0
  72. data/docs/api/working-memory.md +665 -0
  73. data/docs/architecture/adrs/001-postgresql-timescaledb.md +314 -0
  74. data/docs/architecture/adrs/002-two-tier-memory.md +411 -0
  75. data/docs/architecture/adrs/003-ollama-embeddings.md +421 -0
  76. data/docs/architecture/adrs/004-hive-mind.md +437 -0
  77. data/docs/architecture/adrs/005-rag-retrieval.md +531 -0
  78. data/docs/architecture/adrs/006-context-assembly.md +496 -0
  79. data/docs/architecture/adrs/007-eviction-strategy.md +645 -0
  80. data/docs/architecture/adrs/008-robot-identification.md +625 -0
  81. data/docs/architecture/adrs/009-never-forget.md +648 -0
  82. data/docs/architecture/adrs/010-redis-working-memory-rejected.md +323 -0
  83. data/docs/architecture/adrs/011-pgai-integration.md +494 -0
  84. data/docs/architecture/adrs/index.md +215 -0
  85. data/docs/architecture/hive-mind.md +736 -0
  86. data/docs/architecture/index.md +351 -0
  87. data/docs/architecture/overview.md +538 -0
  88. data/docs/architecture/two-tier-memory.md +873 -0
  89. data/docs/assets/css/custom.css +83 -0
  90. data/docs/assets/images/htm-core-components.svg +63 -0
  91. data/docs/assets/images/htm-database-schema.svg +93 -0
  92. data/docs/assets/images/htm-hive-mind-architecture.svg +125 -0
  93. data/docs/assets/images/htm-importance-scoring-framework.svg +83 -0
  94. data/docs/assets/images/htm-layered-architecture.svg +71 -0
  95. data/docs/assets/images/htm-long-term-memory-architecture.svg +115 -0
  96. data/docs/assets/images/htm-working-memory-architecture.svg +120 -0
  97. data/docs/assets/images/htm.jpg +0 -0
  98. data/docs/assets/images/htm_demo.gif +0 -0
  99. data/docs/assets/js/mathjax.js +18 -0
  100. data/docs/assets/videos/htm_video.mp4 +0 -0
  101. data/docs/database_rake_tasks.md +322 -0
  102. data/docs/development/contributing.md +787 -0
  103. data/docs/development/index.md +336 -0
  104. data/docs/development/schema.md +596 -0
  105. data/docs/development/setup.md +719 -0
  106. data/docs/development/testing.md +819 -0
  107. data/docs/guides/adding-memories.md +824 -0
  108. data/docs/guides/context-assembly.md +1009 -0
  109. data/docs/guides/getting-started.md +577 -0
  110. data/docs/guides/index.md +118 -0
  111. data/docs/guides/long-term-memory.md +941 -0
  112. data/docs/guides/multi-robot.md +866 -0
  113. data/docs/guides/recalling-memories.md +927 -0
  114. data/docs/guides/search-strategies.md +953 -0
  115. data/docs/guides/working-memory.md +717 -0
  116. data/docs/index.md +214 -0
  117. data/docs/installation.md +477 -0
  118. data/docs/multi_framework_support.md +519 -0
  119. data/docs/quick-start.md +655 -0
  120. data/docs/setup_local_database.md +302 -0
  121. data/docs/using_rake_tasks_in_your_app.md +383 -0
  122. data/examples/basic_usage.rb +93 -0
  123. data/examples/cli_app/README.md +317 -0
  124. data/examples/cli_app/htm_cli.rb +270 -0
  125. data/examples/custom_llm_configuration.rb +183 -0
  126. data/examples/example_app/Rakefile +71 -0
  127. data/examples/example_app/app.rb +206 -0
  128. data/examples/sinatra_app/Gemfile +21 -0
  129. data/examples/sinatra_app/app.rb +335 -0
  130. data/lib/htm/active_record_config.rb +113 -0
  131. data/lib/htm/configuration.rb +342 -0
  132. data/lib/htm/database.rb +594 -0
  133. data/lib/htm/embedding_service.rb +115 -0
  134. data/lib/htm/errors.rb +34 -0
  135. data/lib/htm/job_adapter.rb +154 -0
  136. data/lib/htm/jobs/generate_embedding_job.rb +65 -0
  137. data/lib/htm/jobs/generate_tags_job.rb +82 -0
  138. data/lib/htm/long_term_memory.rb +965 -0
  139. data/lib/htm/models/node.rb +109 -0
  140. data/lib/htm/models/node_tag.rb +33 -0
  141. data/lib/htm/models/robot.rb +52 -0
  142. data/lib/htm/models/tag.rb +76 -0
  143. data/lib/htm/railtie.rb +76 -0
  144. data/lib/htm/sinatra.rb +157 -0
  145. data/lib/htm/tag_service.rb +135 -0
  146. data/lib/htm/tasks.rb +38 -0
  147. data/lib/htm/version.rb +5 -0
  148. data/lib/htm/working_memory.rb +182 -0
  149. data/lib/htm.rb +400 -0
  150. data/lib/tasks/db.rake +19 -0
  151. data/lib/tasks/htm.rake +147 -0
  152. data/lib/tasks/jobs.rake +312 -0
  153. data/mkdocs.yml +190 -0
  154. data/scripts/install_local_database.sh +309 -0
  155. metadata +341 -0
data/dbdoc/public.nodes_tags.md ADDED
@@ -0,0 +1,39 @@
1
+ # public.nodes_tags
2
+
3
+ ## Description
4
+
5
+ Join table connecting nodes to tags (many-to-many)
6
+
7
+ ## Columns
8
+
9
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
10
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
11
+ | id | bigint | nextval('node_tags_id_seq'::regclass) | false | | | |
12
+ | node_id | bigint | | false | | [public.nodes](public.nodes.md) | ID of the node being tagged |
13
+ | tag_id | bigint | | false | | [public.tags](public.tags.md) | ID of the tag being applied |
14
+ | created_at | timestamp with time zone | CURRENT_TIMESTAMP | true | | | When this association was created |
15
+
16
+ ## Constraints
17
+
18
+ | Name | Type | Definition |
19
+ | ---- | ---- | ---------- |
20
+ | node_tags_pkey | PRIMARY KEY | PRIMARY KEY (id) |
21
+ | fk_rails_b0b726ecf8 | FOREIGN KEY | FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE |
22
+ | fk_rails_eccc99cec5 | FOREIGN KEY | FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE |
23
+
24
+ ## Indexes
25
+
26
+ | Name | Definition |
27
+ | ---- | ---------- |
28
+ | node_tags_pkey | CREATE UNIQUE INDEX node_tags_pkey ON public.nodes_tags USING btree (id) |
29
+ | idx_node_tags_unique | CREATE UNIQUE INDEX idx_node_tags_unique ON public.nodes_tags USING btree (node_id, tag_id) |
30
+ | idx_node_tags_node_id | CREATE INDEX idx_node_tags_node_id ON public.nodes_tags USING btree (node_id) |
31
+ | idx_node_tags_tag_id | CREATE INDEX idx_node_tags_tag_id ON public.nodes_tags USING btree (tag_id) |
32
+
33
+ ## Relations
34
+
35
+ ![er](public.nodes_tags.svg)
36
+
37
+ ---
38
+
39
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.nodes_tags.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.nodes_tags Pages: 1 -->
7
+ <svg width="968pt" height="787pt"
8
+ viewBox="0.00 0.00 968.37 786.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 782.8)">
10
+ <title>public.nodes_tags</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-782.8 964.37,-782.8 964.37,4 -4,4"/>
12
+ <!-- public.nodes_tags -->
13
+ <g id="node1" class="node">
14
+ <title>public.nodes_tags</title>
15
+ <polygon fill="#efefef" stroke="none" points="354.55,-697 354.55,-732.6 622.52,-732.6 622.52,-697 354.55,-697"/>
16
+ <polygon fill="none" stroke="black" points="354.55,-697 354.55,-732.6 622.52,-732.6 622.52,-697 354.55,-697"/>
17
+ <text text-anchor="start" x="361.55" y="-710.4" font-family="Arial Bold" font-size="18.00">public.nodes_tags</text>
18
+ <text text-anchor="start" x="491.03" y="-710.4" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="522.14" y="-710.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="354.55,-666.2 354.55,-697 622.52,-697 622.52,-666.2 354.55,-666.2"/>
21
+ <text text-anchor="start" x="361.55" y="-678.4" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="376.33" y="-678.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="354.55,-635.4 354.55,-666.2 622.52,-666.2 622.52,-635.4 354.55,-635.4"/>
24
+ <text text-anchor="start" x="361.55" y="-647.6" font-family="Arial" font-size="14.00">node_id </text>
25
+ <text text-anchor="start" x="415.26" y="-647.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
26
+ <polygon fill="none" stroke="black" points="354.55,-604.6 354.55,-635.4 622.52,-635.4 622.52,-604.6 354.55,-604.6"/>
27
+ <text text-anchor="start" x="361.55" y="-616.8" font-family="Arial" font-size="14.00">tag_id </text>
28
+ <text text-anchor="start" x="403.58" y="-616.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
29
+ <polygon fill="none" stroke="black" points="354.55,-573.8 354.55,-604.6 622.52,-604.6 622.52,-573.8 354.55,-573.8"/>
30
+ <text text-anchor="start" x="361.55" y="-586" font-family="Arial" font-size="14.00">created_at </text>
31
+ <text text-anchor="start" x="431.59" y="-586" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
32
+ <polygon fill="none" stroke="black" stroke-width="3" points="353.05,-572.3 353.05,-734.1 624.02,-734.1 624.02,-572.3 353.05,-572.3"/>
33
+ </g>
34
+ <!-- public.nodes -->
35
+ <g id="node2" class="node">
36
+ <title>public.nodes</title>
37
+ <polygon fill="#efefef" stroke="none" points="170.37,-412.8 170.37,-448.4 442.7,-448.4 442.7,-412.8 170.37,-412.8"/>
38
+ <polygon fill="none" stroke="black" points="170.37,-412.8 170.37,-448.4 442.7,-448.4 442.7,-412.8 170.37,-412.8"/>
39
+ <text text-anchor="start" x="198.54" y="-426.2" font-family="Arial Bold" font-size="18.00">public.nodes</text>
40
+ <text text-anchor="start" x="290.03" y="-426.2" font-family="Arial" font-size="14.00">    </text>
41
+ <text text-anchor="start" x="321.15" y="-426.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
42
+ <polygon fill="none" stroke="black" points="170.37,-382 170.37,-412.8 442.7,-412.8 442.7,-382 170.37,-382"/>
43
+ <text text-anchor="start" x="177.37" y="-394.2" font-family="Arial" font-size="14.00">id </text>
44
+ <text text-anchor="start" x="192.15" y="-394.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
45
+ <polygon fill="none" stroke="black" points="170.37,-351.2 170.37,-382 442.7,-382 442.7,-351.2 170.37,-351.2"/>
46
+ <text text-anchor="start" x="177.37" y="-363.4" font-family="Arial" font-size="14.00">content </text>
47
+ <text text-anchor="start" x="227.18" y="-363.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
48
+ <polygon fill="none" stroke="black" points="170.37,-320.4 170.37,-351.2 442.7,-351.2 442.7,-320.4 170.37,-320.4"/>
49
+ <text text-anchor="start" x="177.37" y="-332.6" font-family="Arial" font-size="14.00">source </text>
50
+ <text text-anchor="start" x="223.28" y="-332.6" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
51
+ <polygon fill="none" stroke="black" points="170.37,-289.6 170.37,-320.4 442.7,-320.4 442.7,-289.6 170.37,-289.6"/>
52
+ <text text-anchor="start" x="177.37" y="-301.8" font-family="Arial" font-size="14.00">access_count </text>
53
+ <text text-anchor="start" x="266.86" y="-301.8" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
54
+ <polygon fill="none" stroke="black" points="170.37,-258.8 170.37,-289.6 442.7,-289.6 442.7,-258.8 170.37,-258.8"/>
55
+ <text text-anchor="start" x="177.37" y="-271" font-family="Arial" font-size="14.00">created_at </text>
56
+ <text text-anchor="start" x="247.41" y="-271" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
57
+ <polygon fill="none" stroke="black" points="170.37,-228 170.37,-258.8 442.7,-258.8 442.7,-228 170.37,-228"/>
58
+ <text text-anchor="start" x="177.37" y="-240.2" font-family="Arial" font-size="14.00">updated_at </text>
59
+ <text text-anchor="start" x="251.32" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
60
+ <polygon fill="none" stroke="black" points="170.37,-197.2 170.37,-228 442.7,-228 442.7,-197.2 170.37,-197.2"/>
61
+ <text text-anchor="start" x="177.37" y="-209.4" font-family="Arial" font-size="14.00">last_accessed </text>
62
+ <text text-anchor="start" x="269.97" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
63
+ <polygon fill="none" stroke="black" points="170.37,-166.4 170.37,-197.2 442.7,-197.2 442.7,-166.4 170.37,-166.4"/>
64
+ <text text-anchor="start" x="177.37" y="-178.6" font-family="Arial" font-size="14.00">token_count </text>
65
+ <text text-anchor="start" x="257.54" y="-178.6" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
66
+ <polygon fill="none" stroke="black" points="170.37,-135.6 170.37,-166.4 442.7,-166.4 442.7,-135.6 170.37,-135.6"/>
67
+ <text text-anchor="start" x="177.37" y="-147.8" font-family="Arial" font-size="14.00">in_working_memory </text>
68
+ <text text-anchor="start" x="306.52" y="-147.8" font-family="Arial" font-size="14.00" fill="#666666">[boolean]</text>
69
+ <polygon fill="none" stroke="black" points="170.37,-104.8 170.37,-135.6 442.7,-135.6 442.7,-104.8 170.37,-104.8"/>
70
+ <text text-anchor="start" x="177.37" y="-117" font-family="Arial" font-size="14.00">robot_id </text>
71
+ <text text-anchor="start" x="231.85" y="-117" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
72
+ <polygon fill="none" stroke="black" points="170.37,-74 170.37,-104.8 442.7,-104.8 442.7,-74 170.37,-74"/>
73
+ <text text-anchor="start" x="177.37" y="-86.2" font-family="Arial" font-size="14.00">embedding </text>
74
+ <text text-anchor="start" x="250.53" y="-86.2" font-family="Arial" font-size="14.00" fill="#666666">[vector(2000)]</text>
75
+ <polygon fill="none" stroke="black" points="170.37,-43.2 170.37,-74 442.7,-74 442.7,-43.2 170.37,-43.2"/>
76
+ <text text-anchor="start" x="177.37" y="-55.4" font-family="Arial" font-size="14.00">embedding_dimension </text>
77
+ <text text-anchor="start" x="322.13" y="-55.4" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
78
+ </g>
79
+ <!-- public.nodes_tags&#45;&gt;public.nodes -->
80
+ <g id="edge1" class="edge">
81
+ <title>public.nodes_tags:node_id&#45;&gt;public.nodes:id</title>
82
+ <path fill="none" stroke="black" d="M343.41,-649.74C302.24,-640.31 325.93,-569.83 354.55,-527.6 378.29,-492.57 418.91,-526.6 442.7,-491.6 466.23,-456.97 485.56,-397.4 443.7,-397.4"/>
83
+ <polygon fill="black" stroke="black" points="343.27,-649.73 352.75,-655.24 348.57,-650.28 352.88,-650.73 352.88,-650.73 352.88,-650.73 348.57,-650.28 353.68,-646.29 343.27,-649.73"/>
84
+ <text text-anchor="start" x="7" y="-660.8" font-family="Arial" font-size="10.00">FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE</text>
85
+ </g>
86
+ <!-- public.tags -->
87
+ <g id="node3" class="node">
88
+ <title>public.tags</title>
89
+ <polygon fill="#efefef" stroke="none" points="546.65,-274.2 546.65,-309.8 796.42,-309.8 796.42,-274.2 546.65,-274.2"/>
90
+ <polygon fill="none" stroke="black" points="546.65,-274.2 546.65,-309.8 796.42,-309.8 796.42,-274.2 546.65,-274.2"/>
91
+ <text text-anchor="start" x="570.04" y="-287.6" font-family="Arial Bold" font-size="18.00">public.tags</text>
92
+ <text text-anchor="start" x="648.53" y="-287.6" font-family="Arial" font-size="14.00">    </text>
93
+ <text text-anchor="start" x="679.65" y="-287.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
94
+ <polygon fill="none" stroke="black" points="546.65,-243.4 546.65,-274.2 796.42,-274.2 796.42,-243.4 546.65,-243.4"/>
95
+ <text text-anchor="start" x="553.65" y="-255.6" font-family="Arial" font-size="14.00">id </text>
96
+ <text text-anchor="start" x="568.43" y="-255.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
97
+ <polygon fill="none" stroke="black" points="546.65,-212.6 546.65,-243.4 796.42,-243.4 796.42,-212.6 546.65,-212.6"/>
98
+ <text text-anchor="start" x="553.65" y="-224.8" font-family="Arial" font-size="14.00">name </text>
99
+ <text text-anchor="start" x="592.56" y="-224.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
100
+ <polygon fill="none" stroke="black" points="546.65,-181.8 546.65,-212.6 796.42,-212.6 796.42,-181.8 546.65,-181.8"/>
101
+ <text text-anchor="start" x="553.65" y="-194" font-family="Arial" font-size="14.00">created_at </text>
102
+ <text text-anchor="start" x="623.69" y="-194" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
103
+ </g>
104
+ <!-- public.nodes_tags&#45;&gt;public.tags -->
105
+ <g id="edge2" class="edge">
106
+ <title>public.nodes_tags:tag_id&#45;&gt;public.tags:id</title>
107
+ <path fill="none" stroke="black" d="M633.73,-619.46C769.77,-603.96 385.11,-258.8 545.65,-258.8"/>
108
+ <polygon fill="black" stroke="black" points="633.84,-619.46 623.61,-615.49 628.51,-619.74 624.18,-619.96 624.18,-619.96 624.18,-619.96 628.51,-619.74 624.09,-624.48 633.84,-619.46"/>
109
+ <text text-anchor="start" x="630.52" y="-630" font-family="Arial" font-size="10.00">FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE</text>
110
+ </g>
111
+ </g>
112
+ </svg>
data/dbdoc/public.ontology_structure.md ADDED
@@ -0,0 +1,48 @@
1
+ # public.ontology_structure
2
+
3
+ ## Description
4
+
5
+ Provides a hierarchical view of all topics in the knowledge base. Topics use colon-delimited format (e.g., database:postgresql:timescaledb) and are assigned manually via tags.
6
+
7
+ <details>
8
+ <summary><strong>Table Definition</strong></summary>
9
+
10
+ ```sql
11
+ CREATE VIEW ontology_structure AS (
12
+ SELECT split_part(tag, ':'::text, 1) AS root_topic,
13
+ split_part(tag, ':'::text, 2) AS level1_topic,
14
+ split_part(tag, ':'::text, 3) AS level2_topic,
15
+ tag AS full_path,
16
+ count(DISTINCT node_id) AS node_count
17
+ FROM tags
18
+ WHERE (tag ~ '^[a-z0-9\-]+(:[a-z0-9\-]+)*$'::text)
19
+ GROUP BY tag
20
+ ORDER BY (split_part(tag, ':'::text, 1)), (split_part(tag, ':'::text, 2)), (split_part(tag, ':'::text, 3))
21
+ )
22
+ ```
23
+
24
+ </details>
25
+
26
+ ## Columns
27
+
28
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
29
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
30
+ | root_topic | text | | true | | | |
31
+ | level1_topic | text | | true | | | |
32
+ | level2_topic | text | | true | | | |
33
+ | full_path | text | | true | | | |
34
+ | node_count | bigint | | true | | | |
35
+
36
+ ## Referenced Tables
37
+
38
+ | Name | Columns | Comment | Type |
39
+ | ---- | ------- | ------- | ---- |
40
+ | [public.tags](public.tags.md) | 4 | Hierarchical topic tags for flexible categorization using colon-delimited format | BASE TABLE |
41
+
42
+ ## Relations
43
+
44
+ ![er](public.ontology_structure.svg)
45
+
46
+ ---
47
+
48
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.ontology_structure.svg ADDED
@@ -0,0 +1,38 @@
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.ontology_structure Pages: 1 -->
7
+ <svg width="375pt" height="290pt"
8
+ viewBox="0.00 0.00 374.54 290.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 286)">
10
+ <title>public.ontology_structure</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-286 370.54,-286 370.54,4 -4,4"/>
12
+ <!-- public.ontology_structure -->
13
+ <g id="node1" class="node">
14
+ <title>public.ontology_structure</title>
15
+ <polygon fill="#efefef" stroke="none" points="46.2,-200.2 46.2,-235.8 320.34,-235.8 320.34,-200.2 46.2,-200.2"/>
16
+ <polygon fill="none" stroke="black" points="46.2,-200.2 46.2,-235.8 320.34,-235.8 320.34,-200.2 46.2,-200.2"/>
17
+ <text text-anchor="start" x="53.2" y="-213.6" font-family="Arial Bold" font-size="18.00">public.ontology_structure</text>
18
+ <text text-anchor="start" x="238.67" y="-213.6" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="269.78" y="-213.6" font-family="Arial" font-size="14.00" fill="#666666">[VIEW]</text>
20
+ <polygon fill="none" stroke="black" points="46.2,-169.4 46.2,-200.2 320.34,-200.2 320.34,-169.4 46.2,-169.4"/>
21
+ <text text-anchor="start" x="53.2" y="-181.6" font-family="Arial" font-size="14.00">root_topic </text>
22
+ <text text-anchor="start" x="118.57" y="-181.6" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
23
+ <polygon fill="none" stroke="black" points="46.2,-138.6 46.2,-169.4 320.34,-169.4 320.34,-138.6 46.2,-138.6"/>
24
+ <text text-anchor="start" x="53.2" y="-150.8" font-family="Arial" font-size="14.00">level1_topic </text>
25
+ <text text-anchor="start" x="131.03" y="-150.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
26
+ <polygon fill="none" stroke="black" points="46.2,-107.8 46.2,-138.6 320.34,-138.6 320.34,-107.8 46.2,-107.8"/>
27
+ <text text-anchor="start" x="53.2" y="-120" font-family="Arial" font-size="14.00">level2_topic </text>
28
+ <text text-anchor="start" x="131.03" y="-120" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
29
+ <polygon fill="none" stroke="black" points="46.2,-77 46.2,-107.8 320.34,-107.8 320.34,-77 46.2,-77"/>
30
+ <text text-anchor="start" x="53.2" y="-89.2" font-family="Arial" font-size="14.00">full_path </text>
31
+ <text text-anchor="start" x="110.02" y="-89.2" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
32
+ <polygon fill="none" stroke="black" points="46.2,-46.2 46.2,-77 320.34,-77 320.34,-46.2 46.2,-46.2"/>
33
+ <text text-anchor="start" x="53.2" y="-58.4" font-family="Arial" font-size="14.00">node_count </text>
34
+ <text text-anchor="start" x="130.27" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
35
+ <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-44.7 44.7,-237.3 321.84,-237.3 321.84,-44.7 44.7,-44.7"/>
36
+ </g>
37
+ </g>
38
+ </svg>
data/dbdoc/public.operations_log.md ADDED
@@ -0,0 +1,42 @@
1
+ # public.operations_log
2
+
3
+ ## Description
4
+
5
+ Audit trail of all HTM operations for debugging and replay
6
+
7
+ ## Columns
8
+
9
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
10
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
11
+ | id | bigint | nextval('operations_log_id_seq'::regclass) | false | | | |
12
+ | timestamp | timestamp with time zone | CURRENT_TIMESTAMP | true | | | When this operation occurred |
13
+ | operation | text | | false | | | Operation type: add, retrieve, remove, evict, recall |
14
+ | node_id | bigint | | true | | [public.nodes](public.nodes.md) | ID of the node affected by this operation (if applicable) |
15
+ | robot_id | text | | false | | [public.robots](public.robots.md) | ID of the robot that performed this operation |
16
+ | details | jsonb | | true | | | Additional operation details and context |
17
+
18
+ ## Constraints
19
+
20
+ | Name | Type | Definition |
21
+ | ---- | ---- | ---------- |
22
+ | fk_rails_8df7440180 | FOREIGN KEY | FOREIGN KEY (robot_id) REFERENCES robots(id) ON DELETE CASCADE |
23
+ | fk_rails_f1b5294e6b | FOREIGN KEY | FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE |
24
+ | operations_log_pkey | PRIMARY KEY | PRIMARY KEY (id) |
25
+
26
+ ## Indexes
27
+
28
+ | Name | Definition |
29
+ | ---- | ---------- |
30
+ | operations_log_pkey | CREATE UNIQUE INDEX operations_log_pkey ON public.operations_log USING btree (id) |
31
+ | idx_operations_log_timestamp | CREATE INDEX idx_operations_log_timestamp ON public.operations_log USING btree ("timestamp") |
32
+ | idx_operations_log_robot_id | CREATE INDEX idx_operations_log_robot_id ON public.operations_log USING btree (robot_id) |
33
+ | idx_operations_log_node_id | CREATE INDEX idx_operations_log_node_id ON public.operations_log USING btree (node_id) |
34
+ | idx_operations_log_operation | CREATE INDEX idx_operations_log_operation ON public.operations_log USING btree (operation) |
35
+
36
+ ## Relations
37
+
38
+ ![er](public.operations_log.svg)
39
+
40
+ ---
41
+
42
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.operations_log.svg ADDED
@@ -0,0 +1,130 @@
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.operations_log Pages: 1 -->
7
+ <svg width="1013pt" height="910pt"
8
+ viewBox="0.00 0.00 1013.15 910.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 906)">
10
+ <title>public.operations_log</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-906 1009.15,-906 1009.15,4 -4,4"/>
12
+ <!-- public.operations_log -->
13
+ <g id="node1" class="node">
14
+ <title>public.operations_log</title>
15
+ <polygon fill="#efefef" stroke="none" points="354.55,-820.2 354.55,-855.8 649.51,-855.8 649.51,-820.2 354.55,-820.2"/>
16
+ <polygon fill="none" stroke="black" points="354.55,-820.2 354.55,-855.8 649.51,-855.8 649.51,-820.2 354.55,-820.2"/>
17
+ <text text-anchor="start" x="361.55" y="-833.6" font-family="Arial Bold" font-size="18.00">public.operations_log</text>
18
+ <text text-anchor="start" x="518.02" y="-833.6" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="549.13" y="-833.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="354.55,-789.4 354.55,-820.2 649.51,-820.2 649.51,-789.4 354.55,-789.4"/>
21
+ <text text-anchor="start" x="361.55" y="-801.6" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="376.33" y="-801.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="354.55,-758.6 354.55,-789.4 649.51,-789.4 649.51,-758.6 354.55,-758.6"/>
24
+ <text text-anchor="start" x="361.55" y="-770.8" font-family="Arial" font-size="14.00">timestamp </text>
25
+ <text text-anchor="start" x="430.01" y="-770.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
26
+ <polygon fill="none" stroke="black" points="354.55,-727.8 354.55,-758.6 649.51,-758.6 649.51,-727.8 354.55,-727.8"/>
27
+ <text text-anchor="start" x="361.55" y="-740" font-family="Arial" font-size="14.00">operation </text>
28
+ <text text-anchor="start" x="423.81" y="-740" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
29
+ <polygon fill="none" stroke="black" points="354.55,-697 354.55,-727.8 649.51,-727.8 649.51,-697 354.55,-697"/>
30
+ <text text-anchor="start" x="361.55" y="-709.2" font-family="Arial" font-size="14.00">node_id </text>
31
+ <text text-anchor="start" x="415.26" y="-709.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
32
+ <polygon fill="none" stroke="black" points="354.55,-666.2 354.55,-697 649.51,-697 649.51,-666.2 354.55,-666.2"/>
33
+ <text text-anchor="start" x="361.55" y="-678.4" font-family="Arial" font-size="14.00">robot_id </text>
34
+ <text text-anchor="start" x="416.03" y="-678.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
35
+ <polygon fill="none" stroke="black" points="354.55,-635.4 354.55,-666.2 649.51,-666.2 649.51,-635.4 354.55,-635.4"/>
36
+ <text text-anchor="start" x="361.55" y="-647.6" font-family="Arial" font-size="14.00">details </text>
37
+ <text text-anchor="start" x="405.9" y="-647.6" font-family="Arial" font-size="14.00" fill="#666666">[jsonb]</text>
38
+ <polygon fill="none" stroke="black" stroke-width="3" points="353.05,-633.9 353.05,-857.3 651.01,-857.3 651.01,-633.9 353.05,-633.9"/>
39
+ </g>
40
+ <!-- public.nodes -->
41
+ <g id="node2" class="node">
42
+ <title>public.nodes</title>
43
+ <polygon fill="#efefef" stroke="none" points="183.86,-474.4 183.86,-510 456.19,-510 456.19,-474.4 183.86,-474.4"/>
44
+ <polygon fill="none" stroke="black" points="183.86,-474.4 183.86,-510 456.19,-510 456.19,-474.4 183.86,-474.4"/>
45
+ <text text-anchor="start" x="212.04" y="-487.8" font-family="Arial Bold" font-size="18.00">public.nodes</text>
46
+ <text text-anchor="start" x="303.52" y="-487.8" font-family="Arial" font-size="14.00">    </text>
47
+ <text text-anchor="start" x="334.64" y="-487.8" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
48
+ <polygon fill="none" stroke="black" points="183.86,-443.6 183.86,-474.4 456.19,-474.4 456.19,-443.6 183.86,-443.6"/>
49
+ <text text-anchor="start" x="190.86" y="-455.8" font-family="Arial" font-size="14.00">id </text>
50
+ <text text-anchor="start" x="205.65" y="-455.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
51
+ <polygon fill="none" stroke="black" points="183.86,-412.8 183.86,-443.6 456.19,-443.6 456.19,-412.8 183.86,-412.8"/>
52
+ <text text-anchor="start" x="190.86" y="-425" font-family="Arial" font-size="14.00">content </text>
53
+ <text text-anchor="start" x="240.67" y="-425" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
54
+ <polygon fill="none" stroke="black" points="183.86,-382 183.86,-412.8 456.19,-412.8 456.19,-382 183.86,-382"/>
55
+ <text text-anchor="start" x="190.86" y="-394.2" font-family="Arial" font-size="14.00">speaker </text>
56
+ <text text-anchor="start" x="244.56" y="-394.2" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
57
+ <polygon fill="none" stroke="black" points="183.86,-351.2 183.86,-382 456.19,-382 456.19,-351.2 183.86,-351.2"/>
58
+ <text text-anchor="start" x="190.86" y="-363.4" font-family="Arial" font-size="14.00">type </text>
59
+ <text text-anchor="start" x="221.21" y="-363.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
60
+ <polygon fill="none" stroke="black" points="183.86,-320.4 183.86,-351.2 456.19,-351.2 456.19,-320.4 183.86,-320.4"/>
61
+ <text text-anchor="start" x="190.86" y="-332.6" font-family="Arial" font-size="14.00">category </text>
62
+ <text text-anchor="start" x="248.45" y="-332.6" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
63
+ <polygon fill="none" stroke="black" points="183.86,-289.6 183.86,-320.4 456.19,-320.4 456.19,-289.6 183.86,-289.6"/>
64
+ <text text-anchor="start" x="190.86" y="-301.8" font-family="Arial" font-size="14.00">importance </text>
65
+ <text text-anchor="start" x="264.01" y="-301.8" font-family="Arial" font-size="14.00" fill="#666666">[double precision]</text>
66
+ <polygon fill="none" stroke="black" points="183.86,-258.8 183.86,-289.6 456.19,-289.6 456.19,-258.8 183.86,-258.8"/>
67
+ <text text-anchor="start" x="190.86" y="-271" font-family="Arial" font-size="14.00">created_at </text>
68
+ <text text-anchor="start" x="260.91" y="-271" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
69
+ <polygon fill="none" stroke="black" points="183.86,-228 183.86,-258.8 456.19,-258.8 456.19,-228 183.86,-228"/>
70
+ <text text-anchor="start" x="190.86" y="-240.2" font-family="Arial" font-size="14.00">updated_at </text>
71
+ <text text-anchor="start" x="264.82" y="-240.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
72
+ <polygon fill="none" stroke="black" points="183.86,-197.2 183.86,-228 456.19,-228 456.19,-197.2 183.86,-197.2"/>
73
+ <text text-anchor="start" x="190.86" y="-209.4" font-family="Arial" font-size="14.00">last_accessed </text>
74
+ <text text-anchor="start" x="283.47" y="-209.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
75
+ <polygon fill="none" stroke="black" points="183.86,-166.4 183.86,-197.2 456.19,-197.2 456.19,-166.4 183.86,-166.4"/>
76
+ <text text-anchor="start" x="190.86" y="-178.6" font-family="Arial" font-size="14.00">token_count </text>
77
+ <text text-anchor="start" x="271.03" y="-178.6" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
78
+ <polygon fill="none" stroke="black" points="183.86,-135.6 183.86,-166.4 456.19,-166.4 456.19,-135.6 183.86,-135.6"/>
79
+ <text text-anchor="start" x="190.86" y="-147.8" font-family="Arial" font-size="14.00">in_working_memory </text>
80
+ <text text-anchor="start" x="320.02" y="-147.8" font-family="Arial" font-size="14.00" fill="#666666">[boolean]</text>
81
+ <polygon fill="none" stroke="black" points="183.86,-104.8 183.86,-135.6 456.19,-135.6 456.19,-104.8 183.86,-104.8"/>
82
+ <text text-anchor="start" x="190.86" y="-117" font-family="Arial" font-size="14.00">robot_id </text>
83
+ <text text-anchor="start" x="245.34" y="-117" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
84
+ <polygon fill="none" stroke="black" points="183.86,-74 183.86,-104.8 456.19,-104.8 456.19,-74 183.86,-74"/>
85
+ <text text-anchor="start" x="190.86" y="-86.2" font-family="Arial" font-size="14.00">embedding </text>
86
+ <text text-anchor="start" x="264.03" y="-86.2" font-family="Arial" font-size="14.00" fill="#666666">[vector(2000)]</text>
87
+ <polygon fill="none" stroke="black" points="183.86,-43.2 183.86,-74 456.19,-74 456.19,-43.2 183.86,-43.2"/>
88
+ <text text-anchor="start" x="190.86" y="-55.4" font-family="Arial" font-size="14.00">embedding_dimension </text>
89
+ <text text-anchor="start" x="335.63" y="-55.4" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
90
+ </g>
91
+ <!-- public.operations_log&#45;&gt;public.nodes -->
92
+ <g id="edge1" class="edge">
93
+ <title>public.operations_log:node_id&#45;&gt;public.nodes:id</title>
94
+ <path fill="none" stroke="black" d="M343.4,-711.33C302.1,-701.81 324.94,-630.74 354.55,-589.2 382.36,-550.17 428.33,-592.19 456.19,-553.2 480.54,-519.14 499.06,-459 457.19,-459"/>
95
+ <polygon fill="black" stroke="black" points="343.27,-711.32 352.74,-716.84 348.57,-711.88 352.88,-712.33 352.88,-712.33 352.88,-712.33 348.57,-711.88 353.68,-707.89 343.27,-711.32"/>
96
+ <text text-anchor="start" x="7" y="-722.4" font-family="Arial" font-size="10.00">FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE</text>
97
+ </g>
98
+ <!-- public.robots -->
99
+ <g id="node3" class="node">
100
+ <title>public.robots</title>
101
+ <polygon fill="#efefef" stroke="none" points="560.14,-335.8 560.14,-371.4 809.91,-371.4 809.91,-335.8 560.14,-335.8"/>
102
+ <polygon fill="none" stroke="black" points="560.14,-335.8 560.14,-371.4 809.91,-371.4 809.91,-335.8 560.14,-335.8"/>
103
+ <text text-anchor="start" x="575.54" y="-349.2" font-family="Arial Bold" font-size="18.00">public.robots</text>
104
+ <text text-anchor="start" x="670.03" y="-349.2" font-family="Arial" font-size="14.00">    </text>
105
+ <text text-anchor="start" x="701.14" y="-349.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
106
+ <polygon fill="none" stroke="black" points="560.14,-305 560.14,-335.8 809.91,-335.8 809.91,-305 560.14,-305"/>
107
+ <text text-anchor="start" x="567.14" y="-317.2" font-family="Arial" font-size="14.00">id </text>
108
+ <text text-anchor="start" x="581.93" y="-317.2" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
109
+ <polygon fill="none" stroke="black" points="560.14,-274.2 560.14,-305 809.91,-305 809.91,-274.2 560.14,-274.2"/>
110
+ <text text-anchor="start" x="567.14" y="-286.4" font-family="Arial" font-size="14.00">name </text>
111
+ <text text-anchor="start" x="606.05" y="-286.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
112
+ <polygon fill="none" stroke="black" points="560.14,-243.4 560.14,-274.2 809.91,-274.2 809.91,-243.4 560.14,-243.4"/>
113
+ <text text-anchor="start" x="567.14" y="-255.6" font-family="Arial" font-size="14.00">created_at </text>
114
+ <text text-anchor="start" x="637.19" y="-255.6" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
115
+ <polygon fill="none" stroke="black" points="560.14,-212.6 560.14,-243.4 809.91,-243.4 809.91,-212.6 560.14,-212.6"/>
116
+ <text text-anchor="start" x="567.14" y="-224.8" font-family="Arial" font-size="14.00">last_active </text>
117
+ <text text-anchor="start" x="637.17" y="-224.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
118
+ <polygon fill="none" stroke="black" points="560.14,-181.8 560.14,-212.6 809.91,-212.6 809.91,-181.8 560.14,-181.8"/>
119
+ <text text-anchor="start" x="567.14" y="-194" font-family="Arial" font-size="14.00">metadata </text>
120
+ <text text-anchor="start" x="629.4" y="-194" font-family="Arial" font-size="14.00" fill="#666666">[jsonb]</text>
121
+ </g>
122
+ <!-- public.operations_log&#45;&gt;public.robots -->
123
+ <g id="edge2" class="edge">
124
+ <title>public.operations_log:robot_id&#45;&gt;public.robots:id</title>
125
+ <path fill="none" stroke="black" d="M660.79,-681.06C797.41,-665.56 397.27,-320.4 559.14,-320.4"/>
126
+ <polygon fill="black" stroke="black" points="660.83,-681.06 650.61,-677.09 655.5,-681.34 651.17,-681.57 651.17,-681.57 651.17,-681.57 655.5,-681.34 651.08,-686.08 660.83,-681.06"/>
127
+ <text text-anchor="start" x="657.51" y="-691.6" font-family="Arial" font-size="10.00">FOREIGN KEY (robot_id) REFERENCES robots(id) ON DELETE CASCADE</text>
128
+ </g>
129
+ </g>
130
+ </svg>
data/dbdoc/public.relationships.md ADDED
@@ -0,0 +1,39 @@
1
+ # public.relationships
2
+
3
+ ## Description
4
+
5
+ Knowledge graph edges connecting related nodes
6
+
7
+ ## Columns
8
+
9
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
10
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
11
+ | id | bigint | nextval('relationships_id_seq'::regclass) | false | | | |
12
+ | from_node_id | bigint | | false | | | Source node ID |
13
+ | to_node_id | bigint | | false | | | Target node ID |
14
+ | relationship_type | text | | true | | | Type of relationship: relates_to, caused_by, follows, etc. |
15
+ | strength | double precision | 1.0 | true | | | Relationship strength/weight (0.0-1.0) |
16
+ | created_at | timestamp with time zone | CURRENT_TIMESTAMP | true | | | When this relationship was created |
17
+
18
+ ## Constraints
19
+
20
+ | Name | Type | Definition |
21
+ | ---- | ---- | ---------- |
22
+ | relationships_pkey | PRIMARY KEY | PRIMARY KEY (id) |
23
+
24
+ ## Indexes
25
+
26
+ | Name | Definition |
27
+ | ---- | ---------- |
28
+ | relationships_pkey | CREATE UNIQUE INDEX relationships_pkey ON public.relationships USING btree (id) |
29
+ | idx_relationships_unique | CREATE UNIQUE INDEX idx_relationships_unique ON public.relationships USING btree (from_node_id, to_node_id, relationship_type) |
30
+ | idx_relationships_from | CREATE INDEX idx_relationships_from ON public.relationships USING btree (from_node_id) |
31
+ | idx_relationships_to | CREATE INDEX idx_relationships_to ON public.relationships USING btree (to_node_id) |
32
+
33
+ ## Relations
34
+
35
+ ![er](public.relationships.svg)
36
+
37
+ ---
38
+
39
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.relationships.svg ADDED
@@ -0,0 +1,41 @@
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.relationships Pages: 1 -->
7
+ <svg width="380pt" height="321pt"
8
+ viewBox="0.00 0.00 380.37 320.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 316.8)">
10
+ <title>public.relationships</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-316.8 376.37,-316.8 376.37,4 -4,4"/>
12
+ <!-- public.relationships -->
13
+ <g id="node1" class="node">
14
+ <title>public.relationships</title>
15
+ <polygon fill="#efefef" stroke="none" points="46.2,-231 46.2,-266.6 326.17,-266.6 326.17,-231 46.2,-231"/>
16
+ <polygon fill="none" stroke="black" points="46.2,-231 46.2,-266.6 326.17,-266.6 326.17,-231 46.2,-231"/>
17
+ <text text-anchor="start" x="53.2" y="-244.4" font-family="Arial Bold" font-size="18.00">public.relationships</text>
18
+ <text text-anchor="start" x="194.68" y="-244.4" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="225.79" y="-244.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="46.2,-200.2 46.2,-231 326.17,-231 326.17,-200.2 46.2,-200.2"/>
21
+ <text text-anchor="start" x="53.2" y="-212.4" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="67.99" y="-212.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="46.2,-169.4 46.2,-200.2 326.17,-200.2 326.17,-169.4 46.2,-169.4"/>
24
+ <text text-anchor="start" x="53.2" y="-181.6" font-family="Arial" font-size="14.00">from_node_id </text>
25
+ <text text-anchor="start" x="142.7" y="-181.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
26
+ <polygon fill="none" stroke="black" points="46.2,-138.6 46.2,-169.4 326.17,-169.4 326.17,-138.6 46.2,-138.6"/>
27
+ <text text-anchor="start" x="53.2" y="-150.8" font-family="Arial" font-size="14.00">to_node_id </text>
28
+ <text text-anchor="start" x="126.38" y="-150.8" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
29
+ <polygon fill="none" stroke="black" points="46.2,-107.8 46.2,-138.6 326.17,-138.6 326.17,-107.8 46.2,-107.8"/>
30
+ <text text-anchor="start" x="53.2" y="-120" font-family="Arial" font-size="14.00">relationship_type </text>
31
+ <text text-anchor="start" x="162.94" y="-120" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
32
+ <polygon fill="none" stroke="black" points="46.2,-77 46.2,-107.8 326.17,-107.8 326.17,-77 46.2,-77"/>
33
+ <text text-anchor="start" x="53.2" y="-89.2" font-family="Arial" font-size="14.00">strength </text>
34
+ <text text-anchor="start" x="107.68" y="-89.2" font-family="Arial" font-size="14.00" fill="#666666">[double precision]</text>
35
+ <polygon fill="none" stroke="black" points="46.2,-46.2 46.2,-77 326.17,-77 326.17,-46.2 46.2,-46.2"/>
36
+ <text text-anchor="start" x="53.2" y="-58.4" font-family="Arial" font-size="14.00">created_at </text>
37
+ <text text-anchor="start" x="123.25" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
38
+ <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-44.7 44.7,-268.1 327.67,-268.1 327.67,-44.7 44.7,-44.7"/>
39
+ </g>
40
+ </g>
41
+ </svg>
data/dbdoc/public.robot_activity.md ADDED
@@ -0,0 +1,46 @@
1
+ # public.robot_activity
2
+
3
+ ## Description
4
+
5
+ Robot usage metrics showing total nodes created and last activity timestamp.
6
+
7
+ <details>
8
+ <summary><strong>Table Definition</strong></summary>
9
+
10
+ ```sql
11
+ CREATE VIEW robot_activity AS (
12
+ SELECT r.id,
13
+ r.name,
14
+ count(n.id) AS total_nodes,
15
+ max(n.created_at) AS last_node_created
16
+ FROM (robots r
17
+ LEFT JOIN nodes n ON ((n.robot_id = r.id)))
18
+ GROUP BY r.id, r.name
19
+ )
20
+ ```
21
+
22
+ </details>
23
+
24
+ ## Columns
25
+
26
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
27
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
28
+ | id | text | | true | | | |
29
+ | name | text | | true | | | |
30
+ | total_nodes | bigint | | true | | | |
31
+ | last_node_created | timestamp with time zone | | true | | | |
32
+
33
+ ## Referenced Tables
34
+
35
+ | Name | Columns | Comment | Type |
36
+ | ---- | ------- | ------- | ---- |
37
+ | [public.robots](public.robots.md) | 5 | Registry of all LLM robots using the HTM system | BASE TABLE |
38
+ | [public.nodes](public.nodes.md) | 14 | Core memory storage for conversation messages and context | BASE TABLE |
39
+
40
+ ## Relations
41
+
42
+ ![er](public.robot_activity.svg)
43
+
44
+ ---
45
+
46
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.robot_activity.svg ADDED
@@ -0,0 +1,35 @@
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.robot_activity Pages: 1 -->
7
+ <svg width="399pt" height="259pt"
8
+ viewBox="0.00 0.00 399.21 259.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 255.2)">
10
+ <title>public.robot_activity</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-255.2 395.21,-255.2 395.21,4 -4,4"/>
12
+ <!-- public.robot_activity -->
13
+ <g id="node1" class="node">
14
+ <title>public.robot_activity</title>
15
+ <polygon fill="#efefef" stroke="none" points="46.2,-169.4 46.2,-205 345.01,-205 345.01,-169.4 46.2,-169.4"/>
16
+ <polygon fill="none" stroke="black" points="46.2,-169.4 46.2,-205 345.01,-205 345.01,-169.4 46.2,-169.4"/>
17
+ <text text-anchor="start" x="83.03" y="-182.8" font-family="Arial Bold" font-size="18.00">public.robot_activity</text>
18
+ <text text-anchor="start" x="233.5" y="-182.8" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="264.62" y="-182.8" font-family="Arial" font-size="14.00" fill="#666666">[VIEW]</text>
20
+ <polygon fill="none" stroke="black" points="46.2,-138.6 46.2,-169.4 345.01,-169.4 345.01,-138.6 46.2,-138.6"/>
21
+ <text text-anchor="start" x="53.2" y="-150.8" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="67.99" y="-150.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
23
+ <polygon fill="none" stroke="black" points="46.2,-107.8 46.2,-138.6 345.01,-138.6 345.01,-107.8 46.2,-107.8"/>
24
+ <text text-anchor="start" x="53.2" y="-120" font-family="Arial" font-size="14.00">name </text>
25
+ <text text-anchor="start" x="92.11" y="-120" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
26
+ <polygon fill="none" stroke="black" points="46.2,-77 46.2,-107.8 345.01,-107.8 345.01,-77 46.2,-77"/>
27
+ <text text-anchor="start" x="53.2" y="-89.2" font-family="Arial" font-size="14.00">total_nodes </text>
28
+ <text text-anchor="start" x="129.48" y="-89.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
29
+ <polygon fill="none" stroke="black" points="46.2,-46.2 46.2,-77 345.01,-77 345.01,-46.2 46.2,-46.2"/>
30
+ <text text-anchor="start" x="53.2" y="-58.4" font-family="Arial" font-size="14.00">last_node_created </text>
31
+ <text text-anchor="start" x="172.29" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
32
+ <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-44.7 44.7,-206.5 346.51,-206.5 346.51,-44.7 44.7,-44.7"/>
33
+ </g>
34
+ </g>
35
+ </svg>