@cadenya/cadenya 0.87.0 → 0.89.0

package/src/resources/objectives/objectives.ts

@@ -241,8 +241,8 @@ export interface ContextWindowCompacted {
 
 /**
  * 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.
  */
 export interface MemoryRead {
   /**
@@ -267,7 +267,7 @@ export interface MemoryRead {
 
 /**
  * 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
@@ -275,9 +275,10 @@ export interface MemoryRead {
  */
 export interface MemoryReference {
   /**
-   * 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.
    */
   memoryEntryId?: string;
 
@@ -330,6 +331,11 @@ export interface Objective {
    */
   data?: { [key: string]: unknown };
 
+  /**
+   * Episodic is used to configure the episodic memory for the objective
+   */
+  episodicMemory?: Objective.EpisodicMemory;
+
   /**
    * ObjectiveInfo provides read-only aggregated statistics about an objective's
    * execution
@@ -337,23 +343,21 @@ export interface Objective {
   info?: ObjectiveInfo;
 
   /**
-   * 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.
+   * 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.
    */
-  memoryStack?: Array<MemoryReference>;
+  memoryCascade?: Array<MemoryReference>;
 
   /**
    * The output of the objective, populated when the objective completes. Will match
@@ -385,6 +389,25 @@ export interface Objective {
   userData?: { [key: string]: unknown };
 }
 
+export namespace Objective {
+  /**
+   * Episodic is used to configure the episodic memory for the objective
+   */
+  export interface EpisodicMemory {
+    /**
+     * The caller-supplied episodic key. Objectives created with the same key (for the
+     * same agent) share one episodic memory layer.
+     */
+    key?: string;
+
+    /**
+     * The episodic memory layer resolved (created or reused) for this objective's key.
+     * Populated by the system at objective creation.
+     */
+    memoryLayerId?: string;
+  }
+}
+
 /**
  * ObjectiveConfigSnapshot is the point-in-time snapshot of the agent, variation,
  * and (when applicable) schedule that an objective was started with.
@@ -502,8 +525,8 @@ export interface ObjectiveEventData {
 
   /**
    * 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.
    */
   memoryRead?: MemoryRead;
 
@@ -664,12 +687,14 @@ export interface ObjectiveInfo {
   currentContextWindowId: string;
 
   /**
-   * 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.
    */
-  effectiveMemoryStack: Array<MemoryReference>;
+  effectiveMemoryCascade: Array<MemoryReference>;
 
   /**
    * Total number of context windows that this objective has generated
@@ -862,6 +887,11 @@ export interface ObjectiveCreateParams {
    */
   data: { [key: string]: unknown };
 
+  /**
+   * Episodic is used to configure the episodic memory for the objective
+   */
+  episodicMemory?: ObjectiveCreateParams.EpisodicMemory;
+
   /**
    * 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
@@ -872,23 +902,21 @@ export interface ObjectiveCreateParams {
   initialMessage?: string;
 
   /**
-   * 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.
    */
-  memoryStack?: Array<MemoryReference>;
+  memoryCascade?: Array<MemoryReference>;
 
   /**
    * CreateOperationMetadata contains the user-provided fields for creating an
@@ -918,6 +946,17 @@ export interface ObjectiveCreateParams {
 }
 
 export namespace ObjectiveCreateParams {
+  /**
+   * Episodic is used to configure the episodic memory for the objective
+   */
+  export interface EpisodicMemory {
+    /**
+     * The caller-supplied episodic key. Objectives created with the same key (for the
+     * same agent) share one episodic memory layer.
+     */
+    key?: string;
+  }
+
   export interface Secret {
     name?: string;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.87.0'; // x-release-please-version
+export const VERSION = '0.89.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.87.0";
+export declare const VERSION = "0.89.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.87.0";
+export declare const VERSION = "0.89.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.87.0'; // x-release-please-version
+exports.VERSION = '0.89.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.87.0'; // x-release-please-version
+export const VERSION = '0.89.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map