Give your agent memory

A memory layer is knowledge your agent reads when it needs it, instead of prose you cram into the prompt. You write entries, each one a keyed piece of content, attach the layer to a variation, and the agent pulls an entry into context with the get_memory tool only when the task calls for it. The window stays lean, and the knowledge stays editable on its own. In this lesson you write a support knowledge layer, attach it to an agent, and run an objective that reads from it.

What you need

A workspace, with your API key in CADENYA_API_KEY and your workspace ID in WORKSPACE_ID.
A published agent with a variation. The Support Agent works.

Step 1: Write a memory layer

In the sidebar, open Memory Layers and click to create one. Name it Support knowledge. A layer holds entries. Each entry has a Key (a lookup handle, like a file path), a Description (the one-line hint the agent reads in its manifest to decide when to load the entry), and Content (the body the agent reads). Add one entry with the key policy/refunds.

The Create layer form with a name and an entry keyed policy/refunds — The Create layer form with a refund policy entry

The same layer and entry from your terminal, as two calls:

# Create the layer
curl https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/memory_layers \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "metadata": { "name": "Support knowledge", "externalId": "support-knowledge" },
        "spec": { "type": "MEMORY_LAYER_TYPE_SKILLS", "description": "Policies and procedures for the support agent" }
      }'

# Add an entry, keyed for lookup
curl https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/memory_layers/external_id:support-knowledge/entries \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "metadata": { "name": "Refund policy" },
        "spec": {
          "type": "content",
          "key": "policy/refunds",
          "description": "When the customer asks for a refund or return.",
          "content": "Refund any order under 30 days old. Above 30 days, offer store credit. Never refund shipping."
        }
      }'

The dashboard form and the API take the same three fields: the Key, the Description (the one-line hint that shows in the agent manifest so it knows when to reach for this entry), and the Content. Over the API, type: "content" marks the spec as inline content; an entry built from an upload sends type: "uploadId" with the upload’s ID instead. In the dashboard, you can also drop up to ten files at once, turning each into its own entry keyed by the filename. A blank description still works, but a sharp one helps the agent choose.

The key is a flat, opaque string, not a real path. Slashes like policy/refunds are fine and suggest hierarchy, but the lookup matches the whole key. Keys are unique within a layer. Cadenya reserves the cadenya/ and system/ prefixes for its own entries, so keep yours clear of them.

Step 2: Attach it to a variation

A layer does nothing until a variation carries it. On the variation, click + Add memory layer and pick Support knowledge.

The Add memory layer dialog attaching Support knowledge to a variation — Attaching the layer to a variation

The layer joins the variation’s baseline cascade, the set every objective for this variation starts with. Through the API, the assignment takes a position, where a lower number is more specific and wins when two layers share a key:

curl https://api.cadenya.com/v1/workspaces/$WORKSPACE_ID/agents/external_id:support/variations/external_id:friendly/memory_layer_assignments \
  -H "Authorization: Bearer $CADENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memoryLayerId": "external_id:support-knowledge", "position": 0 }'

Now any objective for this variation can reach the layer.

Step 3: Run it and watch the read

Run the agent with a question the entry answers, such as A customer wants a refund on a 45-day-old order. What do I do?. The agent sees policy/refunds and its description in the manifest, calls get_memory with that key to pull the body into context, and answers from it. The load is recorded in the objective’s events, so you can see exactly which entry the agent reached for and when. The agent reads on demand. Only the manifest of keys and descriptions sits in the window up front; an entry’s body enters only when the agent loads it, which is what keeps a large knowledge base cheap to carry.

Going deeper

A variation can carry several layers, and the cascade decides who wins when two entries share a key. You can also add extra layers to a single objective at run time, or let the agent write memories of its own with episodic memory. All of it is covered in How memory layers work:

How memory layers work

The memory cascade, the get_memory tool, per-objective layers, and episodic memory.

Build an agent that improves

The variations that carry your layers.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Give your agent memory

What you need

Step 1: Write a memory layer

Step 2: Attach it to a variation

Step 3: Run it and watch the read

Going deeper

How memory layers work

Build an agent that improves

​What you need

​Step 1: Write a memory layer

​Step 2: Attach it to a variation

​Step 3: Run it and watch the read

​Going deeper

How memory layers work

Build an agent that improves

What you need

Step 1: Write a memory layer

Step 2: Attach it to a variation

Step 3: Run it and watch the read

Going deeper