Create a memory entry

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 memoryEntryDetail = await client.memoryLayers.entries.create(
  'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
  {
    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
    metadata: { name: 'name' },
    spec: { content: 'content', type: 'content' },
  },
);

console.log(memoryEntryDetail.content);

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_entry_detail = client.memory_layers.entries.create(
    memory_layer_id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    metadata={
        "name": "name"
    },
    spec={
        "content": "content",
        "type": "content",
    },
)
print(memory_entry_detail.content)

package main

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

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	memoryEntryDetail, err := client.MemoryLayers.Entries.New(
		context.TODO(),
		"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
		cadenya.MemoryLayerEntryNewParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Metadata: shared.CreateResourceMetadataParam{
				Name: "name",
			},
			Spec: cadenya.MemoryEntryCreateSpecUnionParam{
				OfContent: &cadenya.MemoryEntryCreateSpecContentParam{
					Content: "content",
					Type:    cadenya.MemoryEntryCreateSpecContentTypeContent,
				},
			},
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", memoryEntryDetail.Content)
}

require "cadenya"

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

memory_entry_detail = cadenya.memory_layers.entries.create(
  "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  metadata: {name: "name"},
  spec: {content: "content", type: :content}
)

puts(memory_entry_detail)

cadenya memory-layers:entries create \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --memory-layer-id memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH \
  --metadata '{name: name}' \
  --spec '{content: content, type: content}'

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "<string>",
    "externalId": "<string>",
    "labels": {}
  },
  "spec": {
    "type": "content",
    "content": "<string>",
    "key": "<string>",
    "description": "<string>"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'name' => '<string>',
        'externalId' => '<string>',
        'labels' => [
                
        ]
    ],
    'spec' => [
        'type' => 'content',
        'content' => '<string>',
        'key' => '<string>',
        'description' => '<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.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"labels\": {}\n  },\n  \"spec\": {\n    \"type\": \"content\",\n    \"content\": \"<string>\",\n    \"key\": \"<string>\",\n    \"description\": \"<string>\"\n  }\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": {
    "key": "<string>",
    "description": "<string>"
  },
  "content": "<string>",
  "info": {
    "memoryLayer": {
      "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"
    },
    "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>"
      }
    }
  }
}

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

POST

workspaces

{workspaceId}

memory_layers

{memoryLayerId}

entries

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 memoryEntryDetail = await client.memoryLayers.entries.create(
  'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
  {
    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
    metadata: { name: 'name' },
    spec: { content: 'content', type: 'content' },
  },
);

console.log(memoryEntryDetail.content);

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_entry_detail = client.memory_layers.entries.create(
    memory_layer_id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    metadata={
        "name": "name"
    },
    spec={
        "content": "content",
        "type": "content",
    },
)
print(memory_entry_detail.content)

package main

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

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	memoryEntryDetail, err := client.MemoryLayers.Entries.New(
		context.TODO(),
		"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
		cadenya.MemoryLayerEntryNewParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Metadata: shared.CreateResourceMetadataParam{
				Name: "name",
			},
			Spec: cadenya.MemoryEntryCreateSpecUnionParam{
				OfContent: &cadenya.MemoryEntryCreateSpecContentParam{
					Content: "content",
					Type:    cadenya.MemoryEntryCreateSpecContentTypeContent,
				},
			},
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", memoryEntryDetail.Content)
}

require "cadenya"

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

memory_entry_detail = cadenya.memory_layers.entries.create(
  "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  metadata: {name: "name"},
  spec: {content: "content", type: :content}
)

puts(memory_entry_detail)

cadenya memory-layers:entries create \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --memory-layer-id memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH \
  --metadata '{name: name}' \
  --spec '{content: content, type: content}'

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "name": "<string>",
    "externalId": "<string>",
    "labels": {}
  },
  "spec": {
    "type": "content",
    "content": "<string>",
    "key": "<string>",
    "description": "<string>"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'name' => '<string>',
        'externalId' => '<string>',
        'labels' => [
                
        ]
    ],
    'spec' => [
        'type' => 'content',
        'content' => '<string>',
        'key' => '<string>',
        'description' => '<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.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"name\": \"<string>\",\n    \"externalId\": \"<string>\",\n    \"labels\": {}\n  },\n  \"spec\": {\n    \"type\": \"content\",\n    \"content\": \"<string>\",\n    \"key\": \"<string>\",\n    \"description\": \"<string>\"\n  }\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": {
    "key": "<string>",
    "description": "<string>"
  },
  "content": "<string>",
  "info": {
    "memoryLayer": {
      "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"
    },
    "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>"
      }
    }
  }
}

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

An entry is one keyed value in a memory layer. Nothing about it enters an agent’s context up front. The agent calls get_memory with the key and gets the content back.

await client.memoryLayers.entries.create(layerId, {
  workspaceId,
  metadata: { name: 'US refunds' },
  spec: {
    type: 'content',
    key: 'policies/us/refunds',
    description: 'US refund window',
    content: 'Refunds within 30 days. No receipt required under $50.',
  },
});

