lex-agentic-memory 0.1.36 → 0.1.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f135722a81c15e36374e61e6348db1f421db9b4fc5257bc2915d8526a9b7a145
-  data.tar.gz: 86dfb884036c9d7d8617a3a785b6b35c6cc0db413b60a9866aad04ad3e899d59
+  metadata.gz: 1d50530306440e9785fb5daf5e4b0a1b5ed7f4e8897758d63db2749b44bb3049
+  data.tar.gz: 6a92e08a370322464f1c149e6b7e3d5c0ab076d137fb6934007d7f610ec3c792
 SHA512:
-  metadata.gz: bd080984039d516a8980ed88723a34f6f8738439f55a921e572cbba852f73af3c48010cffc9fec5b134305f2e7d0f7d774d032bf8a41e88003b9f7cef8cba34a
-  data.tar.gz: 5e2fbe8775082a3e64533acce43937923b0e5f6c97cc7bcb623fc4a42f9bc21be513f824fef9ea80f13afb392da5e30648b68fd6e9a9fbadd1e1eeed985259b5
+  metadata.gz: 7b05da20183b1d7799fd2eafe2d7fe01cec596ccd4be2835197ba7ef44e55bf5c0ba7592616233949ad58de12a0c24cf555b9c68ec52daf97c25dddc79327202
+  data.tar.gz: ed22f62934d8a013e870466839d7573714a064c0d56b42fbf7d00a412cf107cf69e2f33b3c5bbd18bf8c7ddb064e8bab0db9957f03dff80cc6419d30658515e0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.37] - 2026-05-17
+### Added
+- `Memory::Diary` sub-module — per-agent chronological session diary with write, read, and search.
+- `DiaryStore` backed by `Legion::Data::Local` (SQLite) with agent-scoped isolation.
+- Local migration `20260517000001_create_memory_diary_entries` for diary table.
+- `Diary::Client` and `Runners::Diary` for runner integration (write_diary, read_diary, search_diary, diary_stats).
+- Module-level convenience API: `Memory::Diary.write`, `.read`, `.search`.
+
 ## [0.1.36] - 2026-05-17
 ### Fixed
 - `PostgresStore#db_ready?` now checks `Legion::Data.can_write?(:memory_traces)` before attempting writes, preventing `PG::InsufficientPrivilege` errors when connected with a read-only role.

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/diary/helpers/constants'
+require 'legion/extensions/agentic/memory/diary/helpers/diary_store'
+require 'legion/extensions/agentic/memory/diary/runners/diary'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Diary
+          class Client
+            include Runners::Diary
+
+            def initialize(agent_id: nil, store: nil)
+              @diary_store = store || Helpers::DiaryStore.new(agent_id: agent_id)
+            end
+
+            private
+
+            attr_reader :diary_store
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Diary
+          module Helpers
+            module Constants
+              TABLE_NAME = :memory_diary_entries
+              DEFAULT_LIMIT = 20
+              MAX_LIMIT = 200
+              MAX_CONTENT_SIZE = 65_536
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/diary/helpers/diary_store.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Diary
+          module Helpers
+            class DiaryStore
+              include Legion::Logging::Helper if defined?(Legion::Logging::Helper)
+
+              def initialize(agent_id: nil)
+                @agent_id = agent_id || resolve_agent_id
+              end
+
+              attr_reader :agent_id
+
+              def write(session_id:, content:, tags: [], metadata: {})
+                return nil unless db_ready?
+
+                entry_id = SecureRandom.uuid
+                now = Time.now.utc
+                row = {
+                  entry_id:   entry_id,
+                  agent_id:   @agent_id,
+                  session_id: session_id,
+                  content:    sanitize(content.to_s[0...Constants::MAX_CONTENT_SIZE]),
+                  tags:       tags.is_a?(Array) ? Legion::JSON.dump(tags) : '[]',
+                  metadata:   metadata.is_a?(Hash) ? Legion::JSON.dump(metadata) : '{}',
+                  created_at: now
+                }
+                db[Constants::TABLE_NAME].insert(row)
+                entry_id
+              rescue StandardError => e
+                log_warn("write failed: #{e.message}")
+                nil
+              end
+
+              def read(limit: Constants::DEFAULT_LIMIT, since: nil)
+                return [] unless db_ready?
+
+                effective_limit = [limit, Constants::MAX_LIMIT].min
+                ds = scoped_ds.order(Sequel.asc(:created_at)).limit(effective_limit)
+                ds = ds.where { created_at >= since } if since
+                ds.all.map { |row| deserialize(row) }
+              rescue StandardError => e
+                log_warn("read failed: #{e.message}")
+                []
+              end
+
+              def search(query:, limit: Constants::DEFAULT_LIMIT)
+                return [] unless db_ready?
+                return [] if query.nil? || query.strip.empty?
+
+                effective_limit = [limit, Constants::MAX_LIMIT].min
+                ds = scoped_ds
+                     .where(Sequel.like(:content, "%#{sanitize(query)}%"))
+                     .order(Sequel.desc(:created_at))
+                     .limit(effective_limit)
+                ds.all.map { |row| deserialize(row) }
+              rescue StandardError => e
+                log_warn("search failed: #{e.message}")
+                []
+              end
+
+              def get(entry_id)
+                return nil unless db_ready?
+
+                row = scoped_ds.where(entry_id: entry_id).first
+                row ? deserialize(row) : nil
+              rescue StandardError => e
+                log_warn("get failed: #{e.message}")
+                nil
+              end
+
+              def delete(entry_id)
+                return false unless db_ready?
+
+                scoped_ds.where(entry_id: entry_id).delete
+                true
+              rescue StandardError => e
+                log_warn("delete failed: #{e.message}")
+                false
+              end
+
+              def count
+                return 0 unless db_ready?
+
+                scoped_ds.count
+              rescue StandardError => e
+                log_warn("count failed: #{e.message}")
+                0
+              end
+
+              def db_ready?
+                defined?(Legion::Data::Local) &&
+                  Legion::Data::Local.respond_to?(:connected?) &&
+                  Legion::Data::Local.connected? &&
+                  Legion::Data::Local.connection&.table_exists?(Constants::TABLE_NAME)
+              rescue StandardError => e
+                log_warn("db_ready?: #{e.message}")
+                false
+              end
+
+              private
+
+              def db
+                Legion::Data::Local.connection
+              end
+
+              def scoped_ds
+                db[Constants::TABLE_NAME].where(agent_id: @agent_id)
+              end
+
+              def resolve_agent_id
+                Legion::Settings.dig(:agent, :id) || 'default'
+              rescue StandardError => e
+                log_warn("resolve_agent_id: #{e.message}")
+                'default'
+              end
+
+              def deserialize(row)
+                {
+                  entry_id:   row[:entry_id],
+                  agent_id:   row[:agent_id],
+                  session_id: row[:session_id],
+                  content:    row[:content],
+                  tags:       parse_json_array(row[:tags]),
+                  metadata:   parse_json_hash(row[:metadata]),
+                  created_at: row[:created_at]
+                }
+              end
+
+              def parse_json_array(raw)
+                return [] if raw.nil? || raw.to_s.strip.empty?
+
+                result = Legion::JSON.load(raw)
+                result.is_a?(Array) ? result : []
+              rescue StandardError => e
+                log_warn("parse_json_array: #{e.message}")
+                []
+              end
+
+              def parse_json_hash(raw)
+                return {} if raw.nil? || raw.to_s.strip.empty?
+
+                result = Legion::JSON.load(raw)
+                result.is_a?(Hash) ? result : {}
+              rescue StandardError => e
+                log_warn("parse_json_hash: #{e.message}")
+                {}
+              end
+
+              def sanitize(value)
+                return value unless value.is_a?(String)
+
+                value.delete("\x00")
+              end
+
+              def log_warn(message)
+                log.warn "[diary] #{message}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/memory/diary/local_migrations/20260517000001_create_memory_diary_entries.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  change do
+    create_table(:memory_diary_entries) do
+      primary_key :id
+      String   :entry_id,   size: 36, null: false, unique: true
+      String   :agent_id,   size: 64, null: false
+      String   :session_id, size: 64
+      String   :content,    text: true, null: false
+      String   :tags,       text: true
+      String   :metadata,   text: true
+      DateTime :created_at, null: false
+
+      index :agent_id
+      index %i[agent_id created_at]
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Diary
+          module Runners
+            module Diary
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex, false)
+
+              def write_diary(session_id:, content:, tags: [], metadata: {}, store: nil, **)
+                s = store || diary_store
+                entry_id = s.write(session_id: session_id, content: content, tags: tags, metadata: metadata)
+                if entry_id
+                  log.debug("[diary] wrote entry=#{entry_id} agent=#{s.agent_id} session=#{session_id}")
+                  { success: true, entry_id: entry_id }
+                else
+                  { success: false, error: 'diary store not available' }
+                end
+              end
+
+              def read_diary(limit: Helpers::Constants::DEFAULT_LIMIT, since: nil, store: nil, **)
+                s = store || diary_store
+                return { success: false, error: 'diary store not available' } unless s.db_ready?
+
+                entries = s.read(limit: limit, since: since)
+                log.debug("[diary] read #{entries.size} entries for agent=#{s.agent_id}")
+                { success: true, entries: entries, count: entries.size }
+              end
+
+              def search_diary(query:, limit: Helpers::Constants::DEFAULT_LIMIT, store: nil, **)
+                s = store || diary_store
+                return { success: false, error: 'diary store not available' } unless s.db_ready?
+
+                entries = s.search(query: query, limit: limit)
+                log.debug("[diary] search query=#{query} found=#{entries.size} agent=#{s.agent_id}")
+                { success: true, entries: entries, count: entries.size }
+              end
+
+              def diary_stats(store: nil, **)
+                s = store || diary_store
+                { success: true, agent_id: s.agent_id, entry_count: s.count, available: s.db_ready? }
+              end
+
+              private
+
+              def diary_store
+                @diary_store ||= Helpers::DiaryStore.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Diary
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/memory/diary/version'
+require 'legion/extensions/agentic/memory/diary/helpers/constants'
+require 'legion/extensions/agentic/memory/diary/helpers/diary_store'
+require 'legion/extensions/agentic/memory/diary/runners/diary'
+require 'legion/extensions/agentic/memory/diary/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Memory
+        module Diary
+          class << self
+            def write(session_id:, content:, agent_id: nil, tags: [], metadata: {})
+              store = Helpers::DiaryStore.new(agent_id: agent_id)
+              store.write(session_id: session_id, content: content, tags: tags, metadata: metadata)
+            end
+
+            def read(agent_id: nil, limit: Helpers::Constants::DEFAULT_LIMIT, since: nil)
+              store = Helpers::DiaryStore.new(agent_id: agent_id)
+              store.read(limit: limit, since: since)
+            end
+
+            def search(query:, agent_id: nil, limit: Helpers::Constants::DEFAULT_LIMIT)
+              store = Helpers::DiaryStore.new(agent_id: agent_id)
+              store.search(query: query, limit: limit)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  if defined?(Legion::Data::Local)
+    Legion::Data::Local.register_migrations(
+      name: :diary,
+      path: File.join(__dir__, 'diary', 'local_migrations')
+    )
+  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.36'
+        VERSION = '0.1.37'
       end
     end
   end

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

