llmemory 0.1.1 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84ebe29d1042b2efa07d02ded2a5374bbdcc1b0bad195a90d6cc5a15c1a2f73a
-  data.tar.gz: 6b6c0157acc13d89a07b9491c206a5a132d4c1e9c3c63a08f1810dd39681a067
+  metadata.gz: 252d1921772537eaeba7f1f2b689643202fda6db8f5ddc7aa71c7b2f45636331
+  data.tar.gz: c2fc2f9152db916e4448f8a2aa55d8079c68ad40fec1eb0eeaa5564834b1789e
 SHA512:
-  metadata.gz: cfd74b6f30e3d049de41596344a15c7b7734794a146a22e9dc2ad61153eb8fa584982efe1a4969bbe24fdbe2a079f46f8f42aeabd1e90e6f78f65d511fbc10df
-  data.tar.gz: 644dd2c11dbcdb40486d4a1b3cc33e5c13aa0ae0f9616358b4aff069d7b0ac7a04a263bb09a98657e58bcbefd11def65c7c5c711bbf6be3d36645512367439e3
+  metadata.gz: 92256d0f2a37bd2047e78c3651eaa60e8c46dc5bfa176e5e99800a28eeb90cf8b0f791248b5bdd85ff33828e4599acd80d2443698449cdf54017fde23b0a1685
+  data.tar.gz: 3aa07c74614b8975165ed6a073210d0c58c194969043c87080cf516668667d04b71b306212b09e2994d9769e746e2e9d1743ddf6b79ed37b39c54968cbfc06ff

data/README.md

@@ -1,6 +1,6 @@
 # llmemory
 
-Persistent memory system for LLM agents. Implements short-term checkpointing, long-term memory (file-based or **graph-based**), retrieval with time decay, and maintenance jobs.
+Persistent memory system for LLM agents. Implements short-term checkpointing, long-term memory (file-based or **graph-based**), retrieval with time decay, and maintenance jobs. You can inspect memory from the **CLI** or, in Rails apps, from an optional **dashboard**.
 
 ## Installation
 
