htm 0.0.10 → 0.0.14

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 (75) hide show
  1. checksums.yaml +4 -4
  2. data/.dictate.toml +46 -0
  3. data/.envrc +2 -0
  4. data/CHANGELOG.md +86 -3
  5. data/README.md +86 -7
  6. data/Rakefile +14 -2
  7. data/bin/htm_mcp.rb +621 -0
  8. data/config/database.yml +20 -13
  9. data/db/migrate/00010_add_soft_delete_to_associations.rb +29 -0
  10. data/db/migrate/00011_add_performance_indexes.rb +21 -0
  11. data/db/migrate/00012_add_tags_trigram_index.rb +18 -0
  12. data/db/migrate/00013_enable_lz4_compression.rb +43 -0
  13. data/db/schema.sql +49 -92
  14. data/docs/api/index.md +1 -1
  15. data/docs/api/yard/HTM.md +2 -4
  16. data/docs/architecture/index.md +1 -1
  17. data/docs/development/index.md +1 -1
  18. data/docs/getting-started/index.md +1 -1
  19. data/docs/guides/index.md +1 -1
  20. data/docs/images/telemetry-architecture.svg +153 -0
  21. data/docs/telemetry.md +391 -0
  22. data/examples/README.md +171 -1
  23. data/examples/cli_app/README.md +1 -1
  24. data/examples/cli_app/htm_cli.rb +1 -1
  25. data/examples/mcp_client.rb +529 -0
  26. data/examples/sinatra_app/app.rb +1 -1
  27. data/examples/telemetry/README.md +147 -0
  28. data/examples/telemetry/SETUP_README.md +169 -0
  29. data/examples/telemetry/demo.rb +498 -0
  30. data/examples/telemetry/grafana/dashboards/htm-metrics.json +457 -0
  31. data/lib/htm/configuration.rb +261 -70
  32. data/lib/htm/database.rb +46 -22
  33. data/lib/htm/embedding_service.rb +24 -14
  34. data/lib/htm/errors.rb +15 -1
  35. data/lib/htm/jobs/generate_embedding_job.rb +19 -0
  36. data/lib/htm/jobs/generate_propositions_job.rb +103 -0
  37. data/lib/htm/jobs/generate_tags_job.rb +24 -0
  38. data/lib/htm/loaders/markdown_chunker.rb +79 -0
  39. data/lib/htm/loaders/markdown_loader.rb +41 -15
  40. data/lib/htm/long_term_memory/fulltext_search.rb +138 -0
  41. data/lib/htm/long_term_memory/hybrid_search.rb +324 -0
  42. data/lib/htm/long_term_memory/node_operations.rb +209 -0
  43. data/lib/htm/long_term_memory/relevance_scorer.rb +355 -0
  44. data/lib/htm/long_term_memory/robot_operations.rb +34 -0
  45. data/lib/htm/long_term_memory/tag_operations.rb +428 -0
  46. data/lib/htm/long_term_memory/vector_search.rb +109 -0
  47. data/lib/htm/long_term_memory.rb +51 -1153
  48. data/lib/htm/models/node.rb +35 -2
  49. data/lib/htm/models/node_tag.rb +31 -0
  50. data/lib/htm/models/robot_node.rb +31 -0
  51. data/lib/htm/models/tag.rb +44 -0
  52. data/lib/htm/proposition_service.rb +169 -0
  53. data/lib/htm/query_cache.rb +214 -0
  54. data/lib/htm/sql_builder.rb +178 -0
  55. data/lib/htm/tag_service.rb +16 -6
  56. data/lib/htm/tasks.rb +8 -2
  57. data/lib/htm/telemetry.rb +224 -0
  58. data/lib/htm/version.rb +1 -1
  59. data/lib/htm.rb +64 -3
  60. data/lib/tasks/doc.rake +1 -1
  61. data/lib/tasks/htm.rake +259 -13
  62. data/mkdocs.yml +96 -96
  63. metadata +75 -18
  64. data/.aigcm_msg +0 -1
  65. data/.claude/settings.local.json +0 -92
  66. data/CLAUDE.md +0 -603
  67. data/examples/cli_app/temp.log +0 -93
  68. data/lib/htm/loaders/paragraph_chunker.rb +0 -112
  69. data/notes/ARCHITECTURE_REVIEW.md +0 -1167
  70. data/notes/IMPLEMENTATION_SUMMARY.md +0 -606
  71. data/notes/MULTI_FRAMEWORK_IMPLEMENTATION.md +0 -451
  72. data/notes/next_steps.md +0 -100
  73. data/notes/plan.md +0 -627
  74. data/notes/tag_ontology_enhancement_ideas.md +0 -222
  75. data/notes/timescaledb_removal_summary.md +0 -200
