# Jeremylongshore Claude Code Plugins Plus Skills Exa Architecture Variants > Exa Architecture Variants - Skill: `tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-exa-architec` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-exa-architec` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-exa-architec/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-exa-architec --- # Exa Architecture Variants ## Overview Three deployment architectures for Exa neural search at different scales. Each uses real Exa SDK methods: `search`, `searchAndContents`, `findSimilar`, `getContents`, and `answer`. ## Decision Matrix | Factor | Direct Search | Cached Search | RAG Pipeline | |--------|--------------|---------------|--------------| | Volume | < 1K/day | 1K-50K/day | Any volume | | Latency | 500-2000ms | ~50ms (cached) | 3-8s total | | Use Case | Simple search UI | Content aggregation | AI answers with citations | | Complexity | Low | Medium | High | | Cache Required | No | Yes (Redis/LRU) | Yes | | Exa Methods | `searchAndContents` | `searchAndContents` + cache | All methods | ## Instructions ### Variant 1: Direct Search Integration **Best for:** Adding search to an existing app, < 1K queries/day. ```typescript import Exa from "exa-js"; import express from "express"; const app = express(); const exa = new Exa(process.env.EXA_API_KEY); // Simple search endpoint app.get("/api/search", async (req, res) => { const query = req.query.q as string; if (!query) return res.status(400).json({ error: "q required" }); try { const results = await exa.searchAndContents(query, { type: "auto", numResults: 5, text: { maxCharacters: 500 }, highlights: { maxCharacters: 300, query }, }); res.json(results.results.map(r => ({ title: r.title, url: r.url, snippet: r.highlights?.join(" ") || r.text?.substring(0, 200), score: r.score, }))); } catch (err: any) { res.status(err.status || 500).json({ error: err.message }); } }); ``` ### Variant 2: Cached Search with Category Profiles **Best for:** High-traffic search, 1K-50K queries/day, content discovery. ```typescript import Exa from "exa-js"; import { LRUCache } from "lru-cache"; const exa = new Exa(process.env.EXA_API_KEY); const cache = new LRUCache({ max: 5000, ttl: 3600 * 1000 }); const PROFILES = { news: { type: "auto" as const, category: "news" as const, numResults: 10, text: { maxCharacters: 500 }, }, research: { type: "neural" as const, category: "research paper" as const, numResults: 10, text: { maxCharacters: 2000 }, highlights: { maxCharacters: 500 }, }, companies: { type: "auto" as const, category: "company" as const, numResults: 10, text: { maxCharacters: 500 }, }, }; async function cachedProfileSearch( query: string, profile: keyof typeof PROFILES ) { const key = `${query.toLowerCase()}:${profile}`; const cached = cache.get(key); if (cached) return cached; const results = await exa.searchAndContents(query, PROFILES[profile]); cache.set(key, results); return results; } ``` ### Variant 3: Full RAG Pipeline **Best for:** AI-powered answers, research agents, 50K+ queries/day. ```typescript import Exa from "exa-js"; import { LRUCache } from "lru-cache"; const exa = new Exa(process.env.EXA_API_KEY); const contextCache = new LRUCache({ max: 10000, ttl: 7200 * 1000 }); class ExaRAGPipeline { // Phase 1: Search for relevant sources async gatherContext(question: string, maxSources = 5) { const cacheKey = question.toLowerCase().trim(); const cached = contextCache.get(cacheKey); if (cached) return cached; const results = await exa.searchAndContents(question, { type: "neural", numResults: maxSources, text: { maxCharacters: 2000 }, highlights: { maxCharacters: 500, query: question }, }); contextCache.set(cacheKey, results); return results; } // Phase 2: Expand with similar content async expandContext(topResultUrl: string, numSimilar = 3) { return exa.findSimilarAndContents(topResultUrl, { numResults: numSimilar, text: { maxCharacters: 1500 }, excludeSourceDomain: true, }); } // Phase 3: Format for LLM context injection formatForLLM(results: any[]) { return results.map((r, i) => `[Source ${i + 1}] ${r.title}\n` + `URL: ${r.url}\n` + `Content: ${r.text}\n` + `Key points: ${r.highlights?.join(" | ") || "N/A"}` ).join("\n\n---\n\n"); } // Phase 4: Use Exa's built-in answer endpoint async getAnswer(question: string) { const answer = await exa.answer(question, { text: true }); return { answer: answer.answer, sources: answer.results.map(r => ({ title: r.title, url: r.url, })), }; } // Full pipeline async research(question: string) { const context = await this.gatherContext(question, 5); // Expand with similar content from top result let expanded = { results: [] as any[] }; if (context.results[0]?.url) { expanded = await this.expandContext(context.results[0].url); } const allResults = [...context.results, ...expanded.results]; const llmContext = this.formatForLLM(allResults); return { context: llmContext, sourceCount: allResults.length, sources: allResults.map(r => ({ title: r.title, url: r.url, score: r.score })), }; } } ``` ## Scaling Notes | Architecture | 10 QPS Limit Strategy | |-------------|----------------------| | Direct | Natural limit: ~864K searches/day at full rate | | Cached | 50% cache hit = ~1.7M effective searches/day | | RAG Pipeline | 2-3 API calls per question; cache aggressively | ## Error Handling | Issue | Cause | Solution | |-------|-------|----------| | Slow search in UI | No caching | Add LRU or Redis cache | | Stale cached results | Long TTL | Reduce TTL for time-sensitive profiles | | RAG hallucination | Poor source selection | Use highlights, increase numResults | | High API costs | No query deduplication | Cache layer deduplicates identical queries | ## Resources - [Exa API Documentation](https://docs.exa.ai) - [Exa Contents Retrieval](https://docs.exa.ai/reference/contents-retrieval) - [Exa Find Similar](https://docs.exa.ai/reference/find-similar-links) ## Next Steps For reference architecture details, see `exa-reference-architecture`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jeremylongshore) — claim your Tome and manage your conversions.