> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List memory layers
> Every memory layer in a workspace, the ones you author and the ones agents write for themselves.
The [memory layers](/docs/guides/memory-layers) a workspace holds: the `SKILLS` layers you author, and the `EPISODIC` layers Cadenya creates when an agent writes to itself with `store_memory`.
```typescript TypeScript theme={null}
const layers = await client.memoryLayers.list({ workspaceId });
for await (const layer of layers) {
console.log(layer.metadata.name, layer.spec.type, layer.spec.systemManaged);
}
// Skills 3 MEMORY_LAYER_TYPE_SKILLS false
// Episodic: customer-42 MEMORY_LAYER_TYPE_EPISODIC true
```
```go Go theme={null}
layers := client.MemoryLayers.ListAutoPaging(ctx,
cadenya.MemoryLayerListParams{
WorkspaceID: cadenya.String(workspaceID),
})
for layers.Next() {
layer := layers.Current()
fmt.Println(layer.Metadata.Name, layer.Spec.Type, layer.Spec.SystemManaged)
}
// Skills 3 MEMORY_LAYER_TYPE_SKILLS false
// Episodic: customer-42 MEMORY_LAYER_TYPE_EPISODIC true
```
```ruby Ruby theme={null}
layers = cadenya.memory_layers.list(workspace_id: workspace_id)
layers.auto_paging_each do |layer|
puts "#{layer.metadata.name} #{layer.spec.type} #{layer.spec.system_managed}"
end
# Skills 3 MEMORY_LAYER_TYPE_SKILLS false
# Episodic: customer-42 MEMORY_LAYER_TYPE_EPISODIC true
```
```bash cURL theme={null}
curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/memory_layers" \
-H "Authorization: Bearer ${CADENYA_API_KEY}"
```
`systemManaged` is the tell. A `true` layer is episodic memory Cadenya manages for an agent; you rarely create or edit one by hand. A `false` layer is one you authored.
## Two types
| Type | Who writes it | How |
| ---------------------------- | ------------- | ------------------------------------------------------------------------------------- |
| `MEMORY_LAYER_TYPE_SKILLS` | You | [Create a layer](/docs/api-reference/memoryservice/create-a-new-memory-layer), add entries |
| `MEMORY_LAYER_TYPE_EPISODIC` | The agent | `store_memory`, when the agent has episodic memory enabled |
`MEMORY_LAYER_TYPE_UNSPECIFIED` is rejected on create, so those two are all you see.
## Filters, and which field each one hits
Five ways to narrow the list, and they target different fields. This matters, because the two prefix-style filters look alike and are not.
| Filter | Matches |
| ------------------- | ------------------------------------------------------ |
| `type` | The layer type, validated. A bad value is a `400`. |
| `prefix` | The start of the layer **name** |
| `episodicKeyPrefix` | The start of the **episodic key**, for episodic layers |
| `agentId` | The agent an episodic layer belongs to |
| `query` | Free-form search over the name |
The distinction, measured:
```
?prefix=Episodic → the layer NAMED "Episodic: customer-42"
?prefix=customer → nothing (no layer name starts with "customer")
?episodicKeyPrefix=customer → the layer whose episodic KEY is "customer-42"
```
So `prefix` searches names and `episodicKeyPrefix` searches episodic keys. Reach for `episodicKeyPrefix` when you want every episodic session under a namespace, the way a `customer/` prefix collects `customer/42` and `customer/43`.
```typescript theme={null}
// Every episodic session for one customer prefix.
const sessions = await client.memoryLayers.list({
workspaceId,
episodicKeyPrefix: 'customer/',
});
```
`type` combines with the rest. `type: 'MEMORY_LAYER_TYPE_SKILLS'` returns only the layers you author, which is usually what a configuration UI wants.
## Expired episodic layers linger
An episodic layer carries a TTL that slides forward with each objective sharing its key. When the TTL passes, the **entries** stop resolving: `get_memory` and `search_memory` filter on entry expiry, so an agent reads nothing from an expired session. The **layer row** itself, though, stays in this list rather than being cleaned up. An `EPISODIC` row with an `expiresAt` in the past is expired memory the agent can no longer read, not a live layer.
## Related
The `SKILLS` layers you author, and their TTL.
The cascade, episodic memory, and which layer wins a key.
The keyed values inside one layer.
`enableEpisodicMemory`, which makes the system-managed layers.
## OpenAPI
````yaml get /v1/workspaces/{workspaceId}/memory_layers
openapi: 3.1.0
info:
title: Cadenya API
description: API for the Cadenya Agent Runtime platform.
version: '1.0'
servers:
- url: https://api.cadenya.com
description: Production server
security:
- bearerAuth: []
tags:
- name: AIProviderKeyService
- name: APIKeyService
description: |-
Issue, rotate, disable, and revoke a workspace's API keys. Every key
belongs to exactly one workspace; the system-managed global account key is
managed via GlobalAPIKeyService instead.
- name: AccountService
description: >-
Manage the authenticated account. Accounts are the top-level
organizational
unit and contain one or more workspaces.
- name: AgentScheduleService
description: >-
Manage recurring schedules attached to agents. Schedules trigger
objectives
on a cadence defined by AgentScheduleSpec.Schedule.
- name: AgentService
description: >-
Manage AI agents within a workspace. Agents define AI behavior and tool
access.
- name: AgentVariationService
description: >-
Manage variations of an agent and their tool, sub-agent, and memory layer
assignments.
- name: GlobalAPIKeyService
description: |-
Manage the account's system-provisioned global API key. The global key is
the only key that spans every workspace; it is created by the system and
cannot be deleted, so the surface is retrieve, rotate, and the
disable/enable kill switch.
- name: MemoryService
description: >-
Manage memory layers and their entries. Layers are named containers that
can
be composed into an objective's memory cascade; entries are the keyed values
within a layer. System-managed layers (e.g., episodic layers created by the
runtime) cannot be mutated through this API.
- name: ModelService
description: |-
Manage LLM models available to a workspace. Models represent provider and
family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
with the supported models and you can enable or disable each one.
- name: ObjectiveEventStreamsService
- name: ObjectiveService
- name: ProfilesService
description: |-
Operations on profiles, the account-level principals (users, API keys,
system) that authenticate against the API.
- name: SearchService
- name: TenantService
description: >-
Read and erase tenants and the subjects under them. Tenants and subjects
are
created by assertion — on objective creation or widget session mint — never
directly, so this service has no create or update: it exists to enumerate what
assertions have produced, and to destroy it on request.
- name: ToolService
description: >-
Manage tool sets and the tools they contain. Tool sets group related
tools,
and tools define specific capabilities available to agents.
When a tool set is managed, only API key actors can modify its tools; human
(profile) actors cannot.
- name: UploadService
description: |-
Issue short-lived presigned URLs for direct client-to-object-storage
uploads. Created uploads can be referenced by id when creating or updating
resources that accept binary content (e.g., MemoryEntry).
- name: WidgetService
description: |-
Manage embeddable chat widgets. A widget binds an agent to a globally
unique hostname with a per-widget origin allowlist; browsers reach it with
session tokens minted via WidgetSessionService.
- name: WidgetSessionService
description: >-
Mint and manage widget sessions. Session creation is server-to-server
only:
the customer's backend authenticates its visitor, asserts tenant/subject
context, attaches any per-visitor secrets, and receives a short-lived
bearer token the browser uses against the widget host.
- name: WorkspaceAdminService
description: >-
Administer workspaces across the account: create and archive workspaces
and
manage their membership. These operations are account-scoped and require the
admin role (a token whose profile holds the WorkOS admin role); they live
under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
tree so an admin can manage any workspace in the account, including ones they
are not themselves a member of.
- name: WorkspaceSecretService
- name: WorkspaceService
description: |-
Manage workspaces within an account. Workspaces provide organizational
grouping and isolation for resources such as agents, tools, and API keys.
This is the workspace-scoped, end-user surface. Administrative operations
(create / archive workspaces, manage members) live in WorkspaceAdminService
under /v1/account/workspaces and require the admin role.
paths:
/v1/workspaces/{workspaceId}/memory_layers:
get:
tags:
- MemoryService
- Memory Layers
summary: List memory layers
description: Lists all memory layers in the workspace
operationId: MemoryService_ListMemoryLayers
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: limit
in: query
description: Maximum number of results to return
schema:
type: integer
format: int32
- name: cursor
in: query
description: Pagination cursor from previous response
schema:
type: string
- name: prefix
in: query
description: 'Filter expression (query param: prefix)'
schema:
type: string
- name: query
in: query
description: Free-form search query
schema:
type: string
- name: type
in: query
description: Filter by layer type
schema:
enum:
- MEMORY_LAYER_TYPE_UNSPECIFIED
- MEMORY_LAYER_TYPE_EPISODIC
- MEMORY_LAYER_TYPE_SKILLS
type: string
format: enum
- name: agentId
in: query
description: Filter to episodic layers belonging to this agent.
schema:
example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
type: string
- name: episodicKeyPrefix
in: query
description: |-
Filter to episodic layers whose episodic key starts with this prefix
(e.g. "customer/" matches "customer/42" and "customer/43"). Useful for
namespaced keys, similar to a redis key scan.
schema:
type: string
- name: labels
in: query
description: |-
Filters by metadata labels. Comma-separated key=value pairs,
e.g. "env=prod,team=ai". A resource matches only if every pair
matches exactly (AND semantics).
schema:
type: string
- name: sortOrder
in: query
description: Sort order for results (asc or desc by creation time)
schema:
type: string
- name: includeInfo
in: query
description: When set to true you may use more of your alloted API rate-limit
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListMemoryLayersResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
x-codeSamples:
- lang: JavaScript
source: |-
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
// Automatically fetches more pages as needed.
for await (const memoryLayer of client.memoryLayers.list({
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
})) {
console.log(memoryLayer.metadata);
}
- lang: Python
source: |-
import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
page = client.memory_layers.list(
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
page = page.items[0]
print(page.metadata)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.MemoryLayers.List(context.TODO(), cadenya.MemoryLayerListParams{\n\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
- lang: Ruby
source: >-
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
page = cadenya.memory_layers.list(workspace_id:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q")
puts(page)
- lang: CLI
source: |-
cadenya memory-layers list \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q
components:
schemas:
ListMemoryLayersResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/MemoryLayer'
pagination:
$ref: '#/components/schemas/Page'
Status:
type: object
properties:
code:
type: integer
description: >-
The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].
format: int32
message:
type: string
description: >-
A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or
localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/GoogleProtobufAny'
description: >-
A list of messages that carry the error details. There is a common
set of message types for APIs to use.
description: >-
The `Status` type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It
is used by [gRPC](https://github.com/grpc). Each `Status` message
contains three pieces of data: error code, error message, and error
details. You can find out more about this error model and how to work
with it in the [API Design
Guide](https://cloud.google.com/apis/design/errors).
MemoryLayer:
required:
- metadata
- spec
type: object
properties:
metadata:
$ref: '#/components/schemas/ResourceMetadata'
spec:
$ref: '#/components/schemas/MemoryLayerSpec'
info:
$ref: '#/components/schemas/MemoryLayerInfo'
description: >-
MemoryLayer is a named container of memory entries that can be composed
into
an objective's memory cascade. Layers are workspace-scoped resources. The layer
type controls how its entries participate in the agent loop — see
MemoryLayerType for details.
See "Memory cascade composition" above for how layers compose at lookup time.
Page:
type: object
properties:
nextCursor:
type: string
description: >-
Page carries cursor-based pagination state. There is no total: the
cursor
walks the result set without ever counting it, and a count would cost a second
query on every list.
GoogleProtobufAny:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: >-
Contains an arbitrary serialized message along with a @type that
describes the type of the serialized message.
ResourceMetadata:
required:
- id
- accountId
- workspaceId
- name
- profileId
- createdAt
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the resource (prefixed ULID, e.g.,
"agent_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this resource belongs to for multi-tenant isolation
(prefixed ULID)
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
description: >-
Workspace this resource belongs to for organizational grouping
(prefixed ULID)
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
Required for resources that users interact with directly
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
description: ID of the actor (user or service account) that created this resource
createdAt:
readOnly: true
type: string
description: Timestamp when this resource was created
format: date-time
updatedAt:
readOnly: true
type: string
description: Timestamp when this resource was last updated
format: date-time
description: >-
Standard metadata for persistent, named resources (e.g., agents, tools,
prompts)
MemoryLayerSpec:
required:
- type
type: object
properties:
type:
enum:
- MEMORY_LAYER_TYPE_UNSPECIFIED
- MEMORY_LAYER_TYPE_EPISODIC
- MEMORY_LAYER_TYPE_SKILLS
type: string
format: enum
description:
type: string
description: |-
Human-readable description of the layer's purpose. Encouraged for
user-created layers; system-managed layers may have a generated description.
systemManaged:
readOnly: true
type: boolean
description: >-
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 cascades via the API and cannot be
mutated by clients — their lifecycle is controlled entirely by the runtime.
expiresAt:
readOnly: true
type: string
description: >-
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.
format: date-time
agentId:
readOnly: true
example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
type: string
description: >-
Server-set on episodic layers: the agent this layer belongs to.
Unset for
non-episodic layers.
episodicKey:
readOnly: true
type: string
description: >-
Server-set on episodic layers: the caller-supplied episodic key the
layer
was created for. Unset for non-episodic layers.
MemoryLayerInfo:
type: object
properties:
entryCount:
readOnly: true
type: integer
description: Number of entries currently in this layer.
format: int32
createdBy:
$ref: '#/components/schemas/Profile'
lastUsedAt:
readOnly: true
type: string
description: >-
Timestamp of the most recent objective that resolved against this
layer.
Useful for surfacing unused layers in the dashboard.
format: date-time
agent:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: |-
For episodic layers, the metadata of the agent the layer belongs to
(resolved from MemoryLayerSpec.agent_id). Unset for non-episodic layers.
Profile:
required:
- metadata
- spec
type: object
properties:
metadata:
$ref: '#/components/schemas/AccountResourceMetadata'
spec:
$ref: '#/components/schemas/ProfileSpec'
description: |-
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.
AccountResourceMetadata:
required:
- id
- accountId
- name
- profileId
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the resource (prefixed ULID, e.g.,
"apikey_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this resource belongs to for multi-tenant isolation
(prefixed ULID)
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
Required for resources that users interact with directly
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
createdAt:
readOnly: true
type: string
format: date-time
description: >-
AccountResourceMetadata is used to represent a resource that is
associated to an account but not to a workspace.
ProfileSpec:
required:
- type
type: object
properties:
email:
type: string
description: >-
Email address of the profile. Required and unique within an account
for
user profiles.
name:
type: string
description: Display name (e.g., "Bobby Tables").
type:
enum:
- PROFILE_TYPE_UNSPECIFIED
- PROFILE_TYPE_USER
- PROFILE_TYPE_API_KEY
- PROFILE_TYPE_SYSTEM
type: string
description: >-
Whether this profile represents a human user, an API key, or a
system
principal.
format: enum
description: Configuration for a profile.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````