lex-memory 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 887236dfa6fe8f5f792dc57af29a84b1404bac3938fd3482644e15cbdfde394d
+  data.tar.gz: 751161d389e5b4c2a4ecb690b31c0a2223a2e4a7d205623c40585131dedbd75b
+SHA512:
+  metadata.gz: 25fdd67e7aa1b5ed17fbe66253c9a4b925cfd0d82dcc2ccafe63a08f06f7a7126c8b33b99163d415043b43c3456be6a6ff43d1912de27580d255e2e033e176f0
+  data.tar.gz: eda7ac4517f976d8b6f2672c872487e649970df67c1cb89a8249205f8c4294717f965871f6f43e7ab3deb9feefd68df15d1bb2af2f9a57002f2b956036a26f4b

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,53 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.2] - 2026-03-16
+
+### Fixed
+- Add missing `require 'client'` to entry point — `Memory::Client` was never auto-loaded at runtime, causing dream cycle and other consumers to skip memory integration
+
+## [0.1.1] - 2026-03-16
+
+### Fixed
+- Strip default procs from associations hash before Memcached serialization in `CacheStore#flush` to prevent `can't dump hash with default proc` marshalling error
+
+### Added
+- `spec/legion/extensions/memory/actors/decay_spec.rb` (7 examples) — tests for the Decay actor (Every 60s)
+- `spec/legion/extensions/memory/actors/tier_migration_spec.rb` (7 examples) — tests for the TierMigration actor (Every 300s)
+
+## [0.1.0] - 2026-03-13
+
+### Added
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,129 @@
+# lex-memory
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Memory trace system for the LegionIO cognitive architecture. Implements typed trace storage, power-law decay with emotional modulation, reinforcement (with imprint window boost), Hebbian association, tiered retrieval scoring, and selective erasure.
+
+## Gem Info
+
+- **Gem name**: `lex-memory`
+- **Version**: `0.1.2`
+- **Module**: `Legion::Extensions::Memory`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/memory/
+  version.rb
+  helpers/
+    trace.rb          # Trace structure, TRACE_TYPES, decay constants, new_trace factory
+    decay.rb          # compute_decay, compute_reinforcement, compute_retrieval_score, compute_storage_tier
+    store.rb          # In-memory Store class (hash-backed, not DB-persisted)
+    cache_store.rb    # Cache-backed Store using Legion::Cache (Memcached/Redis) — flush/reload API
+    error_tracer.rb   # Wraps Legion::Logging.error/fatal to auto-create episodic traces (60s debounce)
+  runners/
+    traces.rb         # store_trace, get_trace, retrieve_by_type/domain/associated/ranked,
+                      # delete_trace, retrieve_and_reinforce
+    consolidation.rb  # reinforce, decay_cycle, migrate_tier, hebbian_link, erase_by_type/agent
+  actors/
+    decay.rb          # Every 60s - calls decay_cycle
+    tier_migration.rb # Every 300s - calls migrate_tier
+  local_migrations/
+    20260316000001_create_memory_traces.rb      # SQLite persistence for traces
+    20260316000002_create_memory_associations.rb # SQLite persistence for associations
+spec/
+  legion/extensions/memory/
+    helpers/
+      trace_spec.rb
+      decay_spec.rb
+      store_spec.rb
+    runners/
+      traces_spec.rb
+      consolidation_spec.rb
+    client_spec.rb
+    local_persistence_spec.rb
+  legion/extensions/memory_spec.rb
+```
+
+## Key Constants (Helpers::Trace)
+
+```ruby
+E_WEIGHT               = 0.3    # emotional intensity weight on decay
+R_AMOUNT               = 0.10   # base reinforcement per call
+IMPRINT_MULTIPLIER     = 3.0    # multiplier during imprint window
+ARCHIVE_THRESHOLD      = 0.05   # traces below this are archived
+AUTO_FIRE_THRESHOLD    = 0.85   # procedural auto-fire threshold
+PRUNE_THRESHOLD        = 0.01   # traces below this are deleted
+HOT_TIER_WINDOW        = 86_400     # 24h
+WARM_TIER_WINDOW       = 7_776_000  # 90 days
+RETRIEVAL_RECENCY_HALF = 3600       # 1h half-life for recency scoring
+ASSOCIATION_BONUS      = 0.15   # Hebbian association retrieval bonus
+MAX_ASSOCIATIONS       = 20     # max Hebbian links per trace
+COACTIVATION_THRESHOLD = 3      # co-activations before link forms
+```
+
+## Store (Development vs Production)
+
+`Helpers::Store` is an in-memory hash-backed store for development/testing. `Helpers::CacheStore` is a cache-backed store backed by `Legion::Cache` (Memcached/Redis) for shared cross-process access.
+
+**Shared store singleton**: `Legion::Extensions::Memory.shared_store` returns a process-wide store instance. All runner modules (`Traces`, `Consolidation`), the `Client` class, and ad-hoc runners created via `Object.new.extend(Runners::Traces)` all delegate to this singleton. This ensures traces written by one component (ErrorTracer, coldstart, tick retrieval) are visible to all others (dream cycle, predictions, cortex). Auto-selects `CacheStore` when `Legion::Cache.connected?` returns true, falls back to `Store` otherwise. `Memory.reset_store!` clears the singleton (used in test setup).
+
+Both stores implement the same API:
+- `store(trace)` / `get(trace_id)` / `delete(trace_id)`
+- `retrieve_by_type(type, min_strength:, limit:)`
+- `retrieve_by_domain(domain_tag, min_strength:, limit:)`
+- `retrieve_associated(trace_id, min_strength:, limit:)`
+- `record_coactivation(id_a, id_b)` - increments counter, links when >= COACTIVATION_THRESHOLD
+- `all_traces(min_strength:)` / `count` / `firmware_traces`
+- `walk_associations(start_id:, max_hops:, min_strength:)` - BFS traversal with cycle detection
+
+`CacheStore` additionally provides:
+- `flush` - writes local state to cache (only when dirty)
+- `reload` - pulls latest state from cache (after another process wrote)
+- TTL: 24 hours (`TRACES_KEY = 'legion:memory:traces'`, `ASSOC_KEY = 'legion:memory:associations'`)
+
+**SQLite persistence**: `Store#save_to_local` and `Store#load_from_local` persist traces and associations to SQLite via `Legion::Data::Local`. Two local migrations create `memory_traces` and `memory_associations` tables. This enables trace survival across process restarts without requiring Memcached.
+
+**Client class**: `Legion::Extensions::Memory::Client` holds `@default_store` injected via constructor, includes both `Runners::Traces` and `Runners::Consolidation`.
+
+## Runners
+
+### Traces
+CRUD operations. All runners accept `store:` keyword to inject a custom store instance (used in specs). Default store delegates to `Memory.shared_store`.
+
+Additional method:
+- `retrieve_and_reinforce(limit: 10)` — retrieves top N traces by strength, increments `reinforcement_count` and `last_reinforced` on each (skips firmware traces); used by lex-cortex's `memory_retrieval` phase
+
+### Consolidation
+Lifecycle operations:
+- `decay_cycle` - iterates all traces, applies power-law decay, prunes below PRUNE_THRESHOLD
+- `reinforce` - boosts trace strength (firmware traces are skipped)
+- `migrate_tier` - reassigns storage_tier based on last_reinforced timestamp
+- `hebbian_link` - records co-activation, defers actual linking to Store
+- `erase_by_type` / `erase_by_agent` - bulk delete (used by lex-privatecore)
+
+## Integration Points
+
+- **lex-coldstart**: `imprint_active:` flag passed to `reinforce` for the 3x multiplier
+- **lex-emotion**: `emotional_intensity` on traces slows decay (E_WEIGHT)
+- **lex-privatecore**: calls `erase_by_type` / `erase_by_agent` for cryptographic erasure
+- **lex-tick**: `memory_retrieval` and `memory_consolidation` phases call into this extension
+
+## Development Notes
+
+- `new_trace` validates trace type and origin; raises `ArgumentError` on invalid values
+- `firmware` traces: `base_decay_rate = 0.0`, `compute_decay` short-circuits to return `peak_strength`
+- Retrieval score formula: `strength * recency_factor * emotional_weight * association_bonus`
+- `retrieve_ranked` re-scores by retrieval score, not stored strength
+- The gemspec uses `git ls-files` (differs from other LEX gems using `Dir.glob`) — both approaches are fine
+- Actor namespace is `module Actor` (singular), not `Actors`
+- `content_embedding:` is a field on trace hashes (reserved for future vector search)
+- `CacheStore` stores all traces in a single Memcached key (`legion:memory:traces`) — large trace sets require sufficient Memcached item size limits
+- `CacheStore#flush` only writes when `@dirty` is true; safe to call frequently
+- `retrieve_and_reinforce` increments `reinforcement_count` in-place on the trace hash and re-stores it — this makes retrieval itself a reinforcing action

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'sequel'
+  gem 'simplecov'
+  gem 'sqlite3'
+end

