cadenya 0.12.0 → 0.14.0

data/rbi/cadenya/models/memory_read.rbi

@@ -32,8 +32,8 @@ module Cadenya
       attr_writer :message
 
       # 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.
       sig do
         params(
           memory_entry_id: String,

data/rbi/cadenya/models/memory_reference.rbi

@@ -8,9 +8,10 @@ module Cadenya
           T.any(Cadenya::MemoryReference, Cadenya::Internal::AnyHash)
         end
 
-      # 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.
       sig { returns(T.nilable(String)) }
       attr_reader :memory_entry_id
 
@@ -24,7 +25,7 @@ module Cadenya
       attr_writer :memory_layer_id
 
       # 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
@@ -35,9 +36,10 @@ module Cadenya
         )
       end
       def self.new(
-        # 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.
         memory_entry_id: nil,
         memory_layer_id: nil
       )

data/rbi/cadenya/models/objective.rbi

@@ -19,28 +19,35 @@ module Cadenya
       sig { params(metadata: Cadenya::OperationMetadata::OrHash).void }
       attr_writer :metadata
 
-      # Memory layers/entries to push onto this objective's memory stack on top of the
-      # baseline stack inherited from the selected variation.
+      # Episodic is used to configure the episodic memory for the objective
+      sig { returns(T.nilable(Cadenya::Objective::EpisodicMemory)) }
+      attr_reader :episodic_memory
+
+      sig do
+        params(episodic_memory: Cadenya::Objective::EpisodicMemory::OrHash).void
+      end
+      attr_writer :episodic_memory
+
+      # 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.
       sig { returns(T.nilable(T::Array[Cadenya::MemoryReference])) }
-      attr_reader :memory_stack
+      attr_reader :memory_cascade
 
       sig do
-        params(memory_stack: T::Array[Cadenya::MemoryReference::OrHash]).void
+        params(memory_cascade: T::Array[Cadenya::MemoryReference::OrHash]).void
       end
-      attr_writer :memory_stack
+      attr_writer :memory_cascade
 
       # Secrets that can be used in the headers for tool calls using the secret
       # interpolation format.
@@ -125,8 +132,9 @@ module Cadenya
           state: Cadenya::Objective::State::OrSymbol,
           system_prompt: String,
           data: T::Hash[Symbol, T.anything],
+          episodic_memory: Cadenya::Objective::EpisodicMemory::OrHash,
           info: Cadenya::ObjectiveInfo::OrHash,
-          memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
+          memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
           output: T::Hash[Symbol, T.anything],
           parent_objective_id: String,
           secrets: T::Array[Cadenya::ObjectiveSecret::OrHash],
@@ -150,25 +158,25 @@ module Cadenya
         system_prompt:,
         # Arbitrary data for the objective
         data: nil,
+        # Episodic is used to configure the episodic memory for the objective
+        episodic_memory: nil,
         # ObjectiveInfo provides read-only aggregated statistics about an objective's
         # execution
         info: nil,
-        # Memory layers/entries to push onto this objective's memory stack on top of the
-        # baseline stack inherited from the selected variation.
+        # 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.
+        # themselves automatically based on the episodic key.
         #
-        # Stack size cap: the TOTAL effective stack (variation's memory layers
-        #
-        # - this field) must not exceed 10 entries. A request that would produce an
-        #   effective stack larger than 10 is rejected with InvalidArgument.
-        memory_stack: nil,
+        # 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.
+        memory_cascade: nil,
         # The output of the objective, populated when the objective completes. Will match
         # the schema of output_json_schema or output_json_inferred. This will only be set
         # if the state of the objective is set to STATE_FINALIZED
@@ -195,8 +203,9 @@ module Cadenya
             state: Cadenya::Objective::State::TaggedSymbol,
             system_prompt: String,
             data: T::Hash[Symbol, T.anything],
