Use find before WebSearch or WebFetch for research, or before answering a why/how/what-did-we-decide question. Prefer grep for symbol and value lookups; prefer find for meaning.

Combines vector similarity and BM25 full-text search via Reciprocal Rank Fusion (RRF) for better recall on both meaning and exact terms.

Args: query: Natural language search query. limit: Maximum number of results (default 10, max 50). document_filter: Optional exact document name to filter by. collection: Optional collection name to search within. page_type: Optional content type filter (text, code, spreadsheet, etc.). source_format: Optional source format filter (.pdf, .py, .xlsx, etc.). agent_handle: Your own handle to recall only your memories (e.g. "rmh"); leave empty to search everything. memory_type: Optional memory type filter (fact, observation, lesson, etc.).

Use when you have a URL to add to the knowledge base — a doc, an article, a spec.

remember = a specific durable fact, ingest = a URL, learn = a distilled lesson that gets retrieval preference.

Fetches a URL with smart sitemap discovery and single-page fallback. For local files and directories, use register_directory + sync_all_registrations — the daemon owns the filesystem, so there is no in-process file loader here.

Returns immediately — the daemon indexes in the background.

Args: source: HTTP(S) URL to ingest. overwrite: If true, replace existing data. collection: Collection name. Auto-derived if empty.

Use remember when you learn something durable — a decision, a gotcha, a non-obvious fact, a procedure — so it survives context compaction.

remember = a specific durable fact, ingest = a URL, learn = a distilled lesson that gets retrieval preference.

Call it at these five moments, not at the end and not never: a non-obvious root cause or gotcha (fact); a ratified design decision with its reason (fact); a repeatable how-to (procedure); a judgement you will revisit (opinion); and once before submitting a mission result (observation). Always pass your own agent_handle — the daemon cannot infer it, and a subagent's working directory resolves to the repo's leader, not to you.

The daemon scrubs secrets/PII before indexing. Returns immediately — the daemon indexes in the background.

Args: content: The text content to remember. document_name: Name for the document (e.g., 'notes.md'). overwrite: If true, replace existing data for this document. If false, an existing document of this name is left untouched. collection: Collection name. Leave empty to route by agent_handle — memory-<handle> when a handle is given, else default. format_hint: Format hint: 'auto', 'plain', 'markdown', 'latex'. agent_handle: Your own handle (e.g. "rmh") — the memory is filed under it and recalled by it. memory_type: Memory classification: fact, observation, opinion, procedure. 'lesson' is reserved for the learn tool. summary: One-line summary of the content.

Use learn to save a distilled lesson that should outrank ordinary results for related queries -- a rule, a convention, a "do it this way" insight, not a one-off fact.

remember = a specific durable fact, ingest = a URL, learn = a distilled lesson that gets retrieval preference.

The daemon scrubs secrets/PII before indexing, same as remember. Lessons are capped at 500 characters -- use remember for anything longer. Returns immediately -- the daemon indexes in the background.

Args: lesson: The distilled lesson text (<= 500 chars). topic: Optional domain tag (e.g. "testing", "release-process"). name: Optional user-visible slug for later reference.

Use to see what's already indexed before ingesting it again.

Args: kind: What to list — "documents", "collections", "databases", or "registrations". collection: Optional collection filter (only for kind="documents").

Use to read a specific page, or to check whether a document is already indexed.

Without page_number: shows document metadata (pages, chunks, collection). With page_number: shows the full text for that page.

Args: document_name: Document filename (e.g., 'report.pdf'). page_number: Page number (1-indexed). 0 means show metadata only. collection: Optional collection scope.

Use to remove stale or wrong content before re-ingesting it.

Returns immediately — the daemon removes chunks in the background.

Args: name: Document filename or collection name to delete. kind: What to delete — "document" or "collection". collection: Optional collection scope (only for kind="document").

Use to track a local directory so future changes sync automatically.

Returns immediately — the daemon records the registration in the background.

Args: directory: Absolute path to the directory. collection: Collection name. Uses directory name if empty.

Use to stop tracking a directory — keep its indexed data with keep_data=True, or purge it.

Returns the removed-file count synchronously; the chunk purge runs as a background task. An unknown collection surfaces as an error, not a removal confirmation.

Args: collection: Collection name to deregister. keep_data: If true, keep indexed data in LanceDB.

Use after registering a new directory, or when tracked files changed outside quarry's own writes.

Returns immediately — the daemon runs the sync in the background.

Use to check how much is indexed before you search or ingest.

Use to read your own recall stats: query volume, latency, recall mix.

Use to point every other tool at a different named database.

All tools (find, ingest, sync, etc.) will target the selected database's daemon until changed again. Use list(kind="databases") to see the database the daemon is fixed to.

Only selects among LOCAL databases: while a remote target (QUARRY_URL or a 'quarry login') is active, the remote daemon is fixed to its own database and this has no effect.

Args: name: Database name (e.g., 'coding', 'work'). Use 'default' for the default database.

Use after ethos mission close to file each frozen round into the worker's memory (memory-<worker>, type observation).

Reads this repo's .punt-labs/ethos/missions/ tree; safe to re-run — a round already filed is skipped, and a name held by another checkout is reported as an error, never overwritten.

Args: mission: Sync one mission id only; empty means every mission. dry_run: List what would be filed and post nothing. force: Re-file rounds the daemon already holds (matching key only).