metadata CHANGED
@@ -1,11 +1,11 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: htm
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.10
4
+ version: 0.0.14
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dewayne VanHoozer
8
- bindir: exe
8
+ bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies:
@@ -121,6 +121,34 @@ dependencies:
121
121
  - - ">="
122
122
  - !ruby/object:Gem::Version
123
123
  version: '0'
124
+ - !ruby/object:Gem::Dependency
125
+ name: fast-mcp
126
+ requirement: !ruby/object:Gem::Requirement
127
+ requirements:
128
+ - - ">="
129
+ - !ruby/object:Gem::Version
130
+ version: '0'
131
+ type: :runtime
132
+ prerelease: false
133
+ version_requirements: !ruby/object:Gem::Requirement
134
+ requirements:
135
+ - - ">="
136
+ - !ruby/object:Gem::Version
137
+ version: '0'
138
+ - !ruby/object:Gem::Dependency
139
+ name: baran
140
+ requirement: !ruby/object:Gem::Requirement
141
+ requirements:
142
+ - - ">="
143
+ - !ruby/object:Gem::Version
144
+ version: '0'
145
+ type: :runtime
146
+ prerelease: false
147
+ version_requirements: !ruby/object:Gem::Requirement
148
+ requirements:
149
+ - - ">="
150
+ - !ruby/object:Gem::Version
151
+ version: '0'
124
152
  - !ruby/object:Gem::Dependency
125
153
  name: rake
126
154
  requirement: !ruby/object:Gem::Requirement
@@ -177,6 +205,20 @@ dependencies:
177
205
  - - ">="
178
206
  - !ruby/object:Gem::Version
179
207
  version: '0'
208
+ - !ruby/object:Gem::Dependency
209
+ name: ruby_llm-mcp
210
+ requirement: !ruby/object:Gem::Requirement
211
+ requirements:
212
+ - - ">="
213
+ - !ruby/object:Gem::Version
214
+ version: '0'
215
+ type: :development
216
+ prerelease: false
217
+ version_requirements: !ruby/object:Gem::Requirement
218
+ requirements:
219
+ - - ">="
220
+ - !ruby/object:Gem::Version
221
+ version: '0'
180
222
  - !ruby/object:Gem::Dependency
181
223
  name: yard
182
224
  requirement: !ruby/object:Gem::Requirement
@@ -206,18 +248,18 @@ dependencies:
206
248
  - !ruby/object:Gem::Version
207
249
  version: '0'
208
250
  description: |
209
- HTM (Hierarchical Temporary Memory) provides intelligent memory management for
251
+ HTM (Hierarchical Temporal Memory) provides intelligent memory/context management for
210
252
  LLM-based applications. It implements a two-tier memory system with
211
- durable long-term storage (PostgreSQL/TimescaleDB) and token-limited working
253
+ durable long-term storage (PostgreSQL) and token-limited working
212
254
  memory, enabling applications to recall context from past conversations using RAG
213
255
  (Retrieval-Augmented Generation) techniques.
214
256
  email:
