agentrem 1.4.0 → 1.5.0

package/README.md

@@ -1,37 +1,27 @@
-# 🧠 agentrem — Reminders for AI Agents
+# 🔔 agentrem
 
 [![npm version](https://img.shields.io/npm/v/agentrem)](https://www.npmjs.com/package/agentrem)
-[![CI](https://github.com/fraction12/agentrem/actions/workflows/ci.yml/badge.svg)](https://github.com/fraction12/agentrem/actions/workflows/ci.yml)
 [![Tests](https://img.shields.io/badge/tests-392%20passing-brightgreen)](https://github.com/fraction12/agentrem)
+[![CI](https://github.com/fraction12/agentrem/actions/workflows/ci.yml/badge.svg)](https://github.com/fraction12/agentrem/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/node/v/agentrem)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
 
-Structured reminders CLI + MCP server that gives AI agents persistent, priority-aware memory with triggers, recurrence, dependencies, full-text search, and native OS notifications.
+Structured reminders for AI agents. Persistent, searchable, works across sessions.
 
-**Why?** AI agents forget between sessions. agentrem gives them a reminder system that persists across sessions, triggers on time/keywords/conditions, fires native desktop notifications, and fits within token budgets.
-
-## Install
+## Instant Start
 
 ```bash
-npm install -g agentrem
-agentrem init
+npx agentrem add "Deploy to prod" --due tomorrow --priority 2
+npx agentrem check
+npx agentrem list
 ```
 
-## Connect to Your AI Tool
-
-### Claude Code (Recommended)
-
-Claude Code has shell access, so it works out of the box — no MCP config needed.
+---
 
-**1. Install globally:**
+## For AI Agents
 
-```bash
-npm install -g agentrem
-agentrem init
-```
-
-**2. Add to your `CLAUDE.md`:**
+Copy this into your `CLAUDE.md` / `AGENTS.md` (or run `agentrem setup` to generate it):
 
 ```markdown
 ## Reminders
@@ -53,19 +43,11 @@ agentrem add "<content>" --due "<when>" --priority <1-5> --tags "<tags>"
 - `agentrem --help` — full reference
 ```
 
-**3. That's it.** Next time you tell Claude Code "remind me to deploy tomorrow at 9am", it runs:
-
-```bash
-agentrem add "Deploy to production" --due "tomorrow" --priority 2
-```
+---
 
-Next session, `agentrem check` surfaces it automatically.
-
-### Claude Desktop (MCP)
-
-For Claude Desktop (the chat app), use the MCP server:
+## MCP Server
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+For Claude Desktop and any MCP client — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -78,7 +60,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-Or without global install:
+No global install? Use `npx`:
 
 ```json
 {
@@ -91,113 +73,49 @@ Or without global install:
 }
 ```
 
-Restart Claude Desktop. You'll see agentrem tools available (add, check, list, search, complete, snooze, etc.).
-
-### Cursor / Windsurf / Any MCP Client
-
-Same MCP pattern — point your config to `agentrem-mcp` or `npx agentrem mcp`.
-
-### OpenClaw
-
-agentrem works as a CLI tool that OpenClaw agents call directly:
-
-```bash
-# Session start hook
-agentrem check --type time,session --budget 800
-
-# Keyword scanning on messages
-agentrem check --type keyword --text "user message here"
-
-# Periodic maintenance
-agentrem check --escalate && agentrem gc --days 30
-```
-
-### Any Agent with Shell Access
-
-If your agent can run shell commands, it can use agentrem directly:
-
-```bash
-agentrem add "Follow up on PR review" --due "+4h" --priority 2
-agentrem check
-agentrem complete <id>
-```
-
-## Quick Start
-
-```bash
-# Run the interactive walkthrough (first time)
-agentrem quickstart
-
-# Time-triggered reminder
-agentrem add "Deploy v2.1 to staging" --due "+2h" --priority 2 --tags "deploy,staging"
-
-# Natural language dates
-agentrem add "Send weekly report" --due "tomorrow" --priority 2
-agentrem add "Check alerts" --due "in 30 minutes"
-agentrem add "Quarterly review" --due "2026-04-01" --priority 3
-
-# Keyword-triggered (fires when text matches)
-agentrem add "Review security checklist" --trigger keyword --keywords "deploy,release" --match any
-
-# Session reminder (fires every session start)
-agentrem add "Check CI pipeline status" --trigger session
-
-# Recurring weekly reminder
-agentrem add "Weekly sync prep" --due "2026-02-24T09:00:00" --recur 1w
-
-# Check what's triggered
-agentrem check
-
-# List all active
-agentrem list
-
-# Full-text search
-agentrem search "deploy staging"
-
-# Complete
-agentrem complete <id>
-
-# Run self-diagnostics
-agentrem doctor
-```
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `init` | Initialize database (`--force` to recreate with backup) |
-| `add <content>` | Create a reminder |
-| `check` | Check for triggered reminders |
-| `list` | List reminders with filters |
-| `search <query>` | Full-text search across all fields |
-| `complete <id>` | Mark done (auto-creates next if recurring) |
-| `snooze <id>` | Snooze (`--until` or `--for`) |
-| `edit <id>` | Edit reminder fields |
-| `delete [id]` | Soft-delete (`--permanent` for hard delete) |
-| `stats` | Show statistics |
-| `gc` | Garbage collect old reminders |
-| `history [id]` | View audit trail |
-| `undo <history_id>` | Revert a change |
-| `export` | Export to JSON |
-| `import <file>` | Import from JSON |
-| `schema` | Show database schema |
-| `watch` | Background daemon: poll + fire OS notifications |
-| `doctor` | Self-diagnostic check |
-| `quickstart` | Interactive first-run walkthrough |
-| `setup` | Print CLAUDE.md snippet (`--mcp` for MCP config) |
-
-## Trigger Types
+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` · `undo_change` · `export_reminders` · `import_reminders`
+
+---
+
+## All Commands
+
+| Command | Key Flags | Example |
+|---------|-----------|---------|
+| `add <content>` | `--due` `--priority` `--tags` `--trigger` `--recur` `--agent` `--dry-run` | `agentrem add "PR review" --due "+4h" --priority 2` |
+| `check` | `--type` `--text` `--budget` `--format` `--json` `--escalate` `--agent` | `agentrem check --type time,session --budget 800 --json` |
+| `list` | `--status` `--priority` `--tag` `--due` `--limit` `--json` `--all` `--agent` | `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` | `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` `--install` `--uninstall` `--status` `--agent` | `agentrem watch --install` |
+| `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` |
-| `keyword` | Text matches keywords | `--keywords`, `--match` |
-| `condition` | Shell command matches expected output | `--check`, `--expect` |
-| `session` | Every session check | — |
+| `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` | Only via explicit check | — |
+| `manual` | Explicit `check` only | — |
 
-## Priority Levels
+### Priority Levels
 
 | Level | Label | Behavior |
 |-------|-------|----------|
@@ -207,124 +125,89 @@ agentrem doctor
 | 4 | ⚪ Low | Counted but not surfaced |
 | 5 | 💤 Someday | Skipped entirely |
 
+---
+
 ## Natural Language Dates
 
-`--due` (and `--until`, `--decay`) accept many formats:
+`--due`, `--until`, and `--decay` all accept natural language:
 
 ```bash
---due "now"                  # Immediately
---due "today"                # Today at 23:59
---due "tomorrow"             # Tomorrow at 09:00
---due "in 5 minutes"         # Relative 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 "+5m"                   # Short relative
 --due "+2h"
 --due "+3d"
 --due "+1w"
---due "2026-02-22T09:00:00"  # ISO datetime
---due "2026-02-22"           # ISO date
+--due "2026-04-01T09:00:00"   # ISO datetime
+--due "2026-04-01"            # ISO date
 ```
 
+---
+
 ## Background Watcher
 
-`agentrem watch` polls for due reminders and fires native OS notifications. Perfect for always-on setups or running as a background service.
+`agentrem watch` polls for due reminders and fires native OS notifications.
 
 ```bash
-# Run in foreground
-agentrem watch                           # Poll every 30s
+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 --once                    # Single check, then exit
 agentrem watch --verbose                 # Show poll log
 
-# Service management (auto-start on boot)
-agentrem watch --install                 # Install as launchd/systemd service
-agentrem watch --install --interval 60   # Install with custom interval
-agentrem watch --uninstall               # Remove service
-agentrem watch --status                  # Check if installed and running
+# Install as OS service (auto-start on boot)
+agentrem watch --install
+agentrem watch --install --interval 60
+agentrem watch --status
+agentrem watch --uninstall
 ```
 
-The watcher uses a 5-minute per-reminder cooldown to avoid notification spam. It checks all trigger types (`time`, `heartbeat`, `session`, `condition`) and runs escalation automatically.
+**Service files:** macOS → `~/Library/LaunchAgents/com.agentrem.watch.plist` · Linux → `~/.config/systemd/user/agentrem-watch.service` · Logs → `~/.agentrem/logs/watch.log`
 
-**Service files:**
-- macOS: `~/Library/LaunchAgents/com.agentrem.watch.plist`
-- Linux: `~/.config/systemd/user/agentrem-watch.service`
-- Logs: `~/.agentrem/logs/watch.log`
+---
 
 ## Native Notifications 🔔
 
-agentrem ships a custom Swift app (`Agentrem.app`) in `assets/`. On macOS, notifications show:
+On macOS, agentrem ships a bundled Swift app (`Agentrem.app`) so notifications appear with a bell icon — not a terminal icon.
 
-- **App name:** "agentrem" with a 🔔 bell icon (not a terminal icon)
-- **Priority-based sounds:** P1=Hero, P2=Ping, P3=Pop
-- **Cheeky overdue messages:** e.g. "so... you forgot about this one 😅"
+| Priority | Sound |
+|----------|-------|
+| P1 🔴 Critical | Hero |
+| P2 🟡 High | Ping |
+| P3 🔵 Normal | Pop |
 
-**Notification backend priority:**
+**Backend fallback order:** `Agentrem.app` → `terminal-notifier` → `osascript` → `console`
 
-| Backend | When used |
-|---------|-----------|
-| `Agentrem.app` | Preferred on macOS (bundled, no dependencies) |
-| `terminal-notifier` | Fallback if app is missing |
-| `osascript` | macOS AppleScript fallback |
-| `console` | Linux / last resort |
+Notifications include a **Complete** button and cheeky overdue messages. To rebuild the Swift app: `npm run build:notify`
 
-To rebuild the Swift app from source:
+---
 
-```bash
-npm run build:notify
-```
+## Why agentrem?
 
-## Features
-
-- **Natural language dates** — `--due "tomorrow"`, `"in 5 minutes"`, `"+2h"`, ISO formats
-- **Background watcher** — `agentrem watch` daemon with OS service management
-- **Native notifications** — custom macOS app with bell icon, priority sounds, cheeky overdue messages
-- **Recurrence** — `--recur 1d/2w/1m` auto-creates next instance on completion
-- **Dependencies** — `--depends-on <id>` blocks until dependency is completed
-- **Decay** — `--decay <datetime>` auto-expires after a date
-- **Max fires** — `--max-fires <n>` auto-completes after N triggers
-- **Escalation** — `check --escalate` promotes overdue (P3→P2 after 48h, P2→P1 after 24h)
-- **Token budget** — `check --budget <n>` limits output to fit context windows
-- **Full-text search** — FTS5 across content, context, tags, notes
-- **Undo** — revert any change via audit history
-- **Multi-agent** — `--agent <name>` isolates reminders per agent
-- **Export/Import** — JSON backup with merge and replace modes
-- **Doctor** — `agentrem doctor` runs self-diagnostics
-- **Quickstart** — `agentrem quickstart` for interactive first-run setup
-
-## MCP Server
-
-The MCP server exposes all functionality as tools, resources, and prompts for AI clients.
-
-### 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`
+```
+# vs flat files / memory.md
+agentrem check --json   # structured output your agent can parse; memory.md can't do that
+```
 
-### Resources
-- `agentrem://reminders/active` — all active reminders
-- `agentrem://reminders/overdue` — overdue reminders
-- `agentrem://stats` — statistics
-- `agentrem://schema` — database schema
+- **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
+- **Agent-native** — `--json` everywhere, `--agent` namespacing, MCP server for chat clients
 
-### Prompts
-- `triage` — review and prioritize active reminders
-- `guided-creation` — interactive reminder creation
-- `session-briefing` — session start briefing
+---
 
-## Development
+## Install
 
 ```bash
-git clone https://github.com/fraction12/agentrem.git
-cd agentrem
-npm install
-npm run build
-npm test          # 392 tests
-
-# Rebuild native notification app (Swift)
-npm run build:notify
+npm install -g agentrem
+agentrem init
 ```
 
-## License
+Then run `agentrem setup` to get your `CLAUDE.md` snippet, or `agentrem setup --mcp` for Claude Desktop.
 
-MIT
+MIT License

package/dist/api.d.ts

@@ -0,0 +1,93 @@
+import { type StatsResult } from './core.js';
+import type { Reminder } from './types.js';
+export type { Reminder } from './types.js';
+export type { StatsResult } from './core.js';
+export interface CheckResult {
+    /** Reminders that fired and fit within the token budget */
+    included: Reminder[];
+    /** Count of reminders not returned per priority level due to budget */
+    overflowCounts: Record<number, number>;
+    /** Total number of reminders that triggered (before budget trim) */
+    totalTriggered: number;
+}
+/** Reset the internal DB singleton (useful for testing with custom DB paths). */
+export declare function _resetDb(): void;
+export interface AddOptions {
+    due?: string;
+    priority?: number;
+    tags?: string;
+    agent?: string;
+    context?: string;
+    trigger?: string;
+    category?: string;
+    keywords?: string;
+    recur?: string;
+}
+/**
+ * Add a new reminder.
+ * @example
+ *   const rem = await add('Review PR', { due: 'tomorrow', priority: 2 });
+ */
+export declare function add(content: string, opts?: AddOptions): Promise<Reminder>;
+export interface CheckOptions {
+    type?: string;
+    budget?: number;
+    agent?: string;
+    format?: 'text' | 'json';
+}
+/**
+ * Check for triggered reminders. Returns all reminders that are currently
+ * due/active within the given token budget.
+ * @example
+ *   const { included } = await check({ budget: 500 });
+ */
+export declare function check(opts?: CheckOptions): Promise<CheckResult>;
+export interface ListOptions {
+    filter?: string;
+    agent?: string;
+    limit?: number;
+    status?: string;
+    priority?: string;
+    tag?: string;
+}
+/**
+ * List reminders.
+ * @example
+ *   const reminders = await list({ limit: 10 });
+ */
+export declare function list(opts?: ListOptions): Promise<Reminder[]>;
+/**
+ * Mark a reminder as completed.
+ * @example
+ *   const done = await complete('abc123');
+ */
+export declare function complete(id: string, notes?: string): Promise<Reminder>;
+export interface SnoozeOptions {
+    for: string;
+}
+/**
+ * Snooze a reminder for a duration.
+ * @example
+ *   const snoozed = await snooze('abc123', { for: '2h' });
+ */
+export declare function snooze(id: string, opts: SnoozeOptions): Promise<Reminder>;
+export interface SearchOptions {
+    limit?: number;
+    agent?: string;
+}
+/**
+ * Full-text search reminders.
+ * @example
+ *   const results = await search('PR review');
+ */
+export declare function search(query: string, opts?: SearchOptions): Promise<Reminder[]>;
+/**
+ * Get reminder statistics.
+ * @example
+ *   const s = await stats();
+ *   console.log(s.totalActive);
+ */
+export declare function stats(opts?: {
+    agent?: string;
+}): Promise<StatsResult>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAMA,OAAO,EAQL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAI7C,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;CACxB;AAeD,iFAAiF;AACjF,wBAAgB,QAAQ,IAAI,IAAI,CAK/B;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAc/E;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAMrE;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAQlE;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAG5E;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE/E;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAKrF;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CAAC,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAG3E"}

package/dist/api.js

@@ -0,0 +1,111 @@
+// ── Programmatic JavaScript API ───────────────────────────────────────────
+// Clean async wrappers for use by agents and scripts.
+// import { add, check, list, complete, search } from 'agentrem'
+import { initDb, getDb } from './db.js';
+import { coreAdd, coreCheck, coreList, coreSearch, coreComplete, coreSnooze, coreStats, } from './core.js';
+// ── Lazy DB singleton ──────────────────────────────────────────────────────
+let _db = null;
+function db() {
+    if (!_db) {
+        // Auto-init on first call so `import { add } from 'agentrem'` just works
+        initDb(false);
+        _db = getDb();
+    }
+    return _db;
+}
+/** Reset the internal DB singleton (useful for testing with custom DB paths). */
+export function _resetDb() {
+    if (_db) {
+        try {
+            _db.close();
+        }
+        catch { /* ignore */ }
+        _db = null;
+    }
+}
+/**
+ * Add a new reminder.
+ * @example
+ *   const rem = await add('Review PR', { due: 'tomorrow', priority: 2 });
+ */
+export async function add(content, opts) {
+    const result = coreAdd(db(), {
+        content,
+        due: opts?.due,
+        priority: opts?.priority,
+        tags: opts?.tags,
+        agent: opts?.agent,
+        context: opts?.context,
+        trigger: opts?.trigger,
+        category: opts?.category,
+        keywords: opts?.keywords,
+        recur: opts?.recur,
+    });
+    return result;
+}
+/**
+ * Check for triggered reminders. Returns all reminders that are currently
+ * due/active within the given token budget.
+ * @example
+ *   const { included } = await check({ budget: 500 });
+ */
+export async function check(opts) {
+    return coreCheck(db(), {
+        type: opts?.type,
+        budget: opts?.budget,
+        agent: opts?.agent,
+    });
+}
+/**
+ * List reminders.
+ * @example
+ *   const reminders = await list({ limit: 10 });
+ */
+export async function list(opts) {
+    return coreList(db(), {
+        agent: opts?.agent,
+        limit: opts?.limit,
+        status: opts?.status,
+        priority: opts?.priority,
+        tag: opts?.tag ?? opts?.filter,
+    });
+}
+/**
+ * Mark a reminder as completed.
+ * @example
+ *   const done = await complete('abc123');
+ */
+export async function complete(id, notes) {
+    const { completed } = coreComplete(db(), id, notes);
+    return completed;
+}
+/**
+ * Snooze a reminder for a duration.
+ * @example
+ *   const snoozed = await snooze('abc123', { for: '2h' });
+ */
+export async function snooze(id, opts) {
+    return coreSnooze(db(), id, undefined, opts.for);
+}
+/**
+ * Full-text search reminders.
+ * @example
+ *   const results = await search('PR review');
+ */
+export async function search(query, opts) {
+    return coreSearch(db(), {
+        query,
+        limit: opts?.limit,
+    });
+}
+/**
+ * Get reminder statistics.
+ * @example
+ *   const s = await stats();
+ *   console.log(s.totalActive);
+ */
+export async function stats(opts) {
+    void opts; // agent filter not currently in coreStats; included for API compat
+    return coreStats(db());
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export declare const SCHEMA_VERSION = 1;
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.5.0";
 export declare const PRIORITY_LABELS: Record<number, string>;
 export declare const PRIORITY_COLORS: Record<number, string>;
 export declare const VALID_TRIGGERS: Set<string>;

package/dist/types.js

@@ -1,6 +1,6 @@
 // ── Types ──────────────────────────────────────────────────────────────────
 export const SCHEMA_VERSION = 1;
-export const VERSION = '1.4.0';
+export const VERSION = '1.5.0';
 export const PRIORITY_LABELS = {
     1: '🔴 Critical',
     2: '🟡 High',

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "agentrem",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Structured reminders CLI for AI agents with MCP server",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/api.js",
+  "types": "dist/api.d.ts",
+  "exports": {
+    ".": "./dist/api.js",
+    "./mcp": "./dist/mcp/server.js"
+  },
   "bin": {
     "agentrem": "dist/index.js",
     "agentrem-mcp": "dist/mcp/server.js"
@@ -18,6 +23,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "postbuild": "chmod +x dist/index.js dist/mcp/server.js",
     "build:notify": "bash scripts/build-notify.sh",
     "dev": "tsc --watch",
     "test": "vitest run",