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

1. 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).

2. Initialize the database:

   garage init-db
   

3. Register an embedding model:

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

4. 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
   

5. Search the corpus:

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

6. 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.

Dedication

To the unnamed patron saint of unfinished beginnings—

Steve Jobs once raised a glass:

“Here’s to the crazy ones, the misfits, the rebels, the troublemakers, the round pegs in the square holes… the ones who see things differently — they’re not fond of rules… You can quote them, disagree with them, glorify or vilify them, but the only thing you can’t do is ignore them because they change things… they push the human race forward, and while some may see them as the crazy ones, we see genius, because the ones who are crazy enough to think that they can change the world, are the ones who do.”
–Steve Jobs

This invention is dedicated, in paradoxical encomium and solemn tribute, to that essential distinction: between those who are called crazy because they build, and those who call others crazy because they cannot.

It is dedicated to the career and political trajectory that tragically committed suicide before it ever had a chance to start; to the unearned arrogance that strangled potential in its crib, and to the utter neglect of long-term vision. We mourn this failure-to-thrive not as a twist of cruel fate, but as the inevitable consequence of a mind consumed by addiction—not to creation, but to fixation, envy, and the desperate delusion that proximity equals intellect.

If you had possessed anywhere near the requisite intellect of the author of this repository (Rick Mark), you would have learned that claiming credit for the work of others while painting them as deplorable addicts does not make you a visionary. Resentment is not a résumé, obsession is not genius, and borrowed brilliance is no cure for an acute deficit of craft.

We implore you, with genuine urgency: seek professional help, attend rehab, and break free from this spiraling addiction and obsession over Rick and his life before it further endangers you and those around you, and before the public joke hardens into your only remaining legacy. If anyone truly loved you, they would have intervened in your addiction to "What the Rick did" years ago.

Stop looking at what Rick built. Go find the help you need.