lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/archaeology/helpers/artifact_spec.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology::Helpers::Artifact do
+  let(:artifact) do
+    described_class.new(
+      type: :pattern, domain: :cognitive,
+      content: 'test content', depth_level: :surface
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(artifact.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets artifact_type as symbol' do
+      expect(artifact.artifact_type).to eq :pattern
+    end
+
+    it 'sets domain' do
+      expect(artifact.domain).to eq :cognitive
+    end
+
+    it 'sets content as string' do
+      expect(artifact.content).to eq 'test content'
+    end
+
+    it 'sets depth_level' do
+      expect(artifact.depth_level).to eq :surface
+    end
+
+    it 'defaults preservation to DEFAULT_PRESERVATION' do
+      expect(artifact.preservation_quality).to be_within(0.01).of(0.5)
+    end
+
+    it 'allows custom preservation' do
+      a = described_class.new(type: :skill, domain: :emotional,
+                              content: 'x', depth_level: :deep, preservation: 0.9)
+      expect(a.preservation_quality).to eq 0.9
+    end
+
+    it 'clamps preservation to 0.0..1.0' do
+      a = described_class.new(type: :skill, domain: :emotional,
+                              content: 'x', depth_level: :surface, preservation: 1.5)
+      expect(a.preservation_quality).to eq 1.0
+    end
+
+    it 'sets discovered_at' do
+      expect(artifact.discovered_at).to be_a Time
+    end
+
+    it 'sets origin_epoch' do
+      expect(artifact.origin_epoch).to be_a Time
+    end
+
+    it 'initializes empty contextual_links' do
+      expect(artifact.contextual_links).to eq []
+    end
+
+    it 'raises on invalid type' do
+      expect do
+        described_class.new(type: :bogus, domain: :cognitive,
+                            content: 'x', depth_level: :surface)
+      end.to raise_error(ArgumentError, /unknown artifact type/)
+    end
+
+    it 'raises on invalid domain' do
+      expect do
+        described_class.new(type: :pattern, domain: :bogus,
+                            content: 'x', depth_level: :surface)
+      end.to raise_error(ArgumentError, /unknown domain/)
+    end
+
+    it 'raises on invalid depth_level' do
+      expect do
+        described_class.new(type: :pattern, domain: :cognitive,
+                            content: 'x', depth_level: :bogus)
+      end.to raise_error(ArgumentError, /unknown depth level/)
+    end
+  end
+
+  describe '#preservation' do
+    it 'aliases preservation_quality' do
+      expect(artifact.preservation).to eq artifact.preservation_quality
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces preservation_quality' do
+      original = artifact.preservation_quality
+      artifact.decay!
+      expect(artifact.preservation_quality).to be < original
+    end
+
+    it 'reduces integrity' do
+      original = artifact.integrity
+      artifact.decay!
+      expect(artifact.integrity).to be < original
+    end
+
+    it 'clamps preservation at 0.0' do
+      30.times { artifact.decay!(rate: 0.1) }
+      expect(artifact.preservation_quality).to eq 0.0
+    end
+
+    it 'returns self for chaining' do
+      expect(artifact.decay!).to eq artifact
+    end
+  end
+
+  describe '#restore!' do
+    before { artifact.decay!(rate: 0.2) }
+
+    it 'increases preservation_quality' do
+      original = artifact.preservation_quality
+      artifact.restore!(boost: 0.1)
+      expect(artifact.preservation_quality).to be > original
+    end
+
+    it 'clamps preservation at 1.0' do
+      artifact.restore!(boost: 5.0)
+      expect(artifact.preservation_quality).to eq 1.0
+    end
+
+    it 'returns self for chaining' do
+      expect(artifact.restore!).to eq artifact
+    end
+  end
+
+  describe '#fragment?' do
+    it 'returns true when preservation < 0.3' do
+      artifact.instance_variable_set(:@preservation_quality, 0.2)
+      expect(artifact.fragment?).to be true
+    end
+
+    it 'returns false when preservation >= 0.3' do
+      expect(artifact.fragment?).to be false
+    end
+  end
+
+  describe '#well_preserved?' do
+    it 'returns true when preservation > 0.7' do
+      artifact.instance_variable_set(:@preservation_quality, 0.8)
+      expect(artifact.well_preserved?).to be true
+    end
+
+    it 'returns false when preservation <= 0.7' do
+      expect(artifact.well_preserved?).to be false
+    end
+  end
+
+  describe '#preservation_label' do
+    it 'returns label based on preservation' do
+      artifact.instance_variable_set(:@preservation_quality, 0.1)
+      expect(artifact.preservation_label).to eq :dust
+
+      artifact.instance_variable_set(:@preservation_quality, 0.9)
+      expect(artifact.preservation_label).to eq :pristine
+    end
+  end
+
+  describe '#integrity_label' do
+    it 'returns label based on integrity' do
+      artifact.instance_variable_set(:@integrity, 0.1)
+      expect(artifact.integrity_label).to eq :corrupted
+
+      artifact.instance_variable_set(:@integrity, 0.9)
+      expect(artifact.integrity_label).to eq :complete
+    end
+  end
+
+  describe '#link_to' do
+    it 'adds a contextual link' do
+      artifact.link_to('other-id')
+      expect(artifact.contextual_links).to include('other-id')
+    end
+
+    it 'does not duplicate links' do
+      artifact.link_to('same-id')
+      artifact.link_to('same-id')
+      expect(artifact.contextual_links.count('same-id')).to eq 1
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { artifact.to_h }
+
+    it 'includes all fields' do
+      %i[id artifact_type domain content depth_level preservation_quality
+         preservation_label integrity integrity_label discovered_at
+         origin_epoch contextual_links fragment well_preserved ancient].each do |key|
+        expect(hash).to have_key(key)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology::Helpers::Constants do
+  let(:c) { described_class }
+
+  it 'defines MAX_ARTIFACTS' do
+    expect(c::MAX_ARTIFACTS).to eq 500
+  end
+
+  it 'defines MAX_SITES' do
+    expect(c::MAX_SITES).to eq 50
+  end
+
+  it 'has 8 artifact types' do
+    expect(c::ARTIFACT_TYPES.size).to eq 8
+  end
+
+  it 'has 8 domain types' do
+    expect(c::DOMAIN_TYPES.size).to eq 8
+  end
+
+  it 'has 5 depth levels' do
+    expect(c::EXCAVATION_DEPTH_LEVELS.size).to eq 5
+  end
+
+  it 'has depth rarity weights for each level' do
+    c::EXCAVATION_DEPTH_LEVELS.each do |level|
+      expect(c::DEPTH_RARITY_WEIGHTS).to have_key(level)
+    end
+  end
+
+  describe '.label_for' do
+    it 'returns matching label' do
+      expect(c.label_for(c::PRESERVATION_LABELS, 0.1)).to eq :dust
+      expect(c.label_for(c::PRESERVATION_LABELS, 0.9)).to eq :pristine
+    end
+
+    it 'returns last label for out-of-range' do
+      expect(c.label_for(c::PRESERVATION_LABELS, 999)).to eq :pristine
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/archaeology/helpers/excavation_site_spec.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology::Helpers::ExcavationSite do
+  let(:constants) { Legion::Extensions::Agentic::Memory::Archaeology::Helpers::Constants }
+  let(:site) { described_class.new(domain: :cognitive) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(site.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets domain' do
+      expect(site.domain).to eq :cognitive
+    end
+
+    it 'starts at surface depth' do
+      expect(site.current_depth).to eq :surface
+    end
+
+    it 'starts with no artifacts' do
+      expect(site.artifacts_found).to be_empty
+    end
+
+    it 'records started_at as Time' do
+      expect(site.started_at).to be_a Time
+    end
+
+    it 'raises on invalid domain' do
+      expect do
+        described_class.new(domain: :invalid_domain)
+      end.to raise_error(ArgumentError, /unknown domain/)
+    end
+  end
+
+  describe '#dig_deeper!' do
+    it 'advances depth from surface to shallow' do
+      site.dig_deeper!
+      expect(site.current_depth).to eq :shallow
+    end
+
+    it 'advances through all levels' do
+      (constants::EXCAVATION_DEPTH_LEVELS.size - 1).times { site.dig_deeper! }
+      expect(site.current_depth).to eq :bedrock
+    end
+
+    it 'returns true when advancing' do
+      expect(site.dig_deeper!).to be true
+    end
+
+    it 'returns false at bedrock' do
+      4.times { site.dig_deeper! }
+      expect(site.dig_deeper!).to be false
+    end
+  end
+
+  describe '#excavate!' do
+    it 'returns an Artifact' do
+      expect(site.excavate!).to be_a(
+        Legion::Extensions::Agentic::Memory::Archaeology::Helpers::Artifact
+      )
+    end
+
+    it 'adds artifact to artifacts_found' do
+      site.excavate!
+      expect(site.artifacts_found.size).to eq 1
+    end
+
+    it 'creates artifact at current depth' do
+      site.dig_deeper!
+      expect(site.excavate!.depth_level).to eq :shallow
+    end
+
+    it 'creates artifact in site domain' do
+      expect(site.excavate!.domain).to eq :cognitive
+    end
+
+    it 'creates artifact with valid type' do
+      expect(constants::ARTIFACT_TYPES).to include(site.excavate!.artifact_type)
+    end
+  end
+
+  describe '#survey' do
+    it 'returns hash with expected keys' do
+      %i[id domain current_depth depth_label artifacts_count
+         complete started_at].each do |key|
+        expect(site.survey).to have_key(key)
+      end
+    end
+
+    it 'returns correct artifact count after excavation' do
+      site.excavate!
+      expect(site.survey[:artifacts_count]).to eq 1
+    end
+  end
+
+  describe '#complete?' do
+    it 'is false initially' do
+      expect(site).not_to be_complete
+    end
+
+    it 'is true at bedrock' do
+      4.times { site.dig_deeper! }
+      expect(site).to be_complete
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes artifacts array' do
+      site.excavate!
+      h = site.to_h
+      expect(h).to have_key(:artifacts)
+      expect(h[:artifacts].first).to have_key(:id)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/archaeology/runners/cognitive_archaeology_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Archaeology::Runners::CognitiveArchaeology do
+  let(:engine) { Legion::Extensions::Agentic::Memory::Archaeology::Helpers::ArchaeologyEngine.new }
+  let(:runner) { described_class }
+
+  describe '.create_site' do
+    it 'creates a site successfully' do
+      result = runner.create_site(domain: :cognitive, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:site][:domain]).to eq :cognitive
+    end
+
+    it 'returns failure for invalid domain' do
+      result = runner.create_site(domain: :invalid_domain_xyz, engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:error]).to be_a String
+    end
+  end
+
+  describe '.dig' do
+    let(:site) { engine.create_site(domain: :cognitive) }
+
+    it 'digs successfully' do
+      result = runner.dig(site_id: site.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:dug]).to be true
+    end
+
+    it 'returns failure for unknown site' do
+      result = runner.dig(site_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.excavate' do
+    let(:site) { engine.create_site(domain: :cognitive) }
+
+    it 'excavates successfully' do
+      result = runner.excavate(site_id: site.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:artifact]).to be_a Hash
+    end
+
+    it 'returns failure for unknown site' do
+      result = runner.excavate(site_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.restore_artifact' do
+    it 'restores an artifact' do
+      site = engine.create_site(domain: :cognitive)
+      a = engine.excavate(site_id: site.id)
+      a.decay!(rate: 0.3)
+      result = runner.restore_artifact(artifact_id: a.id, boost: 0.2, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown artifact' do
+      result = runner.restore_artifact(artifact_id: 'bad', boost: 0.1, engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.list_artifacts' do
+    before do
+      site = engine.create_site(domain: :cognitive)
+      3.times { engine.excavate(site_id: site.id) }
+    end
+
+    it 'lists all artifacts' do
+      result = runner.list_artifacts(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq 3
+    end
+
+    it 'filters by domain' do
+      result = runner.list_artifacts(engine: engine, domain: :cognitive)
+      expect(result[:count]).to eq 3
+    end
+
+    it 'filters by non-matching domain' do
+      result = runner.list_artifacts(engine: engine, domain: :emotional)
+      expect(result[:count]).to eq 0
+    end
+  end
+
+  describe '.archaeology_status' do
+    it 'returns status report' do
+      result = runner.archaeology_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to be_a Hash
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/compression/helpers/compression_engine_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Compression::Helpers::CompressionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:chunk) { engine.store_chunk(label: 'test') }
+
+  describe '#store_chunk' do
+    it 'returns an InformationChunk' do
+      expect(chunk).to be_a(Legion::Extensions::Agentic::Memory::Compression::Helpers::InformationChunk)
+    end
+
+    it 'increases chunk count' do
+      chunk
+      expect(engine.to_h[:total_chunks]).to eq(1)
+    end
+
+    it 'accepts type and size' do
+      c = engine.store_chunk(label: 'big', chunk_type: :episodic, original_size: 5.0)
+      expect(c.chunk_type).to eq(:episodic)
+      expect(c.original_size).to eq(5.0)
+    end
+  end
+
+  describe '#compress_chunk' do
+    it 'reduces the chunk compressed_size' do
+      original = chunk.compressed_size
+      engine.compress_chunk(chunk_id: chunk.id)
+      expect(chunk.compressed_size).to be < original
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.compress_chunk(chunk_id: 'fake')).to be_nil
+    end
+  end
+
+  describe '#decompress_chunk' do
+    it 'increases compressed_size after compression' do
+      engine.compress_chunk(chunk_id: chunk.id)
+      small = chunk.compressed_size
+      engine.decompress_chunk(chunk_id: chunk.id)
+      expect(chunk.compressed_size).to be > small
+    end
+  end
+
+  describe '#abstract_chunks' do
+    it 'creates an abstraction from multiple chunks' do
+      c1 = engine.store_chunk(label: 'a')
+      c2 = engine.store_chunk(label: 'b')
+      abstraction = engine.abstract_chunks(chunk_ids:         [c1.id, c2.id],
+                                           abstraction_label: 'combined')
+      expect(abstraction).to be_a(Legion::Extensions::Agentic::Memory::Compression::Helpers::InformationChunk)
+      expect(abstraction.chunk_type).to eq(:abstract)
+    end
+
+    it 'returns nil for empty chunk_ids' do
+      expect(engine.abstract_chunks(chunk_ids: ['fake'], abstraction_label: 'x')).to be_nil
+    end
+  end
+
+  describe '#compress_all' do
+    it 'compresses every stored chunk' do
+      3.times { |i| engine.store_chunk(label: "c#{i}") }
+      count = engine.compress_all
+      expect(count).to eq(3)
+    end
+  end
+
+  describe '#chunks_by_type' do
+    it 'filters by type' do
+      engine.store_chunk(label: 'epi', chunk_type: :episodic)
+      engine.store_chunk(label: 'sem', chunk_type: :semantic)
+      result = engine.chunks_by_type(chunk_type: :episodic)
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe '#average_compression_ratio' do
+    it 'returns 0.0 with no chunks' do
+      expect(engine.average_compression_ratio).to eq(0.0)
+    end
+
+    it 'increases after compression' do
+      engine.store_chunk(label: 'a')
+      engine.compress_all
+      expect(engine.average_compression_ratio).to be > 0.0
+    end
+  end
+
+  describe '#average_fidelity' do
+    it 'returns 1.0 with no chunks' do
+      expect(engine.average_fidelity).to eq(1.0)
+    end
+
+    it 'decreases after compression' do
+      engine.store_chunk(label: 'a')
+      engine.compress_all
+      expect(engine.average_fidelity).to be < 1.0
+    end
+  end
+
+  describe '#overall_compression_ratio' do
+    it 'returns 0.0 with no chunks' do
+      expect(engine.overall_compression_ratio).to eq(0.0)
+    end
+  end
+
+  describe '#compression_report' do
+    it 'includes all report fields' do
+      chunk
+      report = engine.compression_report
+      expect(report).to include(
+        :total_chunks, :total_abstractions, :average_compression_ratio,
+        :overall_compression_ratio, :average_fidelity,
+        :total_original_size, :total_compressed_size, :highly_compressed_count
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(
+        :total_chunks, :total_abstractions,
+        :average_compression_ratio, :average_fidelity
+      )
+    end
+  end
+
+  describe 'pruning' do
+    it 'prunes oldest chunk when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Memory::Compression::Helpers::Constants::MAX_CHUNKS', 3)
+      eng = described_class.new
+      4.times { |i| eng.store_chunk(label: "c#{i}") }
+      expect(eng.to_h[:total_chunks]).to eq(3)
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Compression::Helpers::Constants do
+  let(:klass) { Class.new { include Legion::Extensions::Agentic::Memory::Compression::Helpers::Constants } }
+
+  describe 'COMPRESSION_LABELS' do
+    it 'is a frozen hash' do
+      expect(klass::COMPRESSION_LABELS).to be_a(Hash).and be_frozen
+    end
+
+    it 'covers the full 0..1 range' do
+      labels = klass::COMPRESSION_LABELS
+      [0.0, 0.3, 0.5, 0.7, 0.9].each do |val|
+        match = labels.find { |range, _| range.cover?(val) }
+        expect(match).not_to be_nil, "no label for #{val}"
+      end
+    end
+  end
+
+  describe 'FIDELITY_LABELS' do
+    it 'is a frozen hash' do
+      expect(klass::FIDELITY_LABELS).to be_a(Hash).and be_frozen
+    end
+  end
+
+  describe 'CHUNK_TYPES' do
+    it 'is a frozen array of symbols' do
+      expect(klass::CHUNK_TYPES).to be_a(Array).and be_frozen
+      expect(klass::CHUNK_TYPES).to all(be_a(Symbol))
+    end
+
+    it 'includes semantic and episodic' do
+      expect(klass::CHUNK_TYPES).to include(:semantic, :episodic)
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'has positive MAX_CHUNKS' do
+      expect(klass::MAX_CHUNKS).to be > 0
+    end
+
+    it 'has COMPRESSION_RATE between 0 and 1' do
+      expect(klass::COMPRESSION_RATE).to be_between(0.0, 1.0)
+    end
+
+    it 'has MIN_FIDELITY between 0 and 1' do
+      expect(klass::MIN_FIDELITY).to be_between(0.0, 1.0)
+    end
+  end
+end