Minion is a capture-first macOS second brain: it watches what you work on (window focus, accessibility text, selective screenshots when text is thin), ingests files you drop in, and stores everything in a local vault at ~/Library/Application Support/Minion/data. The app is chat-first: on first run it introduces itself in plain language, asks what to call you, and only then requests optional permissions (Contacts sync happens in the background). You can paste text or add files to context in a couple clicks, and your assistants can read the same vault over MCP—either via stdio (Claude Desktop) or LAN HTTP (other clients on your network).

Under the hood: one memory.db (plus vectors) in the vault; override the data directory with MINION_DATA_DIR. macOS capture respects deny lists and keeps screenshots sparse (OCR when accessibility text is thin). Settings cover sidecar paths, Claude one-click MCP setup, and per-format ingest.

Ships today: Tauri desktop, Python sidecar, ambient capture, Activity + 42, vault + MCP, life-graph seed, council-style suggestions. Roadmap (mirror sharing, belief plasticity, tiered compression at scale, ambient audio, and more) is spelled out in docs/ROADMAP.md—not promised here.

On tauri build, desktop/src-tauri/scripts/sync_sidecar.sh copies chatgpt_mcp_memory into desktop/src-tauri/resources/sidecar/ (gitignored; canonical source stays chatgpt_mcp_memory/).

When an AI has access to Minion's index, the output changes character entirely. Here Claude is asked to rewrite website copy "in my voice — ask minion". It calls ask_minion across dozens of past conversations, reads the pattern ("short sentences, direct subject-verb, 'we' naturally, thinks out loud without hedging"), and rewrites the copy in that register — quoting actual lines back as evidence.

Without Minion: generic, polished, forgettable. With Minion: the AI knows how you actually write and produces something that sounds like you wrote it yourself.

Claude rewriting copy in the user's voice after calling ask_minion across dozens of conversations

Preferences — Status (sources, chunks, sidecar, paths), Claude (MCP) one-click config, and Ingest & file types:

On GitHub Releases there are two macOS downloads. Read the file name—it says which kind of Mac it is for:

If you pick the wrong one, macOS may refuse to open the app or show an architecture error. Delete Minion.app, download the other zip, unzip, and drag Minion.app to Applications again.

1. Download the matching zip from GitHub Releases (or build from source — below).
2. Unzip, then move Minion.app to Applications when prompted (avoid running forever from the disk image or a translocated copy).
3. First launch can take a few minutes while Minion prepares its embedded Python environment and starts the sidecar. Later launches are quick.
4. Follow the chat onboarding (name, optional permissions). You can paste text or add files to context from the main window.
5. Optional: open Settings → Claude (MCP) and click Add to Claude, then fully quit and reopen Claude Desktop.
6. Optional (LAN MCP for other clients): point an MCP client at http://<this-mac-lan-ip>:8765/mcp and set Authorization: Bearer foofie (or override with MINION_MCP_HTTP_TOKEN).
7. Optional: import a ChatGPT export (zip or folder) via the drop zone so the index has history on day one.

Ollama (image captions): If you do not already have Ollama installed, Minion can download the official macOS Ollama app into your Minion data folder on first launch and start it locally. To skip that behavior, set MINION_SKIP_MANAGED_OLLAMA=1 before opening the app.

git clone https://github.com/reif-is-a-foofie/Minion.git
cd Minion # or your clone path, e.g. ~/Classified/minion
git submodule update --init --recursive
cd chatgpt_mcp_memory
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cd ../desktop
npm install
npm run tauri dev

The Rust shell prefers ../chatgpt_mcp_memory/.venv/bin/python. Release builds produce desktop/src-tauri/target/release/bundle/macos/Minion.app; see desktop/README.md for bundling notes.

For a terminal-first setup (export path, minion doctor, minion setup, inbox CRUD without the GUI), use the launcher in bin/minion and chatgpt_mcp_memory/README.md. The desktop app and the CLI share the same store and MCP server code.

Screen-memory MVP commands:

./bin/minion remember-screen
./bin/minion search "where did I see the export button?"
./bin/minion summarize-last 30m
./bin/minion what-was-i-doing
./bin/minion guidance
./bin/minion screen-memory-status --probe
./bin/minion verify-screen-memory

When run from this checkout, screen-memory commands use the repo-local chatgpt_mcp_memory/.venv automatically. Use --workspace only when you want to run against another installed workspace.

Indexing, capture, and search run on your machine. MCP speaks stdio to Claude Desktop by default—no cloud "memory service" for your chunks. Optional components (for example Ollama for voice or captions, or HF Hub for some embedding downloads) only touch the network if you configure them. Keep exports and large corpora outside the git tree if you prefer.

If you use LAN MCP, the sidecar can bind to 0.0.0.0 (see MINION_API_HOST) so other machines on your network can reach POST /mcp. POST /mcp is password-protected (default foofie, override with MINION_MCP_HTTP_TOKEN). Other HTTP API routes may require MINION_API_TOKEN depending on route and configuration.

Built and dogfooded by Reif — questions: reif@thegoodproject.net.

Cursor skills catalog: Awesome Cursor Skills by Spencer Pauly — vendored in-repo at third_party/awesome-cursor-skills. Third-party list; not affiliated with Minion.