agentrem 1.0.0

package/README.md

@@ -0,0 +1,194 @@
+# 🧠 agentrem — Reminders for AI Agents
+
+Structured reminders CLI + MCP server that gives AI agents persistent, priority-aware memory with triggers, recurrence, dependencies, and full-text search.
+
+**Why?** AI agents forget between sessions. agentrem gives them a reminder system that persists across sessions, triggers on time/keywords/conditions, and fits within token budgets.
+
+## Install
+
+```bash
+npm install -g agentrem
+agentrem init
+```
+
+## Connect to Your AI Tool
+
+### Claude Desktop / Claude Code
+
+Add to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agentrem": {
+      "command": "agentrem-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Or if using `npx`:
+
+```json
+{
+  "mcpServers": {
+    "agentrem": {
+      "command": "npx",
+      "args": ["-y", "agentrem", "mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see agentrem tools available (add, check, list, search, complete, snooze, etc.).
+
+### Cursor / Windsurf / Any MCP Client
+
+Same pattern — point your MCP config to:
+
+```bash
+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
+# Time-triggered reminder
+agentrem add "Deploy v2.1 to staging" --due "+2h" --priority 2 --tags "deploy,staging"
+
+# 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 "monday 9am" --recur 1w
+
+# Check what's triggered
+agentrem check
+
+# List all active
+agentrem list
+
+# Full-text search
+agentrem search "deploy staging"
+
+# Complete
+agentrem complete <id>
+```
+
+## 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 |
+
+## 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 | — |
+| `heartbeat` | Every heartbeat check | — |
+| `manual` | Only via explicit check | — |
+
+## 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 |
+
+## Features
+
+- **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
+
+## 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`
+
+### Resources
+- `agentrem://reminders/active` — all active reminders
+- `agentrem://reminders/overdue` — overdue reminders
+- `agentrem://stats` — statistics
+- `agentrem://schema` — database schema
+
+### Prompts
+- `triage` — review and prioritize active reminders
+- `guided-creation` — interactive reminder creation
+- `session-briefing` — session start briefing
+
+## Development
+
+```bash
+git clone https://github.com/fraction12/agentrem.git
+cd agentrem
+npm install
+npm run build
+npm test          # 292 tests
+```
+
+## License
+
+MIT

package/dist/core.d.ts

@@ -0,0 +1,138 @@
+import type Database from 'better-sqlite3';
+import { type Reminder, type HistoryEntry } from './types.js';
+export interface AddOptions {
+    content: string;
+    due?: string;
+    trigger?: string;
+    priority?: number;
+    tags?: string;
+    context?: string;
+    category?: string;
+    keywords?: string;
+    match?: string;
+    check?: string;
+    expect?: string;
+    decay?: string;
+    maxFires?: number;
+    recur?: string;
+    agent?: string;
+    dependsOn?: string;
+    source?: string;
+    dryRun?: boolean;
+}
+export declare function coreAdd(db: Database.Database, opts: AddOptions): Reminder;
+export interface CheckOptions {
+    type?: string;
+    text?: string;
+    budget?: number;
+    format?: string;
+    agent?: string;
+    escalate?: boolean;
+    dryRun?: boolean;
+}
+export interface CheckResult {
+    included: Reminder[];
+    overflowCounts: Record<number, number>;
+    totalTriggered: number;
+}
+export declare function coreCheck(db: Database.Database, opts: CheckOptions): CheckResult;
+export interface ListOptions {
+    status?: string;
+    priority?: string;
+    tag?: string;
+    trigger?: string;
+    due?: string;
+    agent?: string;
+    category?: string;
+    limit?: number;
+    all?: boolean;
+}
+export declare function coreList(db: Database.Database, opts: ListOptions): Reminder[];
+export interface SearchOptions {
+    query: string;
+    status?: string;
+    limit?: number;
+}
+export declare function coreSearch(db: Database.Database, opts: SearchOptions): Reminder[];
+export interface CompleteResult {
+    completed: Reminder;
+    nextRecurrence: Reminder | null;
+}
+export declare function coreComplete(db: Database.Database, id: string, notes?: string): CompleteResult;
+export declare function coreSnooze(db: Database.Database, id: string, until?: string, forDuration?: string): Reminder;
+export interface EditOptions {
+    content?: string;
+    context?: string;
+    priority?: number;
+    due?: string;
+    tags?: string;
+    addTags?: string;
+    removeTags?: string;
+    category?: string;
+    decay?: string;
+    maxFires?: number;
+    keywords?: string;
+    agent?: string;
+}
+export declare function coreEdit(db: Database.Database, id: string, opts: EditOptions): Reminder;
+export interface DeleteOptions {
+    id?: string;
+    permanent?: boolean;
+    status?: string;
+    olderThan?: string;
+}
+export interface DeleteResult {
+    count: number;
+    permanent: boolean;
+}
+export declare function coreDelete(db: Database.Database, opts: DeleteOptions): DeleteResult;
+export interface StatsResult {
+    totalActive: number;
+    byPriority: {
+        priority: number;
+        count: number;
+        label: string;
+    }[];
+    overdue: number;
+    snoozed: number;
+    completedWeek: number;
+    expired: number;
+    byTrigger: {
+        type: string;
+        count: number;
+    }[];
+    nextDue: {
+        content: string;
+        triggerAt: string;
+    } | null;
+    lastCreated: string | null;
+    dbSizeBytes: number;
+}
+export declare function coreStats(db: Database.Database): StatsResult;
+export interface GcResult {
+    count: number;
+    reminders: {
+        id: string;
+        status: string;
+        content: string;
+    }[];
+}
+export declare function coreGc(db: Database.Database, olderThan?: number, dryRun?: boolean): GcResult;
+export declare function coreHistory(db: Database.Database, id?: string, limit?: number): HistoryEntry[];
+export declare function coreUndo(db: Database.Database, historyId: number): void;
+export interface ExportData {
+    exported_at: string;
+    schema_version: number;
+    reminder_count: number;
+    reminders: Record<string, unknown>[];
+    history: Record<string, unknown>[];
+}
+export declare function coreExport(db: Database.Database, status?: string): ExportData;
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    historyImported: number;
+}
+export declare function coreImport(db: Database.Database, data: ExportData, merge?: boolean, replace?: boolean, dryRun?: boolean): ImportResult;
+export declare function coreSchema(db: Database.Database): string[];
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

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