probe-search 0.2.1

AI Agent Context Engine — give your coding agent a brain beyond code

probe

Give your AI agent a brain beyond code.

probe is a CLI tool and MCP server that indexes your project's documentation, specs, and code, then serves curated, reranked context to AI coding agents in milliseconds.

---

The Problem

AI coding agents waste time searching. When you ask Claude Code or Cursor "how does our auth flow work?", they grep through files, read them one by one, and piece together an answer over multiple tool calls. On a large project with docs, specs, ADRs, and runbooks, this takes 30-60 seconds and often misses the most relevant context entirely.

probe makes this instant. It indexes everything -- markdown docs, code, PDFs, plain text -- into a hybrid search engine powered by ZeroEntropy's state-of-the-art embedding and reranking models. One query, one API call, sub-second results with the best context from docs AND code ranked together.

---

Quick Start

# 1. Get a free API key at https://dashboard.zeroentropy.dev
# 2. Install
pip install probe-search

# 3. Register probe with Claude Code (one-time, machine-wide)
probe install

# Now open any project in Claude Code and ask a question —
# probe will auto-index on first search and refresh on subsequent ones.

For CLI-only use:

export ZEROENTROPY_API_KEY="ze_xxx"
probe index .
probe search "how does authentication work"

The index auto-refreshes before each search; set PROBE_REFRESH_TTL=0 to force refresh every time, or -1 to disable refresh.

---

MCP Server Setup (Claude Code, Cursor)

Claude Code users: probe install (see Quick Start) does this automatically.

For Cursor or advanced use: add a .mcp.json file to your project root:

{
  "mcpServers": {
    "probe": {
      "command": "uvx",
      "args": ["probe-search", "mcp"],
      "env": {
        "ZEROENTROPY_API_KEY": "ze_xxx"
      }
    }
  }
}

This works with Claude Code, Cursor, and any MCP-compatible agent. No pip install required -- uvx handles it.

On first use, probe automatically indexes your project. No manual setup needed -- just ask your agent a question and it works.

Your agent gains four tools:

Tool	What it does
probe_search	Semantic search across docs and code with reranking
probe_index	Index or re-index project files
probe_status	Show what's indexed
probe_read	Read a specific file by path

---

How It Works

1. Hybrid Retrieval Each query runs through two parallel search paths: semantic vector search (cosine similarity against zembed-1 embeddings) and keyword search (BM25 via SQLite FTS5). This catches both conceptual matches and exact term hits.

2. Cross-Source Reranking Results from both paths are fused using Reciprocal Rank Fusion, then passed through zerank-2, a neural cross-encoder reranker that scores each chunk against the original query. Docs and code are ranked together -- the best answer wins regardless of file type.

3. Smart Context Assembly Results are deduplicated, trimmed to your token budget, and returned with source citations. Each result includes its file path, location metadata (header paths for markdown, symbol names for code, page numbers for PDFs), and a relevance score.

---

Example Output

$ probe search "how does authentication work"

 Found 5 results (342 chunks searched)

 [0.94] docs/design/auth.md > Authentication > OAuth Flow
   We use PKCE-based OAuth 2.0 with Auth0 as the identity provider.
   The flow works as follows: 1) Client generates a code verifier
   and challenge, 2) User is redirected to Auth0's /authorize...

 [0.87] src/auth/oauth.py > class OAuthHandler
   class OAuthHandler:
       """Handles OAuth2 PKCE flow for web and mobile clients."""
       def __init__(self, client_id: str, redirect_uri: str):
           self.client_id = client_id...

 [0.82] docs/adr/003-auth-provider.md > ADR-003: Auth Provider Selection
   ## Decision
   We chose Auth0 over Cognito because: 1) Better PKCE support,
   2) Built-in MFA, 3) Superior documentation...

 ------------------------------------------
 zembed-1 + zerank-2 | 1,847 tokens | 0.3s

One query returns the design spec, the implementation code, and the architectural decision record -- ranked by relevance, in under a second.

---

CLI Reference

Command	Description
probe index [paths...]	Index project files for semantic search
probe index --full	Force full re-index (ignore file hashes)
probe install	Register probe as a user-scope MCP server in Claude Code
probe search "query"	Search project knowledge with natural language
probe search --top-k N	Limit number of results (default: 10)
probe search --type code	Filter by file type (markdown, code, pdf, text)
probe search --no-rerank	Skip reranking (faster, lower quality)
probe search --max-tokens N	Token budget for results (default: 4096)
probe status	Show index stats and provider config
probe list	List all indexed files
probe config	Show current provider configuration
probe init	Auto-detect provider and save config
probe mcp	Start MCP server (stdio transport)
probe uninstall [--purge]	Unregister probe; --purge also deletes .probe/ in cwd

---

Multi-Provider Support

probe defaults to ZeroEntropy but works with other providers:

Provider	Embedding	Reranker	Install
ZeroEntropy (default)	zembed-1	zerank-2	included
OpenAI	text-embedding-3-large	--	pip install "probe-search[openai]"
Cohere	embed-v4.0	rerank-v3.5	pip install "probe-search[cohere]"

Set the corresponding API key (ZEROENTROPY_API_KEY, OPENAI_API_KEY, or COHERE_API_KEY) and run probe init. You can mix providers -- for example, OpenAI for embeddings with ZeroEntropy for reranking.

---

Why ZeroEntropy?

zembed-1 is a 4B-parameter open-weight embedding model that outperforms OpenAI, Cohere, and Voyage across nine domains including code, legal, finance, and healthcare. Combined with zerank-2 for cross-encoder reranking, it delivers the best retrieval quality available.

Pricing: $0.05 per 1M tokens for embeddings, $0.025 per 1M tokens for reranking. Free trial available.

---

Configuration

probe stores its index and config in .probe/ at your project root. Add it to .gitignore.

# .probe/config.yaml
providers:
  embedding:
    name: zeroentropy
    model: zembed-1
    dimensions: 1280
  reranker:
    name: zeroentropy
    model: zerank-2

---

How Data Is Handled

Documents are chunked and stored locally in .probe/ (SQLite + numpy). Only chunk text is sent to the embedding/reranking API for processing. Documents are never uploaded or stored on any external server.

---

What's NOT in v1

• Web sources (Notion, Confluence, Google Docs)
• Git-aware context (commit history, blame)
• Image/diagram understanding within PDFs
• Custom chunking strategies

---

Links

• ZeroEntropy -- the AI retrieval engine powering probe
• API Dashboard -- get your API key
• Documentation -- ZeroEntropy API docs
• Models -- zembed-1 and zerank-2 details

---

License

MIT -- see LICENSE for details.