Minion

Minion is a macOS desktop app that turns your machine into private, searchable long-term memory for AI assistants. It watches and listens on your desk (windows, browser text, optional mic) as the primary substrate; you can also drop exports, PDFs, notes, and media into an inbox. Everything is chunked, embedded, and stored locally in SQLite. Claude Desktop (and any other MCP client) can call Minion over stdio to search that archive, browse conversations, and maintain an evolving voice profile—without sending your corpus to a hosted service.

Screenshots

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

What you get

• Local index — One memory.db (plus vectors) under ~/Library/Application Support/Minion/data by default. Override with MINION_DATA_DIR if needed.
• Drop zone + watcher — Drag files or folders onto the app (or use Choose files…). The sidecar ingests in the background; the Activity list shows progress and chunk counts.
• MCP tools for Claude — Semantic / keyword / temporal ask_minion, get_chunk, conversation helpers, index_info, voice tools (commit_voice / append_to_voice), and identity helpers where enabled. Claude chooses when to call them.
• Settings hub — Restart the Python sidecar, inspect API and DB paths, tune which file kinds are ingested, and Add to Claude to merge Minion into claude_desktop_config.json.

For tool tables, parsers, env flags, and CLI-only workflows, see chatgpt_mcp_memory/README.md. For Tauri architecture and tauri dev / tauri build, see desktop/README.md. Product direction and phased themes: docs/ROADMAP.md.

Where the app lives in this repo (on GitHub)

All of it is in this monorepo—nothing is shipped from a private subtree:

On tauri build, desktop/src-tauri/scripts/sync_sidecar.sh copies chatgpt_mcp_memory’s src/ and requirements*.txt into desktop/src-tauri/resources/sidecar/. That sidecar/ folder is gitignored (generated each build); the canonical source is always chatgpt_mcp_memory/ on GitHub.

Install (macOS app)

1. Pick the right download (Intel vs Apple Silicon)

On GitHub Releases there are two macOS downloads. Read the file name—it says which kind of Mac it is for (no “arm64” / “x64” jargon):

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.

2. Install and run

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; that can confuse paths and file access).
3. First launch can take a few minutes while Minion prepares its embedded Python environment and starts the sidecar. Later launches are quick.
4. In Minion, open Settings → Claude (MCP) and click Add to Claude. Then fully quit and reopen Claude Desktop so it loads the new MCP entry.
5. 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 downloads the official macOS Ollama app (one build for both Apple Silicon and Intel) into your Minion data folder on first launch and starts it locally. To skip that behavior (e.g. corporate machines), set MINION_SKIP_MANAGED_OLLAMA=1 before opening the app.

Build from source (developers)

git clone https://github.com/reif-is-a-foofie/Minion.git
cd 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; bundling details may evolve — see desktop/README.md and desktop/src-tauri/ notes.

CLI (minion command)

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

Privacy

Indexing and search run on your machine. MCP speaks stdio to Claude Desktop by default—no cloud “memory service” in the loop for your chunks. Optional components (for example Ollama for voice synthesis, 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 (e.g. a sibling folder).

Credits

Built and dogfooded by Reif — questions: [email protected].

Cursor skills catalog: Awesome Cursor Skills by Spencer Pauly — vendored in-repo as a git submodule at third_party/awesome-cursor-skills so agents can scan curated SKILL.md workflows. Third-party list; not affiliated with Minion.