{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/hero.jpg?v=6d74a19\" alt=\"Free Search Aggregator\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">Free Search Aggregator</h1>\n\n<p align=\"center\">\nQuota-aware web search for OpenClaw with 12 providers, automatic failover,\ntask-level multi-query search, and managed storage under <code>memory/</code>.\n</p>\n\n## What’s New (v1.2.x)\n\n- Expanded provider pool to **12 providers**\n- Added: **Exa, Bing RSS, Mojeek, Wikipedia, Google CSE, Baidu, SearXNG**\n- Introduced clearer quota capability mapping for new providers\n- Updated docs and setup guidance for API + no-key providers\n- Smoke-tested core flow (`status/search/task/remaining/storage`) after rollout\n\n---\n\n## Highlights\n\n- **12 providers** (6 work without API keys)\n- **Auto failover** when provider fails (auth/rate/network/upstream)\n- **Task search** (`task`) with query expansion + deduped merged results\n- **Quota controls**: tracked quota + real quota (supported providers)\n- **Preset modes**:\n  - default: `workers=1`\n  - `@dual`: `workers=2`\n  - `@deep`: `workers=3` + deeper query coverage\n- **Managed storage** (cache/index/report) to avoid workspace clutter\n\n---\n\n## Provider Matrix\n\n| Provider | Key Required | Free Quota | Notes |\n|---|---|---:|---|\n| `brave` | `BRAVE_API_KEY` | 2000/day | Independent index, high quality |\n| `exa` | `EXA_API_KEY` | ~33/day (1000/month) | Semantic search |\n| `tavily` | `TAVILY_API_KEY` | 1000/day | AI-agent optimized |\n| `duckduckgo` | No | ~500/day | Privacy-first fallback |\n| `bing_html` | No | ~300/day | Bing RSS endpoint (stable XML) |\n| `mojeek` | Optional (`MOJEEK_API_KEY`) | ~200/day | Independent index |\n| `serper` | `SERPER_API_KEY` | 2500/day | Google-backed results |\n| `searchapi` | `SEARCHAPI_API_KEY` | 100/month | Multi-engine API |\n| `google_cse` | `GOOGLE_API_KEY` + `GOOGLE_CX` | 100/day | Official Google CSE |\n| `baidu` | `BAIDU_API_KEY` | 200/day | Strong CN coverage |\n| `wikipedia` | No | ~1000/day | Factual/encyclopedic |\n| `searxng` | No (self-hosted) | depends | Requires private instance |\n\n> With all keys configured, total tracked daily capacity is ~8400+.\n\n---\n\n## Quick Start\n\n```bash\n# Normal search\nscripts/search \"latest ai agent frameworks 2026\" --max-results 5\n\n# Task-level search\nscripts/search task \"@dual Compare Claude vs GPT-4 for code generation\" --max-results 5\n\n# Deep task search\nscripts/search task \"@deep autonomous driving safety 2026\" --max-results 8 --max-queries 10\n\n# Tracked quota status\nscripts/status\n\n# Real quota (supported providers)\nscripts/remaining --real\n\n# Optional probe for header-only providers (may consume quota)\nscripts/remaining --real --probe\n\n# Cleanup old cache files (default: 14 days)\nscripts/gc --cache-days 14\n```\n\n---\n\n## CLI\n\n```bash\npython -m free_search \"<query>\"\npython -m free_search task \"<task>\" [--workers 1|2|3] [--max-queries N]\npython -m free_search status [--real] [--probe]\npython -m free_search remaining --real [--probe]\npython -m free_search gc --cache-days 14 [--report-days 90]\n```\n\n---\n\n## Python API\n\n```python\nfrom free_search import search, task_search, get_quota_status, get_real_quota\n\npayload = search(\"latest LLM eval benchmark\", max_results=5)\n\ntask_payload = task_search(\n    \"Compare Claude vs GPT-4 for code generation\",\n    max_results_per_query=5,\n    max_queries=6,\n    max_workers=2,\n)\n\nstatus = get_quota_status()\nreal = get_real_quota()\n```\n\n---\n\n## Post-install Smoke Check (Recommended)\n\n```bash\n# 1) Config/provider load\nscripts/status --compact\n\n# 2) Basic search smoke test\nscripts/search \"openclaw\" --max-results 3 --compact\n\n# 3) Verify storage paths\nls -la /home/openclaw/.openclaw/workspace/memory/search-cache/ | tail -n 5\nls -la /home/openclaw/.openclaw/workspace/memory/search-index/\nls -la /home/openclaw/.openclaw/workspace/memory/search-reports/ | tail -n 5\n\n# 4) Optional real quota check\nscripts/remaining --real --compact\n```\n\n---\n\n## Data Organization (Managed)\n\nAll artifacts are persisted under `memory/`:\n\n- `memory/search-cache/YYYY-MM-DD/*.json` — raw cache\n- `memory/search-index/search-index.jsonl` — append-only index\n- `memory/search-reports/YYYY-MM-DD/*.md` — human-readable reports\n\nRecommended retention:\n\n- cache: **14 days**\n- reports: **long-term**\n\n---\n\n## Real Quota Support\n\n| Provider | Real quota support |\n|---|---|\n| Tavily | ✅ official usage endpoint |\n| SearchAPI | ✅ official account endpoint |\n| Brave | ⚠ via `--probe` header check |\n| Serper | ❌ no public endpoint |\n| DuckDuckGo / Bing / Mojeek / Wikipedia | N/A |\n| Exa / Google CSE / Baidu | ❌ no public quota endpoint |\n\n---\n\n## Notes\n\n- `@deep` optimizes for **coverage depth**, not brute-force burn.\n- If quota usage gets high, concurrency may auto-downgrade.\n- Keep `workers=1` for default workflows, enable `@dual/@deep` only when needed.\n",
  "bytes": 4797,
  "sha": "c5e800e128c487b0d3f2ab2f8272f8914e78accebe616c8651e4cc5a28e79c47",
  "repo_slug": "vulcanusalex/free-search-aggregator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_vulcanusalex_free_search_aggregator_free_00f4466b/readme"
}