Frequently Asked Questions (FAQ)

Garage is a local-first personal Retrieval-Augmented Generation (RAG) and knowledge indexing engine for macOS. 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. Your private communications and personal notes are never transmitted to third-party servers.

Not unless you point it at another machine. Garage sends nothing to the cloud, and the guarantee 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 Mac or to the Ollama / LM Studio server you configure. Anything else is refused.
• Local OCR: Text in images is recognized with Tesseract on your Mac. 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 Mac, even one you configured.

If you connect an MCP client such as Claude Desktop, what Garage returns to it is handled by that client under its own terms.

No. The local HTTP MCP server on 127.0.0.1:8787 includes always-on DNS rebinding protection and Host validation. 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 garage_postgres_super.

Garage includes streaming, memory-efficient extractors for:

• Markdown & Plain Text: .md, .txt, .rst (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.
• Communications: Apple Messages (chat.db) and Mailbox files.

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 active models.
• rag_list_sources: List all configured knowledge sources and their sync status.
• rag_list_models: Inspect registered embedding models and vector dimensions.
• rag_ask: Answer a question from retrieved excerpts with a local model (facts.provider / facts.model), citing them as [n]. Garage sends nothing off the machine; the answer goes back to the agent that asked.
• rag_generate: Send a raw prompt to the same local model, with no retrieval.