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, 768-dim), stores vectors in LanceDB, and serves semantic search to Claude Code, Claude Desktop, and the CLI. Everything runs locally — no API keys, no cloud accounts. The embedding model (~120 MB int8) downloads once on first use. CUDA GPUs are auto-detected for faster inference.

Platforms: macOS, Linux

Quick Start

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

Restart Claude Code, then:

> /ingest report.pdf                    # index a document (runs in background)
> /quarry status                        # after a moment, confirm it's there
> /find "what does the report say about margins"   # search by meaning

Once installed, a plugin hook auto-indexes your current project directory on every session start — you don't need to /ingest your codebase manually.

uv tool install punt-quarry
quarry install
quarry doctor

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/35a4b33/install.sh -o install.sh
shasum -a 256 install.sh
cat install.sh
sh install.sh

Remote Server

Run quarry on a GPU server and connect from any Mac or Linux client over TLS.

Server (GPU host, serves remote clients):

export QUARRY_API_KEY=$(openssl rand -hex 32)
curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/35a4b33/install.sh | sh -s -- --network

Generates TLS certificates, binds daemon to 0.0.0.0, registers a systemd service, and prints a CA fingerprint. NVIDIA GPUs are auto-detected for CUDA inference.

Client (connects to remote server):

curl -fsSL https://raw.githubusercontent.com/punt-labs/quarry/35a4b33/install.sh | sh
quarry login <server-hostname> --api-key <token>

No special flag needed --- the default install runs a local daemon on localhost. quarry login redirects queries to the remote server over wss:// with TOFU certificate pinning.

Claude Desktop

Download punt-quarry.mcpb and double-click to install. Alternatively, quarry install configures Claude Desktop automatically.

Note: Uploaded files in Claude Desktop live in a sandbox that quarry cannot access. Use remember for uploaded content, or provide local file paths to ingest.

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

• Daemon architecture --- one quarry serve process loads the embedding model once and serves all Claude Code sessions via mcp-proxy over WebSocket

• Passive knowledge capture --- quarry enable sets up three scoped collections per project: file sync, passive captures (web fetches + session transcripts), and per-agent memory. Captures are separated from the code index so research doesn't pollute code search

• Named databases --- isolated LanceDB directories with independent sync registries. Switch with use for work/personal separation

• Research agent --- researcher subagent combines quarry local search with web research, auto-ingests valuable findings

What It Looks Like

Ingest a document

> /ingest report.pdf

▶ Ingesting report.pdf (background)

Check what's indexed

> /quarry

▶ Database: default
  Documents: 47
  Chunks: 1,203
  Size: 12.4 MB
  Model: snowflake-arctic-embed-m-v1.5 (768-dim)

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

quarry ingest report.pdf                       # index a file
quarry ingest https://example.com              # index a webpage
echo "notes" | quarry remember --name notes.md # index inline text
quarry find "revenue trends"                   # hybrid search (vector + FTS)
quarry list documents                          # list indexed documents
quarry register ~/Documents/notes              # watch a directory
quarry sync                                    # re-index registered dirs
quarry use work                                # switch database
quarry enable                                  # set up project collections + captures
quarry disable                                 # remove project registration + data
quarry status                                  # database dashboard
quarry doctor                                  # health check
quarry serve                                   # start daemon on :8420
quarry install                                 # set up daemon, TLS certs, mcp-proxy

# Remote connections
quarry login okinos.local --api-key <token>    # TOFU login to remote server
quarry logout                                  # disconnect, revert to local daemon
quarry remote list --ping                      # show remote config and health

# Agent memory tagging
quarry ingest notes.md --agent-handle claude --memory-type fact
quarry find "deployment steps" --agent-handle claude
echo "key insight" | quarry remember --name insight.md --agent-handle claude \
  --memory-type observation --summary "Key insight from review"

Setup

Quarry works with zero configuration. These environment variables are available for customization:

For the full configuration reference, see Architecture section 7.

Passive Knowledge Capture

Beyond explicit /ingest and /find commands, quarry runs as a Claude Code plugin with hooks that capture knowledge automatically during your sessions:

All hooks are fail-open — failures are ignored and never block Claude Code. Each hook is individually toggleable via .punt-labs/quarry/config.md YAML frontmatter. See AGENTS.md for the full integration model.

How It Works

Quarry runs as a daemon. Claude Code sessions connect through mcp-proxy:

                    stdio                       wss:// (TLS)
Claude Code <-----------------> mcp-proxy <---------------------> quarry serve
             MCP JSON-RPC       (~5 MB Go)      pinned CA cert    (one daemon)

Without the proxy, every session spawns a separate Python process, each loading the embedding model into ~200 MB of RAM. With it, startup is instant and state is shared across all sessions. All connections use TLS with a self-signed CA — even on localhost.

quarry install downloads mcp-proxy (SHA256-verified, correct platform) and configures MCP clients.

Documentation

Architecture | Z Specification | Design | Agents | Changelog

Development

uv sync                        # install dependencies
make check                     # run all quality gates (lint, type, test)
make test                      # test suite only
make format                    # auto-format code
make docs                      # build LaTeX documents

License

MIT