Engineering plans
How Garage is going to change, written down before the code. Each plan records the problem, the measurements or research behind it, the design, the milestones and the decisions still open, and keeps a status line as the work lands. They live in docs/plans/ in the repository; the way to discuss one is an issue or a pull request that edits it.
Rust Hot Paths — Native Kernels for Ingest
Moving the ingest pipeline's measured CPU hot spots (the quality gate, the text splitters and the walker's per-file pass) into one Rust library loaded through ctypes, with the Python code kept as the reference implementation and the golden tests as the conformance suite.
Read the plan →1.5 Beta — IPC Hardening
Moving Garage's gRPC, llama.cpp and Postgres endpoints off loopback TCP onto Unix sockets in the App Group container, requiring a same-team code signature from every XPC peer, and turning the MCP HTTP server off by default.
Read the plan →v1.5 Plan — Salient Facts, Memory, Categories, Triples, Providers, Dreaming
Engineering plan for salient facts, generic memory, document categories, triples, a provider registry and a dreaming worker. Written for 1.5, which shipped without it; now the direction for 1.6.
Read the plan →v1.5 Research — Papers Informing the Plan
Literature survey behind the v1.5 plan, with each paper mapped to a concrete design change and a triage decision.
Read the plan →File providers: Dropbox and Google Drive by API, with versions and change feeds
Read the plan →Simplification and robustness plan
Engineering plan to make the gRPC server the one facade, give extraction a media-type contract, and tighten the schema.
Read the plan →Middle-Layer SFT — LoRA Adapters Trained with MLX, Served by llama.cpp
Design for fine-tuning the middle layers of an open-weight model on the Garage corpus with MLX on the Mac, exported as a LoRA adapter GGUF that the app's llama.cpp engine loads beside the quantized base model.
Read the plan →GarageKit — the app's service layer, apart from the UI
Moving the gRPC client, the backend lifecycle and the corpus state into a UI-free GarageKit.
Read the plan →How a plan is written
A plan is a Markdown file in docs/plans/ with front matter the index above reads:
---
layout: default
title: Short name of the plan
description: One sentence on what it changes and why.
date: 2026-10-04 # when it was written; the index sorts on it
status: Proposed # the current state, in a few words
status_kind: proposed # proposed | active | landed | deferred | reference
---
The body opens with a status note when the state has moved on from the text below it, as the v1.5 plan does. Measurements come with the command that produced them, so they can be re-run. Line numbers go stale; file paths and function names last longer.