+            episodic_memory: Cadenya::Objective::EpisodicMemory,
             info: Cadenya::ObjectiveInfo,
-            memory_stack: T::Array[Cadenya::MemoryReference],
+            memory_cascade: T::Array[Cadenya::MemoryReference],
             output: T::Hash[Symbol, T.anything],
             parent_objective_id: String,
             secrets: T::Array[Cadenya::ObjectiveSecret],
@@ -236,6 +245,50 @@ module Cadenya
         def self.values
         end
       end
+
+      class EpisodicMemory < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::Objective::EpisodicMemory,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        # The caller-supplied episodic key. Objectives created with the same key (for the
+        # same agent) share one episodic memory layer.
+        sig { returns(T.nilable(String)) }
+        attr_reader :key
+
+        sig { params(key: String).void }
+        attr_writer :key
+
+        # The episodic memory layer resolved (created or reused) for this objective's key.
+        # Populated by the system at objective creation.
+        sig { returns(T.nilable(String)) }
+        attr_reader :memory_layer_id
+
+        sig { params(memory_layer_id: String).void }
+        attr_writer :memory_layer_id
+
+        # Episodic is used to configure the episodic memory for the objective
+        sig do
+          params(key: String, memory_layer_id: String).returns(T.attached_class)
+        end
+        def self.new(
+          # The caller-supplied episodic key. Objectives created with the same key (for the
+          # same agent) share one episodic memory layer.
+          key: nil,
+          # The episodic memory layer resolved (created or reused) for this objective's key.
+          # Populated by the system at objective creation.
+          memory_layer_id: nil
+        )
+        end
+
+        sig { override.returns({ key: String, memory_layer_id: String }) }
+        def to_hash
+        end
+      end
     end
   end
 end

data/rbi/cadenya/models/objective_create_params.rbi

@@ -22,6 +22,18 @@ module Cadenya
       sig { returns(T::Hash[Symbol, T.anything]) }
       attr_accessor :data
 
+      # Episodic is used to configure the episodic memory for the objective
+      sig { returns(T.nilable(Cadenya::ObjectiveCreateParams::EpisodicMemory)) }
+      attr_reader :episodic_memory
+
+      sig do
+        params(
+          episodic_memory:
+            Cadenya::ObjectiveCreateParams::EpisodicMemory::OrHash
+        ).void
+      end
+      attr_writer :episodic_memory
+
       # 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
       # variation's user_message_template is rendered with user_data instead. If neither
@@ -33,28 +45,26 @@ module Cadenya
       sig { params(initial_message: String).void }
       attr_writer :initial_message
 
-      # Memory layers/entries to push onto this objective's memory stack on top of the
-      # baseline stack inherited from the selected variation.
+      # 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.
       sig { returns(T.nilable(T::Array[Cadenya::MemoryReference])) }
-      attr_reader :memory_stack
+      attr_reader :memory_cascade
 
       sig do
-        params(memory_stack: T::Array[Cadenya::MemoryReference::OrHash]).void
+        params(memory_cascade: T::Array[Cadenya::MemoryReference::OrHash]).void
       end
-      attr_writer :memory_stack
+      attr_writer :memory_cascade
 
       # CreateOperationMetadata contains the user-provided fields for creating an
       # operation. Read-only fields (id, account_id, workspace_id, created_at,
@@ -101,8 +111,10 @@ module Cadenya
           workspace_id: String,
           agent_id: String,
           data: T::Hash[Symbol, T.anything],
+          episodic_memory:
+            Cadenya::ObjectiveCreateParams::EpisodicMemory::OrHash,
           initial_message: String,
-          memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
+          memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
           metadata: Cadenya::CreateOperationMetadata::OrHash,
           secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash],
           user_data: T::Hash[Symbol, T.anything],
@@ -116,28 +128,28 @@ module Cadenya
         # Arbitrary data for the objective. May be used in liquid templates for prompts
         # configured on the agent variation
         data:,
