Agentic Search

An agentic search platform that uses iterative reasoning and structured memory to answer complex queries. Built with SearXNG, Claude, TypeScript, and Redis.

Unlike traditional RAG (single retrieval pass), this system plans sub-queries, searches across multiple engines, evaluates whether results are sufficient, and iterates until it has comprehensive coverage. A three-tier memory layer (working memory, episodic memory, semantic memory) ensures the agent doesn't lose context across iterations or follow-up queries.

Architecture

Query -> Planner -> Search (SearXNG) -> Reasoner -> [Insufficient? -> Search again] -> Synthesize
                                                          |
                                                    Memory Layer
                                                 (Working + Episodic)

Planner - Decomposes queries into focused, search-engine-friendly sub-queries using Claude.

Search Layer - Executes sub-queries against SearXNG, which fans out to Google, Bing, DuckDuckGo, ArXiv, and more in parallel. Results are deduplicated and scored.

Reasoner - Evaluates result coverage, quality, and freshness. Decides whether to iterate or synthesize. Produces a cited answer from all collected results.

Memory Layer - Working memory tracks state within a single query. Episodic memory (Redis) persists session history across queries, enabling follow-ups like "How does Perplexity implement it?" after asking "What is agentic search?"

Prerequisites

• Node.js >= 22.0.0
• Docker and Docker Compose
• Anthropic API key

Quick Start

# 1. Clone the repo
git clone https://github.com/nihalwashere/agentic-search.git
cd agentic-search

# 2. Set up environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# 3. Use the correct Node version
nvm use

# 4. Install dependencies
npm install

# 5. Start SearXNG and Redis
cd docker && docker compose up -d && cd ..

# 6. Verify infrastructure
npm run verify

# 7. Build and run the server
npm run build && npm run serve

The server starts on http://localhost:3000.

API Endpoints

Method	Endpoint	Description
POST	/sessions	Create a new session
POST	/sessions/:id/search	Search within a session
GET	/sessions/:id	Get session history
DELETE	/sessions/:id	Delete a session

Example Usage

# Create a session
curl -s -X POST http://localhost:3000/sessions | jq
# Returns: { "sessionId": "abc123..." }

# Search
curl -s -X POST http://localhost:3000/sessions/SESSION_ID/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "What is agentic search?"}' | jq

# Follow-up (episodic memory carries context)
curl -s -X POST http://localhost:3000/sessions/SESSION_ID/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "How does Perplexity implement it?"}' | jq

# View session history
curl -s http://localhost:3000/sessions/SESSION_ID | jq

A Postman collection is included at agentic-search.postman_collection.json. Import it and the sessionId auto-populates after creating a session.

Running the Example Script

npm run build && node dist/examples/basic-search.js

This runs a single query ("What is agentic search and how does it differ from RAG?") and prints the full result with citations and metadata.

Configuration

All configuration is via environment variables. See .env.example for the full list.

Variable	Default	Description
ANTHROPIC_API_KEY	(required)	Your Anthropic API key
SEARXNG_URL	http://localhost:8080	SearXNG instance URL
REDIS_URL	redis://localhost:6379	Redis instance URL
MAX_ITERATIONS	3	Max search iterations before forcing synthesis
REQUEST_TIMEOUT_MS	30000	Request timeout in milliseconds
CLAUDE_MODEL	claude-sonnet-4-20250514	Claude model to use
LOG_LEVEL	info	Log level (debug, info, warn, error)
ENABLE_EPISODIC_MEMORY	true	Enable Redis-backed session memory
PORT	3000	Server port

Project Structure

src/
  agents/          # Planner, Reasoner, and Orchestrator
  llm/             # Claude client and prompt templates
  memory/          # Working memory and episodic memory stores
  search/          # SearXNG client and result processor
  utils/           # Config, logging
  server.ts        # Express API server
examples/          # Example usage script
scripts/           # Setup and verification scripts
docker/            # Docker Compose and SearXNG config

How It Works

1. A query arrives. The Planner decomposes it into 1-5 focused sub-queries.
2. Sub-queries are executed in parallel against SearXNG (which queries Google, Bing, DuckDuckGo, ArXiv, etc.).
3. Results are deduplicated, scored, and stored in working memory.
4. The Reasoner evaluates coverage: are all aspects of the query answered?
5. If not, the Reasoner generates targeted follow-up queries and the loop repeats (max 3 iterations).
6. Once sufficient, the Reasoner synthesizes a final answer with inline citations.
7. The full interaction is saved to episodic memory (Redis), so follow-up queries have context.

Stopping Services

cd docker && docker compose down