punt-quarry

Local semantic search for AI agents and humans.

Quarry indexes documents in 20+ formats, embeds them with a local ONNX model (snowflake-arctic-embed-m-v1.5), stores the vectors in LanceDB, and serves semantic search to Claude Code, Claude Desktop, and the command line. Everything runs locally — no API keys, no cloud accounts. One quarryd daemon per machine loads the model once; the CLI, the MCP server, and the Claude Code hooks are thin clients over it.

Platforms: macOS, Linux

Quick Start

Install the CLI, the daemon, the MCP server, and the Claude Code plugin:

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/9d500df/install.sh | sh

Restart Claude Code. Your current project is auto-indexed at session start, so you can search it by meaning right away — see What It Looks Like.

Install the package:

uv tool install punt-quarry

Set up the daemon, TLS certificates, and MCP config:

quarry install

Check health:

quarry doctor

For non-Claude harnesses (Codex, Cursor, a plain terminal) or Claude Code users whose org policy blocks marketplace/plugin installs, --no-plugin installs everything except the marketplace-register and plugin-install steps:

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/9d500df/install.sh | sh -s -- --no-plugin

Where a flag cannot be passed (CI templating a bare curl … | sh), set QUARRY_NO_PLUGIN=1 — honored only when exactly 1:

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/9d500df/install.sh | QUARRY_NO_PLUGIN=1 sh

Everything else runs unchanged. Use the CLI and the stdio quarry mcp server directly; both talk to the resident quarryd. Re-run the installer without --no-plugin to add the plugin later.

Download the installer:

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/9d500df/install.sh -o install.sh

Check its digest (shasum -a 256 install.sh on macOS):

sha256sum install.sh

Read it:

cat install.sh

Run it:

sh install.sh

Related MCP server: rag-mcp

Features

• 20+ formats — PDFs (with OCR for scanned pages), source code (AST-aware splitting), spreadsheets, presentations, HTML, Markdown, LaTeX, DOCX, images.

• Semantic search — retrieval is by meaning, not keyword. A query about "margins" finds passages about profitability even if they never use that word.

• One daemon, thin clients — a single quarryd process loads the embedding model once and serves the CLI, the MCP server, and the Claude Code hooks over a versioned REST API. Its resource use is bounded so it stays quiet in the background while you work.

• Passive knowledge capture — quarry enable sets up per-project file sync, web-fetch and session-transcript capture, and per-agent memory. Captures are PII/secret-scrubbed at write time and kept separate from the code index. See Knowledge Capture.

• Named databases — isolated LanceDB directories with independent sync registries; switch with quarry use for work/personal separation.

• Remote server — run the engine on a GPU host and connect from any Mac or Linux client over TLS. See Remote Server.

What It Looks Like

Ingest a document:

> /ingest report.pdf

▶ Ingesting report.pdf (background)

Search by meaning:

> /find "what were the Q3 revenue figures"

▶ [report.pdf p.12 | text/.pdf] (similarity: 0.4521)
  Third quarter revenue reached $142M, up 18% year-over-year,
  driven primarily by expansion in the enterprise segment.
  Gross margins improved to 71% from 68% in Q2.

Commands

Slash Commands (Claude Code)

MCP Tools

CLI

Agent-memory tagging is available on ingest/remember/find via --agent-handle, --memory-type, and --summary.

Setup

Quarry works with zero configuration. These environment variables customize it:

The full configuration reference is in docs/architecture.tex.

Remote Server

Run quarry on a GPU host and connect from any Mac or Linux client over TLS. On the server, set an API key and install in network mode (binds 0.0.0.0, registers a service, prints a CA fingerprint):

export QUARRY_API_KEY=$(openssl rand -hex 32)

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/9d500df/install.sh | sh -s -- --network

On the client, install normally, then log in — queries redirect to the server over wss:// with TOFU certificate pinning:

quarry login <server-hostname> --api-key <token>

Claude Desktop

The .mcpb bundle is an on-top way to reach the same local index from Claude Desktop. It embeds no engine — it registers the thin quarry mcp client, which talks to the same quarryd that backs the CLI and Claude Code. It is not a standalone install: quarry must already be installed and running.

quarry install configures Claude Desktop automatically. To add it by hand instead, download punt-quarry.mcpb and double-click it.

Uploaded files in Claude Desktop live in a sandbox quarry cannot read — use remember for that content, or give ingest a local path.

Knowledge Capture

As a Claude Code plugin, quarry captures knowledge automatically: it auto-indexes your project at session start, ingests URLs you fetch during research, and captures session transcripts before context compaction. All hooks fail open (a failure never blocks Claude Code) and are individually toggleable in .punt-labs/quarry/config.md.

Captures are PII/secret-scrubbed at write time (secrets, paths, emails, hostnames) through a single choke point, fail-closed. Deliberate ingest/remember content is not scrubbed. An opt-in per-project shadow repo (<repo> → private <repo>-quarry) can push the redacted captures off the public repo. See DES-036 and DES-039 in DESIGN.md and AGENTS.md.

Managing the Daemon

quarry install registers quarryd as a per-user service that starts at login and restarts on crash (launchd on macOS, systemd on Linux). After upgrading the package, restart the service so the new engine loads — a running daemon holds the old code in memory.

macOS:

launchctl kickstart -k gui/$(id -u)/com.punt-labs.quarry

Linux:

systemctl --user restart quarry

quarry doctor confirms the daemon is running and ready.

Documentation

Architecture | Design (ADR log) | Agents | Changelog

Development

License

MIT