+        # Episodic is used to configure the episodic memory for the objective
+        episodic_memory: nil,
         # 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
         # variation's user_message_template is rendered with user_data instead. If neither
         # this field nor a user_message_template is present, the request is rejected with
         # InvalidArgument.
         initial_message: nil,
-        # Memory layers/entries to push onto this objective's memory stack on top of the
-        # baseline stack inherited from the selected variation.
+        # 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.
+        # themselves automatically based on the episodic key.
         #
-        # Stack size cap: the TOTAL effective stack (variation's memory layers
-        #
-        # - this field) must not exceed 10 entries. A request that would produce an
-        #   effective stack larger than 10 is rejected with InvalidArgument.
-        memory_stack: nil,
+        # 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.
+        memory_cascade: nil,
         # CreateOperationMetadata contains the user-provided fields for creating an
         # operation. Read-only fields (id, account_id, workspace_id, created_at,
         # profile_id) are excluded since they are set by the server.
@@ -162,8 +174,9 @@ module Cadenya
             workspace_id: String,
             agent_id: String,
             data: T::Hash[Symbol, T.anything],
+            episodic_memory: Cadenya::ObjectiveCreateParams::EpisodicMemory,
             initial_message: String,
-            memory_stack: T::Array[Cadenya::MemoryReference],
+            memory_cascade: T::Array[Cadenya::MemoryReference],
             metadata: Cadenya::CreateOperationMetadata,
             secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret],
             user_data: T::Hash[Symbol, T.anything],
@@ -175,6 +188,37 @@ module Cadenya
       def to_hash
       end
 
+      class EpisodicMemory < Cadenya::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Cadenya::ObjectiveCreateParams::EpisodicMemory,
+              Cadenya::Internal::AnyHash
+            )
+          end
+
+        # The caller-supplied episodic key. Objectives created with the same key (for the
+        # same agent) share one episodic memory layer.
+        sig { returns(T.nilable(String)) }
+        attr_reader :key
+
+        sig { params(key: String).void }
+        attr_writer :key
+
+        # Episodic is used to configure the episodic memory for the objective
+        sig { params(key: String).returns(T.attached_class) }
+        def self.new(
+          # The caller-supplied episodic key. Objectives created with the same key (for the
+          # same agent) share one episodic memory layer.
+          key: nil
+        )
+        end
+
+        sig { override.returns({ key: String, memory_layer_id: String }) }
+        def to_hash
+        end
+      end
+
       class Secret < Cadenya::Internal::Type::BaseModel
         OrHash =
           T.type_alias do

data/rbi/cadenya/models/objective_event_data.rbi

@@ -53,8 +53,8 @@ module Cadenya
       attr_writer :finalized
 
       # 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.
       sig { returns(T.nilable(Cadenya::MemoryRead)) }
       attr_reader :memory_read
 
@@ -158,8 +158,8 @@ module Cadenya
         # compaction, or continuation are permitted.
         finalized: nil,
         # 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.
         memory_read: nil,
         sub_agent_spawned: nil,
         sub_agent_updated: nil,

data/rbi/cadenya/models/objective_info.rbi

@@ -36,12 +36,14 @@ module Cadenya
       sig { returns(String) }
       attr_accessor :current_context_window_id
 
-      # The effective memory stack at objective creation time, flattened from the
-      # variation's baseline plus Objective.memory_stack. Order is push order (last =
-      # top). Returned on reads so clients can see exactly what stack the objective is
-      # using without having to re-join variation state.
+      # The effective memory cascade at objective creation time: the episodic layer
+      # (when present), then Objective.memory_cascade, then the variation's baseline
+      # layers by ascending position. Order is resolution order — index 0 is the most
+      # specific and is consulted first; the first layer containing a key wins. Returned
+      # on reads so clients can see exactly what the objective resolves against without
+      # re-joining variation state.
       sig { returns(T::Array[Cadenya::MemoryReference]) }
