lex-agentic-memory 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67778a6febdad1ae0a13004c17e1b3ddc045b49d634771aace21c103b0f6dd61
-  data.tar.gz: cc2bf829f1148699ef2a125239c6ab61095237c7fe74214aefbe9461692f0a20
+  metadata.gz: 0a4e4cd5cb55b0bcb654b44c0db73ee734142186f9644301e69abe95edee2ddb
+  data.tar.gz: 935663fa7f445a49611f707e83c8de9519822ef28492664e23fba71f4d82af20
 SHA512:
-  metadata.gz: 819f261ce1f0695201afe3baf912ea5250401940c124289e82d68b9a1c1e209988663c6bbbc75d92638ce9d594dcb688bcdc32bfd555491f5de7f96ebbe078a9
-  data.tar.gz: cf7a2eabc74347b03e5c3275a61f3ba44667225533cce82f943fd5e7a948a7ae04e88f5b04f660b573ab23bce15a71a01964d4dbc8c756917fe227e944700e66
+  metadata.gz: 19a3751371051af37741c3907832b1f2558912ab508a52ce72c2e47e1045ea207a56abcbc2a1ad6d546f72b8e6de4cedc9a6c3c8ab968df27afc51866dd60aca
+  data.tar.gz: 2406cc17b24e58554824439d78d578e07b5d13e3a8b63bcd701dacb2f751f82d94c6c79e35030e8af610304aab09cb4020bb92654c1106b1ac171bfe781872ac

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## [Unreleased]
+## [0.1.2] - 2026-03-20
+
+### Added
+- `Trace::Helpers::Snapshot`: cognitive state persistence with MessagePack serialization and SHA-512/Ed25519 signing
+- Snapshot save, restore, list, and prune operations with auto-prune on save
+- GAIA lifecycle hooks: auto-save on `service.shutting_down`, auto-restore on `gaia.started`
+- `msgpack` gem dependency
+
+## [0.1.1] - 2026-03-18
+
+### Changed
+- Enforce NODE_TYPES validation in SemanticPriming::PrimingNetwork#add_node (returns nil for invalid types)
 
 ## [0.1.0] - 2026-03-18
 

data/README.md

@@ -1,13 +1,58 @@
 # lex-agentic-memory
 
-LEX agentic memory domain: episodic, semantic, and working memory
+Domain consolidation gem for memory storage, retrieval, and consolidation. Bundles 18 source extensions into one loadable unit under `Legion::Extensions::Agentic::Memory`.
 
-## Sub-modules
+## Overview
 
-*(populated as extensions are consolidated)*
+**Gem**: `lex-agentic-memory`
+**Version**: 0.1.1
+**Namespace**: `Legion::Extensions::Agentic::Memory`
+
+## Sub-Modules
+
+| Sub-Module | Source Gem | Purpose |
+|---|---|---|
+| `Memory::Trace` | `lex-memory` | Memory trace storage, power-law decay, Hebbian association, tiered retrieval |
+| `Memory::Episodic` | `lex-episodic-buffer` | Baddeley & Hitch episodic buffer — integrates working memory channels |
+| `Memory::Semantic` | `lex-semantic-memory` | Long-term conceptual knowledge — spreading activation |
+| `Memory::SemanticPriming` | `lex-semantic-priming` | Prior exposure boosts retrieval speed for related concepts |
+| `Memory::SemanticSatiation` | `lex-semantic-satiation` | Repeated activation reduces salience — cognitive desensitization |
+| `Memory::SourceMonitoring` | `lex-source-monitoring` | Attribution of memories to origin source |
+| `Memory::Transfer` | `lex-transfer-learning` | Knowledge transfer between domains |
+| `Memory::Archaeology` | `lex-cognitive-archaeology` | Excavates dormant or deeply buried traces |
+| `Memory::Paleontology` | `lex-cognitive-paleontology` | Excavating old knowledge layers |
+| `Memory::Palimpsest` | `lex-cognitive-palimpsest` | Layered memory overwriting — recovering original layers |
+| `Memory::Compression` | `lex-cognitive-compression` | Memory compression for storage efficiency |
+| `Memory::Hologram` | `lex-cognitive-hologram` | Distributed memory storage with holographic properties |
+| `Memory::Offloading` | `lex-cognitive-offloading` | Externalizing memory to reduce cognitive load |
+| `Memory::Nostalgia` | `lex-cognitive-nostalgia` | Nostalgic retrieval bias — past warmth enhancement |
+| `Memory::Echo` | `lex-cognitive-echo` | Echo/resonance of past experiences |
+| `Memory::EchoChamber` | `lex-cognitive-echo-chamber` | Self-reinforcing memory patterns |
+| `Memory::ImmuneMemory` | `lex-cognitive-immune-memory` | Immune-style memory for threat patterns |
+| `Memory::Reserve` | `lex-cognitive-reserve` | Cognitive reserve capacity |
+
+## Actors
+
+- `Memory::Episodic::Actors::Decay` — interval actor, decays episodic buffer entries
+- `Memory::Semantic::Actors::Decay` — interval actor, decays semantic memory activation
+- `Memory::SourceMonitoring::Actors::Decay` — interval actor, decays source monitoring confidence
+- `Memory::Trace::Actors::Decay` — runs every 60s, executes `decay_cycle`
+- `Memory::Trace::Actors::TierMigration` — runs every 300s, migrates traces between tiers
 
 ## Installation
 
 ```ruby
 gem 'lex-agentic-memory'
 ```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # 1795 examples, 0 failures
