Set Expiry Policy

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"
  }'

{
  "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"
  }
}

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "retention"],
      "msg": "Value error, unknown memory type 'notatype' in retention table."
    }
  ]
}

{
  "detail": "Missing session token. Use X-Session-Token header."
}

PUT

api

agents

{agent_id}

policy

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"
  }'

{
  "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"
  }
}

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "retention"],
      "msg": "Value error, unknown memory type 'notatype' in retention table."
    }
  ]
}

{
  "detail": "Missing session token. Use X-Session-Token header."
}

Overview

Replaces the agent’s expiry policy wholesale. Saving a policy expires nothing on its own — run Apply Expiry Policy afterwards, or let the nightly schedule job pick it up. See the Memory Lifecycle reference for the model.

Authentication

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

string

required

Session token from Activate Agent. Must match agent_id.

string

required

Must be application/json

Path Parameters

string

required

The unique identifier of the agent.

Body

integer

default:"1"

Policy schema version.

object

Maps a memory type to a maximum age ({"context": "7d"}). Types absent from the table never expire on a timer. An unknown type is rejected.

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.

string

default:"never"

How long an already-expired memory is kept before purging can delete it permanently. Unrelated to what retention expires.

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.

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

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"
  }'

{
  "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"
  }
}

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "retention"],
      "msg": "Value error, unknown memory type 'notatype' in retention table."
    }
  ]
}

{
  "detail": "Missing session token. Use X-Session-Token header."
}

Next Steps

Apply Expiry Policy to run the sweep
List Policy Presets for a starting point

Getting Started

System

Agent Management

Session Management

Data

Expiry Policy

Search & Discovery

AI Generation

Overview

Authentication

Path Parameters

Body

Rule `match` conditions

Durations

Next Steps

​Overview

​Authentication

​Path Parameters

​Body

​Rule match conditions

​Durations

​Next Steps

Overview

Authentication

Path Parameters

Body

Rule `match` conditions

Durations

Next Steps