4 files changed, 88 insertions, 25 deletions

diff --git a/README.md b/README.md
index ef15d10..ede58a8 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,9 @@ For credentials and configurations, relevant environment variables can be set in
 OPENAI_API_ADDRESS=https://api.openai.com
 OPENAI_API_ACCESS_TOKEN=your-token
 OPENAI_API_USER_IDENTIFIER=your-user
-NANO_BOTS_STATE_DIRECTORY=/home/your-user/.local/share/.nano-bots
+
+NANO_BOTS_STATE_DIRECTORY=/home/your-user/.local/state/nano-bots
+NANO_BOTS_CARTRIDGES_DIRECTORY=/home/your-user/.local/share/nano-bots/cartridges
 ```
 
 Alternatively, if your current directory has a `.env` file with the environment variables, they will be automatically loaded.
diff --git a/components/storage.rb b/components/storage.rb
new file mode 100644
index 0000000..5f51d06
--- /dev/null
+++ b/components/storage.rb
@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'babosa'
+
+require_relative '../logic/helpers/hash'
+
+module NanoBot
+  module Components
+    class Storage
+      def self.build_path_and_ensure_state_file!(key, cartridge)
+        path = [
+          Logic::Helpers::Hash.fetch(cartridge, %i[state directory]),
+          ENV.fetch('NANO_BOTS_STATE_DIRECTORY', nil)
+        ].find do |candidate|
+          !candidate.nil? && !candidate.empty?
+        end
+
+        path = "#{user_home!.sub(%r{/$}, '')}/.local/state/nano-bots" if path.nil?
+
+        path = "#{path.sub(%r{/$}, '')}/nano-bots-rb/#{cartridge[:name].to_slug.normalize}"
+        path = "#{path}/#{cartridge[:version].to_slug.normalize}/#{key.to_slug.normalize}"
+        path = "#{path}/state.json"
+
+        FileUtils.mkdir_p(File.dirname(path))
+
+        File.write(path, JSON.generate({ key:, history: [] })) unless File.exist?(path)
+
+        path
+      end
+
+      def self.cartridge_path(path)
+        partial = File.join(File.dirname(path), File.basename(path, File.extname(path)))
+
+        candidates = [
+          path,
+          "#{partial}.yml",
+          "#{partial}.yaml"
+        ]
+
+        unless ENV.fetch('NANO_BOTS_CARTRIDGES_DIRECTORY', nil).nil?
+          directory = ENV.fetch('NANO_BOTS_CARTRIDGES_DIRECTORY').sub(%r{/$}, '')
+
+          partial = File.join(File.dirname(partial), File.basename(partial, File.extname(partial)))
+
+          partial = path.sub(%r{^\.?/}, '')
+
+          candidates << "#{directory}/#{partial}"
+          candidates << "#{directory}/#{partial}.yml"
+          candidates << "#{directory}/#{partial}.yaml"
+        end
+
+        directory = "#{user_home!.sub(%r{/$}, '')}/.local/share/nano-bots/cartridges"
+
+        partial = File.join(File.dirname(partial), File.basename(partial, File.extname(partial)))
+
+        partial = path.sub(%r{^\.?/}, '')
+
+        candidates << "#{directory}/#{partial}"
+        candidates << "#{directory}/#{partial}.yml"
+        candidates << "#{directory}/#{partial}.yaml"
+
+        candidates = candidates.uniq
+
+        candidates.find do |candidate|
+          File.exist?(candidate) && File.file?(candidate)
+        end
+      end
+
+      def self.user_home!
+        [Dir.home, `echo ~`.strip, '~'].find do |candidate|
+          !candidate.nil? && !candidate.empty?
+        end
+      end
+    end
+  end
+end
diff --git a/controllers/instance.rb b/controllers/instance.rb
index 5635658..bee4dfb 100644
--- a/controllers/instance.rb
+++ b/controllers/instance.rb
@@ -4,6 +4,7 @@ require 'yaml'
 
 require_relative '../logic/helpers/hash'
 require_relative '../components/provider'
+require_relative '../components/storage'
 require_relative './interfaces/repl'
 require_relative './session'
 
@@ -34,7 +35,10 @@ module NanoBot
 
       def load_cartridge!(path)
         @cartridge = Logic::Helpers::Hash.symbolize_keys(
-          YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+          YAML.safe_load(
+            File.read(Components::Storage.cartridge_path(path)),
+            permitted_classes: [Symbol]
+          )
         )
 
         inject_environment_variables!(@cartridge)
diff --git a/controllers/session.rb b/controllers/session.rb
index fadb21b..9277a84 100644
--- a/controllers/session.rb
+++ b/controllers/session.rb
@@ -5,6 +5,7 @@ require 'babosa'
 require 'fileutils'
 
 require_relative '../logic/helpers/hash'
+require_relative '../components/storage'
 
 module NanoBot
   module Controllers
@@ -22,7 +23,9 @@ module NanoBot
         if @stateless
           @state = { history: [] }
         else
-          build_path_and_ensure_state_file!(state.strip)
+          @state_path = Components::Storage.build_path_and_ensure_state_file!(
+            state.strip, @cartridge
+          )
           @state = load_state
         end
       end
@@ -44,28 +47,6 @@ module NanoBot
         File.write(@state_path, JSON.generate(@state))
       end
 
-      def build_path_and_ensure_state_file!(key)
-        path = Logic::Helpers::Hash.fetch(@cartridge, %i[state directory])
-
-        path = "#{user_home!.sub(%r{/$}, '')}/.local/share/.nano-bots" if path.nil? || path.empty?
-
-        path = "#{path.sub(%r{/$}, '')}/nano-bots-rb/#{@cartridge[:name].to_slug.normalize}"
-        path = "#{path}/#{@cartridge[:version].to_slug.normalize}/#{key.to_slug.normalize}"
-        path = "#{path}/state.json"
-
-        @state_path = path
-
-        FileUtils.mkdir_p(File.dirname(@state_path))
-
-        File.write(@state_path, JSON.generate({ key:, history: [] })) unless File.exist?(@state_path)
-      end
-
-      def user_home!
-        [Dir.home, `echo ~`.strip, '~'].find do |candidate|
-          !candidate.nil? && !candidate.empty?
-        end
-      end
-
       def boot(mode:)
         return unless Logic::Helpers::Hash.fetch(@cartridge, %i[behaviors boot instruction])