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, reachable directly too via an HTTP API.

Platforms: macOS (Apple Silicon), 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/8f4d2c1/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.

uv tool install punt-quarry

quarry install

quarry doctor

brew install punt-labs/tap/quarry
quarry install

claude plugin marketplace add punt-labs/claude-plugins
claude plugin install quarry@punt-labs

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

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

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

sha256sum install.sh

cat install.sh

sh install.sh

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 ADVANCED-SETUP.md.

What It Looks Like

Sync a folder:

> /ingest ~/Documents/research

▶  Registering /Users/you/Documents/research as 'research' (task a1b2c3)
▶  Syncing all registrations (task d4e5f6)

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. --memory-type is one vocabulary on every surface (fact, observation, opinion, procedure; lesson is reserved for quarry learn) — an unknown value is a 400 on remember, ingest, and the capture route alike. Always pass your own handle: the daemon cannot infer it, and a subagent's working directory resolves to the repo's leader, not to the subagent.

Each ethos identity gets a versioned ## Memory (quarry guide v2) block in its session_context — when to remember (the five moments), what never to store, and why the handle is yours — written to the vendored .punt-labs/ethos/identities/<handle>.ext/quarry.yaml on quarry enable (commit it via PR) and to the global identities on quarry install.

Two Agent Skills carry the deep how-to that used to be restated across the SessionStart context, the MCP instructions block, and the memory guide: quarry-recall (understand code, recall a decision, recall memory — all backed by quarry find) and quarry-capture (remember/learn/ingest, the five-moments timing, the agent_handle discipline). Claude Code reads them straight from this repo's plugin/skills/; quarry skills install deposits the same two skills into pi (~/.pi/agent/skills/), opencode (~/.config/opencode/skills/), and codex (~/.codex/skills/, alongside its own preinstalled .system/ skills) — version-stamped by content hash, so a re-run only touches a harness whose deposit is stale. quarry disable retracts them again, but only when the disabled repo's own pyproject.toml names the punt-quarry package (never merely because a plugin/skills/ tree exists — every marketplace-layout plugin ships one) and only for a directory carrying quarry's own deposit manifest; a same-named directory it never wrote is left alone.

A registered directory isn't cron-driven — quarryd runs a live filesystem watch (debounced, ~1s) that reacts to changes as they happen, backed by a 5-minute periodic safety sweep (catches anything the watch missed, self-heals the search index). quarry sync triggers an immediate one-shot pass on top of that; you don't need to run it after every edit.

The watch honors ignore rules the way git does: .gitignore (at every level), a root-level .quarryignore, and built-in scratch/VCS defaults all prune both what gets indexed and which directories consume OS watch resources — a giant node_modules or .venv costs nothing. quarry list registrations shows each collection's live watch state (watched, degraded, or scan-only); a scan-only collection still stays current via the periodic sweep.

Setup

Quarry works with zero configuration. For environment variables and running the engine on a remote/GPU host, see ADVANCED-SETUP.md.

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 hooks into the session lifecycle and captures knowledge automatically, with no action from you:

Every hook fails open — a hook failure never blocks Claude Code — and each is independently toggleable in .punt-labs/quarry/config.md.

Captures are scrubbed at write time (secrets, paths, emails, hostnames) through a single choke point before they ever reach disk. The scrub is pattern-based and best-effort, not a formal guarantee of catching every possible secret; a failure in the scrubber itself is fail-closed (the write is blocked, not written unscrubbed). Deliberate ingest/remember content is not scrubbed — that's content you chose to add. See DES-036 in DESIGN.md.

Extension: private capture shadow. An opt-in per-project shadow repo (<repo> → private <repo>-quarry) can push the scrubbed captures off the public repo entirely, for projects where even scrubbed transcripts shouldn't live in a public history. See DES-039 in DESIGN.md and AGENTS.md.

Recall telemetry privacy note. Every search records a scrubbed copy of the query text and its ranked hits to a local SQLite file (~/.punt-labs/quarry/data/<db>/telemetry.db) — nothing leaves the machine. Query text goes through the same secret/PII scrub as captures before it ever touches disk. Turn it off with telemetry_enabled: false in Settings (env var TELEMETRY_ENABLED); see DES-056 in DESIGN.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). Re-running the Quick Start installer does this for you on every upgrade — it calls quarry install and then force-restarts the service as a belt-and-suspenders step, so a plain curl | sh re-run is enough.

After upgrading the package some other way (uv tool install --force, a local wheel), restart the service yourself — a running daemon holds the old engine in memory until restarted.

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.

HTTP API

quarryd also exposes a REST API — every CLI/MCP operation is a thin client over it. The CLI is the primary, documented way to drive quarry; the HTTP API is there for scripting or a non-Claude integration that wants to talk to the daemon directly. quarry install generates a self-signed CA for the managed daemon, local or remote, so it's TLS even on loopback:

curl --cacert ~/.punt-labs/quarry/tls/ca.crt "https://127.0.0.1:8420/v1/search?q=Q3+revenue"

Local installs bind loopback-only with no auth required; a --network install additionally requires a Bearer token (QUARRY_API_KEY) — see ADVANCED-SETUP.md. The full endpoint list is generated at docs/openapi.json (make openapi regenerates it).

Documentation

Architecture | Advanced Setup | Design (ADR log) | Agents | Changelog

Development

Quality gates, architecture notes, and the PR process are in CONTRIBUTING.md.

License

MIT