cadenya 0.12.0 → 0.14.0

data/lib/cadenya/models/objective_event_data.rb

@@ -38,8 +38,8 @@ module Cadenya
 
       # @!attribute memory_read
       #   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.
       #
       #   @return [Cadenya::Models::MemoryRead, nil]
       optional :memory_read, -> { Cadenya::MemoryRead }, api_name: :memoryRead

data/lib/cadenya/models/objective_info.rb

@@ -31,16 +31,18 @@ module Cadenya
         #   @return [String]
         required :current_context_window_id, String, api_name: :currentContextWindowId
 
-        # @!attribute effective_memory_stack
-        #   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.
+        # @!attribute effective_memory_cascade
+        #   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.
         #
         #   @return [Array<Cadenya::Models::MemoryReference>]
-        required :effective_memory_stack,
+        required :effective_memory_cascade,
                  -> { Cadenya::Internal::Type::ArrayOf[Cadenya::MemoryReference] },
-                 api_name: :effectiveMemoryStack
+                 api_name: :effectiveMemoryCascade
 
         # @!attribute total_context_windows
         #   Total number of context windows that this objective has generated
@@ -80,7 +82,7 @@ module Cadenya
         required :total_tool_calls, Integer, api_name: :totalToolCalls
       end
 
-      # @!method initialize(agent:, agent_variation:, created_by:, current_context_window_id:, effective_memory_stack:, total_context_windows:, total_events:, total_input_tokens:, total_iterations:, total_output_tokens:, total_tool_calls:)
+      # @!method initialize(agent:, agent_variation:, created_by:, current_context_window_id:, effective_memory_cascade:, total_context_windows:, total_events:, total_input_tokens:, total_iterations:, total_output_tokens:, total_tool_calls:)
       #   Some parameter documentations has been truncated, see
       #   {Cadenya::Models::ObjectiveInfo} for more details.
       #
@@ -95,7 +97,7 @@ module Cadenya
       #
       #   @param current_context_window_id [String] ID of the objective's current (most recent) context window. Hydrated on
       #
-      #   @param effective_memory_stack [Array<Cadenya::Models::MemoryReference>] The effective memory stack at objective creation time, flattened
+      #   @param effective_memory_cascade [Array<Cadenya::Models::MemoryReference>] The effective memory cascade at objective creation time: the
       #
       #   @param total_context_windows [Integer] Total number of context windows that this objective has generated
       #

data/lib/cadenya/resources/agents/variations.rb

@@ -256,7 +256,7 @@ module Cadenya
         # {Cadenya::Models::Agents::VariationAddMemoryLayerParams} for more details.
         #
         # Attaches a memory layer to a variation at a given position in the variation's
-        # baseline memory stack.
+        # baseline memory cascade.
         #
         # @overload add_memory_layer(variation_id, workspace_id:, agent_id:, memory_layer_id: nil, position: nil, request_options: {})
         #
@@ -268,7 +268,7 @@ module Cadenya
         #
         # @param memory_layer_id [String] Body param: Layer to attach. Accepts the canonical `memlyr_…` form or the `exter
         #
-        # @param position [Integer] Body param: Position in the stack. If omitted, server appends
+        # @param position [Integer] Body param: Position in the baseline cascade (lower = more specific). If
         #
         # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/cadenya/resources/memory_layers/entries.rb

@@ -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
         # Some parameter documentations has been truncated, see

data/lib/cadenya/resources/memory_layers.rb

@@ -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.
       # @return [Cadenya::Resources::MemoryLayers::Entries]
       attr_reader :entries
@@ -108,16 +108,23 @@ module Cadenya
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Cadenya::Models::MemoryLayerListParams} for more details.
+      #
       # Lists all memory layers in the workspace
       #
-      # @overload list(workspace_id, bundle_key: nil, cursor: nil, include_info: nil, limit: nil, prefix: nil, query: nil, sort_order: nil, type: nil, request_options: {})
+      # @overload list(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: {})
       #
       # @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
