Agentrem

npm version CI License: MIT Node.js MCP

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:

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:

agentrem watch --on-fire-preset openclaw   # auto-delivers to your OpenClaw agent

Or craft your own:

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