🔔 agentrem

![npm version](https://www.npmjs.com/package/agentrem) ![CI](https://github.com/fraction12/agentrem/actions/workflows/ci.yml) ![License: MIT](https://opensource.org/licenses/MIT) ![Node.js](https://nodejs.org) ![MCP](https://modelcontextprotocol.io)

Structured reminders for AI agents. Persistent, searchable, works across sessions.

Instant Start

npx agentrem add "Deploy to prod" --due tomorrow --priority 2
npx agentrem check
npx agentrem list

---

For AI Agents

Copy this into your CLAUDE.md / AGENTS.md (or run agentrem setup to generate it):

## Reminders
You have access to `agentrem` CLI for persistent reminders across sessions.

### On every session start, run:
agentrem check --type time,session --budget 800

### When the user says "remind me", "don't forget", "follow up", or "next time":
agentrem add "<content>" --due "<when>" --priority <1-5> --tags "<tags>"

### Key commands:
- `agentrem add` — create a reminder
- `agentrem check` — see what's triggered/due
- `agentrem check --watch` — block until next reminder fires
- `agentrem list` — list all active reminders
- `agentrem search <query>` — full-text search
- `agentrem complete <id>` — mark done
- `agentrem snooze <id> --for 2h` — snooze
- `agentrem --help` — full reference

---

MCP Server

For Claude Desktop and any MCP client — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentrem": {
      "command": "agentrem-mcp",
      "args": []
    }
  }
}

No global install? Use npx:

{
  "mcpServers": {
    "agentrem": {
      "command": "npx",
      "args": ["-y", "agentrem", "mcp"]
    }
  }
}

Run agentrem setup --mcp to print this config. MCP tools: add_reminder · check_reminders · list_reminders · search_reminders · complete_reminder · snooze_reminder · edit_reminder · delete_reminder · get_stats · get_history · undo_change · garbage_collect · export_reminders · import_reminders

---

All Commands

| Command | Key Flags | Example | |---------|-----------|---------| | add <content> | --due --priority --tags --trigger --recur --agent --context --category --depends-on --dry-run | agentrem add "PR review" --due "+4h" --priority 2 | | check | --type --text --budget --format --json --escalate --agent --dry-run | agentrem check --type time,session --budget 800 --json | | check --watch | --timeout --json --type --agent | agentrem check --watch --timeout 300 --json | | list | --status --priority --tag --due --limit --json --all --agent --category --trigger --format | agentrem list --priority 1,2 --json | | search <query> | --status --limit --json | agentrem search "deploy staging" --json | | complete <id> | --notes | agentrem complete abc12345 | | snooze <id> | --until --for | agentrem snooze abc12345 --for 2h | | edit <id> | --content --due --priority --tags --add-tags --remove-tags --context --category --agent | agentrem edit abc12345 --priority 1 | | delete [id] | --permanent --status --older-than | agentrem delete abc12345 --permanent | | stats | --json | agentrem stats --json | | history [id] | --limit --json | agentrem history --limit 20 --json | | undo <history_id> | — | agentrem undo 42 | | gc | --older-than --dry-run | agentrem gc --older-than 30 | | export | --out --status | agentrem export --out backup.json | | import <file> | --merge --replace --dry-run | agentrem import backup.json --merge | | watch | --interval --once --verbose --on-fire --on-fire-preset --on-fire-timeout --install --uninstall --status --agent | agentrem watch --on-fire-preset openclaw | | setup | --mcp | agentrem setup / agentrem setup --mcp | | doctor | --json | agentrem doctor | | init | --force | agentrem init | | quickstart | — | agentrem quickstart | | schema | — | agentrem schema |

--json is available on check, list, search, stats, history, doctor — use it for structured output in your agent.

Trigger Types

| Type | Fires when... | Key flags | |------|--------------|-----------| | time | Due datetime is reached | --due (notifies once by default; stays active until explicitly completed) | | keyword | Message text matches | --keywords, --match any\|all\|regex | | condition | Shell command output matches | --check, --expect | | session | Every session start check | — | | heartbeat | Every heartbeat check | — | | manual | Explicit check only | — |

Priority Levels

| Level | Label | Behavior | |-------|-------|----------| | 1 | 🔴 Critical | Always surfaced | | 2 | 🟡 High | Surfaced within 60% budget | | 3 | 🔵 Normal | Surfaced within 85% budget | | 4 | ⚪ Low | Counted but not surfaced | | 5 | 💤 Someday | Skipped entirely |

---

Natural Language Dates

--due, --until, and --decay all accept natural language:

--due "now"                   # Immediately
--due "today"                 # Today at 23:59
--due "tomorrow"              # Tomorrow at 09:00
--due "in 5 minutes"
--due "in 2 hours"
--due "in 3 days"
--due "in 1 week"
--due "+5m"                   # Short relative
--due "+2h"
--due "+3d"
--due "+1w"
--due "2026-04-01T09:00:00"   # ISO datetime
--due "2026-04-01"            # ISO date

---

check --watch: Blocking Mode

agentrem check --watch blocks until the next due reminder fires. Useful for scripting, pipelines, or pausing an agent until something needs attention.

# Wait indefinitely for next reminder
agentrem check --watch

