> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Expiry Policy

> Replace the agent's expiry policy.

## Overview

Replaces the agent's expiry policy wholesale. Saving a policy **expires nothing on
its own** — run [Apply Expiry Policy](/api-reference/policy/apply-policy)
afterwards, or let the nightly schedule job pick it up.

See the [Memory Lifecycle](/reference/memory-lifecycle) reference for the model.

## Authentication

API clients do not send an API key or `Authorization` header.

<ParamField header="X-Session-Token" type="string" required>
  Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the agent.
</ParamField>

## Body

<ParamField body="version" type="integer" default="1">
  Policy schema version.
</ParamField>

<ParamField body="retention" type="object">
  Maps a [memory type](/reference/memory-types) to a maximum age
  (`{"context": "7d"}`). Types absent from the table never expire on a timer.
  An unknown type is rejected.
</ParamField>

<ParamField body="rules" type="array">
  Named match blocks, checked in order. The first match wins and overrides the
  retention table, so a rule with `expire_after: "never"` pins a memory active.
  Each entry takes `name`, `match`, and `expire_after`.
</ParamField>

<ParamField body="purge_expired_after" type="string" default="never">
  How long an *already-expired* memory is kept before
  [purging](/api-reference/policy/purge-expired) can delete it permanently.
  Unrelated to what `retention` expires.
</ParamField>

### Rule `match` conditions

Every condition set must match (AND). An empty `match` matches every memory.

| Field              | Type   | Matches on                                    |
| ------------------ | ------ | --------------------------------------------- |
| `type`             | array  | Memory types                                  |
| `tags`             | array  | Memory has any of these tags                  |
| `source`           | array  | Writer labels (`user`, `cursor`, …)           |
| `provenance`       | array  | Provenance values (`imported`, `inferred`, …) |
| `confidence_below` | number | Stored confidence strictly below this         |

### Durations

`30m`, `12h`, `7d`, `2w`, `3mo`, `1y`, or `never`. A month is 30 days.

<Note>
  A rule `name` is stamped onto expired memories as `expired_by`, so it is bounded
  to letters, digits, `.`, `_` and `-`. Duplicate rule names are rejected.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "http://localhost:8000/api/v2/agents/my-agent/policy" \
    -H "X-Session-Token: your_session_token" \
    -H "Content-Type: application/json" \
    -d '{
      "version": 1,
      "retention": { "context": "7d", "event": "30d" },
      "rules": [
        { "name": "pinned", "match": { "tags": ["pinned"] }, "expire_after": "never" },
        { "name": "scratch-notes", "match": { "tags": ["scratch"] }, "expire_after": "3d" }
      ],
      "purge_expired_after": "never"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "agent_id": "my-agent",
    "path": "/home/user/.memanto/policies/my-agent.yaml",
    "policy": {
      "version": 1,
      "retention": { "context": "7d", "event": "30d" },
      "rules": [
        { "name": "pinned", "match": { "tags": ["pinned"] }, "expire_after": "never" },
        { "name": "scratch-notes", "match": { "tags": ["scratch"] }, "expire_after": "3d" }
      ],
      "purge_expired_after": "never"
    }
  }
  ```

  ```json 422 - Validation Error (unknown memory type) theme={null}
  {
    "detail": [
      {
        "type": "value_error",
        "loc": ["body", "retention"],
        "msg": "Value error, unknown memory type 'notatype' in retention table."
      }
    ]
  }
  ```

  ```json 401 - Unauthorized (Missing Token) theme={null}
  {
    "detail": "Missing session token. Use X-Session-Token header."
  }
  ```
</ResponseExample>

## Next Steps

* [Apply Expiry Policy](/api-reference/policy/apply-policy) to run the sweep
* [List Policy Presets](/api-reference/policy/list-policy-presets) for a starting point