@@ -21,6 +21,7 @@ require_relative 'memory/semantic_satiation'
 require_relative 'memory/source_monitoring'
 require_relative 'memory/transfer'
 require_relative 'memory/communication_pattern'
+require_relative 'memory/diary'
 
 module Legion
   module Extensions

data/spec/legion/extensions/agentic/memory/diary/client_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Diary::Client do
+  let(:store) { instance_double(Legion::Extensions::Agentic::Memory::Diary::Helpers::DiaryStore) }
+  let(:client) { described_class.new(store: store) }
+
+  before do
+    allow(store).to receive(:agent_id).and_return('test-agent')
+    allow(store).to receive(:db_ready?).and_return(true)
+    allow(store).to receive(:count).and_return(5)
+  end
+
+  it 'includes Runners::Diary' do
+    expect(described_class.ancestors).to include(Legion::Extensions::Agentic::Memory::Diary::Runners::Diary)
+  end
+
+  it 'delegates write_diary to the store' do
+    allow(store).to receive(:write).and_return('entry-uuid')
+    result = client.write_diary(session_id: 'sess-1', content: 'notes')
+    expect(result[:success]).to be true
+    expect(result[:entry_id]).to eq('entry-uuid')
+  end
+
+  it 'delegates read_diary to the store' do
+    allow(store).to receive(:read).and_return([{ entry_id: 'e1', content: 'test' }])
+    result = client.read_diary
+    expect(result[:success]).to be true
+    expect(result[:count]).to eq(1)
+  end
+
+  it 'delegates search_diary to the store' do
+    allow(store).to receive(:search).and_return([])
+    result = client.search_diary(query: 'redis')
+    expect(result[:success]).to be true
+    expect(result[:count]).to eq(0)
+  end
+
+  it 'returns diary_stats' do
+    result = client.diary_stats
+    expect(result[:agent_id]).to eq('test-agent')
+    expect(result[:entry_count]).to eq(5)
+  end
+end

