Garage

A local-first personal Retrieval-Augmented Generation (RAG) pipeline and knowledge indexing system powered by
PostgreSQL + pgvector. Garage indexes personal documents, code repositories, and notes with automated authorship
attribution, multi-model vector embeddings, hybrid full-text/vector search via Reciprocal Rank Fusion (RRF), and
a Model Context Protocol (MCP) 2.0 server, accompanied by a native macOS companion application.

Key Features

Local-First & Privacy-Focused: Extracted documents, chunks, and embeddings remain in your local PostgreSQL database. There is no cloud AI client in the app; content goes only to the built-in llama.cpp or the Ollama / LM Studio server you configure, through one tested egress choke point, and communications never leave your Mac.
Smart Multi-Format Ingestion: Streaming, memory-efficient extractors for Markdown, PDF (pypdf with selective pdfplumber escalation for tables), Office documents (.docx, .pptx, .xlsx), images (Tesseract OCR, in-process; HEIC through macOS ImageIO), Apple Mail (.emlx) and .eml messages, Apple Messages threads, code, and configuration files. Re-ingesting is cheap: unchanged files are skipped on stat or hash, files with no text are remembered rather than re-read, and a changed document keeps its unchanged chunks and their vectors.
Automated Authorship Attribution: Classifies content by provenance (authored, reference, received) and role using Git commit history, embedded document metadata, and configurable path heuristics.
Hybrid Retrieval (RRF): Combines dense vector similarity (pgvector cosine distance) with PostgreSQL full-text search (tsvector / tsquery) using Reciprocal Rank Fusion.
Model-Agnostic Vector Storage: Chunks are decoupled from embedding tables (emb_<slug>), allowing seamless multi-model backfilling and re-indexing across the app's built-in llama.cpp engine, Ollama and LM Studio.
Fact Distillation: An optional pass distills documents into atomic, span-grounded facts with a local model (a vendored, local-only subset of LangExtract, with configurable prompts); every fact is embedded and searchable like a chunk.
Model Context Protocol (MCP) 2.0: Exposes indexed knowledge to LLMs (such as Claude Desktop and Claude Code) over standard stdio or local HTTP with DNS-rebinding protection.
Native macOS Application (GarageApp): Menu bar and window application in Swift/SwiftUI (Apple Silicon, macOS 14+) embedding a self-contained, relocatable PostgreSQL 18 + pgvector (+ Apache AGE) instance, llama.cpp for local embeddings and distillation, and the garage / garage-mcp command-line launchers. The current version is 1.5.

Architecture Overview

sources ──▶ walker ──▶ [materialize] ──▶ extract ──▶ quality gate
                                                          │
                            attribution ◀─────────────────┤
                                  │                       ▼
                                  └──────▶ documents ── chunks
                                                          │
                                              ┌───────────┴───────────┐
                                              ▼                       ▼
                                         emb_<model_1>           emb_<model_2>
                                              └───────────┬───────────┘
                                                          ▼
                                              hybrid search (RRF)
                                                          │
                                                    MCP server

For detailed architectural and design specifications, see:

Support Center & User Guide — Comprehensive setup, CLI usage, and MCP integrations.
Troubleshooting & Diagnostics — Common issues, error codes, and permission troubleshooting.
Frequently Asked Questions (FAQ) — Privacy, storage, models, and MCP tools.
Architecture Guide — Ingestion pipeline, extractors, quality filtering, and concurrency model.
Attribution & Identity — Git-aware author detection, trust tiers, and evidence logging.
Privacy & Egress Guarantees — The egress choke point, destination allowlist and communication rule, and macOS TCC considerations.
Database Schema Reference — PostgreSQL schema layout, cascade rules, and HNSW vector indexing.

Repository Structure

├── BUILD.bazel               # Top-level Bazel build targets and aliases
├── MODULE.bazel              # Bazel dependencies (aspect_rules_py, rules_swift, rules_apple, etc.)
├── data/
│   ├── notices/              # THIRD_PARTY_NOTICES.txt, generated by tools/third_party_notices.py
│   └── sql/                  # PostgreSQL DDL, applied in order (001_extensions … 013_fact_prompts)
├── docs/                     # The garagerag.app site: support pages, architecture, privacy, schema, attribution,
│                             # the generated config schema and model catalog (.data/), and the Sparkle appcast
├── ext/                      # Hermetic Bazel builds: PostgreSQL 18/19, pgvector, Apache AGE, ICU, zlib, OpenSSL,
│                             # Python.framework, llama.cpp, Tesseract/Leptonica, Sparkle
├── garage_python/            # Python backend package (garage_rag), CLI (garage), and MCP server (garage-mcp)
│   ├── pyproject.toml        # Python project configuration (uv managed)
│   └── src/garage_rag/       # Core RAG, extraction, embedding, database, and search modules
├── macapp/                   # Native macOS SwiftUI application (GarageApp), its XPC services and launchers
├── proto/garage.proto        # gRPC contract between the app and the Python GarageService
└── tools/                    # Tooling, linters, formatters, and Bazel environment helpers

Getting Started

Prerequisites

Aspect CLI or Bazel (v8+)
Python 3.14+ (when running outside the Bazel hermetic toolchains)
PostgreSQL with pgvector (or use the embedded instance provided by GarageApp)
An embedding server: the app's built-in llama.cpp engine (provider llama_xpc, available while
Garage is running), or Ollama or LM Studio

Python CLI Quickstart

Install the garage and garage-mcp commands from PyPI:

uv tool install --python 3.14 garage-rag   # or: pipx install garage-rag

Initialize configuration:
```
garage config init          # ./garage.json
garage config init --user   # or ~/.garage.json
```
This writes every setting at its default. garage reads ./garage.json, then ~/.garage.json
(or --config PATH).
Initialize the database:
```
garage init-db
```

Register an embedding model:

garage register-model bge-m3 --provider ollama --dims 1024
garage set-default-model bge-m3

Add and ingest sources:

# Add a notes directory as authored content
garage add-source notes ~/Documents/Notes --class document --trust authored

# Ingest documents and generate vector embeddings
garage ingest
garage backfill

Search the corpus:

garage search "distributed consensus"
garage search "kernel tracing" --trust authored

Start or Install the MCP Server:

# The stdio server MCP clients spawn (its own entry point, separate from the CLI)
garage-mcp --config ~/.garage.json

# Or one long-running HTTP server for several clients
garage mcp-serve

# Register either with Claude Desktop / Claude Code (stdio garage-mcp by default, --http for a URL)
garage mcp-install --target claude-desktop
garage mcp-install --target claude-code-user --http

Development & Build Commands

This monorepo uses Aspect CLI / Bazel for hermetic builds, testing, formatting, and linting.

Building Targets

# Build all targets in the repository
aspect build //...

# Build the macOS application
aspect build //:macapp

Running Tests

# Run all unit and integration tests across the repo
aspect test //...

The tests in garage_python/tests/test_postgres.py run against a real Postgres with pgvector.
They skip unless GARAGE_TEST_DATABASE_URL names a development server, such as Homebrew's
postgresql@18 with pgvector running as a service. Point it at a superuser URL such as
postgresql://localhost:5432/postgres, never at the app's own database. See "Testing against
Postgres" in CLAUDE.md.

Code Quality & Formatting

# Format Python, Starlark, and configuration files
aspect format -- //...
aspect buildifier

# Run linters and type checkers (Ruff, Ty)
aspect lint //...

Xcode Integration

To generate an Xcode project for developing the macOS application:

aspect run //:xcodeproj
open macapp/Garage.xcodeproj

License

See LICENSE for terms of use.