@@ -188,6 +188,53 @@ Llmemory::Maintenance::Runner.run_weekly(user_id, storage: memory.storage)
 Llmemory::Maintenance::Runner.run_monthly(user_id, storage: memory.storage)
 ```
 
+## Inspecting memory
+
+### CLI
+
+The gem ships an executable to inspect memory from the terminal (no extra dependencies; uses Ruby’s OptParse):
+
+```bash
+llmemory --help
+llmemory users
+llmemory short-term USER_ID [--session SESSION_ID] [--list-sessions]
+llmemory facts USER_ID [--category CATEGORY] [--limit N]
+llmemory categories USER_ID
+llmemory resources USER_ID [--limit N]
+llmemory nodes USER_ID [--type TYPE] [--limit N]      # graph-based
+llmemory edges USER_ID [--subject NODE_ID] [--limit N]
+llmemory graph USER_ID [--format dot|json]
+llmemory search USER_ID "query" [--type short|long|all]
+llmemory stats [USER_ID]
+```
+
+Use `--store TYPE` where applicable to override the configured store (e.g. `memory`, `redis`, `postgres`, `active_record` for short-term; same or `file` for long-term file-based).
+
+### Dashboard (Rails, optional)
+
+If you use Rails and want a web UI to browse memory, load the dashboard and mount the engine. **Rails is not a dependency of the gem**; the dashboard is only loaded when you require it.
+
+1. In an initializer or early in boot (e.g. `config/initializers/llmemory.rb`):
+
+```ruby
+require "llmemory/dashboard"
+```
+
+2. In `config/routes.rb`:
+
+```ruby
+mount Llmemory::Dashboard::Engine, at: "/llmemory"
+```
+
+3. Visit `/llmemory`. You get:
+   - List of users with memory
+   - Short-term: conversation messages per session
+   - Long-term (file-based): resources, items by category, category summaries
+   - Long-term (graph-based): nodes and edges
+   - Search and stats
+
+The dashboard uses your existing `Llmemory.configuration` (short-term store, long-term store/type, etc.) and does not add any gem dependency; it only runs when Rails is present and you require `llmemory/dashboard`.
+
 ## License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/exe/llmemory

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__)) unless $LOAD_PATH.include?(File.expand_path("../lib", __dir__))
+require "llmemory"
+require "llmemory/cli"
+
+Llmemory::CLI.run(ARGV)

data/lib/llmemory/cli/commands/base.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Cli
+    module Commands
+      class Base
+        def run(argv)
+          opts = parse_options(argv)
+          execute(argv, opts)
+        end
+
+        def parse_options(argv)
+          OptionParser.new do |opts|
+            option_parser(opts)
+          end.parse!(argv)
+        end
+
+        def option_parser(parser)
+          # Override in subclasses to add options
+        end
+
+        def execute(_argv, _opts)
+          raise NotImplementedError, "#{self.class}#execute must be implemented"
+        end
+
+        protected
+
+        def short_term_store(store_type = nil)
+          type = (store_type || Llmemory.configuration.short_term_store).to_s.to_sym
+          case type
+          when :memory then Llmemory::ShortTerm::Stores::MemoryStore.new
+          when :redis then Llmemory::ShortTerm::Stores::RedisStore.new
+          when :postgres then Llmemory::ShortTerm::Stores::PostgresStore.new
+          when :active_record, :activerecord
+            require_relative "../../short_term/stores/active_record_store"
+            Llmemory::ShortTerm::Stores::ActiveRecordStore.new
+          else
+            Llmemory::ShortTerm::Stores::MemoryStore.new
+          end
+        end
+
+        def file_based_storage(store_type = nil)
+          type = (store_type || Llmemory.configuration.long_term_store).to_s.to_sym
+          case type
+          when :memory then Llmemory::LongTerm::FileBased::Storages::MemoryStorage.new
+          when :file
+            Llmemory::LongTerm::FileBased::Storages::FileStorage.new(
+              base_path: Llmemory.configuration.long_term_storage_path
+            )
+          when :postgres, :database
+            Llmemory::LongTerm::FileBased::Storages::DatabaseStorage.new(
+              database_url: Llmemory.configuration.database_url
+            )
+          when :active_record, :activerecord
+            require_relative "../../long_term/file_based/storages/active_record_storage"
+            Llmemory::LongTerm::FileBased::Storages::ActiveRecordStorage.new
+          else
+            Llmemory::LongTerm::FileBased::Storages::MemoryStorage.new
+          end
+        end
+
+        def graph_based_storage(store_type = nil)
+          type = (store_type || :memory).to_s.to_sym
+          case type
+          when :memory then Llmemory::LongTerm::GraphBased::Storages::MemoryStorage.new
+          when :active_record, :activerecord
+            require_relative "../../long_term/graph_based/storages/active_record_storage"
+            Llmemory::LongTerm::GraphBased::Storages::ActiveRecordStorage.new
+          else
+            Llmemory::LongTerm::GraphBased::Storages::MemoryStorage.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term/categories.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        class Categories < Commands::Base
+          def option_parser(parser)
+            parser.on("--store TYPE", "Storage type") { |v| @store_type = v }
+          end
+
+          def execute(argv, _opts)
+            user_id = argv.first
+            unless user_id
+              $stderr.puts "Usage: llmemory categories USER_ID"
+              exit 1
+            end
+
+            storage = file_based_storage(@store_type)
+            categories = storage.list_categories(user_id)
+
+            if categories.empty?
+              puts "No categories found for user #{user_id}."
+            else
+              categories.each { |c| puts c }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term/edges.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        class Edges < Commands::Base
+          def option_parser(parser)
+            parser.on("--subject NODE_ID", "Filter by subject node") { |v| @subject_id = v }
+            parser.on("--limit N", Integer, "Max number of edges") { |v| @limit = v }
+            parser.on("--store TYPE", "Storage type") { |v| @store_type = v }
+          end
+
+          def execute(argv, _opts)
+            user_id = argv.first
+            unless user_id
+              $stderr.puts "Usage: llmemory edges USER_ID [--subject NODE_ID] [--limit N]"
+              exit 1
+            end
+
+            storage = graph_based_storage(@store_type)
+            edges = storage.list_edges(user_id, subject_id: @subject_id, limit: @limit)
+
+            if edges.empty?
+              puts "No edges found for user #{user_id}."
+              return
+            end
+
+            edges.each do |e|
+              id = e.respond_to?(:id) ? e.id : e[:id]
+              subj = e.respond_to?(:subject_id) ? e.subject_id : e[:subject_id]
+              pred = e.respond_to?(:predicate) ? e.predicate : e[:predicate]
+              obj = e.respond_to?(:object_id) ? e.object_id : e[:object_id]
+              puts "#{id}: #{subj} --#{pred}--> #{obj}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term/facts.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        class Facts < Commands::Base
+          def option_parser(parser)
+            parser.on("--category CATEGORY", "Filter by category") { |v| @category = v }
+            parser.on("--limit N", Integer, "Max number of items") { |v| @limit = v }
+            parser.on("--store TYPE", "Storage type") { |v| @store_type = v }
+          end
+
+          def execute(argv, _opts)
+            user_id = argv.first
+            unless user_id
+              $stderr.puts "Usage: llmemory facts USER_ID [--category CATEGORY] [--limit N]"
+              exit 1
+            end
+
+            storage = file_based_storage(@store_type)
+            items = storage.list_items(user_id: user_id, category: @category, limit: @limit)
+
+            if items.empty?
+              puts "No facts found for user #{user_id}."
+              return
+            end
+
+            items.each do |i|
+              cat = i[:category] || i["category"]
+              content = (i[:content] || i["content"]).to_s
+              created = i[:created_at] || i["created_at"]
+              puts "[#{cat}] #{content} (#{created})"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term/graph.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../base"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        class Graph < Commands::Base
+          def option_parser(parser)
+            parser.on("--format FORMAT", "Output format: dot, json") { |v| @format = (v || "dot").downcase }
+            parser.on("--store TYPE", "Storage type") { |v| @store_type = v }
+          end
+
+          def execute(argv, _opts)
+            user_id = argv.first
+            unless user_id
+              $stderr.puts "Usage: llmemory graph USER_ID [--format dot|json]"
+              exit 1
+            end
+
+            storage = graph_based_storage(@store_type)
+            nodes = storage.list_nodes(user_id)
+            edges = storage.list_edges(user_id)
+
+            case @format
+            when "json"
+              puts JSON.pretty_generate(
+                nodes: nodes.map { |n| node_to_h(n) },
+                edges: edges.map { |e| edge_to_h(e) }
+              )
+            else
+              puts to_dot(nodes, edges)
+            end
+          end
+
+          private
+
+          def node_to_h(n)
+            if n.respond_to?(:to_h)
+              n.to_h
+            else
+              { id: n[:id], entity_type: n[:entity_type], name: n[:name] }
+            end
+          end
+
+          def edge_to_h(e)
+            if e.respond_to?(:to_h)
+              e.to_h
+            else
+              { id: e[:id], subject_id: e[:subject_id], predicate: e[:predicate], object_id: e[:object_id] }
+            end
+          end
+
+          def to_dot(nodes, edges)
+            lines = ["digraph llmemory {"]
+            nodes.each do |n|
+              id = n.respond_to?(:id) ? n.id : n[:id]
+              name = (n.respond_to?(:name) ? n.name : n[:name]).to_s.gsub('"', '\\"')
+              lines << "  \"#{id}\" [label=\"#{name}\"];"
+            end
+            edges.each do |e|
+              subj = e.respond_to?(:subject_id) ? e.subject_id : e[:subject_id]
+              obj = e.respond_to?(:object_id) ? e.object_id : e[:object_id]
+              pred = e.respond_to?(:predicate) ? e.predicate : e[:predicate]
+              lines << "  \"#{subj}\" -> \"#{obj}\" [label=\"#{pred}\"];"
+            end
+            lines << "}"
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term/nodes.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        class Nodes < Commands::Base
+          def option_parser(parser)
+            parser.on("--type TYPE", "Filter by entity type") { |v| @entity_type = v }
+            parser.on("--limit N", Integer, "Max number of nodes") { |v| @limit = v }
+            parser.on("--store TYPE", "Storage type (memory, active_record)") { |v| @store_type = v }
+          end
+
+          def execute(argv, _opts)
+            user_id = argv.first
+            unless user_id
+              $stderr.puts "Usage: llmemory nodes USER_ID [--type TYPE] [--limit N]"
+              exit 1
+            end
+
+            storage = graph_based_storage(@store_type)
+            nodes = storage.list_nodes(user_id, entity_type: @entity_type, limit: @limit)
+
+            if nodes.empty?
+              puts "No nodes found for user #{user_id}."
+              return
+            end
+
+            nodes.each do |n|
+              id = n.respond_to?(:id) ? n.id : n[:id]
+              type = n.respond_to?(:entity_type) ? n.entity_type : n[:entity_type]
+              name = n.respond_to?(:name) ? n.name : n[:name]
+              puts "#{id} [#{type}] #{name}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term/resources.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        class Resources < Commands::Base
+          def option_parser(parser)
+            parser.on("--limit N", Integer, "Max number of resources") { |v| @limit = v }
+            parser.on("--store TYPE", "Storage type") { |v| @store_type = v }
+          end
+
+          def execute(argv, _opts)
+            user_id = argv.first
+            unless user_id
+              $stderr.puts "Usage: llmemory resources USER_ID [--limit N]"
+              exit 1
+            end
+
+            storage = file_based_storage(@store_type)
+            resources = storage.list_resources(user_id: user_id, limit: @limit)
+
+            if resources.empty?
+              puts "No resources found for user #{user_id}."
+              return
+            end
+
+            resources.each do |r|
+              id = r[:id] || r["id"]
+              text = (r[:text] || r["text"]).to_s
+              text = text[0, 150] + "..." if text.length > 150
+              created = r[:created_at] || r["created_at"]
+              puts "#{id}: #{text} (#{created})"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/long_term.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "long_term/facts"
+require_relative "long_term/categories"
+require_relative "long_term/resources"
+require_relative "long_term/nodes"
+require_relative "long_term/edges"
+require_relative "long_term/graph"
+
+module Llmemory
+  module Cli
+    module Commands
+      module LongTerm
+        # Namespace for long-term inspection commands
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/search.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Search < Base
+        def option_parser(parser)
+          parser.on("--type TYPE", "Search in: short, long, all (default: all)") { |v| @search_type = (v || "all").downcase }
+          parser.on("--store TYPE", "Store type") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.shift
+          query = argv.join(" ").strip
+          unless user_id && !query.empty?
+            $stderr.puts "Usage: llmemory search USER_ID \"query\" [--type short|long|all]"
+            exit 1
+          end
+
+          type = @search_type || "all"
+
+          if type == "short" || type == "all"
+            search_short_term(user_id, query)
+          end
+
+          if type == "long" || type == "all"
+            if Llmemory.configuration.long_term_type.to_s == "graph_based"
+              search_graph_based(user_id, query)
+            else
+              search_file_based(user_id, query)
+            end
+          end
+        end
+
+        private
+
+        def search_short_term(user_id, query)
+          store = short_term_store(@store_type)
+          sessions = store.list_sessions(user_id: user_id)
+          puts "=== Short-term ==="
+          sessions.each do |session_id|
+            state = store.load(user_id, session_id)
+            next unless state
+            messages = state[:messages] || state["messages"] || []
+            messages.each do |m|
+              content = (m[:content] || m["content"]).to_s
+              next unless content.downcase.include?(query.downcase)
+              role = m[:role] || m["role"]
+              puts "[#{session_id}] [#{role}] #{content[0, 150]}..."
+            end
+          end
+        end
+
+        def search_file_based(user_id, query)
+          storage = file_based_storage(@store_type)
+          puts "=== Long-term (file-based) ==="
+          items = storage.search_items(user_id, query)
+          items.each do |i|
+            content = (i[:content] || i["content"]).to_s
+            puts "[#{i[:category]}] #{content}"
+          end
+          resources = storage.search_resources(user_id, query)
+          resources.each do |r|
+            text = (r[:text] || r["text"]).to_s
+            puts "[resource] #{text[0, 150]}..."
+          end
+        end
+
+        def search_graph_based(user_id, query)
+          storage = graph_based_storage(@store_type)
+          puts "=== Long-term (graph-based) ==="
+          nodes = storage.list_nodes(user_id)
+          query_lower = query.downcase
+          nodes.each do |n|
+            name = (n.respond_to?(:name) ? n.name : n[:name]).to_s
+            next unless name.downcase.include?(query_lower)
+            type = n.respond_to?(:entity_type) ? n.entity_type : n[:entity_type]
+            puts "[node] #{type}: #{name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/short_term.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class ShortTerm < Base
+        DEFAULT_SESSION = "default"
+
+        def option_parser(parser)
+          parser.on("--session SESSION_ID", "Session ID (default: default)") { |v| @session_id = v }
+          parser.on("--list-sessions", "List sessions for the user") { @list_sessions = true }
+          parser.on("--store TYPE", "Store type") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory short-term USER_ID [--session SESSION_ID] [--list-sessions]"
+            exit 1
+          end
+
+          store = short_term_store(@store_type)
+
+          if @list_sessions
+            sessions = store.list_sessions(user_id: user_id)
+            if sessions.empty?
+              puts "No sessions found for user #{user_id}."
+            else
+              sessions.each { |s| puts s }
+            end
+            return
+          end
+
+          session_id = @session_id || DEFAULT_SESSION
+          state = store.load(user_id, session_id)
+          if state.nil?
+            puts "No state found for user #{user_id}, session #{session_id}."
+            return
+          end
+
+          messages = state[:messages] || state["messages"] || []
+          if messages.empty?
+            puts "No messages in session #{session_id}."
+            return
+          end
+
+          messages.each do |m|
+            role = m[:role] || m["role"]
+            content = (m[:content] || m["content"]).to_s
+            content = content[0, 200] + "..." if content.length > 200
+            puts "[#{role}] #{content}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli/commands/stats.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Stats < Base
+        def option_parser(parser)
+          parser.on("--store TYPE", "Store type") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.first
+          short_store = short_term_store(@store_type)
+          long_type = Llmemory.configuration.long_term_type.to_s
+
+          if user_id
+            print_user_stats(user_id, short_store, long_type)
+          else
+            print_global_stats(short_store, long_type)
+          end
+        end
+
+        private
+
+        def print_user_stats(user_id, short_store, long_type)
+          puts "Stats for user: #{user_id}"
+          puts "---"
+
+          sessions = short_store.list_sessions(user_id: user_id)
+          puts "Short-term sessions: #{sessions.size}"
+
+          if long_type == "graph_based"
+            storage = graph_based_storage(@store_type)
+            puts "Long-term (graph) nodes: #{storage.count_nodes(user_id)}"
+            puts "Long-term (graph) edges: #{storage.count_edges(user_id)}"
+          else
+            storage = file_based_storage(@store_type)
+            puts "Long-term (file) items: #{storage.count_items(user_id: user_id)}"
+            puts "Long-term (file) categories: #{storage.list_categories(user_id).size}"
+            puts "Long-term (file) resources: #{storage.list_resources(user_id: user_id).size}"
+          end
+        end
+
+        def print_global_stats(short_store, long_type)
+          users = short_store.list_users
+          puts "Total users (short-term): #{users.size}"
+          puts "---"
+
+          if long_type == "graph_based"
+            storage = graph_based_storage(@store_type)
+            long_users = storage.list_users
+            puts "Total users (long-term graph): #{long_users.size}"
+            total_nodes = long_users.sum { |u| storage.count_nodes(u) }
+            total_edges = long_users.sum { |u| storage.count_edges(u) }
+            puts "Total nodes: #{total_nodes}"
+            puts "Total edges: #{total_edges}"
+          else
+            storage = file_based_storage(@store_type)
+            long_users = storage.list_users
+            puts "Total users (long-term file): #{long_users.size}"
+            total_items = long_users.sum { |u| storage.count_items(user_id: u) }
+            puts "Total items: #{total_items}"
+          end
+        end
+      end
+    end
+  end
+end