robot_lab-durable 0.2.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b576c8ce4dc5ca5b4741cf6b7d9a95b0b653b9f54ab15aa02e0114a2e7cf43d4
-  data.tar.gz: 5079f8bd4f6a63fdcc9938da446db749ca1e93ab844aa5d47c4a8fbd025d189f
+  metadata.gz: 54a17c8e6e00177f47175470d75d785d95aa4322ee89f1dd89702b218491b2e8
+  data.tar.gz: 0d87cba5d51a23813f7592058daf4f4f3e12822d6545d03bbcb363cf8a9013b0
 SHA512:
-  metadata.gz: 7834ab27785b8f43f52e67dad700dd9a5a886cb0fb265d84e46b4cc79c0e123b5181847d17e87260400d6c3db3ac2212507ae7205186f684a6b8962270f49b57
-  data.tar.gz: cc57c77b81eaf328a07d167dc5d053dff56599935e51ada19fc50ac39bb73a73c1f63c28d387d77e3380693871b20e4e33c787cd9a2c39cd6d8734add3e8f19f
+  metadata.gz: bb2cd6073cbd35a76fed4d8a741171b40109d5c0739297879460b37d7a9141e2d4391247c2ff80118d661cc648380fbca5fa54f54afb34dce833f4ae2e6f1eee
+  data.tar.gz: ec9d1af50d43b74ef6826e2216173d990101028394b4960414c7ff64bded29301b13879c6816e1c37a257a03fcf4e3950d47fc499fd06c0d035cb323400a794d

data/.envrc

@@ -1 +1,3 @@
+source_up
 export RR=`pwd`
+export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# robot_lab-durable — cross-session persistent robot memory and learned behaviors.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-durable".freeze
+
+  header "robot_lab-durable v#{gem_version} — cross-session persistent learning"
+end

data/.rubocop.yml

@@ -1,173 +1 @@
-AllCops:
-  NewCops: enable
-  SuggestExtensions: false
-  TargetRubyVersion: 4.0
-  Exclude:
-    - 'examples/**/*'
-    - 'vendor/**/*'
-    - 'dead_code/**/*'
-
-# ── Style: disabled cops ───────────────────────────────────────────────────
-Style/StringLiterals:
-  Enabled: false
-
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-
-Style/Documentation:
-  Enabled: false
-
-# Ruby 4.0 freezes string literals by default
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Style/IfUnlessModifier:
-  Enabled: false
-
-Style/RescueModifier:
-  Enabled: false
-
-Style/TrivialAccessors:
-  Enabled: false
-
-Style/MultilineTernaryOperator:
-  Enabled: false
-
-Style/SafeNavigation:
-  Enabled: false
-
-Style/EmptyClassDefinition:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  Enabled: false
-
-Style/RescueStandardError:
-  Enabled: false
-
-Style/OneClassPerFile:
-  Enabled: false
-
-# Both % and format/sprintf are acceptable
-Style/FormatString:
-  Enabled: false
-
-# String concatenation and interpolation are both acceptable
-Style/StringConcatenation:
-  Enabled: false
-
-# ── Layout ─────────────────────────────────────────────────────────────────
-Layout/LineLength:
-  Max: 140
-
-Layout/ExtraSpacing:
-  Enabled: false
-
-Layout/HashAlignment:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-# ── Naming ─────────────────────────────────────────────────────────────────
-# Single-char params (c, e, n) are acceptable throughout
-Naming/MethodParameterName:
-  Enabled: false
-
-Naming/VariableNumber:
-  Exclude:
-    - 'test/**/*'
-
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-
-# set_results and similar explicit setters are clear and conventional
-Naming/AccessorMethodName:
-  Enabled: false
-
-
-# has_tool_calls? and similar are clear and conventional
-Naming/PredicatePrefix:
-  Enabled: false
-
-# Test helper methods don't need to follow predicate naming rules
-Naming/PredicateMethod:
-  Exclude:
-    - 'test/**/*'
-
-# ── Lint: relax noisy cops on intentional patterns ─────────────────────────
-# Library and framework methods commonly accept args for API/documentation purposes
-Lint/UnusedMethodArgument:
-  Enabled: false
-
-
-Lint/EmptyBlock:
-  Exclude:
-    - 'test/**/*'
-
-Lint/ConstantDefinitionInBlock:
-  Exclude:
-    - 'Rakefile'
-    - 'test/**/*'
-
-# ── Gemspec ────────────────────────────────────────────────────────────────
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: Gemfile
-
-Gemspec/RequiredRubyVersion:
-  Enabled: false
-
-Gemspec/OrderedDependencies:
-  Enabled: false
-
-# ── Metrics ────────────────────────────────────────────────────────────────
-# Framework-level code (routers, parsers, orchestrators) is inherently complex.
-# Flog is the primary complexity gate — these RuboCop thresholds catch only
-# egregious outliers without false-positiving every dispatch method.
-
-Metrics/MethodLength:
-  Max: 35
-  CountAsOne:
-    - heredoc
-    - array
-    - hash
-  Exclude:
-    - 'test/**/*'
-
-Metrics/AbcSize:
-  Max: 40
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ClassLength:
-  Max: 600
-  Exclude:
-    - 'test/**/*'
-
-Metrics/ModuleLength:
-  Max: 200
-  Exclude:
-    - 'test/**/*'
-
-Metrics/CyclomaticComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-Metrics/PerceivedComplexity:
-  Max: 20
-  Exclude:
-    - 'test/**/*'
-
-# Long method signatures with keyword args are a Ruby framework idiom
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - 'Rakefile'
-    - '*.gemspec'
-    - 'test/**/*'
+inherit_from: ../.rubocop-base.yml

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 ## [Unreleased]
 
