cadenya 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc33022d12e62f8273e8a7aa25cc2f020c231e6ce29f66775f9b144747d5658f
-  data.tar.gz: 619df9b5f16e896b922e1f8a1fa312f175a869154eb78a54c29a641e20f09b6b
+  metadata.gz: 12a4c26346682e6c70e9ce503df02f091ce2073e37f522e372106696b66f8437
+  data.tar.gz: e799c37f8c84900db9cdf5d4cfc0bacd2b623c7d8ff0407b12d2d89b2bfc88ee
 SHA512:
-  metadata.gz: 67d08c0901b15069f74e1a8a071876d9ac7c2871f5d73c2986c28ce4b6c01fe564a3385e6bd932f018a6392094d10e3d0a860f9bcd199435cc4fb99beb3a52d4
-  data.tar.gz: e6bd7a52e5e2a517108f7eeb6a3902c4662ed72c4158e06da10fc0862fc9292191d479ede3e87662a6104d9a680fe62d9e05d51be0f3b15ed9015907780415f4
+  metadata.gz: be228543f1c57ae71379a60d35bc0ceae0aa24498041a3ffc69b14f6b55b6a5c34f4e232e453933c148149ce46a0d49cca232683f8218b0e1ec22eeed8591b07
+  data.tar.gz: 9d93340c52c5d99382179ed1b51804720fe7464c7b55ac7c604a868ddbe52103718bdaab4f1632ea73c201b8324aef318a3673caa3e7481d2dbc766d7fcd05f9

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.14.0 (2026-06-11)
+
+Full Changelog: [v0.13.0...v0.14.0](https://github.com/cadenya/cadenya-ruby/compare/v0.13.0...v0.14.0)
+
+### Features
+
+* **api:** api update ([4b8c8d2](https://github.com/cadenya/cadenya-ruby/commit/4b8c8d26a3e7e55103f11eeeae4f32f7893288ce))
+
+## 0.13.0 (2026-06-11)
+
+Full Changelog: [v0.12.0...v0.13.0](https://github.com/cadenya/cadenya-ruby/compare/v0.12.0...v0.13.0)
+
+### Features
+
+* **api:** api update ([9a5ddd6](https://github.com/cadenya/cadenya-ruby/commit/9a5ddd6a2e2628aa7a73894216112b252ca8b0ba))
+
 ## 0.12.0 (2026-06-10)
 
 Full Changelog: [v0.11.0...v0.12.0](https://github.com/cadenya/cadenya-ruby/compare/v0.11.0...v0.12.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "cadenya", "~> 0.12.0"
+gem "cadenya", "~> 0.14.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/cadenya/client.rb

@@ -37,8 +37,8 @@ module Cadenya
     attr_reader :objectives
 
     # Manage memory layers and their entries. Layers are named containers that can be
-    # composed into an objective's memory stack; entries are the keyed values within a
-    # layer. System-managed layers (e.g., episodic layers created by the runtime)
+    # composed into an objective's memory cascade; entries are the keyed values within
+    # a layer. System-managed layers (e.g., episodic layers created by the runtime)
     # cannot be mutated through this API.
     # @return [Cadenya::Resources::MemoryLayers]
     attr_reader :memory_layers

data/lib/cadenya/models/agent_spec.rb

@@ -18,6 +18,24 @@ module Cadenya
       #   @return [String, nil]
       optional :description, String
 
+      # @!attribute enable_episodic_memory
+      #   Enable episodic memory for objectives created for this agent. When true,
+      #   objective creation requires an episodic_memory key and the system finds or
+      #   creates a memory layer for that (agent, key) pair, letting the agent store and
+      #   retrieve memories across objectives that share the key. Memory is agent-level so
+      #   all variations of the agent share the same layers.
+      #
+      #   @return [Boolean, nil]
+      optional :enable_episodic_memory, Cadenya::Internal::Type::Boolean, api_name: :enableEpisodicMemory
+
+      # @!attribute episodic_memory_ttl
+      #   How long episodic memories should be retained. Each new objective slides the
+      #   layer's expiry forward by this duration, and stored entries expire this long
+      #   after they are written. If not set, episodic memories are retained indefinitely.
+      #
+      #   @return [Integer, nil]
+      optional :episodic_memory_ttl, Integer, api_name: :episodicMemoryTtl
+
       # @!attribute input_data_schema
       #   InputDataSchema is used for enforcing a data input when objectives are created.
       #   This is valuable when using liquid formatting in agent variation prompts. Input
@@ -47,7 +65,7 @@ module Cadenya
       #   @return [String, nil]
       optional :webhook_events_url, String, api_name: :webhookEventsUrl
 
-      # @!method initialize(variation_selection_mode:, description: nil, input_data_schema: nil, output_definition: nil, webhook_events_url: nil)
+      # @!method initialize(variation_selection_mode:, description: nil, enable_episodic_memory: nil, episodic_memory_ttl: nil, input_data_schema: nil, output_definition: nil, webhook_events_url: nil)
       #   Some parameter documentations has been truncated, see
       #   {Cadenya::Models::AgentSpec} for more details.
       #
@@ -57,6 +75,10 @@ module Cadenya
       #
       #   @param description [String] Description of the agent's purpose
       #
+      #   @param enable_episodic_memory [Boolean] Enable episodic memory for objectives created for this agent.
+      #
+      #   @param episodic_memory_ttl [Integer] How long episodic memories should be retained.
+      #
       #   @param input_data_schema [Hash{Symbol=>Object}] InputDataSchema is used for enforcing a data input when objectives are created.
       #
       #   @param output_definition [Hash{Symbol=>Object}] Optional output definition for objectives created for this agent.

data/lib/cadenya/models/agents/agent_variation_info.rb

@@ -36,7 +36,8 @@ module Cadenya
 
           # @!attribute memory_layer_assignments
           #   Read-only list of memory layer assignments for this variation, returned in
-          #   ascending `position` (bottom → top). Capped at 10 entries.
+          #   ascending `position` (most specific first — resolution order). Capped at 10
+          #   entries.
           #
           #   @return [Array<Cadenya::Models::Agents::VariationMemoryLayerAssignment>, nil]
           optional :memory_layer_assignments,

data/lib/cadenya/models/agents/agent_variation_spec.rb

@@ -25,23 +25,6 @@ module Cadenya
         #   @return [String, nil]
         optional :description, String
 
-        # @!attribute enable_episodic_memory
-        #   Enable episodic memory for objectives using this variation. When true, the
-        #   system automatically creates a document namespace for each objective using the
-        #   objective's episodic_key as the external_id, allowing the agent to store and
-        #   retrieve documents specific to that episode.
-        #
-        #   @return [Boolean, nil]
-        optional :enable_episodic_memory, Cadenya::Internal::Type::Boolean, api_name: :enableEpisodicMemory
-
-        # @!attribute episodic_memory_ttl
-        #   How long episodic memories should be retained. After this duration, episodic
-        #   document namespaces can be automatically cleaned up. If not set, episodic
-        #   memories are retained indefinitely.
-        #
-        #   @return [Integer, nil]
-        optional :episodic_memory_ttl, Integer, api_name: :episodicMemoryTtl
-
         # @!attribute model_config
         #   ModelConfig defines the model configuration for a variation
         #
@@ -86,7 +69,7 @@ module Cadenya
         #   @return [Integer, nil]
         optional :weight, Integer
 
-        # @!method initialize(compaction_config: nil, constraints: nil, description: nil, enable_episodic_memory: nil, episodic_memory_ttl: nil, model_config: nil, progressive_discovery: nil, system_prompt_template: nil, user_message_template: nil, weight: nil)
+        # @!method initialize(compaction_config: nil, constraints: nil, description: nil, model_config: nil, progressive_discovery: nil, system_prompt_template: nil, user_message_template: nil, weight: nil)
         #   Some parameter documentations has been truncated, see
         #   {Cadenya::Models::Agents::AgentVariationSpec} for more details.
         #
@@ -98,10 +81,6 @@ module Cadenya
         #
         #   @param description [String] Human-readable description of what this variation does or when it should be used
         #
-        #   @param enable_episodic_memory [Boolean] Enable episodic memory for objectives using this variation.
-        #
-        #   @param episodic_memory_ttl [Integer] How long episodic memories should be retained.
-        #
         #   @param model_config [Cadenya::Models::Agents::AgentVariationSpecModelConfig] ModelConfig defines the model configuration for a variation
         #
         #   @param progressive_discovery [Cadenya::Models::Agents::AgentVariationSpecProgressiveDiscovery] ProgressiveDiscovery is used to indicate that the agent should automatically dis

data/lib/cadenya/models/agents/variation_add_memory_layer_params.rb

@@ -31,7 +31,8 @@ module Cadenya
         optional :memory_layer_id, String, api_name: :memoryLayerId
 
         # @!attribute position
-        #   Position in the stack. If omitted, server appends (max existing position + 1).
+        #   Position in the baseline cascade (lower = more specific). If omitted, the server
+        #   appends at the most general end (max existing position + 1).
         #
         #   @return [Integer, nil]
         optional :position, Integer
@@ -48,7 +49,7 @@ module Cadenya
         #
         #   @param memory_layer_id [String] Layer to attach. Accepts the canonical `memlyr_…` form or the `external_id:<valu
         #
-        #   @param position [Integer] Position in the stack. If omitted, server appends
+        #   @param position [Integer] Position in the baseline cascade (lower = more specific). If
         #
         #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
       end

data/lib/cadenya/models/agents/variation_memory_layer_assignment.rb

@@ -17,9 +17,10 @@ module Cadenya
         optional :memory_layer, -> { Cadenya::BareMetadata }, api_name: :memoryLayer
 
         # @!attribute position
-        #   Position in the variation's baseline stack. Lower values sit lower; the
-        #   highest-position assignment is on top of the variation's baseline. Gaps are fine
-        #   — only relative position matters. Positions must be unique within a variation; a
+        #   Position in the variation's baseline cascade. Position is specificity,
+        #   CSS-style: a LOWER position is more specific and is consulted first; the
+        #   highest-position assignment is the most general fallback. Gaps are fine — only
+        #   relative position matters. Positions must be unique within a variation; a
         #   request that would collide with an existing assignment's position is rejected
         #   with InvalidArgument.
         #
@@ -40,8 +41,8 @@ module Cadenya
         #   {Cadenya::Models::Agents::VariationMemoryLayerAssignment} for more details.
         #
         #   VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a
-        #   given position in the variation's baseline memory stack. A variation has at most
-        #   one assignment per memory_layer_id.
+        #   given position in the variation's baseline memory cascade. A variation has at
+        #   most one assignment per memory_layer_id.
         #
         #   Variations only support whole-layer attachments — entry pinning is an
         #   objective-level capability.
@@ -50,7 +51,7 @@ module Cadenya
         #
         #   @param memory_layer [Cadenya::Models::BareMetadata] BareMetadata contains the minimal metadata for a resource: the ID and an
         #
-        #   @param position [Integer] Position in the variation's baseline stack. Lower values sit lower;
+        #   @param position [Integer] Position in the variation's baseline cascade. Position is
       end
     end
   end

data/lib/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_entry_outcome.rb

@@ -31,8 +31,8 @@ module Cadenya
         #   MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed
         #   by their key, which follows the S3 object key safe-character convention (see
         #   MemoryEntrySpec.key for the full rule). Keys are unique within a single layer;
-        #   the same key may appear in multiple layers, in which case the LIFO stack-walk
-        #   determines which one wins for a given objective.
+        #   the same key may appear in multiple layers, in which case the cascade walk
+        #   determines which one wins for a given objective (most specific layer first).
         #
         #   MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not
         #   carry the entry body — callers that need the body must fetch the entry

data/lib/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_layer_outcome.rb

@@ -29,11 +29,11 @@ module Cadenya
 
         # @!attribute resource
         #   MemoryLayer is a named container of memory entries that can be composed into an
-        #   objective's memory stack. Layers are workspace-scoped resources. The layer type
-        #   controls how its entries participate in the agent loop — see MemoryLayerType for
-        #   details.
+        #   objective's memory cascade. Layers are workspace-scoped resources. The layer
+        #   type controls how its entries participate in the agent loop — see
+        #   MemoryLayerType for details.
         #
-        #   See "Memory stack composition" above for how layers compose at lookup time.
+        #   See "Memory cascade composition" above for how layers compose at lookup time.
         #
         #   @return [Cadenya::Models::MemoryLayer, nil]
         optional :resource, -> { Cadenya::MemoryLayer }

data/lib/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_variation_memory_layer_outcome.rb

@@ -24,8 +24,8 @@ module Cadenya
 
         # @!attribute resource
         #   VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a
-        #   given position in the variation's baseline memory stack. A variation has at most
-        #   one assignment per memory_layer_id.
+        #   given position in the variation's baseline memory cascade. A variation has at
+        #   most one assignment per memory_layer_id.
         #
         #   Variations only support whole-layer attachments — entry pinning is an
         #   objective-level capability.

data/lib/cadenya/models/memory_layer.rb

@@ -25,11 +25,11 @@ module Cadenya
       #   {Cadenya::Models::MemoryLayer} for more details.
       #
       #   MemoryLayer is a named container of memory entries that can be composed into an
-      #   objective's memory stack. Layers are workspace-scoped resources. The layer type
-      #   controls how its entries participate in the agent loop — see MemoryLayerType for
-      #   details.
+      #   objective's memory cascade. Layers are workspace-scoped resources. The layer
+      #   type controls how its entries participate in the agent loop — see
+      #   MemoryLayerType for details.
       #
-      #   See "Memory stack composition" above for how layers compose at lookup time.
+      #   See "Memory cascade composition" above for how layers compose at lookup time.
       #
       #   @param metadata [Cadenya::Models::ResourceMetadata] Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
       #

data/lib/cadenya/models/memory_layer_list_params.rb

@@ -12,6 +12,12 @@ module Cadenya
       #   @return [String]
       required :workspace_id, String
 
+      # @!attribute agent_id
+      #   Filter to episodic layers belonging to this agent.
+      #
+      #   @return [String, nil]
+      optional :agent_id, String
+
       # @!attribute bundle_key
       #   Filter by bundle_key — return only resources owned by this bundle.
       #
@@ -24,6 +30,14 @@ module Cadenya
       #   @return [String, nil]
       optional :cursor, String
 
+      # @!attribute episodic_key_prefix
+      #   Filter to episodic layers whose episodic key starts with this prefix (e.g.
+      #   "customer/" matches "customer/42" and "customer/43"). Useful for namespaced
+      #   keys, similar to a redis key scan.
+      #
+      #   @return [String, nil]
+      optional :episodic_key_prefix, String
+
       # @!attribute include_info
       #   When set to true you may use more of your alloted API rate-limit
       #
@@ -60,13 +74,20 @@ module Cadenya
       #   @return [Symbol, Cadenya::Models::MemoryLayerListParams::Type, nil]
       optional :type, enum: -> { Cadenya::MemoryLayerListParams::Type }
 
-      # @!method initialize(workspace_id:, bundle_key: nil, cursor: nil, include_info: nil, limit: nil, prefix: nil, query: nil, sort_order: nil, type: nil, request_options: {})
+      # @!method initialize(workspace_id:, agent_id: nil, bundle_key: nil, cursor: nil, episodic_key_prefix: nil, include_info: nil, limit: nil, prefix: nil, query: nil, sort_order: nil, type: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Cadenya::Models::MemoryLayerListParams} for more details.
+      #
       #   @param workspace_id [String]
       #
+      #   @param agent_id [String] Filter to episodic layers belonging to this agent.
+      #
       #   @param bundle_key [String] Filter by bundle_key — return only resources owned by this bundle.
       #
       #   @param cursor [String] Pagination cursor from previous response
       #
+      #   @param episodic_key_prefix [String] Filter to episodic layers whose episodic key starts with this prefix
+      #
       #   @param include_info [Boolean] When set to true you may use more of your alloted API rate-limit
       #
       #   @param limit [Integer] Maximum number of results to return

data/lib/cadenya/models/memory_layer_spec.rb

@@ -16,6 +16,20 @@ module Cadenya
       optional :description, String
 
       response_only do
+        # @!attribute agent_id
+        #   Server-set on episodic layers: the agent this layer belongs to. Unset for
+        #   non-episodic layers.
+        #
+        #   @return [String, nil]
+        optional :agent_id, String, api_name: :agentId
+
+        # @!attribute episodic_key
+        #   Server-set on episodic layers: the caller-supplied episodic key the layer was
+        #   created for. Unset for non-episodic layers.
+        #
+        #   @return [String, nil]
+        optional :episodic_key, String, api_name: :episodicKey
+
         # @!attribute expires_at
         #   For layers with a finite lifetime (e.g., episodic), the time at which the layer
         #   becomes eligible for cleanup. Set by the system; unset for persistent layers.
@@ -26,21 +40,25 @@ module Cadenya
         # @!attribute system_managed
         #   Server-set. True for layers managed by the system (e.g., episodic layers created
         #   automatically when an objective uses an episodic_key). System-managed layers
-        #   cannot be assigned to objective stacks via the API and cannot be mutated by
+        #   cannot be assigned to objective cascades via the API and cannot be mutated by
         #   clients — their lifecycle is controlled entirely by the runtime.
         #
         #   @return [Boolean, nil]
         optional :system_managed, Cadenya::Internal::Type::Boolean, api_name: :systemManaged
       end
 
-      # @!method initialize(type:, description: nil, expires_at: nil, system_managed: nil)
+      # @!method initialize(type:, agent_id: nil, description: nil, episodic_key: nil, expires_at: nil, system_managed: nil)
       #   Some parameter documentations has been truncated, see
       #   {Cadenya::Models::MemoryLayerSpec} for more details.
       #
       #   @param type [Symbol, Cadenya::Models::MemoryLayerSpec::Type]
       #
+      #   @param agent_id [String] Server-set on episodic layers: the agent this layer belongs to. Unset for
+      #
       #   @param description [String] Human-readable description of the layer's purpose. Encouraged for
       #
+      #   @param episodic_key [String] Server-set on episodic layers: the caller-supplied episodic key the layer
+      #
       #   @param expires_at [Time] For layers with a finite lifetime (e.g., episodic), the time at which the
       #
       #   @param system_managed [Boolean] Server-set. True for layers managed by the system (e.g., episodic layers

data/lib/cadenya/models/memory_layers/memory_entry.rb

@@ -31,8 +31,8 @@ module Cadenya
         #   MemoryEntry is a single keyed value within a MemoryLayer. Entries are addressed
         #   by their key, which follows the S3 object key safe-character convention (see
         #   MemoryEntrySpec.key for the full rule). Keys are unique within a single layer;
-        #   the same key may appear in multiple layers, in which case the LIFO stack-walk
-        #   determines which one wins for a given objective.
+        #   the same key may appear in multiple layers, in which case the cascade walk
+        #   determines which one wins for a given objective (most specific layer first).
         #
         #   MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not
         #   carry the entry body — callers that need the body must fetch the entry

data/lib/cadenya/models/memory_read.rb

@@ -30,8 +30,8 @@ module Cadenya
       #   {Cadenya::Models::MemoryRead} for more details.
       #
       #   MemoryRead is emitted each time the agent resolves a key against the memory
-      #   stack and loads an entry. Lookups that miss (key not found in any layer) do not
-      #   emit this event.
+      #   cascade and loads an entry. Lookups that miss (key not found in any layer) do
+      #   not emit this event.
       #
       #   @param memory_entry_id [String] The specific entry that was read.
       #

data/lib/cadenya/models/memory_reference.rb

@@ -4,9 +4,10 @@ module Cadenya
   module Models
     class MemoryReference < Cadenya::Internal::Type::BaseModel
       # @!attribute memory_entry_id
-      #   When set, pushes only this entry from memory_layer_id onto the stack — behaves
-      #   as a single-entry layer (only this key resolves at this position). The entry
-      #   must belong to memory_layer_id; mismatches are rejected with InvalidArgument.
+      #   When set, inserts only this entry from memory_layer_id into the cascade —
+      #   behaves as a single-entry layer (only this key resolves at this position). The
+      #   entry must belong to memory_layer_id; mismatches are rejected with
+      #   InvalidArgument.
       #
       #   @return [String, nil]
       optional :memory_entry_id, String, api_name: :memoryEntryId
@@ -21,13 +22,13 @@ module Cadenya
       #   {Cadenya::Models::MemoryReference} for more details.
       #
       #   MemoryReference identifies a memory layer or a specific entry within one, for
-      #   composition into a memory stack. Used on objectives (where entry pinning is
+      #   composition into a memory cascade. Used on objectives (where entry pinning is
       #   permitted).
       #
       #   memory*layer_id accepts both the canonical form (memlyr*…) and the external-id
       #   form (external_id:my-custom-id). The same applies to memory_entry_id when set.
       #
-      #   @param memory_entry_id [String] When set, pushes only this entry from memory_layer_id onto the stack —
+      #   @param memory_entry_id [String] When set, inserts only this entry from memory_layer_id into the cascade —
       #
       #   @param memory_layer_id [String]
     end

data/lib/cadenya/models/objective.rb

@@ -18,27 +18,31 @@ module Cadenya
       #   @return [Cadenya::Models::OperationMetadata]
       required :metadata, -> { Cadenya::OperationMetadata }
 
-      # @!attribute memory_stack
-      #   Memory layers/entries to push onto this objective's memory stack on top of the
-      #   baseline stack inherited from the selected variation.
+      # @!attribute episodic_memory
+      #   Episodic is used to configure the episodic memory for the objective
       #
-      #   Array order is push order: the first element sits lower in the objective's
-      #   contribution to the stack; the LAST element ends up on top of the effective
-      #   stack. Entries pinned via memory_entry_id behave as single-entry layers at their
-      #   position.
+      #   @return [Cadenya::Models::Objective::EpisodicMemory, nil]
+      optional :episodic_memory, -> { Cadenya::Objective::EpisodicMemory }, api_name: :episodicMemory
+
+      # @!attribute memory_cascade
+      #   Memory layers/entries layered over the baseline cascade inherited from the
+      #   selected variation — element-level rules over inherited styles, in CSS terms.
       #
-      #   System-managed layers (e.g., episodic) cannot be referenced here; they attach
-      #   themselves automatically based on episodic_key.
+      #   Array order is resolution order: EARLIER elements are more specific and are
+      #   consulted first. Entries pinned via memory_entry_id behave as single-entry
+      #   layers at their position.
       #
-      #   Stack size cap: the TOTAL effective stack (variation's memory layers
+      #   System-managed layers (e.g., episodic) cannot be referenced here; they attach
+      #   themselves automatically based on the episodic key.
       #
-      #   - this field) must not exceed 10 entries. A request that would produce an
-      #     effective stack larger than 10 is rejected with InvalidArgument.
+      #   Size cap: the TOTAL effective cascade (this field + the variation's memory layer
+      #   assignments) must not exceed 10 entries. A request that would produce a larger
+      #   cascade is rejected with InvalidArgument.
       #
       #   @return [Array<Cadenya::Models::MemoryReference>, nil]
-      optional :memory_stack,
+      optional :memory_cascade,
                -> { Cadenya::Internal::Type::ArrayOf[Cadenya::MemoryReference] },
-               api_name: :memoryStack
+               api_name: :memoryCascade
 
       # @!attribute secrets
       #   Secrets that can be used in the headers for tool calls using the secret
@@ -110,7 +114,7 @@ module Cadenya
                  api_name: :userData
       end
 
-      # @!method initialize(config_snapshot:, initial_message:, metadata:, state:, system_prompt:, data: nil, info: nil, memory_stack: nil, output: nil, parent_objective_id: nil, secrets: nil, state_message: nil, user_data: nil)
+      # @!method initialize(config_snapshot:, initial_message:, metadata:, state:, system_prompt:, data: nil, episodic_memory: nil, info: nil, memory_cascade: nil, output: nil, parent_objective_id: nil, secrets: nil, state_message: nil, user_data: nil)
       #   Some parameter documentations has been truncated, see
       #   {Cadenya::Models::Objective} for more details.
       #
@@ -130,9 +134,11 @@ module Cadenya
       #
       #   @param data [Hash{Symbol=>Object}] Arbitrary data for the objective
       #
+      #   @param episodic_memory [Cadenya::Models::Objective::EpisodicMemory] Episodic is used to configure the episodic memory for the objective
+      #
       #   @param info [Cadenya::Models::ObjectiveInfo] ObjectiveInfo provides read-only aggregated statistics about an objective's exec
       #
-      #   @param memory_stack [Array<Cadenya::Models::MemoryReference>] Memory layers/entries to push onto this objective's memory stack on
+      #   @param memory_cascade [Array<Cadenya::Models::MemoryReference>] Memory layers/entries layered over the baseline cascade inherited
       #
       #   @param output [Hash{Symbol=>Object}] The output of the objective, populated when the objective completes. Will match
       #
@@ -161,6 +167,35 @@ module Cadenya
         # @!method self.values
         #   @return [Array<Symbol>]
       end
+
+      # @see Cadenya::Models::Objective#episodic_memory
+      class EpisodicMemory < Cadenya::Internal::Type::BaseModel
+        # @!attribute key
+        #   The caller-supplied episodic key. Objectives created with the same key (for the
+        #   same agent) share one episodic memory layer.
+        #
+        #   @return [String, nil]
+        optional :key, String
+
+        response_only do
+          # @!attribute memory_layer_id
+          #   The episodic memory layer resolved (created or reused) for this objective's key.
+          #   Populated by the system at objective creation.
+          #
+          #   @return [String, nil]
+          optional :memory_layer_id, String, api_name: :memoryLayerId
+        end
+
+        # @!method initialize(key: nil, memory_layer_id: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Cadenya::Models::Objective::EpisodicMemory} for more details.
+        #
+        #   Episodic is used to configure the episodic memory for the objective
+        #
+        #   @param key [String] The caller-supplied episodic key. Objectives created with the same key
+        #
+        #   @param memory_layer_id [String] The episodic memory layer resolved (created or reused) for this
+      end
     end
   end
 end

data/lib/cadenya/models/objective_create_params.rb

@@ -24,6 +24,14 @@ module Cadenya
       #   @return [Hash{Symbol=>Object}]
       required :data, Cadenya::Internal::Type::HashOf[Cadenya::Internal::Type::Unknown]
 
+      # @!attribute episodic_memory
+      #   Episodic is used to configure the episodic memory for the objective
+      #
+      #   @return [Cadenya::Models::ObjectiveCreateParams::EpisodicMemory, nil]
+      optional :episodic_memory,
+               -> { Cadenya::ObjectiveCreateParams::EpisodicMemory },
+               api_name: :episodicMemory
+
       # @!attribute initial_message
       #   Optional override for the initial message sent to the agent. This becomes the
       #   first user message in the LLM chat history. When not set, the selected
@@ -34,27 +42,25 @@ module Cadenya
       #   @return [String, nil]
       optional :initial_message, String, api_name: :initialMessage
 
-      # @!attribute memory_stack
-      #   Memory layers/entries to push onto this objective's memory stack on top of the
-      #   baseline stack inherited from the selected variation.
+      # @!attribute memory_cascade
+      #   Memory layers/entries layered over the baseline cascade inherited from the
+      #   selected variation — element-level rules over inherited styles, in CSS terms.
       #
-      #   Array order is push order: the first element sits lower in the objective's
-      #   contribution to the stack; the LAST element ends up on top of the effective
-      #   stack. Entries pinned via memory_entry_id behave as single-entry layers at their
-      #   position.
+      #   Array order is resolution order: EARLIER elements are more specific and are
+      #   consulted first. Entries pinned via memory_entry_id behave as single-entry
+      #   layers at their position.
       #
       #   System-managed layers (e.g., episodic) cannot be referenced here; they attach
-      #   themselves automatically based on episodic_key.
-      #
-      #   Stack size cap: the TOTAL effective stack (variation's memory layers
+      #   themselves automatically based on the episodic key.
       #
-      #   - this field) must not exceed 10 entries. A request that would produce an
-      #     effective stack larger than 10 is rejected with InvalidArgument.
+      #   Size cap: the TOTAL effective cascade (this field + the variation's memory layer
+      #   assignments) must not exceed 10 entries. A request that would produce a larger
+      #   cascade is rejected with InvalidArgument.
       #
       #   @return [Array<Cadenya::Models::MemoryReference>, nil]
-      optional :memory_stack,
+      optional :memory_cascade,
                -> { Cadenya::Internal::Type::ArrayOf[Cadenya::MemoryReference] },
-               api_name: :memoryStack
+               api_name: :memoryCascade
 
       # @!attribute metadata
       #   CreateOperationMetadata contains the user-provided fields for creating an
@@ -88,7 +94,7 @@ module Cadenya
       #   @return [String, nil]
       optional :variation_id, String, api_name: :variationId
 
-      # @!method initialize(workspace_id:, agent_id:, data:, initial_message: nil, memory_stack: nil, metadata: nil, secrets: nil, user_data: nil, variation_id: nil, request_options: {})
+      # @!method initialize(workspace_id:, agent_id:, data:, episodic_memory: nil, initial_message: nil, memory_cascade: nil, metadata: nil, secrets: nil, user_data: nil, variation_id: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {Cadenya::Models::ObjectiveCreateParams} for more details.
       #
@@ -98,9 +104,11 @@ module Cadenya
       #
       #   @param data [Hash{Symbol=>Object}] Arbitrary data for the objective. May be used in liquid templates for prompts co
       #
+      #   @param episodic_memory [Cadenya::Models::ObjectiveCreateParams::EpisodicMemory] Episodic is used to configure the episodic memory for the objective
+      #
       #   @param initial_message [String] Optional override for the initial message sent to the agent. This becomes the fi
       #
-      #   @param memory_stack [Array<Cadenya::Models::MemoryReference>] Memory layers/entries to push onto this objective's memory stack on
+      #   @param memory_cascade [Array<Cadenya::Models::MemoryReference>] Memory layers/entries layered over the baseline cascade inherited
       #
       #   @param metadata [Cadenya::Models::CreateOperationMetadata] CreateOperationMetadata contains the user-provided fields for creating
       #
@@ -112,6 +120,23 @@ module Cadenya
       #
       #   @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}]
 
+      class EpisodicMemory < Cadenya::Internal::Type::BaseModel
+        # @!attribute key
+        #   The caller-supplied episodic key. Objectives created with the same key (for the
+        #   same agent) share one episodic memory layer.
+        #
+        #   @return [String, nil]
+        optional :key, String
+
+        # @!method initialize(key: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Cadenya::Models::ObjectiveCreateParams::EpisodicMemory} for more details.
+        #
+        #   Episodic is used to configure the episodic memory for the objective
+        #
+        #   @param key [String] The caller-supplied episodic key. Objectives created with the same key
+      end
+
       class Secret < Cadenya::Internal::Type::BaseModel
         # @!attribute name
         #