215
257
  - dvanhoozer@gmail.com
216
- executables: []
258
+ executables:
259
+ - htm_mcp.rb
217
260
  extensions: []
218
261
  extra_rdoc_files: []
219
262
  files:
220
- - ".aigcm_msg"
221
263
  - ".architecture/decisions/adrs/001-use-postgresql-timescaledb-storage.md"
222
264
  - ".architecture/decisions/adrs/002-two-tier-memory-architecture.md"
223
265
  - ".architecture/decisions/adrs/003-ollama-default-embedding-provider.md"
@@ -238,17 +280,17 @@ files:
238
280
  - ".architecture/reviews/2025-10-29-llm-configuration-and-async-processing-review.md"
239
281
  - ".architecture/reviews/comprehensive-codebase-review.md"
240
282
  - ".architecture/reviews/initial-system-analysis.md"
241
- - ".claude/settings.local.json"
283
+ - ".dictate.toml"
242
284
  - ".envrc"
243
285
  - ".irbrc"
244
286
  - ".tbls.yml"
245
287
  - CHANGELOG.md
246
- - CLAUDE.md
247
288
  - COMMITS.md
248
289
  - LICENSE
249
290
  - README.md
250
291
  - Rakefile
251
292
  - SETUP.md
293
+ - bin/htm_mcp.rb
252
294
  - config/database.yml
253
295
  - db/migrate/00001_enable_extensions.rb
254
296
  - db/migrate/00002_create_robots.rb
@@ -258,6 +300,10 @@ files:
258
300
  - db/migrate/00006_create_node_tags.rb
259
301
  - db/migrate/00007_create_robot_nodes.rb
260
302
  - db/migrate/00009_add_working_memory_to_robot_nodes.rb
303
+ - db/migrate/00010_add_soft_delete_to_associations.rb
304
+ - db/migrate/00011_add_performance_indexes.rb
305
+ - db/migrate/00012_add_tags_trigram_index.rb
306
+ - db/migrate/00013_enable_lz4_compression.rb
261
307
  - db/schema.sql
262
308
  - db/seed_data/README.md
263
309
  - db/seed_data/presidents.md
@@ -389,19 +435,21 @@ files:
389
435
  - docs/guides/search-strategies.md
390
436
  - docs/guides/working-memory.md
391
437
  - docs/images/htm-er-diagram.svg
438
+ - docs/images/telemetry-architecture.svg
392
439
  - docs/index.md
393
440
  - docs/multi_framework_support.md
394
441
  - docs/setup_local_database.md
442
+ - docs/telemetry.md
395
443
  - docs/using_rake_tasks_in_your_app.md
396
444
  - examples/README.md
397
445
  - examples/basic_usage.rb
398
446
  - examples/cli_app/README.md
399
447
  - examples/cli_app/htm_cli.rb
400
- - examples/cli_app/temp.log
401
448
  - examples/custom_llm_configuration.rb
402
449
  - examples/example_app/Rakefile
403
450
  - examples/example_app/app.rb
404
451
  - examples/file_loader_usage.rb
452
+ - examples/mcp_client.rb
405
453
  - examples/robot_groups/lib/robot_group.rb
406
454
  - examples/robot_groups/lib/working_memory_channel.rb
407
455
  - examples/robot_groups/multi_process.rb
@@ -410,6 +458,10 @@ files:
410
458
  - examples/sinatra_app/Gemfile
411
459
  - examples/sinatra_app/Gemfile.lock
412
460
  - examples/sinatra_app/app.rb
461
+ - examples/telemetry/README.md
462
+ - examples/telemetry/SETUP_README.md
463
+ - examples/telemetry/demo.rb
464
+ - examples/telemetry/grafana/dashboards/htm-metrics.json
413
465
  - examples/timeframe_demo.rb
414
466
  - lib/htm.rb
415
467
  - lib/htm/active_record_config.rb