@@ -142,7 +149,9 @@ module Cadenya
           method: :get,
           path: ["v1/workspaces/%1$s/memory_layers", workspace_id],
           query: query.transform_keys(
+            agent_id: "agentId",
             bundle_key: "bundleKey",
+            episodic_key_prefix: "episodicKeyPrefix",
             include_info: "includeInfo",
             sort_order: "sortOrder"
           ),

data/lib/cadenya/resources/objectives.rb

@@ -20,7 +20,7 @@ module Cadenya
       #
       # Creates a new objective in the workspace
       #
-      # @overload create(workspace_id, agent_id:, data:, initial_message: nil, memory_stack: nil, metadata: nil, secrets: nil, user_data: nil, variation_id: nil, request_options: {})
+      # @overload create(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: {})
       #
       # @param workspace_id [String]
       #
@@ -28,9 +28,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
       #

data/lib/cadenya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cadenya
-  VERSION = "0.12.0"
+  VERSION = "0.14.0"
 end

data/rbi/cadenya/client.rbi

@@ -32,8 +32,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.
     sig { returns(Cadenya::Resources::MemoryLayers) }
     attr_reader :memory_layers

data/rbi/cadenya/models/agent_spec.rbi

@@ -18,6 +18,26 @@ module Cadenya
       sig { params(description: String).void }
       attr_writer :description
 
+      # 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.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :enable_episodic_memory
+
+      sig { params(enable_episodic_memory: T::Boolean).void }
+      attr_writer :enable_episodic_memory
+
+      # 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.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :episodic_memory_ttl
+
+      sig { params(episodic_memory_ttl: Integer).void }
+      attr_writer :episodic_memory_ttl
+
       # InputDataSchema is used for enforcing a data input when objectives are created.
       # This is valuable when using liquid formatting in agent variation prompts. Input
       # data schema is also valuable when using an agent as a sub-agent, as the schema
@@ -52,6 +72,8 @@ module Cadenya
           variation_selection_mode:
             Cadenya::AgentSpec::VariationSelectionMode::OrSymbol,
           description: String,
+          enable_episodic_memory: T::Boolean,
+          episodic_memory_ttl: Integer,
           input_data_schema: T::Hash[Symbol, T.anything],
           output_definition: T::Hash[Symbol, T.anything],
           webhook_events_url: String
@@ -63,6 +85,16 @@ module Cadenya
         variation_selection_mode:,
         # Description of the agent's purpose
         description: nil,
+        # 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.
+        enable_episodic_memory: nil,
+        # 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.
+        episodic_memory_ttl: nil,
         # InputDataSchema is used for enforcing a data input when objectives are created.
         # This is valuable when using liquid formatting in agent variation prompts. Input
         # data schema is also valuable when using an agent as a sub-agent, as the schema
@@ -85,6 +117,8 @@ module Cadenya
             variation_selection_mode:
               Cadenya::AgentSpec::VariationSelectionMode::OrSymbol,
             description: String,
+            enable_episodic_memory: T::Boolean,
+            episodic_memory_ttl: Integer,
             input_data_schema: T::Hash[Symbol, T.anything],
             output_definition: T::Hash[Symbol, T.anything],
             webhook_events_url: String

data/rbi/cadenya/models/agents/agent_variation_info.rbi

