llmemory 0.1.17 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b86647810e47140fff5732a066da4a16188704249d09db14720d8c565b6eaf0e
-  data.tar.gz: 7c52c551746d22c29e41015098a68e166788bb614b0e0c2b064fa5fc0824989f
+  metadata.gz: 80f259aa60090b95d21110bdf1f91c2c91bd5334a1bc4e3effaec444f241f371
+  data.tar.gz: 0b07d9a6ce5e485a69f00dfb2ad7c0cd03a442e95817d310a65d85e40f9def2c
 SHA512:
-  metadata.gz: f584d487eca13280b13f7a3e9f4b8eda60ed10ec8dbb45ff72483acbc76b7feb7f79fb5ae572640a31e87ade05b0762f07cacbecb778dffa6d62a7096231fb12
-  data.tar.gz: c68e284c21fc22ccdf20160d9082575a47482b03c5a91fb3b52ec5a6c51b7f5cf13a8915bfd3fe2f5933aa6a52fe8c382e2373393b27d68d8ed1c7ac83766e49
+  metadata.gz: 464cc0765650869996ff24a4bf7e2b3ce4d3433a6c73cc9d63167173b04d14deedf0e169ca4579a7d7ac253b5a858f2b88629ce1b888bf48becfa46fad581979
+  data.tar.gz: 7624c8cd607cf882b13d500ee878b5412f49e13282014a33dc836cfa68c9bfdf9f759b89f53b51eccb38c32966f0cc66ae5d23a2297f2c965a67d81ccb8f437f

data/README.md

@@ -70,6 +70,15 @@ Llmemory.configure do |config|
   config.prune_after_days = 90
   config.compact_max_bytes = 8192  # max bytes before compact! triggers
 
+  # Retrieval ranking signals (see "Cognitive Memory (CoALA)")
+  config.importance_weight = 1.0          # how strongly importance multiplies the score (0 = ignore)
+  config.retrieval_feedback_weight = 0.5  # how strongly useful/harmful feedback shifts ranking (0 = ignore)
+
+  # Semantic (embedding) retrieval for episodic/procedural memory (opt-in;
+  # default off keeps them deterministic and network-free)
+  config.episodic_vector_enabled = false
+  config.procedural_vector_enabled = false
+
   # Pre-compaction memory flush (prevents knowledge loss when compacting)
   config.memory_flush_enabled = true
   config.memory_flush_threshold_tokens = 4000
@@ -125,7 +134,7 @@ rails g llmemory:install
 rails db:migrate
 ```
 
-La migración crea las tablas de long-term file-based (resources, items, categories), short-term (checkpoints) y, para graph-based, nodos, aristas y embeddings (`llmemory_nodes`, `llmemory_edges`, `llmemory_embeddings`). Para embeddings se usa pgvector; asegúrate de tener la extensión `vector` en PostgreSQL. Para usar ambas con ActiveRecord:
+La migración crea las tablas de long-term file-based (resources, items, categories), short-term (checkpoints), episódica y procedural (`llmemory_episodes`, `llmemory_skills`; columna `data` JSONB) y, para graph-based, nodos, aristas y embeddings (`llmemory_nodes`, `llmemory_edges`, `llmemory_embeddings`). Para embeddings se usa pgvector; asegúrate de tener la extensión `vector` en PostgreSQL. Para usar ambas con ActiveRecord:
 
 ```ruby
 # config/application.rb o config/initializers/llmemory.rb
@@ -195,6 +204,174 @@ candidates = memory.search_candidates("job", top_k: 20)
 
 **Graph storage:** `:memory` (in-memory) or `:active_record` (Rails). For ActiveRecord, run `rails g llmemory:install` and migrate; the migration creates `llmemory_nodes`, `llmemory_edges`, and `llmemory_embeddings` (pgvector). Enable the `vector` extension in PostgreSQL for embeddings.
 
