List memory layers

JavaScript

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);
}

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)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	page, err := client.MemoryLayers.List(context.TODO(), cadenya.MemoryLayerListParams{
		WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", page)
}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "items": [
    {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "description": "<string>",
        "systemManaged": true,
        "expiresAt": "2023-11-07T05:31:56Z",
        "agentId": "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
        "episodicKey": "<string>"
      },
      "info": {
        "entryCount": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        },
        "lastUsedAt": "2023-11-07T05:31:56Z",
        "agent": {
          "id": "<string>",
          "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
          "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
          "name": "<string>",
          "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
          "createdAt": "2023-11-07T05:31:56Z",
          "externalId": "<string>",
          "labels": {},
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

GET

workspaces

{workspaceId}

memory_layers

JavaScript

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);
}

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)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	page, err := client.MemoryLayers.List(context.TODO(), cadenya.MemoryLayerListParams{
		WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", page)
}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "items": [
    {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "description": "<string>",
        "systemManaged": true,
        "expiresAt": "2023-11-07T05:31:56Z",
        "agentId": "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
        "episodicKey": "<string>"
      },
      "info": {
        "entryCount": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        },
        "lastUsedAt": "2023-11-07T05:31:56Z",
        "agent": {
          "id": "<string>",
          "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
          "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
          "name": "<string>",
          "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
          "createdAt": "2023-11-07T05:31:56Z",
          "externalId": "<string>",
          "labels": {},
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

The 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.

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

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

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

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, 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.

// 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.

Create a memory layer

The SKILLS layers you author, and their TTL.

Memory layers

The cascade, episodic memory, and which layer wins a key.

List memory entries

The keyed values inside one layer.

Create an agent

enableEpisodicMemory, which makes the system-managed layers.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Query Parameters

limit

integer<int32>

Maximum number of results to return

cursor

string

Pagination cursor from previous response

prefix

string

Filter expression (query param: prefix)

query

string

Free-form search query

type

enum<string>

Filter by layer type

Available options:

MEMORY_LAYER_TYPE_UNSPECIFIED,

MEMORY_LAYER_TYPE_EPISODIC,

MEMORY_LAYER_TYPE_SKILLS

agentId

string

Filter to episodic layers belonging to this agent.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

episodicKeyPrefix

string

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.

labels

string

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

sortOrder

string

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

includeInfo

boolean

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

Response

items

object[]

Show child attributes

pagination

object

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.

Show child attributes

​Two types

​Filters, and which field each one hits

​Expired episodic layers linger

​Related

Create a memory layer

Memory layers

List memory entries

Create an agent

Authorizations

Path Parameters

Query Parameters

Response

Two types

Filters, and which field each one hits

Expired episodic layers linger

Related