@@ -54,7 +54,8 @@ module Cadenya
         attr_writer :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.
         sig do
           returns(
             T.nilable(T::Array[Cadenya::Agents::VariationMemoryLayerAssignment])
@@ -133,7 +134,8 @@ module Cadenya
           # Total number of objective feedbacks received for this variation
           feedback_count: nil,
           # 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.
           memory_layer_assignments: nil,
           # Count of memory layer assignments.
           memory_layer_count: nil,

data/rbi/cadenya/models/agents/agent_variation_spec.rbi

@@ -51,25 +51,6 @@ module Cadenya
         sig { params(description: String).void }
         attr_writer :description
 
-        # 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.
-        sig { returns(T.nilable(T::Boolean)) }
-        attr_reader :enable_episodic_memory
-
-        sig { params(enable_episodic_memory: T::Boolean).void }
-        attr_writer :enable_episodic_memory
-
-        # 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.
-        sig { returns(T.nilable(Integer)) }
-        attr_reader :episodic_memory_ttl
-
-        sig { params(episodic_memory_ttl: Integer).void }
-        attr_writer :episodic_memory_ttl
-
         # ModelConfig defines the model configuration for a variation
         sig do
           returns(T.nilable(Cadenya::Agents::AgentVariationSpecModelConfig))
@@ -139,8 +120,6 @@ module Cadenya
               Cadenya::Agents::AgentVariationSpecCompactionConfig::OrHash,
             constraints: Cadenya::Agents::AgentVariationSpecConstraints::OrHash,
             description: String,
-            enable_episodic_memory: T::Boolean,
-            episodic_memory_ttl: Integer,
             model_config:
               Cadenya::Agents::AgentVariationSpecModelConfig::OrHash,
             progressive_discovery:
@@ -158,15 +137,6 @@ module Cadenya
           constraints: nil,
           # Human-readable description of what this variation does or when it should be used
           description: nil,
-          # 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.
-          enable_episodic_memory: nil,
-          # 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.
-          episodic_memory_ttl: nil,
           # ModelConfig defines the model configuration for a variation
           model_config: nil,
           # ProgressiveDiscovery is used to indicate that the agent should automatically
@@ -199,8 +169,6 @@ module Cadenya
                 Cadenya::Agents::AgentVariationSpecCompactionConfig,
               constraints: Cadenya::Agents::AgentVariationSpecConstraints,
               description: String,
-              enable_episodic_memory: T::Boolean,
-              episodic_memory_ttl: Integer,
               model_config: Cadenya::Agents::AgentVariationSpecModelConfig,
               progressive_discovery:
                 Cadenya::Agents::AgentVariationSpecProgressiveDiscovery,

data/rbi/cadenya/models/agents/variation_add_memory_layer_params.rbi

@@ -32,7 +32,8 @@ module Cadenya
         sig { params(memory_layer_id: String).void }
         attr_writer :memory_layer_id
 
-        # 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).
         sig { returns(T.nilable(Integer)) }
         attr_reader :position
 
@@ -56,7 +57,8 @@ module Cadenya
           # Layer to attach. Accepts the canonical `memlyr_…` form or the
           # `external_id:<value>` form.
           memory_layer_id: nil,
-          # 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).
           position: nil,
           request_options: {}
         )

data/rbi/cadenya/models/agents/variation_memory_layer_assignment.rbi

@@ -24,9 +24,10 @@ module Cadenya
         sig { params(memory_layer: Cadenya::BareMetadata::OrHash).void }
         attr_writer :memory_layer
 
-        # 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.
         sig { returns(T.nilable(Integer)) }
@@ -44,8 +45,8 @@ module Cadenya
         attr_writer :id
 
         # 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.
@@ -67,9 +68,10 @@ module Cadenya
           # to an objective. Both fields are server-populated; clients provide IDs through
           # sibling fields rather than by constructing a BareMetadata themselves.
           memory_layer: nil,
-          # 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.
           position: nil

data/rbi/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_entry_outcome.rbi

@@ -61,8 +61,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
@@ -98,8 +98,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/rbi/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_memory_layer_outcome.rbi

@@ -59,11 +59,11 @@ module Cadenya
         attr_writer :external_id
 
         # 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.
         sig { returns(T.nilable(Cadenya::MemoryLayer)) }
         attr_reader :resource
 
@@ -91,11 +91,11 @@ module Cadenya
           error: nil,
           external_id: nil,
           # 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.
           resource: nil
         )
         end

data/rbi/cadenya/models/bulk_workspace_resources/bulk_workspace_apply_result_data_variation_memory_layer_outcome.rbi

@@ -53,8 +53,8 @@ module Cadenya
         attr_writer :error
 
         # 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.
