> ## 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.
# Give your agent memory
> A hands-on lesson. Write a memory layer, attach it to a variation, and watch the agent read what it needs on demand.
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](/docs/guides/agents) 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 same layer and entry from your terminal, as two calls:
```bash theme={null}
# 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](/docs/api-reference/uploadservice/create-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 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:
```bash theme={null}
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](/docs/guides/memory-layers):
The memory cascade, the get\_memory tool, per-objective layers, and episodic memory.
The variations that carry your layers.