data/spec/legion/extensions/agentic/memory/diary/helpers/constants_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Diary::Helpers::Constants do
+  it 'defines TABLE_NAME' do
+    expect(described_class::TABLE_NAME).to eq(:memory_diary_entries)
+  end
+
+  it 'defines DEFAULT_LIMIT' do
+    expect(described_class::DEFAULT_LIMIT).to eq(20)
+  end
+
+  it 'defines MAX_LIMIT' do
+    expect(described_class::MAX_LIMIT).to eq(200)
+  end
+
+  it 'defines MAX_CONTENT_SIZE' do
+    expect(described_class::MAX_CONTENT_SIZE).to eq(65_536)
+  end
+end

data/spec/legion/extensions/agentic/memory/diary/helpers/diary_store_spec.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'sequel'
+require 'json'
+
+unless defined?(Legion::Data::Local)
+  module Legion
+    module Data
+      module Local
+        class << self
+          attr_reader :connection
+
+          def connected?
+            !@connection.nil?
+          end
+
+          def respond_to?(method, *)
+            super
+          end
+        end
+      end
+    end
+  end
+end
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Diary::Helpers::DiaryStore do
+  let(:db) do
+    d = Sequel.sqlite
+    d.create_table(:memory_diary_entries) do
+      primary_key :id
+      String   :entry_id,   size: 36, null: false, unique: true
+      String   :agent_id,   size: 64, null: false
+      String   :session_id, size: 64
+      String   :content,    text: true, null: false
+      String   :tags,       text: true
+      String   :metadata,   text: true
+      DateTime :created_at, null: false
+
+      index :agent_id
+      index %i[agent_id created_at]
+    end
+    d
+  end
+
+  let(:store) { described_class.new(agent_id: 'test-agent') }
+
+  before do
+    allow(Legion::Data::Local).to receive(:respond_to?).and_call_original
+    allow(Legion::Data::Local).to receive(:respond_to?).with(:connected?).and_return(true)
+    allow(Legion::Data::Local).to receive(:connected?).and_return(true)
+    allow(Legion::Data::Local).to receive(:connection).and_return(db)
+  end
+
+  describe '#db_ready?' do
+    it 'returns true when local DB is connected and table exists' do
+      expect(store.db_ready?).to be true
+    end
+
+    it 'returns false when table does not exist' do
+      db.drop_table(:memory_diary_entries)
+      expect(store.db_ready?).to be false
+    end
+
+    it 'returns false when Local is not connected' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      expect(store.db_ready?).to be false
+    end
+  end
+
+  describe '#write' do
+    it 'creates a diary entry and returns the entry_id' do
+      entry_id = store.write(session_id: 'sess-1', content: 'learned about caching')
+      expect(entry_id).to be_a(String)
+      expect(entry_id.length).to eq(36)
+    end
+
+    it 'persists the entry to the database' do
+      store.write(session_id: 'sess-1', content: 'session notes', tags: %w[decisions])
+      row = db[:memory_diary_entries].first
+      expect(row[:agent_id]).to eq('test-agent')
+      expect(row[:session_id]).to eq('sess-1')
+      expect(row[:content]).to eq('session notes')
+      expect(JSON.parse(row[:tags])).to eq(['decisions'])
+    end
+
+    it 'returns nil when db is not ready' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      expect(store.write(session_id: 'sess-1', content: 'test')).to be_nil
+    end
+
+    it 'strips null bytes from content' do
+      store.write(session_id: 'sess-1', content: "hello\x00world")
+      row = db[:memory_diary_entries].first
+      expect(row[:content]).to eq('helloworld')
+    end
+
+    it 'truncates content beyond MAX_CONTENT_SIZE' do
+      long_content = 'x' * 100_000
+      store.write(session_id: 'sess-1', content: long_content)
+      row = db[:memory_diary_entries].first
+      expect(row[:content].length).to eq(65_536)
+    end
+  end
+
+  describe '#read' do
+    before do
+      store.write(session_id: 'sess-1', content: 'first entry', tags: %w[boot])
+      store.write(session_id: 'sess-2', content: 'second entry', tags: %w[work])
+      store.write(session_id: 'sess-3', content: 'third entry', tags: %w[debug])
+    end
+
+    it 'returns entries in chronological order (oldest first)' do
+      entries = store.read
+      expect(entries.size).to eq(3)
+      expect(entries.first[:content]).to eq('first entry')
+      expect(entries.last[:content]).to eq('third entry')
+    end
+
+    it 'respects the limit parameter' do
+      entries = store.read(limit: 2)
+      expect(entries.size).to eq(2)
+    end
+
+    it 'caps limit at MAX_LIMIT' do
+      entries = store.read(limit: 500)
+      expect(entries.size).to eq(3)
+    end
+
+    it 'scopes to the current agent only' do
+      other = described_class.new(agent_id: 'other-agent')
+      other.write(session_id: 'sess-x', content: 'other agent entry')
+      entries = store.read
+      expect(entries.size).to eq(3)
+    end
+
+    it 'deserializes tags as an array' do
+      entries = store.read(limit: 1)
+      expect(entries.first[:tags]).to eq(['boot'])
+    end
+
+    it 'returns empty array when db not ready' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      expect(store.read).to eq([])
+    end
+  end
+
+  describe '#search' do
+    before do
+      store.write(session_id: 'sess-1', content: 'decided to use Redis for caching')
+      store.write(session_id: 'sess-2', content: 'discussed database migration plan')
+      store.write(session_id: 'sess-3', content: 'optimized Redis pool settings')
+    end
+
+    it 'returns entries matching the query' do
+      entries = store.search(query: 'Redis')
+      expect(entries.size).to eq(2)
+    end
+
+    it 'returns empty for no match' do
+      entries = store.search(query: 'nonexistent')
+      expect(entries.empty?).to be true
+    end
+
+    it 'returns empty for nil/blank query' do
+      expect(store.search(query: nil)).to eq([])
+      expect(store.search(query: '  ')).to eq([])
+    end
+
+    it 'scopes to current agent' do
+      other = described_class.new(agent_id: 'other-agent')
+      other.write(session_id: 'sess-x', content: 'Redis in other agent')
+      entries = store.search(query: 'Redis')
+      expect(entries.size).to eq(2)
+    end
+  end
+
+  describe '#get' do
+    it 'retrieves a single entry by entry_id' do
+      entry_id = store.write(session_id: 'sess-1', content: 'test entry')
+      entry = store.get(entry_id)
+      expect(entry[:entry_id]).to eq(entry_id)
+      expect(entry[:content]).to eq('test entry')
+    end
+
+    it 'returns nil for unknown entry_id' do
+      expect(store.get('nonexistent')).to be_nil
+    end
+
+    it 'does not return entries from another agent' do
+      entry_id = store.write(session_id: 'sess-1', content: 'mine')
+      other = described_class.new(agent_id: 'other-agent')
+      expect(other.get(entry_id)).to be_nil
+    end
+  end
+
+  describe '#delete' do
+    it 'removes the entry' do
+      entry_id = store.write(session_id: 'sess-1', content: 'deletable')
+      expect(store.delete(entry_id)).to be true
+      expect(store.get(entry_id)).to be_nil
+    end
+
+    it 'returns false when db not ready' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      expect(store.delete('any')).to be false
+    end
+  end
+
+  describe '#count' do
+    it 'returns the number of entries for the agent' do
+      store.write(session_id: 'sess-1', content: 'one')
+      store.write(session_id: 'sess-2', content: 'two')
+      expect(store.count).to eq(2)
+    end
+
+    it 'does not count entries from other agents' do
+      store.write(session_id: 'sess-1', content: 'mine')
+      other = described_class.new(agent_id: 'other-agent')
+      other.write(session_id: 'sess-x', content: 'theirs')
+      expect(store.count).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/diary/runners/diary_spec.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'sequel'
+
+unless defined?(Legion::Data::Local)
+  module Legion
+    module Data
+      module Local
+        class << self
+          attr_reader :connection
+
+          def connected?
+            !@connection.nil?
+          end
+
+          def respond_to?(method, *)
+            super
+          end
+        end
+      end
+    end
+  end
+end
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Diary::Runners::Diary do
+  let(:db) do
+    d = Sequel.sqlite
+    d.create_table(:memory_diary_entries) do
+      primary_key :id
+      String   :entry_id,   size: 36, null: false, unique: true
+      String   :agent_id,   size: 64, null: false
+      String   :session_id, size: 64
+      String   :content,    text: true, null: false
+      String   :tags,       text: true
+      String   :metadata,   text: true
+      DateTime :created_at, null: false
+
+      index :agent_id
+      index %i[agent_id created_at]
+    end
+    d
+  end
+
+  let(:store) { Legion::Extensions::Agentic::Memory::Diary::Helpers::DiaryStore.new(agent_id: 'runner-agent') }
+
+  let(:runner) do
+    client = Legion::Extensions::Agentic::Memory::Diary::Client.new(store: store)
+    client
+  end
+
+  before do
+    allow(Legion::Data::Local).to receive(:respond_to?).and_call_original
+    allow(Legion::Data::Local).to receive(:respond_to?).with(:connected?).and_return(true)
+    allow(Legion::Data::Local).to receive(:connected?).and_return(true)
+    allow(Legion::Data::Local).to receive(:connection).and_return(db)
+  end
+
+  describe '#write_diary' do
+    it 'writes an entry and returns success with entry_id' do
+      result = runner.write_diary(session_id: 'sess-1', content: 'test notes')
+      expect(result[:success]).to be true
+      expect(result[:entry_id]).to be_a(String)
+    end
+
+    it 'returns failure when store is not available' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      result = runner.write_diary(session_id: 'sess-1', content: 'test')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#read_diary' do
+    before do
+      runner.write_diary(session_id: 'sess-1', content: 'entry one')
+      runner.write_diary(session_id: 'sess-2', content: 'entry two')
+    end
+
+    it 'returns entries with count' do
+      result = runner.read_diary
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+      expect(result[:entries].size).to eq(2)
+    end
+
+    it 'respects limit' do
+      result = runner.read_diary(limit: 1)
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'returns failure when store is not available' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      result = runner.read_diary
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq('diary store not available')
+    end
+  end
+
+  describe '#search_diary' do
+    before do
+      runner.write_diary(session_id: 'sess-1', content: 'discussed caching strategy')
+      runner.write_diary(session_id: 'sess-2', content: 'fixed database bug')
+    end
+
+    it 'finds entries matching query' do
+      result = runner.search_diary(query: 'caching')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'returns empty for no match' do
+      result = runner.search_diary(query: 'nonexistent')
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns failure when store is not available' do
+      allow(Legion::Data::Local).to receive(:connected?).and_return(false)
+      result = runner.search_diary(query: 'caching')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq('diary store not available')
+    end
+  end
+
+  describe '#diary_stats' do
+    it 'returns stats for the agent diary' do
+      runner.write_diary(session_id: 'sess-1', content: 'test')
+      result = runner.diary_stats
+      expect(result[:success]).to be true
+      expect(result[:agent_id]).to eq('runner-agent')
+      expect(result[:entry_count]).to eq(1)
+      expect(result[:available]).to be true
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-agentic-memory
 version: !ruby/object:Gem::Version
