lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/trace/local_persistence_spec.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require 'sequel/extensions/migration'
+
+# Minimal stub for Legion::Data::Local used in persistence specs.
+# Does not require the full legion-data gem.
+module Legion
+  module Data
+    module Local
+      class << self
+        attr_reader :connection
+
+        def setup_in_memory!
+          ::Sequel.extension :migration
+          @connection = ::Sequel.sqlite
+          @connected = true
+          run_memory_migrations
+        end
+
+        def connected?
+          @connected == true
+        end
+
+        def table_exists?(name)
+          @connection&.table_exists?(name) || false
+        end
+
+        def reset!
+          @connection&.disconnect
+          @connection = nil
+          @connected = false
+        end
+
+        private
+
+        def run_memory_migrations
+          migration_path = File.join(
+            __dir__,
+            '../lib/legion/extensions/memory/local_migrations'
+          )
+          ::Sequel::TimestampMigrator.new(@connection, migration_path).run
+        end
+      end
+    end
+  end
+end
+
+RSpec.describe 'lex-memory local SQLite persistence' do
+  let(:store) { Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new }
+  let(:trace_helper) { Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace }
+
+  let(:semantic_trace) do
+    trace_helper.new_trace(
+      type:            :semantic,
+      content_payload: { fact: 'SQLite is persistent' },
+      domain_tags:     ['storage']
+    )
+  end
+
+  let(:episodic_trace) do
+    trace_helper.new_trace(
+      type:            :episodic,
+      content_payload: { event: 'first boot' },
+      domain_tags:     ['boot']
+    )
+  end
+
+  before(:all) do
+    Legion::Data::Local.setup_in_memory!
+  end
+
+  after(:all) do
+    Legion::Data::Local.reset!
+  end
+
+  before(:each) do
+    # Clear tables between examples so tests are isolated
+    db = Legion::Data::Local.connection
+    db[:memory_associations].delete
+    db[:memory_traces].delete
+    Legion::Extensions::Agentic::Memory::Trace.reset_store!
+  end
+
+  describe '#save_to_local' do
+    it 'persists traces to the SQLite database' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+      store.save_to_local
+
+      db = Legion::Data::Local.connection
+      expect(db[:memory_traces].count).to eq(2)
+    end
+
+    it 'persists trace fields accurately' do
+      store.store(semantic_trace)
+      store.save_to_local
+
+      db = Legion::Data::Local.connection
+      row = db[:memory_traces].where(trace_id: semantic_trace[:trace_id]).first
+      expect(row).not_to be_nil
+      expect(row[:trace_type]).to eq('semantic')
+      expect(row[:strength]).to eq(semantic_trace[:strength])
+    end
+
+    it 'persists associations to the SQLite database' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+      store.save_to_local
+
+      db = Legion::Data::Local.connection
+      expect(db[:memory_associations].count).to be > 0
+    end
+
+    it 'updates an existing trace row on subsequent saves' do
+      store.store(semantic_trace)
+      store.save_to_local
+
+      # Mutate strength directly and save again
+      store.traces[semantic_trace[:trace_id]][:strength] = 0.99
+      store.save_to_local
+
+      db = Legion::Data::Local.connection
+      row = db[:memory_traces].where(trace_id: semantic_trace[:trace_id]).first
+      expect(row[:strength]).to eq(0.99)
+      expect(db[:memory_traces].count).to eq(1)
+    end
+
+    it 'removes pruned traces from the database' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+      store.save_to_local
+
+      # Prune semantic_trace from memory (simulate decay below threshold)
+      store.delete(semantic_trace[:trace_id])
+      store.save_to_local
+
+      db = Legion::Data::Local.connection
+      expect(db[:memory_traces].count).to eq(1)
+      expect(db[:memory_traces].first[:trace_id]).to eq(episodic_trace[:trace_id])
+    end
+
+    it 'replaces association rows on each save' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+      store.save_to_local
+
+      first_count = Legion::Data::Local.connection[:memory_associations].count
+
+      store.save_to_local
+
+      second_count = Legion::Data::Local.connection[:memory_associations].count
+      expect(second_count).to eq(first_count)
+    end
+
+    it 'is a no-op when Local is not connected' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      expect { store.save_to_local }.not_to raise_error
+    end
+  end
+
+  describe '#load_from_local' do
+    it 'restores traces from the database into a fresh store' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      expect(fresh.count).to eq(2)
+      expect(fresh.get(semantic_trace[:trace_id])).not_to be_nil
+      expect(fresh.get(episodic_trace[:trace_id])).not_to be_nil
+    end
+
+    it 'restores associations from the database into a fresh store' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      expect(fresh.associations[semantic_trace[:trace_id]]).not_to be_empty
+    end
+
+    it 'is a no-op when Local is not connected' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      expect { store.load_from_local }.not_to raise_error
+    end
+  end
+
+  describe 'round-trip: save then load' do
+    it 'produces identical trace data in a fresh store' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      restored = fresh.get(semantic_trace[:trace_id])
+
+      expect(restored[:trace_id]).to eq(semantic_trace[:trace_id])
+      expect(restored[:trace_type]).to eq(:semantic)
+      expect(restored[:strength]).to eq(semantic_trace[:strength])
+      expect(restored[:domain_tags]).to eq(semantic_trace[:domain_tags])
+      expect(restored[:origin]).to eq(semantic_trace[:origin])
+    end
+
+    it 'restores content hash with symbol keys' do
+      store.store(semantic_trace)
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      restored = fresh.get(semantic_trace[:trace_id])
+      expect(restored[:content]).to be_a(Hash)
+      expect(restored[:content][:fact]).to eq('SQLite is persistent')
+    end
+
+    it 'restores domain_tags as an array' do
+      store.store(semantic_trace)
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      restored = fresh.get(semantic_trace[:trace_id])
+      expect(restored[:domain_tags]).to eq(['storage'])
+    end
+
+    it 'preserves storage_tier as a symbol' do
+      store.store(semantic_trace)
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      restored = fresh.get(semantic_trace[:trace_id])
+      expect(restored[:storage_tier]).to eq(:hot)
+    end
+
+    it 'preserves association coactivation counts' do
+      store.store(semantic_trace)
+      store.store(episodic_trace)
+
+      threshold = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::COACTIVATION_THRESHOLD
+      threshold.times { store.record_coactivation(semantic_trace[:trace_id], episodic_trace[:trace_id]) }
+      store.save_to_local
+
+      fresh = Legion::Extensions::Agentic::Memory::Trace::Helpers::Store.new
+      count = fresh.associations[semantic_trace[:trace_id]][episodic_trace[:trace_id]]
+      expect(count).to eq(threshold)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/memory_spec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace do
+  it 'has a version number' do
+    expect(Legion::Extensions::Agentic::Memory::Trace::VERSION).not_to be_nil
+  end
+
+  it 'has a version that is a string' do
+    expect(Legion::Extensions::Agentic::Memory::Trace::VERSION).to be_a(String)
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/persistent_store_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/trace/persistent_store'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::PersistentStore do
+  let(:store) { described_class.new(agent_id: 'test-agent') }
+
+  describe '#read' do
+    it 'returns empty when db unavailable' do
+      allow(store).to receive(:db_ready?).and_return(false)
+      expect(store.read).to eq([])
+    end
+  end
+
+  describe '#write' do
+    it 'returns nil when db unavailable' do
+      allow(store).to receive(:db_ready?).and_return(false)
+      expect(store.write(trace_type: :episodic, content: 'test')).to be_nil
+    end
+  end
+
+  describe '#count' do
+    it 'returns 0 when db unavailable' do
+      allow(store).to receive(:db_ready?).and_return(false)
+      expect(store.count).to eq(0)
+    end
+  end
+
+  describe '#total_bytes' do
+    it 'returns 0 when db unavailable' do
+      allow(store).to receive(:db_ready?).and_return(false)
+      expect(store.total_bytes).to eq(0)
+    end
+  end
+
+  describe '#delete_lowest_confidence' do
+    it 'returns 0 when db unavailable' do
+      allow(store).to receive(:db_ready?).and_return(false)
+      expect(store.delete_lowest_confidence).to eq(0)
+    end
+  end
+
+  describe '#delete_least_recently_used' do
+    it 'returns 0 when db unavailable' do
+      allow(store).to receive(:db_ready?).and_return(false)
+      expect(store.delete_least_recently_used).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/quota_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/trace/quota'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Quota do
+  describe '.new' do
+    it 'uses defaults' do
+      quota = described_class.new
+      expect(quota.max_traces).to eq(10_000)
+      expect(quota.max_bytes).to eq(52_428_800)
+      expect(quota.eviction).to eq(:lru)
+    end
+
+    it 'accepts overrides' do
+      quota = described_class.new(max_traces: 500, eviction: :lowest_confidence)
+      expect(quota.max_traces).to eq(500)
+      expect(quota.eviction).to eq(:lowest_confidence)
+    end
+  end
+
+  describe '#within_limits?' do
+    let(:quota) { described_class.new(max_traces: 100, max_bytes: 1024) }
+    let(:store) { double('store') }
+
+    it 'returns true when under limits' do
+      allow(store).to receive(:count).and_return(50)
+      allow(store).to receive(:total_bytes).and_return(512)
+      expect(quota.within_limits?(store)).to be true
+    end
+
+    it 'returns false when over trace limit' do
+      allow(store).to receive(:count).and_return(200)
+      allow(store).to receive(:total_bytes).and_return(512)
+      expect(quota.within_limits?(store)).to be false
+    end
+
+    it 'returns false when over byte limit' do
+      allow(store).to receive(:count).and_return(50)
+      allow(store).to receive(:total_bytes).and_return(2048)
+      expect(quota.within_limits?(store)).to be false
+    end
+  end
+
+  describe '#enforce!' do
+    let(:quota) { described_class.new(max_traces: 10, max_bytes: 1_048_576) }
+    let(:store) { double('store') }
+
+    it 'evicts when over trace limit' do
+      allow(store).to receive(:count).and_return(15)
+      allow(store).to receive(:total_bytes).and_return(100)
+      expect(store).to receive(:delete_least_recently_used).with(count: 5)
+      quota.enforce!(store)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/runners/consolidation_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/trace/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Runners::Consolidation do
+  let(:client) { Legion::Extensions::Agentic::Memory::Trace::Client.new }
+
+  describe '#reinforce' do
+    it 'increases trace strength' do
+      stored = client.store_trace(type: :semantic, content_payload: {})
+      result = client.reinforce(trace_id: stored[:trace_id])
+
+      expect(result[:reinforced]).to be true
+      expect(result[:new_strength]).to eq(0.6) # 0.5 + 0.1
+    end
+
+    it 'applies imprint multiplier' do
+      stored = client.store_trace(type: :semantic, content_payload: {})
+      result = client.reinforce(trace_id: stored[:trace_id], imprint_active: true)
+
+      expect(result[:new_strength]).to eq(0.8) # 0.5 + 0.1 * 3.0
+    end
+
+    it 'does not reinforce firmware traces' do
+      stored = client.store_trace(type: :firmware, content_payload: { directive_text: 'protect' })
+      result = client.reinforce(trace_id: stored[:trace_id])
+
+      expect(result[:reinforced]).to be false
+      expect(result[:reason]).to eq(:firmware)
+    end
+
+    it 'returns found: false for missing traces' do
+      result = client.reinforce(trace_id: 'nonexistent')
+      expect(result[:found]).to be false
+    end
+
+    it 'clamps at 1.0' do
+      stored = client.store_trace(type: :semantic, content_payload: {})
+      # Reinforce multiple times
+      10.times { client.reinforce(trace_id: stored[:trace_id]) }
+      trace = client.get_trace(trace_id: stored[:trace_id])
+      expect(trace[:trace][:strength]).to eq(1.0)
+    end
+
+    it 'increments reinforcement_count' do
+      stored = client.store_trace(type: :semantic, content_payload: {})
+      3.times { client.reinforce(trace_id: stored[:trace_id]) }
+      trace = client.get_trace(trace_id: stored[:trace_id])
+      expect(trace[:trace][:reinforcement_count]).to eq(3)
+    end
+  end
+
+  describe '#decay_cycle' do
+    it 'decays non-firmware traces' do
+      client.store_trace(type: :semantic, content_payload: {})
+      client.store_trace(type: :firmware, content_payload: { directive_text: 'protect' })
+
+      result = client.decay_cycle(tick_count: 100)
+      expect(result[:decayed]).to be >= 1
+    end
+
+    it 'prunes traces below threshold' do
+      stored = client.store_trace(type: :sensory, content_payload: {})
+      trace = client.get_trace(trace_id: stored[:trace_id])
+      trace[:trace][:strength] = 0.005
+      trace[:trace][:peak_strength] = 0.005
+
+      result = client.decay_cycle(tick_count: 100_000)
+      expect(result[:pruned]).to be >= 0
+    end
+  end
+
+  describe '#migrate_tier' do
+    it 'migrates traces to correct tier' do
+      stored = client.store_trace(type: :semantic, content_payload: {})
+      trace = client.get_trace(trace_id: stored[:trace_id])
+      trace[:trace][:last_reinforced] = Time.now.utc - (50 * 86_400)
+
+      result = client.migrate_tier
+      expect(result[:migrated]).to be >= 1
+    end
+  end
+
+  describe '#hebbian_link' do
+    it 'records coactivation' do
+      a = client.store_trace(type: :semantic, content_payload: { fact: 'a' })
+      b = client.store_trace(type: :semantic, content_payload: { fact: 'b' })
+
+      result = client.hebbian_link(trace_id_a: a[:trace_id], trace_id_b: b[:trace_id])
+      expect(result[:linked]).to be true
+    end
+  end
+
+  describe '#erase_by_type' do
+    it 'erases all traces of specified type' do
+      client.store_trace(type: :sensory, content_payload: {})
+      client.store_trace(type: :sensory, content_payload: {})
+      client.store_trace(type: :semantic, content_payload: {})
+
+      result = client.erase_by_type(type: :sensory)
+      expect(result[:erased]).to eq(2)
+
+      remaining = client.retrieve_by_type(type: :sensory)
+      expect(remaining[:count]).to eq(0)
+    end
+  end
+
+  describe '#erase_by_agent' do
+    it 'erases all traces for a partition' do
+      client.store_trace(type: :semantic, content_payload: {}, partition_id: 'agent-1')
+      client.store_trace(type: :semantic, content_payload: {}, partition_id: 'agent-1')
+      client.store_trace(type: :semantic, content_payload: {}, partition_id: 'agent-2')
+
+      result = client.erase_by_agent(partition_id: 'agent-1')
+      expect(result[:erased]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/trace/runners/traces_spec.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/trace/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Runners::Traces do
+  before(:each) { Legion::Extensions::Agentic::Memory::Trace.reset_store! }
+
+  let(:client) { Legion::Extensions::Agentic::Memory::Trace::Client.new }
+
+  describe '#store_trace' do
+    it 'stores a semantic trace and returns id' do
+      result = client.store_trace(type: :semantic, content_payload: { fact: 'test' })
+      expect(result[:trace_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:trace_type]).to eq(:semantic)
+      expect(result[:strength]).to eq(0.5)
+    end
+
+    it 'stores all 7 trace types' do
+      Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace::TRACE_TYPES.each do |type|
+        result = client.store_trace(type: type, content_payload: {})
+        expect(result[:trace_type]).to eq(type)
+      end
+    end
+  end
+
+  describe '#get_trace' do
+    it 'retrieves a stored trace' do
+      stored = client.store_trace(type: :episodic, content_payload: { event: 'meeting' })
+      result = client.get_trace(trace_id: stored[:trace_id])
+      expect(result[:found]).to be true
+      expect(result[:trace][:content_payload]).to eq({ event: 'meeting' })
+    end
+
+    it 'returns found: false for missing traces' do
+      result = client.get_trace(trace_id: 'nonexistent')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#retrieve_by_type' do
+    it 'returns traces of specified type' do
+      client.store_trace(type: :semantic, content_payload: { fact: 'a' })
+      client.store_trace(type: :semantic, content_payload: { fact: 'b' })
+      client.store_trace(type: :episodic, content_payload: { event: 'c' })
+
+      result = client.retrieve_by_type(type: :semantic)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#retrieve_by_domain' do
+    it 'returns traces matching domain tag' do
+      client.store_trace(type: :semantic, content_payload: {}, domain_tags: ['work'])
+      client.store_trace(type: :semantic, content_payload: {}, domain_tags: ['personal'])
+
+      result = client.retrieve_by_domain(domain_tag: 'work')
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#delete_trace' do
+    it 'removes a trace' do
+      stored = client.store_trace(type: :semantic, content_payload: {})
+      client.delete_trace(trace_id: stored[:trace_id])
+      result = client.get_trace(trace_id: stored[:trace_id])
+      expect(result[:found]).to be false
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/transfer/client_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/transfer/client'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Transfer::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:learn_domain)
+    expect(client).to respond_to(:attempt_transfer)
+    expect(client).to respond_to(:set_similarity)
+    expect(client).to respond_to(:transfer_effectiveness)
+    expect(client).to respond_to(:most_transferable)
+    expect(client).to respond_to(:interference_risks)
+    expect(client).to respond_to(:transfer_report)
+    expect(client).to respond_to(:get_domain)
+  end
+end

data/spec/legion/extensions/agentic/memory/transfer/helpers/constants_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Transfer::Helpers::Constants do
+  subject(:mod) { described_class }
+
+  it 'defines MAX_DOMAINS as 200' do
+    expect(mod::MAX_DOMAINS).to eq(200)
+  end
+
+  it 'defines POSITIVE_TRANSFER_THRESHOLD as 0.6' do
+    expect(mod::POSITIVE_TRANSFER_THRESHOLD).to eq(0.6)
+  end
+
+  it 'defines NEGATIVE_TRANSFER_THRESHOLD as 0.3' do
+    expect(mod::NEGATIVE_TRANSFER_THRESHOLD).to eq(0.3)
+  end
+
+  it 'defines TRANSFER_BOOST as 0.15' do
+    expect(mod::TRANSFER_BOOST).to eq(0.15)
+  end
+
+  it 'defines INTERFERENCE_PENALTY as 0.1' do
+    expect(mod::INTERFERENCE_PENALTY).to eq(0.1)
+  end
+
+  it 'defines all four TRANSFER_LABELS' do
+    expect(mod::TRANSFER_LABELS.keys).to contain_exactly(:positive, :neutral, :negative, :interference)
+  end
+
+  it 'defines all three DISTANCE_LABELS' do
+    expect(mod::DISTANCE_LABELS.keys).to contain_exactly(:near, :moderate, :far)
+  end
+
+  it 'freezes TRANSFER_LABELS' do
+    expect(mod::TRANSFER_LABELS).to be_frozen
+  end
+
+  it 'freezes DISTANCE_LABELS' do
+    expect(mod::DISTANCE_LABELS).to be_frozen
+  end
+end