Frequently Asked Questions (FAQ)

Garage is a local-first personal Retrieval-Augmented Generation (RAG) and knowledge indexing engine for your computer: a native macOS app, a Windows alpha, and a command line for Linux. It indexes your documents, notes, codebases, and communications locally using PostgreSQL and pgvector, providing hybrid semantic/keyword search via the Model Context Protocol (MCP 2.0) to local and desktop AI assistants like Claude Desktop and Claude Code.

Yes. Garage is licensed under the permissive MIT License. You have complete freedom to inspect the source code, run it locally, and adapt it to your workflow.

Unlike cloud solutions, Garage stores 100% of your documents, extracted chunks, and vector embeddings in a private local PostgreSQL instance on your machine. Garage never uploads them. If you connect a cloud assistant like Claude or ChatGPT, the assistant sends the relevant excerpts its searches return, and the documents it opens, to its provider's servers; the rest of the collection never leaves your computer.

Your files and the index never do. What leaves your computer depends only on which AI you connect:

• Claude, ChatGPT and other cloud assistants (what most people use): the assistant's app queries Garage over MCP and gets only the relevant parts of your collection, the excerpts its searches return and the documents it opens, never the whole index. Garage uploads nothing, but the assistant sends those parts to its provider's servers with your conversation, including excerpts from Messages and Mail if you have indexed them, and handled under the provider's terms.
• Fully private, on your computer: with the built-in llama.cpp engine on macOS, or LM Studio or Ollama on this computer, and an agent that runs its model locally, nothing leaves the machine.
• Private AI on your own network: with an Ollama or LM Studio server on another machine, documents and code go to that one server and nowhere else. Messages and Mail stay on this computer even then.

Garage itself sends nothing to the cloud, and that is enforced by tests rather than by convention:

• No cloud AI client: An automated scan of every source file fails the build if any module imports a cloud AI SDK, and the dependency lockfile must contain none.
• One egress choke point, one allowlist: Every outbound connection is built by a single tested module, and goes only to this computer or to the Ollama / LM Studio server you configure. Anything else is refused.
• Local OCR: Text in images is recognized with Tesseract on your computer. There is no cloud fallback.
• Communications stay local: Content classified as communication (e.g., Messages, Mail) is never sent to a server that is not on this computer, even one you configured.

No. By default the local HTTP MCP server binds only to 127.0.0.1:8787, refuses remote clients, and includes DNS rebinding protection and Host validation. (Serving other computers is an explicit opt-in for power users, --allow-remote; with it, and with no --allow-host, the Host check is off. See Troubleshooting.) Any request originating from an unauthorized Host or browser cross-origin without explicit permission is rejected with HTTP 421 Misdirected Request.

GarageApp automatically generates a cryptographically random SCRAM superuser password on initial launch and stores it in the secure macOS Keychain under the service name com.rickmark.garage.postgres. Signed builds keep it in the App Group keychain, which only Garage and its bundled garage / garage-mcp commands can read, without a Keychain prompt. The Database page's copy button puts the full connection URL, password included, on the clipboard when you need it.

Garage includes streaming, memory-efficient extractors for:

• Markdown & Plain Text: .md, .txt, .rst, .org, .adoc (with YAML frontmatter stripping).
• PDF Documents: Fast extraction via pypdf, with automatic page-level escalation to pdfplumber for embedded data tables.
• Office Documents: Word (.docx), PowerPoint (.pptx), and Excel (.xlsx).
• Source Code & Config: .py, .swift, .ts, .rs, .go, .json, .yaml, .toml, etc.
• Images & Scans: Local OCR via Tesseract (PNG, JPEG, TIFF, HEIC and more). An image with no text in it is skipped and remembered, not indexed.
• Communications: Apple Messages (chat.db, one document per conversation) and Apple Mail (.emlx) or .eml messages.

Garage automatically tags content with provenance (authored, reference, or received):

• Git Repositories: Commits are inspected so that files you modified are attributed to you (authored), while upstream or vendored libraries are categorized as reference.
• Document Metadata: PDF / Office author tags are extracted and cleaned against tool signatures.
• Path Heuristics: Paths such as Papers/, Manuals/, or node_modules/ are automatically mapped to reference material.

Yes. Garage decouples text chunks from embedding tables (emb_<model_slug>). You can register multiple models (e.g., bge-m3, nomic-embed-text) and run vector searches across any of them without re-extracting your original files.

Reciprocal Rank Fusion (RRF) combines PostgreSQL full-text search (BM25-style keyword matching) with dense pgvector cosine similarity. This ensures that exact keyword matches (like specific function names or error codes) and semantic conceptual queries are merged into an optimal ranked result list.

Garage provides the following MCP tools to LLMs:

• rag_search: Hybrid semantic and keyword search across your documents and code.
• rag_get_document: Retrieve the full extracted text and metadata of a specific indexed file.
• rag_stats: Overview of indexed document counts, chunk counts, and registered embedding models.
• rag_list_sources: List all configured knowledge sources and their sync status.
• rag_list_authors: List the people the corpus attributes documents to.
• rag_ask: Answer a question from retrieved excerpts with a local model (inference.model, or facts.model when that is empty), citing them as [n]. Garage sends nothing off the machine; the answer goes back to the agent that asked.
• rag_agent: Let the same local model search and read the corpus itself with the tools above, in a loop, and answer; the result lists the steps it took and the documents it saw. This is what "Ask Garage" in the menu bar runs.
• rag_generate: Send a raw prompt to the same local model, with no retrieval.