-      attr_accessor :effective_memory_stack
+      attr_accessor :effective_memory_cascade
 
       # Total number of context windows that this objective has generated
       sig { returns(Integer) }
@@ -76,7 +78,7 @@ module Cadenya
           agent_variation: Cadenya::ResourceMetadata::OrHash,
           created_by: Cadenya::Profile::OrHash,
           current_context_window_id: String,
-          effective_memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
+          effective_memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
           total_context_windows: Integer,
           total_events: Integer,
           total_input_tokens: Integer,
@@ -97,11 +99,13 @@ module Cadenya
         # ID of the objective's current (most recent) context window. Hydrated on demand;
         # empty when the objective has not yet produced a context window.
         current_context_window_id:,
-        # The effective memory stack at objective creation time, flattened from the
-        # variation's baseline plus Objective.memory_stack. Order is push order (last =
-        # top). Returned on reads so clients can see exactly what stack the objective is
-        # using without having to re-join variation state.
-        effective_memory_stack:,
+        # The effective memory cascade at objective creation time: the episodic layer
+        # (when present), then Objective.memory_cascade, then the variation's baseline
+        # layers by ascending position. Order is resolution order — index 0 is the most
+        # specific and is consulted first; the first layer containing a key wins. Returned
+        # on reads so clients can see exactly what the objective resolves against without
+        # re-joining variation state.
+        effective_memory_cascade:,
         # Total number of context windows that this objective has generated
         total_context_windows:,
         # Total number of events generated during this objective's execution
@@ -125,7 +129,7 @@ module Cadenya
             agent_variation: Cadenya::ResourceMetadata,
             created_by: Cadenya::Profile,
             current_context_window_id: String,
-            effective_memory_stack: T::Array[Cadenya::MemoryReference],
+            effective_memory_cascade: T::Array[Cadenya::MemoryReference],
             total_context_windows: Integer,
             total_events: Integer,
             total_input_tokens: Integer,

data/rbi/cadenya/resources/agents/variations.rbi

@@ -182,7 +182,7 @@ module Cadenya
         end
 
         # Attaches a memory layer to a variation at a given position in the variation's
-        # baseline memory stack.
+        # baseline memory cascade.
         sig do
           params(
             variation_id: String,
@@ -205,8 +205,8 @@ module Cadenya
           # Body param: Layer to attach. Accepts the canonical `memlyr_…` form or the
           # `external_id:<value>` form.
           memory_layer_id: nil,
-          # Body param: Position in the stack. If omitted, server appends (max existing
-          # position + 1).
+          # Body param: Position in the baseline cascade (lower = more specific). If
+          # omitted, the server appends at the most general end (max existing position + 1).
           position: nil,
           request_options: {}
         )

data/rbi/cadenya/resources/memory_layers/entries.rbi

@@ -4,8 +4,8 @@ module Cadenya
   module Resources
     class MemoryLayers
       # 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.
       class Entries
         # Creates a new entry in a memory layer. Returns the detail view, including the

data/rbi/cadenya/resources/memory_layers.rbi

@@ -3,13 +3,13 @@
 module Cadenya
   module Resources
     # 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.
     class MemoryLayers
       # 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.
       sig { returns(Cadenya::Resources::MemoryLayers::Entries) }
       attr_reader :entries