+### Added
+- `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, and `console` tasks via the Asgard task runner
+- `flay_check` Rake task: structural code duplication gate (mass threshold 50); integrated into the `quality` Rake task
+- `flay` and `minitest-reporters` gems added to development dependencies
+- `test_output.txt`, `flay_output.txt`, `flog_output.txt`, and `rubocop_output.txt` added to `.gitignore`
+
+### Changed
+- `test/test_helper.rb`: test output redirected to `test_output.txt` via `$stdout` reassignment; `TerminalSummaryReporter` prints a single PASS/FAIL summary line to the terminal
+- `Rakefile`: `rubocop` and `rubocop_fix` tasks removed (now owned by Asgard); `flay_check` integrated into the `quality` gate
+
+## [0.3.0] - 2026-05-24
+
+### Changed (breaking)
+- **Backend replaced**: YAML file store replaced entirely by the `htm` gem (PostgreSQL + pgvector).
+  `robot_lab-durable` is now a thin adapter between `robot_lab` and `htm`.
+- `Durable::Entry` is now a presenter built from HTM node hashes via `Entry.from_node(node)`.
+  Removed fields: `domain`, `confidence`, `use_count`. Added: `node_id`.
+- `Durable::Hook` no longer manages a domain or seeds past knowledge into session memory.
+  `around_run` initialises a thread-local `Adapter` from `ctx.robot.name`; `on_learn` persists
+  new learnings via `adapter.record`. `Hook.current_adapter` returns the active adapter.
+- `RecallKnowledge` and `RecordKnowledge` now delegate to `Hook.current_adapter` instead of a
+  YAML store. The `domain:` parameter is removed from both tools.
+- `Gemfile` updated: depends on published `htm` gem and local `robot_lab` path.
+
+### Added
+- `Durable::Adapter` — wraps `HTM.new(robot_name:)`, exposes `recall(query:, ...)` and
+  `record(content:, reasoning:, category:)`. HTM deduplicates by content hash, eliminating
+  the need for double-write prevention.
+- Full test suite for `Durable::Adapter` (`test/robot_lab/durable/adapter_test.rb`) using a
+  `FakeHTM` stand-in — no PostgreSQL required.
+- `examples/01_day_trader.rb` — demo launcher that spawns the generator and predictor as
+  subprocesses and relays their output with colour-coded `[GEN ]`/`[PRED]` prefixes.
+- `examples/day_trader_lib/generator.rb` — XYZZY fake stock price stream via Redis (GBM model).
+- `examples/day_trader_lib/predictor.rb` — SMA+EMA ensemble tuned by a durable agent;
+  prints `✓ GOOD / ✗ MISS` verdict after each prediction window.
+
+### Removed
+- `Durable::Store` (YAML-backed per-domain file store).
+- `Durable::Reflector` (end-of-run confidence promoter).
+- `domain` concept throughout — HTM uses `robot_name` for scoping.
+- `skip_persist` mechanism — HTM SHA-256 content deduplication makes it unnecessary.
+
 ## [0.2.1] - 2026-05-19
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Gem Does
+
+`robot_lab-durable` gives RobotLab robots cross-session persistent memory backed by the `htm` gem (Hierarchical Temporal Memory). Knowledge is recorded by robots during a session and recalled in future sessions using hybrid semantic search (vector + full-text).
+
+## Commands
+
+```bash
+bundle exec rake test        # Run full test suite
+ruby -Ilib:test test/<file>  # Run a single test file
+```
+
+## Architecture
+
+All source lives under `lib/robot_lab/durable/` plus two tool files at `lib/robot_lab/`.
+
+**`Adapter`** (`durable/adapter.rb`) — Wraps an `HTM` instance for one robot. Two operations:
+- `recall(query:, limit:, strategy:)` — calls `htm.recall` and maps nodes to `Entry` structs. Strategies: `:vector`, `:fulltext`, `:hybrid` (default)
+- `record(content:, reasoning:, category:)` — calls `htm.remember` with metadata hash
+
+**`Entry`** (`durable/entry.rb`) — `Data.define(:node_id, :content, :reasoning, :category, :created_at)`. Immutable value object. `category` is always a Symbol. Built via `Entry.from_node(node)` from raw HTM node hashes.
+
+**`Hook`** (`durable/hook.rb`) — Subclass of `RobotLab::Hook` with `namespace = :durable`. Manages a per-thread `Adapter` instance:
+- `around_run` — creates an `Adapter` for the robot, stores it in `Thread.current`, tears it down in `ensure`
+- `on_learn` — called by the `:learn` hook family when the robot learns something; persists to HTM if `ctx.stored` is true
+
+**`RecallKnowledge`** (`recall_knowledge.rb`) — `RobotLab::Tool` subclass. Takes a `query` param, calls `Hook.current_adapter.recall`, formats results for the LLM. Returns "No relevant past knowledge found" when empty — instructs the robot to skip rather than guess.
+
+**`RecordKnowledge`** (`record_knowledge.rb`) — `RobotLab::Tool` subclass. Takes `content`, `reasoning`, `category` params. Calls `adapter.record` then `robot.learn(content)` to update in-session memory immediately. HTM deduplicates by content hash so double-writes are harmless.
+
+## Enabling
+
+```ruby
+require 'robot_lab'
+require 'robot_lab/durable'
+
+robot = RobotLab.build(
+  name:        "advisor",
+  local_tools: [RobotLab::RecallKnowledge, RobotLab::RecordKnowledge]
+)
+robot.on(RobotLab::Durable::Hook)
+result = robot.run("Remember my preference for concise answers.")
+```
+
+## Valid Categories
+
+`fact`, `preference`, `pattern`, `correction`, `observation`
+
+The LLM is free to choose — these are stored as metadata strings and returned as Symbols in `Entry#category`.
+
+## Key Constraints
+
+- The `Adapter` is scoped to `Thread.current` — it is NOT available across Ractors or Fibers.
+- `RecordKnowledge` calls `robot.learn` internally; this triggers the `:learn` hook which calls `on_learn`. HTM deduplication prevents a double-write.
+- `Hook` loads only when `RobotLab::Hook` is defined; `RecallKnowledge`/`RecordKnowledge` load only when `RobotLab::Tool` is defined. Always `require 'robot_lab'` before `require 'robot_lab/durable'`.
+- The `htm` gem manages its own storage backend (PostgreSQL with vector extensions). Ensure the HTM database is configured before use.
+
+## Testing
+
+- Minitest with SimpleCov (branch coverage tracked, no minimum threshold enforced yet)
+- Tests stub `HTM` — do not use a real database in unit tests
+- Coverage baseline: ~83% line / ~44% branch

