> ## 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.
# Create a memory entry
> One keyed value inside a memory layer. The agent reads it by key, on demand, with get_memory.
An entry is one keyed value in a [memory layer](/docs/api-reference/memoryservice/create-a-new-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.
```typescript TypeScript theme={null}
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.',
},
});
```
```go Go theme={null}
_, 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.",
},
},
})
```
```ruby Ruby theme={null}
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."
}
)
```
```bash cURL theme={null}
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](/docs/guides/memory-layers) 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](/docs/api-reference/uploadservice/create-an-upload) 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.
```typescript theme={null}
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](/docs/api-reference/objectiveservice/list-objective-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:
```typescript theme={null}
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.
```typescript theme={null}
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.
## Related
The container, its type, and its TTL.
The cascade, and which layer wins a key.
Where `uploadId` comes from, for entries too big to inline.
Assigning layers, and the `position` that orders them.
## OpenAPI
````yaml post /v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries
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/{memoryLayerId}/entries:
post:
tags:
- MemoryService
- Memory Entries
summary: Create a new memory entry
description: >-
Creates a new entry in a memory layer. Returns the detail view,
including the resolved content body.
operationId: MemoryService_CreateMemoryEntry
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: memoryLayerId
in: path
description: >-
Memory layer ID. Accepts canonical memlyr_… form or
external_id: form.
required: true
schema:
example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMemoryEntryRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MemoryEntryDetail'
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
});
const memoryEntryDetail = await client.memoryLayers.entries.create(
'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
{
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
metadata: { name: 'name' },
spec: { content: 'content', type: 'content' },
},
);
console.log(memoryEntryDetail.content);
- 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
)
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)
- 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\t\"go.cadenya.com/cadenya-go/shared\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmemoryEntryDetail, err := client.MemoryLayers.Entries.New(\n\t\tcontext.TODO(),\n\t\t\"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH\",\n\t\tcadenya.MemoryLayerEntryNewParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t\tMetadata: shared.CreateResourceMetadataParam{\n\t\t\t\tName: \"name\",\n\t\t\t},\n\t\t\tSpec: cadenya.MemoryEntryCreateSpecUnionParam{\n\t\t\t\tOfContent: &cadenya.MemoryEntryCreateSpecContentParam{\n\t\t\t\t\tContent: \"content\",\n\t\t\t\t\tType: cadenya.MemoryEntryCreateSpecContentTypeContent,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", memoryEntryDetail.Content)\n}\n"
- lang: Ruby
source: |-
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)
- lang: CLI
source: |-
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}'
components:
schemas:
CreateMemoryEntryRequest:
required:
- metadata
- spec
type: object
properties:
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
memoryLayerId:
readOnly: true
example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH
type: string
description: >-
Memory layer ID. Accepts canonical memlyr_… form or
external_id: form.
metadata:
$ref: '#/components/schemas/CreateResourceMetadata'
spec:
$ref: '#/components/schemas/MemoryEntryCreateSpec'
MemoryEntryDetail:
required:
- metadata
- spec
- content
type: object
properties:
metadata:
$ref: '#/components/schemas/ResourceMetadata'
spec:
$ref: '#/components/schemas/MemoryEntrySpec'
info:
$ref: '#/components/schemas/MemoryEntryInfo'
content:
type: string
description: >-
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).
description: |-
MemoryEntryDetail is the full representation of an entry, including the
resolved content body. Returned by GetMemoryEntry, CreateMemoryEntry, and
UpdateMemoryEntry.
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).
CreateResourceMetadata:
required:
- name
type: object
properties:
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
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"}
description: |-
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.
MemoryEntryCreateSpec:
oneOf:
- $ref: '#/components/schemas/MemoryEntryCreateSpec_Content'
- $ref: '#/components/schemas/MemoryEntryCreateSpec_UploadId'
discriminator:
propertyName: type
mapping:
content:
$ref: '#/components/schemas/MemoryEntryCreateSpec_Content'
uploadId:
$ref: '#/components/schemas/MemoryEntryCreateSpec_UploadId'
description: >-
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.
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)
MemoryEntrySpec:
required:
- key
type: object
properties:
key:
type: string
description: >-
The lookup key for this entry within its layer. Must conform to the
S3
object key safe-characters spec: ASCII alphanumerics and the special
characters !, -, _, ., *, ', (, ), and /. Forward slashes may be used to
suggest hierarchy (e.g., "skills/postmortem/write"), but lookups are flat
— the key is a single opaque string, not a path.
Additional rules enforced by the service:
- May not begin or end with /
- May not contain consecutive slashes (//)
- May not begin with reserved prefixes (cadenya/, system/)
- Case-sensitive
- Unique within the parent layer
For skills entries, this key is what the model passes to get_memory to
load the entry's content.
description:
type: string
description: >-
One-line "when to use this" hint shown in the frontmatter manifest
for
skills entries. The model uses this to decide whether to load the body,
so it should be written for the model as the audience. Ignored for layer
types that do not advertise frontmatter.
description: |-
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.
MemoryEntryInfo:
type: object
properties:
memoryLayer:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: The layer this entry belongs to.
createdBy:
$ref: '#/components/schemas/Profile'
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.
MemoryEntryCreateSpec_Content:
type: object
required:
- type
- content
properties:
type:
type: string
enum:
- content
content:
type: string
description: Inline content, written directly into the entry.
key:
type: string
description: >-
See MemoryEntrySpec.key for the full rule set. Same constraints
apply
here.
description:
type: string
MemoryEntryCreateSpec_UploadId:
type: object
required:
- type
- uploadId
properties:
type:
type: string
enum:
- uploadId
uploadId:
example: upload_01HXKD2E5NQM3T9AYWCFZ05DNK
type: string
description: |-
ID of a COMPLETE Upload. The server reads the object from storage,
copies its bytes into the entry, and marks the upload consumed.
key:
type: string
description: >-
See MemoryEntrySpec.key for the full rule set. Same constraints
apply
here.
description:
type: string
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
````