Installation Guide

Get Pieces up and running in three simple steps on any platform.

Step 1: Install PiecesOS + Desktop App

PiecesOS is the core engine that powers all Pieces functionality. The Desktop App installer includes PiecesOS automatically.

macOS

Recommended: Download the .pkg installer (Apple Silicon or Intel).

Chip	Download
Apple Silicon (M1/M2/M3/M4)	Download PKG (ARM)
Intel	Download PKG (Intel)

Alternative - Homebrew:

brew install --cask pieces

System requirements: macOS 13.0 (Ventura) or higher.

Windows

Recommended: Download the .appinstaller file.

Download Pieces Desktop App (.appinstaller)

Alternative - WinGet:

winget install "Pieces"

Alternative - EXE: Download Pieces Desktop App (.exe)

System requirements: Windows 10 (1809) or higher.

Linux

Ubuntu 22.04+ required. Install via snap commands in order:

sudo snap install pieces-os
sudo snap connect pieces-os:process-control :process-control
sudo snap install pieces-for-developers
pieces-os.doctor    # Run the doctor script, then copy/paste the output command
pieces-for-developers   # Launch the app

Linux Note

The LTM-2.7 Engine requires the X11 Window Manager. Wayland is not compatible with long-term memory features.

Step 2: Choose Your Tools

After installing the Desktop App, add the integrations that fit your workflow:

Tool	What It Does
VS Code Extension	AI copilot, snippet management, and code actions inside VS Code
Pieces CLI	Access Pieces features from your terminal
MCP Integrations	Connect to Cursor, GitHub Copilot, Claude Desktop, Goose
Web Extension	Capture content, research, and context from any website
JetBrains Plugin	Full Pieces integration for IntelliJ, PyCharm, WebStorm
Obsidian Plugin	Pieces inside your Obsidian vault

Step 3: Start Building Memories

1. Open the Desktop App
2. Sign in (required as of v15.0.0+)
3. Turn on Long-Term Memory in the PiecesOS toolbar
4. Work as usual -- Pieces captures context automatically

What gets captured automatically:

• Saved content (copies, files, snippets)
• Browser tabs and links
• Documents and code
• Conversations and decisions

flowchart LR
    A[Install PiecesOS + Desktop App] --> B[Add IDE Extensions]
    B --> C[Enable Long-Term Memory]
    C --> D[Work Normally]
    D --> E[Recall Anything with AI]
    style A fill:#000,stroke:#fff,color:#fff
    style E fill:#000,stroke:#fff,color:#fff

System Requirements

Component	Minimum	Recommended
CPU	Any modern CPU	Multi-core (4+ cores)
RAM (Local Mode)	8 GB total, 2 GB free	16 GB+
RAM (Cloud Mode)	8 GB total, 1 GB free	16 GB+
Disk Space	2 GB (+ 4 GB free)	8 GB (+ 6 GB free)

For running local LLMs, additional resources are needed:

• 3B models: 8 GB RAM
• 7B models: 16 GB RAM
• 13B models: 32 GB RAM, 8+ core CPU

Next Steps

• Desktop App Basics -- Learn the core interface
• VS Code Setup -- Get Pieces running in your editor
• Daily Workflow -- See how Pieces fits into your day