# Memory Layers ## List memory layers `memory_layers.list(workspace_id, **kwargs) -> CursorPagination` **get** `/v1/workspaces/{workspaceId}/memory_layers` Lists all memory layers in the workspace ### Parameters - `workspace_id: String` - `bundle_key: String` Filter by bundle_key — return only resources owned by this bundle. - `cursor: String` Pagination cursor from previous response - `include_info: bool` When set to true you may use more of your alloted API rate-limit - `limit: Integer` Maximum number of results to return - `prefix: String` Filter expression (query param: prefix) - `query: String` Free-form search query - `sort_order: String` Sort order for results (asc or desc by creation time) - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` Filter by layer type - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` ### Returns - `class MemoryLayer` 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. See "Memory stack composition" above for how layers compose at lookup time. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. - `info: MemoryLayerInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `entry_count: Integer` Number of entries currently in this layer. - `last_used_at: Time` Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard. ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") page = cadenya.memory_layers.list("workspaceId") puts(page) ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "MEMORY_LAYER_TYPE_UNSPECIFIED", "description": "description", "expiresAt": "2019-12-27T18:11:19.117Z", "systemManaged": true }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "entryCount": 0, "lastUsedAt": "2019-12-27T18:11:19.117Z" } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Create a new memory layer `memory_layers.create(workspace_id, **kwargs) -> MemoryLayer` **post** `/v1/workspaces/{workspaceId}/memory_layers` Creates a new memory layer in the workspace ### Parameters - `workspace_id: String` - `metadata: CreateResourceMetadata` CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server. - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") - `bundle_key: String` Optional bundle ownership key. See ResourceMetadata.bundle_key. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. ### Returns - `class MemoryLayer` 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. See "Memory stack composition" above for how layers compose at lookup time. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. - `info: MemoryLayerInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `entry_count: Integer` Number of entries currently in this layer. - `last_used_at: Time` Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard. ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") memory_layer = cadenya.memory_layers.create( "workspaceId", metadata: {name: "name"}, spec: {type: :MEMORY_LAYER_TYPE_UNSPECIFIED} ) puts(memory_layer) ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "MEMORY_LAYER_TYPE_UNSPECIFIED", "description": "description", "expiresAt": "2019-12-27T18:11:19.117Z", "systemManaged": true }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "entryCount": 0, "lastUsedAt": "2019-12-27T18:11:19.117Z" } } ``` ## Get a memory layer by ID `memory_layers.retrieve(id, **kwargs) -> MemoryLayer` **get** `/v1/workspaces/{workspaceId}/memory_layers/{id}` Retrieves a memory layer by ID from the workspace ### Parameters - `workspace_id: String` - `id: String` ### Returns - `class MemoryLayer` 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. See "Memory stack composition" above for how layers compose at lookup time. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. - `info: MemoryLayerInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `entry_count: Integer` Number of entries currently in this layer. - `last_used_at: Time` Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard. ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") memory_layer = cadenya.memory_layers.retrieve("id", workspace_id: "workspaceId") puts(memory_layer) ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "MEMORY_LAYER_TYPE_UNSPECIFIED", "description": "description", "expiresAt": "2019-12-27T18:11:19.117Z", "systemManaged": true }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "entryCount": 0, "lastUsedAt": "2019-12-27T18:11:19.117Z" } } ``` ## Update a memory layer `memory_layers.update(id, **kwargs) -> MemoryLayer` **patch** `/v1/workspaces/{workspaceId}/memory_layers/{id}` Updates a memory layer in the workspace ### Parameters - `workspace_id: String` - `id: String` - `metadata: UpdateResourceMetadata` UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server. - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") - `bundle_key: String` Optional bundle ownership key. See ResourceMetadata.bundle_key. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. - `update_mask: String` ### Returns - `class MemoryLayer` 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. See "Memory stack composition" above for how layers compose at lookup time. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. - `info: MemoryLayerInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `entry_count: Integer` Number of entries currently in this layer. - `last_used_at: Time` Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard. ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") memory_layer = cadenya.memory_layers.update("id", workspace_id: "workspaceId") puts(memory_layer) ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "MEMORY_LAYER_TYPE_UNSPECIFIED", "description": "description", "expiresAt": "2019-12-27T18:11:19.117Z", "systemManaged": true }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "entryCount": 0, "lastUsedAt": "2019-12-27T18:11:19.117Z" } } ``` ## Delete a memory layer `memory_layers.delete(id, **kwargs) -> void` **delete** `/v1/workspaces/{workspaceId}/memory_layers/{id}` Deletes a memory layer from the workspace ### Parameters - `workspace_id: String` - `id: String` ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") result = cadenya.memory_layers.delete("id", workspace_id: "workspaceId") puts(result) ``` ## Domain Types ### Memory Layer - `class MemoryLayer` 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. See "Memory stack composition" above for how layers compose at lookup time. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. - `info: MemoryLayerInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `entry_count: Integer` Number of entries currently in this layer. - `last_used_at: Time` Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard. ### Memory Layer Info - `class MemoryLayerInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `entry_count: Integer` Number of entries currently in this layer. - `last_used_at: Time` Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard. ### Memory Layer Spec - `class MemoryLayerSpec` - `type: :MEMORY_LAYER_TYPE_UNSPECIFIED | :MEMORY_LAYER_TYPE_EPISODIC | :MEMORY_LAYER_TYPE_SKILLS` - `:MEMORY_LAYER_TYPE_UNSPECIFIED` - `:MEMORY_LAYER_TYPE_EPISODIC` - `:MEMORY_LAYER_TYPE_SKILLS` - `description: String` Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description. - `expires_at: Time` 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. - `system_managed: bool` 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 clients — their lifecycle is controlled entirely by the runtime. # Entries ## List memory entries `memory_layers.entries.list(memory_layer_id, **kwargs) -> CursorPagination` **get** `/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries` Lists all entries in a memory layer ### Parameters - `workspace_id: String` - `memory_layer_id: String` - `bundle_key: String` Filter by bundle_key — return only resources owned by this bundle. - `cursor: String` Pagination cursor from previous response - `include_info: bool` When set to true you may use more of your alloted API rate-limit - `limit: Integer` Maximum number of results to return - `prefix: String` Filter by key prefix (e.g., "skills/postmortem/" to list all entries under that hierarchy). Matches against the entry's key, not its name. - `query: String` Free-form search query - `sort_order: String` Sort order for results (asc or desc by creation time) ### Returns - `class MemoryEntry` 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. MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not carry the entry body — callers that need the body must fetch the entry individually via GetMemoryEntry, which returns a MemoryEntryDetail. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. - `info: MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") page = cadenya.memory_layers.entries.list("memoryLayerId", workspace_id: "workspaceId") puts(page) ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "key": "key", "description": "description" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "memoryLayer": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Create a new memory entry `memory_layers.entries.create(memory_layer_id, **kwargs) -> MemoryEntryDetail` **post** `/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries` Creates a new entry in a memory layer. Returns the detail view, including the resolved content body. ### Parameters - `workspace_id: String` - `memory_layer_id: String` - `metadata: CreateResourceMetadata` CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server. - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") - `bundle_key: String` Optional bundle ownership key. See ResourceMetadata.bundle_key. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntryCreateSpec` MemoryEntryCreateSpec is the input shape for CreateMemoryEntry. It accepts either inline content or a reference to a completed Upload; exactly one of the two must be set. - `key: String` See MemoryEntrySpec.key for the full rule set. Same constraints apply here. - `content: String` Inline content, written directly into the entry. - `description: String` - `upload_id: String` ID of a COMPLETE Upload. The server reads the object from storage, copies its bytes into the entry, and marks the upload consumed. ### Returns - `class MemoryEntryDetail` MemoryEntryDetail is the full representation of an entry, including the resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and UpdateMemoryEntry. - `content: String` The resolved body of the entry. For entries created or updated via an upload_id, this is the ingested content, not the original upload handle. May be empty; an entry with only a key and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload). - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. - `info: MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") memory_entry_detail = cadenya.memory_layers.entries.create( "memoryLayerId", workspace_id: "workspaceId", metadata: {name: "name"}, spec: {key: "key"} ) puts(memory_entry_detail) ``` #### Response ```json { "content": "content", "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "key": "key", "description": "description" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "memoryLayer": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } } } } ``` ## Get a memory entry by ID `memory_layers.entries.retrieve(id, **kwargs) -> MemoryEntryDetail` **get** `/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}` Retrieves a memory entry by ID from a memory layer. Returns the detail view, including the content body. ### Parameters - `workspace_id: String` - `memory_layer_id: String` - `id: String` ### Returns - `class MemoryEntryDetail` MemoryEntryDetail is the full representation of an entry, including the resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and UpdateMemoryEntry. - `content: String` The resolved body of the entry. For entries created or updated via an upload_id, this is the ingested content, not the original upload handle. May be empty; an entry with only a key and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload). - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. - `info: MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") memory_entry_detail = cadenya.memory_layers.entries.retrieve( "id", workspace_id: "workspaceId", memory_layer_id: "memoryLayerId" ) puts(memory_entry_detail) ``` #### Response ```json { "content": "content", "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "key": "key", "description": "description" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "memoryLayer": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } } } } ``` ## Update a memory entry `memory_layers.entries.update(id, **kwargs) -> MemoryEntryDetail` **patch** `/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}` Updates a memory entry in a memory layer. Returns the detail view, including the resolved content body. ### Parameters - `workspace_id: String` - `memory_layer_id: String` - `id: String` - `metadata: UpdateResourceMetadata` UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server. - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") - `bundle_key: String` Optional bundle ownership key. See ResourceMetadata.bundle_key. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntryUpdateSpec` MemoryEntryUpdateSpec is the input shape for UpdateMemoryEntry. Fields present in the request's update_mask are applied; unset fields are left alone. The source oneof is optional for updates — omit it to leave the body untouched, or set exactly one branch to replace it. - `content: String` - `description: String` - `key: String` - `upload_id: String` - `update_mask: String` ### Returns - `class MemoryEntryDetail` MemoryEntryDetail is the full representation of an entry, including the resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and UpdateMemoryEntry. - `content: String` The resolved body of the entry. For entries created or updated via an upload_id, this is the ingested content, not the original upload handle. May be empty; an entry with only a key and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload). - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. - `info: MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") memory_entry_detail = cadenya.memory_layers.entries.update("id", workspace_id: "workspaceId", memory_layer_id: "memoryLayerId") puts(memory_entry_detail) ``` #### Response ```json { "content": "content", "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "key": "key", "description": "description" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "memoryLayer": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "bundleKey": "bundleKey", "externalId": "externalId", "labels": { "foo": "string" } } } } ``` ## Delete a memory entry `memory_layers.entries.delete(id, **kwargs) -> void` **delete** `/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}` Deletes a memory entry from a memory layer ### Parameters - `workspace_id: String` - `memory_layer_id: String` - `id: String` ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") result = cadenya.memory_layers.entries.delete("id", workspace_id: "workspaceId", memory_layer_id: "memoryLayerId") puts(result) ``` ## Domain Types ### Memory Entry - `class MemoryEntry` 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. MemoryEntry is the summary shape, returned by ListMemoryEntries. It does not carry the entry body — callers that need the body must fetch the entry individually via GetMemoryEntry, which returns a MemoryEntryDetail. - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. - `info: MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ### Memory Entry Create Spec - `class MemoryEntryCreateSpec` MemoryEntryCreateSpec is the input shape for CreateMemoryEntry. It accepts either inline content or a reference to a completed Upload; exactly one of the two must be set. - `key: String` See MemoryEntrySpec.key for the full rule set. Same constraints apply here. - `content: String` Inline content, written directly into the entry. - `description: String` - `upload_id: String` ID of a COMPLETE Upload. The server reads the object from storage, copies its bytes into the entry, and marks the upload consumed. ### Memory Entry Detail - `class MemoryEntryDetail` MemoryEntryDetail is the full representation of an entry, including the resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and UpdateMemoryEntry. - `content: String` The resolved body of the entry. For entries created or updated via an upload_id, this is the ingested content, not the original upload handle. May be empty; an entry with only a key and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload). - `metadata: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. - `info: MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) ### Memory Entry Info - `class MemoryEntryInfo` - `created_by: Profile` A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces. - `metadata: AccountResourceMetadata` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: ProfileSpec` Configuration for a profile. - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM` Whether this profile represents a human user, an API key, or a system principal. - `:PROFILE_TYPE_UNSPECIFIED` - `:PROFILE_TYPE_USER` - `:PROFILE_TYPE_API_KEY` - `:PROFILE_TYPE_SYSTEM` - `email: String` Email address of the profile. Required and unique within an account for user profiles. - `name: String` Display name (e.g., "Bobby Tables"). - `memory_layer: ResourceMetadata` Standard metadata for persistent, named resources (e.g., agents, tools, prompts) - `id: String` Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...") - `account_id: String` Account this resource belongs to for multi-tenant isolation (prefixed ULID) - `created_at: Time` Timestamp when this resource was created - `name: String` Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly - `profile_id: String` ID of the actor (user or service account) that created this resource - `workspace_id: String` Workspace this resource belongs to for organizational grouping (prefixed ULID) - `bundle_key: String` Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply. - `external_id: String` External ID for the resource (e.g., a workflow ID from an external system) - `labels: Hash[Symbol, String]` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} ### Memory Entry Spec - `class MemoryEntrySpec` MemoryEntrySpec is the metadata portion of an entry — the fields that identify and describe it, without the body. It appears on both the summary (MemoryEntry) and detail (MemoryEntryDetail) views. - `key: String` The lookup key for this entry within its layer. Must conform to the S3 object key safe-characters spec: ASCII alphanumerics and the special characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat — the key is a single opaque string, not a path. Additional rules enforced by the service: - May not begin or end with / - May not contain consecutive slashes (//) - May not begin with reserved prefixes (cadenya/, system/) - Case-sensitive - Unique within the parent layer For skills entries, this key is also the id the model passes to memory_load_skill when it decides to load the entry's content. - `description: String` One-line "when to use this" hint shown in the frontmatter manifest for skills entries. The model uses this to decide whether to load the body, so it should be written for the model as the audience. Ignored for layer types that do not advertise frontmatter. ### Memory Entry Update Spec - `class MemoryEntryUpdateSpec` MemoryEntryUpdateSpec is the input shape for UpdateMemoryEntry. Fields present in the request's update_mask are applied; unset fields are left alone. The source oneof is optional for updates — omit it to leave the body untouched, or set exactly one branch to replace it. - `content: String` - `description: String` - `key: String` - `upload_id: String`