{"id":"4c179b01-53c6-4874-8849-1ddb6be5669b","entityType":"agent","slug":"clawhub-robbyczgw-cla-topic-monitor","name":"Topic Monitor","canonicalUrl":"https://www.xpersona.co/agent/clawhub-robbyczgw-cla-topic-monitor","canonicalPath":"/agent/clawhub-robbyczgw-cla-topic-monitor","generatedAt":"2026-10-10T09:08:16.354Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"description":"Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries. Skill: Topic Monitor Owner: robbyczgw-cla Summary: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries. Tags: latest:1","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 5.9K downloads reported by the source. Last updated 4/15/2026.","installCommand":"clawhub skill install kn73gpe8xz2630jrknkb3ya96h7zb84h:topic-monitor","sourceUrl":"https://clawhub.ai/robbyczgw-cla/topic-monitor","homepage":"https://clawhub.ai/robbyczgw-cla/topic-monitor","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/robbyczgw-cla/topic-monitor","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":69,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":"No protocol or capability metadata is available."},"protocols":[],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":0,"capabilityMatrix":{"rows":[],"flattenedTokens":""}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-04-15T00:45:39.800Z","emptyReason":null},"stars":null,"forks":null,"downloads":5899,"packageName":null,"latestVersion":"1.3.4","tractionLabel":"5.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-02-28T17:13:03.240Z","emptyReason":null},"lastUpdatedAt":"2026-04-15T00:45:39.800Z","lastCrawledAt":"2026-02-28T17:13:03.240Z","lastIndexedAt":null,"nextCrawlAt":"2026-03-01T17:13:03.240Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.4","createdAt":"2026-02-11T10:04:39.101Z","changelog":"Security: setup_cron outputs JSON (no crontab manipulation), query input sanitized.","fileCount":16,"zipByteSize":36621},{"version":"1.3.3","createdAt":"2026-02-11T09:22:50.772Z","changelog":"Security: sanitized subprocess env (allowlist only), removed direct Discord webhook HTTP calls.","fileCount":16,"zipByteSize":36353},{"version":"1.3.2","createdAt":"2026-02-11T09:05:39.451Z","changelog":"Fix: SKILL.md metadata updated to openclaw format. Env vars declared as optional.","fileCount":null,"zipByteSize":null},{"version":"1.3.1","createdAt":"2026-02-11T08:55:01.125Z","changelog":"Security: removed hardcoded paths (/root/), hardcoded Telegram ID, hardcoded web-search-plus path. All now configurable via env vars or use safe defaults.","fileCount":null,"zipByteSize":null},{"version":"1.3.0","createdAt":"2026-02-11T08:38:01.022Z","changelog":"Implemented real alerting (was stub). State files moved to memory/monitors/. Switched to web-search-plus for searches.","fileCount":null,"zipByteSize":null},{"version":"1.2.1","createdAt":"2026-02-04T23:04:11.158Z","changelog":"- Added CHANGELOG.md file for improved documentation of changes. - Updated version to 1.2.1 in SKILL.md and package.json. - Minor documentation or metadata updates; no functional changes to core logic.","fileCount":null,"zipByteSize":null},{"version":"1.2.0","createdAt":"2026-02-04T12:20:04.643Z","changelog":"**Quick setup for single-topic monitoring added in v1.2.0:** - Introduced `quick.py` for instant, one-command topic monitoring with sensible defaults. - Added \"Quick Start\" instructions and comparison table to documentation. - No changes to existing setup or core monitoring processes. - Improvements to SKILL.md for clarity and ease of onboarding.","fileCount":null,"zipByteSize":null},{"version":"1.1.2","createdAt":"2026-02-03T17:18:20.477Z","changelog":"Add ClawHub runtime requirements metadata (SKILL.md frontmatter)","fileCount":null,"zipByteSize":null}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install kn73gpe8xz2630jrknkb3ya96h7zb84h:topic-monitor","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-robbyczgw-cla-topic-monitor/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":[]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T09:08:16.353Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-robbyczgw-cla-topic-monitor/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-04-15T00:45:39.800Z","emptyReason":null},"readme":"Skill: Topic Monitor\n\nOwner: robbyczgw-cla\n\nSummary: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries.\n\nTags: latest:1.3.4\n\nVersion history:\n\nv1.3.4 | 2026-02-11T10:04:39.101Z | user\n\nSecurity: setup_cron outputs JSON (no crontab manipulation), query input sanitized.\n\nv1.3.3 | 2026-02-11T09:22:50.772Z | user\n\nSecurity: sanitized subprocess env (allowlist only), removed direct Discord webhook HTTP calls.\n\nv1.3.2 | 2026-02-11T09:05:39.451Z | user\n\nFix: SKILL.md metadata updated to openclaw format. Env vars declared as optional.\n\nv1.3.1 | 2026-02-11T08:55:01.125Z | user\n\nSecurity: removed hardcoded paths (/root/), hardcoded Telegram ID, hardcoded web-search-plus path. All now configurable via env vars or use safe defaults.\n\nv1.3.0 | 2026-02-11T08:38:01.022Z | user\n\nImplemented real alerting (was stub). State files moved to memory/monitors/. Switched to web-search-plus for searches.\n\nv1.2.1 | 2026-02-04T23:04:11.158Z | auto\n\n- Added CHANGELOG.md file for improved documentation of changes.\n- Updated version to 1.2.1 in SKILL.md and package.json.\n- Minor documentation or metadata updates; no functional changes to core logic.\n\nv1.2.0 | 2026-02-04T12:20:04.643Z | auto\n\n**Quick setup for single-topic monitoring added in v1.2.0:**\n\n- Introduced `quick.py` for instant, one-command topic monitoring with sensible defaults.\n- Added \"Quick Start\" instructions and comparison table to documentation.\n- No changes to existing setup or core monitoring processes.\n- Improvements to SKILL.md for clarity and ease of onboarding.\n\nv1.1.2 | 2026-02-03T17:18:20.477Z | user\n\nAdd ClawHub runtime requirements metadata (SKILL.md frontmatter)\n\nv1.1.1 | 2026-02-03T16:58:51.859Z | user\n\nAdd runtime requirements metadata for ClawHub discovery\n\nv1.1.0 | 2026-01-31T23:02:53.906Z | auto\n\nVersion 1.1.0\n\n- Added interactive setup wizard (`scripts/setup.py`) for first-time configuration.\n- Included `skill.json` to define skill metadata.\n- Updated documentation to guide users through the new setup wizard and quick start methods.\n- Streamlined onboarding by prompting new users to configure topics and preferences interactively.\n- No changes to core monitoring logic or alerting features.\n\nv1.0.1 | 2026-01-31T22:55:14.865Z | auto\n\n- Renamed the skill from \"proactive-research\" to \"topic-monitor\" throughout documentation.\n- Updated all branding and references in commands, examples, file paths, and cron setup to reflect the new skill name.\n- No changes to features or functionality—documentation updates only.\n- All usage instructions and configuration samples remain unchanged except for the updated name.\n\nv1.0.0 | 2026-01-31T21:50:53.788Z | user\n\nAutomated topic monitoring with AI importance scoring\n\nArchive index:\n\nArchive v1.3.4: 16 files, 36621 bytes\n\nFiles: CHANGELOG.md (1925b), config.example.json (1309b), package.json (1297b), README.md (5913b), scripts/config.py (7268b), scripts/digest.py (6718b), scripts/importance_scorer.py (9320b), scripts/manage_topics.py (7874b), scripts/monitor.py (17472b), scripts/process_alerts.py (5155b), scripts/quick.py (4986b), scripts/setup_cron.py (2777b), scripts/setup.py (11027b), skill.json (821b), SKILL.md (17511b), _meta.json (132b)\n\nFile v1.3.4:SKILL.md\n\n---\nname: topic-monitor\nversion: 1.3.4\ndescription: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\"],\"env\":{\"TOPIC_MONITOR_TELEGRAM_ID\":\"optional - Telegram chat ID for alerts\",\"TOPIC_MONITOR_DATA_DIR\":\"optional - defaults to .data/ in skill dir\",\"WEB_SEARCH_PLUS_PATH\":\"optional - defaults to relative path\"},\"note\":\"All env vars optional. Defaults work out of the box.\"}}}\n---\n\n# Topic Monitor\n\n**Monitor what matters. Get notified when it happens.**\n\nTopic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly matters.\n\n---\n\n## ⚡ Quick Start (New in v1.2.0!)\n\n**Just want to monitor one topic? One command:**\n\n```bash\npython3 scripts/quick.py \"AI Model Releases\"\n```\n\nThat's it! This creates a topic with sensible defaults:\n- **Query:** Auto-generated from topic name\n- **Keywords:** Extracted from topic name\n- **Frequency:** Daily\n- **Importance:** Medium\n- **Channel:** Telegram\n\n### Quick Start Options\n\n```bash\n# Basic - just a topic name\npython3 scripts/quick.py \"Bitcoin Price\"\n\n# With keywords\npython3 scripts/quick.py \"Security CVEs\" --keywords \"CVE,vulnerability,critical\"\n\n# High priority, hourly checks\npython3 scripts/quick.py \"Production Alerts\" --frequency hourly --importance high\n\n# Custom query\npython3 scripts/quick.py \"Competitor News\" --query \"CompanyName product launch funding\"\n\n# Different channel\npython3 scripts/quick.py \"Team Updates\" --channel discord\n```\n\n### Quick Start vs Full Setup\n\n| Feature | Quick Start | Full Setup |\n|---------|-------------|------------|\n| Speed | ⚡ 1 command | 📝 Wizard |\n| Defaults | Smart | Customizable |\n| Use case | Single topic | Multiple topics |\n| Configuration | Minimal | Full control |\n\n**After Quick Start, you can always customize:**\n```bash\npython3 scripts/manage_topics.py edit ai-model-releases --frequency hourly\n```\n\n---\n\n## Core Capabilities\n\n1. **Topic Configuration** - Define subjects with custom parameters\n2. **Scheduled Monitoring** - Automated searches at configurable intervals\n3. **AI Importance Scoring** - Smart filtering: immediate alert vs digest vs ignore\n4. **Contextual Summaries** - Not just links—meaningful summaries with context\n5. **Weekly Digest** - Low-priority findings compiled into readable reports\n6. **Memory Integration** - References your past conversations and interests\n\n---\n\n## Full Setup (Interactive Wizard)\n\nFor configuring multiple topics or advanced options:\n\n```bash\npython3 scripts/setup.py\n```\n\nThe wizard will guide you through:\n\n1. **Topics** - What subjects do you want to monitor?\n2. **Search queries** - How to search for each topic\n3. **Keywords** - What terms indicate relevance\n4. **Frequency** - How often to check (hourly/daily/weekly)\n5. **Importance threshold** - When to send alerts (low/medium/high)\n6. **Weekly digest** - Compile non-urgent findings into a summary\n\nThe wizard creates `config.json` with your preferences. You can always edit it later or use `manage_topics.py` to add/remove topics.\n\n**Example session:**\n```\n🔍 Topic Monitor - Setup Wizard\n\nWhat topics do you want to monitor?\n  > AI Model Releases\n  > Security Vulnerabilities\n  > \n\n--- Topic 1/2: AI Model Releases ---\n  Search query for 'AI Model Releases' [AI Model Releases news updates]: new AI model release announcement\n  Keywords to watch for in 'AI Model Releases'?\n  > GPT, Claude, Llama, release\n\n--- Topic 2/2: Security Vulnerabilities ---\n  Search query for 'Security Vulnerabilities' [Security Vulnerabilities news updates]: CVE critical vulnerability patch\n  Keywords to watch for in 'Security Vulnerabilities'?\n  > CVE, vulnerability, critical, patch\n\nHow often should I check for updates?\n  1. hourly\n  2. daily *\n  3. weekly\n\n✅ Setup Complete!\n```\n\n## Quick Start\n\nAlready know what you're doing? Here's the manual approach:\n\n```bash\n# Initialize config from template\ncp config.example.json config.json\n\n# Add a topic\npython3 scripts/manage_topics.py add \"Product Updates\" \\\n  --keywords \"release,update,patch\" \\\n  --frequency daily \\\n  --importance medium\n\n# Test monitoring (dry run)\npython3 scripts/monitor.py --dry-run\n\n# Set up cron for automatic monitoring\npython3 scripts/setup_cron.py\n```\n\n## Topic Configuration\n\nEach topic has:\n\n- **name** - Display name (e.g., \"AI Model Releases\")\n- **query** - Search query (e.g., \"new AI model release announcement\")\n- **keywords** - Relevance filters ([\"GPT\", \"Claude\", \"Llama\", \"release\"])\n- **frequency** - `hourly`, `daily`, `weekly`\n- **importance_threshold** - `high` (alert immediately), `medium` (alert if important), `low` (digest only)\n- **channels** - Where to send alerts ([\"telegram\", \"discord\"])\n- **context** - Why you care (for AI contextual summaries)\n\n### Example config.json\n\n```json\n{\n  \"topics\": [\n    {\n      \"id\": \"ai-models\",\n      \"name\": \"AI Model Releases\",\n      \"query\": \"new AI model release GPT Claude Llama\",\n      \"keywords\": [\"GPT\", \"Claude\", \"Llama\", \"release\", \"announcement\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"high\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Following AI developments for work\",\n      \"alert_on\": [\"model_release\", \"major_update\"]\n    },\n    {\n      \"id\": \"tech-news\",\n      \"name\": \"Tech Industry News\",\n      \"query\": \"technology startup funding acquisition\",\n      \"keywords\": [\"startup\", \"funding\", \"Series A\", \"acquisition\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"medium\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Staying informed on tech trends\",\n      \"alert_on\": [\"major_funding\", \"acquisition\"]\n    },\n    {\n      \"id\": \"security-alerts\",\n      \"name\": \"Security Vulnerabilities\",\n      \"query\": \"CVE critical vulnerability security patch\",\n      \"keywords\": [\"CVE\", \"vulnerability\", \"security\", \"patch\", \"critical\"],\n      \"frequency\": \"hourly\",\n      \"importance_threshold\": \"high\",\n      \"channels\": [\"telegram\", \"email\"],\n      \"context\": \"DevOps security monitoring\",\n      \"alert_on\": [\"critical_cve\", \"zero_day\"]\n    }\n  ],\n  \"settings\": {\n    \"digest_day\": \"sunday\",\n    \"digest_time\": \"18:00\",\n    \"max_alerts_per_day\": 5,\n    \"deduplication_window_hours\": 72,\n    \"learning_enabled\": true\n  }\n}\n```\n\n## Scripts\n\n### manage_topics.py\n\nManage research topics:\n\n```bash\n# Add topic\npython3 scripts/manage_topics.py add \"Topic Name\" \\\n  --query \"search query\" \\\n  --keywords \"word1,word2\" \\\n  --frequency daily \\\n  --importance medium \\\n  --channels telegram\n\n# List topics\npython3 scripts/manage_topics.py list\n\n# Edit topic\npython3 scripts/manage_topics.py edit eth-price --frequency hourly\n\n# Remove topic\npython3 scripts/manage_topics.py remove eth-price\n\n# Test topic (preview results without saving)\npython3 scripts/manage_topics.py test eth-price\n```\n\n### monitor.py\n\nMain monitoring script (run via cron):\n\n```bash\n# Normal run (alerts + saves state)\npython3 scripts/monitor.py\n\n# Dry run (no alerts, shows what would happen)\npython3 scripts/monitor.py --dry-run\n\n# Force check specific topic\npython3 scripts/monitor.py --topic eth-price\n\n# Verbose logging\npython3 scripts/monitor.py --verbose\n```\n\n**How it works:**\n1. Reads topics due for checking (based on frequency)\n2. Searches using web-search-plus or built-in web_search\n3. Scores each result with AI importance scorer\n4. High-importance → immediate alert\n5. Medium-importance → saved for digest\n6. Low-importance → ignored\n7. Updates state to prevent duplicate alerts\n\n### digest.py\n\nGenerate weekly digest:\n\n```bash\n# Generate digest for current week\npython3 scripts/digest.py\n\n# Generate and send\npython3 scripts/digest.py --send\n\n# Preview without sending\npython3 scripts/digest.py --preview\n```\n\nOutput format:\n```markdown\n# Weekly Research Digest - [Date Range]\n\n## 🔥 Highlights\n\n- **AI Models**: Claude 4.5 released with improved reasoning\n- **Security**: Critical CVE patched in popular framework\n\n## 📊 By Topic\n\n### AI Model Releases\n- [3 findings this week]\n\n### Security Vulnerabilities\n- [1 finding this week]\n\n## 💡 Recommendations\n\nBased on your interests, you might want to monitor:\n- \"Kubernetes security\" (mentioned 3x this week)\n```\n\n### setup_cron.py\n\nConfigure automated monitoring:\n\n```bash\n# Interactive setup\npython3 scripts/setup_cron.py\n\n# Auto-setup with defaults\npython3 scripts/setup_cron.py --auto\n\n# Remove cron jobs\npython3 scripts/setup_cron.py --remove\n```\n\nCreates cron entries:\n```cron\n# Topic Monitor - Hourly topics\n0 * * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency hourly\n\n# Topic Monitor - Daily topics  \n0 9 * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency daily\n\n# Topic Monitor - Weekly digest\n0 18 * * 0 cd /path/to/skills/topic-monitor && python3 scripts/digest.py --send\n```\n\n## AI Importance Scoring\n\nThe scorer uses multiple signals to decide alert priority:\n\n### Scoring Signals\n\n**HIGH priority (immediate alert):**\n- Major breaking news (detected via freshness + keyword density)\n- Price changes >10% (for finance topics)\n- Product releases matching your exact keywords\n- Security vulnerabilities in tools you use\n- Direct answers to specific questions you asked\n\n**MEDIUM priority (digest-worthy):**\n- Related news but not urgent\n- Minor updates to tracked products\n- Interesting developments in your topics\n- Tutorial/guide releases\n- Community discussions with high engagement\n\n**LOW priority (ignore):**\n- Duplicate news (already alerted)\n- Tangentially related content\n- Low-quality sources\n- Outdated information\n- Spam/promotional content\n\n### Learning Mode\n\nWhen enabled (`learning_enabled: true`), the system:\n1. Tracks which alerts you interact with\n2. Adjusts scoring weights based on your behavior\n3. Suggests topic refinements\n4. Auto-adjusts importance thresholds\n\nLearning data stored in `.learning_data.json` (privacy-safe, never shared).\n\n## Memory Integration\n\nTopic Monitor connects to your conversation history:\n\n**Example alert:**\n> 🔔 **Dirac Live Update**\n> \n> Version 3.8 released with the room correction improvements you asked about last week.\n> \n> **Context:** You mentioned struggling with bass response in your studio. This update includes new low-frequency optimization.\n> \n> [Link] | [Full details]\n\n**How it works:**\n1. Reads references/memory_hints.md (create this file)\n2. Scans recent conversation logs (if available)\n3. Matches findings to past context\n4. Generates personalized summaries\n\n### memory_hints.md (optional)\n\nHelp the AI connect dots:\n\n```markdown\n# Memory Hints for Topic Monitor\n\n## AI Models\n- Using Claude for coding assistance\n- Interested in reasoning improvements\n- Comparing models for different use cases\n\n## Security\n- Running production Kubernetes clusters\n- Need to patch critical CVEs quickly\n- Interested in zero-day disclosures\n\n## Tech News\n- Following startup ecosystem\n- Interested in developer tools space\n- Tracking potential acquisition targets\n```\n\n## Alert Channels\n\n### Telegram\n\nRequires OpenClaw message tool:\n\n```json\n{\n  \"channels\": [\"telegram\"],\n  \"telegram_config\": {\n    \"chat_id\": \"@your_username\",\n    \"silent\": false,\n    \"effects\": {\n      \"high_importance\": \"🔥\",\n      \"medium_importance\": \"📌\"\n    }\n  }\n}\n```\n\n### Discord\n\nAgent-delivered (no webhook in skill config):\n\n`monitor.py` emits `DISCORD_ALERT` JSON payloads, and OpenClaw sends them via the message tool. This matches the Telegram alert flow (structured output, no direct HTTP in skill code).\n\n```json\n{\n  \"channels\": [\"discord\"]\n}\n```\n\n### Email\n\nSMTP or API:\n\n```json\n{\n  \"channels\": [\"email\"],\n  \"email_config\": {\n    \"to\": \"you@example.com\",\n    \"from\": \"research@yourdomain.com\",\n    \"smtp_server\": \"smtp.gmail.com\",\n    \"smtp_port\": 587\n  }\n}\n```\n\n## Advanced Features\n\n### Alert Conditions\n\nFine-tune when to alert:\n\n```json\n{\n  \"alert_on\": [\n    \"price_change_10pct\",\n    \"keyword_exact_match\",\n    \"source_tier_1\",\n    \"high_engagement\"\n  ],\n  \"ignore_sources\": [\n    \"spam-site.com\",\n    \"clickbait-news.io\"\n  ],\n  \"boost_sources\": [\n    \"github.com\",\n    \"arxiv.org\",\n    \"official-site.com\"\n  ]\n}\n```\n\n### Regex Patterns\n\nMatch specific patterns:\n\n```json\n{\n  \"patterns\": [\n    \"version \\\\d+\\\\.\\\\d+\\\\.\\\\d+\",\n    \"\\\\$\\\\d{1,3}(,\\\\d{3})*\",\n    \"CVE-\\\\d{4}-\\\\d+\"\n  ]\n}\n```\n\n### Rate Limiting\n\nPrevent alert fatigue:\n\n```json\n{\n  \"settings\": {\n    \"max_alerts_per_day\": 5,\n    \"max_alerts_per_topic_per_day\": 2,\n    \"quiet_hours\": {\n      \"start\": \"22:00\",\n      \"end\": \"08:00\"\n    }\n  }\n}\n```\n\n## Environment Variables\n\nConfigure these environment variables to customize topic-monitor:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Your Telegram chat ID for receiving alerts |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` in skill dir | Where to store state and findings |\n| `WEB_SEARCH_PLUS_PATH` | Relative to skill | Path to web-search-plus search.py |\n| `SERPER_API_KEY` / `TAVILY_API_KEY` / `EXA_API_KEY` / `YOU_API_KEY` / `SEARXNG_INSTANCE_URL` / `WSP_CACHE_DIR` | — | Optional search-provider vars passed via subprocess env allowlist |\n\n**Example setup:**\n```bash\n# Add to ~/.bashrc or .env\nexport TOPIC_MONITOR_TELEGRAM_ID=\"123456789\"\nexport TOPIC_MONITOR_DATA_DIR=\"/home/user/topic-monitor-data\"\nexport WEB_SEARCH_PLUS_PATH=\"/path/to/skills/web-search-plus/scripts/search.py\"\n```\n\n## State Management\n\n### .research_state.json\n\nStored in `TOPIC_MONITOR_DATA_DIR` (default: `.data/` in skill directory).\n\nTracks:\n- Last check time per topic\n- Alerted URLs (deduplication)\n- Importance scores history\n- Learning data (if enabled)\n\nExample:\n```json\n{\n  \"topics\": {\n    \"eth-price\": {\n      \"last_check\": \"2026-01-28T22:00:00Z\",\n      \"last_alert\": \"2026-01-28T15:30:00Z\",\n      \"alerted_urls\": [\n        \"https://example.com/eth-news-1\"\n      ],\n      \"findings_count\": 3,\n      \"alerts_today\": 1\n    }\n  },\n  \"deduplication\": {\n    \"url_hash_map\": {\n      \"abc123\": \"2026-01-28T15:30:00Z\"\n    }\n  }\n}\n```\n\n### .findings/ directory\n\nStores digest-worthy findings:\n\n```\n.findings/\n├── 2026-01-22_eth-price.json\n├── 2026-01-24_fm26-patches.json\n└── 2026-01-27_ai-breakthroughs.json\n```\n\n## Best Practices\n\n1. **Start conservative** - Set `importance_threshold: medium` initially, adjust based on alert quality\n2. **Use context field** - Helps AI generate better summaries\n3. **Refine keywords** - Add negative keywords to filter noise: `\"keywords\": [\"AI\", \"-clickbait\", \"-spam\"]`\n4. **Enable learning** - Improves over time based on your behavior\n5. **Review digest weekly** - Don't ignore the digest—it surfaces patterns\n6. **Combine with personal-analytics** - Get topic recommendations based on your chat patterns\n\n## Integration with Other Skills\n\n### web-search-plus\n\nAutomatically uses intelligent routing:\n- Product/price topics → Serper\n- Research topics → Tavily  \n- Company/startup discovery → Exa\n\n### personal-analytics\n\nSuggests topics based on conversation patterns:\n> \"You've asked about Rust 12 times this month. Want me to monitor 'Rust language updates'?\"\n\n## Privacy & Security\n\n- **All data local** - No external services except search APIs\n- **State files gitignored** - Safe to use in version-controlled workspace\n- **Memory hints optional** - You control what context is shared\n- **Learning data stays local** - Never sent to APIs\n- **Subprocess env allowlist** - monitor forwards only PATH/HOME/LANG/TERM and search-provider keys\n- **No direct HTTP in skill code** - alerts are emitted as JSON for OpenClaw delivery\n\n## Troubleshooting\n\n**No alerts being sent:**\n- Check cron is running: `crontab -l`\n- Verify channel config (Telegram chat ID, topic channel list for Discord/email)\n- Run with `--dry-run --verbose` to see scoring\n\n**Too many alerts:**\n- Increase `importance_threshold`\n- Add rate limiting\n- Refine keywords (add negative filters)\n- Enable learning mode\n\n**Missing important news:**\n- Decrease `importance_threshold`\n- Increase check frequency\n- Broaden keywords\n- Check `.research_state.json` for deduplication issues\n\n**Digest not generating:**\n- Verify `.findings/` directory exists and has content\n- Check digest cron schedule\n- Run manually: `python3 scripts/digest.py --preview`\n\n## Example Workflows\n\n### Track Product Release\n\n```bash\npython3 scripts/manage_topics.py add \"iPhone 17 Release\" \\\n  --query \"iPhone 17 announcement release date\" \\\n  --keywords \"iPhone 17,Apple event,September\" \\\n  --frequency daily \\\n  --importance high \\\n  --channels telegram \\\n  --context \"Planning to upgrade from iPhone 13\"\n```\n\n### Monitor Competitor\n\n```bash\npython3 scripts/manage_topics.py add \"Competitor Analysis\" \\\n  --query \"CompetitorCo product launch funding\" \\\n  --keywords \"CompetitorCo,product,launch,Series,funding\" \\\n  --frequency weekly \\\n  --importance medium \\\n  --channels discord,email\n```\n\n### Research Topic\n\n```bash\npython3 scripts/manage_topics.py add \"Quantum Computing Papers\" \\\n  --query \"quantum computing arxiv\" \\\n  --keywords \"quantum,qubit,arxiv\" \\\n  --frequency weekly \\\n  --importance low \\\n  --channels email\n```\n\n## Credits\n\nBuilt for ClawHub. Uses web-search-plus skill for intelligent search routing.\n\nFile v1.3.4:README.md\n\n# Topic Monitor\n\n**Never miss what matters. Get alerted when it happens.**\n\nTopic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly important occurs.\n\n## Features\n\n- 🔍 **Automated Monitoring** - Scheduled web searches for your topics\n- 🧠 **AI Importance Scoring** - Smart filtering: alert vs digest vs ignore\n- 📱 **Multi-Channel Alerts** - Telegram, Discord, Email (agent-delivered)\n- 📊 **Weekly Digests** - Curated summaries of interesting findings\n- 🧩 **Memory Integration** - Contextual alerts referencing your past conversations\n- ⚡ **Rate Limiting** - Prevent alert fatigue\n- 🎯 **Custom Conditions** - Fine-tune when to alert\n\n## Quick Start\n\n### Option 1: Interactive Setup (Recommended)\n\nRun the setup wizard for a guided experience:\n\n```bash\npython3 scripts/setup.py\n```\n\nThe wizard asks friendly questions about what you want to monitor and creates your config automatically.\n\n### Option 2: Manual Setup\n\n```bash\n# 1. Copy the template\ncp config.example.json config.json\n\n# 2. Add your first topic\npython3 scripts/manage_topics.py add \"AI Models\" \\\n  --query \"new AI model release announcement\" \\\n  --keywords \"GPT,Claude,Llama,release\" \\\n  --frequency daily \\\n  --importance high \\\n  --channels telegram\n\n# 3. Test it\npython3 scripts/manage_topics.py test ai-models\n\n# 4. Set up automated monitoring\npython3 scripts/setup_cron.py\n```\n\n## Use Cases\n\n### 📈 Price Monitoring\nTrack product prices, SaaS pricing changes, or market trends with alerts on significant changes.\n\n### 🔧 Product Updates\nMonitor software releases, patches, and feature announcements.\n\n### 📰 News Tracking\nStay updated on specific topics without drowning in noise.\n\n### 🏢 Competitor Analysis\nTrack competitor product launches, funding, and news.\n\n### 🎓 Research Papers\nMonitor arXiv, GitHub, or academic publications in your field.\n\n## How It Works\n\n1. **Configure Topics** - Define what to monitor and when to alert\n2. **Scheduled Checks** - Cron jobs run searches at your chosen frequency\n3. **AI Scoring** - Each result is scored for importance\n4. **Smart Alerting** - High priority → immediate alert, Medium → digest, Low → ignore\n5. **Deduplication** - Never get the same alert twice\n\n## Configuration\n\nSee [SKILL.md](SKILL.md) for complete documentation.\n\n### Example Topic\n\n```json\n{\n  \"id\": \"ai-breakthroughs\",\n  \"name\": \"AI Research Breakthroughs\",\n  \"query\": \"artificial intelligence breakthrough research\",\n  \"keywords\": [\"AI\", \"LLM\", \"transformer\", \"AGI\"],\n  \"frequency\": \"daily\",\n  \"importance_threshold\": \"medium\",\n  \"channels\": [\"telegram\"],\n  \"context\": \"Following AI developments for work\",\n  \"alert_on\": [\"major_paper\", \"model_release\"]\n}\n```\n\n## Commands\n\n### Manage Topics\n\n```bash\n# Add topic\npython3 scripts/manage_topics.py add \"Topic Name\" \\\n  --query \"search query\" \\\n  --keywords \"word1,word2\" \\\n  --frequency daily\n\n# List topics\npython3 scripts/manage_topics.py list\n\n# Edit topic\npython3 scripts/manage_topics.py edit topic-id --frequency hourly\n\n# Remove topic\npython3 scripts/manage_topics.py remove topic-id\n\n# Test topic\npython3 scripts/manage_topics.py test topic-id\n```\n\n### Monitor\n\n```bash\n# Manual check (dry run)\npython3 scripts/monitor.py --dry-run --verbose\n\n# Check specific topic\npython3 scripts/monitor.py --topic ai-models\n\n# Check all hourly topics\npython3 scripts/monitor.py --frequency hourly\n```\n\n### Digest\n\n```bash\n# Preview this week's digest\npython3 scripts/digest.py --preview\n\n# Generate and send\npython3 scripts/digest.py --send\n```\n\n### Cron Setup\n\n```bash\n# Interactive setup\npython3 scripts/setup_cron.py\n\n# Auto-setup\npython3 scripts/setup_cron.py --auto\n\n# Remove cron jobs\npython3 scripts/setup_cron.py --remove\n```\n\n## Integration\n\n### Works With\n\n- **web-search-plus** - Intelligent search routing (Serper, Tavily, Exa)\n- **personal-analytics** - Get topic recommendations from your chat patterns\n- **OpenClaw message tool** - Send alerts via Telegram/Discord from structured JSON output\n\n### Channel Setup\n\n#### Telegram\nConfigure in config.json:\n```json\n{\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"chat_id\": \"@your_username\"\n    }\n  }\n}\n```\n\n#### Discord\nNo webhook is needed in `config.json`. `monitor.py` now emits `DISCORD_ALERT` JSON lines and your OpenClaw agent delivers them via the message tool (same pattern as Telegram).\n\nMinimal topic-level channel usage:\n```json\n{\n  \"topics\": [\n    {\n      \"name\": \"Team Updates\",\n      \"channels\": [\"discord\"]\n    }\n  ]\n}\n```\n\n## Configuration via Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Telegram chat ID for alerts (required for Telegram) |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` | Directory for state and findings files |\n| `WEB_SEARCH_PLUS_PATH` | Relative to skill | Path to web-search-plus search.py script |\n| `SERPER_API_KEY` / `TAVILY_API_KEY` / `EXA_API_KEY` / `YOU_API_KEY` / `SEARXNG_INSTANCE_URL` / `WSP_CACHE_DIR` | — | Optional search-provider vars forwarded via subprocess env allowlist |\n\n**Example:**\n```bash\nexport TOPIC_MONITOR_TELEGRAM_ID=\"123456789\"\nexport TOPIC_MONITOR_DATA_DIR=\"/path/to/data\"\nexport WEB_SEARCH_PLUS_PATH=\"/path/to/skills/web-search-plus/scripts/search.py\"\n```\n\n## Privacy\n\n- All data stored locally\n- No external services except search APIs\n- Learning data stays on your machine\n- State files are gitignored\n- **No hardcoded personal info** — configure via environment variables\n- Search subprocess uses env allowlist only (`PATH`, `HOME`, `LANG`, `TERM` + search provider keys)\n- No direct HTTP calls from topic-monitor skill code\n\n## Requirements\n\n- Python 3.8+\n- Optional: web-search-plus skill (for better search)\n- Cron (for automated monitoring)\n\n## License\n\nMIT\n\n## Credits\n\nBuilt for ClawHub.\n\nFile v1.3.4:_meta.json\n\n{\n  \"ownerId\": \"kn73gpe8xz2630jrknkb3ya96h7zb84h\",\n  \"slug\": \"topic-monitor\",\n  \"version\": \"1.3.4\",\n  \"publishedAt\": 1770804279101\n}\n\nFile v1.3.4:CHANGELOG.md\n\n# Changelog\n\n## [1.3.3] - 2026-02-11\n\n### Changed\n\n- **Subprocess env hardening:** `monitor.py` now uses an allowlist for web-search-plus subprocess environment (`PATH`, `HOME`, `LANG`, `TERM` + search provider keys only).\n- **Discord delivery flow:** Removed webhook-style delivery from skill docs/flow; Discord alerts are now emitted as structured JSON (`DISCORD_ALERT`) for OpenClaw agent delivery (same pattern as Telegram).\n- **No direct HTTP calls:** Alerting/search integration is documented as agent-mediated JSON output + subprocess execution, without direct outbound HTTP from topic-monitor skill code.\n\n## [1.3.2] - 2026-02-11\n\n### 🆕 Real Alerting System\n\nThe alerting system is now fully functional (was a stub before):\n\n- **Telegram Alerts:** Send immediate alerts for high-priority findings\n- **Multi-Channel Support:** Telegram, Discord, and Email\n- **Smart Filtering:** Importance scoring determines what gets alerted\n\n### Changed\n\n- **State Files:** Now stored in `.data/` directory (configurable via `TOPIC_MONITOR_DATA_DIR`)\n- **Telegram ID:** Configured via `TOPIC_MONITOR_TELEGRAM_ID` environment variable (no hardcoded values)\n- **web-search-plus Path:** Now relative by default, configurable via `WEB_SEARCH_PLUS_PATH`\n- **No Hardcoded Paths:** All paths and IDs are now configurable\n\n### Environment Variables\n\nNew environment variables for configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Telegram chat ID for alerts |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` | State and findings directory |\n| `WEB_SEARCH_PLUS_PATH` | Relative | Path to web-search-plus script |\n\n### Migration\n\nIf you had hardcoded paths in config.json, update to use environment variables:\n```bash\nexport TOPIC_MONITOR_TELEGRAM_ID=\"your_telegram_id\"\n```\n\n## [1.2.1] - 2026-02-04\n\n- Privacy cleanup: removed hardcoded paths and personal info from docs\n\nFile v1.3.4:config.example.json\n\n{\n  \"topics\": [\n    {\n      \"id\": \"example-topic\",\n      \"name\": \"Example Topic\",\n      \"query\": \"search query here\",\n      \"keywords\": [\"keyword1\", \"keyword2\", \"keyword3\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"medium\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Why this topic matters to you\",\n      \"alert_on\": [\"keyword_exact_match\"],\n      \"ignore_sources\": [],\n      \"boost_sources\": []\n    }\n  ],\n  \"settings\": {\n    \"digest_day\": \"sunday\",\n    \"digest_time\": \"18:00\",\n    \"max_alerts_per_day\": 5,\n    \"max_alerts_per_topic_per_day\": 2,\n    \"deduplication_window_hours\": 72,\n    \"learning_enabled\": true,\n    \"quiet_hours\": {\n      \"enabled\": false,\n      \"start\": \"22:00\",\n      \"end\": \"08:00\"\n    }\n  },\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"chat_id\": null,\n      \"silent\": false,\n      \"effects\": {\n        \"high_importance\": \"🔥\",\n        \"medium_importance\": \"📌\"\n      }\n    },\n    \"discord\": {\n      \"enabled\": false,\n      \"webhook_url\": null,\n      \"username\": \"Research Bot\",\n      \"avatar_url\": null\n    },\n    \"email\": {\n      \"enabled\": false,\n      \"to\": null,\n      \"from\": \"research@yourdomain.com\",\n      \"smtp_server\": \"smtp.gmail.com\",\n      \"smtp_port\": 587,\n      \"smtp_user\": null,\n      \"smtp_password\": null\n    }\n  }\n}\n\nFile v1.3.4:package.json\n\n{\n  \"name\": \"@openclaw/topic-monitor\",\n  \"version\": \"1.3.4\",\n  \"description\": \"Monitor topics of interest and get proactive alerts when important developments occur\",\n  \"author\": \"robbyczgw-cla\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"openclaw\",\n    \"skill\",\n    \"monitoring\",\n    \"alerts\",\n    \"research\",\n    \"proactive\",\n    \"news\",\n    \"tracking\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/robbyczgw-cla/topic-monitor.git\"\n  },\n  \"homepage\": \"https://clawhub.ai/robbyczgw-cla/topic-monitor\",\n  \"bugs\": {\n    \"url\": \"https://github.com/robbyczgw-cla/topic-monitor/issues\"\n  },\n  \"openclaw\": {\n    \"skill\": true,\n    \"triggers\": [\"monitor topic\", \"track topic\", \"topic alerts\"],\n    \"capabilities\": [\n      \"proactive-alerts\",\n      \"topic-tracking\",\n      \"digest-reports\"\n    ],\n    \"requirements\": {\n      \"bins\": [\"python3\"],\n      \"env\": {}\n    }\n  },\n  \"files\": [\n    \"SKILL.md\",\n    \"README.md\",\n    \"config.example.json\",\n    \"scripts/\"\n  ],\n  \"scripts\": {\n    \"setup\": \"python3 scripts/setup.py\",\n    \"monitor\": \"python3 scripts/monitor.py\",\n    \"digest\": \"python3 scripts/digest.py\",\n    \"topics\": \"python3 scripts/manage_topics.py\"\n  },\n  \"dependencies\": {\n    \"python\": \">=3.8\"\n  },\n  \"optionalDependencies\": {\n    \"skills\": [\"web-search-plus\"]\n  }\n}\n\nFile v1.3.4:skill.json\n\n{\n  \"name\": \"topic-monitor\",\n  \"version\": \"1.1.0\",\n  \"description\": \"Monitor topics of interest and get proactive alerts when important developments occur\",\n  \"author\": \"robbyczgw-cla\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"monitoring\",\n    \"alerts\",\n    \"research\",\n    \"proactive\",\n    \"news\",\n    \"tracking\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/robbyczgw-cla/skills\"\n  },\n  \"files\": [\n    \"SKILL.md\",\n    \"README.md\",\n    \"config.example.json\",\n    \"scripts/\"\n  ],\n  \"scripts\": {\n    \"setup\": \"python3 scripts/setup.py\",\n    \"monitor\": \"python3 scripts/monitor.py\",\n    \"digest\": \"python3 scripts/digest.py\",\n    \"topics\": \"python3 scripts/manage_topics.py\"\n  },\n  \"dependencies\": {\n    \"python\": \">=3.8\"\n  },\n  \"optional_dependencies\": {\n    \"skills\": [\"web-search-plus\"]\n  }\n}\n\nArchive v1.3.3: 16 files, 36353 bytes\n\nFiles: CHANGELOG.md (1324b), config.example.json (1309b), package.json (1297b), README.md (5364b), scripts/config.py (7268b), scripts/digest.py (6718b), scripts/importance_scorer.py (9320b), scripts/manage_topics.py (7874b), scripts/monitor.py (17226b), scripts/process_alerts.py (5155b), scripts/quick.py (4986b), scripts/setup_cron.py (4921b), scripts/setup.py (11027b), skill.json (821b), SKILL.md (17049b), _meta.json (132b)\n\nFile v1.3.3:SKILL.md\n\n---\nname: topic-monitor\nversion: 1.3.3\ndescription: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\"],\"env\":{\"TOPIC_MONITOR_TELEGRAM_ID\":\"optional - Telegram chat ID for alerts\",\"TOPIC_MONITOR_DATA_DIR\":\"optional - defaults to .data/ in skill dir\",\"WEB_SEARCH_PLUS_PATH\":\"optional - defaults to relative path\"},\"note\":\"All env vars optional. Defaults work out of the box.\"}}}\n---\n\n# Topic Monitor\n\n**Monitor what matters. Get notified when it happens.**\n\nTopic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly matters.\n\n---\n\n## ⚡ Quick Start (New in v1.2.0!)\n\n**Just want to monitor one topic? One command:**\n\n```bash\npython3 scripts/quick.py \"AI Model Releases\"\n```\n\nThat's it! This creates a topic with sensible defaults:\n- **Query:** Auto-generated from topic name\n- **Keywords:** Extracted from topic name\n- **Frequency:** Daily\n- **Importance:** Medium\n- **Channel:** Telegram\n\n### Quick Start Options\n\n```bash\n# Basic - just a topic name\npython3 scripts/quick.py \"Bitcoin Price\"\n\n# With keywords\npython3 scripts/quick.py \"Security CVEs\" --keywords \"CVE,vulnerability,critical\"\n\n# High priority, hourly checks\npython3 scripts/quick.py \"Production Alerts\" --frequency hourly --importance high\n\n# Custom query\npython3 scripts/quick.py \"Competitor News\" --query \"CompanyName product launch funding\"\n\n# Different channel\npython3 scripts/quick.py \"Team Updates\" --channel discord\n```\n\n### Quick Start vs Full Setup\n\n| Feature | Quick Start | Full Setup |\n|---------|-------------|------------|\n| Speed | ⚡ 1 command | 📝 Wizard |\n| Defaults | Smart | Customizable |\n| Use case | Single topic | Multiple topics |\n| Configuration | Minimal | Full control |\n\n**After Quick Start, you can always customize:**\n```bash\npython3 scripts/manage_topics.py edit ai-model-releases --frequency hourly\n```\n\n---\n\n## Core Capabilities\n\n1. **Topic Configuration** - Define subjects with custom parameters\n2. **Scheduled Monitoring** - Automated searches at configurable intervals\n3. **AI Importance Scoring** - Smart filtering: immediate alert vs digest vs ignore\n4. **Contextual Summaries** - Not just links—meaningful summaries with context\n5. **Weekly Digest** - Low-priority findings compiled into readable reports\n6. **Memory Integration** - References your past conversations and interests\n\n---\n\n## Full Setup (Interactive Wizard)\n\nFor configuring multiple topics or advanced options:\n\n```bash\npython3 scripts/setup.py\n```\n\nThe wizard will guide you through:\n\n1. **Topics** - What subjects do you want to monitor?\n2. **Search queries** - How to search for each topic\n3. **Keywords** - What terms indicate relevance\n4. **Frequency** - How often to check (hourly/daily/weekly)\n5. **Importance threshold** - When to send alerts (low/medium/high)\n6. **Weekly digest** - Compile non-urgent findings into a summary\n\nThe wizard creates `config.json` with your preferences. You can always edit it later or use `manage_topics.py` to add/remove topics.\n\n**Example session:**\n```\n🔍 Topic Monitor - Setup Wizard\n\nWhat topics do you want to monitor?\n  > AI Model Releases\n  > Security Vulnerabilities\n  > \n\n--- Topic 1/2: AI Model Releases ---\n  Search query for 'AI Model Releases' [AI Model Releases news updates]: new AI model release announcement\n  Keywords to watch for in 'AI Model Releases'?\n  > GPT, Claude, Llama, release\n\n--- Topic 2/2: Security Vulnerabilities ---\n  Search query for 'Security Vulnerabilities' [Security Vulnerabilities news updates]: CVE critical vulnerability patch\n  Keywords to watch for in 'Security Vulnerabilities'?\n  > CVE, vulnerability, critical, patch\n\nHow often should I check for updates?\n  1. hourly\n  2. daily *\n  3. weekly\n\n✅ Setup Complete!\n```\n\n## Quick Start\n\nAlready know what you're doing? Here's the manual approach:\n\n```bash\n# Initialize config from template\ncp config.example.json config.json\n\n# Add a topic\npython3 scripts/manage_topics.py add \"Product Updates\" \\\n  --keywords \"release,update,patch\" \\\n  --frequency daily \\\n  --importance medium\n\n# Test monitoring (dry run)\npython3 scripts/monitor.py --dry-run\n\n# Set up cron for automatic monitoring\npython3 scripts/setup_cron.py\n```\n\n## Topic Configuration\n\nEach topic has:\n\n- **name** - Display name (e.g., \"AI Model Releases\")\n- **query** - Search query (e.g., \"new AI model release announcement\")\n- **keywords** - Relevance filters ([\"GPT\", \"Claude\", \"Llama\", \"release\"])\n- **frequency** - `hourly`, `daily`, `weekly`\n- **importance_threshold** - `high` (alert immediately), `medium` (alert if important), `low` (digest only)\n- **channels** - Where to send alerts ([\"telegram\", \"discord\"])\n- **context** - Why you care (for AI contextual summaries)\n\n### Example config.json\n\n```json\n{\n  \"topics\": [\n    {\n      \"id\": \"ai-models\",\n      \"name\": \"AI Model Releases\",\n      \"query\": \"new AI model release GPT Claude Llama\",\n      \"keywords\": [\"GPT\", \"Claude\", \"Llama\", \"release\", \"announcement\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"high\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Following AI developments for work\",\n      \"alert_on\": [\"model_release\", \"major_update\"]\n    },\n    {\n      \"id\": \"tech-news\",\n      \"name\": \"Tech Industry News\",\n      \"query\": \"technology startup funding acquisition\",\n      \"keywords\": [\"startup\", \"funding\", \"Series A\", \"acquisition\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"medium\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Staying informed on tech trends\",\n      \"alert_on\": [\"major_funding\", \"acquisition\"]\n    },\n    {\n      \"id\": \"security-alerts\",\n      \"name\": \"Security Vulnerabilities\",\n      \"query\": \"CVE critical vulnerability security patch\",\n      \"keywords\": [\"CVE\", \"vulnerability\", \"security\", \"patch\", \"critical\"],\n      \"frequency\": \"hourly\",\n      \"importance_threshold\": \"high\",\n      \"channels\": [\"telegram\", \"email\"],\n      \"context\": \"DevOps security monitoring\",\n      \"alert_on\": [\"critical_cve\", \"zero_day\"]\n    }\n  ],\n  \"settings\": {\n    \"digest_day\": \"sunday\",\n    \"digest_time\": \"18:00\",\n    \"max_alerts_per_day\": 5,\n    \"deduplication_window_hours\": 72,\n    \"learning_enabled\": true\n  }\n}\n```\n\n## Scripts\n\n### manage_topics.py\n\nManage research topics:\n\n```bash\n# Add topic\npython3 scripts/manage_topics.py add \"Topic Name\" \\\n  --query \"search query\" \\\n  --keywords \"word1,word2\" \\\n  --frequency daily \\\n  --importance medium \\\n  --channels telegram\n\n# List topics\npython3 scripts/manage_topics.py list\n\n# Edit topic\npython3 scripts/manage_topics.py edit eth-price --frequency hourly\n\n# Remove topic\npython3 scripts/manage_topics.py remove eth-price\n\n# Test topic (preview results without saving)\npython3 scripts/manage_topics.py test eth-price\n```\n\n### monitor.py\n\nMain monitoring script (run via cron):\n\n```bash\n# Normal run (alerts + saves state)\npython3 scripts/monitor.py\n\n# Dry run (no alerts, shows what would happen)\npython3 scripts/monitor.py --dry-run\n\n# Force check specific topic\npython3 scripts/monitor.py --topic eth-price\n\n# Verbose logging\npython3 scripts/monitor.py --verbose\n```\n\n**How it works:**\n1. Reads topics due for checking (based on frequency)\n2. Searches using web-search-plus or built-in web_search\n3. Scores each result with AI importance scorer\n4. High-importance → immediate alert\n5. Medium-importance → saved for digest\n6. Low-importance → ignored\n7. Updates state to prevent duplicate alerts\n\n### digest.py\n\nGenerate weekly digest:\n\n```bash\n# Generate digest for current week\npython3 scripts/digest.py\n\n# Generate and send\npython3 scripts/digest.py --send\n\n# Preview without sending\npython3 scripts/digest.py --preview\n```\n\nOutput format:\n```markdown\n# Weekly Research Digest - [Date Range]\n\n## 🔥 Highlights\n\n- **AI Models**: Claude 4.5 released with improved reasoning\n- **Security**: Critical CVE patched in popular framework\n\n## 📊 By Topic\n\n### AI Model Releases\n- [3 findings this week]\n\n### Security Vulnerabilities\n- [1 finding this week]\n\n## 💡 Recommendations\n\nBased on your interests, you might want to monitor:\n- \"Kubernetes security\" (mentioned 3x this week)\n```\n\n### setup_cron.py\n\nConfigure automated monitoring:\n\n```bash\n# Interactive setup\npython3 scripts/setup_cron.py\n\n# Auto-setup with defaults\npython3 scripts/setup_cron.py --auto\n\n# Remove cron jobs\npython3 scripts/setup_cron.py --remove\n```\n\nCreates cron entries:\n```cron\n# Topic Monitor - Hourly topics\n0 * * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency hourly\n\n# Topic Monitor - Daily topics  \n0 9 * * * cd /path/to/skills/topic-monitor && python3 scripts/monitor.py --frequency daily\n\n# Topic Monitor - Weekly digest\n0 18 * * 0 cd /path/to/skills/topic-monitor && python3 scripts/digest.py --send\n```\n\n## AI Importance Scoring\n\nThe scorer uses multiple signals to decide alert priority:\n\n### Scoring Signals\n\n**HIGH priority (immediate alert):**\n- Major breaking news (detected via freshness + keyword density)\n- Price changes >10% (for finance topics)\n- Product releases matching your exact keywords\n- Security vulnerabilities in tools you use\n- Direct answers to specific questions you asked\n\n**MEDIUM priority (digest-worthy):**\n- Related news but not urgent\n- Minor updates to tracked products\n- Interesting developments in your topics\n- Tutorial/guide releases\n- Community discussions with high engagement\n\n**LOW priority (ignore):**\n- Duplicate news (already alerted)\n- Tangentially related content\n- Low-quality sources\n- Outdated information\n- Spam/promotional content\n\n### Learning Mode\n\nWhen enabled (`learning_enabled: true`), the system:\n1. Tracks which alerts you interact with\n2. Adjusts scoring weights based on your behavior\n3. Suggests topic refinements\n4. Auto-adjusts importance thresholds\n\nLearning data stored in `.learning_data.json` (privacy-safe, never shared).\n\n## Memory Integration\n\nTopic Monitor connects to your conversation history:\n\n**Example alert:**\n> 🔔 **Dirac Live Update**\n> \n> Version 3.8 released with the room correction improvements you asked about last week.\n> \n> **Context:** You mentioned struggling with bass response in your studio. This update includes new low-frequency optimization.\n> \n> [Link] | [Full details]\n\n**How it works:**\n1. Reads references/memory_hints.md (create this file)\n2. Scans recent conversation logs (if available)\n3. Matches findings to past context\n4. Generates personalized summaries\n\n### memory_hints.md (optional)\n\nHelp the AI connect dots:\n\n```markdown\n# Memory Hints for Topic Monitor\n\n## AI Models\n- Using Claude for coding assistance\n- Interested in reasoning improvements\n- Comparing models for different use cases\n\n## Security\n- Running production Kubernetes clusters\n- Need to patch critical CVEs quickly\n- Interested in zero-day disclosures\n\n## Tech News\n- Following startup ecosystem\n- Interested in developer tools space\n- Tracking potential acquisition targets\n```\n\n## Alert Channels\n\n### Telegram\n\nRequires OpenClaw message tool:\n\n```json\n{\n  \"channels\": [\"telegram\"],\n  \"telegram_config\": {\n    \"chat_id\": \"@your_username\",\n    \"silent\": false,\n    \"effects\": {\n      \"high_importance\": \"🔥\",\n      \"medium_importance\": \"📌\"\n    }\n  }\n}\n```\n\n### Discord\n\nWebhook-based:\n\n```json\n{\n  \"channels\": [\"discord\"],\n  \"discord_config\": {\n    \"webhook_url\": \"https://discord.com/api/webhooks/...\",\n    \"username\": \"Research Bot\",\n    \"avatar_url\": \"https://...\"\n  }\n}\n```\n\n### Email\n\nSMTP or API:\n\n```json\n{\n  \"channels\": [\"email\"],\n  \"email_config\": {\n    \"to\": \"you@example.com\",\n    \"from\": \"research@yourdomain.com\",\n    \"smtp_server\": \"smtp.gmail.com\",\n    \"smtp_port\": 587\n  }\n}\n```\n\n## Advanced Features\n\n### Alert Conditions\n\nFine-tune when to alert:\n\n```json\n{\n  \"alert_on\": [\n    \"price_change_10pct\",\n    \"keyword_exact_match\",\n    \"source_tier_1\",\n    \"high_engagement\"\n  ],\n  \"ignore_sources\": [\n    \"spam-site.com\",\n    \"clickbait-news.io\"\n  ],\n  \"boost_sources\": [\n    \"github.com\",\n    \"arxiv.org\",\n    \"official-site.com\"\n  ]\n}\n```\n\n### Regex Patterns\n\nMatch specific patterns:\n\n```json\n{\n  \"patterns\": [\n    \"version \\\\d+\\\\.\\\\d+\\\\.\\\\d+\",\n    \"\\\\$\\\\d{1,3}(,\\\\d{3})*\",\n    \"CVE-\\\\d{4}-\\\\d+\"\n  ]\n}\n```\n\n### Rate Limiting\n\nPrevent alert fatigue:\n\n```json\n{\n  \"settings\": {\n    \"max_alerts_per_day\": 5,\n    \"max_alerts_per_topic_per_day\": 2,\n    \"quiet_hours\": {\n      \"start\": \"22:00\",\n      \"end\": \"08:00\"\n    }\n  }\n}\n```\n\n## Environment Variables\n\nConfigure these environment variables to customize topic-monitor:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Your Telegram chat ID for receiving alerts |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` in skill dir | Where to store state and findings |\n| `WEB_SEARCH_PLUS_PATH` | Relative to skill | Path to web-search-plus search.py |\n\n**Example setup:**\n```bash\n# Add to ~/.bashrc or .env\nexport TOPIC_MONITOR_TELEGRAM_ID=\"123456789\"\nexport TOPIC_MONITOR_DATA_DIR=\"/home/user/topic-monitor-data\"\nexport WEB_SEARCH_PLUS_PATH=\"/path/to/skills/web-search-plus/scripts/search.py\"\n```\n\n## State Management\n\n### .research_state.json\n\nStored in `TOPIC_MONITOR_DATA_DIR` (default: `.data/` in skill directory).\n\nTracks:\n- Last check time per topic\n- Alerted URLs (deduplication)\n- Importance scores history\n- Learning data (if enabled)\n\nExample:\n```json\n{\n  \"topics\": {\n    \"eth-price\": {\n      \"last_check\": \"2026-01-28T22:00:00Z\",\n      \"last_alert\": \"2026-01-28T15:30:00Z\",\n      \"alerted_urls\": [\n        \"https://example.com/eth-news-1\"\n      ],\n      \"findings_count\": 3,\n      \"alerts_today\": 1\n    }\n  },\n  \"deduplication\": {\n    \"url_hash_map\": {\n      \"abc123\": \"2026-01-28T15:30:00Z\"\n    }\n  }\n}\n```\n\n### .findings/ directory\n\nStores digest-worthy findings:\n\n```\n.findings/\n├── 2026-01-22_eth-price.json\n├── 2026-01-24_fm26-patches.json\n└── 2026-01-27_ai-breakthroughs.json\n```\n\n## Best Practices\n\n1. **Start conservative** - Set `importance_threshold: medium` initially, adjust based on alert quality\n2. **Use context field** - Helps AI generate better summaries\n3. **Refine keywords** - Add negative keywords to filter noise: `\"keywords\": [\"AI\", \"-clickbait\", \"-spam\"]`\n4. **Enable learning** - Improves over time based on your behavior\n5. **Review digest weekly** - Don't ignore the digest—it surfaces patterns\n6. **Combine with personal-analytics** - Get topic recommendations based on your chat patterns\n\n## Integration with Other Skills\n\n### web-search-plus\n\nAutomatically uses intelligent routing:\n- Product/price topics → Serper\n- Research topics → Tavily  \n- Company/startup discovery → Exa\n\n### personal-analytics\n\nSuggests topics based on conversation patterns:\n> \"You've asked about Rust 12 times this month. Want me to monitor 'Rust language updates'?\"\n\n## Privacy & Security\n\n- **All data local** - No external services except search APIs\n- **State files gitignored** - Safe to use in version-controlled workspace\n- **Memory hints optional** - You control what context is shared\n- **Learning data stays local** - Never sent to APIs\n\n## Troubleshooting\n\n**No alerts being sent:**\n- Check cron is running: `crontab -l`\n- Verify channel config (Telegram chat ID, Discord webhook)\n- Run with `--dry-run --verbose` to see scoring\n\n**Too many alerts:**\n- Increase `importance_threshold`\n- Add rate limiting\n- Refine keywords (add negative filters)\n- Enable learning mode\n\n**Missing important news:**\n- Decrease `importance_threshold`\n- Increase check frequency\n- Broaden keywords\n- Check `.research_state.json` for deduplication issues\n\n**Digest not generating:**\n- Verify `.findings/` directory exists and has content\n- Check digest cron schedule\n- Run manually: `python3 scripts/digest.py --preview`\n\n## Example Workflows\n\n### Track Product Release\n\n```bash\npython3 scripts/manage_topics.py add \"iPhone 17 Release\" \\\n  --query \"iPhone 17 announcement release date\" \\\n  --keywords \"iPhone 17,Apple event,September\" \\\n  --frequency daily \\\n  --importance high \\\n  --channels telegram \\\n  --context \"Planning to upgrade from iPhone 13\"\n```\n\n### Monitor Competitor\n\n```bash\npython3 scripts/manage_topics.py add \"Competitor Analysis\" \\\n  --query \"CompetitorCo product launch funding\" \\\n  --keywords \"CompetitorCo,product,launch,Series,funding\" \\\n  --frequency weekly \\\n  --importance medium \\\n  --channels discord,email\n```\n\n### Research Topic\n\n```bash\npython3 scripts/manage_topics.py add \"Quantum Computing Papers\" \\\n  --query \"quantum computing arxiv\" \\\n  --keywords \"quantum,qubit,arxiv\" \\\n  --frequency weekly \\\n  --importance low \\\n  --channels email\n```\n\n## Credits\n\nBuilt for ClawHub. Uses web-search-plus skill for intelligent search routing.\n\nFile v1.3.3:README.md\n\n# Topic Monitor\n\n**Never miss what matters. Get alerted when it happens.**\n\nTopic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly important occurs.\n\n## Features\n\n- 🔍 **Automated Monitoring** - Scheduled web searches for your topics\n- 🧠 **AI Importance Scoring** - Smart filtering: alert vs digest vs ignore\n- 📱 **Multi-Channel Alerts** - Telegram, Discord, Email\n- 📊 **Weekly Digests** - Curated summaries of interesting findings\n- 🧩 **Memory Integration** - Contextual alerts referencing your past conversations\n- ⚡ **Rate Limiting** - Prevent alert fatigue\n- 🎯 **Custom Conditions** - Fine-tune when to alert\n\n## Quick Start\n\n### Option 1: Interactive Setup (Recommended)\n\nRun the setup wizard for a guided experience:\n\n```bash\npython3 scripts/setup.py\n```\n\nThe wizard asks friendly questions about what you want to monitor and creates your config automatically.\n\n### Option 2: Manual Setup\n\n```bash\n# 1. Copy the template\ncp config.example.json config.json\n\n# 2. Add your first topic\npython3 scripts/manage_topics.py add \"AI Models\" \\\n  --query \"new AI model release announcement\" \\\n  --keywords \"GPT,Claude,Llama,release\" \\\n  --frequency daily \\\n  --importance high \\\n  --channels telegram\n\n# 3. Test it\npython3 scripts/manage_topics.py test ai-models\n\n# 4. Set up automated monitoring\npython3 scripts/setup_cron.py\n```\n\n## Use Cases\n\n### 📈 Price Monitoring\nTrack product prices, SaaS pricing changes, or market trends with alerts on significant changes.\n\n### 🔧 Product Updates\nMonitor software releases, patches, and feature announcements.\n\n### 📰 News Tracking\nStay updated on specific topics without drowning in noise.\n\n### 🏢 Competitor Analysis\nTrack competitor product launches, funding, and news.\n\n### 🎓 Research Papers\nMonitor arXiv, GitHub, or academic publications in your field.\n\n## How It Works\n\n1. **Configure Topics** - Define what to monitor and when to alert\n2. **Scheduled Checks** - Cron jobs run searches at your chosen frequency\n3. **AI Scoring** - Each result is scored for importance\n4. **Smart Alerting** - High priority → immediate alert, Medium → digest, Low → ignore\n5. **Deduplication** - Never get the same alert twice\n\n## Configuration\n\nSee [SKILL.md](SKILL.md) for complete documentation.\n\n### Example Topic\n\n```json\n{\n  \"id\": \"ai-breakthroughs\",\n  \"name\": \"AI Research Breakthroughs\",\n  \"query\": \"artificial intelligence breakthrough research\",\n  \"keywords\": [\"AI\", \"LLM\", \"transformer\", \"AGI\"],\n  \"frequency\": \"daily\",\n  \"importance_threshold\": \"medium\",\n  \"channels\": [\"telegram\"],\n  \"context\": \"Following AI developments for work\",\n  \"alert_on\": [\"major_paper\", \"model_release\"]\n}\n```\n\n## Commands\n\n### Manage Topics\n\n```bash\n# Add topic\npython3 scripts/manage_topics.py add \"Topic Name\" \\\n  --query \"search query\" \\\n  --keywords \"word1,word2\" \\\n  --frequency daily\n\n# List topics\npython3 scripts/manage_topics.py list\n\n# Edit topic\npython3 scripts/manage_topics.py edit topic-id --frequency hourly\n\n# Remove topic\npython3 scripts/manage_topics.py remove topic-id\n\n# Test topic\npython3 scripts/manage_topics.py test topic-id\n```\n\n### Monitor\n\n```bash\n# Manual check (dry run)\npython3 scripts/monitor.py --dry-run --verbose\n\n# Check specific topic\npython3 scripts/monitor.py --topic ai-models\n\n# Check all hourly topics\npython3 scripts/monitor.py --frequency hourly\n```\n\n### Digest\n\n```bash\n# Preview this week's digest\npython3 scripts/digest.py --preview\n\n# Generate and send\npython3 scripts/digest.py --send\n```\n\n### Cron Setup\n\n```bash\n# Interactive setup\npython3 scripts/setup_cron.py\n\n# Auto-setup\npython3 scripts/setup_cron.py --auto\n\n# Remove cron jobs\npython3 scripts/setup_cron.py --remove\n```\n\n## Integration\n\n### Works With\n\n- **web-search-plus** - Intelligent search routing (Serper, Tavily, Exa)\n- **personal-analytics** - Get topic recommendations from your chat patterns\n- **OpenClaw message tool** - Send alerts via Telegram, Discord\n\n### Channel Setup\n\n#### Telegram\nConfigure in config.json:\n```json\n{\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"chat_id\": \"@your_username\"\n    }\n  }\n}\n```\n\n#### Discord\nAdd webhook URL:\n```json\n{\n  \"channels\": {\n    \"discord\": {\n      \"enabled\": true,\n      \"webhook_url\": \"https://discord.com/api/webhooks/...\"\n    }\n  }\n}\n```\n\n## Configuration via Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Telegram chat ID for alerts (required for Telegram) |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` | Directory for state and findings files |\n| `WEB_SEARCH_PLUS_PATH` | Relative to skill | Path to web-search-plus search.py script |\n\n**Example:**\n```bash\nexport TOPIC_MONITOR_TELEGRAM_ID=\"123456789\"\nexport TOPIC_MONITOR_DATA_DIR=\"/path/to/data\"\nexport WEB_SEARCH_PLUS_PATH=\"/path/to/skills/web-search-plus/scripts/search.py\"\n```\n\n## Privacy\n\n- All data stored locally\n- No external services except search APIs\n- Learning data stays on your machine\n- State files are gitignored\n- **No hardcoded personal info** — configure via environment variables\n\n## Requirements\n\n- Python 3.8+\n- Optional: web-search-plus skill (for better search)\n- Cron (for automated monitoring)\n\n## License\n\nMIT\n\n## Credits\n\nBuilt for ClawHub.\n\nFile v1.3.3:_meta.json\n\n{\n  \"ownerId\": \"kn73gpe8xz2630jrknkb3ya96h7zb84h\",\n  \"slug\": \"topic-monitor\",\n  \"version\": \"1.3.3\",\n  \"publishedAt\": 1770801770772\n}\n\nFile v1.3.3:CHANGELOG.md\n\n# Changelog\n\n## [1.3.2] - 2026-02-11\n\n### 🆕 Real Alerting System\n\nThe alerting system is now fully functional (was a stub before):\n\n- **Telegram Alerts:** Send immediate alerts for high-priority findings\n- **Multi-Channel Support:** Telegram, Discord, and Email\n- **Smart Filtering:** Importance scoring determines what gets alerted\n\n### Changed\n\n- **State Files:** Now stored in `.data/` directory (configurable via `TOPIC_MONITOR_DATA_DIR`)\n- **Telegram ID:** Configured via `TOPIC_MONITOR_TELEGRAM_ID` environment variable (no hardcoded values)\n- **web-search-plus Path:** Now relative by default, configurable via `WEB_SEARCH_PLUS_PATH`\n- **No Hardcoded Paths:** All paths and IDs are now configurable\n\n### Environment Variables\n\nNew environment variables for configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Telegram chat ID for alerts |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` | State and findings directory |\n| `WEB_SEARCH_PLUS_PATH` | Relative | Path to web-search-plus script |\n\n### Migration\n\nIf you had hardcoded paths in config.json, update to use environment variables:\n```bash\nexport TOPIC_MONITOR_TELEGRAM_ID=\"your_telegram_id\"\n```\n\n## [1.2.1] - 2026-02-04\n\n- Privacy cleanup: removed hardcoded paths and personal info from docs\n\nFile v1.3.3:config.example.json\n\n{\n  \"topics\": [\n    {\n      \"id\": \"example-topic\",\n      \"name\": \"Example Topic\",\n      \"query\": \"search query here\",\n      \"keywords\": [\"keyword1\", \"keyword2\", \"keyword3\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"medium\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Why this topic matters to you\",\n      \"alert_on\": [\"keyword_exact_match\"],\n      \"ignore_sources\": [],\n      \"boost_sources\": []\n    }\n  ],\n  \"settings\": {\n    \"digest_day\": \"sunday\",\n    \"digest_time\": \"18:00\",\n    \"max_alerts_per_day\": 5,\n    \"max_alerts_per_topic_per_day\": 2,\n    \"deduplication_window_hours\": 72,\n    \"learning_enabled\": true,\n    \"quiet_hours\": {\n      \"enabled\": false,\n      \"start\": \"22:00\",\n      \"end\": \"08:00\"\n    }\n  },\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"chat_id\": null,\n      \"silent\": false,\n      \"effects\": {\n        \"high_importance\": \"🔥\",\n        \"medium_importance\": \"📌\"\n      }\n    },\n    \"discord\": {\n      \"enabled\": false,\n      \"webhook_url\": null,\n      \"username\": \"Research Bot\",\n      \"avatar_url\": null\n    },\n    \"email\": {\n      \"enabled\": false,\n      \"to\": null,\n      \"from\": \"research@yourdomain.com\",\n      \"smtp_server\": \"smtp.gmail.com\",\n      \"smtp_port\": 587,\n      \"smtp_user\": null,\n      \"smtp_password\": null\n    }\n  }\n}\n\nFile v1.3.3:package.json\n\n{\n  \"name\": \"@openclaw/topic-monitor\",\n  \"version\": \"1.3.3\",\n  \"description\": \"Monitor topics of interest and get proactive alerts when important developments occur\",\n  \"author\": \"robbyczgw-cla\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"openclaw\",\n    \"skill\",\n    \"monitoring\",\n    \"alerts\",\n    \"research\",\n    \"proactive\",\n    \"news\",\n    \"tracking\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/robbyczgw-cla/topic-monitor.git\"\n  },\n  \"homepage\": \"https://clawhub.ai/robbyczgw-cla/topic-monitor\",\n  \"bugs\": {\n    \"url\": \"https://github.com/robbyczgw-cla/topic-monitor/issues\"\n  },\n  \"openclaw\": {\n    \"skill\": true,\n    \"triggers\": [\"monitor topic\", \"track topic\", \"topic alerts\"],\n    \"capabilities\": [\n      \"proactive-alerts\",\n      \"topic-tracking\",\n      \"digest-reports\"\n    ],\n    \"requirements\": {\n      \"bins\": [\"python3\"],\n      \"env\": {}\n    }\n  },\n  \"files\": [\n    \"SKILL.md\",\n    \"README.md\",\n    \"config.example.json\",\n    \"scripts/\"\n  ],\n  \"scripts\": {\n    \"setup\": \"python3 scripts/setup.py\",\n    \"monitor\": \"python3 scripts/monitor.py\",\n    \"digest\": \"python3 scripts/digest.py\",\n    \"topics\": \"python3 scripts/manage_topics.py\"\n  },\n  \"dependencies\": {\n    \"python\": \">=3.8\"\n  },\n  \"optionalDependencies\": {\n    \"skills\": [\"web-search-plus\"]\n  }\n}\n\nFile v1.3.3:skill.json\n\n{\n  \"name\": \"topic-monitor\",\n  \"version\": \"1.1.0\",\n  \"description\": \"Monitor topics of interest and get proactive alerts when important developments occur\",\n  \"author\": \"robbyczgw-cla\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"monitoring\",\n    \"alerts\",\n    \"research\",\n    \"proactive\",\n    \"news\",\n    \"tracking\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/robbyczgw-cla/skills\"\n  },\n  \"files\": [\n    \"SKILL.md\",\n    \"README.md\",\n    \"config.example.json\",\n    \"scripts/\"\n  ],\n  \"scripts\": {\n    \"setup\": \"python3 scripts/setup.py\",\n    \"monitor\": \"python3 scripts/monitor.py\",\n    \"digest\": \"python3 scripts/digest.py\",\n    \"topics\": \"python3 scripts/manage_topics.py\"\n  },\n  \"dependencies\": {\n    \"python\": \">=3.8\"\n  },\n  \"optional_dependencies\": {\n    \"skills\": [\"web-search-plus\"]\n  }\n}","readmeExcerpt":"Skill: Topic Monitor Owner: robbyczgw-cla Summary: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries. Tags: latest:1","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python3 scripts/quick.py \"AI Model Releases\""},{"language":"bash","snippet":"# Basic - just a topic name\npython3 scripts/quick.py \"Bitcoin Price\"\n\n# With keywords\npython3 scripts/quick.py \"Security CVEs\" --keywords \"CVE,vulnerability,critical\"\n\n# High priority, hourly checks\npython3 scripts/quick.py \"Production Alerts\" --frequency hourly --importance high\n\n# Custom query\npython3 scripts/quick.py \"Competitor News\" --query \"CompanyName product launch funding\"\n\n# Different channel\npython3 scripts/quick.py \"Team Updates\" --channel discord"},{"language":"bash","snippet":"python3 scripts/manage_topics.py edit ai-model-releases --frequency hourly"},{"language":"bash","snippet":"python3 scripts/setup.py"},{"language":"text","snippet":"🔍 Topic Monitor - Setup Wizard\n\nWhat topics do you want to monitor?\n  > AI Model Releases\n  > Security Vulnerabilities\n  > \n\n--- Topic 1/2: AI Model Releases ---\n  Search query for 'AI Model Releases' [AI Model Releases news updates]: new AI model release announcement\n  Keywords to watch for in 'AI Model Releases'?\n  > GPT, Claude, Llama, release\n\n--- Topic 2/2: Security Vulnerabilities ---\n  Search query for 'Security Vulnerabilities' [Security Vulnerabilities news updates]: CVE critical vulnerability patch\n  Keywords to watch for in 'Security Vulnerabilities'?\n  > CVE, vulnerability, critical, patch\n\nHow often should I check for updates?\n  1. hourly\n  2. daily *\n  3. weekly\n\n✅ Setup Complete!"},{"language":"bash","snippet":"# Initialize config from template\ncp config.example.json config.json\n\n# Add a topic\npython3 scripts/manage_topics.py add \"Product Updates\" \\\n  --keywords \"release,update,patch\" \\\n  --frequency daily \\\n  --importance medium\n\n# Test monitoring (dry run)\npython3 scripts/monitor.py --dry-run\n\n# Set up cron for automatic monitoring\npython3 scripts/setup_cron.py"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: topic-monitor\nversion: 1.3.4\ndescription: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\"],\"env\":{\"TOPIC_MONITOR_TELEGRAM_ID\":\"optional - Telegram chat ID for alerts\",\"TOPIC_MONITOR_DATA_DIR\":\"optional - defaults to .data/ in skill dir\",\"WEB_SEARCH_PLUS_PATH\":\"optional - defaults to relative path\"},\"note\":\"All env vars optional. Defaults work out of the box.\"}}}\n---\n\n# Topic Monitor\n\n**Monitor what matters. Get notified when it happens.**\n\nTopic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly matters.\n\n---\n\n## ⚡ Quick Start (New in v1.2.0!)\n\n**Just want to monitor one topic? One command:**\n\n```bash\npython3 scripts/quick.py \"AI Model Releases\"\n```\n\nThat's it! This creates a topic with sensible defaults:\n- **Query:** Auto-generated from topic name\n- **Keywords:** Extracted from topic name\n- **Frequency:** Daily\n- **Importance:** Medium\n- **Channel:** Telegram\n\n### Quick Start Options\n\n```bash\n# Basic - just a topic name\npython3 scripts/quick.py \"Bitcoin Price\"\n\n# With keywords\npython3 scripts/quick.py \"Security CVEs\" --keywords \"CVE,vulnerability,critical\"\n\n# High priority, hourly checks\npython3 scripts/quick.py \"Production Alerts\" --frequency hourly --importance high\n\n# Custom query\npython3 scripts/quick.py \"Competitor News\" --query \"CompanyName product launch funding\"\n\n# Different channel\npython3 scripts/quick.py \"Team Updates\" --channel discord\n```\n\n### Quick Start vs Full Setup\n\n| Feature | Quick Start | Full Setup |\n|---------|-------------|------------|\n| Speed | ⚡ 1 command | 📝 Wizard |\n| Defaults | Smart | Customizable |\n| Use case | Single topic | Multiple topics |\n| Configuration | Minimal | Full control |\n\n**After Quick Start, you can always customize:**\n```bash\npython3 scripts/manage_topics.py edit ai-model-releases --frequency hourly\n```\n\n---\n\n## Core Capabilities\n\n1. **Topic Configuration** - Define subjects with custom parameters\n2. **Scheduled Monitoring** - Automated searches at configurable intervals\n3. **AI Importance Scoring** - Smart filtering: immediate alert vs digest vs ignore\n4. **Contextual Summaries** - Not just links—meaningful summaries with context\n5. **Weekly Digest** - Low-priority findings compiled into readable reports\n6. **Memory Integration** - References your past conversations and interests\n\n---\n\n## Full Setup (Interactive Wizard)\n\nFor configuring multiple topics or advanced options:\n\n```bash\npython3 scripts/setup.py\n```\n\nThe wizard will guide you through:\n\n1. **Topics** - What subjects do you want to monitor?\n2. **Search queries*"},{"path":"README.md","content":"# Topic Monitor\n\n**Never miss what matters. Get alerted when it happens.**\n\nTopic Monitor transforms your assistant from reactive to proactive by continuously monitoring topics you care about and intelligently alerting you only when something truly important occurs.\n\n## Features\n\n- 🔍 **Automated Monitoring** - Scheduled web searches for your topics\n- 🧠 **AI Importance Scoring** - Smart filtering: alert vs digest vs ignore\n- 📱 **Multi-Channel Alerts** - Telegram, Discord, Email (agent-delivered)\n- 📊 **Weekly Digests** - Curated summaries of interesting findings\n- 🧩 **Memory Integration** - Contextual alerts referencing your past conversations\n- ⚡ **Rate Limiting** - Prevent alert fatigue\n- 🎯 **Custom Conditions** - Fine-tune when to alert\n\n## Quick Start\n\n### Option 1: Interactive Setup (Recommended)\n\nRun the setup wizard for a guided experience:\n\n```bash\npython3 scripts/setup.py\n```\n\nThe wizard asks friendly questions about what you want to monitor and creates your config automatically.\n\n### Option 2: Manual Setup\n\n```bash\n# 1. Copy the template\ncp config.example.json config.json\n\n# 2. Add your first topic\npython3 scripts/manage_topics.py add \"AI Models\" \\\n  --query \"new AI model release announcement\" \\\n  --keywords \"GPT,Claude,Llama,release\" \\\n  --frequency daily \\\n  --importance high \\\n  --channels telegram\n\n# 3. Test it\npython3 scripts/manage_topics.py test ai-models\n\n# 4. Set up automated monitoring\npython3 scripts/setup_cron.py\n```\n\n## Use Cases\n\n### 📈 Price Monitoring\nTrack product prices, SaaS pricing changes, or market trends with alerts on significant changes.\n\n### 🔧 Product Updates\nMonitor software releases, patches, and feature announcements.\n\n### 📰 News Tracking\nStay updated on specific topics without drowning in noise.\n\n### 🏢 Competitor Analysis\nTrack competitor product launches, funding, and news.\n\n### 🎓 Research Papers\nMonitor arXiv, GitHub, or academic publications in your field.\n\n## How It Works\n\n1. **Configure Topics** - Define what to monitor and when to alert\n2. **Scheduled Checks** - Cron jobs run searches at your chosen frequency\n3. **AI Scoring** - Each result is scored for importance\n4. **Smart Alerting** - High priority → immediate alert, Medium → digest, Low → ignore\n5. **Deduplication** - Never get the same alert twice\n\n## Configuration\n\nSee [SKILL.md](SKILL.md) for complete documentation.\n\n### Example Topic\n\n```json\n{\n  \"id\": \"ai-breakthroughs\",\n  \"name\": \"AI Research Breakthroughs\",\n  \"query\": \"artificial intelligence breakthrough research\",\n  \"keywords\": [\"AI\", \"LLM\", \"transformer\", \"AGI\"],\n  \"frequency\": \"daily\",\n  \"importance_threshold\": \"medium\",\n  \"channels\": [\"telegram\"],\n  \"context\": \"Following AI developments for work\",\n  \"alert_on\": [\"major_paper\", \"model_release\"]\n}\n```\n\n## Commands\n\n### Manage Topics\n\n```bash\n# Add topic\npython3 scripts/manage_topics.py add \"Topic Name\" \\\n  --query \"search query\" \\\n  --keywords \"word1,word2\" \\\n  --frequency daily\n\n# List topics\npython3 scripts/manage_topics.py li"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn73gpe8xz2630jrknkb3ya96h7zb84h\",\n  \"slug\": \"topic-monitor\",\n  \"version\": \"1.3.4\",\n  \"publishedAt\": 1770804279101\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n## [1.3.3] - 2026-02-11\n\n### Changed\n\n- **Subprocess env hardening:** `monitor.py` now uses an allowlist for web-search-plus subprocess environment (`PATH`, `HOME`, `LANG`, `TERM` + search provider keys only).\n- **Discord delivery flow:** Removed webhook-style delivery from skill docs/flow; Discord alerts are now emitted as structured JSON (`DISCORD_ALERT`) for OpenClaw agent delivery (same pattern as Telegram).\n- **No direct HTTP calls:** Alerting/search integration is documented as agent-mediated JSON output + subprocess execution, without direct outbound HTTP from topic-monitor skill code.\n\n## [1.3.2] - 2026-02-11\n\n### 🆕 Real Alerting System\n\nThe alerting system is now fully functional (was a stub before):\n\n- **Telegram Alerts:** Send immediate alerts for high-priority findings\n- **Multi-Channel Support:** Telegram, Discord, and Email\n- **Smart Filtering:** Importance scoring determines what gets alerted\n\n### Changed\n\n- **State Files:** Now stored in `.data/` directory (configurable via `TOPIC_MONITOR_DATA_DIR`)\n- **Telegram ID:** Configured via `TOPIC_MONITOR_TELEGRAM_ID` environment variable (no hardcoded values)\n- **web-search-plus Path:** Now relative by default, configurable via `WEB_SEARCH_PLUS_PATH`\n- **No Hardcoded Paths:** All paths and IDs are now configurable\n\n### Environment Variables\n\nNew environment variables for configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOPIC_MONITOR_TELEGRAM_ID` | — | Telegram chat ID for alerts |\n| `TOPIC_MONITOR_DATA_DIR` | `.data/` | State and findings directory |\n| `WEB_SEARCH_PLUS_PATH` | Relative | Path to web-search-plus script |\n\n### Migration\n\nIf you had hardcoded paths in config.json, update to use environment variables:\n```bash\nexport TOPIC_MONITOR_TELEGRAM_ID=\"your_telegram_id\"\n```\n\n## [1.2.1] - 2026-02-04\n\n- Privacy cleanup: removed hardcoded paths and personal info from docs"},{"path":"config.example.json","content":"{\n  \"topics\": [\n    {\n      \"id\": \"example-topic\",\n      \"name\": \"Example Topic\",\n      \"query\": \"search query here\",\n      \"keywords\": [\"keyword1\", \"keyword2\", \"keyword3\"],\n      \"frequency\": \"daily\",\n      \"importance_threshold\": \"medium\",\n      \"channels\": [\"telegram\"],\n      \"context\": \"Why this topic matters to you\",\n      \"alert_on\": [\"keyword_exact_match\"],\n      \"ignore_sources\": [],\n      \"boost_sources\": []\n    }\n  ],\n  \"settings\": {\n    \"digest_day\": \"sunday\",\n    \"digest_time\": \"18:00\",\n    \"max_alerts_per_day\": 5,\n    \"max_alerts_per_topic_per_day\": 2,\n    \"deduplication_window_hours\": 72,\n    \"learning_enabled\": true,\n    \"quiet_hours\": {\n      \"enabled\": false,\n      \"start\": \"22:00\",\n      \"end\": \"08:00\"\n    }\n  },\n  \"channels\": {\n    \"telegram\": {\n      \"enabled\": true,\n      \"chat_id\": null,\n      \"silent\": false,\n      \"effects\": {\n        \"high_importance\": \"🔥\",\n        \"medium_importance\": \"📌\"\n      }\n    },\n    \"discord\": {\n      \"enabled\": false,\n      \"webhook_url\": null,\n      \"username\": \"Research Bot\",\n      \"avatar_url\": null\n    },\n    \"email\": {\n      \"enabled\": false,\n      \"to\": null,\n      \"from\": \"research@yourdomain.com\",\n      \"smtp_server\": \"smtp.gmail.com\",\n      \"smtp_port\": 587,\n      \"smtp_user\": null,\n      \"smtp_password\": null\n    }\n  }\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries. Skill: Topic Monitor Owner: robbyczgw-cla Summary: Monitor topics of interest and proactively alert when important developments occur. Use when user wants automated monitoring of specific subjects (e.g., product releases, price changes, news topics, technology updates). Supports scheduled web searches, AI-powered importance scoring, smart alerts vs weekly digests, and memory-aware contextual summaries. Tags: latest:1","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1254,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-04-15T00:45:39.800Z","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-04-15T00:45:39.800Z","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":"agent-directory","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:08:16.354Z","emptyReason":"No close protocol neighbors were found."},"items":[],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[]}}}