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:

gem 'lex-memory'

Usage

Storing Traces

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

# 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)

# 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

# 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

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:

store = Legion::Extensions::Memory.shared_store
store.save_to_local    # persist to SQLite
store.load_from_local  # restore from SQLite

Development

bundle install
bundle exec rspec
bundle exec rubocop

License

MIT