@@ -421,10 +473,18 @@ files:
421
473
  - lib/htm/integrations/sinatra.rb
422
474
  - lib/htm/job_adapter.rb
423
475
  - lib/htm/jobs/generate_embedding_job.rb
476
+ - lib/htm/jobs/generate_propositions_job.rb
424
477
  - lib/htm/jobs/generate_tags_job.rb
478
+ - lib/htm/loaders/markdown_chunker.rb
425
479
  - lib/htm/loaders/markdown_loader.rb
426
- - lib/htm/loaders/paragraph_chunker.rb
427
480
  - lib/htm/long_term_memory.rb
481
+ - lib/htm/long_term_memory/fulltext_search.rb
482
+ - lib/htm/long_term_memory/hybrid_search.rb
483
+ - lib/htm/long_term_memory/node_operations.rb
484
+ - lib/htm/long_term_memory/relevance_scorer.rb
485
+ - lib/htm/long_term_memory/robot_operations.rb
486
+ - lib/htm/long_term_memory/tag_operations.rb
487
+ - lib/htm/long_term_memory/vector_search.rb
428
488
  - lib/htm/models/file_source.rb
429
489
  - lib/htm/models/node.rb
430
490
  - lib/htm/models/node_tag.rb
@@ -432,9 +492,13 @@ files:
432
492
  - lib/htm/models/robot_node.rb
433
493
  - lib/htm/models/tag.rb
434
494
  - lib/htm/observability.rb
495
+ - lib/htm/proposition_service.rb
496
+ - lib/htm/query_cache.rb
435
497
  - lib/htm/railtie.rb
498
+ - lib/htm/sql_builder.rb
436
499
  - lib/htm/tag_service.rb
437
500
  - lib/htm/tasks.rb
501
+ - lib/htm/telemetry.rb
438
502
  - lib/htm/timeframe.rb
439
503
  - lib/htm/timeframe_extractor.rb
440
504
  - lib/htm/version.rb
@@ -446,13 +510,6 @@ files:
446
510
  - lib/tasks/jobs.rake
447
511
  - lib/tasks/tags.rake
448
512
  - mkdocs.yml
449
- - notes/ARCHITECTURE_REVIEW.md
450
- - notes/IMPLEMENTATION_SUMMARY.md
451
- - notes/MULTI_FRAMEWORK_IMPLEMENTATION.md
452
- - notes/next_steps.md
453
- - notes/plan.md
454
- - notes/tag_ontology_enhancement_ideas.md
455
- - notes/timescaledb_removal_summary.md
456
513
  - scripts/install_local_database.sh
457
514
  homepage: https://github.com/madbomber/htm
458
515
  licenses:
@@ -477,5 +534,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
477
534
  requirements: []
478
535
  rubygems_version: 4.0.0.dev
479
536
  specification_version: 4
480
- summary: Hierarchical Temporary Memory for LLM robots
537
+ summary: Hierarchical Temporal Memory for LLM robots
481
538
  test_files: []