@@ -84,8 +84,10 @@ module Cadenya
       sig do
         params(
           workspace_id: String,
+          agent_id: String,
           bundle_key: String,
           cursor: String,
+          episodic_key_prefix: String,
           include_info: T::Boolean,
           limit: Integer,
           prefix: String,
@@ -97,10 +99,16 @@ module Cadenya
       end
       def list(
         workspace_id,
+        # Filter to episodic layers belonging to this agent.
+        agent_id: nil,
         # Filter by bundle_key — return only resources owned by this bundle.
         bundle_key: nil,
         # Pagination cursor from previous response
         cursor: nil,
+        # 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.
+        episodic_key_prefix: nil,
         # When set to true you may use more of your alloted API rate-limit
         include_info: nil,
         # Maximum number of results to return

data/rbi/cadenya/resources/objectives.rbi

@@ -21,8 +21,10 @@ module Cadenya
           workspace_id: String,
           agent_id: String,
           data: T::Hash[Symbol, T.anything],
+          episodic_memory:
+            Cadenya::ObjectiveCreateParams::EpisodicMemory::OrHash,
           initial_message: String,
-          memory_stack: T::Array[Cadenya::MemoryReference::OrHash],
+          memory_cascade: T::Array[Cadenya::MemoryReference::OrHash],
           metadata: Cadenya::CreateOperationMetadata::OrHash,
           secrets: T::Array[Cadenya::ObjectiveCreateParams::Secret::OrHash],
           user_data: T::Hash[Symbol, T.anything],
@@ -36,28 +38,28 @@ module Cadenya
         # Arbitrary data for the objective. May be used in liquid templates for prompts
         # configured on the agent variation
         data:,
+        # Episodic is used to configure the episodic memory for the objective
+        episodic_memory: nil,
         # 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
         # variation's user_message_template is rendered with user_data instead. If neither
         # this field nor a user_message_template is present, the request is rejected with
         # InvalidArgument.
         initial_message: nil,
-        # Memory layers/entries to push onto this objective's memory stack on top of the
-        # baseline stack inherited from the selected variation.
+        # 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.
+        # themselves automatically based on the episodic key.
         #
-        # Stack size cap: the TOTAL effective stack (variation's memory layers
-        #
-        # - this field) must not exceed 10 entries. A request that would produce an
-        #   effective stack larger than 10 is rejected with InvalidArgument.
-        memory_stack: nil,
+        # 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.
+        memory_cascade: nil,
         # CreateOperationMetadata contains the user-provided fields for creating an
         # operation. Read-only fields (id, account_id, workspace_id, created_at,
         # profile_id) are excluded since they are set by the server.

data/sig/cadenya/models/agent_spec.rbs

@@ -4,6 +4,8 @@ module Cadenya
       {
         variation_selection_mode: Cadenya::Models::AgentSpec::variation_selection_mode,
         description: String,
+        enable_episodic_memory: bool,
+        episodic_memory_ttl: Integer,
         input_data_schema: ::Hash[Symbol, top],
         output_definition: ::Hash[Symbol, top],
         webhook_events_url: String
@@ -16,6 +18,14 @@ module Cadenya
 
       def description=: (String) -> String
 
+      attr_reader enable_episodic_memory: bool?
+
+      def enable_episodic_memory=: (bool) -> bool
+
+      attr_reader episodic_memory_ttl: Integer?
+
+      def episodic_memory_ttl=: (Integer) -> Integer
+
       attr_reader input_data_schema: ::Hash[Symbol, top]?
 
       def input_data_schema=: (::Hash[Symbol, top]) -> ::Hash[Symbol, top]
@@ -31,6 +41,8 @@ module Cadenya
       def initialize: (
         variation_selection_mode: Cadenya::Models::AgentSpec::variation_selection_mode,
         ?description: String,
+        ?enable_episodic_memory: bool,
+        ?episodic_memory_ttl: Integer,
         ?input_data_schema: ::Hash[Symbol, top],
         ?output_definition: ::Hash[Symbol, top],
         ?webhook_events_url: String
@@ -39,6 +51,8 @@ module Cadenya
       def to_hash: -> {
         variation_selection_mode: Cadenya::Models::AgentSpec::variation_selection_mode,
         description: String,
+        enable_episodic_memory: bool,
+        episodic_memory_ttl: Integer,
         input_data_schema: ::Hash[Symbol, top],
         output_definition: ::Hash[Symbol, top],
         webhook_events_url: String