# Exit 1 if nothing fires within 5 minutes
agentrem check --watch --timeout 300

# Get the full reminder as JSON when it fires
agentrem check --watch --json

# Filter by trigger type and agent
agentrem check --watch --type time,heartbeat --agent jarvis --timeout 60

Exit codes: 0 = reminder found (or SIGINT/SIGTERM), 1 = timeout elapsed with no reminder.

Note: --watch does not update fire counts. Use a regular agentrem check after to actually mark reminders as fired.

Poll-then-act pattern: ``bash if agentrem check --watch --timeout 120 --json > /tmp/due.json; then echo "Reminder fired:" cat /tmp/due.json agentrem check # mark as fired fi ``

watch --on-fire: Hooks

⚠️ Security: The --on-fire command runs with your user's permissions. Only use trusted commands. Reminder data is passed via environment variables (never shell-interpolated) to prevent injection.

Execute a shell command whenever a reminder fires:

agentrem watch --on-fire "curl -X POST https://hooks.example.com/reminder"

Reminder data is passed as environment variables (no shell injection — data never interpolated into the command):

| Variable | Description | |----------|-------------| | AGENTREM_ID | Reminder ID | | AGENTREM_CONTENT | Reminder text | | AGENTREM_PRIORITY | Priority (1-5) | | AGENTREM_TAGS | Comma-separated tags | | AGENTREM_CONTEXT | Context string | | AGENTREM_DUE | Due datetime | | AGENTREM_FIRE_COUNT | Number of times fired |

Fire-and-forget — failures are logged to ~/.agentrem/logs/on-fire.log, never crash the watcher
Sequential — multiple reminders process one at a time
Timeout: 5 seconds default, configurable with --on-fire-timeout <ms>

Built-in presets — skip the shell command entirely: ``bash agentrem watch --on-fire-preset openclaw # auto-delivers to your OpenClaw agent ``

Or craft your own: ``bash agentrem watch --on-fire 'curl -X POST https://hooks.example.com/reminder -d "text=$AGENTREM_CONTENT"' ``

---

Background Watcher

agentrem watch polls for due reminders and fires native OS notifications.

agentrem watch                           # Poll every 30s (foreground)
agentrem watch --interval 60             # Custom interval
agentrem watch --once                    # Single check and exit
agentrem watch --agent jarvis            # Watch for a specific agent
agentrem watch --verbose                 # Show poll log

# Install as OS service (auto-start on boot)
agentrem watch --install
agentrem watch --install --interval 60
agentrem watch --status
agentrem watch --uninstall

Service files: macOS → ~/Library/LaunchAgents/com.agentrem.watch.plist · Linux → ~/.config/systemd/user/agentrem-watch.service · Logs → ~/.agentrem/logs/watch.log

---

Native Notifications 🔔

On macOS, agentrem ships a bundled Swift app (Agentrem.app) that runs as a singleton process — notifications appear under "agentrem" with a bell icon.

| Priority | Sound | |----------|-------| | P1 🔴 Critical | Hero | | P2 🟡 High | Ping | | P3 🔵 Normal | Pop |

Notification behavior:

Click body → notification re-appears (won't dismiss until you act on it)
Complete ✅ → marks reminder complete and dismisses (the only way to complete a fired reminder)
Multiple reminders → single process handles all via IPC
Fallback chain: Agentrem.app → terminal-notifier → osascript → console

To rebuild the Swift app: npm run build:notify

---

Programmatic API

Use agentrem directly from JavaScript/TypeScript — no CLI subprocess needed.

npm install agentrem

import { add, check, list, complete, snooze, search, stats } from 'agentrem';
import type { Reminder } from 'agentrem';

// Add a reminder
const rem = await add('Review PR #42', { due: 'tomorrow', priority: 2, tags: 'pr,review' });

// Check for triggered reminders (session start pattern)
const { included, totalTriggered } = await check({ type: 'time,session', budget: 800 });
for (const r of included) {
  console.log(`[P${r.priority}] ${r.content}`);
}

// List active reminders
const reminders = await list({ limit: 20 });

// Complete a reminder
const done = await complete(rem.id, 'Reviewed and merged');

// Snooze a reminder
const snoozed = await snooze(rem.id, { for: '2h' });

// Full-text search
const results = await search('deploy staging');

// Get statistics
const s = await stats();
console.log(`${s.totalActive} active, ${s.overdue} overdue`);

All API functions are async and return full Reminder objects. The database is auto-initialized on first call (no manual init needed).

See llms-full.txt for complete type signatures and all options.

---

Why agentrem?

# vs flat files / memory.md
agentrem check --json   # structured output your agent can parse; memory.md can't do that

Persistent across sessions — SQLite-backed, survives restarts, not just in-context notes
Priority-aware + token budgets — check --budget 800 fits within any context window without overflow
Triggerable — time, keyword, condition, session, heartbeat triggers; not just static lists
Blocking watch mode — check --watch lets agents pause until something needs attention
Agent-native — --json everywhere, --agent namespacing, MCP server for chat clients

---

Install

npm install -g agentrem

The database auto-initializes on first use. Run agentrem setup to get your CLAUDE.md snippet, or agentrem setup --mcp for Claude Desktop.

MIT License

agentrem