# magpie-search

A local search engine for your AI agent. One call fans out across transcripts, project files, a knowledge graph, vectors and the web, then returns ranked hits.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 28
- Author: xfloukiex-lab
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/xfloukiex-lab/magpie-search
- Updated: 2026-09-09
- HTML: https://affpapa.org/en/nevibecode/mcp/magpie-search

## What it does

Magpie keeps a local SQLite index of what your agent has worked through: an FTS5 full-text index ranked by BM25 sits next to a `sqlite-vec` vector index built from 384-dim embeddings of the `all-MiniLM-L6-v2` model, which runs on your machine. A scrubber strips secrets at ingest — keys, tokens, private keys, connection strings — before anything lands in the index. A crash mid-session stops being amnesia.

Five modes cover different ways of looking: `grep` for exact strings and regexes, `lexical` for keywords, `semantic` for meaning via vector K-NN, `hybrid` mixing both through RRF, and `rerank` where jina-reranker re-scores the candidates. The federation layer plugs in five providers — transcripts, files, knowledge graph, vector store, web — each tagging hits as `fact`, `reference`, `lead` or `stale`. Queries fan out concurrently and a slow backend fails open, so it adds nothing instead of stalling the call. Trust-weighted RRF then merges everything, duplicates collapse by content hash, and a token budget keeps the output from flooding the model's context.

Agents reach it over MCP through `search`, `recent`, `session`, `list_sessions`, `stats` and `reindex`. Nothing in that list writes an answer. Installation goes through `uvx`, so you need `uv` present before adding the server.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add magpie-search -- uvx magpie-search
```
uvx runs the command named after the package; if the README names another one, use uvx --from magpie-search <command>

### Codex

**Platform CLI**
```bash
codex mcp add magpie-search -- uvx magpie-search
```
uvx runs the command named after the package; if the README names another one, use uvx --from magpie-search <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "magpie-search": {
            "command": "uvx",
            "args": [
                "magpie-search"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from magpie-search <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "magpie-search": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "magpie-search"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from magpie-search <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add magpie-search uvx magpie-search
```
uvx runs the command named after the package; if the README names another one, use uvx --from magpie-search <command>

## When to use it
- find an exact error string across past agent sessions
- recover context after a reboot or a crash
- see which sources back up the same fact
- search by meaning when you don't recall the wording
- trim results to fit a model's context window

## Example prompts
- Search my session history for where we discussed the database connection timeout
- Grep the transcripts and project files for `ECONNREFUSED`
- Run a deep web search on SQLite migrations and tell me how many domains agree

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md