Create a new memory entry

POST/v1/memory_layers/{memoryLayerId}/entries

Creates a new entry in a memory layer. Returns the detail view, including the resolved content body.

Path ParametersExpand Collapse

memoryLayerId: string

Body ParametersJSONExpand Collapse

metadata: CreateResourceMetadata { name, externalId, labels }

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.

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

spec: MemoryEntryCreateSpec { key, content, description, 2 more }

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.

key: string

See MemoryEntrySpec.key for the full rule set. Same constraints apply here.

content: optional string

Inline content, written directly into the entry.

description: optional string

title: optional string

uploadId: optional string

ID of a COMPLETE Upload. The server reads the object from storage, copies its bytes into the entry, and marks the upload consumed.

ReturnsExpand Collapse

MemoryEntryDetail = object { content, metadata, spec, info }

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

content: string

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, title, and description is valid (e.g., a stub skill being drafted, or an entry where the frontmatter alone is the payload).

metadata: ResourceMetadata { id, accountId, createdAt, 5 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

spec: MemoryEntrySpec { key, description, title }

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.

key: string

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 also the id the model passes to memory_load_skill when it decides to load the entry's content.

description: optional string

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.

title: optional string

Short human/LLM-readable title shown in the frontmatter manifest for skills entries. Ignored for layer types that do not advertise frontmatter.

info: optional MemoryEntryInfo { createdBy, memoryLayer }

createdBy: optional Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

profileId: string

externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

spec: ProfileSpec { type, email, name }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email: optional string

Email address of the user (required, unique per account)

Display name for the user (e.g., "Bobby Tables")

memoryLayer: optional ResourceMetadata { id, accountId, createdAt, 5 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time

Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}

Create a new memory entry

curl https://api.cadenya.com/v1/memory_layers/$MEMORY_LAYER_ID/entries \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CADENYA_API_KEY" \
    -d '{
          "metadata": {
            "name": "name"
          },
          "spec": {
            "key": "key"
          }
        }'

{
  "content": "content",
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "key": "key",
    "description": "description",
    "title": "title"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_USER",
        "email": "email",
        "name": "name"
      }
    },
    "memoryLayer": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    }
  }
}

Returns Examples

{
  "content": "content",
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "key": "key",
    "description": "description",
    "title": "title"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_USER",
        "email": "email",
        "name": "name"
      }
    },
    "memoryLayer": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    }
  }
}