---

💡 Why Annolux?

Current web search APIs for AI agents suffer from three fatal flaws:

1. Garbage in, garbage out: Commercial search engines index millions of SEO farms, scraped spam, and auto-generated noise that pollute LLM context windows.
2. Missing time-provenance: LLMs hallucinate current state because search APIs omit the exact snapshot timestamp (fetched_at).
3. Predatory billing: Paying full price for failed requests, empty outputs, or rate-limited retries.

Annolux solves this with an agent-first curated approach:

• 🛡️ Curated Bilingual Technical Index: High-signal English & Chinese corpus (Rust, Go, Python, AI/ML, Official Docs, RFCs, GitHub, arXiv).
• 🕒 Explicit fetched_at Timestamp: Every ranked hit reveals the exact second it was ingested—enabling grounded citations and temporal reasoning.
• 🎯 Predictable Ledger Billing: Exactly 1 credit per successful 2xx response. Errors, timeouts (504), rate limits (429), and bad requests cost 0 credits.
• 🧩 Native Model Context Protocol (MCP): Zero setup across Claude Code, Cursor, Windsurf, Cline, Zed, and Claude Desktop.
• 🚀 1,000 Free Credits Every Month: Sign in with GitHub or Google at annolux.com and start querying in 30 seconds.

---

🥊 Comparison: Annolux vs. Generic Search APIs

---

📦 Quick Installation

Node.js 18+ is the only prerequisite. Start in the zero-config sandbox—no account or API key is required:

npx -y annolux-mcp

For the full monthly allowance, create a free key at annolux.com and pass it through the process environment:

ANNOLUX_API_KEY=ann_live_YOUR_API_KEY npx -y annolux-mcp

---

🔌 MCP Integration

Annolux implements the official Model Context Protocol (MCP) specification with a single, high-efficiency tool: search_web.

⚡ 1-Click Installation (Cursor & Smithery)

• Cursor: Click to install natively via deep link.
• Smithery CLI:

  npx -y @smithery/cli install annolux-mcp --client claude
  npx -y @smithery/cli install annolux-mcp --client cursor
  

• Glama Online Playground: Test queries instantly without local setup on Glama.ai.

1. Claude Code

claude mcp add annolux -- npx -y annolux-mcp

This starts in sandbox mode. To use an account key, add it with -e ANNOLUX_API_KEY=ann_live_YOUR_API_KEY before --.

2. Cursor / Windsurf

Add to your project .cursor/mcp.json or global configuration:

{
  "mcpServers": {
    "annolux": {
      "command": "npx",
      "args": ["-y", "annolux-mcp"],
      "env": {
        "ANNOLUX_API_KEY": "ann_live_YOUR_API_KEY"
      }
    }
  }
}

3. Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "annolux": {
      "command": "npx",
      "args": ["-y", "annolux-mcp"],
      "env": {
        "ANNOLUX_API_URL": "https://api.annolux.com",
        "ANNOLUX_API_KEY": "ann_live_YOUR_API_KEY"
      }
    }
  }
}

---

🚀 HTTP API Quickstart

Standard Search Endpoint

POST https://api.annolux.com/api/v1/search
Authorization: Bearer ann_live_YOUR_API_KEY
Content-Type: application/json

{
  "query": "tokio async runtime memory model",
  "domains": ["tokio.rs", "docs.rs", "github.com"],
  "deduplicate": true,
  "limit": 5,
  "timeout": 10,
  "ranking": "default"
}

Python

import os
import requests

response = requests.post(
    "https://api.annolux.com/api/v1/search",
    headers={"Authorization": f"Bearer {os.environ.get('ANNOLUX_API_KEY')}"},
    json={
        "query": "DeepSeek R1 architecture reinforcement learning",
        "limit": 5,
        "deduplicate": True
    },
    timeout=15
)

data = response.json()
for result in data.get("results", []):
    print(f"[{result['fetched_at']}] {result['title']} -> {result['url']}")

TypeScript / Node.js

const res = await fetch("https://api.annolux.com/api/v1/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ANNOLUX_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "vLLM PagedAttention implementation details",
    limit: 5,
    deduplicate: true
  })
});

const data = await res.json();
console.log(`Credits Remaining: ${res.headers.get("X-Annolux-Credits-Remaining")}`);
console.log(data.results);

cURL

curl -s -X POST https://api.annolux.com/api/v1/search \
  -H "Authorization: Bearer ann_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Go sync.Pool benchmark best practices",
    "limit": 3
  }' | jq .

---

🏛️ Architecture & Mechanics

┌─────────────────────────────────────────────────────────────┐
│                 AI Agent / RAG Application                  │
│       (Claude Code / Cursor / LangChain / Custom LLM)       │
└──────────────────────────────┬──────────────────────────────┘
                               │
               Stdio MCP / HTTPS REST Request
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  Annolux Gateway API Engine                 │
│  ┌─────────────────────────┐     ┌───────────────────────┐  │
│  │ 1. Account & Rate Limit │ ──► │ Reserve 1 Credit      │  │
│  │    (5 RPS, Burst 10)    │     │ in /data/accounts.db  │  │
│  └─────────────────────────┘     └───────────────────────┘  │
│                                              │              │
│                                              ▼              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 2. Bilingual FTS Ranker (/data/index.db)              │  │
│  │    • Curated English & Chinese Corpus                 │  │
│  │    • SimHash Content-Deduplication Engine             │  │
│  │    • Domain Filter & Exact Substring Match            │  │
│  └───────────────────────────────────────────────────────┘  │
│                                              │              │
│                                              ▼              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 3. Atomic Response & Ledger Settlement                │  │
│  │    • 2xx Success ──► Commit 1 Credit & Attach Timing  │  │
│  │    • 4xx/5xx Err ──► Release Reservation (0 Cost)     │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────┘
                               │
          JSON with exact `fetched_at` & verified URL
                               │
                               ▼
                     [ Grounded LLM Response ]

---

📊 Search Quality & Frozen Benchmarks

Annolux evaluates search retrieval performance against an immutable, frozen blind set of 40 complex bilingual queries. The ranking weights are never tuned on the test set.

All benchmarks are evaluated client-side under full concurrency load.

---

💳 Transparent Pricing

• No overage charges.
• Errors, rate-limits, and timeouts are 100% free (0 credit charged).
• Up to 3 active API keys per account.

---

📁 Examples & Recipes

Check the examples/ directory for production-ready starters:

• 01-claude-code-literature-research: Automated technical survey agent with timestamped citations.
• 02-cursor-authority-domain-refactor: Restrict search to official doc domains (react.dev, go.dev) for zero-hallucination refactoring.
• 03-production-rag-temporal-pipeline: Production RAG hybrid search pipeline with fallback retrieval.
• 04-n8n-ai-research-agent: Ready-to-import n8n AI Agent workflow with community node (n8n-nodes-annolux) and temporal citations.

---

🤝 Community & Support

• File bug reports or feature requests on GitHub Issues.
• Review SECURITY.md for private vulnerability reporting.
• Public OpenAPI specification: annolux.com/openapi.json.

---

📄 License

Annolux is open-source software licensed under the Apache License, Version 2.0.