lex-narrative-self 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 336a5c4eb91fca23131bab8a2566fe8398bba7541dcc68e1c437c6a1a8c9067d
+  data.tar.gz: c43bcd16be3bca9f7a320b40e62e2dcb3aa08b5a0953685674924bbdb0269a4f
+SHA512:
+  metadata.gz: cf610636d9fce5865681b7b7dc143926f99bcb91b2b26d8526e2f23cfdbe0bade5ce1c746eaa8667e417f7c1de1dabc8f14dc9ec24ae86c72accbf6d1376ca33
+  data.tar.gz: a61cad3fb3f040028f902dec6c6f99a4a9291caadef117277f29421872403b2ca909e87ef938f5668facaa427daf9667dcca9ea1123681bd8a5c7d9269bbf0c9

data/README.md

@@ -0,0 +1,69 @@
+# lex-narrative-self
+
+Autobiographical narrative and self-concept for the LegionIO cognitive architecture. Models the agent's personal history as episodes, threads, and an evolving identity.
+
+## What It Does
+
+Maintains an autobiography of personal episodes — each with a significance score, emotional valence, domain, and tags. Episodes are grouped into narrative threads by thematic overlap. A self-concept emerges from the statistical pattern of episode types over time via exponential moving average. Older low-significance episodes fade naturally.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::NarrativeSelf::Client.new
+
+# Record an experience
+client.record_episode(
+  description:       'Successfully debugged a complex race condition',
+  episode_type:      :achievement,
+  domain:            :engineering,
+  significance:      0.8,
+  emotional_valence: 0.7,
+  tags:              ['debugging', 'concurrency']
+)
+
+# Create a narrative thread to track a recurring theme
+client.create_thread(theme: 'debugging', domain: :engineering)
+
+# Retrieve recent and significant episodes
+client.recent_episodes(count: 5)
+client.significant_episodes(min_significance: 0.7)
+
+# Self-concept summary
+summary = client.self_summary
+# => {
+#   total_episodes: 42,
+#   dominant_types: [:achievement, :discovery, :insight],
+#   dominant_domains: [:engineering, :coordination],
+#   active_threads: ['debugging', 'planning'],
+#   self_concept: { achievement: 0.72, discovery: 0.61, ... },
+#   narrative_richness: 0.64
+# }
+
+# Tick decay (call each processing cycle)
+client.update_narrative_self
+```
+
+## Episode Types
+
+`:achievement`, `:failure`, `:discovery`, `:connection`, `:conflict`, `:resolution`, `:insight`, `:surprise`, `:decision`, `:transition`, `:reflection`
+
+## Significance Labels
+
+| Range | Label |
+|---|---|
+| 0.8+ | `:pivotal` |
+| 0.6–0.8 | `:important` |
+| 0.3–0.6 | `:routine` |
+| < 0.3 | `:minor` |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrative_self/helpers/constants'
+require 'legion/extensions/narrative_self/helpers/episode'
+require 'legion/extensions/narrative_self/helpers/narrative_thread'
+require 'legion/extensions/narrative_self/helpers/autobiography'
+require 'legion/extensions/narrative_self/runners/narrative_self'
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      class Client
+        include Runners::NarrativeSelf
+
+        attr_reader :autobiography
+
+        def initialize(autobiography: nil, **)
+          @autobiography = autobiography || Helpers::Autobiography.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_self/helpers/autobiography.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      module Helpers
+        class Autobiography
+          include Constants
+
+          attr_reader :episodes, :threads, :self_concept
+
+          def initialize
+            @episodes     = []
+            @threads      = []
+            @self_concept = {}
+          end
+
+          def record_episode(description:, episode_type: :insight, domain: :general,
+                             significance: nil, emotional_valence: 0.0, tags: [])
+            episode = Episode.new(
+              description:       description,
+              episode_type:      episode_type,
+              domain:            domain,
+              significance:      significance,
+              emotional_valence: emotional_valence,
+              tags:              tags
+            )
+            @episodes << episode
+            auto_link_threads(episode)
+            update_self_concept(episode)
+            trim_episodes
+            episode
+          end
+
+          def find_episode(id)
+            @episodes.find { |e| e.id == id }
+          end
+
+          def recent_episodes(count = 10)
+            @episodes.last(count)
+          end
+
+          def significant_episodes(min_significance: 0.6)
+            @episodes.select { |e| e.significance >= min_significance }
+                     .sort_by { |e| -e.significance }
+          end
+
+          def episodes_by_type(episode_type)
+            @episodes.select { |e| e.episode_type == episode_type }
+          end
+
+          def episodes_in_domain(domain)
+            @episodes.select { |e| e.domain == domain }
+          end
+
+          def create_thread(theme:, domain: :general)
+            thread = NarrativeThread.new(theme: theme, domain: domain)
+            @threads << thread
+            trim_threads
+            thread
+          end
+
+          def find_thread(id)
+            @threads.find { |t| t.id == id }
+          end
+
+          def find_threads_by_theme(theme)
+            @threads.select { |t| t.theme == theme }
+          end
+
+          def strongest_threads(count = 5)
+            @threads.sort_by { |t| -t.strength }.first(count)
+          end
+
+          def timeline(window: MAX_TIMELINE_WINDOW)
+            @episodes.last(window).map(&:to_h)
+          end
+
+          def self_summary
+            top_types = episode_type_distribution.first(3).map(&:first)
+            top_domains = domain_distribution.first(3).map(&:first)
+            top_threads = strongest_threads(3).map(&:theme)
+            {
+              total_episodes:     @episodes.size,
+              dominant_types:     top_types,
+              dominant_domains:   top_domains,
+              active_threads:     top_threads,
+              self_concept:       @self_concept.dup,
+              pivotal_count:      @episodes.count { |e| e.label == :pivotal },
+              narrative_richness: narrative_richness
+            }
+          end
+
+          def decay_all
+            @episodes.each(&:decay)
+            @episodes.reject!(&:faded?)
+            @threads.each(&:decay)
+            @threads.reject!(&:weak?)
+          end
+
+          def to_h
+            {
+              episode_count:    @episodes.size,
+              thread_count:     @threads.size,
+              self_concept:     @self_concept.dup,
+              by_type:          @episodes.group_by(&:episode_type).transform_values(&:size),
+              by_domain:        @episodes.group_by(&:domain).transform_values(&:size),
+              avg_significance: avg_significance
+            }
+          end
+
+          private
+
+          def auto_link_threads(episode)
+            @threads.each do |thread|
+              relevance = episode.matches_tags?([thread.theme])
+              relevance += 0.2 if episode.domain == thread.domain
+              next unless relevance >= THREAD_MATCH_THRESHOLD
+
+              thread.add_episode(episode.id)
+              episode.link_thread(thread.id)
+            end
+          end
+
+          def update_self_concept(episode)
+            trait = episode.episode_type
+            current = @self_concept.fetch(trait, 0.0)
+            signal = episode.significance
+            @self_concept[trait] = ((TRAIT_ALPHA * signal) + ((1.0 - TRAIT_ALPHA) * current)).clamp(0.0, 1.0)
+            trim_self_concept
+          end
+
+          def trim_self_concept
+            return unless @self_concept.size > MAX_SELF_CONCEPT_TRAITS
+
+            sorted = @self_concept.sort_by { |_, v| v }
+            @self_concept = sorted.last(MAX_SELF_CONCEPT_TRAITS).to_h
+          end
+
+          def trim_episodes
+            return unless @episodes.size > MAX_EPISODES
+
+            @episodes.sort_by!(&:significance)
+            @episodes.shift(@episodes.size - MAX_EPISODES)
+          end
+
+          def trim_threads
+            return unless @threads.size > MAX_THREADS
+
+            @threads.sort_by!(&:strength)
+            @threads.shift(@threads.size - MAX_THREADS)
+          end
+
+          def episode_type_distribution
+            @episodes.group_by(&:episode_type)
+                     .transform_values(&:size)
+                     .sort_by { |_, count| -count }
+          end
+
+          def domain_distribution
+            @episodes.group_by(&:domain)
+                     .transform_values(&:size)
+                     .sort_by { |_, count| -count }
+          end
+
+          def avg_significance
+            return 0.0 if @episodes.empty?
+
+            @episodes.sum(&:significance) / @episodes.size
+          end
+
+          def narrative_richness
+            return 0.0 if @episodes.empty?
+
+            type_diversity = @episodes.map(&:episode_type).uniq.size.to_f / EPISODE_TYPES.size
+            thread_activity = @threads.empty? ? 0.0 : @threads.count { |t| t.size > 1 }.to_f / @threads.size
+            ((type_diversity + thread_activity) / 2.0).clamp(0.0, 1.0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_self/helpers/constants.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      module Helpers
+        module Constants
+          MAX_EPISODES        = 500
+          MAX_THREADS         = 50
+          MAX_CHAPTER_SIZE    = 20
+          EPISODE_DECAY       = 0.005
+          THREAD_DECAY        = 0.01
+          SIGNIFICANCE_FLOOR  = 0.05
+          SIGNIFICANCE_ALPHA  = 0.15
+          DEFAULT_SIGNIFICANCE = 0.5
+          EMOTIONAL_BOOST = 0.3
+          THREAD_MATCH_THRESHOLD = 0.3
+          MAX_SELF_CONCEPT_TRAITS = 30
+          TRAIT_ALPHA         = 0.1
+          MAX_TIMELINE_WINDOW = 100
+
+          SIGNIFICANCE_LABELS = {
+            (0.8..)     => :pivotal,
+            (0.6...0.8) => :important,
+            (0.3...0.6) => :routine,
+            (..0.3)     => :minor
+          }.freeze
+
+          EPISODE_TYPES = %i[
+            achievement failure discovery connection
+            conflict resolution insight surprise
+            decision transition reflection
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_self/helpers/episode.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      module Helpers
+        class Episode
+          include Constants
+
+          attr_reader :id, :description, :episode_type, :domain, :significance,
+                      :emotional_valence, :tags, :created_at, :thread_ids
+
+          def initialize(description:, episode_type: :insight, domain: :general,
+                         significance: nil, emotional_valence: 0.0, tags: [])
+            @id                = SecureRandom.uuid
+            @description       = description
+            @episode_type      = episode_type
+            @domain            = domain
+            @significance      = significance || DEFAULT_SIGNIFICANCE
+            @emotional_valence = emotional_valence.clamp(-1.0, 1.0)
+            @tags              = tags
+            @created_at        = Time.now.utc
+            @thread_ids        = []
+          end
+
+          def boost(amount)
+            emotional_factor = @emotional_valence.abs * EMOTIONAL_BOOST
+            @significance = [(@significance + amount + emotional_factor), 1.0].min
+          end
+
+          def decay
+            @significance = [(@significance - EPISODE_DECAY), 0.0].max
+          end
+
+          def faded?
+            @significance < SIGNIFICANCE_FLOOR
+          end
+
+          def label
+            SIGNIFICANCE_LABELS.each do |range, lbl|
+              return lbl if range.cover?(@significance)
+            end
+            :minor
+          end
+
+          def link_thread(thread_id)
+            @thread_ids << thread_id unless @thread_ids.include?(thread_id)
+          end
+
+          def matches_tags?(query_tags)
+            return false if query_tags.empty? || @tags.empty?
+
+            overlap = (@tags & query_tags).size
+            overlap.to_f / query_tags.size
+          end
+
+          def to_h
+            {
+              id:                @id,
+              description:       @description,
+              episode_type:      @episode_type,
+              domain:            @domain,
+              significance:      @significance,
+              emotional_valence: @emotional_valence,
+              label:             label,
+              tags:              @tags.dup,
+              thread_ids:        @thread_ids.dup,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_self/helpers/narrative_thread.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      module Helpers
+        class NarrativeThread
+          include Constants
+
+          attr_reader :id, :theme, :domain, :strength, :episode_ids, :created_at
+
+          def initialize(theme:, domain: :general)
+            @id          = SecureRandom.uuid
+            @theme       = theme
+            @domain      = domain
+            @strength    = 0.5
+            @episode_ids = []
+            @created_at  = Time.now.utc
+          end
+
+          def add_episode(episode_id)
+            return if @episode_ids.include?(episode_id)
+
+            @episode_ids << episode_id
+            @episode_ids.shift if @episode_ids.size > MAX_CHAPTER_SIZE
+            reinforce
+          end
+
+          def reinforce
+            @strength = [@strength + 0.1, 1.0].min
+          end
+
+          def decay
+            @strength = [(@strength - THREAD_DECAY), 0.0].max
+          end
+
+          def weak?
+            @strength < SIGNIFICANCE_FLOOR
+          end
+
+          def size
+            @episode_ids.size
+          end
+
+          def to_h
+            {
+              id:         @id,
+              theme:      @theme,
+              domain:     @domain,
+              strength:   @strength,
+              episodes:   @episode_ids.size,
+              created_at: @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_self/runners/narrative_self.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      module Runners
+        module NarrativeSelf
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def record_episode(description:, episode_type: :insight, domain: :general,
+                             significance: nil, emotional_valence: 0.0, tags: [], **)
+            episode = autobiography.record_episode(
+              description:       description,
+              episode_type:      episode_type,
+              domain:            domain,
+              significance:      significance,
+              emotional_valence: emotional_valence,
+              tags:              tags
+            )
+            Legion::Logging.debug "[narrative_self] recorded episode=#{episode_type} domain=#{domain} sig=#{episode.significance.round(3)}"
+            { success: true, episode: episode.to_h }
+          end
+
+          def recent_episodes(count: 10, **)
+            episodes = autobiography.recent_episodes(count)
+            { success: true, episodes: episodes.map(&:to_h), count: episodes.size }
+          end
+
+          def significant_episodes(min_significance: 0.6, **)
+            episodes = autobiography.significant_episodes(min_significance: min_significance)
+            { success: true, episodes: episodes.map(&:to_h), count: episodes.size }
+          end
+
+          def episodes_by_type(episode_type:, **)
+            episodes = autobiography.episodes_by_type(episode_type)
+            { success: true, episodes: episodes.map(&:to_h), count: episodes.size }
+          end
+
+          def create_thread(theme:, domain: :general, **)
+            thread = autobiography.create_thread(theme: theme, domain: domain)
+            Legion::Logging.debug "[narrative_self] created thread=#{theme} domain=#{domain}"
+            { success: true, thread: thread.to_h }
+          end
+
+          def strongest_threads(count: 5, **)
+            threads = autobiography.strongest_threads(count)
+            { success: true, threads: threads.map(&:to_h), count: threads.size }
+          end
+
+          def timeline(window: nil, **)
+            w = window || Helpers::Constants::MAX_TIMELINE_WINDOW
+            entries = autobiography.timeline(window: w)
+            { success: true, timeline: entries, count: entries.size }
+          end
+
+          def self_summary(**)
+            summary = autobiography.self_summary
+            Legion::Logging.debug "[narrative_self] summary: episodes=#{summary[:total_episodes]} richness=#{summary[:narrative_richness].round(3)}"
+            { success: true, summary: summary }
+          end
+
+          def update_narrative_self(**)
+            autobiography.decay_all
+            Legion::Logging.debug "[narrative_self] tick: episodes=#{autobiography.episodes.size} threads=#{autobiography.threads.size}"
+            { success: true, episode_count: autobiography.episodes.size, thread_count: autobiography.threads.size }
+          end
+
+          def narrative_self_stats(**)
+            { success: true, stats: autobiography.to_h }
+          end
+
+          private
+
+          def autobiography
+            @autobiography ||= Helpers::Autobiography.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_self/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/narrative_self.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrative_self/version'
+require 'legion/extensions/narrative_self/helpers/constants'
+require 'legion/extensions/narrative_self/helpers/episode'
+require 'legion/extensions/narrative_self/helpers/narrative_thread'
+require 'legion/extensions/narrative_self/helpers/autobiography'
+require 'legion/extensions/narrative_self/runners/narrative_self'
+require 'legion/extensions/narrative_self/client'
+
+module Legion
+  module Extensions
+    module NarrativeSelf
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: lex-narrative-self
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Models autonoetic consciousness — maintains an autobiographical narrative
+  of episodes, narrative threads, and an evolving self-concept that emerges from the
+  pattern of lived experience.
+email:
+- matt@iverson.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/narrative_self.rb
+- lib/legion/extensions/narrative_self/client.rb
+- lib/legion/extensions/narrative_self/helpers/autobiography.rb
+- lib/legion/extensions/narrative_self/helpers/constants.rb
+- lib/legion/extensions/narrative_self/helpers/episode.rb
+- lib/legion/extensions/narrative_self/helpers/narrative_thread.rb
+- lib/legion/extensions/narrative_self/runners/narrative_self.rb
+- lib/legion/extensions/narrative_self/version.rb
+homepage: https://github.com/LegionIO/lex-narrative-self
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Autobiographical narrative and self-concept for LegionIO
+test_files: []