lex-agentic-memory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 67778a6febdad1ae0a13004c17e1b3ddc045b49d634771aace21c103b0f6dd61
+  data.tar.gz: cc2bf829f1148699ef2a125239c6ab61095237c7fe74214aefbe9461692f0a20
+SHA512:
+  metadata.gz: 819f261ce1f0695201afe3baf912ea5250401940c124289e82d68b9a1c1e209988663c6bbbc75d92638ce9d594dcb688bcdc32bfd555491f5de7f96ebbe078a9
+  data.tar.gz: cf7a2eabc74347b03e5c3275a61f3ba44667225533cce82f943fd5e7a948a7ae04e88f5b04f660b573ab23bce15a71a01964d4dbc8c756917fe227e944700e66

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,13 @@
+# lex-agentic-memory
+
+LEX agentic memory domain: episodic, semantic, and working memory
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-memory'
+```

data/lex-agentic-memory.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/memory/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-memory'
+  spec.version       = Legion::Extensions::Agentic::Memory::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Memory'
+  spec.description   = 'LEX agentic memory domain: episodic, semantic, and working memory'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-memory'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-memory.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

data/lib/legion/extensions/agentic/memory/archaeology/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+          class Client
+            include Runners::CognitiveArchaeology
+
+            def initialize(engine: nil)
+              @default_engine = engine || Helpers::ArchaeologyEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/archaeology/helpers/archaeology_engine.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+          module Helpers
+            class ArchaeologyEngine
+              def initialize
+                @sites     = {}
+                @artifacts = {}
+              end
+
+              def create_site(domain:)
+                validate_site_capacity!
+                site = ExcavationSite.new(domain: domain)
+                @sites[site.id] = site
+                site
+              end
+
+              def dig(site_id:)
+                site = fetch_site!(site_id)
+                dug  = site.dig_deeper!
+                { site: site.survey, dug: dug }
+              end
+
+              def excavate(site_id:)
+                site = fetch_site!(site_id)
+                validate_artifact_capacity!
+                artifact = site.excavate!
+                @artifacts[artifact.id] = artifact
+                artifact
+              end
+
+              def restore_artifact(artifact_id:, boost: 0.15)
+                artifact = fetch_artifact!(artifact_id)
+                artifact.restore!(boost: boost)
+                artifact
+              end
+
+              def decay_all!(rate: Constants::PRESERVATION_DECAY)
+                @artifacts.each_value { |a| a.decay!(rate: rate) }
+                prune_dust!
+                @artifacts.size
+              end
+
+              def artifacts_by_type(type)
+                @artifacts.values.select { |a| a.artifact_type == type.to_sym }
+              end
+
+              def artifacts_by_domain(domain)
+                @artifacts.values.select { |a| a.domain == domain.to_sym }
+              end
+
+              def artifacts_by_depth(depth_level)
+                @artifacts.values.select do |a|
+                  a.depth_level == depth_level.to_sym
+                end
+              end
+
+              def best_preserved(limit: 10)
+                @artifacts.values.sort_by { |a| -a.preservation }.first(limit)
+              end
+
+              def most_fragile(limit: 10)
+                @artifacts.values
+                          .select(&:fragment?)
+                          .sort_by(&:preservation)
+                          .first(limit)
+              end
+
+              def site_report(site_id:)
+                fetch_site!(site_id).to_h
+              end
+
+              def archaeology_report
+                {
+                  total_artifacts:  @artifacts.size,
+                  total_sites:      @sites.size,
+                  type_breakdown:   type_breakdown,
+                  domain_breakdown: domain_breakdown,
+                  depth_breakdown:  depth_breakdown,
+                  avg_preservation: avg_preservation,
+                  avg_integrity:    avg_integrity,
+                  fragment_count:   @artifacts.values.count(&:fragment?),
+                  ancient_count:    @artifacts.values.count(&:ancient?),
+                  sites:            @sites.values.map { |s| site_summary(s) }
+                }
+              end
+
+              def all_artifacts
+                @artifacts.values
+              end
+
+              def all_sites
+                @sites.values
+              end
+
+              private
+
+              def fetch_site!(site_id)
+                @sites.fetch(site_id) do
+                  raise ArgumentError, "site not found: #{site_id.inspect}"
+                end
+              end
+
+              def fetch_artifact!(artifact_id)
+                @artifacts.fetch(artifact_id) do
+                  raise ArgumentError,
+                        "artifact not found: #{artifact_id.inspect}"
+                end
+              end
+
+              def validate_site_capacity!
+                return if @sites.size < Constants::MAX_SITES
+
+                raise ArgumentError,
+                      "site capacity reached (max #{Constants::MAX_SITES})"
+              end
+
+              def validate_artifact_capacity!
+                return if @artifacts.size < Constants::MAX_ARTIFACTS
+
+                raise ArgumentError,
+                      "artifact capacity reached (max #{Constants::MAX_ARTIFACTS})"
+              end
+
+              def prune_dust!
+                @artifacts.delete_if { |_, a| a.preservation <= 0.0 }
+              end
+
+              def type_breakdown
+                count_by(:artifact_type, Constants::ARTIFACT_TYPES)
+              end
+
+              def domain_breakdown
+                count_by(:domain, Constants::DOMAIN_TYPES)
+              end
+
+              def depth_breakdown
+                count_by(:depth_level, Constants::EXCAVATION_DEPTH_LEVELS)
+              end
+
+              def count_by(attr, values)
+                values.to_h do |v|
+                  [v, @artifacts.values.count { |a| a.public_send(attr) == v }]
+                end
+              end
+
+              def avg_preservation
+                return 0.0 if @artifacts.empty?
+
+                (@artifacts.values.sum(&:preservation) / @artifacts.size).round(10)
+              end
+
+              def avg_integrity
+                return 0.0 if @artifacts.empty?
+
+                (@artifacts.values.sum(&:integrity) / @artifacts.size).round(10)
+              end
+
+              def site_summary(site)
+                site.survey.merge(
+                  depth_progress: depth_progress(site),
+                  artifact_types: site.artifacts_found
+                                  .each_with_object(Hash.new(0)) do |a, h|
+                                    h[a.artifact_type] += 1
+                                  end
+                )
+              end
+
+              def depth_progress(site)
+                idx   = Constants::EXCAVATION_DEPTH_LEVELS.index(site.current_depth)
+                total = Constants::EXCAVATION_DEPTH_LEVELS.size - 1
+                total.zero? ? 1.0 : (idx.to_f / total).round(4)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/archaeology/helpers/artifact.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+          module Helpers
+            class Artifact
+              attr_reader :id, :artifact_type, :domain, :content, :depth_level,
+                          :discovered_at, :origin_epoch, :contextual_links
+
+              attr_accessor :preservation_quality, :integrity
+
+              alias type artifact_type
+
+              def initialize(type:, domain:, content:, depth_level:,
+                             preservation: nil, integrity: nil,
+                             origin_epoch: nil, contextual_links: nil)
+                validate_type!(type)
+                validate_domain!(domain)
+                validate_depth!(depth_level)
+
+                @id               = SecureRandom.uuid
+                @artifact_type    = type.to_sym
+                @domain           = domain.to_sym
+                @content          = content.to_s
+                @depth_level      = depth_level.to_sym
+                pres = (preservation || Constants::DEFAULT_PRESERVATION).to_f
+                @preservation_quality = pres.clamp(0.0, 1.0).round(10)
+                @integrity        = (integrity || derive_integrity).clamp(0.0, 1.0).round(10)
+                @discovered_at    = Time.now.utc
+                @origin_epoch     = origin_epoch || (Time.now.utc - rand(0..31_536_000))
+                @contextual_links = Array(contextual_links).dup
+              end
+
+              def preservation
+                @preservation_quality
+              end
+
+              def preservation=(val)
+                @preservation_quality = val.to_f.clamp(0.0, 1.0).round(10)
+              end
+
+              def decay!(rate: Constants::PRESERVATION_DECAY)
+                @preservation_quality = (@preservation_quality - rate.abs).clamp(0.0, 1.0).round(10)
+                @integrity            = (@integrity - (rate.abs * 0.5)).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def restore!(boost: 0.15)
+                @preservation_quality = (@preservation_quality + boost.abs).clamp(0.0, 1.0).round(10)
+                @integrity            = (@integrity + (boost.abs * 0.5)).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def fragment?
+                @preservation_quality < 0.3
+              end
+
+              def well_preserved?
+                @preservation_quality > 0.7
+              end
+
+              def ancient?
+                (Time.now.utc - @origin_epoch) > 15_552_000
+              end
+
+              def preservation_label
+                match_label(Constants::PRESERVATION_LABELS, @preservation_quality)
+              end
+
+              def integrity_label
+                match_label(Constants::INTEGRITY_LABELS, @integrity)
+              end
+
+              def link_to(other_id)
+                @contextual_links << other_id unless @contextual_links.include?(other_id)
+              end
+
+              def to_h
+                {
+                  id:                   @id,
+                  type:                 @artifact_type,
+                  artifact_type:        @artifact_type,
+                  domain:               @domain,
+                  content:              @content,
+                  depth_level:          @depth_level,
+                  preservation:         @preservation_quality,
+                  preservation_quality: @preservation_quality,
+                  preservation_label:   preservation_label,
+                  integrity:            @integrity,
+                  integrity_label:      integrity_label,
+                  discovered_at:        @discovered_at,
+                  origin_epoch:         @origin_epoch,
+                  contextual_links:     @contextual_links,
+                  fragment:             fragment?,
+                  well_preserved:       well_preserved?,
+                  ancient:              ancient?
+                }
+              end
+
+              private
+
+              def derive_integrity
+                depth_mod = Constants::DEPTH_PRESERVATION_MODIFIER.fetch(@depth_level, 0.0)
+                (0.8 + depth_mod + rand(-0.1..0.1)).clamp(0.0, 1.0)
+              end
+
+              def validate_type!(type_val)
+                return if Constants::ARTIFACT_TYPES.include?(type_val.to_sym)
+
+                raise ArgumentError,
+                      "unknown artifact type: #{type_val.inspect}; " \
+                      "must be one of #{Constants::ARTIFACT_TYPES.inspect}"
+              end
+
+              def validate_domain!(domain_val)
+                return if Constants::DOMAIN_TYPES.include?(domain_val.to_sym)
+
+                raise ArgumentError,
+                      "unknown domain: #{domain_val.inspect}; " \
+                      "must be one of #{Constants::DOMAIN_TYPES.inspect}"
+              end
+
+              def validate_depth!(depth_val)
+                return if Constants::EXCAVATION_DEPTH_LEVELS.include?(depth_val.to_sym)
+
+                raise ArgumentError,
+                      "unknown depth level: #{depth_val.inspect}; " \
+                      "must be one of #{Constants::EXCAVATION_DEPTH_LEVELS.inspect}"
+              end
+
+              def match_label(label_table, value)
+                label_table.each { |range, label| return label if range.cover?(value) }
+                label_table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/archaeology/helpers/constants.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+          module Helpers
+            module Constants
+              MAX_ARTIFACTS            = 500
+              MAX_SITES                = 50
+              DEFAULT_PRESERVATION     = 0.5
+              PRESERVATION_DECAY       = 0.02
+              SEDIMENT_DENSITY_DEFAULT = 0.5
+
+              ARTIFACT_TYPES = %i[
+                pattern skill knowledge memory_fragment
+                association procedure belief schema
+              ].freeze
+
+              DOMAIN_TYPES = %i[
+                cognitive emotional procedural semantic
+                episodic social creative analytical
+              ].freeze
+
+              EXCAVATION_DEPTH_LEVELS = %i[surface shallow mid deep bedrock].freeze
+
+              EPOCH_NAMES = %i[
+                genesis formation expansion consolidation
+                crisis renewal maturation current
+              ].freeze
+
+              DEPTH_PRESERVATION_MODIFIER = {
+                surface: 0.0,
+                shallow: -0.1,
+                mid:     -0.2,
+                deep:    -0.35,
+                bedrock: -0.5
+              }.freeze
+
+              DEPTH_RARITY_WEIGHTS = {
+                surface: { pattern: 3, skill: 2, knowledge: 3, memory_fragment: 5,
+                           association: 3, procedure: 2, belief: 1, schema: 1 },
+                shallow: { pattern: 3, skill: 3, knowledge: 3, memory_fragment: 4,
+                           association: 3, procedure: 3, belief: 1, schema: 1 },
+                mid:     { pattern: 2, skill: 3, knowledge: 3, memory_fragment: 3,
+                           association: 3, procedure: 3, belief: 2, schema: 2 },
+                deep:    { pattern: 1, skill: 2, knowledge: 2, memory_fragment: 2,
+                           association: 2, procedure: 3, belief: 3, schema: 3 },
+                bedrock: { pattern: 1, skill: 1, knowledge: 1, memory_fragment: 1,
+                           association: 1, procedure: 2, belief: 4, schema: 4 }
+              }.freeze
+
+              PRESERVATION_LABELS = [
+                [0.0..0.2, :dust],
+                [0.2..0.4, :fragmented],
+                [0.4..0.6, :partial],
+                [0.6..0.8, :intact],
+                [0.8..1.0, :pristine]
+              ].freeze
+
+              INTEGRITY_LABELS = [
+                [0.0..0.3, :corrupted],
+                [0.3..0.6, :degraded],
+                [0.6..0.8, :coherent],
+                [0.8..1.0, :complete]
+              ].freeze
+
+              DENSITY_LABELS = [
+                [0.0..0.2, :friable],
+                [0.2..0.4, :loose],
+                [0.4..0.6, :moderate],
+                [0.6..0.8, :dense],
+                [0.8..1.0, :compacted]
+              ].freeze
+
+              DEPTH_LABELS = {
+                surface: 'Surface Layer (recent, well-preserved)',
+                shallow: 'Shallow Layer (familiar but fading)',
+                mid:     'Mid Layer (semi-dormant knowledge)',
+                deep:    'Deep Layer (long-dormant patterns)',
+                bedrock: 'Bedrock Layer (foundational cognitive strata)'
+              }.freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/archaeology/helpers/excavation_site.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Archaeology
+          module Helpers
+            class ExcavationSite
+              include Constants
+
+              attr_reader :id, :domain, :current_depth, :artifacts_found, :created_at
+
+              alias started_at created_at
+
+              def initialize(domain:)
+                validate_domain!(domain)
+                @id              = SecureRandom.uuid
+                @domain          = domain.to_sym
+                @current_depth   = :surface
+                @artifacts_found = []
+                @created_at      = Time.now.utc
+              end
+
+              def dig_deeper!
+                idx = EXCAVATION_DEPTH_LEVELS.index(@current_depth) || 0
+                return false if idx >= EXCAVATION_DEPTH_LEVELS.size - 1
+
+                @current_depth = EXCAVATION_DEPTH_LEVELS[idx + 1]
+                true
+              end
+
+              def complete?
+                @current_depth == EXCAVATION_DEPTH_LEVELS.last
+              end
+
+              def excavate!
+                weights  = DEPTH_RARITY_WEIGHTS.fetch(@current_depth, {})
+                art_type = weighted_pick(weights)
+                artifact = Artifact.new(type: art_type, domain: @domain,
+                                        content: "#{art_type} from #{@current_depth}",
+                                        depth_level: @current_depth,
+                                        preservation: compute_base_preservation)
+                @artifacts_found << artifact
+                artifact
+              end
+
+              def survey
+                {
+                  id:              @id,
+                  domain:          @domain,
+                  current_depth:   @current_depth,
+                  depth_label:     DEPTH_LABELS.fetch(@current_depth, 'Unknown'),
+                  artifacts_count: @artifacts_found.size,
+                  complete:        complete?,
+                  started_at:      @created_at.iso8601
+                }
+              end
+
+              def to_h
+                survey.merge(artifacts: @artifacts_found.map(&:to_h))
+              end
+
+              private
+
+              def validate_domain!(domain_val)
+                return if DOMAIN_TYPES.include?(domain_val.to_sym)
+
+                raise ArgumentError,
+                      "unknown domain: #{domain_val.inspect}; " \
+                      "must be one of #{DOMAIN_TYPES.inspect}"
+              end
+
+              def weighted_pick(weights)
+                total = weights.values.sum
+                return ARTIFACT_TYPES.sample if total.zero?
+
+                roll       = rand(total)
+                cumulative = 0
+                weights.each do |type, weight|
+                  cumulative += weight
+                  return type if roll < cumulative
+                end
+                weights.keys.last
+              end
+
+              def compute_base_preservation
+                mod = DEPTH_PRESERVATION_MODIFIER.fetch(@current_depth, 0.0)
+                (DEFAULT_PRESERVATION + mod).clamp(0.0, 1.0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end