# agentrem

> You lose context between sessions. agentrem fixes that.

Structured reminders CLI for AI agents. Persistent, SQLite-backed, works across sessions.

## Quick Integration (3 commands)

```bash
# 1. Install (one time)
npm install -g agentrem  # DB auto-initializes on first use

# 2. On session start — check what's due
agentrem check --type time,session --budget 800

# 3. When your human says "remind me" — save it
agentrem add "Deploy to prod" --due "+2h" --priority 2
```

## All Commands

```bash
agentrem add <content>          # Create a reminder
agentrem check                  # See what's triggered/due
agentrem check --watch          # Block until a reminder fires (see below)
agentrem list                   # List all active reminders
agentrem search <query>         # Full-text search
agentrem complete <id>          # Mark done (auto-creates next if recurring)
agentrem snooze <id> --for 2h   # Snooze by duration or --until datetime
agentrem edit <id>              # Modify fields
agentrem delete <id>            # Soft delete (--permanent to hard delete)
agentrem stats                  # Overview
agentrem history [id]           # Audit trail
agentrem undo <history_id>      # Revert a change
agentrem gc                     # Garbage collect old reminders
agentrem export                 # Export to JSON
agentrem import <file>          # Import from JSON
agentrem watch                  # Background daemon: poll + fire OS notifications + auto-gc
agentrem doctor                 # Self-diagnostic check
agentrem quickstart             # Interactive first-run walkthrough
agentrem setup                  # Print CLAUDE.md snippet (--mcp for MCP config)
agentrem schema                 # Show database schema
agentrem init                   # Initialize database (auto-runs on first use)
```

## add flags
`--due/-d <datetime>` `--trigger/-t <type>` `--priority/-p <1-5>` `--tags <tags>`
`--context/-c <ctx>` `--category <cat>` `--keywords/-k <kw>` `--match any|all|regex`
`--check <cmd>` `--expect <output>` `--decay <datetime>` `--max-fires <n>`
`--recur/-r 1d|2w|1m` `--agent/-a <name>` `--depends-on <id>` `--source agent|user|system` `--dry-run`

## check flags
`--type <types>` `--text <text>` `--budget <n>` `--format full|compact|inline`
`--json` `--agent/-a <name>` `--escalate` `--dry-run`
`--watch` `--timeout <seconds>` (used with --watch)

## check --watch (blocking mode)

Blocks until the next due reminder fires. Polls every 5 seconds.

```bash
agentrem check --watch                        # Wait indefinitely for any time trigger
agentrem check --watch --timeout 300          # Exit 1 if no reminder in 5 minutes
agentrem check --watch --json                 # Output full reminder JSON when it fires
agentrem check --watch --type time,heartbeat  # Filter trigger types
agentrem check --watch --agent jarvis         # Filter by agent
```

Exit codes: `0` = reminder found (or SIGINT/SIGTERM), `1` = timeout elapsed with no reminder.
Does NOT update fire counts. Use `agentrem check` (without --watch) to actually fire/mark reminders.

## list flags
`--status/-s <statuses>` `--priority <priorities>` `--tag <tag>` `--trigger <type>`
`--due today|tomorrow|overdue|week|<date>` `--agent/-a <name>` `--category <cat>`
`--limit <n>` `--format table|json|compact` `--json` `--all`

## snooze flags
`--until <datetime>` `--for 1h|2h|1d|3d|1w`

## edit flags
`--content` `--context` `--priority/-p` `--due/-d` `--tags` `--add-tags` `--remove-tags`
`--category` `--decay` `--max-fires` `--keywords/-k` `--agent/-a`

## delete flags
`--permanent` `--status <status>` `--older-than <days>`

## watch flags
`--interval <seconds>` `--agent/-a <name>` `--once` `--verbose`
`--on-fire <command>` `--on-fire-preset <name>` `--on-fire-timeout <ms>`
`--install` `--uninstall` `--status`

## Trigger Types
`time` — specific datetime | `keyword` — message text matches | `condition` — shell command output
`session` — every session check | `heartbeat` — every heartbeat check | `manual` — explicit only

## Priority Levels
1=🔴 Critical (always), 2=🟡 High, 3=🔵 Normal, 4=⚪ Low (counted), 5=💤 Someday (skipped)

## Natural Language Dates
`now` `today` `tomorrow` `in 5 minutes` `in 2 hours` `in 3 days` `in 1 week`
`+5m` `+2h` `+3d` `+1w` `2026-02-22T09:00:00` `2026-02-22`

## JSON output
`--json` available on: `check`, `list`, `search`, `stats`, `history`, `doctor`

## Agent Integration Patterns

```bash
# Session start
agentrem check --type time,session --budget 800

# Keyword scan
agentrem check --type keyword --text "the user's message here"

# Blocking wait (e.g., pause agent until something fires)
agentrem check --watch --timeout 60 && agentrem check --json

# Maintenance
agentrem check --escalate && agentrem gc --older-than 30
```

## Programmatic API (Node.js / TypeScript)

```typescript
import { add, check, list, complete, snooze, search, stats } from 'agentrem';

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

// Check for triggered reminders
const { included } = await check({ type: 'time,session', budget: 800 });

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

// Complete a reminder
const done = await complete('abc12345', 'Done!');

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

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

// Get stats
const s = await stats();
console.log(s.totalActive, s.overdue);
```

## MCP Server
`agentrem-mcp` — 14 tools, 4 resources, 3 prompts
Run `agentrem setup --mcp` to print Claude Desktop config.

See `llms-full.txt` for complete API reference with all flags and JSON examples.