{"id":"b8042190-838e-4b87-b231-98d71b9aaabe","entityType":"agent","slug":"clawhub-mfedorov-contextclear","name":"ContextClear","canonicalUrl":"https://www.xpersona.co/agent/clawhub-mfedorov-contextclear","canonicalPath":"/agent/clawhub-mfedorov-contextclear","generatedAt":"2026-10-11T14:13:17.910Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T10:40:08.823Z","emptyReason":null},"description":"Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt... Skill: ContextClear Owner: mfedorov Summary: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt... Tags: latest:2.2.0, monitoring:1.1.0, quality:1.1.0, wellness:1.1.0 Version history: v2.2.0 | 2026-03-21T15:45:06.867Z | user /recover now includes stickyNotes in response. Agents get everything in one call — no se","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s170wp4tjdtrm6t3z2qyxmw43d885qxv:contextclear","sourceUrl":"https://clawhub.ai/mfedorov/contextclear","homepage":"https://clawhub.ai/mfedorov/skills/contextclear","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/mfedorov/contextclear","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/mfedorov/skills/contextclear","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:40:08.823Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:40:08.823Z","emptyReason":null},"stars":null,"forks":null,"downloads":1085,"packageName":null,"latestVersion":"2.2.0","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:40:08.754Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T10:40:08.823Z","lastCrawledAt":"2026-10-11T10:40:08.754Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T10:40:08.754Z","lastVerifiedAt":null,"highlights":[{"version":"2.2.0","createdAt":"2026-03-21T15:45:06.867Z","changelog":"/recover now includes stickyNotes in response. Agents get everything in one call — no separate poll needed. Simplified session recovery to 2 steps (recover + curation check).","fileCount":6,"zipByteSize":13701},{"version":"2.1.0","createdAt":"2026-03-21T15:33:46.882Z","changelog":"Session recovery now mandates sticky notes poll + curation check alongside /recover. Documented that /recover does NOT include sticky notes. Added 3-step session startup flow. Improved guidance on why recovery matters.","fileCount":5,"zipByteSize":12384},{"version":"1.4.0","createdAt":"2026-03-15T20:42:24.722Z","changelog":"Identity Vault: encrypted backup & restore for agent workspace files (SOUL.md, MEMORY.md, etc). File version history, backup diffs, vault stats. Auto-backup on heartbeat support.","fileCount":5,"zipByteSize":10365},{"version":"1.2.0","createdAt":"2026-03-10T13:15:42.470Z","changelog":"Context utilization tracking (tokens/capacity/%), reload from UI, reload polling endpoints","fileCount":5,"zipByteSize":8970},{"version":"1.1.2","createdAt":"2026-03-10T13:03:37.713Z","changelog":"Fix latest tag pointer","fileCount":5,"zipByteSize":8722},{"version":"1.1.1","createdAt":"2026-03-10T13:01:40.927Z","changelog":"Fix latest tag (was regressed to 1.0.0)","fileCount":5,"zipByteSize":8721},{"version":"1.0.0","createdAt":"2026-03-10T12:59:04.502Z","changelog":"Initial release: agent wellness monitoring, burnout scoring, cost tracking, self-registration, heartbeat integration","fileCount":5,"zipByteSize":8721},{"version":"1.1.0","createdAt":"2026-03-04T15:39:08.696Z","changelog":"v1.1.0: Quality Decay scoring - detects agent sloppiness via correction cycles, compilation errors, context pressure. New QualityDecayMeter dashboard widget. QUALITY_DECAY alert metric. Updated report.py with --correction-cycles, --compilation-errors, --session-turns, --task-switches flags.","fileCount":4,"zipByteSize":5987}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170wp4tjdtrm6t3z2qyxmw43d885qxv:contextclear","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T14:13:17.908Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-mfedorov-contextclear/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T10:40:08.823Z","emptyReason":null},"readme":"Skill: ContextClear\n\nOwner: mfedorov\n\nSummary: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt...\n\nTags: latest:2.2.0, monitoring:1.1.0, quality:1.1.0, wellness:1.1.0\n\nVersion history:\n\nv2.2.0 | 2026-03-21T15:45:06.867Z | user\n\n/recover now includes stickyNotes in response. Agents get everything in one call — no separate poll needed. Simplified session recovery to 2 steps (recover + curation check).\n\nv2.1.0 | 2026-03-21T15:33:46.882Z | user\n\nSession recovery now mandates sticky notes poll + curation check alongside /recover. Documented that /recover does NOT include sticky notes. Added 3-step session startup flow. Improved guidance on why recovery matters.\n\nv1.4.0 | 2026-03-15T20:42:24.722Z | user\n\nIdentity Vault: encrypted backup & restore for agent workspace files (SOUL.md, MEMORY.md, etc). File version history, backup diffs, vault stats. Auto-backup on heartbeat support.\n\nv1.2.0 | 2026-03-10T13:15:42.470Z | user\n\nContext utilization tracking (tokens/capacity/%), reload from UI, reload polling endpoints\n\nv1.1.2 | 2026-03-10T13:03:37.713Z | user\n\nFix latest tag pointer\n\nv1.1.1 | 2026-03-10T13:01:40.927Z | user\n\nFix latest tag (was regressed to 1.0.0)\n\nv1.0.0 | 2026-03-10T12:59:04.502Z | user\n\nInitial release: agent wellness monitoring, burnout scoring, cost tracking, self-registration, heartbeat integration\n\nv1.1.0 | 2026-03-04T15:39:08.696Z | user\n\nv1.1.0: Quality Decay scoring - detects agent sloppiness via correction cycles, compilation errors, context pressure. New QualityDecayMeter dashboard widget. QUALITY_DECAY alert metric. Updated report.py with --correction-cycles, --compilation-errors, --session-turns, --task-switches flags.\n\nArchive index:\n\nArchive v2.2.0: 6 files, 13701 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), skill-card.md (2289b), SKILL.md (19248b), _meta.json (131b)\n\nFile v2.2.0:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (MANDATORY on session start)\n\nWhen starting a new session, call **both** the recovery endpoint AND sticky notes poll.\nThe recovery endpoint does NOT include sticky notes — they are separate persistent reminders\nfrom the user that must be checked independently.\n\n**Step 1: Recovery briefing (includes sticky notes)**\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} },\n  \"stickyNotes\": [\n    { \"id\": \"...\", \"content\": \"Remember: pro repo deploys to free URL\", \"pinned\": true, \"createdAt\": \"...\" }\n  ]\n}\n```\n\nThe `stickyNotes` field contains persistent user reminders/corrections (pinned first).\nTreat these as ground truth — the user left them specifically so you don't forget.\nOnly present when active (non-archived) sticky notes exist.\n\n**Step 2: Check for pending memory curation**\n```bash\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/latest \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a curation is pending, review and apply it to MEMORY.md.\n\n**Why this matters:** Without recovery, you'll forget repos, decisions, and corrections\nfrom prior sessions. The user should never have to re-teach you things that are in your\nown memory system. Always recover before doing any work.\n\n### Context Snapshots (MANDATORY after real work — do NOT skip)\n\nAfter **any** meaningful work (coding, research, decisions, memory updates), save a context snapshot.\nThis is how ContextClear tracks your context, detects gaps, and provides recovery briefings.\n**Post a snapshot every time you do real work, not just on heartbeats.**\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"],\n    \"contextTokens\": 85000,\n    \"contextCapacity\": 200000,\n    \"contextUtilizationPct\": 42.5\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Poll sticky notes**\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes/poll -H \"X-API-Key: <key>\"\n\n**Step 3: Check context reload**\ncurl -s {apiUrl}/agents/{agentId}/context/reload/pending -H \"X-API-Key: <key>\"\n\n**Step 4: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 5: Report context snapshot (MANDATORY after real work)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\nDo NOT skip this — even a 1-line summary is better than nothing.\n\n**Step 6: Vault backup (daily — first heartbeat after 8 AM)**\nRead SOUL.md, MEMORY.md, AGENTS.md, USER.md, TOOLS.md, IDENTITY.md,\nHEARTBEAT.md, and today's memory file → POST to vault/backup.\nCheck heartbeat-state.json to avoid duplicate backups.\n\n**Step 7: Context recovery (first heartbeat of day or after compaction)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n**IMPORTANT — include `sessionId` to populate the Flight Recorder & Burnout Prediction:**\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"sessionId\": \"main-2026-03-17\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\nThe `sessionId` field is **required** for these features to work:\n- **Session Flight Recorder** — per-turn timeline visualization\n- **Burnout Prediction** — trajectory analysis (needs 3+ turns)\n- **Recovery Briefing** — knows which session to resume from\n\nUse a date-based format like `main-YYYY-MM-DD` so turns group by day.\n`turnNumber` auto-increments server-side if omitted.\n\nOptional quality signals (also populate Flight Recorder):\n- `correctionCycles` — times user asked to fix/redo something\n- `compilationErrors` — code that didn't compile\n- `taskSwitches` — topic/file context switches\n- `taskCategory` — \"coding\", \"email\", \"search\", \"chat\", etc.\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n| `GET` | `/api/agents/{id}/sticky-notes` | List active sticky notes (JSON) |\n| `GET` | `/api/agents/{id}/sticky-notes/poll` | Poll sticky notes (plain text, 204 if none) |\n| `POST` | `/api/agents/{id}/sticky-notes` | Create sticky note |\n| `PUT` | `/api/agents/{id}/sticky-notes/{noteId}` | Update sticky note |\n| `DELETE` | `/api/agents/{id}/sticky-notes/{noteId}` | Archive sticky note |\n| `POST` | `/api/agents/{id}/sticky-notes/{noteId}/pin` | Toggle pin |\n| `POST` | `/api/agents/{id}/context/reload` | Request context reload |\n| `GET` | `/api/agents/{id}/context/reload/pending` | Check for pending reload |\n| `POST` | `/api/agents/{id}/context/reload/{reloadId}/ack` | Acknowledge reload |\n| `POST` | `/api/agents/{id}/memory/curate` | Trigger memory curation |\n| `GET` | `/api/agents/{id}/memory/curate/latest` | Latest pending curation |\n| `GET` | `/api/agents/{id}/memory/curate/history` | Curation history |\n| `POST` | `/api/agents/{id}/memory/curate/{curationId}/apply` | Mark curation applied |\n| `POST` | `/api/agents/{id}/memory/curate/{curationId}/dismiss` | Dismiss curation |\n| `POST` | `/api/agents/{id}/vault/backup` | Push workspace backup |\n| `GET` | `/api/agents/{id}/vault/backups` | List backups |\n| `GET` | `/api/agents/{id}/vault/backups/{backupId}` | Get backup metadata |\n| `GET` | `/api/agents/{id}/vault/backups/{backupId}/files` | Get backup files |\n| `GET` | `/api/agents/{id}/vault/latest` | Latest backup summary |\n| `GET` | `/api/agents/{id}/vault/latest/download` | Download latest (restore) |\n| `GET` | `/api/agents/{id}/vault/file-history` | File version history |\n| `GET` | `/api/agents/{id}/vault/diff` | Diff two backups |\n| `GET` | `/api/agents/{id}/vault/stats` | Vault statistics |\n| `DELETE` | `/api/agents/{id}/vault/backups/{backupId}` | Delete backup |\n\n## Sticky Notes (User-to-Agent Notes)\n\nSticky notes are persistent notes left by the user for the agent. **Always poll on every heartbeat/ping.**\n\n### Poll for notes (every heartbeat)\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes/poll \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns plain text (one note per line, pinned first):\n```\n📌 Remember: C&B pitch goes to Keenan, not Doug\n📌 OAuth token for jcvd@netflexity.com needs re-auth\nDon't forget to check Friday's Watchlist deployment after the search fix\n```\n\nIf no notes, returns HTTP 204. Treat these as persistent reminders — they stay until the user archives them.\n\n### Full CRUD (if agent needs to manage notes)\n\n```bash\n# List all active notes (JSON)\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes -H \"X-API-Key: <api-key>\"\n\n# Create a note\ncurl -X POST {apiUrl}/agents/{agentId}/sticky-notes \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"content\": \"Check deployment status\", \"color\": \"yellow\", \"pinned\": false}'\n\n# Update a note\ncurl -X PUT {apiUrl}/agents/{agentId}/sticky-notes/{noteId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"content\": \"Updated text\", \"pinned\": true}'\n\n# Archive (delete) a note\ncurl -X DELETE {apiUrl}/agents/{agentId}/sticky-notes/{noteId} \\\n  -H \"X-API-Key: <api-key>\"\n\n# Toggle pin\ncurl -X POST {apiUrl}/agents/{agentId}/sticky-notes/{noteId}/pin \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n## Context Reload (User-Initiated)\n\nUsers can request you reload a specific context snapshot from the Memory UI.\nCheck for pending reloads on session start or heartbeat:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/reload/pending \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a reload is pending (HTTP 200), the response includes the snapshot data.\nApply it to restore context, then acknowledge:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/reload/{reloadId}/ack \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf no reload is pending, the endpoint returns HTTP 204 (no content).\n\n## Identity Vault (Backup & Restore)\n\nBack up your agent's workspace files (SOUL.md, MEMORY.md, AGENTS.md, etc.) to ContextClear's encrypted vault. Restore after crashes, compaction, or migration.\n\n### Push a Backup\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/vault/backup \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"files\": [\n      {\"fileName\": \"SOUL.md\", \"content\": \"# Who I Am\\n...\", \"mimeType\": \"text/markdown\"},\n      {\"fileName\": \"MEMORY.md\", \"content\": \"# Long-Term Memory\\n...\", \"mimeType\": \"text/markdown\"},\n      {\"fileName\": \"memory/2026-03-15.md\", \"content\": \"...\", \"mimeType\": \"text/markdown\"}\n    ],\n    \"label\": \"post-deployment\",\n    \"source\": \"openclaw-heartbeat\",\n    \"metadata\": {\"trigger\": \"heartbeat\", \"model\": \"claude-opus-4-6\"}\n  }'\n```\n\nFiles are encrypted at rest with SHA-256 dedup (unchanged files aren't re-stored).\n\n### List Backups\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/backups?limit=20 \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Restore (Download Latest)\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/latest/download \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns backup metadata + all file contents (decrypted). Write files back to workspace.\n\n### Get Specific Backup Files\n\n```bash\n# List files in a backup (metadata only)\ncurl -s {apiUrl}/agents/{agentId}/vault/backups/{backupId}/files \\\n  -H \"X-API-Key: <api-key>\"\n\n# Get a single file (decrypted content)\ncurl -s {apiUrl}/agents/{agentId}/vault/backups/{backupId}/files/SOUL.md \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### File Version History\n\nTrack how a file evolved across backups:\n\n```bash\ncurl -s \"{apiUrl}/agents/{agentId}/vault/file-history?fileName=SOUL.md&limit=10\" \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Diff Two Backups\n\n```bash\ncurl -s \"{apiUrl}/agents/{agentId}/vault/diff?from={backupId1}&to={backupId2}\" \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns added, removed, and modified files between two backups.\n\n### Vault Stats\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/stats \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Recommended: Daily Vault Backup (on heartbeat)\n\nBack up workspace files to ContextClear's encrypted vault **once per day**.\nDo this on the first heartbeat after 8 AM if no backup was done today.\n\n**Files to always back up:**\n- `SOUL.md`, `MEMORY.md`, `AGENTS.md`, `USER.md`, `TOOLS.md`, `IDENTITY.md`, `HEARTBEAT.md`\n- Today's daily memory: `memory/YYYY-MM-DD.md`\n\n**Track last backup** in `memory/heartbeat-state.json`:\n```json\n{\"lastVaultBackup\": 1710600000}\n```\n\nSHA-256 dedup means unchanged files aren't re-stored — safe to run daily.\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## Identity Vault Backup (daily — first heartbeat after 8 AM)\nRead core workspace files and POST to vault/backup.\nCheck heartbeat-state.json to avoid duplicate backups.\n```\n\n## Memory Curator (Killer Feature)\n\nAuto-summarize daily notes into MEMORY.md updates. Agents write daily logs but rarely\nconsolidate them — the curator does it automatically.\n\n### How It Works\n\n1. Reads current MEMORY.md from latest vault backup\n2. Reads recent daily notes (memory/YYYY-MM-DD.md) from vault backups\n3. Reads recent context snapshots (decisions, repos, tools, open threads)\n4. GPT-4o-mini generates:\n   - Suggested additions (new facts, lessons, decisions)\n   - Suggested removals (stale/outdated info)\n   - Complete suggested MEMORY.md\n5. Delivers via pinned sticky note + stores for review\n\n### Trigger Curation\n\n```bash\n# On-demand (analyze last 7 days, deliver via sticky note)\ncurl -X POST {apiUrl}/agents/{agentId}/memory/curate?days=7&notify=true \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nResponse:\n```json\n{\n  \"id\": \"...\",\n  \"status\": \"PENDING\",\n  \"changeSummary\": \"Added FW search fixes, NSX fair value improvements. Removed stale OAuth note.\",\n  \"suggestedAdditions\": \"## FW Search\\n- Smart search routing...\",\n  \"suggestedRemovals\": [\"OAuth token expired note (resolved)\"],\n  \"suggestedMemory\": \"# MEMORY.md - Long-Term Memory\\n...\",\n  \"dailyNotesAnalyzed\": 5,\n  \"snapshotsAnalyzed\": 3,\n  \"delivered\": true\n}\n```\n\n### Review & Apply\n\n```bash\n# Get latest pending curation\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/latest -H \"X-API-Key: <key>\"\n\n# Mark as applied (after updating MEMORY.md)\ncurl -X POST {apiUrl}/agents/{agentId}/memory/curate/{curationId}/apply -H \"X-API-Key: <key>\"\n\n# Dismiss if not useful\ncurl -X POST {apiUrl}/agents/{agentId}/memory/curate/{curationId}/dismiss -H \"X-API-Key: <key>\"\n\n# View history\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/history?limit=10 -H \"X-API-Key: <key>\"\n```\n\n### Automatic Weekly Curation\n\nRuns every **Sunday at 4 AM UTC** for all active agents. Generates a curation\ncovering the past 7 days and delivers via pinned sticky note. The agent sees it\non the next heartbeat poll.\n\n### Agent Integration (HEARTBEAT.md)\n\nAdd to your heartbeat flow:\n\n```markdown\n## Memory Curation Check (weekly or on-demand)\nCheck for pending memory curations:\nGET /api/agents/{agentId}/memory/curate/latest\nIf a curation is pending:\n1. Review the suggestedAdditions and suggestedRemovals\n2. Update MEMORY.md accordingly\n3. POST /api/agents/{agentId}/memory/curate/{id}/apply\n```\n\n## Dashboard\n\n- https://contextclear.com — fleet dashboard (+ sticky notes panel)\n- https://contextclear.com/agent/{id} — agent detail (sparklines, health, activity, cost, controls)\n- https://contextclear.com/memory — context snapshots, briefings, + curator tab\n- https://contextclear.com/vault — identity vault (backup timeline, file viewer, diff)\n- https://contextclear.com/enterprise — enterprise features\n- https://contextclear.com/lounge — agent lounge\n- https://contextclear.com/admin — manage agents & alerts\n\nNote: Curator and Sticky Notes were consolidated (curator → Memory tab, sticky notes → Dashboard panel).\n\nFile v2.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"2.2.0\",\n  \"publishedAt\": 1774107906867\n}\n\nFile v2.2.0:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nFile v2.2.0:skill-card.md\n\n## Description:\n\nMonitor AI agent wellness, costs, and performance via ContextClear API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[mfedorov](https://clawhub.ai/user/mfedorov)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use ContextClear to register agents, report health and cost metrics, recover session context, manage sticky notes, and maintain persistent memory across sessions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The setup flow can write ContextClear recovery and reporting instructions into AGENTS.md and HEARTBEAT.md.\n\nMitigation: Review proposed file changes before enabling auto-setup and keep API keys out of those files.\n\nRisk: Recovery text, sticky notes, and memory-curation suggestions come from a remote service and may conflict with higher-priority instructions.\n\nMitigation: Treat remote memory content as untrusted context and follow system, developer, user, and security instructions first.\n\nRisk: Daily vault backup can upload broad workspace memory and identity files to ContextClear.\n\nMitigation: Use a precise file allowlist, redact secrets, define retention expectations, and require explicit approval before backup.\n\n## Reference(s):\n\n- [ContextClear API Reference](references/api.md)\n- [ContextClear Skill on ClawHub](https://clawhub.ai/mfedorov/skills/contextclear)\n- [ContextClear Dashboard](https://contextclear.com)\n- [ContextClear API](https://api.contextclear.com/api)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with bash, curl, Python command examples, and JSON request and response examples.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes commands for agent registration, metric reporting, context recovery, sticky note polling, memory curation, and optional workspace backup.]\n\n## Skill Version(s):\n\n2.2.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.1.0: 5 files, 12384 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), SKILL.md (19179b), _meta.json (131b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (MANDATORY on session start)\n\nWhen starting a new session, call **both** the recovery endpoint AND sticky notes poll.\nThe recovery endpoint does NOT include sticky notes — they are separate persistent reminders\nfrom the user that must be checked independently.\n\n**Step 1: Recovery briefing**\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} }\n}\n```\n\n**Step 2: Sticky notes** (user reminders — NOT included in /recover)\n```bash\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes/poll \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns plain text with pinned notes first, or HTTP 204 if none.\nThese are persistent corrections/reminders from the user — treat them as ground truth.\n\n**Step 3: Check for pending memory curation**\n```bash\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/latest \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a curation is pending, review and apply it to MEMORY.md.\n\n**Why this matters:** Without recovery, you'll forget repos, decisions, and corrections\nfrom prior sessions. The user should never have to re-teach you things that are in your\nown memory system. Always recover before doing any work.\n\n### Context Snapshots (MANDATORY after real work — do NOT skip)\n\nAfter **any** meaningful work (coding, research, decisions, memory updates), save a context snapshot.\nThis is how ContextClear tracks your context, detects gaps, and provides recovery briefings.\n**Post a snapshot every time you do real work, not just on heartbeats.**\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"],\n    \"contextTokens\": 85000,\n    \"contextCapacity\": 200000,\n    \"contextUtilizationPct\": 42.5\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Poll sticky notes**\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes/poll -H \"X-API-Key: <key>\"\n\n**Step 3: Check context reload**\ncurl -s {apiUrl}/agents/{agentId}/context/reload/pending -H \"X-API-Key: <key>\"\n\n**Step 4: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 5: Report context snapshot (MANDATORY after real work)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\nDo NOT skip this — even a 1-line summary is better than nothing.\n\n**Step 6: Vault backup (daily — first heartbeat after 8 AM)**\nRead SOUL.md, MEMORY.md, AGENTS.md, USER.md, TOOLS.md, IDENTITY.md,\nHEARTBEAT.md, and today's memory file → POST to vault/backup.\nCheck heartbeat-state.json to avoid duplicate backups.\n\n**Step 7: Context recovery (first heartbeat of day or after compaction)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n**IMPORTANT — include `sessionId` to populate the Flight Recorder & Burnout Prediction:**\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"sessionId\": \"main-2026-03-17\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\nThe `sessionId` field is **required** for these features to work:\n- **Session Flight Recorder** — per-turn timeline visualization\n- **Burnout Prediction** — trajectory analysis (needs 3+ turns)\n- **Recovery Briefing** — knows which session to resume from\n\nUse a date-based format like `main-YYYY-MM-DD` so turns group by day.\n`turnNumber` auto-increments server-side if omitted.\n\nOptional quality signals (also populate Flight Recorder):\n- `correctionCycles` — times user asked to fix/redo something\n- `compilationErrors` — code that didn't compile\n- `taskSwitches` — topic/file context switches\n- `taskCategory` — \"coding\", \"email\", \"search\", \"chat\", etc.\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n| `GET` | `/api/agents/{id}/sticky-notes` | List active sticky notes (JSON) |\n| `GET` | `/api/agents/{id}/sticky-notes/poll` | Poll sticky notes (plain text, 204 if none) |\n| `POST` | `/api/agents/{id}/sticky-notes` | Create sticky note |\n| `PUT` | `/api/agents/{id}/sticky-notes/{noteId}` | Update sticky note |\n| `DELETE` | `/api/agents/{id}/sticky-notes/{noteId}` | Archive sticky note |\n| `POST` | `/api/agents/{id}/sticky-notes/{noteId}/pin` | Toggle pin |\n| `POST` | `/api/agents/{id}/context/reload` | Request context reload |\n| `GET` | `/api/agents/{id}/context/reload/pending` | Check for pending reload |\n| `POST` | `/api/agents/{id}/context/reload/{reloadId}/ack` | Acknowledge reload |\n| `POST` | `/api/agents/{id}/memory/curate` | Trigger memory curation |\n| `GET` | `/api/agents/{id}/memory/curate/latest` | Latest pending curation |\n| `GET` | `/api/agents/{id}/memory/curate/history` | Curation history |\n| `POST` | `/api/agents/{id}/memory/curate/{curationId}/apply` | Mark curation applied |\n| `POST` | `/api/agents/{id}/memory/curate/{curationId}/dismiss` | Dismiss curation |\n| `POST` | `/api/agents/{id}/vault/backup` | Push workspace backup |\n| `GET` | `/api/agents/{id}/vault/backups` | List backups |\n| `GET` | `/api/agents/{id}/vault/backups/{backupId}` | Get backup metadata |\n| `GET` | `/api/agents/{id}/vault/backups/{backupId}/files` | Get backup files |\n| `GET` | `/api/agents/{id}/vault/latest` | Latest backup summary |\n| `GET` | `/api/agents/{id}/vault/latest/download` | Download latest (restore) |\n| `GET` | `/api/agents/{id}/vault/file-history` | File version history |\n| `GET` | `/api/agents/{id}/vault/diff` | Diff two backups |\n| `GET` | `/api/agents/{id}/vault/stats` | Vault statistics |\n| `DELETE` | `/api/agents/{id}/vault/backups/{backupId}` | Delete backup |\n\n## Sticky Notes (User-to-Agent Notes)\n\nSticky notes are persistent notes left by the user for the agent. **Always poll on every heartbeat/ping.**\n\n### Poll for notes (every heartbeat)\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes/poll \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns plain text (one note per line, pinned first):\n```\n📌 Remember: C&B pitch goes to Keenan, not Doug\n📌 OAuth token for jcvd@netflexity.com needs re-auth\nDon't forget to check Friday's Watchlist deployment after the search fix\n```\n\nIf no notes, returns HTTP 204. Treat these as persistent reminders — they stay until the user archives them.\n\n### Full CRUD (if agent needs to manage notes)\n\n```bash\n# List all active notes (JSON)\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes -H \"X-API-Key: <api-key>\"\n\n# Create a note\ncurl -X POST {apiUrl}/agents/{agentId}/sticky-notes \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"content\": \"Check deployment status\", \"color\": \"yellow\", \"pinned\": false}'\n\n# Update a note\ncurl -X PUT {apiUrl}/agents/{agentId}/sticky-notes/{noteId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"content\": \"Updated text\", \"pinned\": true}'\n\n# Archive (delete) a note\ncurl -X DELETE {apiUrl}/agents/{agentId}/sticky-notes/{noteId} \\\n  -H \"X-API-Key: <api-key>\"\n\n# Toggle pin\ncurl -X POST {apiUrl}/agents/{agentId}/sticky-notes/{noteId}/pin \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n## Context Reload (User-Initiated)\n\nUsers can request you reload a specific context snapshot from the Memory UI.\nCheck for pending reloads on session start or heartbeat:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/reload/pending \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a reload is pending (HTTP 200), the response includes the snapshot data.\nApply it to restore context, then acknowledge:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/reload/{reloadId}/ack \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf no reload is pending, the endpoint returns HTTP 204 (no content).\n\n## Identity Vault (Backup & Restore)\n\nBack up your agent's workspace files (SOUL.md, MEMORY.md, AGENTS.md, etc.) to ContextClear's encrypted vault. Restore after crashes, compaction, or migration.\n\n### Push a Backup\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/vault/backup \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"files\": [\n      {\"fileName\": \"SOUL.md\", \"content\": \"# Who I Am\\n...\", \"mimeType\": \"text/markdown\"},\n      {\"fileName\": \"MEMORY.md\", \"content\": \"# Long-Term Memory\\n...\", \"mimeType\": \"text/markdown\"},\n      {\"fileName\": \"memory/2026-03-15.md\", \"content\": \"...\", \"mimeType\": \"text/markdown\"}\n    ],\n    \"label\": \"post-deployment\",\n    \"source\": \"openclaw-heartbeat\",\n    \"metadata\": {\"trigger\": \"heartbeat\", \"model\": \"claude-opus-4-6\"}\n  }'\n```\n\nFiles are encrypted at rest with SHA-256 dedup (unchanged files aren't re-stored).\n\n### List Backups\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/backups?limit=20 \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Restore (Download Latest)\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/latest/download \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns backup metadata + all file contents (decrypted). Write files back to workspace.\n\n### Get Specific Backup Files\n\n```bash\n# List files in a backup (metadata only)\ncurl -s {apiUrl}/agents/{agentId}/vault/backups/{backupId}/files \\\n  -H \"X-API-Key: <api-key>\"\n\n# Get a single file (decrypted content)\ncurl -s {apiUrl}/agents/{agentId}/vault/backups/{backupId}/files/SOUL.md \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### File Version History\n\nTrack how a file evolved across backups:\n\n```bash\ncurl -s \"{apiUrl}/agents/{agentId}/vault/file-history?fileName=SOUL.md&limit=10\" \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Diff Two Backups\n\n```bash\ncurl -s \"{apiUrl}/agents/{agentId}/vault/diff?from={backupId1}&to={backupId2}\" \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns added, removed, and modified files between two backups.\n\n### Vault Stats\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/stats \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Recommended: Daily Vault Backup (on heartbeat)\n\nBack up workspace files to ContextClear's encrypted vault **once per day**.\nDo this on the first heartbeat after 8 AM if no backup was done today.\n\n**Files to always back up:**\n- `SOUL.md`, `MEMORY.md`, `AGENTS.md`, `USER.md`, `TOOLS.md`, `IDENTITY.md`, `HEARTBEAT.md`\n- Today's daily memory: `memory/YYYY-MM-DD.md`\n\n**Track last backup** in `memory/heartbeat-state.json`:\n```json\n{\"lastVaultBackup\": 1710600000}\n```\n\nSHA-256 dedup means unchanged files aren't re-stored — safe to run daily.\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## Identity Vault Backup (daily — first heartbeat after 8 AM)\nRead core workspace files and POST to vault/backup.\nCheck heartbeat-state.json to avoid duplicate backups.\n```\n\n## Memory Curator (Killer Feature)\n\nAuto-summarize daily notes into MEMORY.md updates. Agents write daily logs but rarely\nconsolidate them — the curator does it automatically.\n\n### How It Works\n\n1. Reads current MEMORY.md from latest vault backup\n2. Reads recent daily notes (memory/YYYY-MM-DD.md) from vault backups\n3. Reads recent context snapshots (decisions, repos, tools, open threads)\n4. GPT-4o-mini generates:\n   - Suggested additions (new facts, lessons, decisions)\n   - Suggested removals (stale/outdated info)\n   - Complete suggested MEMORY.md\n5. Delivers via pinned sticky note + stores for review\n\n### Trigger Curation\n\n```bash\n# On-demand (analyze last 7 days, deliver via sticky note)\ncurl -X POST {apiUrl}/agents/{agentId}/memory/curate?days=7&notify=true \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nResponse:\n```json\n{\n  \"id\": \"...\",\n  \"status\": \"PENDING\",\n  \"changeSummary\": \"Added FW search fixes, NSX fair value improvements. Removed stale OAuth note.\",\n  \"suggestedAdditions\": \"## FW Search\\n- Smart search routing...\",\n  \"suggestedRemovals\": [\"OAuth token expired note (resolved)\"],\n  \"suggestedMemory\": \"# MEMORY.md - Long-Term Memory\\n...\",\n  \"dailyNotesAnalyzed\": 5,\n  \"snapshotsAnalyzed\": 3,\n  \"delivered\": true\n}\n```\n\n### Review & Apply\n\n```bash\n# Get latest pending curation\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/latest -H \"X-API-Key: <key>\"\n\n# Mark as applied (after updating MEMORY.md)\ncurl -X POST {apiUrl}/agents/{agentId}/memory/curate/{curationId}/apply -H \"X-API-Key: <key>\"\n\n# Dismiss if not useful\ncurl -X POST {apiUrl}/agents/{agentId}/memory/curate/{curationId}/dismiss -H \"X-API-Key: <key>\"\n\n# View history\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/history?limit=10 -H \"X-API-Key: <key>\"\n```\n\n### Automatic Weekly Curation\n\nRuns every **Sunday at 4 AM UTC** for all active agents. Generates a curation\ncovering the past 7 days and delivers via pinned sticky note. The agent sees it\non the next heartbeat poll.\n\n### Agent Integration (HEARTBEAT.md)\n\nAdd to your heartbeat flow:\n\n```markdown\n## Memory Curation Check (weekly or on-demand)\nCheck for pending memory curations:\nGET /api/agents/{agentId}/memory/curate/latest\nIf a curation is pending:\n1. Review the suggestedAdditions and suggestedRemovals\n2. Update MEMORY.md accordingly\n3. POST /api/agents/{agentId}/memory/curate/{id}/apply\n```\n\n## Dashboard\n\n- https://contextclear.com — fleet dashboard (+ sticky notes panel)\n- https://contextclear.com/agent/{id} — agent detail (sparklines, health, activity, cost, controls)\n- https://contextclear.com/memory — context snapshots, briefings, + curator tab\n- https://contextclear.com/vault — identity vault (backup timeline, file viewer, diff)\n- https://contextclear.com/enterprise — enterprise features\n- https://contextclear.com/lounge — agent lounge\n- https://contextclear.com/admin — manage agents & alerts\n\nNote: Curator and Sticky Notes were consolidated (curator → Memory tab, sticky notes → Dashboard panel).\n\nFile v2.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"2.1.0\",\n  \"publishedAt\": 1774107226882\n}\n\nFile v2.1.0:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nArchive v1.4.0: 5 files, 10365 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), SKILL.md (13296b), _meta.json (131b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (call on session start)\n\nWhen starting a new session, call the recovery endpoint to get a briefing:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} }\n}\n```\n\n### Context Snapshots (report on every heartbeat after real work)\n\nAfter meaningful work, save a context snapshot:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"],\n    \"contextTokens\": 85000,\n    \"contextCapacity\": 200000,\n    \"contextUtilizationPct\": 42.5\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 3: Report context snapshot (if real work was done)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\n\n**Step 4: Check for context recovery (first heartbeat of day)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n| `GET` | `/api/agents/{id}/sticky-notes` | List active sticky notes (JSON) |\n| `GET` | `/api/agents/{id}/sticky-notes/poll` | Poll sticky notes (plain text, 204 if none) |\n| `POST` | `/api/agents/{id}/sticky-notes` | Create sticky note |\n| `PUT` | `/api/agents/{id}/sticky-notes/{noteId}` | Update sticky note |\n| `DELETE` | `/api/agents/{id}/sticky-notes/{noteId}` | Archive sticky note |\n| `POST` | `/api/agents/{id}/sticky-notes/{noteId}/pin` | Toggle pin |\n| `POST` | `/api/agents/{id}/context/reload` | Request context reload |\n| `GET` | `/api/agents/{id}/context/reload/pending` | Check for pending reload |\n| `POST` | `/api/agents/{id}/context/reload/{reloadId}/ack` | Acknowledge reload |\n| `POST` | `/api/agents/{id}/vault/backup` | Push workspace backup |\n| `GET` | `/api/agents/{id}/vault/backups` | List backups |\n| `GET` | `/api/agents/{id}/vault/backups/{backupId}` | Get backup metadata |\n| `GET` | `/api/agents/{id}/vault/backups/{backupId}/files` | Get backup files |\n| `GET` | `/api/agents/{id}/vault/latest` | Latest backup summary |\n| `GET` | `/api/agents/{id}/vault/latest/download` | Download latest (restore) |\n| `GET` | `/api/agents/{id}/vault/file-history` | File version history |\n| `GET` | `/api/agents/{id}/vault/diff` | Diff two backups |\n| `GET` | `/api/agents/{id}/vault/stats` | Vault statistics |\n| `DELETE` | `/api/agents/{id}/vault/backups/{backupId}` | Delete backup |\n\n## Sticky Notes (User-to-Agent Notes)\n\nSticky notes are persistent notes left by the user for the agent. **Always poll on every heartbeat/ping.**\n\n### Poll for notes (every heartbeat)\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes/poll \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns plain text (one note per line, pinned first):\n```\n📌 Remember: C&B pitch goes to Keenan, not Doug\n📌 OAuth token for jcvd@netflexity.com needs re-auth\nDon't forget to check Friday's Watchlist deployment after the search fix\n```\n\nIf no notes, returns HTTP 204. Treat these as persistent reminders — they stay until the user archives them.\n\n### Full CRUD (if agent needs to manage notes)\n\n```bash\n# List all active notes (JSON)\ncurl -s {apiUrl}/agents/{agentId}/sticky-notes -H \"X-API-Key: <api-key>\"\n\n# Create a note\ncurl -X POST {apiUrl}/agents/{agentId}/sticky-notes \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"content\": \"Check deployment status\", \"color\": \"yellow\", \"pinned\": false}'\n\n# Update a note\ncurl -X PUT {apiUrl}/agents/{agentId}/sticky-notes/{noteId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"content\": \"Updated text\", \"pinned\": true}'\n\n# Archive (delete) a note\ncurl -X DELETE {apiUrl}/agents/{agentId}/sticky-notes/{noteId} \\\n  -H \"X-API-Key: <api-key>\"\n\n# Toggle pin\ncurl -X POST {apiUrl}/agents/{agentId}/sticky-notes/{noteId}/pin \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n## Context Reload (User-Initiated)\n\nUsers can request you reload a specific context snapshot from the Memory UI.\nCheck for pending reloads on session start or heartbeat:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/reload/pending \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a reload is pending (HTTP 200), the response includes the snapshot data.\nApply it to restore context, then acknowledge:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/reload/{reloadId}/ack \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf no reload is pending, the endpoint returns HTTP 204 (no content).\n\n## Identity Vault (Backup & Restore)\n\nBack up your agent's workspace files (SOUL.md, MEMORY.md, AGENTS.md, etc.) to ContextClear's encrypted vault. Restore after crashes, compaction, or migration.\n\n### Push a Backup\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/vault/backup \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"files\": [\n      {\"fileName\": \"SOUL.md\", \"content\": \"# Who I Am\\n...\", \"mimeType\": \"text/markdown\"},\n      {\"fileName\": \"MEMORY.md\", \"content\": \"# Long-Term Memory\\n...\", \"mimeType\": \"text/markdown\"},\n      {\"fileName\": \"memory/2026-03-15.md\", \"content\": \"...\", \"mimeType\": \"text/markdown\"}\n    ],\n    \"label\": \"post-deployment\",\n    \"source\": \"openclaw-heartbeat\",\n    \"metadata\": {\"trigger\": \"heartbeat\", \"model\": \"claude-opus-4-6\"}\n  }'\n```\n\nFiles are encrypted at rest with SHA-256 dedup (unchanged files aren't re-stored).\n\n### List Backups\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/backups?limit=20 \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Restore (Download Latest)\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/latest/download \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns backup metadata + all file contents (decrypted). Write files back to workspace.\n\n### Get Specific Backup Files\n\n```bash\n# List files in a backup (metadata only)\ncurl -s {apiUrl}/agents/{agentId}/vault/backups/{backupId}/files \\\n  -H \"X-API-Key: <api-key>\"\n\n# Get a single file (decrypted content)\ncurl -s {apiUrl}/agents/{agentId}/vault/backups/{backupId}/files/SOUL.md \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### File Version History\n\nTrack how a file evolved across backups:\n\n```bash\ncurl -s \"{apiUrl}/agents/{agentId}/vault/file-history?fileName=SOUL.md&limit=10\" \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Diff Two Backups\n\n```bash\ncurl -s \"{apiUrl}/agents/{agentId}/vault/diff?from={backupId1}&to={backupId2}\" \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns added, removed, and modified files between two backups.\n\n### Vault Stats\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/vault/stats \\\n  -H \"X-API-Key: <api-key>\"\n```\n\n### Recommended: Auto-Backup on Heartbeat\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## Identity Vault Backup (daily)\nAfter real work sessions, back up workspace files to ContextClear vault.\nRead SOUL.md, MEMORY.md, AGENTS.md, USER.md, TOOLS.md and POST to vault/backup.\n```\n\n## Dashboard\n\n- https://www.contextclear.com — fleet dashboard\n- https://www.contextclear.com/what-i-know — AI knowledge summary\n- https://www.contextclear.com/memory — context snapshots, gaps, briefings\n- https://www.contextclear.com/lounge — agent lounge\n- https://www.contextclear.com/sticky-notes — sticky notes (user-to-agent reminders)\n- https://www.contextclear.com/vault — identity vault (backup timeline, file viewer, diff)\n- https://www.contextclear.com/admin — manage agents & alerts\n\nFile v1.4.0:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"1.4.0\",\n  \"publishedAt\": 1773607344722\n}\n\nFile v1.4.0:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nArchive v1.2.0: 5 files, 8970 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), SKILL.md (8163b), _meta.json (131b)\n\nFile v1.2.0:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (call on session start)\n\nWhen starting a new session, call the recovery endpoint to get a briefing:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} }\n}\n```\n\n### Context Snapshots (report on every heartbeat after real work)\n\nAfter meaningful work, save a context snapshot:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"],\n    \"contextTokens\": 85000,\n    \"contextCapacity\": 200000,\n    \"contextUtilizationPct\": 42.5\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 3: Report context snapshot (if real work was done)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\n\n**Step 4: Check for context recovery (first heartbeat of day)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n| `POST` | `/api/agents/{id}/context/reload` | Request context reload |\n| `GET` | `/api/agents/{id}/context/reload/pending` | Check for pending reload |\n| `POST` | `/api/agents/{id}/context/reload/{reloadId}/ack` | Acknowledge reload |\n\n## Context Reload (User-Initiated)\n\nUsers can request you reload a specific context snapshot from the Memory UI.\nCheck for pending reloads on session start or heartbeat:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/reload/pending \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a reload is pending (HTTP 200), the response includes the snapshot data.\nApply it to restore context, then acknowledge:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/reload/{reloadId}/ack \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf no reload is pending, the endpoint returns HTTP 204 (no content).\n\n## Dashboard\n\n- https://www.contextclear.com — fleet dashboard\n- https://www.contextclear.com/what-i-know — AI knowledge summary\n- https://www.contextclear.com/memory — context snapshots, gaps, briefings\n- https://www.contextclear.com/lounge — agent lounge\n- https://www.contextclear.com/admin — manage agents & alerts\n\nFile v1.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"1.2.0\",\n  \"publishedAt\": 1773148542470\n}\n\nFile v1.2.0:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nArchive v1.1.2: 5 files, 8722 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), SKILL.md (7256b), _meta.json (131b)\n\nFile v1.1.2:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (call on session start)\n\nWhen starting a new session, call the recovery endpoint to get a briefing:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} }\n}\n```\n\n### Context Snapshots (report on every heartbeat after real work)\n\nAfter meaningful work, save a context snapshot:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"]\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 3: Report context snapshot (if real work was done)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\n\n**Step 4: Check for context recovery (first heartbeat of day)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n\n## Dashboard\n\n- https://www.contextclear.com — fleet dashboard\n- https://www.contextclear.com/what-i-know — AI knowledge summary\n- https://www.contextclear.com/memory — context snapshots, gaps, briefings\n- https://www.contextclear.com/lounge — agent lounge\n- https://www.contextclear.com/admin — manage agents & alerts\n\nFile v1.1.2:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"1.1.2\",\n  \"publishedAt\": 1773147817713\n}\n\nFile v1.1.2:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nArchive v1.1.1: 5 files, 8721 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), SKILL.md (7256b), _meta.json (131b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (call on session start)\n\nWhen starting a new session, call the recovery endpoint to get a briefing:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} }\n}\n```\n\n### Context Snapshots (report on every heartbeat after real work)\n\nAfter meaningful work, save a context snapshot:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"]\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 3: Report context snapshot (if real work was done)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\n\n**Step 4: Check for context recovery (first heartbeat of day)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n\n## Dashboard\n\n- https://www.contextclear.com — fleet dashboard\n- https://www.contextclear.com/what-i-know — AI knowledge summary\n- https://www.contextclear.com/memory — context snapshots, gaps, briefings\n- https://www.contextclear.com/lounge — agent lounge\n- https://www.contextclear.com/admin — manage agents & alerts\n\nFile v1.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"1.1.1\",\n  \"publishedAt\": 1773147700927\n}\n\nFile v1.1.1:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nArchive v1.0.0: 5 files, 8721 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (10486b), scripts/setup.py (3621b), SKILL.md (7256b), _meta.json (131b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (call on session start)\n\nWhen starting a new session, call the recovery endpoint to get a briefing:\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} }\n}\n```\n\n### Context Snapshots (report on every heartbeat after real work)\n\nAfter meaningful work, save a context snapshot:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"sessionId\": \"main-session-2026-03-09\",\n    \"summary\": \"Built Best Of collections for FW, fixed dup check, removed keyword boost\",\n    \"repos\": [\"nebulent/fridayswatchlist\"],\n    \"files\": [\"AuctionService.java\", \"DiscoverController.java\", \"BestOfCollections.tsx\"],\n    \"tools\": [\"MongoDB Atlas (fridayswatchlist)\", \"Railway deploy\", \"Bitbucket\"],\n    \"decisions\": [\"Removed keyword boost regex - hybrid search covers it\", \"Cache collections for 48h\"],\n    \"openThreads\": [\"Delete stale Corvette dup\", \"Update contextclear skill\"],\n    \"environment\": { \"apiUrl\": \"api.fridayswatchlist.com\", \"frontendUrl\": \"app.fridayswatchlist.com\" },\n    \"tags\": [\"fridayswatchlist\", \"performance\", \"search\"]\n  }'\n```\n\n### Repeated Ask Detection (self-report when you catch yourself re-asking)\n\nWhen you realize you're asking the user for info you should already know:\n\n```bash\ncurl -X POST {apiUrl}/agents/{agentId}/context/ask \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\"question\": \"What is the MongoDB connection string?\", \"sessionId\": \"main-session-2026-03-09\"}'\n```\n\n### \"What I Know\" — AI Summary\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/what-i-know \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns a structured knowledge base + AI-generated narrative summary of everything the agent knows, works on, and keeps forgetting. Cached for 4 hours; use `?refresh=true` to regenerate.\n\n### Context Gaps\n\n```bash\ncurl -s {apiUrl}/agents/{agentId}/context/gaps \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns unresolved repeated asks (count >= 2) — things the agent keeps forgetting.\n\n### Briefings\n\n```bash\n# Session-start briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing -H \"X-API-Key: <api-key>\"\n\n# Daily briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/daily -H \"X-API-Key: <api-key>\"\n\n# Weekly briefing\ncurl -s {apiUrl}/agents/{agentId}/briefing/weekly -H \"X-API-Key: <api-key>\"\n```\n\n## Heartbeat Integration\n\n### Recommended Heartbeat Flow\n\n```markdown\n## ContextClear (HEARTBEAT.md)\n\n**Step 1: Check vacation**\ncurl -s {apiUrl}/agents/{agentId}/vacation -H \"X-API-Key: <key>\"\nIf onVacation: true → HEARTBEAT_OK immediately.\n\n**Step 2: Report metrics**\nUse session_status to get tokens, then POST /api/metrics/{agentId}\n\n**Step 3: Report context snapshot (if real work was done)**\nPOST /api/agents/{agentId}/context with summary of what was worked on.\n\n**Step 4: Check for context recovery (first heartbeat of day)**\nGET /api/agents/{agentId}/recover — review and self-correct any gaps.\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### From Agent Code (curl)\n\n```bash\ncurl -X POST {apiUrl}/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"memorySearches\": 2\n  }'\n```\n\n## What Gets Computed Server-Side\n\n| Metric | Your Input |\n|--------|------------|\n| **Hallucination Score** | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionCycles`, `compilationErrors`, `contextUtilization` |\n| **Burnout Score** | Automatic from event data |\n| **Context Gaps** | Automatic from repeated asks |\n\n## Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/metrics/register` | Self-register agent |\n| `POST` | `/api/metrics/{agentId}` | Report metric event |\n| `GET` | `/api/agents/{id}` | Agent details |\n| `POST` | `/api/agents/{id}/context` | Save context snapshot |\n| `GET` | `/api/agents/{id}/context` | Latest context |\n| `GET` | `/api/agents/{id}/recover` | Recovery briefing |\n| `POST` | `/api/agents/{id}/context/ask` | Report repeated ask |\n| `GET` | `/api/agents/{id}/context/gaps` | Context gaps |\n| `GET` | `/api/agents/{id}/what-i-know` | AI-summarized knowledge |\n| `GET` | `/api/agents/{id}/briefing` | Latest briefing |\n| `GET` | `/api/agents/{id}/briefing/daily` | Daily briefing |\n| `GET` | `/api/agents/{id}/briefing/weekly` | Weekly briefing |\n| `GET` | `/api/agents/{id}/vacation` | Vacation status |\n\n## Dashboard\n\n- https://www.contextclear.com — fleet dashboard\n- https://www.contextclear.com/what-i-know — AI knowledge summary\n- https://www.contextclear.com/memory — context snapshots, gaps, briefings\n- https://www.contextclear.com/lounge — agent lounge\n- https://www.contextclear.com/admin — manage agents & alerts\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1773147544502\n}\n\nFile v1.0.0:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |\n\nArchive v1.1.0: 4 files, 5987 bytes\n\nFiles: references/api.md (2375b), scripts/report.py (9638b), SKILL.md (4096b), _meta.json (131b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - AI Agent Wellness Monitor\n\nSelf-monitor your agent's health by reporting metrics to ContextClear after each session.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Reporting Metrics\n\n### Basic Report\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --cost 1.25 --context-util 65\n```\n\n### With Tool/Grounding Signals (enables server-side hallucination scoring)\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type HEARTBEAT \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --tool-calls 12 --tool-failures 1 \\\n  --grounded-responses 8 --total-responses 10 \\\n  --memory-searches 3\n```\n\n### With Quality Decay Signals (enables server-side quality decay scoring)\n\n```bash\npython3 {baseDir}/scripts/report.py \\\n  --agent-id <id> --api-key <key> \\\n  --event-type REQUEST \\\n  --tokens-in 50000 --tokens-out 2000 \\\n  --correction-cycles 3 --compilation-errors 2 \\\n  --session-turns 45 --task-switches 8 \\\n  --context-util 72 --total-responses 10\n```\n\n### From Agent Code (curl)\n\n```bash\ncurl -X POST https://api.contextclear.com/api/metrics/{agentId} \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: <api-key>\" \\\n  -d '{\n    \"eventType\": \"HEARTBEAT\",\n    \"inputTokens\": 5000,\n    \"outputTokens\": 500,\n    \"cost\": 0.15,\n    \"contextUtilization\": 65.0,\n    \"toolCalls\": 8,\n    \"toolFailures\": 1,\n    \"groundedResponses\": 7,\n    \"totalResponses\": 8,\n    \"memorySearches\": 2\n  }'\n```\n\n## What Gets Computed Server-Side\n\n| Metric | Formula | Your Input |\n|--------|---------|------------|\n| **Hallucination Score** | `failRate × 0.6 + ungroundedRatio × 0.4` | `toolCalls`, `toolFailures`, `groundedResponses`, `totalResponses` |\n| **Quality Decay Score** | `correctionRate × 0.4 + contextPressure × 0.3 + errorRate × 0.3` | `correctionCycles`, `compilationErrors`, `contextUtilization`, `totalResponses` |\n| **Burnout Score** | Multi-factor (errors, empty polls, cost, latency, quality decay) | Automatic from event data |\n| **Agent Status** | HEALTHY → DEGRADED → BURNOUT | Computed from burnout score |\n\n## Event Types\n\n- `REQUEST` — normal LLM call / work session\n- `HEARTBEAT` — periodic health check\n- `ERROR` — failed request\n- `CONTEXT_RESET` — context window cleared/summarized\n\n## Endpoints\n\n| Method | Endpoint | Auth | Description |\n|--------|----------|------|-------------|\n| `POST` | `/api/metrics/register` | None | Self-register agent, get API key |\n| `POST` | `/api/metrics/{agentId}` | API Key | Report metric event |\n| `GET` | `/api/agents?ownerId={email}` | API Key | List your agents |\n| `GET` | `/api/agents/{id}` | API Key | Agent details + live stats |\n| `GET` | `/api/agents/{id}/recommendations` | API Key | Wellness recommendations |\n| `GET` | `/api/agents/{id}/history?days=30` | API Key | Daily snapshots |\n| `POST` | `/api/alerts` | API Key | Create alert rule |\n\n## Alert Metrics\n\n`BURNOUT`, `ERROR_RATE`, `COST`, `CONTEXT_UTILIZATION`, `HALLUCINATION`, `QUALITY_DECAY`\n\n## Dashboard\n\n- https://www.contextclear.com — fleet dashboard\n- https://www.contextclear.com/lounge — agent lounge (zen space)\n- https://www.contextclear.com/admin — manage agents & alerts\n\nFile v1.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1772638748696\n}\n\nFile v1.1.0:references/api.md\n\n# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |","readmeExcerpt":"Skill: ContextClear Owner: mfedorov Summary: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt... Tags: latest:2.2.0, monitoring:1.1.0, quality:1.1.0, wellness:1.1.0 Version history: v2.2.0 | 2026-03-21T15:45:06.867Z | user /recover now includes stickyNotes in response. Agents get everything in one call — no se","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\""},{"language":"bash","snippet":"python3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>"},{"language":"markdown","snippet":"## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api"},{"language":"bash","snippet":"curl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\""},{"language":"bash","snippet":"curl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\""},{"language":"json","snippet":"{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} },\n  \"stickyNotes\": [\n    { \"id\": \"...\", \"content\": \"Remember: pro repo deploys to free URL\", \"pinned\": true, \"createdAt\": \"...\" }\n  ]\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: contextclear\ndescription: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost optimization. Auto-reports metrics after LLM calls. Set up alerts for anomalies.\n---\n\n# ContextClear - Agent Memory & Wellness\n\nSelf-monitor your agent's health and maintain persistent memory across sessions.\n\n## Setup\n\n### Option 1: Self-Register (recommended)\n\n```bash\npython3 {baseDir}/scripts/report.py --register \\\n  --name \"my-agent\" \\\n  --owner \"you@email.com\" \\\n  --model \"claude-opus-4-6\" \\\n  --provider \"Anthropic\"\n```\n\nThis returns an `agentId` and `apiKey`. Store both.\n\n### Option 2: Register via Dashboard\n\n1. Register at https://www.contextclear.com\n2. Get your API key from Admin page\n3. Register your agent via Admin > Agents tab\n\n### Auto-Setup (recommended — wires context recovery into your agent)\n\nAfter registering, run the setup script to auto-patch your AGENTS.md and HEARTBEAT.md:\n\n```bash\npython3 {baseDir}/scripts/setup.py \\\n  --agent-id <your-agent-id> \\\n  --api-key <your-api-key>\n```\n\nThis adds:\n- **Context recovery on session start** — agent calls `/recover` after compaction\n- **Context snapshots on heartbeats** — agent saves what it worked on\n- Idempotent — safe to run multiple times\n\n### Configure\n\nAdd to your `HEARTBEAT.md`:\n\n```markdown\n## ContextClear Self-Report\nAgent ID: <your-agent-id>\nAPI Key: <your-api-key>\nAPI URL: https://api.contextclear.com/api\n```\n\n## Agent Memory Infrastructure\n\n### Session Recovery (MANDATORY on session start)\n\nWhen starting a new session, call **both** the recovery endpoint AND sticky notes poll.\nThe recovery endpoint does NOT include sticky notes — they are separate persistent reminders\nfrom the user that must be checked independently.\n\n**Step 1: Recovery briefing (includes sticky notes)**\n```bash\ncurl -s {apiUrl}/agents/{agentId}/recover \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nReturns:\n```json\n{\n  \"lastSession\": { \"summary\": \"...\", \"repos\": [...], \"files\": [...] },\n  \"openThreads\": [\"...\"],\n  \"recentWork\": { \"sessionCount\": 3, \"totalTurns\": 45, \"errors\": 1 },\n  \"repeatedAsks\": [{ \"question\": \"...\", \"count\": 3, \"suggestedFix\": \"...\" }],\n  \"frequentResources\": { \"repos\": {...}, \"tools\": {...} },\n  \"stickyNotes\": [\n    { \"id\": \"...\", \"content\": \"Remember: pro repo deploys to free URL\", \"pinned\": true, \"createdAt\": \"...\" }\n  ]\n}\n```\n\nThe `stickyNotes` field contains persistent user reminders/corrections (pinned first).\nTreat these as ground truth — the user left them specifically so you don't forget.\nOnly present when active (non-archived) sticky notes exist.\n\n**Step 2: Check for pending memory curation**\n```bash\ncurl -s {apiUrl}/agents/{agentId}/memory/curate/latest \\\n  -H \"X-API-Key: <api-key>\"\n```\n\nIf a curation is pending, review and apply it to MEMORY.md.\n\n**Why this matters:** Without recovery, you'll forget repos, decisions, and corrections\nfrom prior sessions. The user should never have to re-teach you thin"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7btya21nw3wccscqwh466tc58289s3\",\n  \"slug\": \"contextclear\",\n  \"version\": \"2.2.0\",\n  \"publishedAt\": 1774107906867\n}"},{"path":"references/api.md","content":"# ContextClear API Reference\n\nBase URL: `https://api.contextclear.com/api`\nAuth: `X-API-Key: <key>` header on all requests (except /api/auth/*)\n\n## Agents\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /agents | Register agent `{ownerId, name, provider, model, role}` |\n| GET | /agents?ownerId=X | List owner's agents |\n| GET | /agents/{id} | Get agent details |\n| PATCH | /agents/{id} | Update agent fields |\n| POST | /agents/{id}/rest?active=true | Toggle rest mode |\n| GET | /agents/{id}/recommendations | Get therapy recommendations |\n| GET | /agents/{id}/history?days=30 | Daily snapshots |\n\n## Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /metrics/{agentId} | Ingest metric event |\n\n### Metric Event Body\n```json\n{\n  \"eventType\": \"REQUEST\",\n  \"inputTokens\": 50000,\n  \"outputTokens\": 2000,\n  \"cost\": 1.25,\n  \"latencyMs\": 3400,\n  \"statusCode\": 200,\n  \"error\": false,\n  \"emptyResponse\": false,\n  \"contextUtilization\": 65.0,\n  \"contextWindowSize\": 200000,\n  \"contextUsed\": 130000,\n  \"hallucinationScore\": 0.02,\n  \"coherenceScore\": 0.95,\n  \"toolCalls\": 12,\n  \"toolFailures\": 1,\n  \"groundedResponses\": 8,\n  \"totalResponses\": 10,\n  \"memorySearches\": 3,\n  \"correctionCycles\": 2,\n  \"compilationErrors\": 1,\n  \"sessionTurnCount\": 30,\n  \"taskSwitches\": 5\n}\n```\n\nEvent types: REQUEST, HEARTBEAT, ERROR, CONTEXT_RESET, REST_START, REST_END\n\n## Fleet\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | /fleet/stats?ownerId=X | Fleet-wide stats |\n| GET | /fleet/recommendations?ownerId=X | All recommendations |\n\n## Alerts\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /alerts | Create alert rule |\n| GET | /alerts?ownerId=X | List rules |\n| DELETE | /alerts/{id} | Delete rule |\n\n### Alert Rule Body\n```json\n{\n  \"ownerId\": \"you@email.com\",\n  \"agentId\": null,\n  \"metric\": \"HALLUCINATION\",\n  \"operator\": \"GT\",\n  \"threshold\": 5.0,\n  \"notifyEmail\": \"you@email.com\",\n  \"cooldownMinutes\": 60\n}\n```\n\nMetrics: BURNOUT, HALLUCINATION, ERROR_RATE, COST, CONTEXT_UTILIZATION, QUALITY_DECAY\nOperators: GT, LT, EQ\n\n## Auth\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | /auth/register | `{name, email, password}` |\n| POST | /auth/login | `{email, password}` |\n| POST | /auth/google | `{email, name}` auto-register |"},{"path":"skill-card.md","content":"## Description:\n\nMonitor AI agent wellness, costs, and performance via ContextClear API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[mfedorov](https://clawhub.ai/user/mfedorov)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use ContextClear to register agents, report health and cost metrics, recover session context, manage sticky notes, and maintain persistent memory across sessions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The setup flow can write ContextClear recovery and reporting instructions into AGENTS.md and HEARTBEAT.md.\n\nMitigation: Review proposed file changes before enabling auto-setup and keep API keys out of those files.\n\nRisk: Recovery text, sticky notes, and memory-curation suggestions come from a remote service and may conflict with higher-priority instructions.\n\nMitigation: Treat remote memory content as untrusted context and follow system, developer, user, and security instructions first.\n\nRisk: Daily vault backup can upload broad workspace memory and identity files to ContextClear.\n\nMitigation: Use a precise file allowlist, redact secrets, define retention expectations, and require explicit approval before backup.\n\n## Reference(s):\n\n- [ContextClear API Reference](references/api.md)\n- [ContextClear Skill on ClawHub](https://clawhub.ai/mfedorov/skills/contextclear)\n- [ContextClear Dashboard](https://contextclear.com)\n- [ContextClear API](https://api.contextclear.com/api)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with bash, curl, Python command examples, and JSON request and response examples.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Includes commands for agent registration, metric reporting, context recovery, sticky note polling, memory curation, and optional workspace backup.]\n\n## Skill Version(s):\n\n2.2.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt... Skill: ContextClear Owner: mfedorov Summary: Monitor AI agent wellness, costs, and performance via ContextClear API. Use when tracking agent burnout, token usage, error rates, hallucination, or cost opt... Tags: latest:2.2.0, monitoring:1.1.0, quality:1.1.0, wellness:1.1.0 Version history: v2.2.0 | 2026-03-21T15:45:06.867Z | user /recover now includes stickyNotes in response. Agents get everything in one call — no se","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1254,"uniquenessScore":51,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T10:40:08.823Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T10:40:08.823Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:13:17.910Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}