_, err := client.MemoryLayers.Entries.New(ctx, layerID,
	cadenya.MemoryLayerEntryNewParams{
		WorkspaceID: cadenya.String(workspaceID),
		Metadata: shared.CreateResourceMetadataParam{
			Name: "US refunds",
		},
		Spec: cadenya.MemoryEntryCreateSpecUnionParam{
			OfContent: &cadenya.MemoryEntryCreateSpecContentParam{
				Type:        cadenya.MemoryEntryCreateSpecContentTypeContent,
				Key:         cadenya.String("policies/us/refunds"),
				Description: cadenya.String("US refund window"),
				Content:     "Refunds within 30 days. No receipt required under $50.",
			},
		},
	})

cadenya.memory_layers.entries.create(
  layer_id,
  workspace_id: workspace_id,
  metadata: {name: "US refunds"},
  spec: {
    type: :content,
    key: "policies/us/refunds",
    description: "US refund window",
    content: "Refunds within 30 days. No receipt required under $50."
  }
)

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/memory_layers/${MEMORY_LAYER_ID}/entries" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
        "metadata": { "name": "US refunds" },
        "spec": {
          "type": "content",
          "key": "policies/us/refunds",
          "description": "US refund window",
          "content": "Refunds within 30 days. No receipt required under $50."
        }
      }'

The key is the interface

key is the only required field on the spec, and it works like a file path. It is what the agent passes to get_memory, and what the memory cascade resolves against: the first layer holding the key wins. Keys are unique within a layer. A second entry with the same key is a 409.

POST .../entries  { type: "content", key: "policies/us/refunds", content: "..." }   -> 200
POST .../entries  { type: "content", key: "policies/us/refunds", content: "..." }   -> 409

Across layers, a repeated key is the whole point. Put policies/us/refunds in a general layer and again in a customer-specific one, and the cascade picks the specific one.

Key syntax is not validated. A leading slash, a double slash, and a cadenya/ prefix are all accepted. Pick a convention and hold yourself to it. The API does not.

Content or upload, never neither

An entry needs a body, and spec.type names where it comes from: content for inline text, or uploadId to point at an uploaded file for anything large. The matching field rides along with the type.

POST .../entries  { key: "policies/empty" }                              -> 400
POST .../entries  { type: "content", key: "policies/x", content: "..." } -> 200

description is optional and independent of both. It tells the agent what the entry holds before it decides to read it, which is what makes search_memory worth calling.

`content` comes back at the top level

Read an entry and content sits beside spec, not inside it. spec holds key and description; the body is its own field.

const entry = await client.memoryLayers.entries.retrieve(layerId, entryId, { workspaceId });

console.log(Object.keys(entry));  // [ 'metadata', 'spec', 'info', 'content' ]
console.log(entry.content);       // 'Updated: 45 days.'
console.log(entry.spec);          // { key: 'policies/us/refunds', description: 'US refund window' }

The list omits it, the same way tool calls omit their results: paging a big layer stays cheap, and you pay for a body only when you ask for one. An update replaces the content, and the next get_memory sees the new value:

await client.memoryLayers.entries.update(layerId, entryId, {
  workspaceId,
  spec: { key: 'policies/us/refunds', content: 'Updated: 45 days.' },
});

Ask an agent assigned to that layer to read the key and it answers Updated: 45 days., the same string a retrieve returns.

The layer types you can create

spec.type is required on the parent layer, and MEMORY_LAYER_TYPE_UNSPECIFIED is rejected.

POST /memory_layers  { metadata: { name: 'x' }, spec: { type: 'MEMORY_LAYER_TYPE_UNSPECIFIED' } }  -> 400
POST /memory_layers  { metadata: { name: 'x' }, spec: {} }                                         -> 400
POST /memory_layers  { metadata: { name: 'x' }, spec: { type: 'MEMORY_LAYER_TYPE_SKILLS' } }       -> 200

metadata.name is required too, so a body carrying only a spec is a 400 whatever the type says. That leaves SKILLS for knowledge you author, and EPISODIC for the layer an agent writes to itself with store_memory. Cadenya creates and manages the episodic layer when an agent has enableEpisodicMemory set, so you rarely create one by hand.

Reaching the agent

An entry is inert until its layer is assigned to a variation. position orders the cascade.

await client.agents.variations.addMemoryLayer(agentId, variationId, {
  workspaceId,
  memoryLayerId: layerId,
  position: 0,
});

Publish the agent, and the next objective’s agent carries get_memory and search_memory in its tool list. The read arrives as a toolCalled event with arguments: { "memoryKey": "policies/us/refunds" }, not as a memoryRead event.

Create a memory layer

The container, its type, and its TTL.

Memory layers

The cascade, and which layer wins a key.

Create an upload

Where uploadId comes from, for entries too big to inline.

Create a variation

Assigning layers, and the position that orders them.

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"

memoryLayerId

string

required

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

Example:

"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"

Body

application/json

metadata

object

required

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.

Show child attributes

spec

object

required

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.

Option 1
Option 2

Show child attributes

Response

MemoryEntryDetail is the full representation of an entry, including the resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and UpdateMemoryEntry.

metadata

object

required

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

Show child attributes

spec

object

required

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.

Show child attributes

content

string

required

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

info

object

Show child attributes

​The key is the interface

​Content or upload, never neither

​content comes back at the top level

​The layer types you can create

​Reaching the agent

​Related

Create a memory layer

Memory layers

Create an upload

Create a variation

Authorizations

Path Parameters

Body

Response

The key is the interface

Content or upload, never neither

`content` comes back at the top level

The layer types you can create

Reaching the agent

Related