@@ -89,8 +89,8 @@ module Cadenya
           # [API Design Guide](https://cloud.google.com/apis/design/errors).
           error: nil,
           # 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/rbi/cadenya/models/memory_layer.rbi

@@ -26,11 +26,11 @@ module Cadenya
       attr_writer :info
 
       # 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.
       sig do
         params(
           metadata: Cadenya::ResourceMetadata::OrHash,

data/rbi/cadenya/models/memory_layer_list_params.rbi

@@ -14,6 +14,13 @@ module Cadenya
       sig { returns(String) }
       attr_accessor :workspace_id
 
+      # Filter to episodic layers belonging to this agent.
+      sig { returns(T.nilable(String)) }
+      attr_reader :agent_id
+
+      sig { params(agent_id: String).void }
+      attr_writer :agent_id
+
       # Filter by bundle_key — return only resources owned by this bundle.
       sig { returns(T.nilable(String)) }
       attr_reader :bundle_key
@@ -28,6 +35,15 @@ module Cadenya
       sig { params(cursor: String).void }
       attr_writer :cursor
 
+      # 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.
+      sig { returns(T.nilable(String)) }
+      attr_reader :episodic_key_prefix
+
+      sig { params(episodic_key_prefix: String).void }
+      attr_writer :episodic_key_prefix
+
       # When set to true you may use more of your alloted API rate-limit
       sig { returns(T.nilable(T::Boolean)) }
       attr_reader :include_info
@@ -73,8 +89,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,
@@ -86,10 +104,16 @@ module Cadenya
       end
       def self.new(
         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
@@ -110,8 +134,10 @@ module Cadenya
         override.returns(
           {
             workspace_id: String,
+            agent_id: String,
             bundle_key: String,
             cursor: String,
+            episodic_key_prefix: String,
             include_info: T::Boolean,
             limit: Integer,
             prefix: String,

data/rbi/cadenya/models/memory_layer_spec.rbi

@@ -19,6 +19,22 @@ module Cadenya
       sig { params(description: String).void }
       attr_writer :description
 
+      # Server-set on episodic layers: the agent this layer belongs to. Unset for
+      # non-episodic layers.
+      sig { returns(T.nilable(String)) }
+      attr_reader :agent_id
+
+      sig { params(agent_id: String).void }
+      attr_writer :agent_id
+
+      # Server-set on episodic layers: the caller-supplied episodic key the layer was
+      # created for. Unset for non-episodic layers.
+      sig { returns(T.nilable(String)) }
+      attr_reader :episodic_key
+
+      sig { params(episodic_key: String).void }
+      attr_writer :episodic_key
+
       # 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.
       sig { returns(T.nilable(Time)) }
@@ -29,7 +45,7 @@ module Cadenya
 
       # 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.
       sig { returns(T.nilable(T::Boolean)) }
       attr_reader :system_managed
@@ -40,22 +56,30 @@ module Cadenya
       sig do
         params(
           type: Cadenya::MemoryLayerSpec::Type::OrSymbol,
+          agent_id: String,
           description: String,
+          episodic_key: String,
           expires_at: Time,
           system_managed: T::Boolean
         ).returns(T.attached_class)
       end
       def self.new(
         type:,
+        # Server-set on episodic layers: the agent this layer belongs to. Unset for
+        # non-episodic layers.
+        agent_id: nil,
         # Human-readable description of the layer's purpose. Encouraged for user-created
         # layers; system-managed layers may have a generated description.
         description: nil,
+        # Server-set on episodic layers: the caller-supplied episodic key the layer was
+        # created for. Unset for non-episodic layers.
+        episodic_key: nil,
         # 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.
         expires_at: nil,
         # 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.
         system_managed: nil
       )
@@ -65,7 +89,9 @@ module Cadenya
         override.returns(
           {
             type: Cadenya::MemoryLayerSpec::Type::OrSymbol,
+            agent_id: String,
             description: String,
+            episodic_key: String,
             expires_at: Time,
             system_managed: T::Boolean
           }

data/rbi/cadenya/models/memory_layers/memory_entry.rbi

@@ -41,8 +41,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