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.robots.md ADDED
@@ -0,0 +1,35 @@
1
+ # public.robots
2
+
3
+ ## Description
4
+
5
+ Registry of all LLM robots using the HTM system
6
+
7
+ ## Columns
8
+
9
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
10
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
11
+ | id | bigint | nextval('robots_id_seq'::regclass) | false | [public.nodes](public.nodes.md) | | |
12
+ | name | text | | true | | | Human-readable name for the robot |
13
+ | created_at | timestamp with time zone | CURRENT_TIMESTAMP | true | | | When the robot was first registered |
14
+ | last_active | timestamp with time zone | CURRENT_TIMESTAMP | true | | | Last time the robot accessed the system |
15
+ | metadata | jsonb | | true | | | Robot-specific configuration and metadata |
16
+
17
+ ## Constraints
18
+
19
+ | Name | Type | Definition |
20
+ | ---- | ---- | ---------- |
21
+ | robots_pkey | PRIMARY KEY | PRIMARY KEY (id) |
22
+
23
+ ## Indexes
24
+
25
+ | Name | Definition |
26
+ | ---- | ---------- |
27
+ | robots_pkey | CREATE UNIQUE INDEX robots_pkey ON public.robots USING btree (id) |
28
+
29
+ ## Relations
30
+
31
+ ![er](public.robots.svg)
32
+
33
+ ---
34
+
35
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.robots.svg ADDED
@@ -0,0 +1,90 @@
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.robots Pages: 1 -->
7
+ <svg width="679pt" height="818pt"
8
+ viewBox="0.00 0.00 679.17 817.60" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
9
+ <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 813.6)">
10
+ <title>public.robots</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-813.6 675.17,-813.6 675.17,4 -4,4"/>
12
+ <!-- public.robots -->
13
+ <g id="node1" class="node">
14
+ <title>public.robots</title>
15
+ <polygon fill="#efefef" stroke="none" points="54.48,-200.2 54.48,-235.8 304.25,-235.8 304.25,-200.2 54.48,-200.2"/>
16
+ <polygon fill="none" stroke="black" points="54.48,-200.2 54.48,-235.8 304.25,-235.8 304.25,-200.2 54.48,-200.2"/>
17
+ <text text-anchor="start" x="69.87" y="-213.6" font-family="Arial Bold" font-size="18.00">public.robots</text>
18
+ <text text-anchor="start" x="164.37" y="-213.6" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="195.48" y="-213.6" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="54.48,-169.4 54.48,-200.2 304.25,-200.2 304.25,-169.4 54.48,-169.4"/>
21
+ <text text-anchor="start" x="61.48" y="-181.6" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="76.27" y="-181.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="54.48,-138.6 54.48,-169.4 304.25,-169.4 304.25,-138.6 54.48,-138.6"/>
24
+ <text text-anchor="start" x="61.48" y="-150.8" font-family="Arial" font-size="14.00">name </text>
25
+ <text text-anchor="start" x="100.39" y="-150.8" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
26
+ <polygon fill="none" stroke="black" points="54.48,-107.8 54.48,-138.6 304.25,-138.6 304.25,-107.8 54.48,-107.8"/>
27
+ <text text-anchor="start" x="61.48" y="-120" font-family="Arial" font-size="14.00">created_at </text>
28
+ <text text-anchor="start" x="131.53" y="-120" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
29
+ <polygon fill="none" stroke="black" points="54.48,-77 54.48,-107.8 304.25,-107.8 304.25,-77 54.48,-77"/>
30
+ <text text-anchor="start" x="61.48" y="-89.2" font-family="Arial" font-size="14.00">last_active </text>
31
+ <text text-anchor="start" x="131.51" y="-89.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
32
+ <polygon fill="none" stroke="black" points="54.48,-46.2 54.48,-77 304.25,-77 304.25,-46.2 54.48,-46.2"/>
33
+ <text text-anchor="start" x="61.48" y="-58.4" font-family="Arial" font-size="14.00">metadata </text>
34
+ <text text-anchor="start" x="123.74" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[jsonb]</text>
35
+ <polygon fill="none" stroke="black" stroke-width="3" points="52.98,-44.7 52.98,-237.3 305.75,-237.3 305.75,-44.7 52.98,-44.7"/>
36
+ </g>
37
+ <!-- public.nodes -->
38
+ <g id="node2" class="node">
39
+ <title>public.nodes</title>
40
+ <polygon fill="#efefef" stroke="none" points="43.2,-730.8 43.2,-766.4 315.53,-766.4 315.53,-730.8 43.2,-730.8"/>
41
+ <polygon fill="none" stroke="black" points="43.2,-730.8 43.2,-766.4 315.53,-766.4 315.53,-730.8 43.2,-730.8"/>
42
+ <text text-anchor="start" x="71.38" y="-744.2" font-family="Arial Bold" font-size="18.00">public.nodes</text>
43
+ <text text-anchor="start" x="162.86" y="-744.2" font-family="Arial" font-size="14.00">    </text>
44
+ <text text-anchor="start" x="193.98" y="-744.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
45
+ <polygon fill="none" stroke="black" points="43.2,-700 43.2,-730.8 315.53,-730.8 315.53,-700 43.2,-700"/>
46
+ <text text-anchor="start" x="50.2" y="-712.2" font-family="Arial" font-size="14.00">id </text>
47
+ <text text-anchor="start" x="64.99" y="-712.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
48
+ <polygon fill="none" stroke="black" points="43.2,-669.2 43.2,-700 315.53,-700 315.53,-669.2 43.2,-669.2"/>
49
+ <text text-anchor="start" x="50.2" y="-681.4" font-family="Arial" font-size="14.00">content </text>
50
+ <text text-anchor="start" x="100.01" y="-681.4" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
51
+ <polygon fill="none" stroke="black" points="43.2,-638.4 43.2,-669.2 315.53,-669.2 315.53,-638.4 43.2,-638.4"/>
52
+ <text text-anchor="start" x="50.2" y="-650.6" font-family="Arial" font-size="14.00">source </text>
53
+ <text text-anchor="start" x="96.11" y="-650.6" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
54
+ <polygon fill="none" stroke="black" points="43.2,-607.6 43.2,-638.4 315.53,-638.4 315.53,-607.6 43.2,-607.6"/>
55
+ <text text-anchor="start" x="50.2" y="-619.8" font-family="Arial" font-size="14.00">access_count </text>
56
+ <text text-anchor="start" x="139.7" y="-619.8" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
57
+ <polygon fill="none" stroke="black" points="43.2,-576.8 43.2,-607.6 315.53,-607.6 315.53,-576.8 43.2,-576.8"/>
58
+ <text text-anchor="start" x="50.2" y="-589" font-family="Arial" font-size="14.00">created_at </text>
59
+ <text text-anchor="start" x="120.25" y="-589" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
60
+ <polygon fill="none" stroke="black" points="43.2,-546 43.2,-576.8 315.53,-576.8 315.53,-546 43.2,-546"/>
61
+ <text text-anchor="start" x="50.2" y="-558.2" font-family="Arial" font-size="14.00">updated_at </text>
62
+ <text text-anchor="start" x="124.16" y="-558.2" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
63
+ <polygon fill="none" stroke="black" points="43.2,-515.2 43.2,-546 315.53,-546 315.53,-515.2 43.2,-515.2"/>
64
+ <text text-anchor="start" x="50.2" y="-527.4" font-family="Arial" font-size="14.00">last_accessed </text>
65
+ <text text-anchor="start" x="142.81" y="-527.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
66
+ <polygon fill="none" stroke="black" points="43.2,-484.4 43.2,-515.2 315.53,-515.2 315.53,-484.4 43.2,-484.4"/>
67
+ <text text-anchor="start" x="50.2" y="-496.6" font-family="Arial" font-size="14.00">token_count </text>
68
+ <text text-anchor="start" x="130.37" y="-496.6" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
69
+ <polygon fill="none" stroke="black" points="43.2,-453.6 43.2,-484.4 315.53,-484.4 315.53,-453.6 43.2,-453.6"/>
70
+ <text text-anchor="start" x="50.2" y="-465.8" font-family="Arial" font-size="14.00">in_working_memory </text>
71
+ <text text-anchor="start" x="179.36" y="-465.8" font-family="Arial" font-size="14.00" fill="#666666">[boolean]</text>
72
+ <polygon fill="none" stroke="black" points="43.2,-422.8 43.2,-453.6 315.53,-453.6 315.53,-422.8 43.2,-422.8"/>
73
+ <text text-anchor="start" x="50.2" y="-435" font-family="Arial" font-size="14.00">robot_id </text>
74
+ <text text-anchor="start" x="104.68" y="-435" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
75
+ <polygon fill="none" stroke="black" points="43.2,-392 43.2,-422.8 315.53,-422.8 315.53,-392 43.2,-392"/>
76
+ <text text-anchor="start" x="50.2" y="-404.2" font-family="Arial" font-size="14.00">embedding </text>
77
+ <text text-anchor="start" x="123.37" y="-404.2" font-family="Arial" font-size="14.00" fill="#666666">[vector(2000)]</text>
78
+ <polygon fill="none" stroke="black" points="43.2,-361.2 43.2,-392 315.53,-392 315.53,-361.2 43.2,-361.2"/>
79
+ <text text-anchor="start" x="50.2" y="-373.4" font-family="Arial" font-size="14.00">embedding_dimension </text>
80
+ <text text-anchor="start" x="194.96" y="-373.4" font-family="Arial" font-size="14.00" fill="#666666">[integer]</text>
81
+ </g>
82
+ <!-- public.nodes&#45;&gt;public.robots -->
83
+ <g id="edge1" class="edge">
84
+ <title>public.nodes:robot_id&#45;&gt;public.robots:id</title>
85
+ <path fill="none" stroke="black" d="M326.31,-435.35C371.31,-407.51 358.09,-184.8 305.25,-184.8"/>
86
+ <polygon fill="black" stroke="black" points="326.45,-435.31 315.59,-433.79 321.33,-436.8 317.17,-438.01 317.17,-438.01 317.17,-438.01 321.33,-436.8 318.11,-442.43 326.45,-435.31"/>
87
+ <text text-anchor="start" x="323.53" y="-448.2" font-family="Arial" font-size="10.00">FOREIGN KEY (robot_id) REFERENCES robots(id) ON DELETE CASCADE</text>
88
+ </g>
89
+ </g>
90
+ </svg>
data/dbdoc/public.schema_migrations.md ADDED
@@ -0,0 +1,29 @@
1
+ # public.schema_migrations
2
+
3
+ ## Description
4
+
5
+ ## Columns
6
+
7
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
8
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
9
+ | version | varchar | | false | | | |
10
+
11
+ ## Constraints
12
+
13
+ | Name | Type | Definition |
14
+ | ---- | ---- | ---------- |
15
+ | schema_migrations_pkey | PRIMARY KEY | PRIMARY KEY (version) |
16
+
17
+ ## Indexes
18
+
19
+ | Name | Definition |
20
+ | ---- | ---------- |
21
+ | schema_migrations_pkey | CREATE UNIQUE INDEX schema_migrations_pkey ON public.schema_migrations USING btree (version) |
22
+
23
+ ## Relations
24
+
25
+ ![er](public.schema_migrations.svg)
26
+
27
+ ---
28
+
29
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.schema_migrations.svg ADDED
@@ -0,0 +1,26 @@
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.schema_migrations Pages: 1 -->
7
+ <svg width="428pt" height="167pt"
8
+ viewBox="0.00 0.00 428.35 166.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 162.8)">
10
+ <title>public.schema_migrations</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-162.8 424.35,-162.8 424.35,4 -4,4"/>
12
+ <!-- public.schema_migrations -->
13
+ <g id="node1" class="node">
14
+ <title>public.schema_migrations</title>
15
+ <polygon fill="#efefef" stroke="none" points="46.2,-77 46.2,-112.6 374.15,-112.6 374.15,-77 46.2,-77"/>
16
+ <polygon fill="none" stroke="black" points="46.2,-77 46.2,-112.6 374.15,-112.6 374.15,-77 46.2,-77"/>
17
+ <text text-anchor="start" x="53.2" y="-90.4" font-family="Arial Bold" font-size="18.00">public.schema_migrations</text>
18
+ <text text-anchor="start" x="242.66" y="-90.4" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="273.77" y="-90.4" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="46.2,-46.2 46.2,-77 374.15,-77 374.15,-46.2 46.2,-46.2"/>
21
+ <text text-anchor="start" x="53.2" y="-58.4" font-family="Arial" font-size="14.00">version </text>
22
+ <text text-anchor="start" x="102.22" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[varchar]</text>
23
+ <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-44.7 44.7,-114.1 375.65,-114.1 375.65,-44.7 44.7,-44.7"/>
24
+ </g>
25
+ </g>
26
+ </svg>
data/dbdoc/public.tags.md ADDED
@@ -0,0 +1,35 @@
1
+ # public.tags
2
+
3
+ ## Description
4
+
5
+ Unique tag names for categorization
6
+
7
+ ## Columns
8
+
9
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
10
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
11
+ | id | bigint | nextval('tags_id_seq'::regclass) | false | [public.node_tags](public.node_tags.md) | | |
12
+ | name | text | | false | | | Hierarchical tag in format: root:level1:level2 (e.g., database:postgresql:timescaledb) |
13
+ | created_at | timestamp with time zone | CURRENT_TIMESTAMP | true | | | When this tag was created |
14
+
15
+ ## Constraints
16
+
17
+ | Name | Type | Definition |
18
+ | ---- | ---- | ---------- |
19
+ | tags_pkey | PRIMARY KEY | PRIMARY KEY (id) |
20
+
21
+ ## Indexes
22
+
23
+ | Name | Definition |
24
+ | ---- | ---------- |
25
+ | tags_pkey | CREATE UNIQUE INDEX tags_pkey ON public.tags USING btree (id) |
26
+ | idx_tags_name_unique | CREATE UNIQUE INDEX idx_tags_name_unique ON public.tags USING btree (name) |
27
+ | idx_tags_name_pattern | CREATE INDEX idx_tags_name_pattern ON public.tags USING btree (name text_pattern_ops) |
28
+
29
+ ## Relations
30
+
31
+ ![er](public.tags.svg)
32
+
33
+ ---
34
+
35
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.tags.svg ADDED
@@ -0,0 +1,60 @@
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.tags Pages: 1 -->
7
+ <svg width="650pt" height="510pt"
8
+ viewBox="0.00 0.00 650.02 509.60" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
9
+ <g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 505.6)">
10
+ <title>public.tags</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-505.6 646.02,-505.6 646.02,4 -4,4"/>
12
+ <!-- public.tags -->
13
+ <g id="node1" class="node">
14
+ <title>public.tags</title>
15
+ <polygon fill="#efefef" stroke="none" points="48.8,-138.6 48.8,-174.2 298.57,-174.2 298.57,-138.6 48.8,-138.6"/>
16
+ <polygon fill="none" stroke="black" points="48.8,-138.6 48.8,-174.2 298.57,-174.2 298.57,-138.6 48.8,-138.6"/>
17
+ <text text-anchor="start" x="72.19" y="-152" font-family="Arial Bold" font-size="18.00">public.tags</text>
18
+ <text text-anchor="start" x="150.68" y="-152" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="181.8" y="-152" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
20
+ <polygon fill="none" stroke="black" points="48.8,-107.8 48.8,-138.6 298.57,-138.6 298.57,-107.8 48.8,-107.8"/>
21
+ <text text-anchor="start" x="55.8" y="-120" font-family="Arial" font-size="14.00">id </text>
22
+ <text text-anchor="start" x="70.58" y="-120" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
23
+ <polygon fill="none" stroke="black" points="48.8,-77 48.8,-107.8 298.57,-107.8 298.57,-77 48.8,-77"/>
24
+ <text text-anchor="start" x="55.8" y="-89.2" font-family="Arial" font-size="14.00">name </text>
25
+ <text text-anchor="start" x="94.71" y="-89.2" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
26
+ <polygon fill="none" stroke="black" points="48.8,-46.2 48.8,-77 298.57,-77 298.57,-46.2 48.8,-46.2"/>
27
+ <text text-anchor="start" x="55.8" y="-58.4" font-family="Arial" font-size="14.00">created_at </text>
28
+ <text text-anchor="start" x="125.84" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
29
+ <polygon fill="none" stroke="black" stroke-width="3" points="47.3,-44.7 47.3,-175.7 300.07,-175.7 300.07,-44.7 47.3,-44.7"/>
30
+ </g>
31
+ <!-- public.node_tags -->
32
+ <g id="node2" class="node">
33
+ <title>public.node_tags</title>
34
+ <polygon fill="#efefef" stroke="none" points="43.2,-422.8 43.2,-458.4 304.16,-458.4 304.16,-422.8 43.2,-422.8"/>
35
+ <polygon fill="none" stroke="black" points="43.2,-422.8 43.2,-458.4 304.16,-458.4 304.16,-422.8 43.2,-422.8"/>
36
+ <text text-anchor="start" x="50.2" y="-436.2" font-family="Arial Bold" font-size="18.00">public.node_tags</text>
37
+ <text text-anchor="start" x="172.68" y="-436.2" font-family="Arial" font-size="14.00">    </text>
38
+ <text text-anchor="start" x="203.79" y="-436.2" font-family="Arial" font-size="14.00" fill="#666666">[BASE TABLE]</text>
39
+ <polygon fill="none" stroke="black" points="43.2,-392 43.2,-422.8 304.16,-422.8 304.16,-392 43.2,-392"/>
40
+ <text text-anchor="start" x="50.2" y="-404.2" font-family="Arial" font-size="14.00">id </text>
41
+ <text text-anchor="start" x="64.99" y="-404.2" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
42
+ <polygon fill="none" stroke="black" points="43.2,-361.2 43.2,-392 304.16,-392 304.16,-361.2 43.2,-361.2"/>
43
+ <text text-anchor="start" x="50.2" y="-373.4" font-family="Arial" font-size="14.00">node_id </text>
44
+ <text text-anchor="start" x="103.92" y="-373.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
45
+ <polygon fill="none" stroke="black" points="43.2,-330.4 43.2,-361.2 304.16,-361.2 304.16,-330.4 43.2,-330.4"/>
46
+ <text text-anchor="start" x="50.2" y="-342.6" font-family="Arial" font-size="14.00">tag_id </text>
47
+ <text text-anchor="start" x="92.23" y="-342.6" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
48
+ <polygon fill="none" stroke="black" points="43.2,-299.6 43.2,-330.4 304.16,-330.4 304.16,-299.6 43.2,-299.6"/>
49
+ <text text-anchor="start" x="50.2" y="-311.8" font-family="Arial" font-size="14.00">created_at </text>
50
+ <text text-anchor="start" x="120.25" y="-311.8" font-family="Arial" font-size="14.00" fill="#666666">[timestamp with time zone]</text>
51
+ </g>
52
+ <!-- public.node_tags&#45;&gt;public.tags -->
53
+ <g id="edge1" class="edge">
54
+ <title>public.node_tags:tag_id&#45;&gt;public.tags:id</title>
55
+ <path fill="none" stroke="black" d="M315.48,-344.95C403.6,-330 394.96,-123.2 299.57,-123.2"/>
56
+ <polygon fill="black" stroke="black" points="315.46,-344.95 305.13,-341.29 310.15,-345.39 305.83,-345.75 305.83,-345.75 305.83,-345.75 310.15,-345.39 305.87,-350.26 315.46,-344.95"/>
57
+ <text text-anchor="start" x="312.16" y="-355.8" font-family="Arial" font-size="10.00">FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE</text>
58
+ </g>
59
+ </g>
60
+ </svg>
data/dbdoc/public.topic_relationships.md ADDED
@@ -0,0 +1,45 @@
1
+ # public.topic_relationships
2
+
3
+ ## Description
4
+
5
+ Shows which topics co-occur on the same nodes, revealing cross-topic relationships in the knowledge base.
6
+
7
+ <details>
8
+ <summary><strong>Table Definition</strong></summary>
9
+
10
+ ```sql
11
+ CREATE VIEW topic_relationships AS (
12
+ SELECT t1.tag AS topic1,
13
+ t2.tag AS topic2,
14
+ count(DISTINCT t1.node_id) AS shared_nodes
15
+ FROM (tags t1
16
+ JOIN tags t2 ON (((t1.node_id = t2.node_id) AND (t1.tag < t2.tag))))
17
+ GROUP BY t1.tag, t2.tag
18
+ HAVING (count(DISTINCT t1.node_id) >= 2)
19
+ ORDER BY (count(DISTINCT t1.node_id)) DESC
20
+ )
21
+ ```
22
+
23
+ </details>
24
+
25
+ ## Columns
26
+
27
+ | Name | Type | Default | Nullable | Children | Parents | Comment |
28
+ | ---- | ---- | ------- | -------- | -------- | ------- | ------- |
29
+ | topic1 | text | | true | | | |
30
+ | topic2 | text | | true | | | |
31
+ | shared_nodes | bigint | | true | | | |
32
+
33
+ ## Referenced Tables
34
+
35
+ | Name | Columns | Comment | Type |
36
+ | ---- | ------- | ------- | ---- |
37
+ | [public.tags](public.tags.md) | 4 | Hierarchical topic tags for flexible categorization using colon-delimited format | BASE TABLE |
38
+
39
+ ## Relations
40
+
41
+ ![er](public.topic_relationships.svg)
42
+
43
+ ---
44
+
45
+ > Generated by [tbls](https://github.com/k1LoW/tbls)
data/dbdoc/public.topic_relationships.svg ADDED
@@ -0,0 +1,32 @@
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.topic_relationships Pages: 1 -->
7
+ <svg width="376pt" height="228pt"
8
+ viewBox="0.00 0.00 375.54 228.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 224.4)">
10
+ <title>public.topic_relationships</title>
11
+ <polygon fill="white" stroke="none" points="-4,4 -4,-224.4 371.54,-224.4 371.54,4 -4,4"/>
12
+ <!-- public.topic_relationships -->
13
+ <g id="node1" class="node">
14
+ <title>public.topic_relationships</title>
15
+ <polygon fill="#efefef" stroke="none" points="46.2,-138.6 46.2,-174.2 321.34,-174.2 321.34,-138.6 46.2,-138.6"/>
16
+ <polygon fill="none" stroke="black" points="46.2,-138.6 46.2,-174.2 321.34,-174.2 321.34,-138.6 46.2,-138.6"/>
17
+ <text text-anchor="start" x="53.2" y="-152" font-family="Arial Bold" font-size="18.00">public.topic_relationships</text>
18
+ <text text-anchor="start" x="239.67" y="-152" font-family="Arial" font-size="14.00">    </text>
19
+ <text text-anchor="start" x="270.79" y="-152" font-family="Arial" font-size="14.00" fill="#666666">[VIEW]</text>
20
+ <polygon fill="none" stroke="black" points="46.2,-107.8 46.2,-138.6 321.34,-138.6 321.34,-107.8 46.2,-107.8"/>
21
+ <text text-anchor="start" x="53.2" y="-120" font-family="Arial" font-size="14.00">topic1 </text>
22
+ <text text-anchor="start" x="94.45" y="-120" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
23
+ <polygon fill="none" stroke="black" points="46.2,-77 46.2,-107.8 321.34,-107.8 321.34,-77 46.2,-77"/>
24
+ <text text-anchor="start" x="53.2" y="-89.2" font-family="Arial" font-size="14.00">topic2 </text>
25
+ <text text-anchor="start" x="94.45" y="-89.2" font-family="Arial" font-size="14.00" fill="#666666">[text]</text>
26
+ <polygon fill="none" stroke="black" points="46.2,-46.2 46.2,-77 321.34,-77 321.34,-46.2 46.2,-46.2"/>
27
+ <text text-anchor="start" x="53.2" y="-58.4" font-family="Arial" font-size="14.00">shared_nodes </text>
28
+ <text text-anchor="start" x="145.83" y="-58.4" font-family="Arial" font-size="14.00" fill="#666666">[bigint]</text>
29
+ <polygon fill="none" stroke="black" stroke-width="3" points="44.7,-44.7 44.7,-175.7 322.84,-175.7 322.84,-44.7 44.7,-44.7"/>
30
+ </g>
31
+ </g>
32
+ </svg>