+bundle exec rubocop      # 0 offenses
+```
+
+## License
+
+MIT

data/lex-agentic-memory.gemspec

@@ -24,6 +24,8 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'msgpack', '~> 1.7'
+
   spec.add_development_dependency 'rspec', '~> 3.13'
   spec.add_development_dependency 'rubocop', '~> 1.60'
   spec.add_development_dependency 'rubocop-rspec', '~> 2.26'

data/lib/legion/extensions/agentic/memory/semantic_priming/helpers/priming_network.rb

@@ -16,6 +16,8 @@ module Legion
               end
 
               def add_node(label:, node_type: :concept)
+                return nil unless NODE_TYPES.include?(node_type)
+
                 prune_nodes_if_needed
                 node = SemanticNode.new(label: label, node_type: node_type)
                 @nodes[node.id] = node

data/lib/legion/extensions/agentic/memory/semantic_priming/version.rb

@@ -5,7 +5,7 @@ module Legion
     module Agentic
       module Memory
         module SemanticPriming
-          VERSION = '0.1.0'
+          VERSION = '0.1.1'
         end
       end
     end

data/lib/legion/extensions/agentic/memory/trace/helpers/snapshot.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'msgpack'
+require 'fileutils'
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Trace
+          module Helpers
+            module Snapshot
+              class << self
+                def save_snapshot(agent_id:)
+                  state = gather_state(agent_id)
+                  packed = MessagePack.pack(state)
+                  signed = sign_data(packed, agent_id)
+
+                  dir = snapshot_dir(agent_id)
+                  FileUtils.mkdir_p(dir)
+                  filename = "#{Time.now.utc.strftime('%Y%m%d%H%M%S%L')}_#{SecureRandom.hex(4)}.snapshot"
+                  path = File.join(dir, filename)
+                  File.binwrite(path, signed)
+
+                  prune_snapshots(agent_id: agent_id)
+                  { success: true, path: path, size: signed.bytesize }
+                end
+
+                def restore_snapshot(agent_id:)
+                  path = latest_snapshot_path(agent_id)
+                  return { success: false, reason: :no_snapshot } unless path
+
+                  raw = File.binread(path)
+                  return { success: false, reason: :too_small } if raw.bytesize < 65
+
+                  signature = raw[-64..]
+                  packed = raw[0..-65]
+
+                  unless verify_data(packed, signature, agent_id)
+                    Legion::Logging.warn "[snapshot] signature verification failed for #{agent_id}" if defined?(Legion::Logging)
+                    return { success: false, reason: :invalid_signature }
+                  end
+
+                  state = MessagePack.unpack(packed, symbolize_keys: true)
+                  distribute_state(state)
+                  { success: true, agent_id: agent_id, timestamp: state[:timestamp] }
+                rescue StandardError => e
+                  Legion::Logging.warn "[snapshot] restore failed: #{e.message}" if defined?(Legion::Logging)
+                  { success: false, reason: :error, message: e.message }
+                end
+
+                def list_snapshots(agent_id:)
+                  dir = snapshot_dir(agent_id)
+                  return { success: true, snapshots: [] } unless Dir.exist?(dir)
+
+                  files = Dir.glob(File.join(dir, '*.snapshot')).map do |f|
+                    { filename: File.basename(f), size: File.size(f), mtime: File.mtime(f) }
+                  end
+                  { success: true, snapshots: files }
+                end
+
+                def prune_snapshots(agent_id:, max_count: 10)
+                  dir = snapshot_dir(agent_id)
+                  return { success: true, pruned: 0 } unless Dir.exist?(dir)
+
+                  files = Dir.glob(File.join(dir, '*.snapshot'))
+                  excess = files.size - max_count
+                  return { success: true, pruned: 0 } if excess <= 0
+
+                  files.first(excess).each { |f| File.delete(f) }
+                  { success: true, pruned: excess }
+                end
+
+                private
+
+                def snapshot_dir(agent_id)
+                  base = Legion::Settings.dig(:snapshot, :directory) if defined?(Legion::Settings)
+                  File.join(base || File.expand_path('~/.legionio/snapshots'), agent_id.to_s)
+                end
+
+                def latest_snapshot_path(agent_id)
+                  dir = snapshot_dir(agent_id)
+                  return nil unless Dir.exist?(dir)
+
+                  Dir.glob(File.join(dir, '*.snapshot')).max
+                end
+
+                def gather_state(agent_id)
+                  state = { agent_id: agent_id, schema_version: 1, timestamp: Time.now.utc.iso8601 }
+
+                  store = Legion::Extensions::Agentic::Memory::Trace.shared_store
+                  state[:memory_traces] = if store.respond_to?(:all_traces)
+                                            traces = store.all_traces
+                                            traces.is_a?(Array) ? traces : traces.values
+                                          else
+                                            []
+                                          end
+
+                  state[:personality_state] = {}
+                  state[:mood_state] = {}
+                  state[:trust_scores] = {}
+                  state[:reflection_history] = []
+                  state
+                end
+
+                def distribute_state(state)
+                  return unless state[:memory_traces]
+
+                  store = Legion::Extensions::Agentic::Memory::Trace.shared_store
+                  if store.respond_to?(:restore_traces)
+                    store.restore_traces(state[:memory_traces])
+                  elsif store.respond_to?(:store)
+                    state[:memory_traces].each { |t| store.store(t) }
+                  end
+                end
+
+                def sign_data(data, _agent_id)
+                  if defined?(Legion::Crypt) && Legion::Crypt.respond_to?(:ed25519_sign)
+                    signature = Legion::Crypt.ed25519_sign(data)
+                    data + signature
+                  else
+                    require 'digest'
+                    hash = Digest::SHA512.digest(data)
+                    data + hash[0, 64]
+                  end
+                end
+
+                def verify_data(data, signature, _agent_id)
+                  if defined?(Legion::Crypt) && Legion::Crypt.respond_to?(:ed25519_verify)
+                    Legion::Crypt.ed25519_verify(data, signature)
+                  else
+                    require 'digest'
+                    expected = Digest::SHA512.digest(data)[0, 64]
+                    signature == expected
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Agentic
       module Memory
-        VERSION = '0.1.0'
+        VERSION = '0.1.2'
       end
     end
   end

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

@@ -33,3 +33,45 @@ module Legion
     end
   end
 end
+
+# Snapshot lifecycle hooks
+if defined?(Legion::Events)
+  snapshot_enabled = begin
+    Legion::Settings.dig(:snapshot, :enabled)
+  rescue StandardError
+    true
+  end
+  if snapshot_enabled
+    require 'legion/extensions/agentic/memory/trace/helpers/snapshot'
+
+    Legion::Events.on('service.shutting_down') do
+      next unless begin
+        Legion::Settings.dig(:snapshot, :auto_save_on_shutdown)
+      rescue StandardError
+        true
+      end
+
+      agent_id = begin
+        Legion::Settings.dig(:agent, :id)
+      rescue StandardError
+        nil
+      end || 'default'
+      Legion::Extensions::Agentic::Memory::Trace::Helpers::Snapshot.save_snapshot(agent_id: agent_id)
+    end
+
+    Legion::Events.once('gaia.started') do
+      next unless begin
+        Legion::Settings.dig(:snapshot, :auto_restore_on_boot)
+      rescue StandardError
+        true
+      end
+
+      agent_id = begin
+        Legion::Settings.dig(:agent, :id)
+      rescue StandardError
+        nil
+      end || 'default'
+      Legion::Extensions::Agentic::Memory::Trace::Helpers::Snapshot.restore_snapshot(agent_id: agent_id)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/echo/cognitive_echo_spec.rb

@@ -2,6 +2,6 @@
 
 RSpec.describe Legion::Extensions::Agentic::Memory::Echo do
   it 'has a version number' do
-    expect(Legion::Extensions::Agentic::Memory::Echo::VERSION).to eq('0.1.0')
+    expect(Legion::Extensions::Agentic::Memory::Echo::VERSION).not_to be_nil
   end
 end

data/spec/legion/extensions/agentic/memory/episodic/episodic_buffer_spec.rb

@@ -9,7 +9,7 @@ RSpec.describe Legion::Extensions::Agentic::Memory::Episodic do
     expect(Legion::Extensions::Agentic::Memory::Episodic::VERSION).to be_a(String)
   end
 
-  it 'version is 0.1.0' do
-    expect(Legion::Extensions::Agentic::Memory::Episodic::VERSION).to eq('0.1.0')
+  it 'version is a semver string' do
+    expect(Legion::Extensions::Agentic::Memory::Episodic::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
   end
 end

data/spec/legion/extensions/agentic/memory/gaia_hooks_spec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'GAIA snapshot hooks' do
+  it 'entry point has snapshot lifecycle hooks block' do
+    entry_point = File.read(
+      File.expand_path('../../../../../lib/legion/extensions/agentic/memory.rb', __dir__)
+    )
+    expect(entry_point).to include('service.shutting_down')
+    expect(entry_point).to include('gaia.started')
+    expect(entry_point).to include('Trace::Helpers::Snapshot')
+  end
+end

data/spec/legion/extensions/agentic/memory/hologram/cognitive_hologram_spec.rb

@@ -2,7 +2,7 @@
 
 RSpec.describe Legion::Extensions::Agentic::Memory::Hologram do
   it 'defines a VERSION constant' do
-    expect(described_class::VERSION).to eq('0.1.0')
+    expect(described_class::VERSION).not_to be_nil
   end
 
   it 'defines the Helpers module' do

data/spec/legion/extensions/agentic/memory/immune_memory/cognitive_immune_memory_spec.rb

@@ -2,6 +2,6 @@
 
 RSpec.describe Legion::Extensions::Agentic::Memory::ImmuneMemory do
   it 'has a version number' do
-    expect(Legion::Extensions::Agentic::Memory::ImmuneMemory::VERSION).to eq('0.1.0')
+    expect(Legion::Extensions::Agentic::Memory::ImmuneMemory::VERSION).not_to be_nil
   end
 end

data/spec/legion/extensions/agentic/memory/semantic_priming/helpers/priming_network_spec.rb

@@ -18,6 +18,18 @@ RSpec.describe Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::Pr
       found = network.find_node_by_label(label: 'stored')
       expect(found.id).to eq(node.id)
     end
+
+    it 'rejects invalid node_type' do
+      expect(network.add_node(label: 'bad', node_type: :kinesthetic)).to be_nil
+    end
+
+    it 'accepts all valid NODE_TYPES' do
+      constants = Legion::Extensions::Agentic::Memory::SemanticPriming::Helpers::Constants
+      constants::NODE_TYPES.each do |nt|
+        node = network.add_node(label: "node_#{nt}", node_type: nt)
+        expect(node).not_to be_nil
+      end
+    end
   end
 
   describe '#remove_node' do

data/spec/legion/extensions/agentic/memory/semantic_priming/semantic_priming_spec.rb

@@ -2,6 +2,6 @@
 
 RSpec.describe Legion::Extensions::Agentic::Memory::SemanticPriming do
   it 'has a version number' do
-    expect(Legion::Extensions::Agentic::Memory::SemanticPriming::VERSION).to eq('0.1.0')
+    expect(Legion::Extensions::Agentic::Memory::SemanticPriming::VERSION).not_to be_nil
   end
 end

data/spec/legion/extensions/agentic/memory/trace/helpers/snapshot_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/agentic/memory/trace/helpers/snapshot'
+require 'tmpdir'
+require 'msgpack'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Trace::Helpers::Snapshot do
+  let(:tmpdir) { Dir.mktmpdir('legion-snapshot-test') }
+  let(:agent_id) { 'test-agent' }
+
+  before do
+    allow(described_class).to receive(:snapshot_dir) do |aid|
+      File.join(tmpdir, aid.to_s)
+    end
+    Legion::Extensions::Agentic::Memory::Trace.reset_store!
+  end
+
+  after do
+    FileUtils.rm_rf(tmpdir)
+  end
+
+  describe '.save_snapshot' do
+    it 'creates a snapshot file' do
+      result = described_class.save_snapshot(agent_id: agent_id)
+      expect(result[:success]).to be true
+      expect(result[:path]).to end_with('.snapshot')
+      expect(File.exist?(result[:path])).to be true
+    end
+
+    it 'creates a non-empty file' do
+      result = described_class.save_snapshot(agent_id: agent_id)
+      expect(File.size(result[:path])).to be > 64
+    end
+  end
+
+  describe '.restore_snapshot' do
+    it 'restores from latest snapshot' do
+      described_class.save_snapshot(agent_id: agent_id)
+      result = described_class.restore_snapshot(agent_id: agent_id)
+      expect(result[:success]).to be true
+      expect(result[:agent_id]).to eq(agent_id)
+    end
+
+    it 'returns no_snapshot when none exists' do
+      result = described_class.restore_snapshot(agent_id: 'nonexistent')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:no_snapshot)
+    end
+
+    it 'detects tampered snapshot' do
+      save_result = described_class.save_snapshot(agent_id: agent_id)
+      data = File.binread(save_result[:path])
+      data[0] = (data[0].ord ^ 0xFF).chr
+      File.binwrite(save_result[:path], data)
+
+      result = described_class.restore_snapshot(agent_id: agent_id)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '.list_snapshots' do
+    it 'lists saved snapshots' do
+      described_class.save_snapshot(agent_id: agent_id)
+      described_class.save_snapshot(agent_id: agent_id)
+      result = described_class.list_snapshots(agent_id: agent_id)
+      expect(result[:success]).to be true
+      expect(result[:snapshots].size).to eq(2)
+    end
+
+    it 'returns empty list when no snapshots exist' do
+      result = described_class.list_snapshots(agent_id: 'no-such-agent')
+      expect(result[:snapshots]).to be_empty
+    end
+  end
+
+  describe '.prune_snapshots' do
+    it 'removes excess snapshots keeping newest' do
+      15.times { described_class.save_snapshot(agent_id: agent_id) }
+      result = described_class.prune_snapshots(agent_id: agent_id, max_count: 5)
+      expect(result[:pruned]).to eq(5)
+
+      list = described_class.list_snapshots(agent_id: agent_id)
+      expect(list[:snapshots].size).to eq(5)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-memory
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Esity
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -198,6 +212,7 @@ files:
 - lib/legion/extensions/agentic/memory/trace/helpers/cache_store.rb
 - lib/legion/extensions/agentic/memory/trace/helpers/decay.rb
 - lib/legion/extensions/agentic/memory/trace/helpers/error_tracer.rb
+- lib/legion/extensions/agentic/memory/trace/helpers/snapshot.rb
 - lib/legion/extensions/agentic/memory/trace/helpers/store.rb
 - lib/legion/extensions/agentic/memory/trace/helpers/trace.rb
 - lib/legion/extensions/agentic/memory/trace/local_migrations/20260316000001_create_memory_traces.rb
@@ -244,6 +259,7 @@ files:
 - spec/legion/extensions/agentic/memory/episodic/helpers/episodic_binding_spec.rb
 - spec/legion/extensions/agentic/memory/episodic/helpers/episodic_store_spec.rb
 - spec/legion/extensions/agentic/memory/episodic/runners/episodic_buffer_spec.rb
+- spec/legion/extensions/agentic/memory/gaia_hooks_spec.rb
 - spec/legion/extensions/agentic/memory/hologram/client_spec.rb
 - spec/legion/extensions/agentic/memory/hologram/cognitive_hologram_spec.rb
 - spec/legion/extensions/agentic/memory/hologram/helpers/constants_spec.rb
@@ -309,6 +325,7 @@ files:
 - spec/legion/extensions/agentic/memory/trace/batch_decay_spec.rb
 - spec/legion/extensions/agentic/memory/trace/client_spec.rb
 - spec/legion/extensions/agentic/memory/trace/helpers/decay_spec.rb
+- spec/legion/extensions/agentic/memory/trace/helpers/snapshot_spec.rb
 - spec/legion/extensions/agentic/memory/trace/helpers/store_spec.rb
 - spec/legion/extensions/agentic/memory/trace/helpers/trace_spec.rb
 - spec/legion/extensions/agentic/memory/trace/local_persistence_spec.rb