data/.aigcm_msg DELETED
@@ -1 +0,0 @@
1
- Error generating commit message: status=404 Not Found body=404 page not found
@@ -1,92 +0,0 @@
1
- {
2
- "permissions": {
3
- "allow": [
4
- "WebFetch(domain:raw.githubusercontent.com)",
5
- "Bash(mkdir:*)",
6
- "Bash(mkdocs build:*)",
7
- "Bash(ffmpeg:*)",
8
- "Bash(gh issue create:*)",
9
- "Bash(gh issue list:*)",
10
- "Bash(rake test:*)",
11
- "Bash(ruby -Ilib -e:*)",
12
- "Bash(gh issue view:*)",
13
- "Bash(gh issue close:*)",
14
- "Bash(bundle install:*)",
15
- "Bash(echo:*)",
16
- "Bash(ruby test_connection.rb:*)",
17
- "Bash(psql:*)",
18
- "Bash(ruby -r ./lib/htm -e:*)",
19
- "Bash(curl:*)",
20
- "Bash(ollama list:*)",
21
- "Bash(ruby:*)",
22
- "Bash(rake:*)",
23
- "Bash(export HTM_DBURL=$TIGER_DBURL)",
24
- "Bash(python3:*)",
25
- "Bash(chmod:*)",
26
- "Bash(git clone:*)",
27
- "Bash(cat:*)",
28
- "Bash(source:*)",
29
- "Bash(bundle exec rake:*)",
30
- "Bash(./examples/example_app/app.rb)",
31
- "Bash(gem list:*)",
32
- "Read(//Users/dewayne/.rbenv/versions/3.4.7/lib/ruby/gems/3.4.0/gems/pgvector-0.3.2/lib/pgvector/**)",
33
- "Bash(bundle check:*)",
34
- "Bash(find:*)",
35
- "Bash(test/caching_test.rb)",
36
- "Bash(xargs:*)",
37
- "Bash(git log:*)",
38
- "Bash(done)",
39
- "Bash(brew services:*)",
40
- "Bash(lsof:*)",
41
- "Bash(env)",
42
- "Bash(createdb:*)",
43
- "Bash(export HTM_DBURL:*)",
44
- "Bash(dropdb:*)",
45
- "Bash(bundle exec ruby:*)",
46
- "WebFetch(domain:rubyllm.com)",
47
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" bundle exec rake:*)",
48
- "mcp__playwright-mcp__playwright_navigate",
49
- "mcp__playwright-mcp__playwright_screenshot",
50
- "mcp__playwright-mcp__playwright_fill",
51
- "mcp__playwright-mcp__playwright_click",
52
- "mcp__playwright-mcp__playwright_select",
53
- "mcp__playwright-mcp__playwright_get",
54
- "mcp__playwright-mcp__playwright_post",
55
- "mcp__playwright-mcp__playwright_close",
56
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" bundle exec ruby:*)",
57
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" bundle exec rake test:*)",
58
- "Bash(git mv:*)",
59
- "Bash(kill:*)",
60
- "WebFetch(domain:github.com)",
61
- "WebFetch(domain:api.github.com)",
62
- "Bash(git add:*)",
63
- "Bash(git commit:*)",
64
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" ruby:*)",
65
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" ruby test/loaders/markdown_loader_test.rb:*)",
66
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" bundle exec rake htm:db:stats:*)",
67
- "Skill(architecture-review)",
68
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" psql:*)",
69
- "Bash(git reset:*)",
70
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250101000002_create_robots.rb )",
71
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250101000003_create_nodes.rb )",
72
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250101000005_create_tags.rb )",
73
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250101000007_add_node_vector_indexes.rb )",
74
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250125000001_add_content_hash_to_nodes.rb )",
75
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250125000002_create_robot_nodes.rb )",
76
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250125000003_remove_source_and_robot_id_from_nodes.rb )",
77
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250126000001_create_working_memories.rb )",
78
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20250126000002_remove_unused_columns.rb )",
79
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20251128000001_add_deleted_at_to_nodes.rb )",
80
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20251128000002_create_file_sources.rb )",
81
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20251128000003_add_source_to_nodes.rb )",
82
- "Bash(/Users/dewayne/sandbox/git_repos/madbomber/htm/db/migrate/20251129000002_remove_unused_embedding_columns.rb)",
83
- "WebSearch",
84
- "WebFetch(domain:www.barndominiumlife.com)",
85
- "Bash(git rm:*)",
86
- "Bash(HTM_DBURL=\"postgresql://dewayne@localhost:5432/htm_development\" psql -c \"DROP TABLE IF EXISTS working_memories CASCADE;\" htm_development)",
87
- "Bash(git checkout:*)"
88
- ],
89
- "deny": [],
90
- "ask": []
91
- }
92
- }