Skip to content
cadenya
Get started
API Reference
Memory Layers

List memory layers

client.MemoryLayers.List(ctx, query) (*CursorPagination[MemoryLayer], error)
GET/v1/memory_layers

Lists all memory layers in the workspace

ParametersExpand Collapse
query MemoryLayerListParams
Cursor param.Field[string]optional

Pagination cursor from previous response

IncludeInfo param.Field[bool]optional

When set to true you may use more of your alloted API rate-limit

Limit param.Field[int64]optional

Maximum number of results to return

formatint32
Prefix param.Field[string]optional

Filter expression (query param: prefix)

SortOrder param.Field[string]optional

Sort order for results (asc or desc by creation time)

Type param.Field[MemoryLayerListParamsType]optional

Filter by layer type

formatenum
const MemoryLayerListParamsTypeMemoryLayerTypeUnspecified MemoryLayerListParamsType = "MEMORY_LAYER_TYPE_UNSPECIFIED"
const MemoryLayerListParamsTypeMemoryLayerTypeEpisodic MemoryLayerListParamsType = "MEMORY_LAYER_TYPE_EPISODIC"
const MemoryLayerListParamsTypeMemoryLayerTypeSkills MemoryLayerListParamsType = "MEMORY_LAYER_TYPE_SKILLS"
ReturnsExpand Collapse
type MemoryLayer struct{…}

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.

Memory stacks are LIFO: when an objective resolves a key, layers are walked from the top of the stack downward, and the first matching entry wins.

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

ID string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time
Name string

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

Type MemoryLayerSpecType
formatenum
One of the following:
const MemoryLayerSpecTypeMemoryLayerTypeUnspecified MemoryLayerSpecType = "MEMORY_LAYER_TYPE_UNSPECIFIED"
const MemoryLayerSpecTypeMemoryLayerTypeEpisodic MemoryLayerSpecType = "MEMORY_LAYER_TYPE_EPISODIC"
const MemoryLayerSpecTypeMemoryLayerTypeSkills MemoryLayerSpecType = "MEMORY_LAYER_TYPE_SKILLS"
Description stringoptional

Human-readable description of the layer's purpose. Encouraged for user-created layers; system-managed layers may have a generated description.

ExpiresAt Timeoptional

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.

formatdate-time
SystemManaged booloptional

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 MemoryLayerInfooptional
CreatedBy Profileoptional

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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...")

AccountID 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

ProfileID string
ExternalID stringoptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]optional

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

ProfileSpec contains the profile-specific fields

Type ProfileSpecType

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringoptional

Email address of the user (required, unique per account)

Name stringoptional

Display name for the user (e.g., "Bobby Tables")

EntryCount int64optional

Number of entries currently in this layer.

formatint32
LastUsedAt Timeoptional

Timestamp of the most recent objective that resolved against this layer. Useful for surfacing unused layers in the dashboard.

formatdate-time

List memory layers

package main

import (
  "context"
  "fmt"

  "github.com/cadenya/cadenya-go"
  "github.com/cadenya/cadenya-go/option"
)

func main() {
  client := cadenya.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.MemoryLayers.List(context.TODO(), cadenya.MemoryLayerListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "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_USER",
            "email": "email",
            "name": "name"
          }
        },
        "entryCount": 0,
        "lastUsedAt": "2019-12-27T18:11:19.117Z"
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
Returns Examples
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "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_USER",
            "email": "email",
            "name": "name"
          }
        },
        "entryCount": 0,
        "lastUsedAt": "2019-12-27T18:11:19.117Z"
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}