# agent_reminder_upsert

Create or Update Agent Reminder

## Beschreibung

Schedules a follow-up prompt for yourself, or updates one you
already scheduled. Use this whenever the right next step isn't
"do it now" but "check back later" — e.g. you DM'd a user
about a missed standup and want to re-check in 2 hours, or
you asked a teammate for an estimate and want to escalate if
it's still missing tomorrow.

Two modes, decided by whether `id` is set:
- Without `id` → create. `prompt` and `due_at` required.
  Returns the new reminder's `id` (`arem_…`). Repeated calls
  without `id` create new rows (not idempotent — use a stable
  `subject` to dedupe yourself).
- With `id` → update. Only the fields you pass are changed.
  Use this to:
  - push the reminder out: pass `id` + a new `due_at`
  - mark it handled: pass `id` + `completed: true` (idempotent)
  - re-open: pass `id` + `completed: false`
  - rewrite the prompt as the situation evolves.

Workflow: at session start, call `agent_reminder_list_due`
first to find what's due, do the work, then call this tool
with `id` + `completed: true` to clear it.

`due_at` accepts several formats — pick whichever is easiest:
- **Relative offset (most convenient for "in X")**: `+30m`,
  `+2h`, `+1d`, `+1w` (units: s/m/h/d/w; minutes / hours /
  days / weeks). No spaces.
- **ISO 8601 datetime**: `2026-05-07T10:00:00Z` or
  `2026-05-07T12:00:00+02:00` (timezone offset preserved).
- **Date only**: `2026-05-07` (becomes 00:00 in your timezone).
- **Space-separated**: `2026-05-07 10:00` or
  `2026-05-07 10:00:00`.
- **Unix epoch seconds**: `1746604800`.
Negative offsets are rejected (reminders are always for the
future). Bad input returns an error that lists every accepted
format.

Use the same `subject` and `tags` conventions as the logbook
(`"task:ENG-123"`, `["standup-followup"]`) — they make the
inbox filterable. Reminders auto-expire 14 days after creation
if not completed (they stop appearing in `list_due`), so don't
use this for long-horizon planning.

Scoped to (you, this account); other users can't see or update
your reminders. `prompt` ≤ 8 KB; `subject` ≤ 200 chars.

Example (create, relative): `prompt: "Did @max submit
standup? If not, DM @lead."`, `due_at: "+2h"`,
`subject: "standup:user_max:2026-05-07"`,
`tags: ["standup-followup"]`.
Example (create, ISO): same `prompt`, `due_at:
"2026-05-07T10:00:00Z"`.
Example (push out 1 day): `id: "arem_abc123"`, `due_at: "+1d"`.
Example (complete): `id: "arem_abc123"`, `completed: true`.

## Zugriff

Zugriffsprofil: `gated`. Module: `none`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja |  |
| `id` | string | Nein | Reminder prefix id (arem_…). Omit to create. |
| `prompt` | string | Nein | What you want yourself to do later. Required on create. ≤ 8 KB. |
| `due_at` | string | Nein | When the reminder becomes due. Required on create. Accepts relative offset ('+30m', '+2h', '+1d', '+1w'), ISO 8601 ('2026-05-07T10:00:00Z'), date-only ('2026-05-07'), space-separated ('2026-05-07 10:00'), or Unix epoch seconds. See tool description for full list. |
| `subject` | string / null | Nein | Optional stable identifier, e.g. 'task:ENG-123'. |
| `tags` | array | Nein | Optional short labels. |
| `completed` | boolean | Nein | true → mark handled (idempotent); false → re-open. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "Reminder prefix id (arem_…). Omit to create."
    },
    "prompt": {
      "type": "string",
      "description": "What you want yourself to do later. Required on create. ≤ 8 KB."
    },
    "due_at": {
      "type": "string",
      "description": "When the reminder becomes due. Required on create. Accepts relative offset ('+30m', '+2h', '+1d', '+1w'), ISO 8601 ('2026-05-07T10:00:00Z'), date-only ('2026-05-07'), space-separated ('2026-05-07 10:00'), or Unix epoch seconds. See tool description for full list."
    },
    "subject": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional stable identifier, e.g. 'task:ENG-123'."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional short labels."
    },
    "completed": {
      "type": "boolean",
      "description": "true → mark handled (idempotent); false → re-open."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "reminder": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "prompt": {
          "type": "string"
        },
        "subject": {
          "type": [
            "string",
            "null"
          ]
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "due_at": {
          "type": "string"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "prompt",
        "tags",
        "due_at",
        "created_at"
      ]
    }
  },
  "required": [
    "reminder"
  ],
  "type": "object"
}
```