-  version: 0.1.36
+  version: 0.1.37
 platform: ruby
 authors:
 - Esity
@@ -216,6 +216,13 @@ files:
 - lib/legion/extensions/agentic/memory/consolidation.rb
 - lib/legion/extensions/agentic/memory/consolidation/helpers/extractor.rb
 - lib/legion/extensions/agentic/memory/consolidation/pre_compact.rb
+- lib/legion/extensions/agentic/memory/diary.rb
+- lib/legion/extensions/agentic/memory/diary/client.rb
+- lib/legion/extensions/agentic/memory/diary/helpers/constants.rb
+- lib/legion/extensions/agentic/memory/diary/helpers/diary_store.rb
+- lib/legion/extensions/agentic/memory/diary/local_migrations/20260517000001_create_memory_diary_entries.rb
+- lib/legion/extensions/agentic/memory/diary/runners/diary.rb
+- lib/legion/extensions/agentic/memory/diary/version.rb
 - lib/legion/extensions/agentic/memory/echo.rb
 - lib/legion/extensions/agentic/memory/echo/actors/decay.rb
 - lib/legion/extensions/agentic/memory/echo/client.rb
@@ -383,6 +390,10 @@ files:
 - spec/legion/extensions/agentic/memory/compression/runners/cognitive_compression_spec.rb
 - spec/legion/extensions/agentic/memory/consolidation/helpers/extractor_spec.rb
 - spec/legion/extensions/agentic/memory/consolidation/pre_compact_spec.rb
+- spec/legion/extensions/agentic/memory/diary/client_spec.rb
+- spec/legion/extensions/agentic/memory/diary/helpers/constants_spec.rb
+- spec/legion/extensions/agentic/memory/diary/helpers/diary_store_spec.rb
+- spec/legion/extensions/agentic/memory/diary/runners/diary_spec.rb
 - spec/legion/extensions/agentic/memory/echo/actors/decay_spec.rb
 - spec/legion/extensions/agentic/memory/echo/client_spec.rb
 - spec/legion/extensions/agentic/memory/echo/cognitive_echo_spec.rb