data/Gemfile.lock

@@ -0,0 +1,99 @@
+PATH
+  remote: .
+  specs:
+    lex-memory (0.1.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    mini_portile2 (2.8.9)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rspec_junit_formatter (0.6.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    sequel (5.102.0)
+      bigdecimal
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    sqlite3 (2.9.2)
+      mini_portile2 (~> 2.8.0)
+    sqlite3 (2.9.2-arm64-darwin)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-memory!
+  rake
+  rspec
+  rspec_junit_formatter
+  rubocop
+  rubocop-rspec
+  sequel
+  simplecov
+  sqlite3
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,158 @@
+# lex-memory
+
+Memory trace system for brain-modeled agentic AI. Implements trace storage, power-law decay, reinforcement, Hebbian association, and tiered retrieval.
+
+## Overview
+
+`lex-memory` models the agent's long-term memory as a collection of typed traces. Traces decay over time according to a power-law formula, are strengthened by reinforcement, and form associative links through co-activation (Hebbian learning). Storage tiers (hot/warm/cold) reflect recency of access.
+
+## Trace Types
+
+| Type | Starting Strength | Base Decay Rate | Notes |
+|------|------------------|----------------|-------|
+| `firmware` | 1.0 | 0.0 | Never decays — hardcoded values |
+| `identity` | 1.0 | 0.001 | Self-model |
+| `procedural` | 0.4 | 0.005 | How-to knowledge |
+| `trust` | 0.3 | 0.008 | Agent trust records |
+| `semantic` | 0.5 | 0.010 | Conceptual knowledge |
+| `episodic` | 0.6 | 0.020 | Event memories |
+| `sensory` | 0.4 | 0.100 | Transient perceptual data |
+
+## Storage Tiers
+
+| Tier | Condition |
+|------|-----------|
+| `hot` | Last accessed within 24 hours |
+| `warm` | Last accessed within 90 days |
+| `cold` | Older than 90 days |
+| `erased` | Strength <= 0.01 (pruned) |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-memory'
+```
+
+## Usage
+
+### Storing Traces
+
+```ruby
+require 'legion/extensions/memory'
+
+# Store a new trace
+result = Legion::Extensions::Memory::Runners::Traces.store_trace(
+  type: :episodic,
+  content_payload: { event: "first conversation", summary: "..." },
+  emotional_intensity: 0.7,
+  domain_tags: [:conversation]
+)
+# => { trace_id: "uuid", trace_type: :episodic, strength: 0.6 }
+```
+
+### Retrieving Traces
+
+```ruby
+# By type
+Legion::Extensions::Memory::Runners::Traces.retrieve_by_type(type: :semantic, min_strength: 0.3)
+
+# By domain tag
+Legion::Extensions::Memory::Runners::Traces.retrieve_by_domain(domain_tag: :conversation)
+
+# Associated traces (Hebbian links)
+Legion::Extensions::Memory::Runners::Traces.retrieve_associated(trace_id: "uuid")
+
+# Ranked retrieval (composite score: strength * recency * emotion * association)
+Legion::Extensions::Memory::Runners::Traces.retrieve_ranked(trace_ids: ["uuid1", "uuid2"])
+```
+
+### Active Retrieval (used by lex-cortex)
+
+```ruby
+# Retrieve top N traces by strength and mark them as reinforced
+Legion::Extensions::Memory::Runners::Traces.retrieve_and_reinforce(limit: 10)
+# => { count: 10, traces: [...] }
+```
+
+### Memory Consolidation
+
+```ruby
+# Reinforce a trace (strengthens it; 3x multiplier during imprint window)
+Legion::Extensions::Memory::Runners::Consolidation.reinforce(
+  trace_id: "uuid",
+  imprint_active: false
+)
+
+# Run decay cycle (called each tick)
+Legion::Extensions::Memory::Runners::Consolidation.decay_cycle(tick_count: 1)
+
+# Migrate traces to appropriate storage tiers
+Legion::Extensions::Memory::Runners::Consolidation.migrate_tier
+
+# Form Hebbian link between co-activated traces
+Legion::Extensions::Memory::Runners::Consolidation.hebbian_link(
+  trace_id_a: "uuid1",
+  trace_id_b: "uuid2"
+)
+
+# Selective erasure (for lex-privatecore integration)
+Legion::Extensions::Memory::Runners::Consolidation.erase_by_type(type: :sensory)
+Legion::Extensions::Memory::Runners::Consolidation.erase_by_agent(partition_id: "agent-123")
+```
+
+## Decay Formula
+
+```
+new_strength = peak_strength * (ticks_since_access + 1)^(-base_decay_rate / (1 + emotional_intensity * 0.3))
+```
+
+High emotional intensity slows decay. Firmware traces have `base_decay_rate = 0.0` and never decay.
+
+## Reinforcement Formula
+
+```
+new_strength = min(1.0, current_strength + 0.10 * imprint_multiplier)
+```
+
+During the imprint window (first 7 days), the multiplier is 3.0.
+
+## Hebbian Association
+
+Traces that co-activate 3 or more times form a permanent associative link. Each trace stores up to 20 links. Linked traces receive a 15% bonus in retrieval scoring.
+
+## ErrorTracer
+
+`Helpers::ErrorTracer` wraps `Legion::Logging.error` and `fatal` to auto-create episodic traces when errors occur. A 60-second debounce prevents trace flooding from repeated errors.
+
+## Standalone Client
+
+```ruby
+client = Legion::Extensions::Memory::Client.new
+client.store_trace(type: :semantic, content_payload: { fact: "..." })
+client.retrieve_by_type(type: :semantic)
+client.decay_cycle(tick_count: 1)
+```
+
+## SQLite Persistence
+
+When `legion-data` Local is available, traces can be persisted to SQLite:
+
+```ruby
+store = Legion::Extensions::Memory.shared_store
+store.save_to_local    # persist to SQLite
+store.load_from_local  # restore from SQLite
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-memory.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/memory/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-memory'
+  spec.version       = Legion::Extensions::Memory::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Memory'
+  spec.description   = 'Memory trace system for brain-modeled agentic AI — consolidation, reinforcement, and decay'
+  spec.homepage      = 'https://github.com/LegionIO/lex-memory'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-memory'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-memory'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-memory'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-memory/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+end

data/lib/legion/extensions/memory/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Memory
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Memory::Runners::Consolidation
+          end
+
+          def runner_function
+            'decay_cycle'
+          end
+
+          def time
+            60
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/memory/actors/tier_migration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Memory
+      module Actor
+        class TierMigration < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Memory::Runners::Consolidation
+          end
+
+          def runner_function
+            'migrate_tier'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/memory/helpers/trace'
+require 'legion/extensions/memory/helpers/decay'
+require 'legion/extensions/memory/helpers/store'
+require 'legion/extensions/memory/runners/traces'
+require 'legion/extensions/memory/runners/consolidation'
+
+module Legion
+  module Extensions
+    module Memory
+      class Client
+        include Legion::Extensions::Memory::Runners::Traces
+        include Legion::Extensions::Memory::Runners::Consolidation
+
+        attr_reader :store
+
+        def initialize(store: nil, **)
+          @default_store = store || Legion::Extensions::Memory.shared_store
+        end
+
+        private
+
+        attr_reader :default_store
+      end
+    end
+  end
+end