+## Cognitive Memory (CoALA)
+
+llmemory implements the memory and internal-action concepts from [CoALA — Cognitive Architectures for Language Agents](https://arxiv.org/abs/2309.02427) (Sumers et al., 2024), so a framework can build agents with episodic/semantic/procedural memory, structured working memory, and reasoning/retrieval/learning actions.
+
+| CoALA concept | llmemory |
+|---|---|
+| Working memory | `Llmemory::WorkingMemory` |
+| Episodic memory | `Llmemory::LongTerm::Episodic::Memory` |
+| Semantic memory | `FileBased::Memory` / `GraphBased::Memory` |
+| Procedural memory | `Llmemory::LongTerm::Procedural::Memory` |
+| Reasoning action | `Llmemory::Actions::Reason` |
+| Retrieval action | `Retrieval::Engine` (+ feedback, iterative) |
+| Learning action | `memorize` / `record_episode` / `register_skill` / reflection |
+| Uniform interface | `Llmemory::MemoryModule` (`read`/`write`/`list`/`stats`/`forget`) |
+
+All three long-term memories below are **additive** — episodic and procedural coexist with semantic memory rather than replacing it. They support `:memory`, `:file`, `:postgres` and `:active_record` backends. Retrieval is keyword-based by default (tokenized, so multi-word queries work); semantic (embedding) retrieval is **opt-in** via `config.episodic_vector_enabled` / `config.procedural_vector_enabled` (or by injecting a `vector_store:`), which makes `search_candidates` hybrid (vector + keyword).
+
+### Working memory (structured, persists across LLM calls)
+
+A symbolic scratch space for the current session, distinct from the raw message buffer. Backed by the same pluggable short-term stores, under a namespaced session key so it never collides with messages.
+
+```ruby
+wm = Llmemory::WorkingMemory.new(user_id: "u1", session_id: "s1")
+# or, from the unified API: memory.working_memory
+
+wm.goals = ["plan a trip to Lisbon"]
+wm.current_task = "find flights"
+wm.set(:budget, 1000)           # arbitrary custom slot
+
+wm.goals                        # => ["plan a trip to Lisbon"]
+wm.custom_slots                 # => { budget: 1000 }
+wm.update(last_observation: "no direct flights", scratchpad: "try connections")
+wm.to_h                         # full state; wm.clear! to reset
+```
+
+Predefined slots: `goals`, `current_task`, `retrieved_context`, `scratchpad`, `last_observation`, `intermediate_reasoning`.
+
+### Reasoning action
+
+Read working memory, call the LLM, write the result back — CoALA's reasoning action. Composable (reason → retrieve → reason); it does not touch long-term memory.
+
+```ruby
+Llmemory::Actions::Reason.call(
+  working_memory: wm,
+  template: "Goal: {{goals}}. Observation: {{last_observation}}. What is the next step?",
+  into: :intermediate_reasoning           # slot to write to (nil to not write)
+)
+wm.intermediate_reasoning                 # => the LLM's answer
+
+# A callable template gets the working memory; `parse` transforms the output before storing:
+Llmemory::Actions::Reason.call(
+  working_memory: wm,
+  template: ->(w) { "List 3 options for #{w.current_task}" },
+  parse: ->(out) { out.split("\n") },
+  into: :scratchpad
+)
+```
+
+### Episodic memory (trajectories of experience)
+
+Records what happened — ordered steps `(observation → action → result)` plus a summary, outcome and importance — so experiences can be retrieved as examples or distilled into knowledge by reflection.
+
+```ruby
+episodic = Llmemory::LongTerm::Episodic::Memory.new(user_id: "u1")
+
+id = episodic.record_episode(
+  steps: [{ observation: "deploy failed", action: "rolled back", result: "service restored" }],
+  outcome: "recovered",
+  importance: 0.8
+)
+
+episodic.recent_episodes(limit: 5)        # newest first
+episodic.search_candidates("rolled back") # retrieval-compatible candidates
+```
+
+### Reflection (episodic → semantic)
+
+Distills durable, higher-order insights from recent episodes and writes them to semantic memory with provenance back to the source episodes (the Reflexion / Generative Agents pattern).
+
+```ruby
+semantic = Llmemory::LongTerm::FileBased::Memory.new(user_id: "u1")
+reflector = Llmemory::Reflection::Reflector.new(episodic: episodic, semantic: semantic)
+
+reflector.reflect(window: 10)             # reads recent episodes -> LLM -> writes insights
+# Each insight is stored with provenance { method: "reflection", sources: [{ type: "episode", id: ... }] }
+```
+
+`semantic` must respond to `remember_fact(content:, category:, importance:, provenance:)` (file-based does; graph-based is a roadmap target).
+
+### Procedural memory (skill library)
+
+A Voyager-style library of reusable skills (prompts, templates, code). Skills track success/failure, and their success rate is surfaced as `importance` so proven skills rank higher in retrieval.
+
+```ruby
+skills = Llmemory::LongTerm::Procedural::Memory.new(user_id: "u1")
+
+id = skills.register_skill(
+  name: "rollback", description: "revert a bad deploy",
+  body: "kubectl rollout undo deployment/$1", kind: "code"   # kind: prompt | template | code
+)
+skills.register_skill(name: "rollback", body: "...newer...") # same name -> version auto-increments
+
+skills.find_skill("revert deploy")        # best match (a Skill)
+skills.report_outcome(id, success: true)  # feeds ranking + adaptive retrieval
+```
+
+### Uniform interface (MemoryModule)
+
+The queryable long-term memories (file, graph, episodic, procedural) share one agent-facing contract, so a framework can treat them polymorphically:
+
+```ruby
+memory.read(query, limit: 10)   # retrieve relevant entries (delegates to search_candidates)
+memory.write(...)               # ingest (memorize / record_episode / register_skill)
+memory.list(limit: 50)          # enumerate stored entries
+memory.stats                    # counts, e.g. { items: 12 } / { episodes: 4 } / { skills: 7 }
+memory.forget(ids:, reason:)    # see "Forgetting" below
+```
+
+### Provenance (lineage of every semantic datum)
+
+Facts (items), graph nodes/edges and reflection insights carry provenance — where they came from, how they were produced, with what confidence — so a conclusion can be traced back to its source.
+
+```ruby
+item = storage.get_all_items("u1").first
+item[:provenance]
+# => { sources: [{ type: "resource", id: "res_3" }], method: "fact_extraction", confidence: 0.9, created_at: "..." }
+```
+
+Graph nodes/edges record a SHA-256 fingerprint of the ingested text (lineage without persisting the raw document). Build provenance directly with `Llmemory::Provenance.build(method:, sources:, confidence:)`.
+
+### Adaptive retrieval (feedback loop)
+
+Tell the retrieval engine which retrieved items were useful or noisy; repeatedly-useful items rank higher in future retrievals, noise is dampened. Item ids come from the candidates returned by `read` / `search_candidates`.
+
+```ruby
+engine = Retrieval::Engine.new(memory)
+results = memory.read("deployment incidents")        # candidates carry :id
+
+engine.report_feedback(useful_ids: [results.first[:id]], harmful_ids: [])
+# Next retrievals reweight accordingly. Set config.retrieval_feedback_weight = 0 to disable.
+```
+
+### Iterative retrieval (multi-hop)
+
+Retrieve, reason about what is still missing, then retrieve again — for multi-hop questions a single pass would miss.
+
+```ruby
+engine.iterative_retrieve(
+  "What is the capital of France and its population?",
+  max_hops: 3
+)
+# After each hop an LLM proposes a follow-up query (or "DONE"). Pass a custom
+# `reasoner: ->(question, accumulated, hop) { ... }` to drive the loop yourself.
+```
+
+### Forgetting (unlearning with audit)
+
+Remove entries by id, with an audit trail of what was forgotten, when and why.
+
+```ruby
+removed = memory.forget(ids: [item_id], reason: "user requested deletion")  # => count removed
+
+Llmemory::ForgetLog.new.entries("u1")
+# => [{ memory_type: "file_based", ids: ["item_7"], count: 1, reason: "user requested deletion", at: "..." }]
+```
+
+Supported for file-based, episodic and procedural memory (hard delete by id). Graph forgetting (edge/node lifecycle with orphan handling) is a roadmap item.
+
 ## Advanced Memory Management
 
 These features improve robustness and efficiency, inspired by OpenClaw's memory system.

data/lib/generators/llmemory/install/templates/create_llmemory_tables.rb

@@ -30,6 +30,26 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
     end
     add_index :llmemory_categories, [:user_id, :category_name], unique: true
 
+    # Episodic long-term memory (trajectories) — JSONB document per episode
+    create_table :llmemory_episodes, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.jsonb :data, null: false, default: {}
+      t.text :search_text
+      t.timestamps
+    end
+    add_index :llmemory_episodes, :user_id
+
+    # Procedural long-term memory (skill library) — JSONB document per skill
+    create_table :llmemory_skills, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :user_id, null: false
+      t.jsonb :data, null: false, default: {}
+      t.text :search_text
+      t.timestamps
+    end
+    add_index :llmemory_skills, :user_id
+
     create_table :llmemory_checkpoints do |t|
       t.string :user_id, null: false
       t.string :session_id, null: false

data/lib/llmemory/actions/reason.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Actions
+    # CoALA's "reasoning" action: read working memory, call the LLM, write the
+    # result back to working memory. Unlike retrieval (long-term -> working) or
+    # learning (working -> long-term), reasoning reads from and writes to working
+    # memory, producing new information for the current decision.
+    #
+    # It is a small, composable primitive — agents can chain reason -> retrieve
+    # -> reason — and deliberately does NOT touch long-term memory.
+    #
+    #   Llmemory::Actions::Reason.call(
+    #     working_memory: wm,
+    #     template: "Given goals {{goals}}, what is the next step?",
+    #     into: :intermediate_reasoning
+    #   )
+    #
+    # `template` is either a String (with {{slot}} placeholders filled from
+    # working memory) or a callable that receives the WorkingMemory and returns
+    # the prompt. `parse` optionally transforms the raw LLM output before it is
+    # stored. `into` is the slot to write to (nil to reason without writing).
+    # Returns the parsed result.
+    class Reason
+      DEFAULT_SLOT = :intermediate_reasoning
+
+      def self.call(working_memory:, template:, into: DEFAULT_SLOT, parse: nil, llm: nil)
+        client = llm || Llmemory::LLM.client
+        prompt = render(template, working_memory)
+        output = client.invoke(prompt).to_s
+        result = parse ? parse.call(output) : output
+        working_memory.set(into, result) unless into.nil?
+        result
+      end
+
+      def self.render(template, working_memory)
+        return template.call(working_memory).to_s if template.respond_to?(:call)
+        interpolate(template.to_s, working_memory.to_h)
+      end
+
+      def self.interpolate(text, slots)
+        text.gsub(/\{\{(\w+)\}\}/) do
+          key = Regexp.last_match(1).to_sym
+          slots.key?(key) ? slots[key].to_s : ""
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/actions.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "actions/reason"
+
+module Llmemory
+  module Actions
+  end
+end

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

@@ -70,6 +70,14 @@ module Llmemory
             Llmemory::LongTerm::GraphBased::Storages::MemoryStorage.new
           end
         end
+
+        def episodic_storage(store_type = nil)
+          Llmemory::LongTerm::Episodic::Storages.build(store: (store_type || Llmemory.configuration.long_term_store))
+        end
+
+        def procedural_storage(store_type = nil)
+          Llmemory::LongTerm::Procedural::Storages.build(store: (store_type || Llmemory.configuration.long_term_store))
+        end
       end
     end
   end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Episodic < Commands::Base
+        def option_parser(parser)
+          parser.on("--limit N", Integer, "Max number of episodes (newest first)") { |v| @limit = v }
+          parser.on("--store TYPE", "Storage type (memory|file|postgres|active_record)") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory episodes USER_ID [--limit N] [--store TYPE]"
+            exit 1
+          end
+
+          storage = episodic_storage(@store_type)
+          episodes = storage.list_episodes(user_id, limit: @limit)
+
+          if episodes.empty?
+            puts "No episodes for user #{user_id}."
+            return
+          end
+
+          episodes.each do |e|
+            id = e[:id] || e["id"]
+            summary = e[:summary] || e["summary"]
+            outcome = e[:outcome] || e["outcome"]
+            importance = e[:importance] || e["importance"]
+            steps = e[:steps] || e["steps"] || []
+            puts "[#{id}] (importance: #{importance}; outcome: #{outcome || 'n/a'}) #{summary}"
+            puts "  steps: #{Array(steps).size}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class ForgetLog < Commands::Base
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory forget-log USER_ID"
+            exit 1
+          end
+
+          entries = Llmemory::ForgetLog.new(store: short_term_store).entries(user_id)
+
+          if entries.empty?
+            puts "No forget audit entries for user #{user_id}."
+            return
+          end
+
+          entries.each do |e|
+            type = e[:memory_type] || e["memory_type"]
+            count = e[:count] || e["count"]
+            reason = e[:reason] || e["reason"]
+            at = e[:at] || e["at"]
+            ids = e[:ids] || e["ids"] || []
+            reason_str = reason ? " — #{reason}" : ""
+            puts "[#{at}] #{type}: removed #{count} (#{ids.join(', ')})#{reason_str}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Procedural < Commands::Base
+        def option_parser(parser)
+          parser.on("--limit N", Integer, "Max number of skills (newest first)") { |v| @limit = v }
+          parser.on("--store TYPE", "Storage type (memory|file|postgres|active_record)") { |v| @store_type = v }
+        end
+
+        def execute(argv, _opts)
+          user_id = argv.first
+          unless user_id
+            $stderr.puts "Usage: llmemory skills USER_ID [--limit N] [--store TYPE]"
+            exit 1
+          end
+
+          storage = procedural_storage(@store_type)
+          skills = storage.list_skills(user_id, limit: @limit)
+
+          if skills.empty?
+            puts "No skills for user #{user_id}."
+            return
+          end
+
+          skills.each do |s|
+            id = s[:id] || s["id"]
+            name = s[:name] || s["name"]
+            kind = s[:kind] || s["kind"]
+            version = s[:version] || s["version"]
+            succ = (s[:success_count] || s["success_count"] || 0).to_i
+            fail = (s[:failure_count] || s["failure_count"] || 0).to_i
+            total = succ + fail
+            rate = total.zero? ? "n/a" : format("%.2f", succ.to_f / total)
+            puts "[#{id}] #{name} v#{version} (#{kind}) — success rate: #{rate} (#{succ}/#{total})"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Llmemory
+  module Cli
+    module Commands
+      class Working < Commands::Base
+        def execute(argv, _opts)
+          user_id, session_id = argv
+          unless user_id && session_id
+            $stderr.puts "Usage: llmemory working USER_ID SESSION_ID"
+            exit 1
+          end
+
+          wm = Llmemory::WorkingMemory.new(user_id: user_id, session_id: session_id, store: short_term_store)
+          state = wm.to_h
+
+          if state.empty?
+            puts "Empty working memory for user #{user_id}, session #{session_id}."
+            return
+          end
+
+          state.each do |slot, value|
+            puts "#{slot}: #{value.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/cli.rb

@@ -5,6 +5,10 @@ require_relative "cli/commands/base"
 require_relative "cli/commands/users"
 require_relative "cli/commands/short_term"
 require_relative "cli/commands/long_term"
+require_relative "cli/commands/episodic"
+require_relative "cli/commands/procedural"
+require_relative "cli/commands/working"
+require_relative "cli/commands/forget_log"
 require_relative "cli/commands/stats"
 require_relative "cli/commands/search"
 require_relative "cli/commands/mcp"
@@ -47,6 +51,10 @@ module Llmemory
         "nodes" => Cli::Commands::LongTerm::Nodes,
         "edges" => Cli::Commands::LongTerm::Edges,
         "graph" => Cli::Commands::LongTerm::Graph,
+        "episodes" => Cli::Commands::Episodic,
+        "skills" => Cli::Commands::Procedural,
+        "working" => Cli::Commands::Working,
+        "forget_log" => Cli::Commands::ForgetLog,
         "search" => Cli::Commands::Search,
         "stats" => Cli::Commands::Stats,
         "mcp" => Cli::Commands::Mcp
@@ -68,6 +76,10 @@ module Llmemory
           nodes USER_ID            List graph nodes (graph-based)
           edges USER_ID            List graph edges (graph-based)
           graph USER_ID            Export graph (--format dot|json)
+          episodes USER_ID         List recorded episodes (episodic memory)
+          skills USER_ID           List registered skills (procedural memory)
+          working USER_ID SESSION  Show working-memory slots for a session
+          forget-log USER_ID       Show audit of forgotten entries
           search USER_ID "query"   Search in memory
           stats [USER_ID]          Show statistics
           mcp [serve]              Start MCP server for LLM agents

data/lib/llmemory/configuration.rb

@@ -11,10 +11,13 @@ module Llmemory
                   :long_term_type,
                   :long_term_store,
                   :long_term_storage_path,
+                  :episodic_vector_enabled,
+                  :procedural_vector_enabled,
                   :database_url,
                   :vector_store,
                   :time_decay_half_life_days,
                   :importance_weight,
+                  :retrieval_feedback_weight,
                   :max_retrieval_tokens,
                   :prune_after_days,
                   :compact_max_bytes,
@@ -54,10 +57,13 @@ module Llmemory
       @long_term_type = :file_based
       @long_term_store = :memory
       @long_term_storage_path = ENV["LLMEMORY_STORAGE_PATH"] || "./llmemory_data"
+      @episodic_vector_enabled = false
+      @procedural_vector_enabled = false
       @database_url = ENV["DATABASE_URL"]
       @vector_store = nil
       @time_decay_half_life_days = 30
       @importance_weight = 1.0
+      @retrieval_feedback_weight = 0.5
       @max_retrieval_tokens = 2000
       @prune_after_days = 90
       @compact_max_bytes = 8192

data/lib/llmemory/forget_log.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "short_term/stores"
+
+module Llmemory
+  # Append-only audit trail of forgotten memory entries. CoALA notes that
+  # modifying and deleting memory ("unlearning") are understudied; when an agent
+  # removes knowledge it should remain accountable for what was removed, when and
+  # why. ForgetLog records that trail, unified per user across memory types.
+  #
+  # Backed by the same pluggable short-term stores as the rest of the session
+  # layer, under a per-user pseudo-session key.
+  class ForgetLog
+    SESSION_KEY = "__forget_log__"
+
+    def initialize(store: nil)
+      @store = store || ShortTerm::Stores.build
+    end
+
+    def record(user_id, memory_type:, ids:, reason: nil)
+      ids = Array(ids).map(&:to_s)
+      entry = {
+        memory_type: memory_type.to_s,
+        ids: ids,
+        count: ids.size,
+        reason: reason,
+        at: Time.now.iso8601
+      }
+      log = entries(user_id)
+      log << entry
+      @store.save(user_id, SESSION_KEY, { "entries" => log })
+      entry
+    end
+
+    def entries(user_id)
+      state = @store.load(user_id, SESSION_KEY)
+      return [] unless state.is_a?(Hash)
+      list = state[:entries] || state["entries"]
+      list.is_a?(Array) ? list.map { |e| symbolize(e) } : []
+    end
+
+    private
+
+    def symbolize(entry)
+      return entry unless entry.is_a?(Hash)
+      entry.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end