Update a memory layer

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const memoryLayer = await client.memoryLayers.update('memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH', {
  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
)
memory_layer = client.memory_layers.update(
    id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(memory_layer.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"),
	)
	memoryLayer, err := client.MemoryLayers.Update(
		context.TODO(),
		"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
		cadenya.MemoryLayerUpdateParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", memoryLayer.Metadata)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

memory_layer = cadenya.memory_layers.update(
  "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(memory_layer)

curl --request PATCH \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "updateMask": "<string>"
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'updateMask' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.patch("https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"updateMask\": \"<string>\"\n}")
  .asString();

{
  "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"
    }
  }
}

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

PATCH

workspaces

{workspaceId}

memory_layers

{id}

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const memoryLayer = await client.memoryLayers.update('memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH', {
  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
)
memory_layer = client.memory_layers.update(
    id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(memory_layer.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"),
	)
	memoryLayer, err := client.MemoryLayers.Update(
		context.TODO(),
		"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
		cadenya.MemoryLayerUpdateParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", memoryLayer.Metadata)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

memory_layer = cadenya.memory_layers.update(
  "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(memory_layer)

curl --request PATCH \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "updateMask": "<string>"
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'updateMask' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.patch("https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"updateMask\": \"<string>\"\n}")
  .asString();

{
  "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"
    }
  }
}

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

What you can change on a memory layer after it exists: its name, its description, and its TTL. Not its type, and not at all if the system owns it.

await client.memoryLayers.update(layerId, {
  workspaceId,
  metadata: { name: 'Refund policy, v2' },
});

_, err := client.MemoryLayers.Update(ctx, layerID,
	cadenya.MemoryLayerUpdateParams{
		WorkspaceID: cadenya.String(workspaceID),
		Metadata: shared.UpdateResourceMetadataParam{
			Name: "Refund policy, v2",
		},
	})

cadenya.memory_layers.update(
  layer_id,
  workspace_id: workspace_id,
  metadata: {name: "Refund policy, v2"}
)

curl -X PATCH "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/memory_layers/${MEMORY_LAYER_ID}" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"name": "Refund policy, v2"}}'

System-managed layers are read-only

An episodic layer that Cadenya created for an agent has systemManaged: true. Every write to it is a 403, whether you target the name, the type, or its entries:

PATCH /memory_layers/{episodic}                    → 403 permission denied
PATCH /memory_layers/{episodic}  spec.type change  → 403
POST  /memory_layers/{episodic}/entries            → 403

The agent owns that layer through store_memory. You read it in the cascade; you do not edit it.

The type is fixed

You cannot change a layer from SKILLS to EPISODIC or back. The update writes name, description, and TTL, and never touches the type.

A spec.type change returns 200 and does nothing. Send MEMORY_LAYER_TYPE_EPISODIC to a SKILLS layer and the response is a success with the type unchanged. Read the layer back if you need to be sure a change took, rather than trusting the status code.

The TTL follows the merge rules

expiresAt behaves like every other field on a PATCH: the update merges, so a field you leave out is kept, and a zero value needs updateMask to land.

// Set or extend the TTL.
await client.memoryLayers.update(layerId, {
  workspaceId,
  spec: { type: 'MEMORY_LAYER_TYPE_SKILLS', expiresAt: '2027-01-01T00:00:00Z' },
});

// A later update that omits expiresAt keeps it.
await client.memoryLayers.update(layerId, { workspaceId, metadata: { name: 'renamed' } });
// expiresAt still 2027-01-01

To clear the TTL, name it in updateMask and send no value. Omitting it alone leaves it in place, because a merge cannot tell “clear this” from “did not mention it”:

await client.memoryLayers.update(layerId, {
  workspaceId,
  updateMask: 'spec.expiresAt',
  spec: {},
});
// expiresAt: null

Verified live: the masked call clears the timestamp; the unmasked one preserves it. A TTL on a SKILLS layer sets when its entries stop resolving. get_memory and search_memory both filter on expiry, so an expired layer’s entries read as absent even while the layer row remains.

Create a memory layer

Where the type is set, once and for good.

Update a variation

The same updateMask rule for zero values.

List memory layers

systemManaged, which decides whether you can edit at all.

Memory layers

Episodic versus authored, and the cascade.

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"

string

required

Memory layer ID. Accepts canonical memlyr_… form or external_id: form.

Example:

"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"

Body

application/json

metadata

object

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.

Show child attributes

spec

object

Show child attributes

updateMask

string<field-mask>

Response

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.

metadata

object

required

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

Show child attributes

spec

object

required

Show child attributes

info

object

Show child attributes

​System-managed layers are read-only

​The type is fixed

​The TTL follows the merge rules

​Related

Create a memory layer

Update a variation

List memory layers

Memory layers

Authorizations

Path Parameters

Body

Response

System-managed layers are read-only

The type is fixed

The TTL follows the merge rules

Related