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

# Update a memory entry

> Edit an entry's content, description, or its key. The key is mutable.

Change a [memory entry](/docs/api-reference/memoryservice/create-a-new-memory-entry) in place: rewrite its `content`, refine its `description`, or re-key it.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await client.memoryLayers.entries.update(memoryLayerId, entryId, {
    workspaceId,
    spec: { content: 'Refunds within 60 days now, up from 30.' },
  });
  ```

  ```go Go theme={null}
  _, err := client.MemoryLayers.Entries.Update(ctx, memoryLayerID, entryID,
  	cadenya.MemoryLayerEntryUpdateParams{
  		WorkspaceID: cadenya.String(workspaceID),
  		Spec: cadenya.MemoryEntryUpdateSpecParam{
  			Content: cadenya.String("Refunds within 60 days now, up from 30."),
  		},
  	})
  ```

  ```ruby Ruby theme={null}
  cadenya.memory_layers.entries.update(
    memory_layer_id,
    entry_id,
    workspace_id: workspace_id,
    spec: {content: "Refunds within 60 days now, up from 30."}
  )
  ```

  ```bash cURL theme={null}
  curl -X PATCH "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/memory_layers/${MEMORY_LAYER_ID}/entries/${ENTRY_ID}" \
    -H "Authorization: Bearer ${CADENYA_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"spec": {"content": "Refunds within 60 days now, up from 30."}}'
  ```
</CodeGroup>

## The key is mutable

The `key` is not a fixed identity, it is a field you can change like any other:

```typescript theme={null}
await client.memoryLayers.entries.update(memoryLayerId, entryId, {
  workspaceId,
  spec: { key: 'policy/refunds-2026' },
});
```

Re-keying matters because the `key` is how an agent loads the entry through `get_memory` and how the [cascade](/docs/guides/memory-layers) resolves it. Change the key and any prompt or code that referenced the old one stops finding it. The entry keeps its `mementry_...` id across a re-key; only the lookup handle moves.

## It merges

Send only what you are changing, and the rest survives. A `content`-only update leaves `key` and `description` intact, verified: patch only `content` and the entry keeps its key and description.

One consequence of the merge: setting an optional field like `description` to an empty string reads as "no change", not "clear it", so the old value stays. Send the value you want rather than relying on an empty string to blank a field.

## Related

<CardGroup cols={2}>
  <Card title="Create a memory entry" icon="key" href="/docs/api-reference/memoryservice/create-a-new-memory-entry">
    The `key`, `description`, and `content` fields you edit here.
  </Card>

  <Card title="Get a memory entry" icon="file-lines" href="/docs/api-reference/memoryservice/get-a-memory-entry-by-id">
    Read back the `content` after an edit.
  </Card>

  <Card title="Memory layers" icon="brain" href="/docs/guides/memory-layers">
    How the agent resolves a key through the cascade.
  </Card>
</CardGroup>


## OpenAPI

````yaml patch /v1/workspaces/{workspaceId}/memory_layers/{memoryLayerId}/entries/{id}
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/{id}:
    patch:
      tags:
        - MemoryService
        - Memory Entries
      summary: Update a memory entry
      description: >-
        Updates a memory entry in a memory layer. Returns the detail view,
        including the resolved content body.
      operationId: MemoryService_UpdateMemoryEntry
      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:<value> form.
          required: true
          schema:
            example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: mementry_01HXKD2E5NQM3T9AYWCF5E52Z0
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemoryEntryRequest'
        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.update(
              'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
              'mementry_01HXKD2E5NQM3T9AYWCF5E52Z0',
              { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
            );

            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.update(
                memory_layer_id="memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
                id="mementry_01HXKD2E5NQM3T9AYWCF5E52Z0",
                workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
            )
            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)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmemoryEntryDetail, err := client.MemoryLayers.Entries.Update(\n\t\tcontext.TODO(),\n\t\t\"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH\",\n\t\t\"mementry_01HXKD2E5NQM3T9AYWCF5E52Z0\",\n\t\tcadenya.MemoryLayerEntryUpdateParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\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.update(
              "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
              "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0",
              workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
            )

            puts(memory_entry_detail)
        - lang: CLI
          source: |-
            cadenya memory-layers:entries update \
              --api-key 'My API Key' \
              --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
              --memory-layer-id memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH \
              --id mementry_01HXKD2E5NQM3T9AYWCF5E52Z0
components:
  schemas:
    UpdateMemoryEntryRequest:
      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:<value> form.
        id:
          readOnly: true
          example: mementry_01HXKD2E5NQM3T9AYWCF5E52Z0
          type: string
        metadata:
          $ref: '#/components/schemas/UpdateResourceMetadata'
        spec:
          $ref: '#/components/schemas/MemoryEntryUpdateSpec'
        updateMask:
          type: string
          format: field-mask
    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).
    UpdateResourceMetadata:
      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: |-
        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.
    MemoryEntryUpdateSpec:
      type: object
      properties:
        key:
          type: string
        description:
          type: string
        content:
          type: string
        uploadId:
          example: upload_01HXKD2E5NQM3T9AYWCFZ05DNK
          type: string
      description: |-
        MemoryEntryUpdateSpec is the input shape for UpdateMemoryEntry. Fields
         present in the request's update_mask are applied; unset fields are left
         alone. The source oneof is optional for updates — omit it to leave the
         body untouched, or set exactly one branch to replace it.
    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.
    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

````