data/README.md

@@ -1,18 +1,23 @@
 # robot_lab-durable
 
-Cross-session durable learning for the [RobotLab](https://github.com/MadBomber/robot_lab) LLM agent framework.
+Cross-session durable memory for the [RobotLab](https://github.com/MadBomber/robot_lab) LLM agent framework, backed by the [htm gem](https://madbomber.github.io/htm) (PostgreSQL + pgvector).
 
 > [!CAUTION]
 > This gem is under active development. APIs may change without notice.
 
 ## What it provides
 
-- **`Durable::Entry`** — immutable, confidence-tracked knowledge record
-- **`Durable::Store`** — YAML-backed, file-locked per-domain knowledge persistence in `~/.robot_lab/durable/`
-- **`Durable::Reflector`** — promotes session-level learnings into the durable store at end-of-run
-- **`Durable::Learning`** — mixin included into `RobotLab::Robot`; enabled via `learn: true, learn_domain:` constructor params
-- **`RecallKnowledge`** tool — lets robots query the durable store before making decisions
-- **`RecordKnowledge`** tool — lets robots write new knowledge during a session
+- **`Durable::Adapter`** — thin wrapper around an `HTM` instance; scoped to a robot by name. Exposes `record` and `recall` methods.
+- **`Durable::Entry`** — presenter over raw HTM node hashes returned by recall. Provides typed fields: `node_id`, `content`, `reasoning`, `category`, `created_at`.
+- **`Durable::Hook`** — RobotLab hook handler that wires the `Adapter` lifecycle into `around_run` and `on_learn` automatically.
+- **`RecallKnowledge`** tool — lets a robot query its durable memory before answering.
+- **`RecordKnowledge`** tool — lets a robot persist new knowledge during a session.
+
+## Prerequisites
+
+- PostgreSQL with the pgvector extension enabled.
+- The `htm` gem — see documentation at https://madbomber.github.io/htm.
+- The `robot_lab` gem.
 
 ## Installation
 
@@ -23,6 +28,12 @@ gem "robot_lab"
 gem "robot_lab-durable"
 ```
 
+Then run:
+
+```
+bundle install
+```
+
 ## Quick Example
 
 ```ruby
@@ -30,53 +41,77 @@ require "robot_lab"
 require "robot_lab/durable"
 
 robot = RobotLab.build(
-  name: "advisor",
-  system_prompt: "You are a financial advisor that learns from each session.",
-  learn: true,
-  learn_domain: "finance"
+  name:          "advisor",
+  system_prompt: "You are a financial advisor.",
+  local_tools:   [RobotLab::RecallKnowledge, RobotLab::RecordKnowledge]
 )
+robot.on(RobotLab::Durable::Hook)
 
-# RecallKnowledge and RecordKnowledge tools are automatically available.
-# At the end of each run, the Reflector promotes learned facts to
-# ~/.robot_lab/durable/finance.yml for use in future sessions.
 result = robot.run("What do you know about my risk tolerance?")
 puts result.last_text_content
 ```
 
+No `domain:` argument is required. HTM scopes all storage to the robot's `name` automatically.
+
 ## How It Works
 
-When `learn: true` and `learn_domain:` are set, the robot gains two built-in tools:
+### Hook lifecycle
 
-- **`RecallKnowledge`** — queries the domain's YAML store for relevant past knowledge before responding
-- **`RecordKnowledge`** — writes new knowledge entries during a session
+`RobotLab::Durable::Hook` is registered via `robot.on(...)` and plugs into two lifecycle events:
 
-At the end of each run, `Durable::Reflector` promotes session-level learnings into the persistent store with confidence scoring and deduplication.
+- **`around_run`** — creates a thread-local `Adapter` instance keyed to `ctx.robot.name`, makes it available to tools for the duration of the run, and clears it in `ensure` so state never leaks across run boundaries.
+- **`on_learn`** — fires after each new session learning is stored in memory. When a durable session is active, persists the text via `adapter.record(content:, category: :observation)`.
 
-## Knowledge Persistence
+### Adapter
 
-```
-~/.robot_lab/durable/
-  finance.yml       # per-domain YAML store
-  support.yml
-  ...
-```
+`Durable::Adapter` wraps an `HTM` instance and provides two methods:
+
+| Method | Description |
+|--------|-------------|
+| `record(content:, reasoning: nil, category: 'fact')` | Stores a memory entry. HTM deduplicates by SHA-256 content hash, so calling `record` with identical content is safe. |
+| `recall(query:, limit: 20, strategy: :hybrid)` | Searches stored memory and returns an array of `Entry` objects. |
+| `htm` | Direct access to the underlying `HTM` instance for advanced use. |
 
-Each entry records: `content`, `confidence`, `category`, `domain`, `use_count`, `created_at`, and `updated_at`.
+### Entry
 
-Knowledge confidence grows as the same fact is recalled and confirmed across sessions. Low-confidence entries are pruned automatically over time.
+`Durable::Entry` is a presenter built via `Entry.from_node(node)` over the raw hashes returned by `HTM#recall`. It exposes:
 
-## Relationship to `robot.learn()`
+| Field | Type | Description |
+|-------|------|-------------|
+| `node_id` | String | Unique HTM node identifier |
+| `content` | String | The stored knowledge text |
+| `reasoning` | String / nil | Optional rationale recorded at write time |
+| `category` | Symbol | `:fact`, `:observation`, or any custom value |
+| `created_at` | Time | When the entry was first stored |
 
-`robot.learn()` is a core RobotLab method that accumulates observations within a single session in memory. `robot_lab-durable` extends this by persisting those observations to disk across sessions, making the robot's learning accumulate over its lifetime rather than resetting each run.
+## Tools
+
+### RecallKnowledge
+
+Calls `Hook.current_adapter.recall(query:)` with the query text provided by the LLM and returns formatted entries. Uses the `:hybrid` strategy by default.
+
+### RecordKnowledge
+
+Calls `adapter.record(content:, reasoning:, category:)` to persist a new memory, then calls `robot.learn(content)` to update session context. Because HTM deduplicates by content hash, no explicit double-write prevention is necessary.
+
+## Day Trader Demo
+
+`examples/01_day_trader.rb` demonstrates cross-session durable memory in action. It spawns a GBM stock price generator and an SMA+EMA ensemble predictor as subprocesses. Output is colour-coded `[GEN ]` / `[PRED]` per process, with a GOOD/MISS verdict printed for each prediction window. The durable agent tunes its prediction parameters across sessions, accumulating knowledge about what works.
+
+```
+ruby examples/01_day_trader.rb
+```
 
 ## Links
 
 - [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [HTM gem docs](https://madbomber.github.io/htm)
 - [RubyGems](https://rubygems.org/gems/robot_lab-durable)
+- [GitHub](https://github.com/MadBomber/robot_lab-durable)
 
 ## License
 
-MIT License - Copyright (c) 2025 Dewayne VanHoozer
+MIT License — Copyright (c) 2025 Dewayne VanHoozer
 
 ## Contributing
 

data/Rakefile

@@ -24,16 +24,6 @@ task :test_file, [:file] do |_t, args|
   ruby "test/#{args[:file]}"
 end
 
-desc 'Check code style with RuboCop'
-task :rubocop do
-  sh 'bundle exec rubocop'
-end
-
-desc 'Auto-correct RuboCop offenses'
-task :rubocop_fix do
-  sh 'bundle exec rubocop -a'
-end
-
 desc 'Check code complexity with Flog (warn >=20, fail >=50)'
 task :flog_check do
   require 'flog'
@@ -71,36 +61,62 @@ task :flog_check do
   end
 end
 
-desc 'Run all quality checks: tests (with coverage), RuboCop, and Flog'
-task :quality do
-  results = {}
+desc 'Check for structural code duplication with Flay (mass >= 50)'
+task :flay_check do
+  require 'flay'
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Tests + Coverage'
-  puts '=' * 60
-  results[:tests] = system('bundle exec rake test') ? :pass : :fail
+  mass_threshold = 50
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: RuboCop'
-  puts '=' * 60
-  results[:rubocop] = system('bundle exec rubocop') ? :pass : :fail
+  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
+  flay.process(*Dir.glob('lib/**/*.rb'))
+  flay.analyze
 
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate: Flog Complexity'
-  puts '=' * 60
-  results[:flog] = system('bundle exec rake flog_check') ? :pass : :fail
+  if flay.hashes.empty?
+    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
+  else
+    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
+    flay.report
+    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
+  end
+end
+
+desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
+task :quality do
+  gates = [
+    ['Tests + Coverage', 'bundle exec rake test'],
+    ['RuboCop',          'bundle exec rubocop'],
+    ['Flog Complexity',  'bundle exec rake flog_check'],
+    ['Flay Duplication', 'bundle exec rake flay_check']
+  ]
+
+  results = gates.map do |label, command|
+    puts "\n#{'=' * 60}"
+    puts "Quality Gate: #{label}"
+    puts '=' * 60
+    [label, system(command) ? :pass : :fail]
+  end
+
+  green = ->(s) { "\e[32m#{s}\e[0m" }
+  red   = ->(s) { "\e[31m#{s}\e[0m" }
+  width = results.map { |label, _| label.length }.max
 
   puts "\n#{'=' * 60}"
-  puts 'Quality Summary'
+  puts 'Quality Gate Summary'
   puts '=' * 60
-  results.each do |gate, status|
-    icon = status == :pass ? 'PASS' : 'FAIL'
-    puts "  [#{icon}] #{gate}"
+  results.each do |label, status|
+    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
+    puts "  [#{badge}] #{label.ljust(width)}"
   end
+  puts '-' * 60
+
+  passed = results.count { |_, s| s == :pass }
+  failed = results.count { |_, s| s == :fail }
+  tally  = "#{passed} passed, #{failed} failed"
+  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
   puts '=' * 60
 
-  abort "\nQuality gate failed" if results.values.any?(:fail)
-  puts "\nAll quality gates passed."
+  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
+  puts "\n#{green.call('All quality gates passed.')}"
 end
 
 namespace :docs do

data/docs/document_store_backend_design.md

@@ -1,42 +1,9 @@
 # Delegate Storage to robot_lab-document_store — Design Discussion
 
 **Date:** 2026-05-14
-**Status:** Parked — resume when time allows
+**Original status:** Parked — resume when time allows
+**Current status:** Superseded — see [docs/index.md](index.md)
 
-## The Problem
+The document_store delegation path was abandoned. In v0.3.0, `robot_lab-durable` became a direct adapter over the [`htm` gem](https://madbomber.github.io/htm) (PostgreSQL + pgvector), replacing the YAML store, the `Durable::Store` class, `Durable::Reflector`, and all domain/confidence concepts entirely. The open questions raised here — search semantics, structured metadata, backend versioning — are resolved by HTM's native hybrid recall and metadata hash support.
 
-`robot_lab-durable` currently maintains its own `Store` class: a YAML-backed, file-locked, keyword-search storage layer in `lib/robot_lab/durable/store.rb`. This is duplicated effort — `robot_lab-document_store` is intended to be the canonical pluggable storage abstraction for the robot_lab ecosystem.
-
-## The Vision
-
-Once `robot_lab-document_store` gains a `DocumentStore::FileSystem` backend, durable should drop its custom `Store` class and delegate physical storage to it. Durable retains its own concerns:
-
-- `Entry` — immutable value object with confidence scoring, category, domain, use_count
-- `Reflector` — end-of-session promoter that pushes session learnings into the store
-- `Learning` — mixin included into `Robot` when robot_lab is present
-- `RecallKnowledge` / `RecordKnowledge` — LLM tools that interact with the store
-
-## What Changes in This Gem
-
-1. Add `robot_lab-document_store` as a runtime dependency in the gemspec.
-2. Remove `lib/robot_lab/durable/store.rb`.
-3. Wire `Learning#setup_durable_learning` to instantiate a `DocumentStore::FileSystem` instead of `Durable::Store`.
-4. Adapt `Reflector` and the two tools to call the `DocumentStore` interface (`store`, `search`, `delete`, etc.) rather than the old `Store` API.
-5. Handle `Entry` serialization — since `DocumentStore` stores raw text by key, durable will serialize `Entry` fields into text (or use a metadata hash if `FileSystem` supports it — see open questions).
-
-## Open Questions (shared with robot_lab-document_store)
-
-1. **Search semantics.** `DocumentStore::Memory` uses embedding-based cosine similarity; `DocumentStore::FileSystem` would use keyword matching. Should the interface declare its search capability, or do callers accept whatever the backend provides?
-
-2. **Structured vs raw text.** `Entry` carries structured fields (confidence, category, domain, use_count). Options:
-   - Durable serializes all fields into the stored text string; deserializes on recall.
-   - `DocumentStore::FileSystem` supports an optional `meta:` Hash alongside text, which durable populates with `Entry` fields.
-
-## Versioning
-
-- `robot_lab-document_store` must ship `DocumentStore::FileSystem` first — that is a v0.3.0 breaking change for that gem (v0.2.1 is the current release).
-- This gem (`robot_lab-durable`) then bumps to v0.3.0 once it drops `Store` and depends on document_store.
-
-## See Also
-
-`robot_lab-document_store/docs/pluggable_backends_design.md` — the full backend architecture design including the `DocumentStore` abstract interface and implementation plan.
+For the current architecture, see [docs/index.md](index.md) and the [HTM gem documentation](https://madbomber.github.io/htm).