# Pieces Documentation - Full Content

This file contains the complete content of all public documentation pages for Pieces.
Generated automatically from the documentation content.

---

## Pieces CLI
Path: /products/cli

## Pieces CLI

The Pieces CLI offers users a straightforward way to manage and utilize saved code snippets through the Pieces Drive. It uses the AI-powered features of the [Conversational Search](/products/cli/copilot), all directly within your terminal.

* [Conversational Search](/products/cli/copilot): Utilize AI-driven conversations to enhance productivity by offering contextual assistance for your projects. It helps you understand code, write code comments, perform troubleshooting, and more by incorporating files and folders as context, with or without the powerful Long-Term Memory Engine (LTM-2.7).

* [Pieces Drive](/products/cli/drive): Easily save, find, and share your frequently used code snippets in your Pieces Drive. This makes organizing your work easy, allows for quick access to the code you need, and facilitates effective collaboration with others.

    Follow [these instructions](/products/cli/get-started) on how to download and install the Pieces CLI.

    Explore [troubleshooting options](/products/cli/troubleshooting), navigate to our support page, or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">directly book a call</a> with our engineers.

  Pieces Quick Guides help you quickly understand and utilize powerful features like the Long-Term (LTM-2.7) Memory Engine and Conversational Search. [Get started with Quick Guides.](/products/quick-guides/overview)

This software is designed to offer **two main features**: AI Assistance with Conversational Search and material management within the Pieces Drive.

### Enhanced AI Assistance

Through the Pieces CLI, users can boost productivity by having AI-driven conversations that use [relevant notes and folders as context](/products/cli/copilot/chat), all within their terminal.

### Integrated Snippet Management

With Pieces Drive and PiecesOS in their terminal, users can [save, search, and share their code snippets](/products/cli/drive). This enhances productivity by making reusable code accessible and organized within their notes and project files.

## Using Conversational Search

The Pieces CLI enhances your workflow by letting you save, manage, and share snippets in the terminal. It offers features like snippet enrichment, sharing via custom links, and seamless integration with your development environment.

To explore available options, run `pieces help` within your terminal.

From here, you’ll find several actions, including:

* `Edit`: [Change the name and classification of the material](/products/cli/drive/edit-and-update) within Pieces Drive from directly within the terminal.

* `Create and Delete`: Pieces CLI allows you to [manage your snippets easily from within your terminal](/products/cli/drive/saving-materials), allowing you to create and delete snippets.

## Managing Your Code Snippets

Saving and managing materials with the Pieces CLI is done with lightweight and familiar terminal-style commands.

To save a snippet, copy a section of text or code to your clipboard, head over to Pieces CLI, and type `pieces create`. If you’re in `pieces run` mode, you can just type `create`.

  Common snippet types include utility functions, API requests, and reusable code blocks.

When you save snippets to your Pieces Drive with Pieces CLI, they get AI-generated metadata like [tags, titles, authorship details, and descriptions](/products/cli/drive/saving-materials#whats-stored-when-you-save-a-snippet). This keeps everything organized and easy to access and use at any point.

### Referencing & Reusing

Pieces CLI provides you with powerful search tools to quickly find and access your snippets that you previously saved to Pieces Drive.

There are three different search methods: *Fuzzy Search*, *Neural Code Search*, and *Full Text Search.*

To search for snippets, while Pieces CLI is open, type `search “query”`.

You can also opt-in to using Neural Code Search with `—mode ncs` or Full Text Search with `—mode fts`.

  Your query must be encapsulated in quotations for Pieces CLI to capture your full prompt

A new terminal window will open and you’ll be presented with a list of materials that closely match your query.

Scroll down or up with the `arrow keys` and select the material by pressing `enter`. The material will display with its attributes and the code that was stored in the material.

***

Download the Pieces CLI and follow our [installation guide](/products/cli/get-started) to start streamlining your workflow!

---

## Commands
Path: /products/cli/commands

## Pieces CLI Commands

Reference for every command available in the Pieces CLI, grouped by what you're trying to do.

> The `pieces help` menu listing every command and flag.

## Quick Reference

Run any command with the `pieces` prefix from a regular terminal (e.g., `pieces ask "..."`), or drop the prefix when you're inside `pieces run` loop mode. Type `pieces help` (or `help` inside loop mode) to view this list anytime.

| Command | Description |
| --- | --- |
| `run` | Start the CLI in loop mode |
| `list` | List materials in your Pieces Drive |
| `list apps` | List registered applications |
| `list models` | List configured AI models |
| `create` | Create a material from clipboard |
| `modify` | Update the current material's content |
| `edit` | Rename or reclassify the current material |
| `share` | Generate a shareable link for a material |
| `delete` | Delete the current material |
| `execute` | Run a saved bash material |
| `ask` | Send a question to Conversational Search |
| `search` | Fuzzy-search materials and chats |
| `chats` | List all past conversations |
| `chat` | Show or switch conversations |
| `config` | View or edit CLI configuration |
| `commit` | Commit to GitHub with an auto-generated message |
| `login` | Log in to your Pieces account |
| `logout` | Log out of your Pieces account |
| `open` | Open PiecesOS or its Applet |
| `clear` | Clear the terminal screen |
| `version` | Show installed CLI and PiecesOS versions |
| `help` | Display the help menu |
| `onboarding` | Walk through first-run setup |
| `feedback` | Send feedback to the Pieces team |
| `contribute` | Contribute to the CLI project |

## Materials

Manage saved code, text, and bash materials in your Pieces Drive.

    List every material in your Pieces Drive (alias: `drive`).

    ```bash
    pieces list
    ```

    List every application registered with PiecesOS.

    ```bash
    pieces list apps
    ```

    Create a new material from whatever's currently on your clipboard.

    ```bash
    pieces create
    ```

    Replace the content of the most recently selected material.

    ```bash
    pieces modify
    ```

    Rename or change the classification of the most recently selected material.

    ```bash
    pieces edit
    ```

    Generate a shareable URL for the most recently selected material. The CLI prints the URL and prompts you to open it in your browser.

    ```bash
    pieces share
    ```

    Delete the most recently selected material.

    ```bash
    pieces delete
    ```

    Run a saved bash material directly from the terminal.

    ```bash
    pieces execute
    ```

## AI & Search

Send questions to *Conversational Search*, search across your data, and pick which model responds.

    Send a question to *Conversational Search*. Append flags to attach context from your Drive or local files.

    ```bash
    pieces ask "How do I parse JSON in Python?"
    ```

    Optional flags:

    - `-m`, `--materials` — attach saved materials by index (e.g., `-m 1 2`)
    - `-f`, `--file` — attach files or folders by absolute or relative path

    ```bash
    pieces ask "Refactor this function" -f ./src/utils.py
    ```

    Fuzzy-search materials and past chats.

    ```bash
    pieces search "auth middleware"
    ```

    Optional `--mode` flags:

    - `--mode ncs` — Neural Code Search (semantic)
    - `--mode fts` — Full-Text Search (literal)

    ```bash
    pieces search "auth middleware" --mode ncs
    ```

    Show every AI model configured for `ask`, and switch which one is active.

    ```bash
    pieces list models
    ```

## Conversations

Browse, switch between, and manage your *Conversational Search* threads.

    List every past conversation, numbered for quick switching.

    ```bash
    pieces chats
    ```

    Show messages in your current conversation, or switch to another by number.

    ```bash
    pieces chat
    pieces chat 3
    ```

    Conversation-management flags (use inside the active chat):

    - `-n` — start a new conversation
    - `-d` — delete the current conversation
    - `-r "<name>"` — rename the current conversation

    ```bash
    pieces chat -r "Project Ideas"
    ```

## Configuration

View and edit CLI settings, including which code editor opens your config file.

    Print your current Pieces CLI configuration to the terminal.

    ```bash
    pieces config
    ```

    Open your config file in the editor of your choice (e.g., `vim`, `code`). Changes save immediately.

    ```bash
    pieces config --editor code
    ```

## Account & Git

Sign in to Pieces Cloud and commit code to GitHub with an auto-generated message.

    Log in to your Pieces Cloud account.

    ```bash
    pieces login
    ```

    Log out of your Pieces Cloud account.

    ```bash
    pieces logout
    ```

    Commit staged changes to GitHub with an auto-generated commit message. Add `-p` or `--push` to push immediately after.

    ```bash
    pieces commit
    pieces commit --push
    ```

## Setup & System

Install the CLI, launch the loop, and access help, version, and feedback utilities.

    Install the CLI with `pip` (or `conda`, if you prefer). Python must be set up correctly.

    ```bash
    pip install pieces-cli
    ```

    ```bash
    conda install pieces-cli
    ```

    Start the CLI in loop mode—type commands and flags directly without the `pieces` prefix.

    ```bash
    pieces run
    ```

    Launch PiecesOS or its helper Applet.

    ```bash
    pieces open
    ```

    Clear the terminal screen.

    ```bash
    pieces clear
    ```

    Display installed versions of PiecesOS and the CLI.

    ```bash
    pieces version
    ```

    Display the help menu—the same one shown at the top of this page.

    ```bash
    pieces help
    ```

    Walk through first-run setup interactively.

    ```bash
    pieces onboarding
    ```

    Send feedback directly to the Pieces team.

    ```bash
    pieces feedback
    ```

    Open the contribution flow for the open-source CLI project.

    ```bash
    pieces contribute
    ```

***

## Next Steps

Want to see these commands in context? Read about [Conversational Search](/products/cli/copilot) for `ask`, `search`, and `chat`, [Pieces Drive](/products/cli/drive) for material commands, or the full [Configuration](/products/cli/configuration) walkthrough.

---

## Configuration
Path: /products/cli/configuration

## Configuring the Pieces CLI

Pick which cloud model powers `ask`, set the editor that opens your config file, and manage your Pieces Cloud session. For the full command list, see the [commands reference](/products/cli/commands).

> Switching between available models inside the Pieces CLI.

## Available Models

The Pieces CLI uses the same models as the rest of the Pieces Suite. Choose from three model families—**Claude**, **Gemini**, and **ChatGPT**—each available in Fast, Balanced, and Extra Thinking modes.

For deeper guidance on picking the right model, see [LLM Settings](/products/cli/copilot/llms-settings) and [Choose a Model](/products/desktop/conversational-search/models).

## Switch the Active Model

Use `pieces list models` to view every model configured for the `ask` command. The active model is highlighted, and you can pick a new one interactively from the list.

```bash
pieces list models
```

The next `pieces ask "..."` you run will use the newly selected model.

## Set Your Code Editor

The CLI opens its config file in whichever editor you specify—`vim`, `code`, `nano`, or anything else on your `PATH`. Run `pieces config` to print the current configuration, or `pieces config --editor <editor>` to open the file for editing.

```bash
pieces config
pieces config --editor code
```

Edit values like `timeout: 10`, save the file, and changes take effect on your next CLI invocation.

## Account & Sync

`pieces login` signs you in to your Pieces Cloud account, enabling sync and access to private materials in your [Pieces Drive](/products/cli/drive). `pieces logout` clears your session—useful when switching accounts or working on a shared machine.

```bash
pieces login
pieces logout
```

***

## Next Steps

Hit a snag? Check the [troubleshooting guide](/products/cli/troubleshooting). For a complete reference of every CLI command and flag, see [Commands](/products/cli/commands).

---

## Conversational Search
Path: /products/cli/copilot

## Generative AI Conversations

If you're facing an issue or stuck on a difficult debug, ask Conversational Search specific questions directly in your terminal using `pieces ask`.

You can ask questions that don't need context, like *“What is the basic format for a JSON object?”* or more detailed questions where Conversational Search needs context from your saved materials.

## Adding Conversation Context

Contextual awareness lets Conversational Search help you solve problems faster by providing relevant answers to your issue and notes.

To best add conversation context, [include materials](/products/cli/copilot/chat#via-material-index) or [file context](/products/cli/copilot/chat#via-file-path) for more accurate responses from your terminal chat session.

## Conversational Search As a Daily Driver

Conversational Search is a powerful, adaptable tool that improves the more you use it, *so use it!*

***

    Generate detailed comments and documentation to improve team collaboration and reduce onboarding time. This helps create a consistent coding and writing style across teams.

    Generate initial implementations and boilerplate code for prototypes and fast-paced projects. This is ideal for hackathons, proof-of-concepts (PoCs), and other time-sensitive tasks.

    Conversational Search doubles as a learning tool, helping you explore best practices, new paradigms, and advanced techniques in real-time.

---

## Generative AI Conversations
Path: /products/cli/copilot/chat

## Accessing Copilot Chat in your Terminal

There are two ways to manage your Copilot chats in the Pieces CLI.

### Starting a New Copilot Chat

To quickly start a conversation with Conversational Search:

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal` (macOS/Linux) or `CMD` (Windows).

    You can launch Pieces CLI by typing `pieces run`., Then, you can type `ask query`, where `query` is your question.

    If you’re not in Pieces CLI, in your terminal, you can type `pieces ask query`, replacing `query` with your question.

### Opening Previous Chats

To resume or explore an earlier conversation:

* `chats`: Show all your conversations. The one highlighted in green is where new questions go by default.

* `chat`: Display the messages in your current conversation.

* `chat <number>`: Switch to conversation `<number>` and show its messages.

Use these flags with your `chat` command to manage conversations as you go:

* `chat --new`, `chat -n`: Create a new conversation and switch to it.

* `chat --delete`, `chat -d`: Delete the conversation you’re currently viewing.

* `chat --rename [name]`, `chat -r [name]`: Rename the conversation you’re viewing. If you don’t provide `[name]`, the assistant will suggest one.

[Read more about what commands are available in the Pieces CLI](/products/cli/commands).

## Contextualized Chats

You can narrow Copilot’s focus by feeding it specific materials or files when you ask a question.

### via Material Index

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal`(macOS/Linux) or `CMD`(Windows).

    Run `pieces list` to view all saved materials and note the **index** of the one you need.

    Use the `-m` flag and that index when you ask: `pieces ask "Explain the data model here" -m 4`

    Conversational Search will load material #4 as context.

### via File Path

Use a folder of specific file as context for Conversational Search by initiating the conversation at a specified path.

    Decide which file (or directory) you want Copilot to reference.

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal`(macOS/Linux) or `CMD`(Windows).

    Use the `-f` flag and the path, `pieces ask "How does this component render?" -f src/components/Button.jsx`.

    Conversational Search will read that file before answering.

    Mix flags to supply more than one source `pieces ask "Compare this code to the design spec" -m 2 -f design/specs.md`.

    Copilot loads material #2 and `specs.md` before generating its response.

## Pieces MCP

The Pieces CLI bridges the Model Context Protocol (MCP) to your development tools—no manual config editing required. Run `pieces mcp setup` from your terminal to get started.

### Setup

Run `pieces mcp setup` from your terminal to open an interactive menu and automatically configure Pieces MCP for your platform.

    In your terminal, run `pieces mcp setup`.

    Use the arrow keys to select your MCP client and press Enter. Supported platforms:

    * VS Code
    * Cursor
    * Claude Desktop
    * Windsurf
    * Claude Code
    * Raycast
    * Warp

    The CLI writes the correct configuration for your platform. For VS Code, you'll be asked to choose *User Settings* (MCP available in all projects) or *Workspace Settings* (MCP for the current project only). Other platforms use global config files.

  Ensure PiecesOS is running and LTM is enabled. Run `pieces mcp status` to verify your setup.

### List

The `mcp list` command displays the current implementations of Pieces MCP on your development platforms.

The Pieces CLI supports integration with [VS Code](/products/mcp/vs-code), [Cursor](/products/mcp/cursor), [Claude Desktop](/products/mcp/claude-desktop), [Windsurf](/products/mcp/windsurf), [Claude Code](/products/mcp/claude-code), [Raycast](/products/mcp/raycast), Warp, [GitHub Copilot](/products/mcp/github-copilot), and [Goose](/products/mcp/goose).

### Docs

The `mcp docs` command displays all of the [mcp documentation](/products/mcp) correlated with the supported development environments with the Pieces CLI and Pieces MCP.

### Repair

The `mcp repair` command checks how the Pieces MCP is set up in the platforms supported by Pieces CLI.

If it finds any issues, it will automatically fix them and ask you to type `y` for yes or `n` for no. Then, press `return` (macOS) or `enter` (Windows/Linux) to confirm your choice.

### Status

Running `mcp status` within the Pieces CLI will automatically check all implemented platforms to make sure the Pieces MCP implementation is running correctly.

If it finds that an implementation is broken, it will ask if you want to auto-repair the MCP server.

Type `y` for yes or `n` for no, and press `return` (macOS) or `enter` (Windows/Linux) to confirm your choice.

---

## LLM Settings
Path: /products/cli/copilot/llms-settings

## Switching LLMs

The Pieces CLI supports multiple cloud-hosted LLM models.

## How To Configure Your LLM Runtime

Switching your LLM model in the Pieces CLI is easy. You can select the model that best fits your needs.

Follow the steps below to change the cloud LLM utilized by the Pieces MCP:

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal`(macOS/Linux) or `CMD`(Windows).

    In your terminal, enter `pieces run` to launch into Pieces.

    While in the Pieces CLI, type `list models`. This will display a list of available models within the Pieces CLI.

    Use your `scroll wheel` or `arrow keys` to navigate to your desired LLM and press `return` (macOS) or `enter` (Windows/Linux) to set the LLM runtime.

Once you’ve chosen a new model, the switch is instant. You can continue your work seamlessly with the selected model's capabilities—*no need to restart or refresh anything.*

### Available LLMs

Pieces CLI supports cloud-hosted LLM models, allowing you to choose from a variety of options to meet your needs.

| Supported LLMs                | Supported LLMs   |
| ----------------------------- | ---------------- |
| Gemini-2.5 Flash Preview      | GPT-4o Mini      |
| o4 Mini                       | Gemini-1.5 Pro   |
| o3                            | Gemini-1.5 Flash |
| GPT-4.1                       | GPT-4o           |
| Gemini-2.0 Flash Lite         | Claude 3 Haiku   |
| Gemini-2.5 Pro Experimental   | Claude 3 Sonnet  |
| Gemini-2.5 Pro Preview        | Claude 3 Opus    |
| Claude 3.7 Sonnet             | GPT-4 Turbo      |
| o3 Mini                       | (Gemini)         |
| o1                            | GPT-3.5-turbo    |
| Gemini-2.0 Flash Experimental | GPT-4            |
| Claude 3.5 Sonnet             | Codey (PaLM2)    |
| Claude 3.5 Haiku              | (PaLM2)          |

---

## Pieces Drive
Path: /products/cli/drive

### Using Pieces Drive in the Pieces CLI

The Pieces CLI boosts development productivity and saves time with features like [saving](/products/cli/drive/saving-materials) and [reusing](/products/cli/drive/search-reuse) materials, ensuring your important code is always accessible.

## Use Cases & Examples

Let’s take a look at some examples:

| `Logging Utilities`    | A helper function for detailed server-side logging with timestamps and error levels.                        | Speeds up debugging and monitoring by inserting reliable logging methods.   |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `Validation Functions` | A function to validate JSON payloads or form inputs before submission.                                      | Ensures data integrity with reusable, thoroughly tested validation logic.   |
| `API Integration Code` | Prewritten `axios` code for making GET or POST requests, complete with error handling and response parsing. | Reduces repetitive work when integrating RESTful APIs or GraphQL endpoints. |
| `Component Templates`  | A React functional component template with basic hooks and styling setup.                                   | Provides a consistent starting point for building new components.           |
| `Database Queries`     | A MongoDB query to retrieve active user data filtered by last login.                                        | Streamlines database tasks by reusing optimized query patterns.             |

## Boosting Productivity with Snippet Management

Using prewritten code with the Pieces CLI boosts productivity, standardizes code, and maintains clarity across teams and projects.

The Pieces CLI connects directly to your development environment, letting you focus on what truly matters—building great software—while offering tools for efficient code reuse.

* **Improved Productivity:** Focus on solving new problems rather than fixing old ones.

* **Contextual Awareness:** Snippets enriched with metadata, descriptions, and links to relevant searches help you recall each piece of code's origin, purpose, and best usage scenarios.

* **Code Standardization:** Share best practices and reusable components to help developers keep coding practices and conventions consistent across teams and projects.

By using the Pieces CLI, capture and manage snippets in Pieces Drive to streamline daily tasks and improve your workflow in several ways:

### Save & Organize

Easily [save a function, script, or piece of boilerplate](/products/cli/drive/saving-materials) directly from the tool menu or with a keyboard shortcut. These snippets are stored in your personal Pieces Drive and include context, metadata, and tags for easy retrieval.

To save a code snippet, copy a snippet from a website or your IDE, go over to the Pieces CLI, and type `create`. If you’re not in a running Pieces CLI, you can type `pieces create` and enter the command.

This will automatically grab whatever is in your clipboard and save it to your Pieces Drive.

### Search & Reuse

You can search your collection of saved materials directly from your terminal. This lets you quickly find snippets using keywords or context.

To search, you can access the `search` action inside of the Pieces CLI.

From within Pieces CLI you can enter `search “query”` to do a basic search. If you’re not within the Pieces CLI, you can enter `pieces search “query”`.

You can optionally append `--mode` followed by the search method you’d like:

* `ncs`: Does a neural code search for your query.

* `fts`: Does a full-text search for your query

I.e., `pieces search “query” --mode fts` will use the full-text search on your database using your query.

### Edit & Update

Your snippets can change as your project grows, as you adapt to new project needs, or when you switch to new files in your codebase.

In the `pieces save` command of the **Pieces Drive** within Conversational Search, open your saved snippets, update the code to meet current needs, and save the revised version back to Pieces.

This keeps your library up-to-date, relevant, and aligned with your project's progress. Enhancing your materials makes them more efficient, which benefits you in the long run.

### Reusable Scheduling Functions

Imagine you’re frequently working on projects that involve scheduling tasks at regular intervals.

Instead of rewriting the same logic for each new project, [save an evergreen snippet to your Pieces Drive.](/products/cli/drive/saving-materials#how-to-save-materials)

This allows you to reuse a well-crafted scheduling function across multiple applications, that is useful in a variety of scenarios:

```go
package main

	"fmt"
	"time"
)

// A reusable function to schedule tasks at a specified interval
func scheduleTask(interval time.Duration, task func()) {
	ticker := time.NewTicker(interval)
	defer ticker.Stop()

	for {
		select {
		case <-ticker.C:
			task()
		}
	}
}
```

### File System Monitoring

Suppose you frequently work on projects that involve monitoring file system changes. In that case, you can [save a helpful snippet to your Pieces Drive](/products/cli/drive/saving-materials#how-to-save-materials) that does precisely that, using generic and reusable naming conventions:

```go
package main

	"fmt"
	"log"
	"github.com/fsnotify/fsnotify"
)

// A reusable function to monitor file system changes
func watchFileChanges(path string) {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		log.Fatal(err)
	}
	defer watcher.Close()

	err = watcher.Add(path)
	if err != nil {
		log.Fatal(err)
	}

	for {
		select {
		case event := <-watcher.Events:
			if event.Op&fsnotify.Write == fsnotify.Write {
				fmt.Println("Modified file:", event.Name)
			}
		case err := <-watcher.Errors:
			fmt.Println("Error:", err)
		}
	}
}
```

## **Additional Snippet Scenarios**

Check out more scenarios and use cases for Pieces Drive to see how the Pieces CLI can enhance your workflow.

***

    Streamline your testing process by saving snippets of your frequently used testing functions or unit test templates.

    Save command-line instructions as snippets to easily access deployment commands, Docker setups, and other critical terminal operations.

    You can also save standard logging functions or error-handling snippets that can be reused in different applications, promoting consistent error management.

    Import saved setup scripts, configuration files, and commonly used dependencies to set up new projects and maintain consistency quickly.

---

## Edit & Update
Path: /products/cli/drive/edit-and-update

## Editing

Keeping an up-to-date library of code snippets in the Pieces CLI is easy with seamless editing.

## How to Edit Snippets

Follow the steps below to edit a saved material in the Pieces CLI.

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal`(macOS/Linux) or `CMD`(Windows).

    Launch the Pieces CLI by typing `pieces run` in your terminal.

    Access your saved snippets with the `list` command.

    Use your mouse wheel or arrow keys to scroll and select a snippet by pressing `return` (macOS) or `enter` (Windows/Linux).

    After selecting your desired snippet, enter the `modify` command. This will open your selected snippet in your desired IDE.

    Any changes made and saved within your IDE will update the Pieces Drive automatically, allowing you to use the changed snippet immediately.

## How to Rename Snippets

With the Pieces CLI, you can rename saved materials and have those changes apply universally throughout your Pieces Drive—follow the steps below to learn how.

    In your terminal, type `pieces run` to enter the Pieces CLI. This will switch you to Pieces CLI run mode, where you can type `list`.

    Use your mouse wheel or arrow keys to scroll and select a snippet by pressing `return` (macOS) or `enter` (Windows/Linux).

    After selecting a snippet, you can type `edit`.

    This will open a new prompt for you to change the name and classification for the snippet.

    When you’re complete, the snippet will update across your Pieces Drive automatically.

---

## Saving Materials
Path: /products/cli/drive/saving-materials

## Saving Code Snippets to Pieces Drive

Storing developer materials, such as snippets of boilerplate code, is an excellent way to build a helpful code collection in your Pieces Drive.

This helps you save time when writing generic code in various forms. The Pieces CLI offers a *create* feature designed to assist you with this.

You can use this feature to save all kinds of functional code materials, like:

* API endpoint definitions

* Utility functions or commonly used helper methods

* Code templates for starting new modules

* Reusable logic for error handling or authentication

## How to Save Materials

For Pieces CLI, you can save a snippet to your Pieces Drive with one command.

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal`(macOS/Linux) or `CMD`(Windows).

    Select a section of code or text you want to save and copy it to your clipboard.

    The pieces will use what you have copied to the clipboard as the snippet.

    In your terminal, you can now enter `pieces create`, which will automatically save your clipboard as a new snippet.

    If you’re within the Pieces CLI `pieces run` mode, you can enter `create`.

## What’s Stored When You Save a Snippet

When you save a snippet to your Pieces Drive, more than just the code is stored.

The Conversational Search captures several different kinds of metadata:

* `Type`: Categorizes the snippet (e.g., API call, function, class) and its programming language.

* `Associated Tags`: Keywords linked to the snippet for easier searching.

* `Custom Description`: Specifies exactly which *lines* (by number) the snippet is from and the file it came from—handy for mind-mapping.

* `Smart Description`: AI-generated summaries that explain the snippet’s purpose and function.

* `Suggested Searches`: Related searches that help you find similar snippets.

* `Related Links`: References to documentation, code repositories, or other relevant resources.

* `Related People`: Associated collaborators or contributors.

Furthermore, Conversational Search reviews stored snippets for sensitive data, including API keys, passwords, and authentication tokens, ensuring that **no confidential information** is unintentionally saved.

## Where Saved Snippets Live

Saved snippets are stored locally on your device, ensuring offline accessibility. This also means that any Pieces MCP integration or even the Pieces Desktop App has constant, up-to-date access to your saved materials with Pieces Drive.

You can find your saved snippets via the `pieces list` command or the `pieces search` feature.

[Read more about how to find your saved snippets here.](/products/cli/drive/search-reuse#viewing-and-reusing-saved-snippets)

---

## Search & Reuse
Path: /products/cli/drive/search-reuse

## Locate Materials in Pieces Drive

To find your snippets in Pieces CLI, you can use one of two methods: searching or manually checking the Pieces Drive list.

## How to Search for Saved Materials

From the terminal, you can search for code snippets and other materials stored in your Pieces Drive. Additionally, you can use search filters to refine your results.

### via Search Command

If you want to access your saved snippets directly within Pieces CLI, you can:

    Accessing a terminal on your device varies by platform: Use your OS's search bar to type in `terminal` (for macOS/Linux) or `CMD` (for Windows).

    Within your terminal, you can now enter `pieces search “query”`. This will start a new search using your query to search through your Pieces Drive.

    Alternatively, you can launch into Pieces CLI run mode with `pieces run`. This will enable you to just enter `search “query”`.

You can optionally add `--mode` followed by the search method you prefer:

* `ncs`: Performs a neural code search for your query.

* `fts`: Performs a full-text search for your query.

For example, `pieces search "query" --mode fts` will use the full-text search on your database with your query.

## Viewing and Reusing Saved Snippets

[Saved snippets](/products/cli/drive/saving-materials) can be viewed by opening them up directly from the Pieces Drive with `pieces list`, using your scroll wheel or arrow keys, and selecting the snippet with the `return` (macOS) or `enter` (Windows/Linux) key, all from within your terminal.

In your terminal, you can also open snippets with the `pieces search “query” [optional: --mode ncs,fts]` command. If Pieces finds snippets that match your query, you will be presented with a list of snippets.

You can open a snippet from the list using your scroll wheel or arrow keys and select it with the `return` (macOS) or `enter` (Windows/Linux) key.

***

## Real-Time Snippet Streaming

Every product in the Pieces Suite uses [PiecesOS](/products/core-dependencies/pieces-os) to collect information about the context of your snippets.

When you change a snippet in the [Pieces Desktop App](/products/desktop)—such as its name, description, tags, or any other metadata—those updates automatically appear in your Pieces Drive without needing to refresh.

  If your snippets aren’t updating immediately, refer to the troubleshooting guide for guidance on refreshing your snippet list.

---

## Sharing Snippets
Path: /products/cli/drive/sharing

## How to Share a Saved Snippet

Sharing a saved snippet is easy with the Pieces CLI. It enables you to collaborate with other developers, coworkers, and members even if they are outside of your organization or don’t have a Pieces account.

### via Command

Read below for detailed steps on using the `share` command within the Pieces CLI.

    To access a terminal on your device, the method depends on your platform: use the search bar of your OS to type in `terminal` for macOS/Linux or `CMD` for Windows.

    To share a snippet, enter the `pieces share` command.

    If you’re within the Pieces CLI run mode, you can enter `share`.

    In the new view, use your arrow keys to navigate your saved snippets. When you’ve located the snippet you’d like to share, press `return` (macOS) or `enter` (Windows/Linux).

    This will begin the process of sharing the snippet using the Pieces CLI.

    After the snippet has been shared, its URL will appear within the terminal, and the CLI will prompt you to open the snippet in a browser.

    Open it in a browser with `y` or deny it with `n`. After entering your option, press `return` (macOS) or `enter` (Windows/Linux).

## Enriched Sharing Experience

When you `share` a snippet, it’s not just the code that’s included. The snippet comes with additional metadata to provide context—<a target="_blank" href="/products/cli/drive/sharing#what-information-gets-shared">you can read more about that here.</a>

* `Snippet Type`: Identify the language or framework, such as Python or React.

* `Tags`: Useful keywords for quick categorization.

* `Description`: A summary of what the snippet does.

* `Related Links`: Helpful resources or documentation tied to the snippet.

* `Author Information`: A record of who created the snippet.

## What Information Gets Shared

When you save a snippet to the Pieces Cloud, the code is [enriched with valuable information](/products/cli/drive/saving-materials#what-s-stored-when-you-save-a-snippet), such as related people, links, annotations, tags, and an automatically generated description.

This information appears to the right of the code block when the shared snippet is open in your browser:

### Sensitive Information Watchdog

The share command does more than enable you to share snippets with your entire team and other communities effectively.

You'll see a section titled **Sensitive Information:**

Our in-house ML model scans snippets for potentially sensitive information, such as API keys or passwords, and alerts you so you can make an informed decision before sharing the snippet.

---

## Get Started
Path: /products/cli/get-started

<pieces-pro-cta />

## Pieces CLI Prerequisites

Before installation, you’ll need:

* **PiecesOS:** The power engine behind the Pieces CLI and the rest of the Pieces Suite. [Learn more about PiecesOS](/products/core-dependencies/pieces-os).

* **Python 3.xx:** <a target="_blank" href="https://www.python.org/downloads/">Python</a> is required to be installed on your development machine.

  PiecesOS must be installed to use the Pieces CLI and ensure it works properly. 

  We also suggest using the Pieces Desktop App for better functionality.

### Sign in Required

Pieces requires all users to sign in before using any Pieces products, including MCP integrations and the CLI. You'll be prompted to authenticate if you haven't already. For help, see our [sign-in guide](/products/meet-pieces/sign-into-pieces).

## Installing the Pieces CLI

Follow the instructions below to install the Pieces CLI and any required dependencies.

    Head to [Python’s website](https://www.python.org/downloads/) and download the version that best suits your environment.

    After downloading the Python version 3.xx, you will be guided through the installation process. Follow their steps until Python is installed.

      Make sure to allow Python to be added to your environment variables, so it’s executable via terminal.

    Once Python is installed, its dependency `pip` is automatically installed. Choose your OS:

        Install the Pieces CLI on Windows using Python’s launcher:

        ```bash
        py -m pip install pieces-cli
        ```

        Install with Homebrew on macOS:

        ```bash
        brew install pieces-cli
        ```

        Install with pip3 on Linux:

        ```bash
        pip3 install pieces-cli
        ```

    To verify a successful installation of the Pieces CLI, you can type `pieces version` within your terminal. This will display your Pieces OS and Pieces CLI versions.

      If you receive **'pieces' is not recognized as an internal or external command,** you can run pieces with `py -m pieces $command`.

    To run Pieces CLI, you can enter the command `pieces run`. This will launch you into the Pieces CLI and make it so you don’t have to prefix with `pieces`.

### Setting Up PiecesOS

To use the Pieces CLI, you must install [PiecesOS](/products/core-dependencies/pieces-os) on your working environment.

Click the download buttons or follow the set-up instructions below for your operating system:

<get-started-install />

  For enhanced security and better system integration, we recommend installing the `.appinstaller` package over the `.exe` installer. The `.appinstaller` package operates in a containerized environment, providing additional security benefits.

## Updating

Follow the steps below to update the Pieces CLI.

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal` (macOS/Linux) or `CMD` (Windows).

    Choose your OS:

        Update to the latest Pieces CLI on Windows:

        ```bash
        py -m pip install pieces-cli -U
        ```

        Upgrade with Homebrew on macOS:

        ```bash
        brew upgrade pieces-cli
        ```

        Update with pip3 on Linux:

        ```bash
        pip3 install pieces-cli -U
        ```

## Onboarding

The Pieces CLI offers a walkthrough to guide you through the steps of saving your first material and introduces you to the Long-Term Memory Engine (LTM-2.7), enabling you to make the most of the Pieces CLI.

### Save Your First Material

The onboarding will start by providing you with a snippet to copy to your clipboard. Highlight the code and press `⌘+c` (macOS) or `ctrl+c` (Windows/Linux).

After copying the snippet, you can select any key on your keyboard to proceed.

  If you haven’t copied the snippet, Pieces won’t allow you to paste.

After pressing any key, Pieces will prompt you to type `pieces create` into your terminal. With the snippet still copied, enter `pieces create`, and Pieces will ask if you want to save the snippet.

Type `y` and press `return`(macOS) or `enter`(Windows/Linux) to confirm to save the snippet to your [Pieces Drive](/products/cli/drive).

### Finding your Saved Materials

In this step, you'll learn how to open your saved materials. Start by typing `pieces list` in your terminal and pressing `enter`.

This will display a list of all your saved materials. You can navigate through them using the arrow keys on your keyboard.

Select the material you're highlighting by pressing `return`(macOS) or `enter`(Windows/Linux).

### Start a Session

After selecting a snippet, Pieces CLI will boot you out to the terminal to prompt you to start a new session.

Typing `pieces run` will open a new session, allowing you to enter Pieces commands without prefixing with `pieces`.

After the session, you can type exit and press `return`(macOS) or `enter`(Windows/Linux) to return to the onboarding.

### Chat with the Copilot

This section will walk you through how to ask [Conversational Search](/products/cli/copilot) its first question. You can begin in your terminal by typing `pieces ask 'How to print I love Pieces CLI in Python and Java'` and pressing `return`(macOS) or `enter`(Windows/Linux).

After typing your question and running the command, Conversational Search will quickly generate and display the best response for your query.

It will then prompt you to do it with the Pieces CLI running by typing `pieces run` entering the command and then entering `ask $question`, `$question` being the question you’d like to ask Conversational Search.

  Your question must be encased in quotations or Pieces won’t capture your full question.

### More Resources

Your feedback is **vital** to us. This onboarding step will prompt you to enter `pieces feedback` where you can optionally open the GitHub discussion board related to Pieces CLI to leave helpful feedback.

If you enter `y` it will open the GitHub discussion board in a new tab in your browser, otherwise it will skip this step.

After completing the <a target="_blank" href="https://github.com/pieces-app/cli-agent/discussions/194">feedback</a>, Pieces will prompt you to type `pieces contribute` and then ask if you’d like to open the <a target="_blank" href="https://github.com/pieces-app/cli-agent">source code for Pieces CLI on GitHub</a> to improve it. You can optionally say yes by entering `y`; otherwise, enter `n`.

## Uninstalling

Follow the steps below to uninstall the Pieces CLI.

If you also want to uninstall PiecesOS, [follow these steps](/products/core-dependencies/pieces-os/manual-installation#uninstalling-piecesos).

    Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter `terminal`(macOS/Linux) or `CMD`(Windows).

    Choose your OS:

        Uninstall on Windows:

        ```bash
        py -m pip uninstall pieces-cli
        ```

        Uninstall with Homebrew on macOS:

        ```bash
        brew uninstall pieces-cli
        ```

        Uninstall with pip3 on Linux:

        ```bash
        pip3 uninstall pieces-cli
        ```

---

## Troubleshooting
Path: /products/cli/troubleshooting

***

## Troubleshooting the Pieces CLI

Most CLI issues clear up after updating to the latest version, restarting PiecesOS, or restarting your shell. If those don't help, find your symptom in *Common Issues* below.

## Update Pieces CLI

The first thing to try for any unexpected behavior. An outdated CLI is the single most common cause of broken commands and integration errors.

  Before updating, close any running instance of the Pieces Desktop App and PiecesOS. On Windows, run your terminal as administrator (right-click `Command Prompt` or `PowerShell` → `Run as administrator`).

    ```bash
    pip install pieces-cli -U
    ```

    ```bash
    conda update pieces-cli
    ```

    ```bash
    brew upgrade pieces-cli
    ```

PiecesOS may also need updating—if updating the CLI alone doesn't help, [reinstall PiecesOS](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) and restart your system so any new environment variables take effect.

## Common Issues

Find your symptom below for the recommended fix.

    Your shell can't locate the `pieces` binary on your `PATH`.

    - Confirm the CLI is installed: `pip install pieces-cli` (or your package manager of choice—see *Update Pieces CLI* above).
    - Restart your shell so any new `PATH` entries take effect. On macOS/Linux you can also run `source ~/.zshrc` or `source ~/.bashrc`.
    - If you installed with `pip install --user`, make sure your Python user-scripts directory is on your `PATH`.
    - On Windows, close and reopen `Command Prompt` or `PowerShell` after install so it picks up the new `PATH`.

    The CLI needs PiecesOS running in the background to serve your Pieces Drive and *Conversational Search* requests.

    - Start it with `pieces open`, or launch the Pieces Desktop App or applet manually.
    - Confirm it's running: `pieces version` should return a PiecesOS version alongside the CLI version.
    - If PiecesOS won't start at all, [reinstall it](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation).

    Common when you're using a cloud LLM and your network drops—the model can appear to generate forever, loop, or eventually time out.

    - Force-quit the active chat with `⌘+C` (macOS) or `Ctrl+C` (Windows/Linux), then re-issue your `pieces ask "..."` command.
    - Switch to a different model with `pieces list models`. If one provider is degraded, another usually still works.
    - Confirm you're online and that your firewall or VPN isn't blocking the CLI's outbound HTTPS traffic.

    Upgrades sometimes need the system to settle before everything lines up.

    - Restart your terminal—and your computer if you also updated PiecesOS.
    - Run `pieces version` and confirm the CLI and PiecesOS versions are both current. If one lags, update the lagging side.
    - If errors persist, [reinstall PiecesOS](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation).

    Your user doesn't have permission to write to the install location.

    - On Windows, run your terminal as administrator and retry the update command.
    - On macOS/Linux, prefer a user-scoped install with `pip install --user pieces-cli`. Avoid `sudo pip install`—it can leave your system Python in a broken state.
    - With Conda, run `conda update pieces-cli` from the same environment where you originally installed it.

***

## Still Stuck?

If none of the above resolves your issue, reach out and we'll help.

- File a <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> with your CLI version (`pieces version`), OS, and a description of the problem.
- Or <a target="_blank" href="https://getpieces.typeform.com/to/mCjBSIjF#docs-vscode">contact the Pieces support team</a> directly.

---

## Text User Interface (TUI)
Path: /products/cli/tui

## Interactive Terminal Experience

The Pieces CLI Text User Interface (TUI) provides an interactive, terminal-based experience for managing materials and interacting with Conversational Search.

When you launch the TUI with `pieces tui`, you're greeted with the Copilot interface featuring a sidebar for navigation, chat area for conversations, and keyboard shortcuts for quick access.

## Workstream Activities

Use `shift+ctrl+w` to navigate to the Workstream view. Once there, you can manage your workstream activities. 

Select an activity from the left sidebar to view its content in read mode or switch to edit mode `ctrl+e` to modify it. Save your changes with `ctrl+s`.

## TUI As a Daily Driver

The TUI is a powerful, adaptable tool that improves your workflow the more you use it—*so use it!*

***

    Jump straight into conversations with Copilot. No need to dig through menus. Just start typing!

    Copilot knows what you're working on and keeps track of your materials, so you don't have to repeat yourself or explain context every time.

    Everything you need is just a few keystrokes away. Stay in the flow without reaching for the mouse.

---

## TUI Commands
Path: /products/cli/tui/commands

## Pieces TUI Commands

Below is a comprehensive table containing every command and shortcut available in the Pieces TUI (Text User Interface).

***

## Keyboard Shortcuts

All TUI commands use `ctrl` key combinations for consistency across macOS, Windows, and Linux platforms.

| **Command** | **Shortcut** | **Description** |
| ----------- | ------------ | --------------- |
| **Open Command Palette** | `ctrl+p` | Access the command palette to search and execute any TUI command |
| **New Conversation** | `ctrl+n` | Start a new conversation in the Copilot chat interface |
| **Toggle Sidebar** | `ctrl+s` | Show or hide the navigation sidebar |
| **Refresh** | `ctrl+r` | Refresh the current view and reload content |
| **Change Model** | `shift+ctrl+m` | Switch between available AI models for Copilot |
| **Toggle LTM (Long Term Memory)** | `ctrl+l` | Enable or disable Long Term Memory for context retention |
| **Switch to Workstream** | `shift+ctrl+w` | Navigate to the Workstream Activities view |
| **Switch to Copilot** | `shift+ctrl+c` | Navigate to the Copilot chat interface |
| **Toggle Edit Mode** | `ctrl+e` | Switch between read and edit modes in Workstream view |

***

## Command Palette Actions

The command palette provides access to additional TUI functions and settings:

| **Command** | **Description** |
| ----------- | --------------- |
| **Change Theme** | Switch between available color themes to customize your TUI appearance |
| **Quit the Application** | Exit the TUI application immediately |
| **Save Screenshot** | Capture the current screen as an SVG screenshot for documentation or sharing |
| **Show Keys and Help Panel** | Display the keys and help panel for the currently focused widget with available shortcuts |
| **Switch to Workstream Activity** | Access the context-aware AI that helps with code, documentation, and workflow tasks |

***

## Using the Command Palette

You can easily access all commands through the **Command Palette** using `ctrl+p`.

Simply type in the search bar to filter available commands and use arrow keys to navigate through results. Press `enter` to execute the selected command.

***

---

## TUI Copilot
Path: /products/cli/tui/copilot

## Getting Started with TUI Copilot

The TUI Copilot provides a full-featured chat interface directly in your terminal. The interface is divided into three main areas: chat history, conversation window, and quick options.

## Chat History

    Click the `+ New Chat` button at the top of the left sidebar. This creates a fresh chat session while keeping your previous conversations accessible.

    Click on any chat entry in the sidebar to continue where you left off. The currently active chat is highlighted in light green.

    Scroll down in the sidebar to see relevant snippets and context that Copilot can reference during your conversations.

## Conversation Window

    At the bottom of the chat view, you can find the message bar. When you send a message, your messages will appear in blue and Conversational Search will respond in green.

    Check the top of chats for background information that Copilot uses to provide more accurate responses.

    Use the scrollbar to review previous messages and timestamps in your current chat session.

## Quick Options

    Type in the input bar at the bottom and press `return` (macOS) or `enter` (Windows/Linux) to send your question to Copilot.

    Use these shortcuts for quick access:

    * **`ctrl+s`:** Toggle the sidebar on/off
    * **`ctrl+n`:** Start a new chat
    * **`shift+ctrl+m`:** Change the AI model
    * **`ctrl+l`:** Toggle Long-Term Memory context
    * **`shift+ctrl+w`:** Switch to Workstream view
    * **`ctrl+p`:** Open the command palette

## TUI Copilot As a Daily Driver

The TUI Copilot brings the full power of Conversational Search directly to your terminal, making AI assistance accessible wherever you work.

---

## Get Started
Path: /products/cli/tui/get-started

<pieces-pro-cta />

## TUI Prerequisites

Before you can use the Pieces CLI Text User Interface (TUI), you'll need:

* **Python 3.xx:** [Python](https://www.python.org/downloads/) is required to be installed on your development machine.

* **PiecesOS:** The core engine that powers all Pieces tools. [Learn more about PiecesOS](/products/core-dependencies/pieces-os).

* **Pieces CLI:** The command-line interface that powers the TUI. [Learn how to install the Pieces CLI](/products/cli/get-started).

  PiecesOS must be installed to use the Pieces CLI and ensure it works properly.

  We also suggest using the Pieces Desktop App for better functionality.

### Sign in Required

Pieces requires all users to sign in before using any Pieces products, including MCP integrations and the CLI. You'll be prompted to authenticate if you haven't already. For help, see our [sign-in guide](/products/meet-pieces/sign-into-pieces).

## Installing the TUI

The TUI is included with the Pieces CLI installation, but requires a one-time setup step on first launch. Once you have the CLI installed, you can set up and access the TUI.

On your first launch, you'll need to run `pieces tui install` to download and set up the TUI components. This is a one-time setup process.

  If you haven't installed the Pieces CLI yet, follow the [CLI installation guide](/products/cli/get-started) first.

## Launching the TUI

To start using the TUI, follow these simple steps:

    Open your terminal application:
    * **Windows:** Press `win+r`, type `cmd` or `powershell`, and press `enter`
    * **macOS:** Press `cmd+space`, type `terminal`, and press `return`
    * **Linux:** Press `ctrl+alt+t` or search for "Terminal" in your applications

    After installation, launch the TUI with:

    ```bash
    pieces tui
    ```

    This will launch the interactive Text User Interface.

    Once the TUI loads, you'll see the main interface with:
    * A sidebar for navigation
    * A chat area for conversations with Copilot
    * Keyboard shortcuts for quick access

### Navigation Shortcuts

Use these keyboard shortcuts to navigate efficiently:

* `tab`: Navigate between interface elements
* `shift+ctrl+w`: Switch to Workstream view
* `ctrl+e`: Toggle edit mode in Workstream
* `ctrl+s`: Save changes
* `esc`: Return to previous view or exit current mode

## Your First TUI Session

Let's walk through your first interaction with the TUI to get you comfortable with the interface.

### Starting a Conversation with Copilot

    Open your terminal and run `pieces tui`

    Once the interface loads, you can start typing directly in the chat area at the bottom of your terminal.

    Press `return` (macOS) or `enter` (Windows/Linux) to send your question. Copilot will open a new chat and respond if not already in a chat.

  **New Chat Button:** You can start a fresh conversation anytime by clicking the "+new chat" button at the top of the left sidebar. This creates a new chat session while keeping your previous conversations accessible.

### Exploring Workstream Activities

    Use `shift+ctrl+w` to navigate to the Workstream section.

    Use arrow keys to navigate through your workstream activities in the left sidebar.

    Press `return` (macOS) or `enter` (Windows/Linux) to open the selected workstream.

    Select an activity to view its content in read mode.

    Press `ctrl+e` to switch to edit mode and make changes.

## Uninstalling

Follow the steps below to uninstall the TUI.

    Opening a terminal on your device depends on your platform: Open your OS' search bar and enter `terminal` (macOS/Linux) or `CMD` (Windows).

    Choose your OS:

        Uninstall on Windows:

        ```bash
        py -m pip uninstall pieces-cli
        ```

        Uninstall with Homebrew on macOS:

        ```bash
        brew uninstall pieces-cli
        ```

        Uninstall with pip3 on Linux:

        ```bash
        pip3 uninstall pieces-cli
        ```

  If you also want to uninstall PiecesOS, [follow these steps](/products/core-dependencies/pieces-os/manual-installation#uninstalling-piecesos).

---

## TUI Workstream Activities
Path: /products/cli/tui/workstream

## Workstream Activities Overview

The TUI Workstream Activities view provides terminal-based access to your Long-Term Memory (LTM-2.7) roll-ups and workflow summaries. Access this feature directly from your command line to view, edit, and manage your workstream activities.

## Accessing Workstream Activities

    Use `shift+ctrl+w` from anywhere in the TUI, or click the `Switch to Workstream` button at the bottom of the interface.

    Use arrow keys to navigate through the list of workstream activities in the left sidebar.

    Press `return` (macOS) or `enter` (Windows/Linux) to select an activity and view its content in the right panel.

    Press `ctrl+e` to toggle into edit mode and modify the activity content.

    Press `ctrl+s` to save any modifications made in edit mode.

## Workstream Activity Content

Each workstream activity contains structured information captured by the LTM-2.7 engine:

## Keyboard Shortcuts

    Use these shortcuts to navigate and interact with workstream activities:

    * **`shift+ctrl+w`:** Switch to workstream view
    * **`ctrl+e`:** Toggle edit mode
    * **`ctrl+s`:** Save changes
    * **`ctrl+p`:** Open command palette
    * **`shift+ctrl+c`:** Switch to Copilot

---

## Core Dependencies
Path: /products/core-dependencies

## What Are Core Dependencies?

Pieces products, including the [Pieces Desktop Application](/products/desktop), are built on [PiecesOS](/products/core-dependencies/pieces-os), which provides a local, secure, and efficient experience with built-in AI capabilities.

## What Is PiecesOS?

To run any Pieces software, you will need **PiecesOS,** the backbone of the Pieces Suite. This lightweight application runs in the background of your device.

It powers the [Long-Term Memory (LTM-2.7) Engine](/products/core-dependencies/pieces-os#ltm-27) and [Conversational Search](/products/desktop/conversational-search). [Pieces Drive](/products/desktop/drive) is a **legacy** material manager retained for existing workflows; LTM and [Timeline](/products/desktop/timeline) replace it for new users.

**PiecesOS**: The backbone of the Pieces suite, managing local memory, AI-driven workflow enhancements, [Pieces MCP](/products/mcp), and other integrations within your development environment.

## On-Device Processing

PiecesOS runs directly on your device and powers core Pieces capabilities without sending your data to the cloud:

- **Long-Term Memory (LTM-2.7)** workflow capture and processing
- **Code enrichment** and analysis
- **Secret detection** and security scanning
- **Metadata and tag generation**

Capture, indexing, and storage happen entirely on your device through PiecesOS. AI features that need a large language model—like [Conversational Search](/products/desktop/conversational-search)—send only scoped, relevant context to a cloud model for that request.

## What Does PiecesOS Do?

PiecesOS is a lightweight service that handles everything from on-device context capture and storage to coordinating AI-assisted workflows.

PiecesOS is **required** for all Pieces products, including:

* Pieces Desktop App

* [MCP integrations](/products/mcp) for [JetBrains IDEs](/products/mcp/jetbrains-ides), [VS Code](/products/mcp/vs-code), [Raycast](/products/mcp/raycast), and [many other tools](/products/mcp), plus [the Pieces CLI](/products/cli).

## Why Do We Need PiecesOS?

Pieces is designed with **speed and efficiency** in mind, so PiecesOS acts as the central hub between different Pieces products to minimize client-side overhead and additional code while also being secure and highly configurable.

Our focus on **security and flexibility** is why PiecesOS does as much as possible on your device. By keeping capture and storage local, the user experience benefits from:

* **100% local memory storage** with full control over data.

* **Scoped cloud requests**, so only the relevant context for a given prompt is ever sent to an AI model.

* **Lightweight, background operation**, consuming minimal system resources.

This is especially useful in enterprise settings where strong device security is important.

***

| **Dependency** | **Purpose**                                                           | **Required?**                                   |
| -------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
| *PiecesOS*     | Manages memory, developer material storage, and MCP client communication, capturing and storing your context on-device. | Yes — this is required for all Pieces products. |

***

---

## On-Device Storage
Path: /products/core-dependencies/on-device-storage

## Local-First Architecture

Pieces stores and processes everything on your device by default—code snippets, LTM-2.7 memory, user settings, Conversational Search history, and diagnostic logs all stay local.

**When data can move to the cloud:** Only when you explicitly enable **Personal Cloud** or use a cloud-based model provider (OpenAI, Anthropic, Google). In those cases, data is handled by the provider's privacy policy.

  We're **SOC 2 Type II** certified and never use your data to train models. You can delete everything at any time by removing the `com.pieces.os` and `com.pieces.pfd` folders from your Library (macOS) or equivalent paths on other platforms.

## Where Your Database Lives

| **Platform** | **Default path** |
| --- | --- |
| *macOS* | `/Users/<username>/Library/com.pieces.os/` |
| *Windows (PiecesOS)* | `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\` |
| *Windows (Desktop App)* | `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\` |
| *Linux* | `/home/<username>/.local/share/com.pieces.os/` |

Inside `com.pieces.os`, the `production` folder contains your LTM-2.7 context and all other Pieces data. You can **copy**, **compress**, or **relocate** this folder to sync via OneDrive or migrate to another machine.

The Pieces Desktop App stores additional data in a separate `com.pieces.pfd` folder (`~/Library/com.pieces.pfd/` on macOS, or `...\Pieces for Developers\com.pieces.pfd\` on Windows). For a full backup, copy both folders from their respective parent directories on Windows.

  Replace `<username>` with your OS account name.

## Finding Your Logs

When opening a GitHub issue or contacting support, attaching recent logs helps diagnose problems quickly.

| **Platform** | **Log path** |
| --- | --- |
| *macOS (PiecesOS)* | `/Users/<username>/Library/com.pieces.os/production/Support/logs/` |
| *macOS (Desktop App)* | `/Users/<username>/Library/com.pieces.pfd/production/logs/` |
| *Windows (PiecesOS)* | `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support\` |
| *Windows (Desktop App)* | `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\production\logs\` |
| *Linux* | `/home/<username>/.local/share/com.pieces.os/logs/` |

  On Windows, if `AppData` is hidden in File Explorer, enable `View` → `Show` → `Hidden items`. You can also press `Win+R` and paste the path above. PiecesOS and the Desktop App use different parent folders under `Mesh Intelligent Technologies, Inc\`.

Zip the latest two or three log files from the path above and attach them to your <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> or Discord DM.

## Backup & Restore

Pieces supports two backup approaches. Use **manual folder backup** for a full copy of your on-device database (including Long-Term Memory). Use **Personal Cloud backup** for snapshots of app data you can restore from the Desktop App on any device where you're signed in.

| Method | Best for | Requires |
| --- | --- | --- |
| **Manual folder backup** | Full LTM database, migration, offline archives | Quitting Pieces, copying `com.pieces.os` (and `com.pieces.pfd`) |
| **Personal Cloud backup** | Snippets, Drive files, settings, chat history | Connected [Personal Cloud](/products/desktop/configuration/account#personal-cloud) |

### Manual Backup

Copy your on-device database folders directly. This is the most complete option if you need everything in `production`, including Long-Term Memory context.

    Close the Pieces Desktop App and PiecesOS.

    Copy the entire `com.pieces.os` folder to your backup location (USB, NAS, or cloud storage):

    * **macOS:** `/Users/<username>/Library/` (copy both `com.pieces.os` and `com.pieces.pfd`)
    * **Windows:** Copy `...\Pieces OS\com.pieces.os\` and `...\Pieces for Developers\com.pieces.pfd\` from `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\`
    * **Linux:** `/home/<username>/.local/share/com.pieces.os/`

### Backup via Personal Cloud

Create a snapshot from the Pieces Desktop App. Backups are stored in your personal Pieces Cloud and can be restored or deleted from the same modal.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll to the *Personal Cloud* section. In *Backup & Restore Data*, click the `Restore Icon` (circular arrow) to open the modal.

    In the *Create Backup* section, click the `Cloud Icon with Upward Arrow` to upload a new backup to your personal Pieces Cloud.

Cloud backups include snippets, Pieces Drive files, user preferences, Conversational Search data, search and tagging data, and linked account connections (without passwords). They do not replace a full manual copy of your `com.pieces.os` database if you need to preserve raw Long-Term Memory data.

  For the full backup workflow, including what's included, viewing backups, and deleting old snapshots, see [Backup & Restore Data](/products/desktop/configuration/account#backup--restore-data) in Account settings.

## Restore on a New Machine

### Restore a Manual Backup

Use this when you copied `com.pieces.os` (and optionally `com.pieces.pfd`) to another drive or machine.

    Install PiecesOS on the new machine via the [Pieces Desktop App](/products/desktop/onboarding) or [manual installation](/products/core-dependencies/pieces-os/manual-installation).

    Replace the newly created `com.pieces.os` folder with your backup. Also restore `com.pieces.pfd` if you backed it up.

    Relaunch PiecesOS and the Pieces Desktop App.

### Restore a Personal Cloud Backup

Use this when you created a backup through *Backup & Restore Data* in Account settings.

    On the target machine, open `Settings` → `Account`, scroll to *Personal Cloud*, and connect your cloud if you are not already signed in.

    In the *Personal Cloud* section, click the `Restore Icon` in *Backup & Restore Data* to open the modal.

    In the *Backups* list, find the snapshot you want, then click the `Restore Icon` on that entry and confirm when prompted.

## Start Fresh (Reset)

    Close the Pieces Desktop App and PiecesOS.

    Rename the `production` folder inside `com.pieces.os` to something else (e.g., `production-backup`).

    Relaunch PiecesOS. It will create a brand-new, empty database. Keep the renamed folder as a backup in case you need it.

***

## Next Steps

* [Long-Term Memory settings](/products/desktop/configuration/long-term-memory) — clear stored data, app access, and permissions.
* [Account settings](/products/desktop/configuration/account#backup--restore-data) — Personal Cloud backup and restore.
* [Support](/products/support) — report issues and find platform log paths.

## Need Help?

Open a GitHub issue for PiecesOS, the Pieces Desktop App, or any MCP integration at <a target="_blank" href="https://github.com/pieces-app/support/issues">our GitHub repository</a>.

You can also <a target="_blank" href="https://getpieces.typeform.com/to/mCjBSIjF#page=docs-support">leave feedback or report a bug here.</a>

---

## What is PiecesOS?
Path: /products/core-dependencies/pieces-os

**Action required:** Cloud services no longer work on PiecesOS versions prior to 12.4.0 (deprecated June 5th 2026). Update to 12.4.0 or later to restore Chat, Work Summaries, and Single Click Summaries.

## What is PiecesOS?

**PiecesOS** is a background service that runs on your machine. It orchestrates on-device data capture and storage, coordinates AI model requests, and serves as the bridge between your workflow and every Pieces product—including the [Pieces Desktop App](/products/desktop/onboarding), [MCP integrations](/products/mcp), and the [CLI](/products/cli).

<piecesos-bridge-diagram />

## What PiecesOS Does

PiecesOS powers three core capabilities:

### Agentic Long-Term Memory (LTM-2.7)

The [LTM-2.7 Engine](/products/core-dependencies/pieces-os/long-term-memory) continuously captures workflow context—code you copy, screens you view, audio you hear—and stores it **locally on your device**. This memory powers [Timeline](/products/desktop/timeline), [Conversational Search](/products/desktop/conversational-search) (Agentic Chats), and [Single-Click Summaries](/products/desktop/single-click-summaries) (Agentic Summaries) with real context from your day.

The agent reasons across your memory in multiple turns, following threads, cross-referencing context, and building complete answers instead of one-shot guesses. It can search your memories, the web, your calendar, local files, and browser history automatically.

### AI Models

PiecesOS coordinates AI model requests for all Pieces products. Choose from three model families—Claude, Gemini, and ChatGPT—each available in Fast, Balanced, and Extra Thinking modes. See [Choose a Model](/products/desktop/conversational-search/models) to pick a family and mode.

### MCP Support

The [Model Context Protocol (MCP)](/products/mcp) is an open framework that lets LLMs access your workflow context. PiecesOS serves as the MCP host, connecting tools like Cursor, VS Code, Claude, and ChatGPT to your Long-Term Memory without custom integrations.

> Pieces MCP integration with Cursor showing context-aware documentation changes

## Privacy & Local-First Design

All data captured by PiecesOS is stored **locally on your device**. Capture, indexing, and storage happen on-device, and PiecesOS applies on-device ML to filter out sensitive information and secrets.

  AI features that need a large language model run in the cloud, where only the scoped context for that request is sent—the rest of your data stays on your machine. We're **SOC 2 Type II** certified and never use your data to train models. [Learn more about privacy and on-device storage.](/products/core-dependencies/on-device-storage)

## Installing PiecesOS

PiecesOS installs automatically with the [Pieces Desktop App](/products/desktop/onboarding). If you want to run it standalone (for example, with MCP integrations only), see [Manual Installation](/products/core-dependencies/pieces-os/manual-installation).

***

## Explore PiecesOS

  Learn about Agentic Long-Term Memory, the agent toolbox, and how to enable, pause, and control memory capture.

  Manage PiecesOS settings, LTM, MCP, ML processing, and updates from the menu bar or system tray.

  Where Pieces stores your data locally, how to find logs, and how to back up or reset your database.

  Fix common installation issues, check system specs, update PiecesOS, and find logs on macOS, Windows, and Linux.

---

## LTM-2.7 Engine
Path: /products/core-dependencies/pieces-os/long-term-memory

## What is the LTM-2.7 Engine?

The **Long-Term Memory (LTM-2.7) Engine** is PiecesOS's core memory system. It runs entirely on your device and continuously captures workflow context—code you copy, screens you view, audio you hear—so Pieces can power [Timeline](/products/desktop/timeline), [Conversational Search](/products/desktop/conversational-search), and [MCP integrations](/products/mcp) with real context from your day.

All captured data is processed and stored **locally**. Nothing leaves your machine unless you explicitly choose to share it. See [Privacy & On-Device Storage](/products/core-dependencies/on-device-storage).

The primary control point for LTM is the **[PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu)**—the Pieces icon in your menu bar (macOS, Linux) or system tray (Windows).

***

## Agentic Long-Term Memory

**Agentic LTM** powers a new generation of [Conversational Search](/products/desktop/conversational-search) (Agentic Chats) and [Single-Click Summaries](/products/desktop/single-click-summaries) (Agentic Summaries). Instead of answering questions in one shot, the agent now reasons across your artificial memory in **multiple turns**: following threads, cross-referencing context, and building toward complete answers.

### Multi-Turn Reasoning

When an initial fetch from your LTM leaves a gap, the agent recognizes it and goes back for more. It cross-references context from summaries, conversations, events, and people, building on prior turns within the same conversation so follow-ups feel like a real dialogue.

### What the Agent Can Access

During any chat or summary, the agent can autonomously:

* **Search your memories** across summaries, events, people, hints, and captured sources
* **Search the web** for real-time information with citations (powered by Perplexity)
* **Read your calendar** and create, update, or delete events (requires [Google Calendar connector](/products/desktop/connectors/google-calendar))
* **Search local files** by path, grep file contents, and read files from your machine
* **Look up browser history**, bookmarks, and recent activity across your browsers
* **Reference your user persona**, the Pieces-generated profile describing who you are and the kinds of things you work on
* **Compute time ranges** by parsing natural language like *"last Tuesday"* or *"this quarter"* into precise queries

The agent decides what to access based on your question. You don't need to configure anything, it gathers evidence automatically and builds answers from multiple sources.

### What This Enables

The agentic foundation powers features like [Meeting Prep](/products/desktop/single-click-summaries/default-types#meeting-prep) (summaries that take action on your behalf), [Reflection Mode](/products/desktop/conversational-search#reflection-mode) (metacognition for the agent), and deeper multi-step investigations in chat.

***

## Enabling, Pausing & Disabling LTM

### Enabling LTM

    Click the `Pieces` icon in your taskbar (Windows) or menu bar (macOS, Linux).

    Click `Enable Long-Term Memory Engine`.

> LTM toggle in the PiecesOS Quick Menu

### Pausing or Disabling LTM

When LTM is active, the Quick Menu shows a green `On` button. Click it to pause or turn capture off. You can pause *LTM-2.7* and *LTM Audio* for any length of time, from a few minutes to several days, instead of only fixed presets.

Pieces shows a clear **Paused until** label so you always know when capture resumes. Use this for a confidential call, a stretch of personal browsing, or a few days off.

| Option | Effect |
| --- | --- |
| *Custom pause* | Pause for a duration you choose (minutes, hours, or days); resumes automatically at the *Paused until* time |
| *Turn Off* | Fully disables LTM until you re-enable it manually |

  Use a timed pause for a temporary break, such as a private call or personal browsing, instead of turning LTM off entirely.

You can pause from:

* The **PiecesOS Quick Menu**
* The **user popover** in Pieces Desktop (`User Profile` → hover `LTM-2.7`)
* **Settings** → `Long-Term Memory` in Pieces Desktop

    Click your `User Profile` in the top left of the Pieces Desktop App.

    Hover over `LTM-2.7` to choose a pause duration, or hover over `Settings` and select `Long-Term Memory` for full controls.

For a full breakdown of every toggle and option in that settings panel, see [LTM Settings](/products/desktop/configuration/long-term-memory).

### When Capture Stops Automatically

Capture slows down when you step away:

* When your **screen is locked**, Pieces stops capturing entirely.
* When you go **idle**, Pieces captures less often instead of sampling at full rate, so an unattended laptop isn't recording a screen nobody is looking at.

***

## LTM Audio

**LTM Audio** extends capture to system audio and microphone input—meeting recordings, video calls, podcasts, or your own voice during a call.

    Click the `Pieces` icon in your taskbar or menu bar.

    Scroll to *LTM Audio* and toggle it on.

  On macOS, LTM Audio requires **System Audio Capture** and **Microphone Access** permissions before it can be enabled. First-time users may see a yellow warning indicator on their User Profile inside the Desktop App—click it to grant the required permissions. See [LTM Audio setup](/products/desktop/configuration/long-term-memory#ltm-audio) for full per-platform instructions.

***

## Long-Term Memory Access Control

Access Control lets you decide exactly which applications LTM captures data from.

    Click the `Pieces` icon in your taskbar or menu bar.

    Navigate to *Long-Term Memory Access Control*.

You'll see two views:

### Enabled Sources

A live list of all apps currently feeding data into LTM (for example, Google Chrome, VS Code, Slack).

> Enabled sources view showing apps currently monitored by LTM

Click any listed source to open a window where you can **disable** it for that app individually. Disabled sources stop contributing new events to LTM but previously captured context is retained.

  Disable sources like password managers, banking apps, or private browser profiles to keep sensitive activity out of LTM entirely.

***

## Clearing Stored LTM Data

Long-Term Memory data is stored locally by PiecesOS. You can remove it with granular control over time period, capture method, and application source.

Open the panel from the Pieces Desktop App: click your `User Profile` in the top left, hover over `Settings`, and select `Long-Term Memory`. In the *Stored Data* section, click `Clear Long-Term Memory Data...`.

    Open the `Time Periods` dropdown (default `All Time`) and choose what to clear: `Last hour`, `Today`, `This week`, or a custom range.

    Open the `Modalities` dropdown (default `All Modalities`) to clear by capture method: `Vision`, `Clipboard`, or `Audio`.

    Open the `App Sources` dropdown (default `All Sources`) to clear data from specific applications only.

    The summary line updates with your selection—for example, "Clearing all events for all sources during all time. This action cannot be undone." Click `Clear Data` to confirm, or `Cancel` to back out.

  Clearing Long-Term Memory data is permanent and cannot be undone. Review the summary line before you click `Clear Data`.

### Combining Filters

Combine the three filters for precise deletions:

| **Goal** | **Time Periods** | **Modalities** | **App Sources** |
| --- | --- | --- | --- |
| Clear all clipboard data from the last hour | `Last hour` | `Clipboard` | `All Sources` |
| Remove Slack vision captures from today | `Today` | `Vision` | Slack |
| Delete all audio from this week | `This week` | `Audio` | `All Sources` |
| Wipe everything from one app | `All Time` | `All Modalities` | (specific app) |

***

## Next Steps

  Configure app access control, system permissions, LTM Audio, and performance options from the full settings panel.

  Understand exactly what LTM stores on your device and how to manage or delete it.

  Everything else you can do from the Quick Menu—updates, MCP settings, memory optimization, and more.

---

## Manual Installation
Path: /products/core-dependencies/pieces-os/manual-installation

## When to Install Manually

PiecesOS installs automatically with the [Pieces Desktop App](/products/desktop/onboarding). Install it manually if you want to use [Pieces MCP integrations](/products/mcp) without the full Desktop experience—LTM, Conversational Search, and MCP features still work.

## System Requirements

| **Minimum** | **Recommended** | **Notes** |
| --- | --- | --- |
| Any modern CPU | Multi-core CPU | PiecesOS supports multithreading |
| 8 GB RAM | 16 GB+ RAM | 1 GB free (cloud mode) or 2 GB free (local mode) |
| 6 GB storage | 10 GB+ storage | ~2 GB for PiecesOS + at least 4 GB for LTM data |

### Minimum OS Versions

| **macOS** | **Windows** | **Linux** |
| --- | --- | --- |
| macOS 12.0 (Monterey)+ | Windows 10 (v.1809)+ | Ubuntu 22+ |

  Need help checking your specs or OS version? See [Troubleshooting](/products/core-dependencies/pieces-os/troubleshooting#checking-system-specifications).

***

## Windows

    *Windows 10 (1809) or higher*

    *Windows 10 (1809) or higher*

  **Installation path:** Avoid **OneDrive**, **iCloud Drive**, and other cloud-synced locations—use a local drive (the default path is recommended).

## macOS

    *macOS 12.0 (Monterey) or higher*

    *macOS 12.0 (Monterey) or higher*

### Installing via Homebrew

```bash
brew install --cask pieces-os
```

## Linux

  PiecesOS on Linux requires **Ubuntu 22+** and **snapd** enabled on your system.

    Press `ctrl+alt+t` to open your terminal.

    Run `sudo snap install pieces-os` and enter your password when prompted.

    Run `sudo snap connect pieces-os:process-control :process-control` to enable on-device machine learning and LLM functionality.

    Type `pieces-os` and press Enter.

***

## Uninstalling PiecesOS

    Open **Finder** > **Applications**. Find `PiecesOS`, right-click, and select `Move to Trash`.

    Open **Settings** > **Apps**, search for `Pieces`. Click the three dots next to PiecesOS and select `Uninstall`.

    Run `sudo snap remove pieces-os` in your terminal.

***

Having trouble? See [Troubleshooting PiecesOS](/products/core-dependencies/pieces-os/troubleshooting) or visit the [Support page](/products/support).

---

## Quick Menu
Path: /products/core-dependencies/pieces-os/quick-menu

## Overview

The **Quick Menu** is a lightweight popover for interacting with PiecesOS, located in your menu bar (macOS & Linux) or system tray (Windows). Use it to manage your account, toggle Long-Term Memory, configure ML processing, and check for updates—all without launching a separate application.

> PiecesOS Quick Menu on macOS (Windows shares the same UI)

## Quick Menu at a Glance

| **Section** | **What it does** |
| --------------------------------- | -------------------------------------------------------------------------- |
| *Account* | Log in or log out of your Pieces account |
| *Version* | Check for and install PiecesOS updates |
| *Long-Term Memory Engine* | Enable, pause (custom duration with **Paused until**), or disable LTM |
| *Long-Term Memory Access Control* | Choose which apps LTM captures data from |
| *MCP Servers* | View the SSE endpoint URL and MCP documentation links |
| *Settings* | Launch on login, enabled apps, ML processing, telemetry, memory optimization |
| *Resources* | Links to documentation, support, and community |

## Account

At the top of the Quick Menu, log in or out of your Pieces account. Logging in enables cloud-connected features like preference syncing and cloud model processing. Logging out keeps PiecesOS running locally with saved configurations.

## Checking for Updates

Below your account, the Quick Menu displays your current PiecesOS version. If an update is available, click `Update Available` to install it. Otherwise, a green check mark confirms you're current.

## Long-Term Memory

Toggle the [LTM-2.7 Engine](/products/core-dependencies/pieces-os/long-term-memory) on or off, pause capture for a custom duration (with a **Paused until** label), manage [Audio ingestion](/products/core-dependencies/pieces-os/long-term-memory#ltm-audio), and control which apps LTM captures data from via [Access Control](/products/core-dependencies/pieces-os/long-term-memory#long-term-memory-access-control).

For all pause options, the **Paused until** label, Audio setup, and per-app toggles, see the [LTM-2.7 Engine](/products/core-dependencies/pieces-os/long-term-memory) page.

## MCP Servers

Find the SSE endpoint URL for creating your own Pieces MCP instances, plus links to setup guides for [Cursor](/products/mcp/cursor), [VS Code](/products/mcp/github-copilot), and other IDEs.

## Settings

### Optimize Memory Usage

Adjusts memory allocation for PiecesOS to reduce resource consumption while maintaining performance.

### Launch on Login

Enable or disable automatic PiecesOS startup when your computer boots.

### Enabled Apps

View which applications have active Pieces MCP integrations.

### Telemetry Sharing

Enable or disable telemetry data collection per application or MCP integration.

## Resources

Quick access to documentation, support, and community links.

    * <a target="_blank" href="https://pieces.app/about">About</a>
    * <a target="_blank" href="/">Documentation</a>
    * <a target="_blank" href="/products/support">Support</a>

    * <a target="_blank" href="https://discord.com/invite/ubn8JFAXQ7">Discord</a>
    * <a target="_blank" href="https://x.com/getpieces">X</a>
    * <a target="_blank" href="https://www.linkedin.com/company/getpieces">LinkedIn</a>
    * <a target="_blank" href="https://github.com/pieces-app">GitHub</a>
    * <a target="_blank" href="https://www.youtube.com/@getpieces">YouTube</a>

## Linux

The Quick Menu on Linux has a reduced set of options:

* **Discover Integrations** — Opens the Pieces website with all [MCP integrations](/products/mcp)
* **About** — Launches the <a target="_blank" href="https://pieces.app/about">About</a> page
* **Documentation** — Opens the <a target="_blank" href="/">Pieces documentation</a>
* **Submit Feedback or Issues** — Opens a form for bug reports and feedback. You can also <a target="_blank" href="/products/support">visit our Support page</a>.
* **Optimize Memory Usage** — Reduce PiecesOS resource consumption
* **Quit** — Stops PiecesOS. Relaunch by typing `pieces-os` in your terminal.

---

## Troubleshooting PiecesOS
Path: /products/core-dependencies/pieces-os/troubleshooting

<on-device-storage />

## Installation Issues

### Cloud-Synced Folders

If you installed PiecesOS to **OneDrive**, **iCloud Drive**, or another synced folder, you may see install failures, crashes, or broken updates. **Uninstall**, then **reinstall** to the **default path** on a local drive. See [Manual Installation](/products/core-dependencies/pieces-os/manual-installation).

### Checking System Specifications

    Install the correct PiecesOS build for your chip (ARM vs Intel):

        Click the **Apple () icon** in the top-left corner and select **About This Mac**.

        Look for your processor type:

        * **Apple Silicon:** M-series (e.g., `Apple M3`)
        * **Intel:** Intel processor (e.g., `2.6 GHz Intel Core i7`)

    Check your device specs if you're experiencing issues, especially when running PiecesOS and the Long-Term Memory Engine:

        Press the `Windows` key, type `run`, and press Enter.

        Type `dxdiag` and press Enter.

        The **System** tab shows CPU and RAM; the **Display** tab shows GPU and VRAM.

    Verify your hardware meets requirements:

    * **CPU:** Run `lscpu` in your terminal
    * **GPU:** Run `lspci | grep -i vga` in your terminal

  Once you've determined your CPU architecture, [download the correct PiecesOS build.](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation)

## Updating PiecesOS

Many issues stem from running an outdated version. Check for updates from the [Quick Menu](/products/core-dependencies/pieces-os/quick-menu#checking-for-updates) or follow the platform-specific steps below.

        Look for the **Pieces icon** in your menu bar.

        Click the icon to open the Quick Menu.

        If an update is available, click to install it.

        Click the **Pieces icon** in your taskbar.

        The Quick Menu displays your current version and whether an update is available.

        Follow the on-screen prompt if an update is available.

      If installed via `.appinstaller`, quit the Pieces Desktop App before updating PiecesOS. If the update fails, quit both apps completely, then relaunch PiecesOS.

        Run `snap info pieces-os` in your terminal.

        Run `sudo snap refresh` to install the latest version.

## Checking OS Version

An outdated operating system can prevent PiecesOS from running. Minimum requirements:

| **macOS** | **Windows** | **Linux** |
| --- | --- | --- |
| macOS 12.0 (Monterey)+ | Windows 10 (v.1809)+ | Ubuntu 22+ |

    Click **Apple () icon** > **About This Mac** — the `macOS` line shows your version (e.g., `Sequoia 15.1.1`).

    Go to **Settings** > **Windows Update** and install any pending updates.

    Open **Settings** > **System** > **About** to find your Ubuntu version. Minimum: **Ubuntu 22.04**.

## Windows: Controlled Folder Access

If you've enabled Controlled Folder Access (CFA), PiecesOS may fail to launch if Windows blocks writes under AppData. Add the PiecesOS executable to your CFA allowlist, or disable CFA if it's not required.

## Finding Pieces Logs

Attach recent logs when opening a GitHub issue or contacting support. It helps diagnose problems in minutes.

See [Finding Your Logs](/products/core-dependencies/on-device-storage#finding-your-logs) for the full path table, or use these quick references:

| **Platform** | **PiecesOS logs** |
| --- | --- |
| *macOS* | `/Users/<username>/Library/com.pieces.os/production/Support/logs/` |
| *Windows* | `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support\` |
| *Linux* | `/home/<username>/.local/share/com.pieces.os/logs/` |

**Desktop App logs (Windows):** `C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\production\logs\`

**Desktop App logs (macOS):** `/Users/<username>/Library/com.pieces.pfd/production/logs/`

  Replace `<username>` with your OS account name. Zip the latest two or three log files and attach them to your <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a>.

***

If you've tried everything above and still have issues, <a target="_blank" href="/products/support">visit our support page</a> for additional resources.

---

## Pieces Desktop App
Path: /products/desktop

> Pieces Desktop App logos and branding

## Meet the Pieces Desktop App

The Pieces Desktop Application contains a suite of AI-powered tools designed to improve productivity by utilizing your workflow context and enabling you to make intelligent decisions on a day-to-day basis with Pieces Long-Term Memory.

Powered by [PiecesOS](/products/core-dependencies/pieces-os)—the heart and soul of Pieces—the Pieces Desktop app is the ultimate assistant for code, context, and creativity.

    Follow these instructions to download and install the Pieces Desktop Application for [macOS](/products/meet-pieces/macos-installation-guide), [Windows](/products/meet-pieces/windows-installation-guide), or [Linux](/products/meet-pieces/linux-installation-guide).

    Explore troubleshooting options, visit our [support page](/products/support), or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call</a> directly with our engineers.

<guides-overview-card />

## Overview

The Pieces Desktop app is designed to act as a hub for the Pieces Suite, powered by PiecesOS and the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine.

With the Pieces Desktop App, you have access to dedicated views for the context captured by Long-Term Memory through [Pieces Timeline](/products/desktop/timeline).

## Activity Timeline

A horizontal activity timeline at the bottom of the main view shows your workflow activity across the day (from 12am to 12am). Hover over any point to see a tooltip with more details—including the timestamp, memory count, and LTM status (e.g., *ON LTM-2.7*, *ON LTM Audio*) for that moment.

## Pieces Timeline

Keep track of your workflow so you can access stored context from yesterday, last week, or even last month—whenever you need it. The [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine ensures that nothing slips through the cracks.

[Pieces Timeline](/products/desktop/timeline) provides a sleek UI for interacting with saved data from up to 9 months ago in an easily digestible format, allowing you to view timeline events, workstream summaries, single-click summaries, and conversational searches.

> Pieces Timeline showing workflow events, summaries, and activity graph visualization

  Explore Pieces Timeline features including filtering events, managing event actions, and understanding timeline contents.

## Single-Click Summaries

Generate instant, contextual summaries from your workflow using preset summary types. With [Single-Click Summaries](/products/desktop/single-click-summaries), you can instantly generate contextual summaries with one click. Choose from summary types like *What's Top of Mind*, *Standup Update*, *Custom Summary*, *Day Recap*, *AI Habits*, and *Discover*—to quickly access insights about your workflow without typing a single prompt.

> Showing Pieces with Timeline open and Single-Click Summaries Generating

  Discover all available summary types and learn how to generate, view, and manage your summaries.

## Conversational Search

Use [Conversational Search](/products/desktop/conversational-search) as your main chat interface, where you'll find suggested chats to help you get started. Query your workflow memories and get AI-powered insights about your past activities.

> Conversational Search interface showing suggested chats and recent chats

  Learn how to use Conversational Search, integrate context, and chat with timeline events.

## Configuration

Customize your Pieces Desktop App through `Settings`: **Account** (profile, Personal Cloud, backup, telemetry), **Long-Term Memory**, **MCP**, **Connectors**, **Appearance**, and **Troubleshooting**. Choose models from the Conversational Search chat picker; see [Models in chat](/products/desktop/conversational-search/models) for model families and modes.

  Explore all configuration options to customize your Pieces Desktop experience.

## Model Context Protocol (MCP) Support

The Pieces suite, powered by the LTM-2.7 Engine through PiecesOS, also provides support for [Model Context Protocol (MCP) servers](/products/mcp) through Server-Sent Events (SSEs).

With the Pieces MCP, you can thread rich workflow context through to [Cursor](/products/mcp/cursor), [GitHub Copilot](/products/mcp/github-copilot), [Goose](/products/mcp/goose), and other IDEs and productivity tools, making Pieces a platform for using long-term context in other workflows outside of just the Pieces Desktop App.

  To integrate the Pieces MCP into one of the available integrations, copy the SSE endpoint URL and/or `.json` schema into your IDE of choice.

  You can find the MCP URL inside the *Model Context Protocol (MCP)* tab within *Settings*.

***

*Pieces MCP with Cursor*

> Pieces MCP integration with Cursor showing workflow context threading

***

If Pieces Desktop isn't what you're looking for, check out [PiecesOS](/products/core-dependencies/pieces-os) to learn about the core engine powering Pieces, or explore [MCP integrations](/products/mcp) to connect Pieces to your favorite IDE or editor.

---

## Actions & Keyboard Shortcuts
Path: /products/desktop/actions

## Overview

The Pieces Desktop App provides two primary ways to quickly perform *actions* and navigate around the app:

1. **Power Menu Actions**: A context-aware command palette that surfaces different options depending on the *view* you’re in (e.g., Pieces Drive or Conversational Search).

2. **Keyboard Shortcuts**: System or app-level keyboard shortcuts that let you instantly perform common tasks without opening any menus.

## Context-Aware Power Menu

When you open the **Power Menu**, the actions you see can change based on your current location in the app.

Here are some examples:

* **Pieces Drive Actions**: Creating, editing, and organizing saved materials, etc.

* **Conversational Search Actions**: Generative AI-related features like analyzing or refactoring code, starting new chats, etc.

* **Global/App Actions**: Account management, backup and restore, settings, etc.

Because these commands depend on the active *View*, you’ll *only see and be able to search for* relevant options in that moment.

### When to Use the Power Menu

There are plenty of use cases for using the **Power Menu**—here are a couple:

* **Discoverability**: If you’re unsure which action you need or want to browse available commands, simply open the menu and type a keyword.

* **Context-Specific Actions**: The Power Menu dynamically shows commands that make sense in your current view (e.g., Pieces Drive vs. Copilot).

## Keyboard Shortcuts

For a detailed list of all possible shortcuts and their descriptions, visit the [Keyboard Shortcuts](/products/desktop/actions/keyboard-shortcuts) page for multi-platform shortcut tables and action titles.

### When to Use Shortcuts

Shortcuts are a time-tested and often-preferred method of accomplishing individual tasks or processes for creatives and knowledge-workers alike.

Here are some examples:

* **Speed & Muscle Memory**: If you already know a shortcut (like ⌘+S to save), it’s the fastest way to perform routine tasks.

* **Consistent, Regardless of View**: Many shortcuts (e.g., toggling edit mode or saving a snippet) work across multiple views, even though some may be view-specific.

## Actions vs Shortcuts

The Pieces Desktop App provides the best of both worlds—a wealth of actions accessible from the **Power Menu** and plenty of keyboard shortcuts to boot.

  Try to familiarize yourself with both **Power Menu** actions and **Keyboard Shortcuts** to see which better fit your workflow.

You might want to try getting familiar with both, and here are two reasons why:

* **Invocation**: Shortcuts are **pressed**, while Power Menu commands are **typed** and then selected.

- **Scope**: Shortcuts typically work globally or in a specific view, while Power Menu commands are always **context-aware** and only appear if they’re relevant to the current workspace.

---

## Keyboard Shortcuts
Path: /products/desktop/actions/keyboard-shortcuts

## Overview

You can browse the list of keyboard shortcuts below as a reference guide, or you can open the **Keyboard Shortcuts** modal by navigating to **Settings,** and scrolling to **Support** or use `⌘+;` (macOS) or `ctrl+;` (Windows/Linux).

## Use a Piece

These shortcuts let you quickly interact with saved material in your workspace, making it easy to download, duplicate, or copy it with context.

***

| **Command**         | **Windows/Linux** | **macOS**    |
| ------------------- | ----------------- | ------------ |
| *Download a Piece*  | `shift+ctrl+d`    | `shift+⌘+d`  |
| *Duplicate a Piece* | `ctrl+d`          | `⌘+d`        |
| *Copy with Context* | `ctrl+alt+c`      | `⌘+option+c` |

***

## Add a Piece

Use these shortcuts to seamlessly add new materials into Pieces—whether you're importing files, creating new snippets, or adding collections.

***

| **Command**                           | **Windows/Linux**             | **macOS**   |
| ------------------------------------- | ----------------------------- | ----------- |
| *Add Code file to Pieces*             | `ctrl+v`                      | `⌘+v`       |
| *Add Collections to Pieces*           | `ctrl+shift+c`                | `⌘+shift+c` |
| *Add Code Snippet to Pieces from IDE* | `ctrl+c `*(in IDE),* `ctrl+v` | `⌘+c,⌘+v`   |
| *Create New Material from Scratch*    | `ctrl+n`                      | `⌘+n`       |

***

## Manage a Saved Material

These keyboard shortcuts help you organize your content by renaming, editing, reclassifying, or even deleting a piece as needed.

***

| **Command**                       | **Windows/Linux**           | **macOS**             |
| --------------------------------- | --------------------------- | --------------------- |
| *Rename*                          | `ctrl+r`                    | `⌘+r`                 |
| *Open quick menu*                 | `ctrl+o`                    | `⌘+o`                 |
| *Reclassify*                      | `ctrl+y`                    | `⌘+y`                 |
| *Delete*                          | `del`                       | `del`                 |
| *Edit piece description*          | `shift+ctrl+n/shift+ctrl+p` | `shift+⌘+n/shift+⌘+p` |
| *Add related links*               | `ctrl+k (if shown)`         | `⌘+k (if shown)`      |
| *Add tags*                        | `ctrl+t (if shown)`         | `⌘+t (if shown)`      |
| *Toggle information view*         | `ctrl+i (if shown)`         | `⌘+i (if shown)`      |
| *Highlight sensitive information* | `ctrl+! (if shown)`         | `⌘+! (if shown)`      |
| *Open action menu*                | `ctrl+enter`                | `⌘+enter`             |

***

## Editing a Piece

Quickly focus on the editor, save your changes, or exit editing mode with these shortcuts, so you stay in control of your work.

***

| **Command**      | **Windows/Linux** | **macOS** |
| ---------------- | ----------------- | --------- |
| *Edit Mode*      | `ctrl+e`          | `⌘+e`     |
| *Escape Editing* | `esc`             | `esc`     |
| *Save Edits*     | `ctrl+s`          | `⌘+s`     |

***

## Share with People / Support

Access options for generating shareable links or reaching out for support directly within the app using these commands.

***

| **Command**               | **Windows/Linux** | **macOS** |
| ------------------------- | ----------------- | --------- |
| *Generate Shareable Link* | `ctrl+l`          | `⌘+l`     |
| *Submit Feedback/Issues*  | `shift+?`         | `shift+?` |

***

## Navigating Pieces

These shortcuts make it simple to jump between different views and features, keeping your workflow smooth and efficient.

***

| **Command**                          | **Windows/Linux** | **macOS**   |
| ------------------------------------ | ----------------- | ----------- |
| *Focus search*                       | `ctrl+f or /`     | `⌘+f or /`  |
| *Jump to first/last piece*           | `ctrl+→/ctrl+←`   | `⌘+→/⌘+←`   |
| *Toggle between image and code view* | `t`               | `t`         |
| *View next or previous piece*        | `→ or ←`          | `→ or ←`    |

***

## Zoom & Updates

Adjust the UI scale and check for updates quickly with these handy shortcuts, ensuring a comfortable and current user experience.

***

| **Command**                     | **Windows/Linux** | **macOS**   |
| ------------------------------- | ----------------- | ----------- |
| *Zoom in*                       | `ctrl++`          | `⌘++`       |
| *Zoom out*                      | `ctrl+-`          | `⌘+-`       |
| *Check for desktop app updates* | `shift+u`         | `shift+⌘+u` |
| *Release notes*                 | `shift+w`         | `shift+⌘+w` |
| *View keyboard shortcuts*       | `ctrl+;`          | `⌘+;`       |

***

## Configuring Pieces

Use these shortcuts to open settings and toggle themes, allowing you to personalize your Pieces environment with ease.

***

| **Command**     | **Windows/Linux** | **macOS** |
| --------------- | ----------------- | --------- |
| *Open Settings* | `ctrl+,`          | `⌘+,`     |
| *Change Theme*  | `ctrl+t`          | `⌘+t`     |

***

---

## Power Menu Actions
Path: /products/desktop/actions/power-menu

## Overview

The **Power Menu** in Pieces is a dynamic command palette. It shows certain views as 'suggested' based on the task you're working on or sorts them by how often you use them.

### Quick Navigation

Jump between key views by typing a few letters in the Power Menu search:

* **Conversational Search** — Type `copilot` or `conversational` and select `Go to Conversational Search` to start chatting with your memories.
* **Timeline** — Type `workstream` or `timeline` and select `Go to Timeline` to browse your workflow summaries and activities.

The Power Menu learns from your usage—frequently used commands appear higher, so common jumps get faster over time.

## Dynamic View-Based Actions

The **Power Menu** in Pieces is a dynamic command palette.

When you press the Power Menu hotkey or open it from the app interface, you’ll see different actions *depending on which view or section of the app you’re currently in*.

For example:

* **Pieces Drive View:** You’ll see commands related to creating, editing, or managing snippets (e.g., “Create New Material,” “Optimize Snippet,” etc.).

* **Conversational Search View:** You'll see commands focused on AI-driven interactions (e.g., "Ask Conversational Search," "Analyze this Snippet," etc.).

* **Application & Cloud / Global Context:** Some commands (e.g., “Check for Updates,” “Manage Accounts & Cloud Integrations,” “Go to Settings”) appear in multiple views or from a global context.

  If you search for a command in the Power Menu and you’re *not* in the view where that command is valid, **it will not appear** in your search results.

### Conversational Search

You can find lots of saved material and generative AI-focused actions when accessing the Power Menu from Conversational Search view.

***

| **Command**                                 | **Description**                                                                 |
| ------------------------------------------- | ------------------------------------------------------------------------------- |
| *Manage General Conversational Search Settings*           | Takes you to Conversational Search settings page.                                  |
| *Manage Conversational Search LLM Runtime Configuration*  | Opens a modal for changing the AI model.                                       |
| *Enter Focused Conversational Search*                     | Collapses the sidebar and enters Focus Mode.                                    |
| *Launch Conversational Search in Browser*                 | Launches an instance of the Pieces Desktop App UI in your browser.              |
| *New Conversational Search Conversation with LTM Context* | Starts a new Conversational Search with LTM enabled.                              |
| *New General Conversational Search Conversation*          | Starts a new Conversational Search without additional prompting pipelines.        |
| *New Contextual Conversational Search Conversation*       | Starts a new Conversational Search with context.                                  |
| *New Conversational Search Conversation*                  | Starts a new Conversational Search that defaults to the set LTM behavior.         |
| *New Generative Conversational Search Conversation*       | Starts a new Conversational Search with a code-generating prompt pipeline preset. |
| *Delete All Conversational Search Conversations*                  | Deletes all Conversational Search conversations.                                               |

***

### Pieces Drive

These actions cover everything from creating and editing your code materials to duplicating and optimizing them, ensuring your content is always well-managed.

***

| **Command**                                     | **Description**                                                    |
| ----------------------------------------------- | ------------------------------------------------------------------ |
| *Create New Material*                           | Initiate the creation of a new material (snippet or resource).     |
| *Create New Material from Scratch*              | Build a fresh material without importing existing files.           |
| *Create New Material from File(s)*              | Generate a material by importing local files.                      |
| *Create New Material from Description*          | Produce a material based on user-provided descriptive text.        |
| *View in Gallery*                               | Open the selected material in a gallery-style view.                |
| *Edit Selected Material*                        | Modify the currently highlighted material.                         |
| *Open Quick Menu*                               | Launch a quick-access menu for the selected material.              |
| *Templatize Selected Material*                  | Convert the chosen material into a reusable template.              |
| *Optimize Selected Material for Readability*    | Improve clarity and structure of the material.                     |
| *Optimize Selected Material for Speed*          | Enhance the performance-focused aspects of the material.           |
| *Convert Selected Material to New Language*     | Translate or adapt the material into another programming language. |
| *Copy Selected Material*                        | Duplicate the material content to the clipboard.                   |
| *Generate Shareable Link*                       | Create a link that can be shared externally.                       |
| *Manage Annotations for Selected Material*      | Add or edit annotations for context and clarity.                   |
| *Manage Related Websites for Selected Material* | Associate relevant URLs or references.                             |
| *Manage Tags for Selected Material*             | Assign or remove tags to categorize the material.                  |
| *Manage Sensitives for Selected Material*       | Mark or handle sensitive data within the material.                 |
| *Manage Anchors for Selected Material*          | Attach anchor points for reference or navigation.                  |
| *Manage Related People for Selected Material*   | Link collaborators or owners to the material.                      |
| *Discover Related Materials*                    | Find other materials that share context or tags.                   |
| *Duplicate Selected Material*                   | Create a direct copy of the current material.                      |
| *Start Copilot Chat about Selected Material*    | Launch an AI-powered conversation focused on this material.        |
| *Rename Selected Material*                      | Change the title or identifier of the material.                    |
| *Delete Selected Material*                      | Remove the chosen material from your collection.                   |
| *View Selected Material Context*                | Display contextual information or references.                      |
| *Copy Context for Selected Material*            | Copy contextual details (metadata, tags, etc.) to the clipboard.   |

***

### Application & Cloud

Manage your account, cloud integrations, backups, and updates with these commands to keep the app running smoothly and securely.

***

| **Command**                            | **Description**                                                          |
| -------------------------------------- | ------------------------------------------------------------------------ |
| *Backup & Restore Data*                | Manage or recover saved backups of your Pieces data.                     |
| *Toggle Light Mode*                    | Switch the user interface between light and dark themes.                 |
| *Manage Accounts & Cloud Integrations* | Connect or configure your Pieces Cloud and linked accounts.              |
| *Manage Early Access Program*          | Enroll in or manage beta features of Pieces.              |
| *Check for Updates*                    | Check for and install updates to both the Desktop App and PiecesOS.      |
| *Manage In-App Notifications*          | Configure or silence various in-app alerts and messages.                 |
| *Manage Pieces Drive Action Toolbar*   | Customize toolbar actions for Pieces Drive integrations.                 |
| *Turn Long-Term Memory Engine Off*     | Disable the memory engine that stores historical snippet context.        |
| *Pause Long-Term Memory Engine*        | Temporarily stop the memory engine from updating.                        |
| *View Auto-Saved Materials*            | Access automatically saved drafts or snippets.                           |
| *View All Plugins*                     | See a complete list of available plugins for Pieces.                     |
| *Clear Long-Term Memory Engine Data*   | Erase stored context or historical data from the memory engine.          |

***

### Navigation

These commands help you traverse the Pieces interface, letting you access different panels, search features, and integrations with ease.

***

| **Command**                      | **Description**                                                       |
| -------------------------------- | --------------------------------------------------------------------- |
| *Go to Timeline*                  | Open Timeline to view workflow summaries and captured context. |
| *Go to Updates & Upcoming*       | Check upcoming features, announcements, or patch notes.               |
| *Go to Global Search*            | Access the global search interface for snippets and materials.        |
| *Go to Settings*                 | Open the main settings panel for Pieces.                              |
| *Go Back*                        | Return to the previous screen or menu.                                |
| *Go to Conversational Search*           | Launch or navigate to the AI-assisted Conversational Search interface.              |
| *Go Home*                        | Navigate to the main dashboard or home screen.                        |
| *Go to VS Code Plugin*           | Redirect to the Visual Studio Code integration.                       |
| *Go to Visual Studio Plugin*     | Redirect to the Visual Studio integration.                            |
| *Go to JetBrains Plugin*         | Open the JetBrains family of IDE plugins.                             |
| *Go to Chromium Extension*       | Jump to the Google Chrome browser extension.                          |
| *Go to Microsoft Edge Extension* | Access the Edge browser extension for Pieces.                         |
| *Go to Brave Extension*          | Navigate to the Brave browser extension.                              |
| *Go to Opera Extension*          | Navigate to the Opera browser extension.                              |
| *Go to Firefox Extension*        | Navigate to the Firefox browser extension.                            |
| *Go to Obsidian Plugin*          | Explore the Obsidian plugin for Pieces integration.                   |
| *Go to JupyterLab Plugin*        | Access the JupyterLab plugin for code snippets.                       |
| *Go to Microsoft Teams Add-On*   | Jump to the Teams add-on for sharing snippets.                        |
| *Go to Pieces Open Source*       | Browse the open-source repos related to Pieces.                       |
| *Go to Pieces Discord*           | Join the Pieces Discord community for support or discussion.          |
| *Go to Documentation*            | Open the official Pieces documentation.                               |
| *Go to Support*                  | Access the Pieces support resources.                                  |
| *Go to Feedback*                 | Navigate to feedback channels for product improvements.               |
| *Report Issue or Bug*            | Submit a bug report for the Pieces team to address.                   |
| *Share Feature Idea or Request*  | Propose a new feature or enhancement.                                 |

***

---

## Configuration
Path: /products/desktop/configuration

## Accessing Settings

Open Settings from the home view to adjust account and cloud behaviors, check your application versions, change views and layouts, and more.

    Click your `User Profile` in the top left of the home view.

    Hover over `Settings` in the dropdown menu that appears.

    You can either select one of the quick options (Account, Long-Term Memory, MCP, Connectors, Appearance, Troubleshooting) to jump directly to that category, or select `All` at the top of the quick options to open the full Settings view with all categories. You can also select `Log Out` at the bottom of the menu to sign out of your account.

    The Settings view is organized into a two-column layout:

    * **Left sidebar**: Lists all settings categories
    * **Right content area**: Displays the settings for the selected category

    Scroll through the sidebar to browse categories or scroll through the content area to see all options within a category.

    Clicking a category in the left sidebar filters the right content area to show only that category's settings. Click `All` in the sidebar to see all settings at once.

## Account

Manage your Pieces account, linked third-party services, profile information, personal cloud synchronization, subscriptions, and privacy settings. This ensures your account stays secure and synced with the services you use to authenticate.

> Account settings showing profile information, linked accounts, organizations, subscriptions, personal cloud, and privacy settings

  Learn how to manage your account, view linked services, configure personal cloud synchronization, manage subscriptions, and configure privacy settings.

### Organizations & Teams

Create and manage organizations and teams to collaborate with others, share resources, and maintain consistent settings across your team in Pieces.

> Account settings page showing Organizations & Teams section with organization list and management options

  Learn how to create organizations, invite team members, manage team settings, and collaborate effectively with your team.

## Long-Term Memory

Manage long-term memory preferences and data. Configure the Long-Term Memory Engine, control which applications Pieces can access, manage system permissions, optimize performance, and clear stored data.

> Long-Term Memory settings showing Memory Formation, Performance, and Stored Data sections

  Configure the Long-Term Memory Engine, manage app access control, system permissions, and optimize performance.

## Connectors

Link external services such as Google Calendar so Pieces can read calendar context and take actions on your behalf. Manage connections from the Connectors tab in Settings.

> Connectors settings showing connected and available integrations

  Connect Google Calendar, authorize services, and learn how calendar context appears in summaries.

## Model Context Protocol (MCP)

Access server URLs and documentation for integrating Pieces Long-Term Memory with Cursor, GitHub Copilot, and other tools that support the Model Context Protocol. The MCP server enables connectivity between Large Language Models (LLMs) and your personal context stored by the Long-Term Memory Engine.

> MCP settings showing server URLs and documentation options

  Learn how to configure the Pieces MCP and integrate it with Cursor, GitHub Copilot, Goose, and other tools.

## Appearance

Customize the visual appearance of the Pieces Desktop App, including theme mode, accent colors, font settings, and visual density. Adjust these settings to match your preferences and create a comfortable work environment.

> Appearance settings showing Theming, Fonts, and Spacing sections

  Switch between themes, customize accent colors, adjust font size and weight, and configure visual density.

## Troubleshooting

Get help, troubleshoot issues, view app information, and contact support. Access support resources, documentation links, version details, and feedback channels to resolve issues and get the most out of Pieces.

> Troubleshooting settings showing Online Resources, Get In Touch, PiecesOS Information, and Desktop App Information sections

  Access support resources, view version information, check for updates, and contact the Pieces team.

***

If Configuration isn't what you're looking for, check out [Conversational Search](/products/desktop/conversational-search) to learn about asking questions about your workflow, or explore the [Timeline](/products/desktop/timeline) to see how Pieces [creates](/products/desktop/single-click-summaries) and [stores memories](/products/desktop/timeline/timeline-events).

---

## Account
Path: /products/desktop/configuration/account

## Account Settings

Manage your Pieces account settings, authentication, linked accounts, organizations, subscriptions, personal cloud synchronization, and privacy settings. Your account information is automatically synced from the third-party service you used to sign in, ensuring your profile stays up to date.

To access Account settings, click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

> Account settings showing profile information, linked accounts, organizations, and subscriptions

## Account Information

View your *account details* and manage your session. Your name and email are pulled from the third-party service you used to authenticate, ensuring your profile information stays synchronized.

### Viewing Your Account Information

Your account information displays your name and email address at the top of the Account settings page. 

Clicking on your name opens the *Accounts & Cloud Integrations* modal, where you can manage linked accounts and account settings.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    At the top of the Account settings page, you'll see your name and email address. This information is automatically synced from the service you used to sign in (GitHub, Google, or Microsoft).

    Click on your `Name` in the *Account* section to open the *Accounts & Cloud Integrations* modal, which provides detailed account management options.

### Logging Out

Sign out of your Pieces account to end your current session. You can log back in using any of your linked accounts. You can sign out from multiple locations.

#### Signing Out from Settings Hover Menu

    Click your `User Profile` in the top left of the home view.

    In the dropdown menu that appears, click `Log Out` to sign out of your account.

    You'll be signed out and returned to the login screen. You can sign back in using any of your linked accounts.

#### Signing Out from Account Settings

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Click the `logout icon` (arrow pointing out of a square) next to your name and email to sign out of your account.

    You'll be signed out and returned to the login screen. You can sign back in using any of your linked accounts.

#### Signing Out from Accounts & Cloud Integrations Modal

You can also sign out from the *Accounts & Cloud Integrations* modal. Open the modal by clicking your `Name` in the *Account* section, then scroll down to the *Danger Zone* section and click `Sign Out` to sign out of your account.

You will no longer have the ability to generate shareable links or share via GitHub Gist after signing out.

## Linked Accounts

Link accounts with the same email address to enable unique features from each provider, such as importing and exporting GitHub Gists. Your profile information (name, email, avatar) is automatically pulled from these linked accounts, making it easy to sign in and keep your information up to date.

### Understanding Linked Accounts

Accounts are linked when you sign in using a third-party service (GitHub, Google, or Microsoft). You can link multiple accounts that use the same email address to access features from each provider. Accounts cannot be manually edited—this ensures your account stays secure and synced with the services you use to authenticate.

### Viewing Linked Accounts

See which third-party services are connected to your Pieces account. You can view linked accounts either from the Account settings page.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Linked Accounts* section, which displays icons for GitHub, Google, and Microsoft. Connected services will have a green dot on them. Services that aren't linked will not.

    For detailed account management, click on your `Name` in the *Account* section to open the *Accounts & Cloud Integrations* modal. In the *Connect Individual Accounts* section, you'll see:
    * Connected services show "Connected to [Service]" with a green checkmark
    * Unconnected services show "Connect to [Service]" without a checkmark

### Opening Accounts & Cloud Integrations Modal

Access the *Accounts & Cloud Integrations* modal to manage your linked accounts, view connection status, and access account features.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Click on your `Name` in the *Account* section at the top of the page to open the *Accounts & Cloud Integrations* modal.

    The modal displays:
    * **Introduction**: Information about connecting accounts to enable features like importing/exporting GitHub Gists and generating shareable links
    * **Important Note**: Only accounts with a matching primary email address will be linked
    * **Connect Individual Accounts**: List of available services (Microsoft, GitHub, Google) with connection status
    * **Support**: Links to Discord support and feedback resources
    * *Danger Zone*: Option to sign out of your account

### Linking an Account

Connect a new third-party service to your Pieces account to access provider-specific features like importing and exporting GitHub Gists.

    Click your `User Profile` in the top left, hover over `Settings`, select `Account`, then click on your `Name` to open the *Accounts & Cloud Integrations* modal.

    In the *Connect Individual Accounts* section, find the service you want to link (Microsoft, GitHub, or Google).

    Click on the service name (e.g., "Connect to Microsoft") to start the connection process.

    Make sure the account uses the same email address as your Pieces account. Only accounts with a matching primary email address will be linked. Otherwise, a new, separate account will be created.

    Follow the authentication flow for the selected service. Once authenticated, the account will be linked and you'll see a green checkmark next to the service name.

### Disconnecting an Account

Remove a linked account from your Pieces account. You can disconnect accounts from the *Accounts & Cloud Integrations* modal.

    Click your `User Profile` in the top left, hover over `Settings`, select `Account`, then click on your `Name` to open the *Accounts & Cloud Integrations* modal.

    In the *Connect Individual Accounts* section, find the service you want to disconnect. Connected services show "Connected to [Service]" with a green checkmark.

    Click on the connected service to disconnect it. Confirm the disconnection when prompted.

    The service will no longer show a green checkmark, indicating it has been disconnected. You'll lose access to provider-specific features for that service.

## Organizations & Teams

View and manage your organization memberships from the Account settings page. The *Organizations & Teams* section displays all organizations you belong to, along with their subscription types and management options.

> Account settings page showing Organizations & Teams section with organization list and management options

### Viewing Your Organizations

See all organizations you're a member of, including their subscription plans.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Organizations & Teams* section to view your organization memberships.

    Each organization displays:
    * **Organization name**: The name of the organization
    * **Organization label**: A blue badge indicating it's an organization
    * **Subscription type**: The plan type (e.g., Enterprise Seat Yearly, Enterprise Seat Quarterly, Enterprise Seat Monthly)

### Managing Organizations

Access organization management features from the Account settings page.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Organizations & Teams* section.

    Click the `Manage` button (external link icon) to open your account page in the browser, where you can view and manage your organizations, invite members, configure settings, and access billing information.

### Refreshing Organizations

Manually refresh your organization list if it doesn't appear up to date.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Organizations & Teams* section.

    Click the `Refresh` button (circular arrow icon) to manually sync your organization list with the latest information.

### Getting Help with Organizations

Access troubleshooting resources for organization-related issues.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Organizations & Teams* section.

    Click the `Get Help` button (question mark icon) to open the [Organizations & Teams troubleshooting page](/products/organizations-and-teams/troubleshooting), which provides solutions for common organization access issues and authentication problems.

  Learn how to create organizations, invite team members, manage team settings, and collaborate effectively with your team.

## Personal Subscriptions

Manage your Pieces Pro subscription, view your plan details, update payment methods, and access billing information. Your subscription status, renewal dates, and payment history are all accessible from this section.

  LTM capture and memory search via Conversational Search require Pieces Pro, though your existing memories remain accessible on your device. See [Managing Your Account](/products/meet-pieces/managing-your-account) for plan details.

### Viewing Your Subscriptions

See all of your active and canceled subscriptions, including plan types, status, and renewal information.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Subscription(s)* section to view all of your subscription plans.

    Each subscription shows:
    * **Plan name**: The type of subscription (e.g., Pieces Pro Plan Yearly, Pieces Pro Plan Monthly)
    * **Status**: Active (green badge) or Canceled (red badge)
    * **Renewal information**: Auto-renewal date for active plans or cancellation date for canceled plans

### Managing Your Subscription

[Access the billing dashboard](/products/paid-plans/manage-subscription) to update payment methods, view invoices, and manage your subscription settings.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Subscription(s)* section.

    Click the `Manage` button (document with checkmark icon) next to your subscription to open the [billing dashboard](/products/paid-plans/manage-subscription).

    In the [billing dashboard](/products/paid-plans/manage-subscription), you can:
    * Update your payment method
    * View and download invoices
    * Change your subscription plan
    * Cancel your subscription

### Refreshing Subscription Status

Plan changes sync to PiecesOS within moments. If your subscription status doesn't update within a few minutes, sign out and sign back in. If it still doesn't refresh, visit the [Support page](/products/support).

You can also refresh it manually:

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Subscription(s)* section.

    Click the `Refresh` button (circular arrow icon) to manually sync your subscription status with the latest information from the billing system.

### Getting Help with Subscriptions

Access support resources for subscription and billing questions.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Subscription(s)* section.

    Click the `Get Help` button (question mark icon) to access support resources for subscription and billing questions, including payment issues, plan changes, and account management.

## Personal Cloud

Configure cloud synchronization, backups, and your personal domain. This keeps your materials and workflow history available wherever you work. Pieces can run entirely offline, but connecting to Pieces Cloud enables real-time syncing and access across devices.

### Cloud Status

View your cloud connection status and when it was last updated. The status indicator shows whether your Personal Cloud is connected or disconnected, along with a timestamp of the last update.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Cloud* section to view your connection status.

    You'll see your connection status:
    * **Connected**: Shows "Status: Connected" with a green dot, along with "Last updated [time]" 
    * **Disconnected**: Shows "Status: Disconnected" with a gray dot

### Connecting to Personal Cloud

Connect to your Personal Cloud to enable cloud synchronization, backups, and sharing features. When you connect, Pieces will automatically sync if you already have a cloud account, or create a new cloud for you.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Cloud* section.

    When your cloud is disconnected, click the `Cloud Icon` to the right of the status indicator to connect to your Personal Cloud.

    Pieces will automatically sync your data if you already have a cloud account, or create a new cloud account for you. Once connected, your status will update to "Connected" and you'll have access to all cloud features.

  Any material saved in *Pieces Drive* or marked as a snippet is backed up. There are *no storage limits* on cloud-synced data.

### Disconnecting Personal Cloud

Disconnect from your Personal Cloud at any time to disable cloud synchronization and features. You can reconnect later if needed.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Cloud* section.

    When your cloud is connected, click the `Disconnect Cloud Icon` (cloud with diagonal line) to disconnect from your Personal Cloud.

    Confirm the disconnection when prompted. Once disconnected, cloud features will be disabled and your status will show as "Disconnected".

Before disconnecting, keep in mind that several features require connectivity to your Personal Cloud:

* **Sharing (beta)**: The ability to generate and share links for saved materials from Pieces Drive
* **Cloud ML**: Cloud-based enrichment of metadata for saved materials
* **Cloud Backup**: The automatic synchronization of your data to Pieces Cloud
* **Cloud Integrations**: Your Pieces Cloud which controls your personal subdomain and other integrations

### Personal Domain

Customize your personal subdomain to create a unique URL for sharing your materials. Your personal domain is used when generating shareable links for your saved materials.

When you're connected to Pieces Cloud, you're assigned a personal subdomain (e.g., `yourname.pieces.cloud`) for sharing snippets. This subdomain isn't publicly browsable like a profile page—instead, it's prepended to any URLs you generate when sharing saved materials.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Cloud* section.

    Find the *Personal Cloud Domain* section, which shows your current domain status and the text input field.

    In the text input field, enter the custom text you want to use before `.pieces.cloud`. For example, entering "nolanworksat" will create `nolanworksat.pieces.cloud`.

    Your domain will update automatically. The section will show "Your domain [your_custom_url].pieces.cloud is running" when active.

### Backup & Restore Data

Create manual backups of your data for long-term storage and recovery. These backups are stored in your personal Pieces cloud and can be restored or deleted at any time.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Personal Cloud* section.

    In the *Backup & Restore Data* section, click the `Restore Icon` (Circular Arrow Icon) to open the *Backup & Restore Data* modal.

#### Creating a Backup

Create a manual backup snapshot of your data. Backups are stored in your personal Pieces cloud and include all your saved materials, settings, and preferences.

    Click your `User Profile` in the top left, hover over `Settings`, select `Account`, then scroll to the *Personal Cloud* section and click the `Restore Icon` in the *Backup & Restore Data* section.

    In the modal, find the *Create Backup* section, which shows "Backups will be stored in your personal Pieces cloud".

    Click the `Cloud Icon with Upward Arrow` to create a new backup. The backup will be created and uploaded to your personal Pieces cloud.

#### Backup Contents

A Pieces backup contains the following data:

| **Data Type**           | **Summary**                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| *Snippets*              | All saved code snippets and related metadata.                     |
| *Pieces Drive Files*    | Any files stored in Pieces Drive.                                 |
| *User Preferences*      | Theme, UI settings, and personalization options.                  |
| *Conversational Search Data* | Recent chat history and AI context for Conversational Search. |
| *Search & Tagging Data* | User-defined tags and previous searches for quick retrieval.      |
| *Account Connections*   | Linked GitHub, Google, or Microsoft accounts (without passwords). |

  Backups *do not include* Pieces Cloud data that is already synced or external files which are not explicitly stored in Pieces Drive.

#### Viewing Your Backups

See all of your available backups with details about when they were created, their size, the device they were created on, and the PiecesOS version at the time of backup.

    Click your `User Profile` in the top left, hover over `Settings`, select `Account`, then scroll to the *Personal Cloud* section and click the `Restore Icon` in the *Backup & Restore Data* section.

    Scroll down to the *Backups* section, which shows the total number of backups and lists each backup with:
    * **Date and time**: When the backup was created (e.g., "Mon, Dec 8, 2025 9:41 AM")
    * **Size**: The backup file size (e.g., "342.85 MB")
    * **Device**: The device name where the backup was created (e.g., "Judsons MacBook Air")
    * **OS Version**: The PiecesOS version at the time of backup (e.g., "PiecesOS v12.3.3")

#### Restoring a Backup

Restore a previous backup to recover all saved materials, settings, and preferences. This will return Pieces Drive and the Pieces Desktop App to the state captured in that backup.

    Click your `User Profile` in the top left, hover over `Settings`, select `Account`, then scroll to the *Personal Cloud* section and click the `Restore Icon` in the *Backup & Restore Data* section.

    In the *Backups* section, find the backup you want to restore from the list.

    Click the `Restore Icon` (Refresh/Circular Arrow Icon) on the right side of the backup entry to restore that backup.

    Confirm the restoration when prompted. All saved materials, settings, and preferences will be restored to the state captured in that backup.

#### Deleting a Backup

Remove old backups that you no longer need. Deleted backups cannot be restored—this is a permanent deletion.

    Click your `User Profile` in the top left, hover over `Settings`, select `Account`, then scroll to the *Personal Cloud* section and click the `Restore Icon` in the *Backup & Restore Data* section.

    In the *Backups* section, find the backup you want to delete from the list.

    Click the `Trash Icon` on the right side of the backup entry to delete that backup.

    Confirm the deletion when prompted. The backup will be permanently removed and cannot be restored.

### Cloud Syncing

Cloud syncing is optional—you can use Pieces entirely offline if you prefer. Once connected, syncing happens automatically in real time, keeping your data synchronized across all your devices. The only way to disable syncing is by disconnecting from Pieces Cloud.

When connected, your data is automatically synchronized in real time across all devices where you're signed in. This includes snippets, Pieces Drive files, settings, and workflow history.

## Privacy

Configure telemetry and diagnostics settings to help improve Pieces. Share anonymous telemetry and crash data to help the Pieces team build better tools across macOS, Linux, and Windows.

### Telemetry & Diagnostics

Enable or disable anonymous telemetry and crash data collection. Building next-generation tools across macOS, Linux, and Windows is hard! Share anonymous telemetry and crash data to help improve Pieces.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Account`.

    Scroll down to the *Privacy* section.

    Find the "Telemetry & Diagnostics" option with a checkbox.

    Check or uncheck the `Checkbox` next to "Telemetry & Diagnostics" to enable or disable anonymous telemetry and crash data collection.

  Participating in telemetry helps Pieces evolve more effectively, but you can opt out for greater privacy. Read more about compliance, privacy, and security [here](/products/privacy-security-your-data), and as always feel free to reach out to our team on [Discord](https://discord.gg/getpieces), [GitHub](https://github.com/pieces-app), or at support@pieces.app.

***

## Next Steps

Now that you understand how to manage your account, learn about [Long-Term Memory](/products/desktop/configuration/long-term-memory) to configure memory preferences, or explore [Choose a Model](/products/desktop/conversational-search/models) to switch between model families and modes.

---

## Appearance
Path: /products/desktop/configuration/appearance

## Appearance Settings

Customize the visual appearance of the Pieces Desktop App, including theme mode, accent colors, font size, font weight, and visual density. Adjust these settings to match your preferences and create a comfortable work environment.

To access Appearance settings, click your `User Profile` in the top left, then hover over `Settings` and select `Appearance`.

> Appearance settings showing Theming, Fonts, and Spacing sections

  Theme changes are automatically saved when adjusted, and settings are stored locally, not synced with Pieces Cloud.

## Theming

Customize the overall theme and accent color of the Pieces interface. Choose between dark, light, or system themes, and select an accent color that matches your preferences.

### Theme Mode

Choose how Pieces displays its theme. You can select Dark, Light, or System mode, which automatically matches your operating system's theme preference.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Appearance`.

    In the *Theming* section, find the "Theme Mode" option showing your current mode (e.g., "Theme Mode: System").

    Click the `Dropdown Arrow` next to the current theme mode to open the theme options.

    Choose from the following options:
    * **Dark**: Dark theme for low-light environments
    * **Light**: Light theme for bright environments
    * **System**: Automatically matches your operating system's theme preference

### Accent Color

Customize the accent color used throughout the Pieces interface. The accent color affects interactive elements like buttons and highlights, but not the entire UI.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Appearance`.

    In the *Theming* section, find the "Accent Color" option showing your current color (e.g., "Accent Color: Blue") with a color swatch.

    Click the `Dropdown Arrow` next to the accent color to open the color picker, which displays a grid of available colors.

    Click on any color in the grid to select it. The selected color will be marked with a checkmark, and your accent color will update immediately.

## Fonts

Adjust the size and weight of text throughout the Pieces Desktop App to improve readability and match your preferences.

### Font Size

Adjust the size of all text in the Pieces Desktop App. This is helpful for different screen sizes, resolutions, or if you prefer larger or smaller text for readability.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Appearance`.

    In the *Fonts* section, find the "Font Size" option showing your current size (e.g., "Font Size: 100%").

    Use the controls to change the font size:
    * Click the `Minus Button` (`-`) to decrease the font size
    * Click the `Plus Button` (`+`) to increase the font size
    * The current percentage is displayed between the buttons

  You can also use keyboard shortcuts to zoom: `⌘+,+` (macOS) or `ctrl+,+` (Windows/Linux) to zoom in, and `⌘+,-` (macOS) or `ctrl+,-` (Windows/Linux) to zoom out.

### Font Weight

Adjust the thickness of text throughout the Pieces Desktop App. Choose from Thin, Normal, Medium, or Bold to match your reading preferences.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Appearance`.

    In the *Fonts* section, find the "Font Weight" option showing your current weight (e.g., "Font Weight: Normal").

    Click the `Dropdown Arrow` next to the current font weight to open the font weight options.

    Choose from the following options:
    * **Thin**: Lightest font weight for minimal visual weight
    * **Normal**: Standard font weight (default)
    * **Medium**: Slightly bolder than normal
    * **Bold**: Heaviest font weight for maximum emphasis

## Spacing

Adjust the spacing and layout density of the Pieces interface. Control how much information is displayed and how much space elements take up.

### Visual Density

Adjust the spacing and layout density of the Pieces interface. Choose between Tight, Compact, or Standard to control how much information is displayed and how much space elements take up.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Appearance`.

    In the *Spacing* section, find the "Visual Density" option showing your current density (e.g., "Visual Density: Standard").

    Click the `Dropdown Arrow` next to the current visual density to open the density options.

    Choose from the following options:
    * **Tight**: Maximum density with minimal spacing, showing more content in less space
    * **Compact**: Moderate density with reduced spacing
    * **Standard**: Default density with comfortable spacing (default)

  Controls spacing, padding, and overall compactness of the interface. Tight = minimal spacing, Compact = balanced, Standard = generous spacing.

***

## Next Steps

Now that you understand how to customize Appearance, learn about [Choose a Model](/products/desktop/conversational-search/models) to switch between model families and modes, or explore [Troubleshooting](/products/desktop/configuration/troubleshooting) to access support resources and view app information.

---

## Connected Applications
Path: /products/desktop/configuration/connected-applications

## Connected Applications Settings

Access documentation for Pieces integrations. Most editors and AI tools connect through the **Model Context Protocol (MCP)**; the [Integrations overview](/products/integrations-overview) explains how MCP and the CLI fit your workflow.

To access Connected Applications settings, click your `User Profile` in the top left, then hover over `Settings` and select `Connected Applications`.

> Connected Applications settings showing list of available integrations with links to documentation

## Available Applications

The Connected Applications page lists shortcuts to documentation for each integration. Legacy editor **plugins** are retired; use **MCP** setup guides for current IDE and AI tool integrations.

    Connect IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains editors to Pieces via Model Context Protocol.

    Use Pieces Long-Term Memory with GitHub Copilot in Visual Studio and other supported hosts.

    Browse all MCP clients—including editors without a dedicated guide—on the Pieces MCP documentation hub.

    Connect VS Code to PiecesOS with the official MCP setup guide.

    Access comprehensive documentation for the Pieces Command Line Interface.

    Access comprehensive documentation for the Pieces Desktop App.

    Get started with the Pieces plugin for Obsidian.

    Connect AI assistants that support MCP to PiecesOS; see the MCP hub for supported clients and configuration.

    Set up Pieces MCP in Raycast on macOS using an stdio bridge to PiecesOS.

***

## Next Steps

Now that you've explored the available integrations, choose an application to get started. Most integrations require [PiecesOS](/products/core-dependencies/pieces-os) to be installed, and we recommend the [Pieces Desktop App](/products/desktop) for enhanced functionality.

---

## Copilot Chats
Path: /products/desktop/configuration/copilot-chats

## Copilot Chats Settings

Customize your Conversational Search chat appearance and manage your chat history. Configure the accent color for your chats and delete all chats when needed.

To access Copilot Chats settings, click your `User Profile` in the top left, then hover over `Settings` and select `Copilot Chats`.

> Copilot Chats settings showing accent color option and delete all chats option

## Accent Color

Change the accent color used in your Conversational Search chats. The accent color affects the visual appearance of chat elements and helps personalize your chat interface.

### Changing Accent Color

    Click your `User Profile` in the top left, then hover over `Settings` and select `Copilot Chats`.

    At the top of the Copilot Chats settings, you'll see the "Accent Color" option showing your current color (e.g., "Accent Color: Blue") with a color swatch and Dropdown Arrow.

    Click the `Dropdown Arrow` next to the accent color to open the color picker, which displays a grid of 36 available colors.

    Click on any color in the grid to select it. The selected color will be marked with a checkmark, and your accent color will update immediately.

> Color picker showing grid of 36 colors with selected color marked with Checkmark

## Delete All Copilot Chats

Remove all of your Conversational Search chat history at once. This action permanently deletes all chats and cannot be undone.

### Understanding Chat Deletion

Deleting all Copilot chats permanently removes your entire chat history. This includes all conversations, messages, and context from previous chats. The total number of chats is displayed below the delete option (e.g., "45 Total Copilot Chats").

### Deleting All Chats

    Click your `User Profile` in the top left, then hover over `Settings` and select `Copilot Chats`.

    Scroll down to find the "Delete All Copilot Chats..." option, which displays a red Trash Icon to the right.

    Click the `Trash Icon` to delete all of your Copilot chats.

    Confirm the deletion when prompted. All chats will be permanently removed and cannot be restored.

  Deleting all Copilot chats is a permanent action that cannot be undone. All chat history, conversations, and context will be permanently removed.

***

## Next Steps

Now that you understand how to customize Copilot Chats, learn about [Choose a Model](/products/desktop/conversational-search/models) to switch between model families and modes, or explore [Model Context Protocol (MCP)](/products/desktop/configuration/mcp) to integrate Pieces with other tools.

---

## Long-Term Memory
Path: /products/desktop/configuration/long-term-memory

## Long-Term Memory Settings

Manage long-term memory preferences and data. Configure the Long-Term Memory Engine, control which applications Pieces can access, manage system permissions, optimize performance, and clear stored data.

To access Long-Term Memory settings, click your `User Profile` in the top left, then hover over `Settings` and select `Long-Term Memory`.

> Long-Term Memory settings showing Memory Formation, Performance, and Stored Data sections

## Memory Formation

Configure how the Long-Term Memory Engine captures and processes your workflow context. The Long-Term Memory (LTM-2.7) Engine uses on-device machine learning to auto-generate Workstream Activities and provide temporal context for your Conversational Search.

### Long-Term Memory Engine

Toggle the Long-Term Memory Engine on or off to control whether Pieces captures and uses your workflow context.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Long-Term Memory`.

    In the *Memory Formation* section, find the "Long-Term Memory Engine" option showing your current status (e.g., "Long-Term Memory Engine: On" with a green indicator).

    Click the toggle or button to enable or disable the Long-Term Memory Engine. When enabled, it uses on-device machine learning to auto-generate Workstream Activities and provide temporal context for your Conversational Search.

  The Long-Term Memory Engine helps Pieces understand your workflow patterns and provide more contextual suggestions in Conversational Search. When disabled, Pieces won't capture or use workflow context.

### Pausing Capture

Pause *LTM-2.7* and *LTM Audio* for a custom duration: minutes, hours, or days. Pieces shows a **Paused until** label so you know exactly when capture resumes.

You can pause from:

* This *Long-Term Memory* settings page
* Your `User Profile` popover (hover `LTM-2.7`)
* The [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu)

    Click your `User Profile`, hover over `LTM-2.7`, and choose a pause duration. Alternatively, open `Settings` → `Long-Term Memory` and pause from *Memory Formation*.

    Check the **Paused until** indicator so you know when capture will pick back up automatically.

  Capture also stops while your screen is locked, and slows when you go idle. For the full pause behavior, see [LTM-2.7 Engine](/products/core-dependencies/pieces-os/long-term-memory#pausing-or-disabling-ltm).

### App Access Control

Manage which applications the Long-Term Memory Engine interacts with. This allows you to control what data sources Pieces uses when capturing workflow context.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Long-Term Memory`.

    In the *Memory Formation* section, find the "App Access Control" option with the description "Manage apps that Long-Term Memory interacts with".

    Click the `Dropdown Arrow` or icon next to "App Access Control" to manage which applications the Long-Term Memory Engine interacts with.

    Enable or disable specific applications that you want Long-Term Memory to capture data from. Applications that are enabled will have their workflow context captured and indexed.

### Proactive App Deny List

Block applications from Long-Term Memory **before** Pieces ever captures data from them. This is useful for applications that handle sensitive information, such as password managers, banking apps, healthcare portals, or HR systems.

Unlike standard App Access Control, which manages apps Pieces has already seen, the deny list lets you preemptively block any app on your system so Pieces never captures data from it in the first place.

    In *Memory Formation*, click the dropdown or icon next to "App Access Control".

    Look for the option to add applications to the deny list. This shows all applications on your system, not just ones Pieces has seen.

    Use the search field to find the application you want to block by name.

    Click the application to add it to your deny list. Pieces will never capture data from this application.

  Add sensitive applications to the deny list proactively. Common candidates include password managers (1Password, Bitwarden), banking apps, healthcare portals, and any application where you handle confidential information.

### System Permissions

Manage accessibility and screen permissions for the Long-Term Memory Engine. If permissions are not already enabled, you can provide the necessary permissions to Pieces.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Long-Term Memory`.

    In the *Memory Formation* section, find the "System Permissions" option with the description "Manage accessibility and screen permissions for LTM".

    Click the `Permissions Icon` to open the permissions settings. If permissions are not already enabled, you'll be prompted to provide the necessary permissions to Pieces.

    Follow the system prompts to grant the required accessibility and screen permissions that allow the Long-Term Memory Engine to capture workflow context.

### LTM Audio

LTM Audio, also known as Audio Ingestion, enables the Long-Term Memory Engine to capture system audio and microphone input to enhance your workflow context. This feature is currently in *Preview* and requires platform-specific permissions.

    > LTM Audio setup on macOS

    First-time users will see a yellow warning indicator on the `Enable LTM Audio` option when they open their `User Profile` in the top left. Click the `warning indicator` to open the permissions dialog and grant the required access.

        Click your `User Profile` in the top left. If you see a yellow warning indicator, click it to open the "Some Permissions Are Missing" dialog. Otherwise, go to *Settings* → *Long-Term Memory* → *Long-Term Memory Permissions*.

        In the permissions dialog, locate "System Audio Capture" and click the `Allow` button. This opens the macOS *Privacy & Security* → *Screen & System Audio Recording* settings.

        In the *System Audio Recording Only* section at the bottom, click the `+` button. Navigate to *Applications* in Finder and select `Pieces OS`. The system will prompt you to restart Pieces OS—choose `Quit & Reopen`.

        After restarting, the permissions dialog will prompt you to grant Microphone Access. Click the `Allow` button for "Microphone Access" to open the macOS *Privacy & Security* → *Microphone* settings.

        In the Microphone settings, find `Pieces OS` and turn the toggle on. Choose `Quit & Reopen` when prompted to restart Pieces OS.

        Once permissions are granted, click your `User Profile` in the top left and click `Enable LTM Audio` to turn the feature on. Alternatively, click the `PiecesOS` icon in your menu bar to open the dropdown, scroll to *LTM Audio*, and enable it there.

      LTM Audio is a *Preview* feature. You must grant both System Audio Capture and Microphone Access, then restart Pieces OS after each permission change, before the feature can be enabled.

    > LTM Audio setup on Windows

    On Windows, LTM Audio prompts for microphone permission only. Accept the prompt and the feature is enabled—no system audio capture or restart required.

    Enable LTM Audio from your `User Profile` in the top left, or from the PiecesOS icon in your system tray—click it to open the dropdown, scroll to *LTM Audio*, and toggle it on.

    **If you skipped the initial permission prompt**

    You can grant microphone access through Windows Settings:

        Press `Win + I` or click the `Start` button and select `Settings`.

        Go to `Privacy & Security` (Windows 11) or `Privacy` (Windows 10), then select `Microphone`.

        Turn on *Microphone access* if it is off. Find `Pieces OS` in the list of apps and enable the toggle next to it.

        Restart Pieces if it was open, then enable *LTM Audio* from your `User Profile` or the `PiecesOS` system tray dropdown.

      LTM Audio is a *Preview* feature. Accept the microphone permission when prompted to enable the feature.

    On Linux (Snap installation), run `pieces-os.doctor` after installation. The script outputs a command you can copy and paste into your terminal to connect all interfaces with the system.

    Once the interfaces are connected, enable LTM Audio from your `User Profile` in the top left, or from the PiecesOS icon in your application tray—click it to open the dropdown, scroll to *LTM Audio*, and toggle it on.

      LTM Audio is a *Preview* feature. Run `pieces-os.doctor` to connect system interfaces before enabling the feature.

### Querying Your LTM Audio Context

Once LTM Audio is enabled and you've had meetings or conversations, you can query that audio context in [Conversational Search](/products/desktop/conversational-search) just like any other LTM data. Example queries:

* *"What was discussed in yesterday's standup about the blockers on the API migration?"*
* *"What action items came out of yesterday's sprint planning meeting?"*
* *"Summarize the key takeaways from today's board meeting."*

See the [LTM prompting guide](/products/quick-guides/ltm-prompting) for more query strategies.

## Performance

Optimize system resources and manage memory usage for the Long-Term Memory Engine.

### Optimize System RAM Usage

Unload local machine learning models and resources from memory to free up system resources. This is useful if you need to reduce memory usage or free up resources for other applications.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Long-Term Memory`.

    Scroll down to the *Performance* section.

    Click the `Optimize System RAM Usage` button (CPU/Microchip Icon) to unload local machine learning models and resources from memory.

  Optimizing memory usage can help free up system resources, but you may need to reload models when you next use features that require them, which may take a moment.

## Stored Data

Manage and clear data captured by the Long-Term Memory Engine. In the *Stored Data* section, click `Clear Long-Term Memory Data...` to open the panel, where you can scope deletions by time period, capture method, and application source.

Clearing data is a PiecesOS capability. For the full walkthrough of the `Time Periods`, `Modalities`, and `App Sources` controls, see [Clearing Stored LTM Data](/products/core-dependencies/pieces-os/long-term-memory#clearing-stored-ltm-data).

  Clearing Long-Term Memory data is permanent and cannot be undone. Review the summary line before you confirm.

***

## Next Steps

Now that you understand how to manage Long-Term Memory settings, learn how to [Choose a Model](/products/desktop/conversational-search/models) to switch between model families and modes, or explore [Conversational Search](/products/desktop/conversational-search) to query your workflow memories.

---

## Model Context Protocol (MCP)
Path: /products/desktop/configuration/mcp

## Model Context Protocol (MCP) Settings

Access server URLs and documentation for integrating Pieces Long-Term Memory with Cursor, GitHub Copilot, and other tools that support the Model Context Protocol. The MCP server enables connectivity between Large Language Models (LLMs) and your personal context stored by the Long-Term Memory Engine (LTM-2.7).

To access MCP settings, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

> Model Context Protocol (MCP) settings showing server URLs and View Documentation option

## Available Servers

Copy the server URLs to configure MCP integrations in compatible IDEs and code editors. Multiple server URLs are available, including the latest schema version and previous versions for compatibility.

### Understanding Server URLs

The MCP settings display server URLs that your development tools or AI applications, such as [Cursor](/products/mcp/cursor) or [GitHub Copilot](/products/mcp/github-copilot), will use to communicate directly with your local PiecesOS MCP server.

  Copy the server URL below and paste it into your MCP client configuration. The latest schema version may not be compatible with all MCP clients yet. If you experience connection issues, try using an earlier version or restarting your MCP client. For the best results, try using with Cursor or Claude.

### Copying Server URLs

    Click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    In the *Available Servers* section, you'll see server URLs displayed, each with a Copy Icon to the right.

    The latest schema URL is marked with a blue "LATEST SCHEMA" badge. Click the `Copy Icon` next to the URL to copy it to your clipboard. The URL format is `http://localhost:39300/model_context_protocol/2025-03-26/mcp` with the release date displayed below it.

    If you need compatibility with older MCP clients, you can copy a previous version URL (e.g., `http://localhost:39300/model_context_protocol/2024-11-05/sse`). Click the `Copy Icon` next to the URL you need.

    Paste the copied URL into your IDE or tool's MCP configuration. Use the latest schema URL for the most up-to-date features, or use an earlier version if you encounter compatibility issues.

  The release date displayed under each server URL indicates when that schema version was released. The latest schema version provides the most current features, but older versions may be more compatible with certain MCP clients.

## View Documentation

Access detailed guides that explain how to leverage MCP integrations with popular development environments, such as Cursor and GitHub Copilot.

### Opening MCP Documentation

    Click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll to the *View Documentation* section, which displays: "Learn how to use Long-Term Memories with Cursor, GitHub Copilot and other tools using our MCP server."

    Click the `Documentation Icon` (book icon) to open the MCP documentation, which covers setup instructions, example scenarios, and troubleshooting tips for efficient MCP usage.

The documentation provides comprehensive guides on:

* **Setting Up Integrations**: Step-by-step instructions for configuring MCP in Cursor, GitHub Copilot, and other tools
* **Use Cases**: Examples of how MCP enhances your coding and debugging experiences
* **Troubleshooting**: Solutions for common integration issues and configuration problems

### Example Use Cases

MCP enhances your coding and debugging experiences in several ways:

* **Context-Rich Debugging**: Instantly retrieve logs, historical debugging notes, or team discussions directly from PiecesOS when troubleshooting within Cursor
* **Contextual Queries**: Access historical code implementations, error resolutions, or previously encountered bugs within GitHub Copilot for quicker coding solutions

For more use cases and detailed setup instructions, refer to the [MCP documentation](/products/mcp).

## MCP Connections

Connect Pieces to supported apps with one click. Pieces saves each app's connection settings for you and, when supported, also creates the matching rule or skill file automatically.

Most apps connect with a simple local link. **Claude Desktop** is different: Pieces includes the connector it needs, so you can connect without installing anything extra.

> MCP Connections section showing supported clients with one-click Connect buttons

  Some apps may need to be restarted or reopened before the new settings appear. For Claude Desktop, Pieces shows a *Restart Claude Desktop* prompt with a `Restart Claude Desktop now` button when a restart is required.

The MCP Connections section shows your connection status (e.g., "Connected 4 of 6") and a `Refresh Connections` button to update the status.

### Supported Clients

| Client | Description |
| --- | --- |
| **Claude Desktop** | Connect Pieces to Claude Desktop for access to all of your Personal Memories without any additional installation |
| **Cursor** | Connect Pieces to Cursor so your IDE has access to long-term memory |
| **GitHub Copilot** | Connect Pieces to GitHub Copilot for context-aware code suggestions |
| **Codex** | Connect Pieces to Codex so both the CLI and IDE extension can connect to your memory via MCP |
| **Google Gemini CLI** | Connect Pieces to Google Gemini CLI so terminal-based workflows can use MCP-backed context |
| **Antigravity** | Connect Pieces to Antigravity so its agent panel can access your long-term memory over MCP |
| **Claude Code** | Connect Pieces to Claude Code so terminal-based workflows can use long-term memory context |
| **OpenClaw** | OpenClaw setup is documented separately for now. Click `View Docs` to open the setup guide |

### Connecting a Client

    Click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Find the *MCP Connections* section below the Available Servers and View Documentation sections.

    When connecting **Claude Desktop** on Linux, quit Claude Desktop first if it is already running so Pieces can write the config safely.

    Click the `Connect` button next to the client you want to configure. Pieces automatically writes the MCP configuration to that client's config file.

    Restart or reopen the MCP client for the configuration changes to take effect. For Claude Desktop, use `Restart Claude Desktop now` when the prompt appears.

  For the full Claude Desktop flow, including Snap and Flatpak notes, see [Pieces MCP + Claude Desktop](/products/mcp/claude-desktop).

### Managing Connected Clients

Once connected, a green checkmark appears next to the client name. To disconnect or reconfigure:

    Click the `⋮` menu next to a connected client.

    Select **Disconnect** to remove the configuration, or **Reconfigure** to update settings.

  OpenClaw requires manual configuration. If your OpenClaw instance is remote (e.g., a homelab server), you'll need to set up tunneling. Click `View Docs` next to OpenClaw to see the setup guide.

***

## Next Steps

Now that you understand how to access MCP server URLs and documentation, learn how to [set up MCP with Cursor](/products/mcp/cursor) or [integrate with GitHub Copilot](/products/mcp/github-copilot) to start using Pieces Long-Term Memory in your development workflow.

---

## Troubleshooting
Path: /products/desktop/configuration/troubleshooting

## Troubleshooting Settings

Get help, troubleshoot issues, view app information, and contact support. Access support resources, documentation links, version details, and feedback channels to resolve issues and get the most out of Pieces.

To access Troubleshooting settings, click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

> Troubleshooting settings showing Online Resources, Get In Touch, PiecesOS Information, and Desktop App Information sections

## Online Resources

Access documentation and community resources to find answers and solutions to common issues.

### Product Documentation

Access Pieces' official documentation to learn how to use features, configure settings, and get the most out of Pieces.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Online Resources* section.

    Click the `Product Documentation` option (book icon) to open Pieces' official documentation in your browser.

### GitHub Issues

Report bugs, request features, and track known issues on GitHub. The GitHub issues page is a great place to see what others are experiencing and contribute to improving Pieces.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Online Resources* section.

    Click the `GitHub Issues` option (GitHub Octocat logo icon) to open the Pieces GitHub issues page in your browser.

## Get In Touch

Contact the Pieces team directly for personalized support, feedback, or additional help resources.

### Book a Support Call

Schedule a one-on-one support call with our team to get personalized assistance with any issues or questions you have.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Get In Touch* section.

    Click the `Book a Support Call` option (calendar icon) to schedule a support call with the Pieces team.

### Contact Us

Send us a message and our team will get back to you. Use this option for general questions, feedback, or issues that don't require immediate attention.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Get In Touch* section.

    Click the `Contact Us` option (envelope icon) to send a message to the Pieces support team.

### More Options

Visit our support hub for additional resources, FAQs, and community support. This provides access to a comprehensive knowledge base and community forums.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Get In Touch* section.

    Click the `More Options` option (external link icon) to visit the support hub with additional resources, FAQs, and community support.

## PiecesOS Information

View information about your installed PiecesOS version, check for updates, and see what port PiecesOS is using. PiecesOS is the core engine that powers all Pieces functionality.

### Viewing PiecesOS Version

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *PiecesOS Information* section.

    Find the "Version" field showing your installed PiecesOS version (e.g., "12.3.5").

    Click the `Copy Icon` next to the PiecesOS version to copy the version number to your clipboard.

### Viewing PiecesOS Port

View the port number that PiecesOS is currently using. This information is useful for troubleshooting connection issues or configuring integrations.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *PiecesOS Information* section.

    Find the "Port" field showing the current port (e.g., "39300").

    Click the `Copy Icon` next to the PiecesOS port to copy the port number to your clipboard.

### Checking for PiecesOS Updates

Manually check if a new version of PiecesOS is available. Updates may include bug fixes, performance improvements, and new features.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *PiecesOS Information* section.

    Click the `Check for Updates` link to manually trigger an update check. If an update is available, you'll be prompted to install it. Both PiecesOS and the Desktop App update together.

## Desktop App Information

View information about your installed Pieces Desktop App version, check for updates, and see your platform details. The Desktop App provides the user interface and features built on top of PiecesOS.

### Viewing Desktop App Version

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Desktop App Information* section.

    Find the "Version" field showing your installed Desktop App version (e.g., "5.0.6-staging").

    Click the `Copy Icon` next to the Desktop App version to copy the version number to your clipboard.

### Viewing Platform Information

View your operating system and platform details. This information is useful for troubleshooting or when seeking support.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Desktop App Information* section.

    Find the "Platform" field showing your OS version and build information (e.g., "MacOS Version 15.7.3 (Build 24G419)").

    Click the `Copy Icon` next to the Platform information to copy the platform details to your clipboard.

### Checking for Desktop App Updates

Manually check if a new version of the Pieces Desktop App is available. Updates may include new features, UI improvements, and bug fixes.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Scroll to the *Desktop App Information* section.

    Click the `Check for Updates` link to manually trigger an update check. If an update is available, you'll be prompted to install it. Both PiecesOS and the Desktop App update together.

  You can also check for Desktop App updates using the keyboard shortcut `shift+U` (macOS) or `shift+U` (Windows/Linux) from anywhere in Pieces.

### Keyboard Shortcuts

View all available keyboard shortcuts for Pieces Desktop. Learn shortcuts to navigate faster, perform actions quickly, and improve your workflow efficiency.

    Click your `User Profile` in the top left, then hover over `Settings` and select `Troubleshooting`.

    Find the keyboard shortcuts option or use the keyboard shortcut `⌘+;` (macOS) or `ctrl+;` (Windows/Linux) from anywhere in Pieces.

For a complete reference guide of all keyboard shortcuts, see the [Keyboard Shortcuts](/products/desktop/actions/keyboard-shortcuts) documentation.

## Quick Links

Access common resources and documentation quickly:

* **[Product Documentation](/products/desktop)** - Complete Pieces Desktop documentation
* **[Keyboard Shortcuts](/products/desktop/actions/keyboard-shortcuts)** - All available keyboard shortcuts
* **[GitHub Issues](https://github.com/pieces-app)** - Report bugs and request features
* **[Discord Community](https://discord.gg/getpieces)** - Join the Pieces community for support
* **[Privacy & Security](/products/privacy-security-your-data)** - Learn about data privacy and security
* **[Support](/products/support)** - Additional support resources and FAQs

***

## Next Steps

Now that you understand how to access troubleshooting resources, learn about [Account](/products/desktop/configuration/account) settings to manage your account and cloud settings, or explore [Choose a Model](/products/desktop/conversational-search/models) to switch between model families and modes.

---

## Views & Layouts
Path: /products/desktop/configuration/views-layouts

## Views & Layouts Settings

Customize confirmation settings, metrics summary display, and saved materials toolbar preferences. Configure when confirmation prompts appear, how metrics summaries are displayed, and which toolbar options are available for saved materials.

To access Views & Layouts settings, click your `User Profile` in the top left, then hover over `Settings` and select `Views & Layouts`.

> Views & Layouts settings showing Confirmation Settings, Metrics Summary Settings, and Default Toolbar options

## Confirmation Settings

Configure which confirmation menus appear when performing deletions or updates. Confirmation prompts help protect you from unintended actions by requiring an extra step before making significant changes.

### Opening Confirmation Settings

    Click your `User Profile` in the top left, then hover over `Settings` and select `Views & Layouts`.

    In the *Views & Layouts* section, find the "Confirmation Settings" option with the description "Select which confirmation menus show or not".

    Click the `Settings Icon` (gear icon) to the right of the Confirmation Settings option to open the *Confirmation Menu Settings* popup.

> *Confirmation Menu Settings* popup showing Deletions and Updates sections with checkboxes

### Deletions

Configure confirmation prompts for various deletion actions. When enabled, Pieces will ask for confirmation before permanently deleting items.

    Click the `Settings Icon` next to Confirmation Settings in Views & Layouts.

    In the *Confirmation Menu Settings* popup, find the *Deletions* section.

    Enable or disable confirmation prompts for:
    * **Confirm Saved Material deletions**: Check the checkbox to require confirmation before deleting saved materials
    * **Confirm Timeline Event deletions**: Check the checkbox to require confirmation before deleting Timeline Events
    * **Confirm Saved Material Context deletions**: Check the checkbox to require confirmation before deleting context (tags, related links, and more). Click the `Dropdown Arrow` to access additional context deletion options

### Updates

Configure confirmation prompts for shareable link updates. When enabled, Pieces will prompt you before updating shareable links when modifying saved materials.

    Click the `Settings Icon` next to Confirmation Settings in Views & Layouts.

    In the *Confirmation Menu Settings* popup, find the *Updates* section.

    Enable or disable confirmation prompts for:
    * **Confirm Shareable Link updates**: Check the checkbox to prompt you to update your shareable link when updating a Saved Material
    * **Confirm Sensitive Shareable Link updates**: Check the checkbox to prompt you to update shareable links that have sensitive information when updating a Saved Material

> Updates section showing Shareable Link update confirmation options

## Metrics Summary Settings

Customize when and how the Metrics Summary displays in Gallery View. Control the visibility of context summaries to keep your interface clean while still providing information when needed.

### Opening Metrics Summary Settings

    Click your `User Profile` in the top left, then hover over `Settings` and select `Views & Layouts`.

    In the *Views & Layouts* section, find the "Metrics Summary Settings" option with the description "Customize when the Metrics Summary shows".

    Click the `Hamburger Icon` (three horizontal lines) to the right of the Metrics Summary Settings option to open the *Metrics Settings* popup.

> *Metrics Settings* popup showing Mode and Visibility options

### Mode

Configure how the Metrics Summary behaves in Gallery View.

    Click the `Hamburger Icon` next to Metrics Summary Settings in Views & Layouts.

    In the *Metrics Settings* popup, find the *Mode* section.

    Check the "Smart Layout" checkbox to show Context Summary automatically for small snippets while browsing the Gallery View. When enabled, summaries appear automatically for smaller snippets without requiring hover or navigation.

### Visibility

Configure when the Metrics Summary is visible in Gallery View. You can choose to show summaries when navigating, hovering, or both.

    Click the `Hamburger Icon` next to Metrics Summary Settings in Views & Layouts.

    In the *Metrics Settings* popup, find the *Visibility* section.

    Enable one or more visibility options:
    * **All**: Check the checkbox to show when navigating and hovering
    * **Navigating**: Check the checkbox to show when navigating the Gallery View
    * **Hovering**: Check the checkbox to show when hovering the context icon

  You can enable multiple visibility options simultaneously. For example, enabling both "Navigating" and "Hovering" will show summaries in both scenarios, while enabling "All" covers both cases automatically.

## Saved Materials Action Toolbar

Configure the default toolbar that appears for saved materials. Choose between Default, Suggested, or Custom toolbar options to match your workflow preferences.

### Changing Default Toolbar

    Click your `User Profile` in the top left, then hover over `Settings` and select `Views & Layouts`.

    In the *Saved Materials Action Toolbar* section, find the "Default Toolbar: Default" option.

    Click the `Dropdown Arrow` next to the current toolbar selection to open the toolbar options.

    Choose from the following options:
    * **Default**: Standard toolbar with common actions
    * **Suggested**: Toolbar with AI-suggested actions based on your workflow
    * **Custom**: Customized toolbar with your preferred actions

> Default Toolbar dropdown showing Default, Suggested, and Custom options

***

## Next Steps

Now that you understand how to configure Views & Layouts, learn about [Appearance](/products/desktop/configuration/appearance) settings to customize the visual appearance of Pieces, or explore [Account](/products/desktop/configuration/account) settings to manage your account and privacy preferences.

---

## Connectors
Path: /products/desktop/connectors

## Overview

**Connectors** link external services to Pieces so that [Conversational Search](/products/desktop/conversational-search) can pull richer context from the tools you already use—and take actions in them on your behalf.

Unlike [Long-Term Memory](/products/core-dependencies/pieces-os/long-term-memory), which passively captures activity from your device, *Connectors* are **active integrations**: once authorized, Pieces can both read data from the service (for example, your upcoming meetings) and perform actions in it (scheduling events, inviting attendees, rescheduling, and more).

## Opening Connectors

Access *Connectors* from the Pieces Desktop App settings.

    Click the `Settings` icon in the Pieces Desktop App to open the settings view.

    In the settings sidebar, click `Connectors`.

    Click `Connect` next to any available connector to begin the authorization flow.

> The Connectors pane in Pieces Desktop Settings, showing Google Calendar connected with four additional integrations available soon

## Available Connectors

The following connectors are available or in development:

* **Google Calendar** — Import meeting context so Pieces can understand your schedule, and let Conversational Search create, update, and manage events on your behalf.
* **GitHub** *(coming soon)* — Surface pull requests, issues, and code reviews as context.
* **Slack** *(coming soon)* — Bring team conversations and threads into your workstream.
* **Google Drive** *(coming soon)* — Access documents and files to enrich your context.
* **Microsoft Teams** *(coming soon)* — Connect meetings and messages for a fuller picture of your day.

***

## Explore Connectors

  Connect your Google Calendar to read your schedule and let Pieces create, update, and cancel events on your behalf through Conversational Search.

---

## Google Calendar Connector
Path: /products/desktop/connectors/google-calendar

## Google Calendar Connector

The *Google Calendar* connector links your Google account to Pieces so [Conversational Search](/products/desktop/conversational-search) can both **read** your schedule and **act** on it—creating events, inviting attendees, rescheduling meetings, and more.

Once connected, you can ask Pieces things like *"What do I have tomorrow afternoon?"* or *"Schedule a 30-minute sync with Alice next Tuesday at 2pm with a Google Meet link."*

## Connecting Google Calendar

Connect your Google account through a standard OAuth flow in your default browser.

    In the Pieces Desktop App, open `Settings` and select `Connectors`.

    Click `Connect` next to *Google Calendar*. Pieces opens your default browser to Google's authorization page.

    Sign in to the Google account you want to connect and grant the requested calendar permissions.

    Once authorization completes, your browser redirects back to Pieces. The connector's button changes from `Connect` to `Disconnect`, confirming the account is linked.

## What You Can Do

Once connected, Conversational Search can use the *Google Calendar* connector to query your schedule, take actions, and enrich answers with calendar context.

| Feature | Example prompt |
| --- | --- |
| **View your schedule** | *"What's on my calendar this week?"* |
| **Inspect an event** | *"Show me the attendees, location, and description for my 2pm standup tomorrow."* |
| **Search events** | *"Find my most recent 1:1 with Alice."* |
| **Create an event** | *"Schedule a 30-minute sync with alice@example.com next Tuesday at 2pm and add a Google Meet link."* |
| **Create an all-day event** | *"Block Friday as an all-day focus day on my work calendar."* |
| **Reschedule** | *"Move my 3pm Friday meeting to Monday at 10am and notify attendees."* |
| **Update event details** | *"Add bob@example.com to my 4pm sync and update the description with the new agenda."* |
| **Cancel an event** | *"Cancel my 10am standup tomorrow and send cancellation emails."* |
| **Check availability** | *"When am I free for a 45-minute meeting this week?"* |
| **Scope to one account** | *"Show this week's events on my work calendar, not personal."* |
| **Query a shared calendar** | *"What's on the team calendar for next Monday?"* |
| **Combine with workflow context** | *"Summarize what I worked on during yesterday's 1:1 with Alice."* |

  Deleting an event is permanent. Pieces will always confirm before cancelling an event on your behalf.

## Using Calendar Context in Conversational Search

Beyond direct calendar management, Pieces uses your calendar to enrich answers.

* **Check availability** before suggesting meeting times.
* **Provide context** about upcoming or recent meetings when answering questions.
* **Cross-reference** calendar events with activity captured by [Long-Term Memory](/products/core-dependencies/pieces-os/long-term-memory).

## Calendar Context in Summaries

Once connected, your calendar events flow into [Single-Click Summaries](/products/desktop/single-click-summaries) that use workflow context, including *Morning Brief*, *Standup Update*, and *Day Recap*. These summaries reflect what was actually on your schedule rather than what happened to be visible on your screen.

The *Google Calendar* connector is also the foundation for [Meeting Prep](/products/desktop/single-click-summaries/default-types#meeting-prep), a summary type that looks ahead at your upcoming meetings, cross-references each event with your Long-Term Memory, and generates a structured pre-read. In summary results, hover attendee names for [persona cards](/products/desktop/single-click-summaries#people-tags--anchors).

Example prompts:

* *"When am I free for a 45-minute meeting this week?"*
* *"Summarize what I worked on during yesterday's 1:1 with Alice."*
* *"Move my 3pm to Friday morning and let the attendees know."*

## Managing Connected Accounts

You can connect multiple Google accounts and manage them from the connector's management screen.

> Google Calendar Manage modal showing connected accounts, reconnect options, and add account button

    In the Pieces Desktop App, open `Settings` and select `Connectors`.

    Click the `Manage` button next to *Google Calendar* to open the management modal.

    The modal shows your **Connected Accounts** count and lists each linked account. You can also see accounts under **Needs Attention** if they've been disconnected and require reconnection.

### Adding Another Account

Connect additional Google accounts to access multiple calendars.

    Click `Manage` next to *Google Calendar* in Connectors settings.

    Click `+ Add account` in the Connected Accounts section.

    Complete the OAuth flow for the additional Google account.

### Reconnecting a Disconnected Account

If an account appears under **Needs Attention**, you can reconnect it.

    Click `Manage` next to *Google Calendar* in Connectors settings.

    Look under **Needs Attention** for accounts showing "Disconnected" status.

    Click the `Reconnect` button next to the account to re-authorize access.

### Disconnecting an Account

Remove access for a specific Google account.

    Click `Manage` next to *Google Calendar* in Connectors settings.

    Locate the account you want to disconnect in the Connected Accounts list or Needs Attention section.

    Click the `trash icon` next to the account to disconnect it. Pieces revokes the OAuth token and stops accessing that account's calendar.

## Limitations

The current release of the *Google Calendar* connector has the following limitations:

* **Invitation responses** — Pieces cannot accept or decline invitations on your behalf.
* **Calendar settings** — Pieces cannot manage calendar permissions or settings.
* **Recurring event rules** — Pieces cannot create recurrence rules, though it can read individual instances of recurring events.

***

## Next Steps

Learn more about how *Google Calendar* integrates with the rest of Pieces:

* [Conversational Search](/products/desktop/conversational-search) — where the *Google Calendar* connector is surfaced.
* [Add Context to Your Chats](/products/desktop/conversational-search/setting-context) — combine calendar data with LTM context.
* [Connectors Overview](/products/desktop/connectors) — see every available connector.

---

## Conversational Search
Path: /products/desktop/conversational-search

***

## Overview

**Conversational Search** is the chat interface in the Pieces Desktop App. You ask questions about past work, and responses draw on context captured by the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os/long-term-memory) Engine.

You can include all captured memories or limit scope by app, time range, and modality. You can also attach local files and folders. Chats are saved to [Pieces Timeline](/products/desktop/timeline) so you can open them again later.

> Conversational Search homepage with suggested chats, recent chats, and Start New Chat

## Getting Started on the Homepage

When you open Conversational Search from the Desktop App home view, you have three entry points:

* **Suggested Chats for You** — Conversation starters based on recent activity. Click one to open a thread; responses include Related Timeline Events showing which memories were used.
* **Resume Recent Chats** — Cards for your latest threads. Click any card to continue with full history intact.
* **Start New Chat** — Type in the input at the bottom and press `Enter` to ask your own question.

  Click `Refresh suggestions` (circular icon beside the suggestions grid) to regenerate prompts from your latest activity. Click `Reveal previous chats in timeline` (panel icon on the *Resume Recent Chats* row) to open older threads in [Pieces Timeline](/products/desktop/timeline).

**Example questions:**

* "Why did we choose PostgreSQL over MySQL for the auth project?"
* "What was the blocker I hit last Tuesday afternoon?"
* "What did Sarah and I discuss about the API redesign in Teams?"

## While You Chat

The bottom toolbar controls how each conversation runs:

| Control | What it does |
| --- | --- |
| `+` | Attach files or folders (or drag and drop into the input) |
| `Filter By...` | Limit memories by app, time, or modality |
| Model selector | Pick a model family and mode (Fast, Balanced, or Extra Thinking) |
| `lotus icon` | Toggle *Reflection Mode* for deeper reasoning on hard questions |
| `Send` | Send a message (`Enter` queues a follow-up while the agent is still responding) |

On active threads, the `⋮` menu at the top lets you **Pin**, **Refresh**, or **Delete** the chat. Token usage appears in the chat header so you can see input, output, reasoning, and cache totals for metered or BYOK plans.

To scope a chat to **one** Timeline Event or summary, open that item in Timeline and choose `Chat` from the three-dots menu (⋮). See [Add Context to Your Chats](/products/desktop/conversational-search/setting-context).

***

## Explore Conversational Search

  Use the Filter By menu to narrow which memories the agent can use in a thread.

  Attach files, start chats from Timeline Events, and review source memories in the Relevant Summaries sidebar.

  Switch between model families—Claude, Gemini, and ChatGPT—using Fast, Balanced, and Extra Thinking modes.

  Use keywords, time ranges, app names, and follow-ups to get sharper answers.

***

If Conversational Search is not what you need, explore [Pieces Timeline](/products/desktop/timeline) to browse captured events and summaries, or [Single-Click Summaries](/products/desktop/single-click-summaries) for one-click workflow reports.

---

## Chat from a Timeline Event
Path: /products/desktop/conversational-search/chat-with-timeline-events

## Starting a conversation with a Timeline Event

Start context-specific chats directly from any Timeline Event. When you start a conversation with a Timeline Event, it opens in Conversational Search with that event's full context pre-loaded and displayed as an information card. Use this when you want to ask questions about a specific past moment, understand what happened during a particular work session, or drill into details of a specific Timeline Event.

> Conversational Search view showing a Timeline Event card with pre-loaded context and input field ready for questions

## How to Start a Conversation

Start a context-specific conversation from any Timeline Event using the `Start Related Chat` button in the Timeline Event detail view.

    Click any event in the Pieces Timeline to view its summary in the *main panel*.

    Click `Start Related Chat` in the bottom right of the Timeline Event detail view to open Conversational Search with that event's context loaded.

> Conversational Search showing memory, Timeline Event, Start Related Chat, and Conversational Search open with Timeline Event card displayed

### Asking Questions with Pre-Loaded Context

When Conversational Search opens with a Timeline Event, you'll see an information card displaying the event's details, including its title, description, timestamp, and related participants. The input field will show a placeholder like "Ask about '[Event Name]'..." indicating that the conversation is scoped to that specific event. Type your question or click any suggested chats that appear. The conversation already has full context from that Timeline Event, including core tasks, key decisions, documents reviewed, and follow-up actions.

**Example questions:**
* "Why did we make that decision?"
* "What were the main blockers in this session?"
* "Summarize the key outcomes from this work"
* "What happened next?"

> Conversational Search interface showing Timeline Event information card with event details, input field with placeholder text, and bottom toolbar with model selection and filters

## Working with Responses

You can copy, export, regenerate, or convert responses just like in regular Conversational Search. Responses are scoped to that specific Timeline Event's context. You can also click the `Relevant Summaries` button at the bottom of any response to see which Timeline Events were used to generate the answer, though typically only the event you're discussing will appear since the conversation is already scoped to that single Timeline Event.

## Differences from Conversational Search

Starting a conversation with a Timeline Event focuses on a single Timeline Event, while Conversational Search can access all your memories or a filtered subset. Here's how they compare:

**Starting a conversation with a Timeline Event:**
* **Context** - One specific memory with pre-loaded context
* **Filters** - Not available (context is already scoped to that memory)
* **Best for** - Questions about specific moments, understanding particular decisions, or reviewing individual work sessions

**Conversational Search:**
* **Context** - All memories or a filtered subset based on your filters
* **Filters** - Sources & Time Ranges available to narrow scope
* **Best for** - Broad workflow questions spanning multiple time periods or when you need to search across different apps

Use starting a conversation with a Timeline Event when you want to dive deep into a specific past moment. Use Conversational Search for questions spanning multiple time periods or when you need to filter by apps or dates.

***

## Next Steps

Now that you know how to start context-specific chats from memories, learn how to use Conversational Search for broader workflow questions.

[Talk with Your Memories →](/products/desktop/conversational-search/using-conversational-search)

---

## Use LTM Context in Chats
Path: /products/desktop/conversational-search/context-integration

## Context & Project Integration

Control whether Conversational Search includes Long-Term Memory context in your conversations. When enabled, Conversational Search has access to 9 months of captured workflow context from your [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine, including code you've written, conversations you've had, and decisions you've made.

  LTM must be enabled to access the chat feature in Pieces Desktop. If LTM is off, chat does not work. LTM is enabled by default in conversations.

## LTM Context Toggle

Enable or disable Long-Term Memory context for Conversational Search. When enabled, your chats automatically include workflow history context. When disabled, conversations use only the current context without historical data.

### Enabling LTM Context

Turn on Long-Term Memory context to include workflow history in your chats:

    Click your `User Profile` in the top left of the Pieces Desktop App.

    Hover over `LTM-2.7` in the dropdown menu that appears.

    A menu will appear with options to pause LTM-2.7 or turn it off. To enable LTM context for Conversational Search, ensure LTM-2.7 is not paused or turned off.

### Disabling LTM Context

Turn off Long-Term Memory context when you want conversations without historical workflow data:

    Click your `User Profile` in the top left of the Pieces Desktop App.

    Hover over `LTM-2.7` in the dropdown menu.

    Select a pause duration (15 minutes, 1 hour, 6 hours, 12 hours, or 24 hours) or choose `Turn Off` to disable LTM-2.7. When LTM-2.7 is paused or turned off, Conversational Search will not include workflow history context in conversations.

> User profile menu showing LTM-2.7 hover menu with pause and turn off options

## Understanding LTM Context

When LTM-2.7 is enabled, Conversational Search automatically includes relevant workflow context from your Long-Term Memory. This means your conversations can reference:

* Code you've written and changes you've made
* Conversations and decisions from your workflow history
* Activities captured by LTM-2.7 from connected applications
* Timeline Events and summaries from your workflow

When LTM-2.7 is paused or turned off, Conversational Search operates without access to this historical context, providing responses based only on the current conversation.

  Check out the [LTM Prompting Guide](/products/quick-guides/ltm-prompting) or learn how to use [Conversational Search with LTM Context](/products/quick-guides/copilot-with-context) via these Quick Guides.

## Scoping a chat from Timeline

You can attach local **files** or **folders** to a chat using the `+` button or by dragging them into the input area (see [Adding Files and Folders as Context](/products/desktop/conversational-search/using-conversational-search#adding-files-and-folders-as-context)). To scope a chat to a **specific** captured memory—such as a workflow summary or Timeline Event—open it in [Pieces Timeline](/products/desktop/timeline), then use the **`Chat`** action on that item’s **three-dots menu** (⋮). That opens Conversational Search with that memory in scope.

For the full walkthrough, see [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary) on the Event Actions page.

You can still narrow **which** memories are in play across a normal chat with **Sources** and **Time Ranges**; see [Filtering your searches](/products/desktop/conversational-search/using-conversational-search#filtering-your-searches).

## Related Timeline Events

View which Timeline Events were used to generate responses by opening the Relevant Summaries sidebar.

Conversational Search draws from your LTM memories to provide accurate responses. The Relevant Summaries sidebar shows you exactly which Timeline Events were used to generate each response, helping you verify the source of information and discover related work.

### Viewing Related Timeline Events

Open the Relevant Summaries sidebar to see which Timeline Events were used in a response:

    After receiving a response in Conversational Search, look for the `Relevant Summaries` button at the bottom of the chat response.

    Click the `Relevant Summaries` button to open the sidebar on the right side of the interface.

    The sidebar displays a list of relevant Timeline Events that were used to generate the response. Each entry shows the Timeline Event title, description, timestamp, and related applications.

    Click the sort dropdown in the top right of the sidebar to change how summaries are organized. Options include `Suggested`, `Recent`, and `Most Viewed`.

    Click any Timeline Event in the sidebar to view full details about that event, including when it was captured and what specific context it contains.

    Click the `X` icon in the top left of the sidebar to close it and return to the main chat view.

> Relevant Summaries sidebar open showing Timeline Events used to generate the response, with sort dropdown visible in the top right

***

## Next Steps

Now that you know how to control LTM context in Conversational Search, learn how to start context-specific conversations directly from your workflow memories.

[Starting a conversation with a Timeline Event →](/products/desktop/conversational-search/chat-with-timeline-events)

---

## Choose a Model
Path: /products/desktop/conversational-search/models

## Model Selection

Click the `model button` in the bottom toolbar to choose your model. Pieces keeps selection simple: pick a **model family**, then choose a **mode**.

Pieces offers three model families:

* **Claude**
* **Gemini**
* **ChatGPT**

Each family is available in three modes:

| **Mode** | **Speed** | **Quality** | **Best For** |
| --- | --- | --- | --- |
| **Fast** | Fastest | Good | Quick questions, simple lookups, rapid iteration |
| **Balanced** | Moderate | Better | General tasks, summaries, everyday coding help |
| **Extra Thinking** | Slower | Best | Complex reasoning, debugging, multi-step analysis |

  Start with **Fast** for most tasks. Switch to **Extra Thinking** when you need deeper analysis.

    Click the `model button` in the *bottom toolbar*.

    Hover over **Claude**, **Gemini**, or **ChatGPT**.

    Click **Fast**, **Balanced**, or **Extra Thinking** for that family.

Your chat history stays intact when you switch models—new messages use the selected model while previous responses remain unchanged.

## Reflection Mode

Toggle the `lotus icon` next to the model selector to enable **Reflection Mode**. The agent reflects on its own reasoning and self-corrects in real time, producing higher-quality answers on harder questions.

Reflection Mode is powered by the **Agent Harness**—the framework that lets the agent reason across multiple turns, cross-reference your context, and refine its output before responding. For more on how this works in chat, see [Using Conversational Search](/products/desktop/conversational-search/using-conversational-search#reflection-mode).

## Web Search

Real-time web search with citations is powered by **Perplexity**. It runs automatically when a question needs current information; it is not a selectable model family.

## Your Data & Model Choice

Want control over which specific models are used or where your data is processed? Bring your own keys (BYOK) through your organization. See [BYOK & Org Models](/products/organizations-and-teams/settings-models).

***

## Next Steps

Learn how to [filter your searches](/products/desktop/conversational-search/scoping-your-prompt) by Apps, Time, and Modality to scope which memories are used in your conversations.

---

## Use Conversational Search in IDEs
Path: /products/desktop/conversational-search/multiple-environments

## Use Conversational Search in IDEs

Pieces connects to popular IDEs, editors, and productivity tools—most often through **Model Context Protocol (MCP)**—so you can use the same workflow in the environment you prefer.

## Cross-environment access

Editor integrations today run primarily through **MCP** (see the [Integrations overview](/products/integrations-overview)). Legacy editor **plugins** are retired; use the MCP guides for current setup.

In supported environments you get **PiecesOS** and **Long-Term Memory** context alongside **Conversational Search**. Legacy **Pieces Drive** remains available where documented; new workflows should use **LTM** and **Timeline**.

### MCP and editor guides

| **Environment** | **Documentation** |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| [JetBrains IDEs](/products/mcp/jetbrains-ides) | Setup for JetBrains via MCP |
| [Visual Studio Code](/products/mcp/vs-code) | VS Code via MCP |
| [GitHub Copilot in Visual Studio](/products/mcp/github-copilot) | Visual Studio via MCP |
| [Other editors (MCP hub)](/products/mcp) | Raycast, notebooks, and additional MCP hosts |
| Browser | [Web Extension](/products/web-extension) |
| Neovim | [Neovim plugin](https://pieces.app/plugins/neovim) (external) |

Additionally:

* [Pieces CLI](/products/cli)
* [Raycast (MCP)](/products/mcp/raycast)
* [Obsidian](/products/obsidian)

## Integration with other applications

In IDEs that use the Pieces **Applet** or MCP, you get a familiar chat experience with context-aware suggestions tied to your project. **LTM** preferences and model choices stay aligned with the Desktop App where supported.

### Shared conversation threads

Conversational Search supports **cross-threading**: chat history and context can move between the Desktop App and other connected environments so you can continue the same thread.

## The Pieces user experience

Core behavior—chat history, context controls, and LLM configuration—is designed to feel consistent across environments.

### Flutter-supported environments

On platforms such as JetBrains IDEs, Visual Studio Code, and the Pieces Web Extension, a Flutter-based **Applet** delivers a standardized experience for Conversational Search and related tools.

### Custom UI environments

Where a Flutter applet is not available (for example some editors or the CLI), the UI is tailored to the host while keeping the same capabilities.

***

## Next Steps

Return to the Desktop-focused guides when you configure memory, context, and models in the app:

[Talk with Your Memories →](/products/desktop/conversational-search/using-conversational-search)

---

## Write Better Prompts
Path: /products/desktop/conversational-search/prompting-guide

## Asking Effective Questions

The more specific your questions, the better Conversational Search can find relevant memories and provide accurate answers.

## Use Specific Keywords

Include unique keywords related to what you're looking for—project names, ticket numbers, package names, or specific topics.

**Good:** "What is the status of project Aurora?"

**Bad:** "What is the status of my project?"

  If you can't remember specific keywords, try asking: "Give me the titles of all the project documents I've been working on last month" to find keywords for more specific prompts.

## Include Time Ranges

Specify when something happened to narrow down results. Conversational Search stores up to 9 months of memories.

**Examples:**
* "What decision did we make about the database schema last week?"
* "What were the plans I received in December?"
* "What was I debugging yesterday afternoon?"

## Mention Source Applications

Reference specific apps to separate similar content across different sources.

**Example:** "What did Sarah and I discuss in Teams about the deployment?"

This separates Teams conversations from emails or document comments.

## Combine Techniques

Mix keywords, time ranges, and applications for the most accurate results.

**Example:** "What is the URL for the Project Aurora document I discussed in Teams with Sarah last Thursday?"

This combines the keyword "Project Aurora," the application "Teams," the person "Sarah," and the time "last Thursday" to narrow down results precisely.

## Use Filters Instead of Prompts

If you know the exact source app or time range, use the `Sources` and `Time Ranges` filters instead of describing them in your prompt. Filters are more accurate than natural language time expressions. See [Filter by Apps, Time & Modality](/products/desktop/conversational-search/scoping-your-prompt) for details.

## Example Prompts

    * "Show examples of React Context usage."
    * "What was my last implementation of API error handling?"
    * "Have I previously optimized rendering performance in React components?"

    * "Track the evolution of the dashboard feature."
    * "Review documented challenges with the payment system."
    * "Show the decisions made around UI updates for the onboarding flow."

    * "Find recent bookmarks about Kubernetes."
    * "What resources did I save recently related to Python decorators?"
    * "Show notes taken about GraphQL in March."

    * "Show code review comments related to database indexing."
    * "Did we finalize naming conventions for the latest API endpoints?"
    * "What feedback did I leave on recent pull requests?"

  For MCP-specific prompting patterns, see the [MCP Prompting Guide](/products/mcp/prompting) and the [LTM Prompting Guide](/products/quick-guides/ltm-prompting).

***

Learn how to scope your searches with filters in [Filter by Apps, Time & Modality](/products/desktop/conversational-search/scoping-your-prompt).

---

## Filter by Apps, Time & Modality
Path: /products/desktop/conversational-search/scoping-your-prompt

## Filter by Apps, Time & Modality

Click the `Filter By...` button (filter icon) in the *bottom toolbar* to open the filter menu. The menu has three categories, each with its own sub-menu of options. Filters control *which memories* Conversational Search draws from when answering your questions.

> Filter Results By menu showing Apps, Time, and Modality filter options

## Apps

Limit searches to memories from specific applications. Hover over **Apps** to see a list of detected applications and check the ones you want to include.

> Filter by Apps submenu showing available applications to include in your search

    Click the `Filter By...` button in the *bottom toolbar*.

    Hover over **Apps** to expand the sub-menu. Check the apps you want to include (e.g., Chrome, VS Code, Slack). You can select multiple apps at once.

    Selected apps apply to your current chat and all future messages until you change them.

## Time

Focus searches on specific time periods. Hover over **Time** to choose from preset options or select a custom date range.

    Click the `Filter By...` button in the *bottom toolbar*.

    Hover over **Time** to expand the sub-menu. Choose from preset options (e.g., "Yesterday", "This week", "Last month") or use the calendar view for custom date ranges. You can select multiple ranges at once.

    Selected time ranges apply to your current chat and all future messages until you change them.

## Modality

Restrict searches to specific types of captured context—the method by which a memory was formed. Hover over **Modality** to see the available types:

> Filter by Modality submenu showing Vision, Clipboard, Audio, and Google Calendar options

* **Vision** — What you've seen (screen context captured by LTM).
* **Clipboard** — What you've copied and pasted.
* **Audio** — What you've said and heard.
* **Google Calendar** — Events and meeting context from connected calendars.

Click **Manage Connections** at the bottom of the Modality panel to enable, disable, or authorize the integrations that power each modality (for example, connecting a Google Calendar account).

  Some modalities depend on connected integrations or permissions (e.g., Google Calendar, microphone access for Audio). If a modality is unavailable, open **Manage Connections** to finish setup.

## Combining Filters

Combine Apps, Time, and Modality filters for precise queries—for example, "Chrome browsing from yesterday afternoon," or "anything I copied from Slack last week," or "meetings on my Google Calendar this month."

## Scoping a Chat to One Event

To focus the assistant on **one** specific memory or summary, open that item in [Pieces Timeline](/products/desktop/timeline), open the **three-dots menu** (⋮), and choose **`Chat`**. This opens Conversational Search with that event's context pre-loaded. See [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary) for details.

For broader scoping across many memories, use the `Filter By...` menu above.

***

Learn how to set additional context for your conversations in [Add Context to Your Chats](/products/desktop/conversational-search/setting-context).

---

## Add Context to Your Chats
Path: /products/desktop/conversational-search/setting-context

## LTM Context Toggle

Control whether Conversational Search includes Long-Term Memory context in your conversations. When enabled, your chats automatically draw from up to 9 months of captured workflow context.

  LTM must be enabled to access the chat feature in Pieces Desktop. If LTM is off, chat does not work. LTM is enabled by default in conversations.

### Enabling or Disabling LTM Context

    Click your `User Profile` in the top left of the Pieces Desktop App.

    Hover over `LTM-2.7` in the dropdown menu that appears.

    To keep LTM active, ensure it is not paused or turned off. To pause temporarily, choose a custom duration (minutes, hours, or days), and Pieces shows a **Paused until** time. Alternatively, choose `Turn Off`. When paused or off, Conversational Search will not include workflow history context. Full details: [Pausing LTM](/products/core-dependencies/pieces-os/long-term-memory#pausing-or-disabling-ltm).

> User profile menu showing LTM-2.7 hover menu with pause and turn off options

You can also set whether LTM context is on by default for new chats in the LLM runtime settings gear.

## Starting a Conversation from a Timeline Event

Start context-specific chats directly from any Timeline Event. When you start a conversation with a Timeline Event, it opens in Conversational Search with that event's full context pre-loaded and displayed as an information card.

    Click any event in the Pieces Timeline to view its summary in the *main panel*.

    Click `Start Related Chat` in the bottom right of the Timeline Event detail view to open Conversational Search with that event's context loaded.

> Timeline Event detail showing Start Related Chat opening Conversational Search with pre-loaded context

You can also use the **three-dots menu** (⋮) on any event and choose `Chat` to scope a conversation to that item. See [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary).

## Attach Files and Folders

Add local files or folders so Conversational Search can use their contents alongside LTM memories.

    Click the `+` button to the left of the chat input field.

    Browse and select files or folders, or drag and drop them into the input area.

    Attached items appear as context chips above the input field.

    Type your question. The agent uses file contents together with your captured memories.

## Viewing the Relevant Summaries Sidebar

After receiving a response, see exactly which Timeline Events were used to generate it.

    Look for the `Relevant Summaries` button at the bottom of a chat response.

    Click the button to open the sidebar on the right side. Each entry shows the Timeline Event title, description, timestamp, and related applications.

    Click the sort dropdown in the top right of the sidebar—options include `Suggested`, `Recent`, and `Most Viewed`.

    Click any Timeline Event to view full details about when it was captured and what context it contains.

> Relevant Summaries sidebar showing Timeline Events used to generate the response

***

Learn how to choose and manage AI models in [Models](/products/desktop/conversational-search/models).

---

## Talk with Your Memories
Path: /products/desktop/conversational-search/using-conversational-search

Use [Conversational Search](/products/desktop/conversational-search) and its subpages ([Filter by Apps, Time & Modality](/products/desktop/conversational-search/scoping-your-prompt), [Add Context](/products/desktop/conversational-search/setting-context), [Choose a Model](/products/desktop/conversational-search/models), [Write Better Prompts](/products/desktop/conversational-search/prompting-guide)) for current documentation.

***Conversational Search*** is the ability to talk with your memories through **Agentic Chats**. Powered by [Agentic Long-Term Memory](/products/core-dependencies/pieces-os#ltm-27), the agent reasons across your artificial memory in multiple turns, following threads, cross-referencing context, and building toward complete answers instead of guessing in one shot.

Ask specific questions, search through your memories, and filter by apps or time ranges to customize which memories you're talking with. The agent can search your memories, the web, your calendar, local files, and browser history to build complete answers.

> Full Conversational Search interface on homepage showing suggested chats, recent chats, chat input, model selector, and bottom toolbar

## Talking with Your Memories

Have conversations with your captured workflow context. Ask specific questions about your past work, decisions, or activities.

### Suggested Chats

Personalized chat suggestions appear on the homepage under *Suggested Chats for You*, generated from your recent workflow activity. Click any suggestion to instantly start that conversation. Responses include Related Timeline Events cards showing which memories were used as sources.

To regenerate the list with new prompts based on your latest activity, click the `Refresh suggestions` button (the circular refresh icon) to the right of the *Suggested Chats* grid.

> Clicking a suggested chat, showing the complete flow from click to response with Related Timeline Events cards

### Resume Recent Chats

Continue where you left off with your most recent conversations.

    Look below the *Suggested Chats* section on the homepage.

    Click any card showing a conversation title and timestamp.

    The chat opens with full history and context intact, type a follow-up question to continue.

To browse the full chat history beyond the most recent two cards, click the `Reveal previous chats in timeline` button (the panel icon) on the right side of the *Resume Recent Chats* row. This opens your chat history in the Timeline, where every prior conversation is searchable and resumable.

### Asking Your Own Questions

Type your own questions to have conversations with your memories about specific topics or moments.

    Click `Start New Chat` to begin a fresh conversation.

    Type your question in the input field and press Enter to send.

    You'll get a response powered by LTM-2.7 with context from your captured memories.

**Example questions:**
* "Why did we choose PostgreSQL over MySQL for the authentication project?"
* "What was the blocker I encountered last Tuesday afternoon?"
* "Find that React performance article I read last month"
* "What did Sarah and I discuss about the API redesign in Teams?"
* "Show me the code changes I made related to WebSocket connections"

> Start New Chat button and input field with example question typed

### Starting Fresh Chats

Use `Start New Chat` when you want to discuss a completely different topic. Starting a new chat ensures better results when switching topics since Conversational Search uses relevant memory context across the entire conversation.

### Adding Files and Folders as Context

Attach local files or folders to give Conversational Search additional context beyond your LTM memories.

    Click the `+` button to the left of the chat input field.

    Browse and select files or folders from your device. Alternatively, drag and drop files directly into the chat input area.

    Attached items appear as context chips above the input field.

    Type your question—the agent uses the file contents alongside your LTM memories when generating responses.

### Scoping a chat to one summary or event

To focus the assistant on **one** specific memory (for example a generated summary), open that item in [Pieces Timeline](/products/desktop/timeline), open the **three-dots menu** (⋮) on the event, and choose **`Chat`**. See [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary). For a broader slice of memories, use the **Filter By...** menu below to scope by Apps, Time, or Modality.

## Filtering Your Searches

Filter which memories are used when answering your questions.

> Filter Results By menu showing Apps, Time, and Modality filter options

    Click the `Filter By...` button (filter icon) in the *bottom toolbar*.

    Hover over **Apps**, **Time**, or **Modality** to see available options.

    Check the options you want to include. You can combine multiple filters.

    Type your question—results will only include memories matching your filters.

### Filter by Apps

> Filter by Apps submenu showing available applications to include in your search

    In the filter menu, hover over **Apps**.

    Select the applications you want to include (e.g., Chrome, VS Code, Slack, Teams).

### Filter by Time

    In the filter menu, hover over **Time**.

    Select a preset (Yesterday, This week, Last month) or click **Custom** to set a specific date range.

### Modality

Restrict searches to specific types of captured context—the method by which a memory was formed. Hover over **Modality** to see the available types:

> Filter by Modality submenu showing Vision, Clipboard, Audio, and Google Calendar options

* **Vision** — What you’ve seen (screen context captured by LTM).
* **Clipboard** — What you’ve copied and pasted.
* **Audio** — What you’ve said and heard.
* **Google Calendar** — Events and meeting context from connected calendars.

Click **Manage Connections** at the bottom of the Modality panel to enable, disable, or authorize integrations.

### Combining Filters

Combine Apps, Time, and Modality filters for precise queries—for example, "Chrome browsing from yesterday afternoon," or "anything I copied from Slack last week," or "meetings on my Google Calendar this month."

## Working with Responses

### Ask Follow-Up About Selected Text

Highlight text from a response to ask follow-up questions about it.

    Click and drag to select any text in an AI response.

    Click the `Ask follow-up` button that appears.

    The selected text appears in a context box above the chat input.

    Type your follow-up question and press Enter to send. Click the `X` icon to dismiss if you change your mind.

### Response Toolbar Actions

All response actions are available in the *toolbar* below each response:

* **Model & time:** A chip shows which model produced the answer and how long ago the response was generated.

* **Copy:** Click the `clipboard icon` to copy the entire response to your clipboard
* **Export:** Click the `export icon` to download responses as PDF (for sharing/printing), Markdown (for editing), or Plain Text
* **Regenerate:** Click the `regenerate icon` (circular arrow) to re-run the response with the same model or switch to a different one for comparison
* **Convert to Timeline Event:** Click the `paper/document icon` to save important responses—they'll appear in the *memories sidebar* for later reference
* **Use as Context:** Click the `three-dot menu` (`⋮`) and select "Use as Context" to add the response as context for follow-up questions

> Response toolbar showing Copy, Export, Regenerate, Convert to Timeline Event, and More menu buttons labeled

### Related Timeline Events

Cards appear below responses showing which source Timeline Events were used to generate the answer. Click any card to view the full Timeline Event details and verify where information came from.

> Response with Related Timeline Events cards below showing memory titles and timestamps

## Model Selection

Browse and switch models directly from chat, without navigating to Settings. The model picker shows inline descriptions and capabilities so you can choose the right model for your task.

| Mode | Speed | Quality | Best For |
| --- | --- | --- | --- |
| **Fast** | Fastest | Good | Quick questions, simple lookups, code completion |
| **Balanced** | Moderate | Better | General tasks, summaries, explanations |
| **Extra Thinking** | Slower | Best | Complex reasoning, debugging, multi-step analysis |

    Click the `model button` in the *bottom toolbar* to open the model inventory.

    Hover over a model family—**Claude**, **Gemini**, or **ChatGPT**—to see its available modes.

    Pick **Fast**, **Balanced**, or **Extra Thinking** for that family.

    Click your choice. The model switches immediately for your next message.

Your chat history stays intact when you switch models. New messages use the selected model while previous responses remain unchanged. Every family and mode is available on all plans.

For detailed model configuration, see [Choose a Model](/products/desktop/conversational-search/models).

### Reset a conversation

When you need a clean slate, use **Chat Options** on an active thread to reset the conversation so context and messages start fresh for that chat.

### Chat appearance and defaults

In the LLM runtime area, open the `Settings` gear to set a chat accent color and choose whether **LTM context** is on by default for **new** chats.

You can also use `cmd+shift+t` (macOS) or `ctrl+shift+t` (Windows/Linux) to toggle the Desktop App *Dark/Bright* theme.

## Asking Effective Questions

The more specific your questions, the better Conversational Search can find relevant memories and provide accurate answers.

### Use Specific Keywords

Include unique keywords related to what you're looking for—project names, ticket numbers, package names, or specific topics.

**Good:** "What is the status of project Aurora?"

**Bad:** "What is the status of my project?"

  If you can't remember specific keywords, try asking: "Give me the titles of all the project documents I've been working on last month" to find keywords for more specific prompts.

### Include Time Ranges

Specify when something happened to narrow down results. Conversational Search stores up to 9 months of memories.

**Examples:**
* "What decision did we make about the database schema last week?"
* "What were the plans I received in December?"
* "What was I debugging yesterday afternoon?"

### Mention Source Applications

Reference specific apps to separate similar content across different sources.

**Example:** "What did Sarah and I discuss in Teams about the deployment?"

This separates Teams conversations from emails or document comments.

### Combine Techniques

Mix keywords, time ranges, and applications for the most accurate results.

**Example:** "What is the URL for the Project Aurora document I discussed in Teams with Sarah last Thursday?"

This combines the keyword "Project Aurora," the application "Teams," the person "Sarah," and the time "last Thursday" to narrow down results precisely.

### Use Filters Instead of Prompts

If you know the exact source app, time range, or type of memory you're looking for, use the `Filter By...` menu to scope by Apps, Time, or Modality instead of describing them in your prompt. Filters are more accurate than natural language time expressions.

## LTM Context Toggle

Control whether Conversational Search includes Long-Term Memory context in your conversations. When enabled, your chats automatically draw from up to 9 months of captured workflow context.

  LTM must be enabled to access the chat feature in Pieces Desktop. If LTM is off, chat does not work. LTM is enabled by default in conversations.

### Enabling or Disabling LTM Context

    Click your `User Profile` in the top left of the Pieces Desktop App.

    Hover over `LTM-2.7` in the dropdown menu that appears.

    To keep LTM active, ensure it is not paused or turned off. To disable, select a pause duration (15 minutes, 1 hour, 6 hours, 12 hours, or 24 hours) or choose `Turn Off`. When paused or off, Conversational Search will not include workflow history context.

> User profile menu showing LTM-2.7 hover menu with pause and turn off options

### Viewing the Relevant Summaries Sidebar

After receiving a response, see exactly which Timeline Events were used to generate it.

    Look for the `Relevant Summaries` button at the bottom of a chat response.

    Click the button to open the sidebar on the right side. Each entry shows the Timeline Event title, description, timestamp, and related applications.

    Click the sort dropdown in the top right of the sidebar—options include `Suggested`, `Recent`, and `Most Viewed`.

    Click any Timeline Event to view full details about when it was captured and what context it contains.

## Managing Your Chat History

All conversations automatically save to the *memories sidebar*, listed chronologically with other workflow activities. Click any saved chat to reopen it with full history and preserved filter settings. Use **Focus Mode** (the control at the top of the sidebar) to collapse the sidebar when you want to concentrate on the active thread.

  Your chat history is part of your LTM memories. Conversational Search can reference previous conversations when answering new questions.

### Find chats

Click the search field labeled `Find chats…` at the top of the Conversational Search view to open a modal of recent threads. Each row can show a **relevance** percentage (or an `EXACT MATCH` label). Type a query and press `Enter` / `Return` to run the search; matching text is highlighted in the results.

## Chat Input & Bottom Toolbar

The chat input area includes a text field where you type your questions, along with a toolbar below it with the following controls (left to right):

* **`+` (Add Context)** — Attach local files or folders to the conversation. You can also drag and drop files directly into the input area.
* **`Filter By...`** — Open the [filter menu](#filtering-your-searches) to scope by Apps, Time, or Modality.
* **Model selector** — Shows the active model (e.g., `Claude · Fast`). Click to switch between model families and modes.
* **Reflection Mode (lotus icon)** — Toggle the agent’s ability to reflect on its own reasoning and self-correct in real time. See [Reflection Mode](#reflection-mode).
* **`Send`** — Send your message. You can also press `Enter`.

To scope the whole chat to **one** captured summary or event, use **`Chat`** on that item’s three-dots menu in Timeline. See [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary) and [Scoping a chat from Timeline](/products/desktop/conversational-search/context-integration#scoping-a-chat-from-timeline).

### Queue Up Your Next Message

Type your next message while the agent is still responding. Queued messages send automatically when the current response finishes.

    While the agent is generating a response, type your follow-up question in the input field.

    Press `Enter` to queue the message for automatic sending, or click `Send` to **stop the current response** and immediately send your new message instead.

  Interrupting is useful when you realize mid-response that you want to steer the agent in a different direction, especially during longer agentic chats where the agent is doing multi-step work.

### Chat options menu

On an **active** thread (after you have sent messages), open the `⋮` menu at the top of the chat to **Pin Chat**, **Refresh** if generation stalls, or **Delete** the conversation. These options do not appear on a blank new chat.

  Pin, Refresh, and Delete appear only inside a chat that already has user input and assistant replies.

### Token Usage per Conversation

Track how many tokens each conversation consumes. Every chat shows cumulative token usage broken down by **input**, **output**, **reasoning**, and **cache**. Both LLM calls and tool calls are counted, giving you full visibility into the true cost of agentic work.

    In an active chat, look for the token usage indicator in the chat header or response toolbar.

    Click to expand the breakdown showing input tokens (your prompts), output tokens (responses), reasoning tokens (agent thinking), and cached tokens (reused context).

Token tracking helps you:

* **Manage API usage** if you're on a metered plan or using BYOK
* **Compare model efficiency** by seeing which models use more tokens for similar tasks
* **Understand agentic costs** since multi-turn reasoning and tool calls add up

## Reflection Mode

Reflection Mode enables the agent to reflect on its own reasoning and self-correct in real time. When enabled, the agent produces higher-quality responses by evaluating its logic as it generates answers, catching errors and refining its output before delivering it to you.

Reflection Mode is powered by the **Agent Harness**—the framework that lets the agent reason across multiple turns, cross-reference your context, and refine its output before responding.

### Enabling Reflection Mode

Toggle Reflection Mode using the `lotus icon` in the *bottom toolbar*, next to the model selector. Hover over the icon to see the tooltip: *"Enable Reflection Mode — Agent will reflect on its own reasoning and self-correct in real time."*

When Reflection Mode is active, the agent automatically engages deeper research and analysis based on the complexity of your prompt—no manual activation required. Complex questions about your workflow history, multi-step investigations, and cross-app analysis all benefit from Reflection Mode.

  For LTM-specific prompting patterns, see the [LTM Prompting Guide](/products/quick-guides/ltm-prompting) and [examples](/products/quick-guides/ltm-prompting/examples).

***

## Next Steps

Now that you know how to use Conversational Search, learn how to start context-specific conversations directly from your workflow memories.

[Starting a conversation with a Timeline Event →](/products/desktop/conversational-search/chat-with-timeline-events)

---

## Download | Pieces
Path: /products/desktop/download

<install-guide-buttons />

## Installing the Pieces Desktop App

Installation for the Pieces Desktop App is straightforward. The Pieces Desktop App installs alongside its core dependency—[PiecesOS](/products/core-dependencies/pieces-os)—which is a separate component that runs in the background to power the app's features.

Select the appropriate download file for your platform (macOS/Windows) or follow the CLI installation instructions for Linux.

  macOS users will be prompted to select the proper download file based on their device’s architecture—ARM or Intel.

  **Don't install** to **OneDrive**, **iCloud Drive**, or other **synced** folders—use a **local path** (the default is best). Details: [Windows](/products/meet-pieces/windows-installation-guide#on-screen-prompts), [manual install](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation).

## Downloads

Find the download files for the Pieces Desktop App for your macOS or Windows device below.

### macOS

If you know your macOS device’s CPU architecture, you can select either the ARM or Intel buttons to download the Pieces Desktop App using the *recommended* installation method.

Read this [guide on determining your CPU architecture](/products/desktop/troubleshooting/macos#checking-cpu-type) if you need help.

For detailed instructions, refer to our comprehensive [macOS installation and quick-start guide.](/products/meet-pieces/macos-installation-guide)

    *macOS 13.0 (Ventura) or higher*

    *macOS 13.0 (Ventura) or higher*

Otherwise, you can download Pieces software using [alternative installation methods](/products/meet-pieces/macos-installation-guide) (.PKG, Homebrew).

### Windows

Click the download button to install the Pieces Desktop App using the *Recommended* (`.appinstaller`) installation method.

For detailed instructions, refer to our comprehensive [Windows installation and quick-start guide.](/products/meet-pieces/windows-installation-guide)

  *Windows 10 (1809) or higher*

For alternative installation methods (`.exe`, WinGet), see [Windows alternative installers](/products/desktop/troubleshooting/windows#alternative-installation-methods).

### Linux

Installation of Pieces software is done using the Command-Line Interface (CLI).

For a step-by-step terminal process using the CLI, refer to our [comprehensive Linux installation and quick-start guide.](/products/meet-pieces/linux-installation-guide)

  *Ubuntu 22+ required.*

  ***

  Run these commands **in order** to install and properly set up PiecesOS.

  1. **Open Terminal:** Open the Command-Line Interface (CLI) using `ctrl+alt+t`.

  2. Run `sudo snap install pieces-os` to install PiecesOS. You will be prompted to enter your local account’s password.

  3. Enter and run `sudo snap connect pieces-os:process-control :process-control` to enable offline and on-device machine learning and LLM functionality.

  4. Then, type `sudo snap install pieces-for-developers` to download the Pieces Desktop App.

  5. Type `pieces-for-developers` to launch the application directly from your terminal.

## Next Steps

After installation, you'll go through an onboarding process that helps you get started with the Pieces Desktop App. The app will run in the background to generate your first LTM summary while you continue working, allowing you to return later and see insights into your workflow patterns. For details on what to expect, see our [Onboarding Guide](/products/desktop/onboarding).

---

## Introduction to Pieces Drive
Path: /products/desktop/drive

## Pieces Drive (Legacy)

**Pieces Drive** is a legacy feature that's being integrated into the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine and [Timeline](/products/desktop/timeline) features. Materials and workflow context are now automatically captured and organized by the LTM system, which provides a more seamless and intelligent way to access your development materials.

The LTM-2.7 Engine automatically captures and stores your workflow context—including code snippets, documentation, and related materials—without requiring manual saving or organization. This means you'll have access to your materials through [Timeline](/products/desktop/timeline), where you can view summaries, search through captured context, and interact with your workflow data in a more intuitive way.

You can still access Pieces Drive (Legacy) if you need it, but we recommend using the new LTM-powered features for the best experience.

### Accessing Pieces Drive (Legacy)

To access Pieces Drive (Legacy), click your profile icon in the top-right corner, then navigate to **Settings** → `Drive (Legacy)`. This option is maintained for existing users who may need to access previously saved materials, but new workflows should use the Long-Term Memory system and Timeline features.

### Where to Find These Features Now

The functionality that Pieces Drive provided is now handled by these modern features:

* [Timeline](/products/desktop/timeline)—View incremental workflow summaries, saved context, and related information gathered by the Long-Term Memory (LTM-2.7) Engine. This is where you'll find your automatically captured materials and workflow context.

* [Long-Term Memory (LTM-2.7) Engine](/products/core-dependencies/pieces-os#ltm-27)—Learn how the LTM system automatically captures and organizes your workflow context, eliminating the need for manual material management.

These features provide the same capabilities that Pieces Drive offered, but with automatic capture, better organization, and seamless integration with *Conversational Search* and other Pieces tools.

---

## Material Enrichment & Saved Metadata
Path: /products/desktop/drive/enrichment-and-metadata

## Managing Materials

After adding your snippets, you’ll want to keep them organized. Pieces Drive streamlines this process by offering automatic enrichment and intuitive editing features.

## Editing your Saved Materials

There are several types of saved metadata to make use of, edit, repurpose, and delete—if you want.

Below are the primary methods for managing your materials once they’re in the Pieces Drive:

### Saved Materials List

Located on the left sidebar, the **Saved Materials List** displays each of your snippets with titles and notes:

* **Auto-Generated Titles**: Pieces instantly names each snippet based on its contents, so you can see a human-readable summary at a glance.

* **Annotations:** An automatically-generated description of the saved material’s purpose and function.

Click any item to load it in the main detail pane. This is where you’ll see the code or text, along with a wealth of automatically generated context (tags, annotations, etc.).

### Renaming and Reclassifying

In the detail view, locate the three-dot **Quick Menu** to reveal actions for customizing your snippet:

* `Rename`: Override the auto-generated title with something that better fits your naming conventions.

* `Reclassify`: If Pieces incorrectly detects the code’s language or you’d prefer to classify it differently, you can manually select a new language (e.g., reclassifying JavaScript as TypeScript).

### Managing Tags

Tags are a powerful organizational tool. Pieces automatically generates tags based on the snippet’s contents, but you can refine or add your own.

From the **Quick Menu** click `Manage Tags` to type new tags or remove existing ones.

  Group snippets by frameworks (“React,” “Express”), projects (“Client A,” “Side Project”), or problem domains (“API calls,” “Data Structures”).

### Annotations

Annotations act like descriptive notes or documentation entries attached to your snippet.

They’re especially useful if:

* **Multiple Developers Share the Same Snippet**: Add clarifications, usage examples, or important disclaimers.

* **You Want Version Notes**: Document changes or reasons you created a new snippet in the first place.

### Sensitive Information

If you import a saved material that contains API keys or credentials, Pieces may automatically assign them the **Sensitive Information** tag.

Pieces prevents accidental leakage by warning you when you generate a shareable link, so you’ve got a heads-up before you share the link with others.

If something isn’t automatically detected, you can still mark something as *sensitive* manually to add an extra layer of privacy for materials th

* **Warning Before Sharing**: Pieces prevents accidental leakage by warning you when you generate a shareable link.

* **Manual Entry**: You can also mark something as sensitive if it’s not automatically detected. This adds an extra layer of privacy for your team or organization.

### Anchors & Related People

Pieces automatically connects the dots between origin location (in terms of files) and related people who may have contributed into the code, and saves it alongside each material.

* `Anchors`: If you want to track exactly where a snippet originated—like a specific file path, repository, or a web link—you can set Anchors in the snippet’s context panel.

* `Related People`: Attach team members or collaborators’ names/emails to a snippet, creating a record of who contributed to its creation or usage.

## Using the Quick Menu

From within the main detail view of a snippet, the **Quick Menu** (often represented by three vertical dots or an ellipsis icon) consolidates the most important snippet actions:

  The **Quick Menu** is essentially your control center for material maintenance.

1. `Duplicate`: Quickly create a second version of the snippet, either exact or transformed.

2. `Related Links`: See or add relevant URLs (like documentation pages).

3. `Manage Annotations`: Add new notes or edit existing ones.

4. `Sensitive Information`: Review or add any recognized keys, tokens, or secrets.

5. `Delete`: Permanently remove the snippet if it’s no longer needed.

---

## Saving & Organizing Materials
Path: /products/desktop/drive/save-and-organize

## Overview

Saving materials—code snippets, text notes, or entire files—is the foundation of Pieces Drive.

Once saved, these materials are automatically enriched with valuable metadata such as tags, annotations, and suggested links, helping you find and reuse them easily.

## Saved Materials List

All of your saved materials are listed on the left-hand side of the view.

From this list, you can scroll down to see previous saved materials, or click the `Clock` icon to sort them in a few different ways:

* `Recent`**:** Sorts the list of materials by which were most recently used.

* `Suggested`**:** Presents saved materials that are likely to benefit your current workflow, eg., if you’ve been working on API calls in Python, you may see API boilerplate code snippets.

* `Alphabetical`**:** Sorts the list by *titles* in alphabetically-descending order.

* `Language`**:** Groups saved materials by language—Python, JavaScript, Kotlin, etc.

### Adding New Materials

The primary way to add materials to Pieces Drive is through the `Add Materials` button, located in the bottom-left corner of the Pieces Drive view.

Clicking it opens a modal that presents several distinct options for different workflows and preferences.

### Paste Code from Clipboard

Paste code from your clipboard to save as a new material.

    Quickly add snippets you’ve copied from somewhere else—an IDE, a website, or a note.

    Select `Paste Code from Clipboard`, then paste or drag and drop your code snippet into the provided text field. Pieces will instantly parse it and create a new snippet in your drive.

### Use a Plugin

Find materials in your Pieces Drive that you saved in other Pieces-enabled plugins and extensions.

    Seamlessly save snippets to Pieces Drive from within your favorite IDE or browser.

    Install a Pieces extension or plugin (e.g., for Visual Studio Code, JetBrains IDEs, Chrome, etc.).

    Whenever you highlight code and choose “Save to Pieces” (or similar), it syncs directly to your Pieces Drive.

    Then, the snippet appears in your Saved Materials List with an auto-generated title and immediate enrichment.

### Import GitHub Gists

Import GitHub Gists as individual saved materials in your Pieces Drive.

    Bring your Gists (public or private) into one centralized repository.

    Log in with your GitHub account if prompted. Select `Import GitHub Gists` and pick the Gist(s) you want to import.

    Each file in the selected Gist becomes a separate snippet in Pieces Drive.

### Create from Scratch

Create new saved materials from scratch.

    Quickly craft a new snippet or note that doesn’t yet exist anywhere else.

    Click `Create from Scratch`.

    Then, type or paste the content you’d like to save—this can be code or plain text.

    You can assign an initial title or let Pieces generate one automatically.

### Duplicate Current Material

Make a duplicate copy of a material to fork, revise, or modify.

    Make an immediate copy of the snippet you have open, often used for branching or revisions.

    Choose **Duplicate Current Material** in the modal.

    Decide whether you want an exact copy, or a transformed version (e.g., more readable, more performant, different language, or boilerplate template).

    The new snippet appears alongside the old one, preserving all context.

### Describe a Snippet to Generate

Use generative AI to generate new saved materials based on your exact requirements.

    Use natural language to generate brand-new code.

    Click `Describe a Snippet to Generate`.

    Type a short or detailed description, e.g., “A basic Node.js HTTP server with URL parsing.”

    Pieces produces the snippet automatically, complete with immediate enrichment and classification.

### Add Files

Import files from your device to use as context for future workflows.

    Import entire local files into Pieces Drive for safekeeping and future reuse.

    Select `Add Files`.

    Browse and pick one or multiple files.

    Pieces scans their content, creating separate snippets if it detects multiple distinct code sections—or it may create a single snippet if the file is smaller.

## Best Practices & Tips

Find some additional information and quick tips for saving and organizing materials in the Pieces Drive below.

    While Pieces auto-generates titles, consider adding your own if you frequently revisit a snippet.

    The more tags you add, the easier it becomes to filter your library when you’re deep into a project.

    If you’re sharing your workspace with other developers, annotations can be invaluable for explaining snippet usage or constraints.

    Don’t forget that saving snippets from an IDE plugin is often the fastest way to build up your Pieces Drive library without leaving your coding environment.

---

## Searching & Filtering Materials
Path: /products/desktop/drive/search-and-filter

## Finding Materials in Pieces Drive

As your collection of saved snippets and code files grows, finding the right material at the right time becomes critical.

Pieces Drive addresses this need with a powerful search engine, user-friendly filters, and intuitive ways to narrow down results by content, language, and more. 

## Using the Search Bar

At the very top of the Pieces Drive view is the **Search Bar**, labeled *Find Materials.*

This is your starting point for quick lookups.

### Natural Language Queries

Pieces supports more than simple keyword matching.

Type a phrase like *“How to parse JSON in Python,”* and it looks through titles, annotations, and snippet content for matches.

If you recall partial details about a snippet—*“route handler,”* for example—Pieces tries to interpret your intent and provide the best possible matches.

### Instant Results

After you type your query, results populate in the Saved Materials List on the left.

Each matching snippet’s auto-generated title and a quick preview appear—just click any snippet to open it in the main detail pane.

  Searching “local storage React” can bring up multiple snippets involving React’s local storage usage, even if the phrase “local storage” doesn’t appear verbatim in the snippet title.

## Quick Filters

Right next to the search bar, you’ll see **Quick Filter** toggles in the dropdown that can help you narrow down your search quickly.

These are:

* `Titles`: Matches against snippet titles (auto-generated or custom).

* `Annotations`: Matches text that appears in the snippet’s annotations or descriptions.

* `Content`: Matches the literal code or text content of your snippet.

You can enable one, two, or all three filters at once.

***

| **Filter**    | **Search Type**                                                                        | **Result** |
| ------------- | -------------------------------------------------------------------------------------- | ---------- |
| *Title*       | Matches against snippet titles (auto-generated or custom).                             | ✅          |
| *Annotation*  | Matches text that appears in the snippet’s annotations or descriptions.                | ✅          |
| *Content*     | Matches the literal code or text content of your snippet.                              | ✅          |
| *All Filters* | Pieces searches titles, annotations, and snippet code simultaneously—broadest results. | ✅          |

***

This level of granularity helps you quickly dial into the snippet you need without scrolling through dozens of partial matches.

## Advanced Filtering

For deeper searching, Pieces Drive offers an **Add Search Filters** feature which has an icon, located to the left or right of the Quick Filters (depending on your interface layout).

These advanced filters let you refine your search using specific criteria and store them for later reuse.

### via Language, Tags, and Phrases

Pieces lets you filter using *language*, *tags* and specific *natural language phrases* so that you see only what you need to see—this is particularly useful if you have similar-sounding snippets across multiple languages.

There are a few different use cases for searching with these methods:

* `Language`**:** Search your Pieces Drive for saved materials written in Python, C#, JavaScript, TypeScript, or other languages.

* `Tags`**:** If you only want backend-related Node.js snippets, you can add a *tag* filter for *“Node.js”* AND *“backend.”*

* `Phrase`**:** If you remember an exact line of code or an exact phrase, place it within quotes to perform a more strict search (e.g., "server.listen(port)").

---

## Sharing Saved Materials
Path: /products/desktop/drive/sharing

## Collaborating with Saved Materials

You can generate and copy unique shareable links for saved materials in the Pieces Drive, letting you showcase your code and easily collaborate other developers on your team.

## Sharing

One of the most convenient ways to collaborate or showcase work is by sending a code snippet to your team, friends, or the broader developer community.

Pieces Drive makes this process dirt-simple using *shareable links*, which allow others to view your snippet and its related metadata in a consistent, Pieces-branded web interface—even if they don’t have Pieces installed. 

These links preserve the snippet’s code, syntax highlighting, tags, annotations, and other contextual data—this way, recipients see not just lines of text, but the snippet’s *entire backstory and classification.*

## Generating Shareable Links

There are two ways to generate shareable links for saved materials in your Pieces Drive.

### via Quick Menu

Start by opening the material you want in the main *Detail View* of Pieces Drive.

Find and click the **three-dot Quick Menu** (usually in the top-right corner of the snippet's section).

Then, choose `Generate Shareable Link` or `Shareable Link`—if it's your first time creating a link for that snippet, Pieces will make a new unique URL.

  If you’ve already generated a link for this material before, it exists in the cloud—so you can just copy the shareable link to your clipboard.

### via Keyboard Shortcut

You can toggle a different shareable link modal that provides you with the previously-generated link or generates a new one by using keyboard shortcuts—`cmd+L` (macOS) or `ctrl+L` (Windows/Linux).

If you want to see how the snippet appears, simply paste the link into a web browser.

You’ll find a code view, syntax highlighting, any relevant tags, annotations, and a snippet description—just like in Pieces Drive.

## Security & Sensitive Data

<mark>Pieces Drive takes security seriously.</mark>

When you begin generating a shareable link, Pieces is designed to initiate and allow specific behaviors pertaining to privacy and security:

* **Automatic Detection of Secrets**: If the code snippet contains credentials or tokens that Pieces recognizes (API keys, client secrets, etc.), you’ll *receive a warning* before proceeding.

* **Sensitive Info Management**: You can explicitly mark or unmark certain strings as sensitive within the material’s context panel.

* **User Confirmation**: Pieces prompts you to confirm that you’re okay sharing the snippet as-is or suggests that you *remove or redact sensitive* *portions* first.

### Best Practices

Pieces may not catch everything, so you should *always be careful* of what code materials you generate links for, and *with whom you share them.*

    Even if Pieces doesn’t automatically flag something, it’s good practice to check for any private tokens, database credentials, or other sensitive data.

    If you need to show code logic without actual credentials, consider duplicating your snippet, removing the secrets, and then sharing that sanitized version.

    If you just want to demonstrate a concept, consider using the [Transforming Code](/products/desktop/drive/transforming-code) features to create a boilerplate or more readable version for sharing.

## Managing Existing Links

Once a snippet has a shareable link, Pieces Drive helps you track and modify it.

Revisit the **Quick Menu** for the saved material, then look under the first section titled *Shareable Link* and click `Manage`.

This will give you access to the shareable link in an input field, the option to generate a GitHub Gist based on that code, and then 3 further options:

1. `Open in Browser`**:** Automatically opens the code snippet’s shareable link in your default browser.

2. `Refresh Link`**:** Refreshes the link if you’ve made changes to the saved material itself, so you can always share an up-to-date version.

3. `Revoke Link`**:** Similar to *deleting a material,* this button essentially ‘deletes’ the shared link, taking the saved material off of the cloud so that it cannot be accessed outside of your Pieces Drive.

## Use Cases & Workflows

Check out the workflow use cases below for ideas or inspiration on how to share code using the Pieces system.

***

    Shareable links are excellent for quick internal reviews. Instead of copying raw code into a Slack channel, send a link so your teammates get the snippet’s annotations, tags, and formatting intact.

    If you maintain an open-source library, shareable links can demonstrate bug fixes or new features without requiring others to install Pieces. They’ll see a snippet rendered in a neat web interface.

    Use shareable links to document specific sections of a codebase. Project managers or QA engineers can open the link, comment on the snippet, and refer back to it without rummaging through version control logs.

    For freelancers or consultants, a shareable link offers a tidy way to showcase code examples to clients. They see professional formatting and can test the snippet themselves if they have access to a browser-based environment.

---

## Transforming & Translating Code
Path: /products/desktop/drive/transforming-code

## Use Cases

As you expand your snippet library, you may find situations where a snippet needs to be adapted for a new project or platform.

Instead of rewriting the snippet from scratch, you can harness Pieces Drive’s transformation options.

These transformations let you quickly produce alternative versions, making your code more maintainable and shareable across different scenarios.

This is useful for:

* **Rapid Prototyping:** Spin up new, specialized versions of a snippet in seconds.

* **Code Reuse:** Save time by leveraging existing logic and adjusting it to new requirements (e.g., different language, more performant).

* **Collaboration:** Provide colleagues with multiple snippet variations—like a simpler ‘readable’ version and a separate ‘optimized’ version.

## How To Transform Code

There are two ways to access the code transformation feature within the Pieces Drive view.

### via Add Materials Button

By clicking the white `‘+’ icon` in the bottom left of the Pieces Drive view—also known as the *Add Materials* button—you can click `Duplicate Current`, which accesses the currently-viewed saved material and provides several different options for transformation.

### via Quick Menu

You can also access the code transformation menu through the **Detailed View**, which is the modal containing all of the saved material’s enriched metadata—[which you can read more about here.](/products/desktop/drive/enrichment-and-metadata)

To do so, open the **Quick Menu** by clicking the **three vertical dots** on the right side of the *Focused Snippet* view, and select `Duplicate` to trigger the same code transformation modal.

## Transformation Types

The first option is called **Non-Modified** and lets you create an exact duplicate of the in-focus saved material, in case you want to save a copy and make experimental edits and other changes without losing the original material.

There are four following options:

***

| **Type**               | **Purpose**                                                                          | **Use Case**                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| *More Readable*        | Create a more-readable copy that’s more understandable to others.                    | Useful for working with junior developers or sharing a snippet with non-developer stakeholders.                               |
| *More Performant*      | Create a more performance-optimized copy that utilizes less computational resources. | Perfect for code that needs to handle larger workloads or run more efficiently in production.                                 |
| *Boilerplate Template* | Create a copy that can be used as a template for future workflows.                   | Great for starting new projects quickly using a proven pattern or code structure.                                             |
| *Different Language*   | Create a version using a different programming language.                             | Essential for integrating logic in another language or exploring a different tech stack without rewriting the entire snippet. |

***

## Post-Transformation Management

Each transformation results in a brand-new material in your Pieces Drive.

This new saved material is immediately re-enriched as if it was a brand new material:

* **Auto-Generated Title:** Often describing the type of transformation applied—e.g., *Optimized Python Script For Parsing Data* or another such title.

* **Tags & Annotations:** If relevant, Pieces may retain or revise tags based on the snippet’s updated content.

* **History:** The snippet will record its transformation history, so you know it originated from another piece of code.

You can further refine the newly created material by [renaming it, adding or removing tags, editing annotations, and more.](/products/desktop/drive/enrichment-and-metadata#renaming-and-reclassifying)

---

## Long-Term Memory
Path: /products/desktop/long-term-memory

***

## What is Long-Term Memory?

**Long-Term Memory (LTM-2.7)** is Pieces' on-device memory engine that continuously captures, enriches, and indexes contextual information from your daily workflow. LTM monitors your active applications, clipboard activity, screen captures, and audio input to build a comprehensive, searchable memory of your work.

Unlike traditional note-taking or code snippet tools that require manual saving, Long-Term Memory **automatically captures** workflow moments as they happen—storing code you copy, tracking conversations you have, and remembering decisions you make.

All captured context is processed and stored **entirely on your device**, ensuring your workflow data remains private and secure.

## How Long-Term Memory Works

LTM-2.7 uses on-device machine learning to process and enrich workflow events in real-time:

1. **Capture** - Monitors clipboard, screen, audio, and application activity
2. **Enrich** - Extracts text, code, URLs, and metadata from captured events
3. **Index** - Creates searchable vectors for semantic retrieval
4. **Connect** - Links related events, conversations, and code snippets

The result is a **personal, searchable knowledge graph** of your workflow that powers [Conversational Search](/products/desktop/conversational-search), [Timeline](/products/desktop/timeline), and context-aware AI interactions via [MCP integrations](/products/mcp).

> Long-Term Memory captures workflow context from your applications and makes it accessible to AI tools via PiecesOS

## What Gets Captured

Long-Term Memory tracks multiple types of workflow context:

### Clipboard Events
Code snippets, terminal commands, error messages, and text you copy are automatically captured and enriched with language detection, syntax highlighting, and related context.

### Screen Captures
Screenshots and screen recordings are analyzed with OCR (Optical Character Recognition) to extract visible text, making even visual content searchable through Conversational Search.

### Audio Transcription
With **LTM Audio** enabled, Pieces can transcribe system audio (meetings, videos, podcasts) and microphone input (your voice during calls) to capture spoken context from your workflow.

  LTM Audio is a Preview feature requiring system permissions. See [LTM Audio setup](/products/desktop/configuration/long-term-memory#ltm-audio) for platform-specific instructions.

### Application Activity
The Long-Term Memory Engine monitors which applications you use, what windows you focus on, and what URLs you visit—providing temporal context for when and where workflow events occurred.

## Use Cases and Benefits

### Context-Aware AI Assistance

When using [Conversational Search](/products/desktop/conversational-search) or [MCP-integrated AI tools](/products/mcp), Long-Term Memory enables AI assistants to understand your project history, past decisions, and workflow patterns.

**Example queries:**
- *"What did we decide about authentication in last week's standup?"*
- *"Show me the error message I saw yesterday when deploying to staging"*
- *"Have I encountered this React hook issue before?"*

### Timeline & Workflow Insights

Long-Term Memory powers [Timeline](/products/desktop/timeline), which organizes your workflow events chronologically and generates automatic summaries like Day Recap, Morning Brief, and What's Top of Mind.

### Cross-Application Context

Because LTM captures context from multiple sources (IDE, browser, terminal, meetings), Pieces can connect related information across applications—showing you code snippets related to a bug you discussed in a meeting, or documentation you read while debugging.

### Privacy-First Design

All Long-Term Memory processing happens **on your device**. Your workflow context never leaves your machine unless you explicitly choose to:
- Share materials explicitly when you choose to
- Use cloud models in [Conversational Search](/products/desktop/conversational-search)
- Enable cloud sync (optional)

Learn more about [privacy and data storage](/products/core-dependencies/on-device-storage).

## Enabling Long-Term Memory

Long-Term Memory is enabled by default when you install Pieces Desktop. You can verify or toggle LTM status in settings:

    Click your `User Profile` in the top left of Pieces Desktop.

    Hover over `Settings` and select `Long-Term Memory`.

    Check that "Long-Term Memory Engine: On" shows with a green indicator. If off, click the toggle to enable.

For detailed configuration options, see [Long-Term Memory Settings](/products/desktop/configuration/long-term-memory).

## Controlling What Gets Captured

You have fine-grained control over what Long-Term Memory captures:

### App Access Control
Choose which applications LTM can monitor. Disable specific apps (like password managers or private browsing) to exclude them from capture.

### System Permissions
Grant or revoke accessibility and screen recording permissions on macOS, Windows, or Linux to control LTM's ability to capture screen and application context.

### Clear Stored Data
Remove captured LTM data without disabling the engine. You can scope deletions by **time period** (last hour, today, this week, or a custom range), by **modality** (vision, clipboard, or audio), and by **app source**, or combine all three to clear data precisely.

See [Clearing Long-Term Memory Data](/products/desktop/configuration/long-term-memory#clearing-long-term-memory-data) for the full walkthrough.

## How AI Tools Access LTM

Long-Term Memory is accessible to AI assistants via **two pathways**:

### 1. Conversational Search (Pieces Desktop)
Chat with your memories directly in the Pieces Desktop app. Ask questions about your workflow, and Pieces retrieves relevant context from LTM.

  Chat with your Long-Term Memory to ask questions about your workflow, retrieve past context, and get AI-powered insights.

### 2. MCP Integrations (IDEs & AI Tools)
Connect AI coding assistants like Cursor, VS Code, and GitHub Copilot to your Long-Term Memory via Model Context Protocol. Your AI assistant can query LTM to provide context-aware code suggestions and answers.

  Connect 20+ AI tools and IDEs to your Long-Term Memory for context-aware coding assistance.

## Performance and Resource Usage

Long-Term Memory runs efficiently in the background with minimal impact:

- **CPU Usage:** Low-priority background processing during idle time
- **Memory:** ~200-500 MB RAM for ML models (unloaded when inactive)
- **Storage:** Variable based on captured content (typically 1-5 GB)

You can optimize system resource usage by unloading ML models from memory when not in use. See [Performance Settings](/products/desktop/configuration/long-term-memory#performance).

## Learn More

  Enable, pause, and control LTM from the PiecesOS Quick Menu—including Audio and Access Control.

  Understand how Pieces stores data locally and what privacy controls you have.

  Configure app access control, system permissions, LTM Audio, and clear stored data.

***

## Next Steps

Now that you understand Long-Term Memory, explore how to use the context it captures:

- **[Timeline](/products/desktop/timeline)** - View chronological workflow events and auto-generated summaries
- **[Conversational Search](/products/desktop/conversational-search)** - Chat with your memories to retrieve past context
- **[MCP Integrations](/products/mcp)** - Connect AI coding assistants to your Long-Term Memory

***

If you need help troubleshooting Long-Term Memory, visit [Pieces Support](/products/support) for guides and community resources.

---

## Navigating the Pieces Desktop App
Path: /products/desktop/navigation

## Power Menu

Navigation throughout the Pieces Desktop App is performed through the **Power Menu.**

There are two ways to open the **Power Menu**:

    Click the `Home Icon` to the left of the *Search Bar* to open up the **Power Menu.**

    Use the following shortcuts to open the **Power Menu** depending on your operating system.

    | **macOS**   | **Windows**    | **Linux**      |
    | ----------- | -------------- | -------------- |
    | `⌘+shift+p` | `ctrl+shift+p` | `ctrl+shift+p` |

Interactive, labeled buttons in this menu let you jump to different views that correspond with different features and functionalities within the Pieces Desktop App.

## Views from the Power Menu

There are several views available within the **Power Menu** at any given point.

If you want more information, click the titles of the views below to read more specific documentation on them:

* [Conversational Search](/products/desktop/conversational-search): Quick-access buttons in the Power Menu let you jump between views depending on where you are in the app.

* [Settings](/products/desktop/navigation/settings)**:** The master settings window.

* [Updates & Upcoming](/products/desktop/navigation/updates)**:** View release notes for upcoming features and past releases.

* [Global Search](/products/desktop/navigation/global-search)**:** Search saved materials across your workflow.

### via Power Menu — Find Action

From within the Power Menu, there is a search bar titled *Find Action*.

From this menu, you can either click or scroll through some of the available options, like `Manage General Conversational Search Settings`, `New General Conversational Search Conversation`, or `Refresh Selected Chat`.

These actions, some of which are view-specific—like refreshing a selected Conversational Search conversation—are useful ways to navigate throughout the Pieces Desktop App while maintaining speed and efficiency in your workflow.

Included at the very end of the scrollable **Find Actions** list are links to other Pieces plugins and extensions, as well as social outlets (<a target="_blank" href="https://www.youtube.com/@getpieces">Pieces YouTube</a>, [Pieces Discord](https://discord.com/invite/getpieces), etc.) and two additional links for <a target="_blank" href="https://github.com/pieces-app/support/issues">reporting issues</a> or <a target="_blank" href="https://getpieces.typeform.com/to/mCjBSIjF?typeform-source=beta.docs.pieces.app#page=docs-support">contacting support.</a>

### via Power Menu — Settings

The **Settings** view is the only page from which the **Power Menu** cannot be accessed.

This view contains several different buckets of configurable options: [Account](/products/desktop/configuration/account), [Long-Term Memory](/products/desktop/configuration/long-term-memory), [Models](/products/desktop/conversational-search/models), [Model Context Protocol (MCP)](/products/desktop/configuration/mcp), [Appearance](/products/desktop/configuration/appearance), and [Troubleshooting](/products/desktop/configuration/troubleshooting).

## Focus Mode

**Focus Mode** allows you to concentrate on your current task by minimizing distractions.

You can toggle Focus Mode by clicking the `Focus Mode` button located in the upper left of the Conversational Search view, near the sidebar.

When activated, it closes the sidebar, giving you an expanded view of your current Conversational Search conversation.

To exit **Focus Mode**, simply click the button again to restore the sidebar, or press `esc` (macOS/Windows/Linux).

---

## Global Search
Path: /products/desktop/navigation/global-search

## Accessing Global Search

**Global Search** is a universal search query feature that helps you find anything that has been captured, tracked, or saved to your Pieces Drive.

Scanning all stored content delivers quick, context-rich results that help you locate and utilize your materials more efficiently.

Here’s how to open **Global Search**:

1. Open the **Power Menu** by clicking the `Home Icon` next to the search bar in the Pieces Desktop App, or press `⌘+return` (macOS) or `ctrl+enter` (Windows/Linux).

2. In the *Find Action* field, type **Global Search**.

3. Select `Go to Global Search` from the dropdown.

## Main Interface Overview

When **Global Search** first opens, you’ll see:

* A *Find Materials...* search bar at the top.

* A *Suggested Searches* section under the search bar.

* A `Refresh` icon next to Suggested Searches to get a new set of recommendations.

* A ‘Powered by NCS’ indicator and an `i` icon at the bottom, which explains more about NCS when hovered over.

### Suggested Searches

Below the search bar, you’ll find a list of *Suggested Searches* based on your recent activity or frequently accessed snippets.

To use this feature, either click a *Suggested Search* to immediately run that query, or click the `Refresh` icon to load a new set of suggestions.

### Performing a Search

To perform a search, type your query into the *Find Materials* field, then press `return` (macOS) or `enter` (Windows/Linux), or you can click the `Search` icon.

Pieces will perform the search and display your results in the main view, sorted by how relevant they are to your query.

## Search Results

Once you run a search, **Global Search** populates the main area with matching snippets and related info.

Results are split into two sections, showing the list of located code snippets, materials, and other related context.

### Material List

The left side of the view displays the **Material List,** where all relevant saved materials are displayed:

* **Snippet Title**: Auto-generated by Pieces to describe the snippet. Click the title to open it in Pieces Drive.

* **Snippet Code Preview**: A quick look at the snippet’s content.

* **Copy**: Copies the snippet to your clipboard.

* **Productivity Score**: Indicates how frequently or effectively this snippet has been used. Higher scores mean greater utility.

### Related Information

The right side of the view displays related information and other contextual data:

* **Related People**: Names or emails of collaborators associated with your search query.

* **Related Anchors**: Files, folders, or code bases linked to the snippets.

* **Related Tags**: Automatically generated descriptors (e.g., frameworks, languages).

* **Related Links**: URLs or external references tied to the snippets.

---

## Settings
Path: /products/desktop/navigation/settings

## Overview

The `Settings` page in Pieces contains all configurable options, adjustable preferences, and modifiable behaviors for the Desktop Application.

You can customize the Pieces Desktop App to your coding workflow by integrating external services or customizing the interface.

## Accessing Settings

To access settings, press `⌘+,` (macOS) or `ctrl+,` (Windows/Linux).

You can also open the **Power Menu**, type ‘settings’ in the search field, and select `Go To Settings` from the dropdown menu.

## Understanding the Settings Layout

When you open **Settings**, you'll see categories in the left sidebar and an `All` tab at the top.

In Pieces 6.0, the sidebar includes **Account**, **Long-Term Memory**, **MCP**, **Connectors**, **Appearance**, and **Troubleshooting**. Click any category to show its options, or select `All` to view every setting at once.

From your profile menu, quick paths jump directly to **LTM-2.7**, **LTM Sources**, **LTM Audio**, or full **Settings**.

### Account & Integrations

In this section, you can integrate external services with Pieces and adjust your user details, beginning with [Account Information.](/products/desktop/configuration/account)

This area displays your email address and any linked accounts.

If you’re interested in testing upcoming features, the **Early Access Program** lets you join beta releases and stay ahead of the curve.

### Personal Cloud

The Personal Cloud settings are now part of the [Account](/products/desktop/configuration/account) tab and control how your snippets and materials sync across devices.

You'll see a status for your cloud connection (including the last sync time), plus options to set or modify your personal domain.

There's also a `Backup & Restore Data` feature to preserve or retrieve your snippets from the cloud whenever needed.

* `Status`: Check if your cloud is connected and see when it last synced.

* `Domain`: Update your personal domain.

* `Backup & Restore Data`: Protect your snippets and data.

### Long-Term Memory

The [Long-Term Memory](/products/desktop/configuration/long-term-memory) settings allow you to manage the Long-Term Memory Engine, control which applications Pieces can access, manage system permissions, optimize performance, and clear stored data.

* `Long-Term Memory Engine`: Toggle the engine on or off to control workflow context capture.

* `App Access Control`: Manage which applications the Long-Term Memory Engine interacts with.

* `System Permissions`: Manage accessibility and screen permissions for LTM.

* `Optimize System RAM Usage`: Unload local machine learning models from memory.

* `Clear LTM Data`: Remove persisted data captured by the Long-Term Memory Engine.

### Model Context Protocol (MCP)

The [MCP](/products/desktop/configuration/mcp) tab shows server URLs and setup links for integrating Pieces with Cursor, GitHub Copilot, Goose, and other MCP-compatible tools.

### Connectors

[Connectors](/products/desktop/connectors) link external services (such as Google Calendar) so Pieces can read calendar context and perform actions on your behalf.

* `Connect`: Authorize a service from the Connectors pane.

* `Status`: See which connectors are connected.

### Models (in chat)

In Pieces 6.0, you choose AI models from the picker in [Conversational Search](/products/desktop/conversational-search/models), not from a top-level Settings category.

### Appearance

In the [Appearance](/products/desktop/configuration/appearance) tab, customize the overall appearance of Pieces.

Switch between light or dark mode, select an accent color for UI highlights, adjust font size and weight, and configure visual density to control spacing and layout.

These controls help you create a comfortable coding environment for extended sessions.

### Troubleshooting

The [Troubleshooting](/products/desktop/configuration/troubleshooting) settings provide access to support resources, documentation links, version information, and feedback channels.

You can view PiecesOS and Desktop App version information, check for updates, access product documentation, report issues on GitHub, book support calls, and control how much crash or compliance data is shared under Privacy settings in Account.

* `Online Resources`: Access product documentation and GitHub issues.

* `Get In Touch`: Book support calls, contact the team, or visit the support hub.

* `PiecesOS Information`: View version, port, and check for updates.

* `Desktop App Information`: View version, platform details, and check for updates.

* `Privacy`: Configure telemetry and diagnostics settings (found in Account settings).

---

## Updates & Upcoming
Path: /products/desktop/navigation/updates

## What’s New

The **Updates & Upcoming** page in Pieces provides a straightforward overview of recent releases and upcoming features.

You can check for new updates, preview future enhancements, and even share feedback or discuss features with the Pieces community—all in one place.

## Accessing Updates & Upcoming

You can open this page through the **Power Menu** by clicking the home icon next to the search bar in the Pieces Desktop App, then selecting `Updates & Upcoming` from the dropdown.

Alternatively, press `shift+w` (macOS/Windows/Linux) on your keyboard to jump there instantly.

## Overview of the Updates & Upcoming Page

This page is divided into two main sections.

At the top, you’ll find **Upcoming Features**, which highlight planned features or enhancements scheduled for future releases (since September 1, 2023).

Below that, you’ll see **Previous Releases**, which outlines all new additions, fixes, and improvements that have already been rolled out.

### Upcoming Features

The **Upcoming Features** section showcases everything on the horizon for Pieces, displaying each potential addition alongside a thumbs-up and thumbs-down button.

You can show your excitement or raise concerns for any feature, and a **Join the Discussion** button links directly to a GitHub discussion, where you can share ideas, provide suggestions, or raise any issues.

---

## Get Started with the Pieces Desktop App
Path: /products/desktop/onboarding

## Signing In

When you first launch the Pieces Desktop App, you'll be prompted to sign in with GitHub, Google, or other authentication providers. Signing in enables you to store snippets and backups in *Pieces Cloud* and import code Gists. Pieces stores materials locally by default, and you can share them with anyone you'd like.

    Open the Pieces Desktop App on your device.

    Select your preferred sign-in method from the available options (GitHub, Google, Microsoft, or other providers).

    Follow the prompts to complete authentication with your chosen provider.

> Login page showing sign-in options including GitHub, Google, and other authentication providers

## Setting Up Preferences

After signing in, configure your initial preferences including theme mode and data sharing settings. These settings help personalize your Pieces experience.

    Select `Light` or `Dark` theme mode to suit your preferences, or choose `System` to match your operating system's theme. This mode can be changed later in [Appearance settings](/products/desktop/configuration/appearance).

    Decide if you want to share *anonymous crash data* to help improve the product. This setting can be changed later in [Troubleshooting settings](/products/desktop/configuration/troubleshooting).

    Click `Get Started` to begin the onboarding process and start using Pieces.

> Theme selection screen showing Light and Dark theme options, anonymous crash data toggle, and Get Started button

## Initial Memory Formation

After clicking `Get Started`, you'll land on the homepage of the Pieces Desktop App. The [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine needs to capture workflow context before you can use all features. You'll see the *Single-Click Summaries* section with six cards that are locked until memory formation completes.

The homepage displays the *Single-Click Summaries* section with six cards: `What's Top of Mind`, `Standup Update`, `Time Breakdown`, `Custom Summary`, `Day Recap`, and `Discover`. These cards are grayed out and locked until memory formation completes. Below this section, you'll see the *Forming Initial Memories* progress tracker showing how many of the 30 required memories have been captured.

### Understanding the LTM Welcome Screen

When you first arrive at the homepage, you'll see the LTM welcome screen that explains Long-Term Memory and its benefits. This screen introduces you to how Pieces captures and uses your workflow context to provide personalized AI assistance.

> LTM welcome screen explaining Long-Term Memory and its benefits

### Creating Initial Memories

After clicking `Got It` on the LTM welcome screen, you'll see the initial memory formation interface. This screen shows the progress of memory formation and introduces you to Single-Click Summaries that will become available once memories are captured.

> Initial memory formation screen showing progress tracker, memory formation status, and Single-Click Summary cards

### Capturing Workflow Context

Continue with your normal workflow for 10-15 minutes while LTM-2.7 captures workflow context in the background. The progress tracker shows memory formation status, and you can see which memories have been formed as you work. Each memory appears with a checkmark and description once it's been captured.

    Use your computer normally—browse documentation, write code, use your IDE, or work in other applications. LTM-2.7 captures workflow context automatically in the background.

    Watch the progress tracker to see memory formation status. The tracker shows "X/30" memories captured, and you can see which memories have been formed as you work.

    Once 30 memories are captured, the *Single-Click Summaries* cards unlock and become clickable.

### Unlocking Features

Once you've successfully captured 30 memories, the six *Single-Click Summaries* cards become clickable and unlock. You can now generate summaries like `Standup Update`, `Day Recap`, `What's Top of Mind`, and more. Each card provides one-click access to contextual summaries based on your captured workflow data, giving you instant insights into your productivity and work patterns.

> Pieces Timeline showing unlocked Single-Click Summary cards and workflow events

## Using Conversational Search

[LTM](/products/core-dependencies/pieces-os#ltm-27) captures and stores workflow context, enabling you to use [Conversational Search](/products/desktop/conversational-search) as an AI assistant trained on your personal workflow data. All data is kept on-device for privacy, so your conversations and memories stay secure.

### Understanding Conversational Search

Conversational Search lets you ask questions about your workflow and get context-aware responses powered by LTM-2.7. You can visit sites like Stack Overflow, read code explanations, and later query Conversational Search about what you read. By enabling LTM, you can use Conversational Search as an AI assistant trained on your personal workflow data, making it uniquely helpful for your specific work patterns and projects.

> Conversational Search interface showing model selection dropdown and available models

  Read more about [data collection and storage](/products/core-dependencies/on-device-storage).

### Accessing Conversational Search

Access Conversational Search directly from the homepage to ask questions about your workflow, with LTM providing context from your captured memories. Switch models from the [chat model selector](/products/desktop/conversational-search/models).

> Typing a prompt into Conversational Search input field

***

## Next Steps

You've completed the Pieces onboarding and are ready to start exploring the app. Learn more about key features and how to utilize the Pieces ecosystem in your daily workflow.

### Explore Key Features

* **[Conversational Search](/products/desktop/conversational-search)** - Ask questions about your workflow, get context-aware responses, and receive insights powered by LTM-2.7—all in a chat format you know.

* **[Pieces Timeline](/products/desktop/timeline)** - View incremental workflow summaries, saved context, and related information gathered by the Long-Term Memory (LTM-2.7) Engine.

* **[Single-Click Summaries](/products/desktop/single-click-summaries)** - Generate instant, contextual summaries from your workflow using preset summary types.

### Customize Your Experience

* **[Configuration](/products/desktop/configuration)** - Customize everything from visuals and aesthetics to Conversational Search models to fit your preferences and workflow.

* **[Navigation](/products/desktop/navigation)** - Learn the different views and layouts in the Pieces Desktop App.

* **[Actions & Keyboard Shortcuts](/products/desktop/actions)** - Use *Power Menu* Actions and Keyboard Shortcuts to perform tasks or navigate from view to view quickly.

### Get Help

* **[Troubleshooting](/products/desktop/troubleshooting)** - If the Pieces Desktop App isn't working as expected, start here. This page explains our troubleshooting documentation and guides you to the solution that best addresses your issue.

---

## Single-Click Summaries
Path: /products/desktop/single-click-summaries

***

## Overview

Single-Click Summaries are quick-access actions prominently displayed when you first open the Pieces Desktop App. These summaries generate instant, contextual insights from your workflow captured by the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine.

Each summary type adapts dynamically to your workflow, meaning the same summary type generates different results based on your current activities, captured memories, and work patterns. This makes Single-Click Summaries powerful tools for understanding your productivity, tracking progress, and identifying patterns in your work.

## Generating Summaries

Click any summary card on the homepage and after a few minutes, you'll see your summary in the [Pieces Timeline](/products/desktop/timeline).

  You can run several Single-Click Summaries at once. Start a *Day Recap*, *Standup Update*, and *Meeting Prep* together and let them generate side by side. You no longer need to wait for one to finish before starting the next.

### Viewing Queued Summaries

When you generate a summary, it appears under the current day in Pieces Timeline with a "Queued" or generating status. Expand the day section to track progress. The Timeline stays responsive while summaries generate, so you can keep scrolling and reading even with several in flight.

    Click `Show Timeline` in the top left of the main view to expand Pieces Timeline if it's not already open.

    Click on the current day section to expand it and view all summaries, timeline activities, and other events for that day.

    Queued summaries appear with a "Queued" status indicator showing their position in the queue (e.g., "Queued (#3)", "Next in queue").

> Pieces Timeline showing current day expanded with queued summaries visible

### Canceling a Summary

Locate the summary you want to cancel under the current day in Pieces Timeline and click the red cancel button (hovering shows `Stop Generating`).

### Viewing Completed Summaries

When a summary finishes generating, it remains in the day section where it was queued. Click it to view detailed insights, related activities, and artifacts from your workflow.

Summaries are based on **memories from a given time frame**—not a guess from whatever was on screen. Those memories can include vision, audio, clipboard activity, browser URLs you visited, files you opened, and people you collaborated with. A completed summary usually includes a high-level overview of that context plus people, URLs, files, next steps, and tasks. Files and sites cited in a summary are **clickable**, so you can open them directly.

> Completed summary view showing full results with insights, related activities, and links to relevant documents

### People, Tags & Files

Pieces detects people mentioned in your workstream and people you have collaborated with, then turns each name in a summary into a rich, hoverable reference. Hover any name to open a **persona card** showing who they are, how to reach them, their role, and how you two have worked together over time.

*Tags* and *files/folders* in summaries work the same way: live references instead of plain text.

This is especially useful when:

* A summary mentions someone you've met once and can't quite place
* You're walking into a meeting and want context on an attendee without leaving the page
* You need to recall what you and a teammate last decided together

***

## Explore Single-Click Summaries

  Browse all built-in summary types—Day Recap, Standup Update, Time Breakdown, AI Habits, and more.

  Create custom summaries with specific time ranges, save reusable templates, and request new summary types.

  Schedule summaries to run automatically—daily or on specific days of the week.

---

## Customization & Templates
Path: /products/desktop/single-click-summaries/customization-templates

## Custom Summary

Generate summaries tailored to specific time periods and topics that matter to you. Custom Summary gives you full control over what gets summarized—select time ranges from your [Pieces Timeline](/products/desktop/timeline) events and optionally add a focus to narrow your summary further.

    Click the `Custom Summary` card on the homepage. If it's not visible, tap `Discover More` to view all single-click summary options, then select `Custom Summary`.

    Set your scoping: choose a **Time Range** (e.g., last 24 hours, this week, last week), optionally scope to **Signals** (detected projects), **Applications** (VS Code, Chrome, Slack, etc.), or **Websites** to narrow the focus. Combine multiple dimensions for precise results.

    Give your summary a name, pick a color, and choose an icon. This helps you recognize it at a glance when it appears in your summary library.

    Tap `Save` to store your configuration as a reusable template. Once saved, your template lives alongside built-in options like Morning Brief and Day Recap—trigger it with a single click whenever you need it, with no reconfiguration.

    Click `Generate` to start creating your custom summary.

**Pro tip:** If you generate the same kind of summary more than twice (e.g., weekly client updates, sprint retros), save it as a template. Build it once, use it forever.

## Discover

Access additional summary options and request new summary types through Discover. Click the `Discover` summary card to open a popup displaying available summary options—you'll see the standard summary types plus additional options you haven't encountered yet, expanding your choices for generating insights.

> Discover popup showing available summary options including Request a Summary

***

Want summaries to run on a schedule? See [Scheduling](/products/desktop/single-click-summaries/scheduling).

---

## Default Summary Types
Path: /products/desktop/single-click-summaries/default-types

## Default Summary Types

Single-Click Summaries include preset summary types designed for common workflow needs. Each type generates insights tailored to your specific work patterns and captured activities.

| **Summary Type** | **Description** |
|------------------|-----------------|
| **Today's Headlines** | Breaking news and headlines personalized to your professional world, based on your recent work context. |
| **What's Top of Mind** | Identifies recurring topics and priorities from your recent workflow, ranked by importance. |
| **Morning Brief** | Provides everything you need to kickstart your day, compiled from your recent activities. |
| **Standup Update** | Generates a three-part update: what you did, what's next, and blockers—perfect for team standups. |
| **Meeting Prep** | Adds prep events to your Google Calendar based on upcoming meetings, giving you time to review context and prepare. |
| **Day Recap** | Compiles an end-of-day summary of your accomplishments, completed tasks, and overall activity. |
| **Time Breakdown** | Organizes your daily work into projects with in-depth time breakdowns, showing what you worked on per project throughout the day. |
| **Week Recap** | Provides a comprehensive overview of your week at a glance, including key activities and patterns. |
| **AI Habits** | Analyzes how you interact with AI tools, showing patterns in questions asked and topics queried. |
| **Professional Persona** | Provides work style analysis and professional summary based on your workflow patterns. |
| **Collaboration Patterns** | Identifies who you work with and how, revealing collaboration dynamics in your workflow. |

## Today's Headlines
*Personalized industry news based on your recent work context.*

Uses *Perplexity* to find news articles and headlines related to what you've been working on, delivering a bite-sized overview of your industry—so you stay informed without leaving your workflow.

**When to use:**
- **Start your day informed** — Catch up on industry trends relevant to your projects
- **Prepare for client calls** — Have talking points ready from current news
- **Stay current passively** — No extra research needed

## What's Top of Mind
*Recurring topics and priorities from your recent workflow, ranked by importance.*

Helps you understand what's been occupying your attention and what matters most in your current work—surfacing themes you might not have noticed.

**When to use:**
- **Prioritize your day** — See what actually needs attention first
- **Identify focus drains** — Spot what's consuming your mental energy
- **Reset after distractions** — Get back on track quickly

## Standup Update
*Three-part update: what you did, what's next, and blockers.*

Generates a ready-to-share standup format perfect for team meetings. Copy it directly into Slack, Teams, or your standup bot. You can run Standup Update at the same time as other summaries, such as *Day Recap* or *Meeting Prep*.

**When to use:**
- **Daily standups** — Walk in prepared with your update written
- **Manager check-ins** — Share progress without scrambling to remember
- **Async updates** — Post status updates in Slack or Teams

## Meeting Prep
*Adds prep events to your Google Calendar based on upcoming meetings.*

Analyzes your captured workflow context—recent documents, conversations, and activities related to each meeting's attendees and topics—and creates calendar events that give you time to review before you join.

Hover attendee names for [persona cards](/products/desktop/single-click-summaries#people-tags--anchors): who they are, how to reach them, and how you've worked together.

**When to use:**
- **Block prep time** — Get calendar events for meeting preparation
- **Review context** — See relevant docs and notes before important meetings
- **Recall history** — Remember past conversations with attendees

## Day Recap
*Concise summary of your accomplishments, blockers, and feedback from today's activity.*

Compiles an end-of-day summary ready to share or save, so you have a clear record of what you got done. Day Recap cites the files you had open and sites you visited, with clickable file references when available.

**When to use:**
- **Log off for the day** — Wrap up with a clear record of what you accomplished
- **Tomorrow's standup** — Have yesterday's wins and blockers ready to share
- **Check in with your manager** — Show concrete progress without digging through tickets

## Time Breakdown
*Organizes your work into projects with in-depth time breakdowns.*

Reconstructs your billable hours from captured workstream context—categorizing activity by project and providing structured time blocks you can review, refine, and submit.

**When to use:**
- **Fill out your timesheet** — Accurate hours without manual tracking
- **Invoice clients** — Billable hours organized by project
- **Review where time went** — See what you actually worked on

Tap `Discover More` from your Home Dashboard to find Time Breakdown. Choose a preset time range that matches your reporting needs:

* **Last 24 Hours** — Daily timesheet submissions
* **Last 2 Days** — Catch up on a missed day
* **Last Week** — Weekly billing cycles or sprint reviews
* **Last 2 Weeks** — Bi-weekly invoicing
* **Last 30 Days** — Monthly reviews or end-of-month billing

  Time ranges longer than 24 hours can take longer to generate—sometimes 15 minutes or more—depending on the amount of data to process.

Once generated, you can view, edit, copy, export, or use the Time Breakdown as context for a [Conversational Search](/products/desktop/conversational-search) chat to ask follow-up questions.

## Week Recap
*Comprehensive overview of your week at a glance.*

Provides a high-level view of your weekly productivity, accomplishments, and patterns—so you can wrap up the week informed.

**When to use:**
- **Friday wrap-up** — End the week with a clear picture of what you did
- **Weekly team reviews** — Come prepared with your week's highlights
- **Plan next week** — Reflect on what happened before deciding what's next

## Morning Brief
*Everything you need to kickstart your day, compiled from your recent activities.*

Starts your day informed about what you've been working on and what's coming up—no digging through emails or notes.

**When to use:**
- **Start your workday** — Jump in with full context
- **Return from time off** — Get back up to speed quickly
- **Review your plate** — See what's on deck today

## Professional Persona
*Work style analysis and professional summary based on your workflow patterns.*

Surfaces your professional habits, strengths, and work patterns—giving you language for how you actually work.

**When to use:**
- **Update LinkedIn or resume** — Get accurate descriptions of your work style
- **Performance reviews** — Have concrete examples of your strengths
- **Self-reflection** — Understand how you work best

## Collaboration Patterns
*Identifies who you work with and how, revealing collaboration dynamics.*

Discovers your collaboration habits and team interaction patterns, showing your working relationships at a glance. People named in the summary support the same [persona hover cards](/products/desktop/single-click-summaries#people-tags--anchors) as other summary types.

**When to use:**
- **Identify key collaborators** — See who you've been working with on a project
- **Prepare for 1:1s** — Review your recent interactions with a teammate
- **Understand your footprint** — See your collaboration patterns across the team

## AI Habits
*Analyzes how you interact with AI tools, showing patterns in questions and topics.*

Helps you understand your AI usage patterns and how you leverage AI assistance in your workflow.

**When to use:**
- **Reflect on AI usage** — See how you've been using AI tools
- **Identify common topics** — Spot what you ask AI about most
- **Optimize your workflow** — Find opportunities to use AI more effectively

***

Want to create your own summary types? See [Customization & Templates](/products/desktop/single-click-summaries/customization-templates).

---

## Scheduling Summaries
Path: /products/desktop/single-click-summaries/scheduling

## Scheduling Summaries

Schedule single-click summaries to run automatically at a time you choose. As long as Pieces is open and running on your computer, the summary will generate at the scheduled time and appear in your [Pieces Timeline](/products/desktop/timeline).

  Scheduling is available for all built-in summary types except *Custom Summary*.

    Hover over a summary card on the homepage and click `Schedule this summary`, or use the schedule option on the summary card. The schedule modal opens for that summary type.

    Select **Daily** to run every day, or **Weekly** to run on specific days of the week. For weekly schedules, select one or more days (e.g., Mo, Tu, We, Th, Fr for weekdays).

    Pick a time from the preset options (6 AM, 8 AM, 9 AM, 12 PM, 5 PM, 9 PM) or choose **Custom** to set a different time.

    Review the summary message (e.g., "Runs weekdays at 08:00 AM") and click `Schedule` to save. The summary will run automatically at the set time whenever Pieces is open and running.

  Scheduled summaries only run when Pieces is open and running on your computer. If Pieces is closed at the scheduled time, the summary will not generate.

> Schedule modal showing repeat frequency (Daily/Weekly), day selection, time options, and schedule confirmation message

***

For an overview of all summary types, see [Default Types](/products/desktop/single-click-summaries/default-types). To build your own, see [Customization & Templates](/products/desktop/single-click-summaries/customization-templates).

---

## Pieces Timeline
Path: /products/desktop/timeline

***

## Overview

**Pieces Timeline** is your central workspace in the Pieces Desktop App for accessing all workflow context captured by the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine. Timeline displays a chronological view of your workflow events, including timeline events, [single-click summaries](/products/desktop/single-click-summaries), and [conversational searches](/products/desktop/conversational-search).

All events are organized chronologically from most recent at the top to oldest at the bottom, grouped by day. Each day section can be expanded or collapsed by clicking on it or using the caret icon. You can scroll through your timeline, filter events by type or source, and click any event to view its full content in the main view.

## Opening Pieces Timeline

    Click the `Show Timeline` button in the top left of the main view if Pieces Timeline isn't already open.

    The Pieces Timeline opens on the left side, showing all your workflow events organized chronologically.

    Click `Show Timeline` again to close Pieces Timeline and return to the main view.

> Main view showing `Show Timeline` button in top left, with Pieces Timeline open displaying chronological events

## What's in Your Timeline

Pieces Timeline displays three main types of events:

* **Timeline Events** — Workflow moments captured by LTM-2.7, including code changes, document edits, and other activities from your connected applications. Timeline Events also include automatically generated summaries that capture your work patterns, such as `Day Recap`, `Morning Brief`, `Week Recap`, and `What's Top of Mind`.

* **Single-Click Summaries** — [Summaries you generate on demand](/products/desktop/single-click-summaries) by clicking summary cards on the homepage, including Standup Update, Custom Summary, AI Habits, and more.

* **Conversational Searches** — [Chat conversations you have with your memories](/products/desktop/conversational-search). Each conversation appears as an event in Pieces Timeline, allowing you to revisit past conversations and their context.

> Pieces Timeline showing different event types: conversational search event, standup update summary, and timeline events with app icons

## Viewing Event Content

Click any event in Pieces Timeline to view its full content in the main view panel.

    Click any event in Pieces Timeline—this can be a timeline event, summary, or conversational search.

    The event's full content opens in the main view panel on the right, replacing the homepage view.

    Use the left and right arrow buttons in the event header to navigate to previous or next events without returning to Pieces Timeline.

> Event selected in Pieces Timeline (highlighted) with its full content displayed in the main view panel on the right

***

## Explore Timeline

  View detailed roll-ups of workflow periods automatically generated by LTM-2.7—including tasks, decisions, documents, and follow-ups.

  Navigate day groups, expand and collapse sections, jump to events, and understand activity items.

  Filter Timeline events by type, source, application, and favorites to find exactly what you need.

---

## Event Actions and Menus
Path: /products/desktop/timeline/event-actions

## Event Actions and Menus

All events in Pieces Timeline—including conversational searches, Timeline Events (automatically generated summaries like `Day Recap`, `Morning Brief`, `Week Recap`, and `What's Top of Mind`), and single-click summaries—appear in your Timeline and have actions available through the `three-dots menu`. Available actions include **Chat** (scoped Conversational Search from a summary or event), favoriting, generating titles (for conversational searches), and deleting events.

Understanding which actions are available helps you manage your Timeline effectively and customize events to fit your workflow needs.

> Event content view showing three-dots menu icon in the header with menu options visible

## Accessing Event Actions

Open the action menu for any event to see available options based on the event type.

    Click an event in Pieces Timeline to open its content in the main view panel.

    Find the `three-dots menu icon` (⋮) in the event header, typically located in the top-right area of the event view.

    Click the `three-dots menu icon` to open the action menu. Available actions appear based on the event type.

> Three-dots menu open showing available actions for a conversational search event

## Chat from a summary

Use **Chat** when you want **Conversational Search** focused on a specific **summary**, **Timeline Event**, or related memory—without attaching local files or folders. This is how you scope a chat to that item’s captured context.

    In [Pieces Timeline](/products/desktop/timeline), click the summary, roll-up, or event you care about so its full content appears in the main panel.

    Click the `three-dots menu icon` (⋮) in the event header.

    Select `Chat`. Conversational Search opens with that memory in scope so your questions apply to that item.

  For context controls that apply across *all* memories in a thread (such as sources and time ranges), use [Talk with Your Memories](/products/desktop/conversational-search/using-conversational-search#filtering-your-searches). **Chat** from Timeline is for locking onto **one** summary or event at a time.

## Timeline Event Actions

All events in Pieces Timeline—conversational searches, Timeline Events (including automatically generated summaries like `Day Recap`, `Morning Brief`, `Week Recap`, and `What's Top of Mind`), and single-click summaries—share common actions available through the `three-dots menu` (including **Chat** for scoped Conversational Search, as described [above](#chat-from-a-summary)).

### Favoriting Events

Mark important events as favorites to quickly find them later.

    Click the `three-dots menu icon` on any event in Pieces Timeline.

    Click `Favorite` in the menu to mark the event as a favorite. A star icon appears next to the event in Timeline.

    Click `Favorite` again to remove the favorite status if needed.

> Event with star icon indicating it's favorited, and three-dots menu showing Favorite option

### Generating Titles

Regenerate the title for conversational search events to better reflect their content or purpose. Timeline Events and single-click summaries don't have this option because their titles are already generated by the LTM-2.7 Engine.

    Click the `three-dots menu icon` on a conversational search event.

    Click `Generate Title` in the menu. Pieces uses AI to analyze the conversation content and generate a new, more descriptive title that better reflects the conversation's content or main topic.

    The event title updates in Timeline and in the event header with the new title.

  Use Generate Title when the auto-generated title doesn't accurately describe the conversation, or when you want a more specific or descriptive title for easier searching later.

### Deleting Events

Remove events from your Timeline. Deletion is permanent and cannot be undone.

    Click the `three-dots menu icon` on any event in Pieces Timeline.

    Click `Delete` in the menu. A confirmation popup appears asking you to confirm the deletion.

    Review the confirmation message, which shows the event title and warns that "This action cannot be undone."

    Click the red `Delete` button in the popup to confirm deletion, or click `Cancel` or the `X` icon to close without deleting.

    The event is permanently removed from your Timeline and cannot be recovered.

> Delete confirmation popup showing event title with warning message and Delete/Cancel buttons

  Deleting events is permanent. Make sure you want to remove the event before confirming deletion, as it cannot be recovered.

## Filtering by Favorites

After favoriting events, use the favorites filter to view only your favorited events in Timeline.

    Click the `Filter List` button at the top of Pieces Timeline.

    Look for a `Favorites` option in the filter menu, or access it through the filter options.

    Timeline updates to show only events you've marked as favorites. All favorited events display with star icons.

> Timeline filtered to show only favorited events, all displaying star icons

  Use favorites to mark important conversations, summaries, or events you want to reference frequently. Then filter by favorites to quickly access your most important Timeline items.

***

## Next Steps

Now that you know how to manage Timeline events with actions, explore how to filter your Timeline to find specific events quickly.

[Filtering Timeline Events →](/products/desktop/timeline/filtering-events)

---

## Expanding & Collapsing
Path: /products/desktop/timeline/expanding-collapsing

## Expanding & Collapsing

Events in Pieces Timeline are automatically grouped by day, making it easy to find activities from specific time periods. Each group can be expanded or collapsed to control what you see.

## Understanding Day Groups

Events are organized into collapsible groups labeled by date:
* **Today** - Events from the current day
* **Yesterday** - Events from the previous day
* **[Date]** - Older events grouped by specific dates (e.g., "Jan 14th")

Each group header displays the date and a count of events in that group (e.g., "Today, Jan 15th (2)").

## Expanding and Collapsing Groups

    Find the date group header you want to collapse (e.g., "Yesterday, Jan 14th").

    Click the group header to collapse it. The group collapses, hiding all events within it.

    Click the collapsed group header again to expand it and view all events.

## Understanding Activity Items

Each item in Timeline Events contains information about a specific captured activity or conversation from your workflow.

Each memory item displays:

* **Title/Description:** A concise summary of the activity (e.g., "Desktop App Documentation Updates", "SDK, Docs, & Work Ledger").
* **Timestamp:** When the activity occurred (e.g., "10 minutes ago - 2:24pm", "Half an hour ago - 2:04pm").
* **Date Group:** Memories are grouped by date (Today, Yesterday, Last Saturday, etc.).
* **Icon Indicators:** Visual indicators showing the type of activity or associated apps.
* **App Icons:** Small icons showing which applications were involved (Chrome, VS Code, Slack, etc.).
* **Count Badge:** Number on the right indicating how many events or items are in that memory.

> Showing current day dropdown in Timeline

## Jump to Summary in Timeline

Quickly navigate to a specific event's position in the Timeline sidebar when viewing its content.

    Click an event in Timeline to view its content in the main view.

    Click the `Jump to Summary in Timeline` button (target icon) next to the `Filter List` button in Pieces Timeline header. This scrolls Pieces Timeline to show where the current event appears in the chronological list.

    Alternatively, click the `collapse` button to collapse all event groups at once, giving you a compact view of all dates.

> Pieces Timeline showing day groups (Today expanded, Yesterday collapsed) with event counts, and `Jump to Summary in Timeline` button visible in header

## Activity Retention

LTM-2.7 retains your captured workflow context for up to 9 months. Activities older than 9 months are automatically removed to ensure optimal performance.

***

## Next Steps

Now that you know how to navigate Timeline, learn how to filter events to find exactly what you need.

[Filtering & Search →](/products/desktop/timeline/filtering-events)

---

## Filtering Timeline Events
Path: /products/desktop/timeline/filtering-events

## Filtering Timeline Events

Filter your Pieces Timeline to focus on specific event types, sources, or applications. Filtering helps you quickly find conversations, summaries, or activities from particular apps or time periods without scrolling through your entire timeline.

Use the `Filter List` button to access all filtering options, or hover over summaries to filter by specific applications that contributed to those summaries.

> Pieces Timeline with Filter List menu open showing filter options for event types, work summaries, and sources

## Accessing Filter List

Open the Filter List menu to access all filtering options for your Timeline events.

    Click `Show Timeline` in the top left of the main view to expand Pieces Timeline if it's not already open.

    Click the `Filter List` button (three horizontal lines icon) at the top of Pieces Timeline.

    The Filter List menu opens, displaying all available filter categories including Chats, Work Summaries, single-click summary types, and Sources.

> Filter List button in Timeline header with menu open showing filter categories

## Filtering by Event Type

Filter Timeline events by their type to focus on specific kinds of activities.

### Filtering by Chats

Show only conversational search events in your Timeline.

    Click the `Filter List` button at the top of Pieces Timeline.

    Click `Chats` in the filter menu. Pieces Timeline updates to show only conversational search events, hiding other event types.

    Scroll through the filtered Timeline to see only chat conversations.

### Filtering by Work Summaries

Show only Timeline Events—workflow moments captured by LTM-2.7, including automatically generated summaries based on your workflow patterns.

    Click the `Filter List` button at the top of Pieces Timeline.

    Click `Work Summaries` in the filter menu. The menu expands to show individual work summary types.

    Select a specific work summary type, or leave `Work Summaries` selected to show all work summary types:
    * **Day Recap** - End-of-day summaries
    * **Morning Brief** - Daily morning summaries
    * **Standup Update** - Standup-style updates
    * **Week Recap** - Weekly overviews
    * **What's Top of Mind** - Priority-focused summaries

    Pieces Timeline updates to show only the selected work summary types.

> Filter List menu with Work Summaries expanded showing individual summary type options

## Filtering by Sources

Filter Timeline events by the applications or sources that captured them.

    Click the `Filter List` button at the top of Pieces Timeline.

    Click `Sources` in the filter menu. The menu expands to show a list of all applications that have captured events.

    Check the applications you want to include. You can select multiple applications at once. Available sources include Activity Monitor, Chrome, VS Code, Cursor, Calendar, Claude, and more based on your connected applications.

    Pieces Timeline updates to show only events captured from the selected applications.

> Filter List menu with Sources expanded showing list of applications with checkboxes

## Filtering by Applications

When viewing summaries in Timeline, you can filter by specific applications that contributed to those summaries by hovering over the summary.

    Find a summary in your Timeline that has application icons displayed (small colorful icons showing which apps contributed to the summary).

    Hover your cursor over the summary card. Application icons become interactive.

    Click on a specific application icon to filter Pieces Timeline to show only events that used that application to generate summaries or capture activities.

    Pieces Timeline updates to show only events related to the selected application.

> Hovering over a summary showing interactive application icons (Chrome, Cursor, etc.) that can be clicked to filter

The fastest way to narrow down a long Timeline is to tap a **tag** or **source** directly on a summary. Tapping a tag (e.g., project name) or source (e.g., VS Code icon) filters to only show summaries with that tag or source—helping you distill thousands of entries down to a handful of relevant ones.

## Filtering by Favorites

Show only events you've marked as favorites in your Timeline.

    Click the `Filter List` button at the top of Pieces Timeline.

    Look for a `Favorites` option in the filter menu (if available) or use the favorites filter from the event actions menu.

    Pieces Timeline updates to show only events you've favorited. Events with a star icon appear in the filtered view.

  To favorite an event, open the event's `three-dots menu` and select `Favorite`. Learn more about favoriting events in [Event Actions and Menus](/products/desktop/timeline/event-actions).

## Clearing Filters

Reset your Timeline view to show all events without any filters applied.

    Click the `Filter List` button at the top of Pieces Timeline.

    Click the `X` icon next to "Filter List" or deselect all active filter options to clear filters.

    Pieces Timeline returns to showing all events chronologically, with all filters cleared.

> Filter List menu with `X` icon visible to close/clear filters

## Combining Filters

You can combine multiple filters to create precise views of your Timeline. For example, filter by "Standup Update" summaries from "VS Code" to see only standup summaries that included VS Code activities.

  Combining filters helps you find very specific workflow moments. Start with a broad filter (like event type) and then narrow it further with source or application filters.

***

## Next Steps

Now that you know how to filter Timeline events, learn how to manage individual events with actions like favoriting, generating titles, and deleting events.

[Event Actions and Menus →](/products/desktop/timeline/event-actions)

---

## Auto-Generated Summaries
Path: /products/desktop/timeline/ltm-rollups

## Auto-Generated Summaries

LTM Roll-Ups are detailed summaries of your workflow periods, automatically generated approximately every 30 minutes by the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine. View them by clicking any activity in the [Pieces Timeline](/products/desktop/timeline) sidebar. Each roll-up includes tasks, decisions, documents, and follow-ups from that time period. You can edit, export, or delete them as needed.

Roll-ups capture the context of your work—what you did, why you made certain decisions, and what still needs attention—making it easy to reference past work and understand your workflow patterns.

## Roll-Up Structure

Each roll-up contains structured information about your workflow period:

* **Core Tasks & Projects** — What you worked on and problems solved
* **Key Decisions & Discussions** — Important conversations and choices made
* **Documents & Code Reviewed** — Files and links you accessed (with deep links), based on files you had open and sites you visited during the window
* **Follow-Up Actions** — What still needs attention

Roll-ups created through Model Context Protocol (MCP) integrations display a "Formed with MCP" indicator.

## Viewing Roll-Ups

    Click any activity in Pieces Timeline.

    The full roll-up displays in the main panel with all sections. Deep links open resources directly in your browser.

    Use the `Jump to Summary in Timeline` button in the roll-up header to scroll Pieces Timeline back to that activity's position.

## Roll-Up Actions

From the toolbar, you can:

* **Chat** — Start a [Conversational Search](/products/desktop/conversational-search) conversation with roll-up context loaded
* **Export** — Download as `PDF`, `Markdown`, or `Plain Text`
* **Edit** — Open markdown editor to customize content, or use *Edit with AI* for prompt-based changes
* **More menu** — Copy or Delete
* **macOS Share** — Share to AirDrop, Mail, Messages, etc.

## Editing Roll-Ups

You can edit any roll-up manually or use AI to suggest changes for you.

### Manual Editing

    Click the `Edit` button in the roll-up toolbar, or click the three-dot menu at the top of the summary and select `Edit`.

    Use the markdown editor toolbar for formatting: **Bold**, *Italic*, Link, Code Block.

    Click `Save and Exit` to apply changes or `Cancel and Exit` to discard them.

### Edit with AI

Instead of making manual changes, you can describe what you'd like changed and let AI rewrite the content for you. Edit with AI supports two modes: **inline edits** that target a specific section, and **whole-summary rewrites** that rework the entire summary in one pass.

#### Inline Edits with Diff Review

Highlight a specific section to scope an edit to just that part. The rest of the summary stays untouched.

    Click the three-dot menu at the top of the summary and select `Edit`.

    Select the range of text you want to revise.

    Click the `Edit with AI` button in the top-right corner of the editor toolbar.

    Type a prompt into the *Describe changes you want to make...* field describing how you want the highlighted text revised.

    Pieces generates the suggested revision and displays it in a *Proposed Changes* diff view marked *Review Required*, so you can see exactly what would change.

    Click `Accept` to apply the change, or `Dismiss` to discard it and keep the original text.

#### Whole-Summary Rewrites

Skip the highlight step to rework the entire summary with one prompt. Useful for changing audience, tone, or format without rewriting from scratch.

    Click the three-dot menu at the top of the summary and select `Edit`.

    Click the `Edit with AI` button in the top-right corner of the editor toolbar without selecting any text.

    Type a prompt describing the change you want. Common examples:

    * `Make this shorter and Slack-ready`
    * `Rewrite this for an executive audience`
    * `Convert this into a checklist`

    Pieces generates the rewritten summary and displays it in a *Proposed Changes* diff view marked *Review Required*.

    Click `Accept` to apply the rewrite, or `Dismiss` to keep the original.

  Rewrites stay grounded in the same underlying memories that generated the original summary. Pieces reframes what's already captured rather than inventing new content.

## Privacy Control

Privacy Control lets you choose which applications contribute to your roll-ups. This helps you maintain privacy by excluding sensitive applications or focusing roll-ups on specific types of work.

    Click the grid icon in Timeline or access through the PiecesOS Quick Menu.

    Toggle sources on or off anytime—disabled sources are removed from existing and future roll-ups.

***

## Next Steps

Now that you know how to view and manage auto-generated summaries, learn how to navigate your Timeline.

[Expanding & Collapsing →](/products/desktop/timeline/expanding-collapsing)

---

## Timeline Events
Path: /products/desktop/timeline/timeline-events

## Timeline Events

Timeline Events is the chronological sidebar that displays all activities and conversations captured by the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine. Located on the left side of Timeline, it serves as your navigation hub for accessing any past workflow context. The sidebar organizes your activities by date, making it easy to find specific items whether they happened today or months ago.

Click the `Show Timeline` button in the top-left corner of the main view to open or close Pieces Timeline.

> Full screenshot of Timeline with Timeline Events sidebar open on the left, showing the "Show Timeline" button highlighted, multiple date groups (Today, Yesterday, Last Saturday), and several activity items with timestamps and icons

## Understanding Activity Items

Each item in Timeline Events contains information about a specific captured activity or conversation from your workflow.

Each memory item displays:

* **Title/Description:** A concise summary of the activity (e.g., "Desktop App Documentation Updates", "SDK, Docs, & Work Ledger").
* **Timestamp:** When the activity occurred (e.g., "10 minutes ago - 2:24pm", "Half an hour ago - 2:04pm").
* **Date Group:** Memories are grouped by date (Today, Yesterday, Last Saturday, Last Sunday, etc.).
* **Icon Indicators:** Visual indicators showing the type of activity or associated apps.
* **App Icons:** Small icons showing which applications were involved (Chrome, VS Code, Slack, etc.).
* **Count Badge:** Number on the right indicating how many events or items are in that memory.

> Showing current day dropdown in Timeline

## Navigating Timeline Events

The Timeline Events sidebar provides multiple ways to find and access specific workflow moments.

### Browsing by Date

Browse activities organized by date groups for easy navigation.

The sidebar automatically groups activities by date, with the most recent items at the top. Date groups include Today, Yesterday, and then specific dates for older activities (e.g., "Last Saturday, Jan 3rd"). Each day section can be expanded or collapsed to show or hide its contents. Scroll down through the sidebar to browse older activities—LTM-2.7 retains your workflow context for up to 9 months.

#### Expanding and Collapsing Day Sections

Each day section in Timeline Events can be expanded to view its contents or collapsed to hide them:

    Click the `Show Timeline` button in the top-left corner of the main view to open Pieces Timeline if it's not already open.

    Click on a day section (e.g., "Today, Jan 21st") to expand it and view all activities, summaries, and events for that day.

    When expanded, you can see all items for that day, including timeline activities, summaries (queued, processing, or completed), and conversational searches.

    Click the `caret icon` (dropdown arrow) at the top of the day divider to collapse the section and hide its contents.

    Click any activity item within an expanded day section to view its full roll-up in the main panel.

### Searching & Filtering

Search and filter activities to find specific workflow moments quickly.

#### Searching Activities

Use the search bar to find activities by keyword or topic:

    Click in the search field at the top of Pieces Timeline.

    Type keywords, project names, or topics you're looking for. The search uses neural search, meaning it understands context and can find relevant activities even if your search terms don't match exactly.

    View filtered results that update in real-time as you type.

    Click the `Filter List` button (icon with three horizontal lines) to access additional filtering options.

> Search/filter functionality showing typing a search query in the search bar at the top of Timeline Events sidebar, with the activity list filtering in real-time to display only matching results

## Viewing Activity Details

View full roll-up details for any activity item in the sidebar.

#### Viewing a Roll-Up

Click an activity to view its complete roll-up details:

    Click any activity item in Pieces Timeline.

    The full LTM Roll-Up displays in the main panel with detailed information including core tasks, key decisions, documents reviewed, and follow-up actions.

    You can start a Conversational Search conversation with that context, export it, edit it, or share it.

    Use the `Jump to Summary in Timeline` button (target icon) in the roll-up header to scroll back to the activity's position in Pieces Timeline if you've navigated away.

> Screenshot showing an activity item selected in the Timeline Events sidebar (highlighted) and the corresponding detailed roll-up displayed in the main panel to the right

## Activity Retention

Understand how long your workflow activities are retained.

LTM-2.7 retains your captured workflow context for up to 9 months. This gives you access to a substantial history of your work, allowing you to reference past projects, conversations, and decisions long after they occurred. Activities older than 9 months are automatically removed to ensure optimal performance.

## Tips for Using Timeline Events

Best practices for navigating and using Timeline Events effectively.

Following these tips helps you find and access workflow activities more efficiently.

* Use the search function when you remember specific keywords but not the exact date of an activity
* Date groups make it easy to find activities from "that meeting yesterday" or "the work I did last week"
* The emoji and app icons help you quickly scan the list visually—look for specific patterns that match what you're searching for
* If you're looking at a roll-up and want to see where it is in your chronological history, use the `Jump to Summary in Timeline` button
* Keep the Timeline Events sidebar open while working to quickly reference past context without losing your place

***

## Next Steps

Now that you know how to browse and search Timeline Events, learn how to generate instant summaries from your workflow.

[Single-Click Summaries →](/products/desktop/single-click-summaries)

---

## Timeline Activities
Path: /products/desktop/timeline/your-memories

## Timeline Activities

Browse and search your chronological list of captured activities and conversations in the sidebar.

Timeline Activities is the chronological sidebar that displays all activities and conversations captured by the [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27) Engine. Located on the left side of Timeline, it serves as your navigation hub for accessing any past workflow context. The sidebar organizes your activities by date, making it easy to find specific items whether they happened today or months ago.

Click the `Show Timeline` button in the top-left corner of the main view to open or close Pieces Timeline.

> Full screenshot of Timeline with Timeline Activities sidebar open on the left, showing the "Show Timeline" button highlighted, multiple date groups (Today, Yesterday, Last Saturday), and several activity items with timestamps and icons

## Understanding Activity Items

Each item in Timeline Activities contains information about a specific captured activity or conversation from your workflow.

Each memory item displays:

* **Title/Description:** A concise summary of the activity (e.g., "Desktop App Documentation Updates", "SDK, Docs, & Work Ledger").
* **Timestamp:** When the activity occurred (e.g., "10 minutes ago - 2:24pm", "Half an hour ago - 2:04pm").
* **Date Group:** Memories are grouped by date (Today, Yesterday, Last Saturday, Last Sunday, etc.).
* **Icon Indicators:** Visual indicators showing the type of activity or associated apps.
* **App Icons:** Small icons showing which applications were involved (Chrome, VS Code, Slack, etc.).
* **Count Badge:** Number on the right indicating how many events or items are in that memory.

> Close-up screenshot of 2-3 individual memory items showing all the components clearly labeled: title, timestamp, emoji indicator, app icons, and count badge

## Navigating Timeline Activities

The Timeline Activities sidebar provides multiple ways to find and access specific workflow moments.

### Browsing by Date

Browse activities organized by date groups for easy navigation.

The sidebar automatically groups activities by date, with the most recent items at the top. Date groups include Today, Yesterday, and then specific dates for older activities (e.g., "Last Saturday, Jan 3rd"). Scroll down through the sidebar to browse older activities—LTM-2.7 retains your workflow context for up to 9 months.

#### Browsing Activities

Navigate through date groups to find activities from specific time periods.

    Click the `Show Timeline` button in the top-left corner of the main view to open Pieces Timeline if it's not already open.

    Scroll down through Pieces Timeline to browse activities grouped by date.

    Click any activity item to view its full roll-up in the main panel.

### Searching & Filtering

Search and filter activities to find specific workflow moments quickly.

At the top of the Timeline Activities sidebar, you'll find a search and filter bar. Use the search field to find activities by keyword—search for project names, topics, document titles, or any text you remember from the activity. The filter functionality uses neural search, meaning it understands context and can find relevant activities even if your search terms don't match exactly.

Results update in real-time as you type, filtering the sidebar to show only matching activities. Click the `Filter List` button (icon with three horizontal lines) to access additional filtering options.

#### Searching Activities

Use the search bar to find activities by keyword or topic.

    Click in the search field at the top of Pieces Timeline.

    Type keywords, project names, or topics you're looking for. The search uses neural search, meaning it understands context and can find relevant activities even if your search terms don't match exactly.

    View filtered results that update in real-time as you type.

> Search/filter functionality showing typing a search query in the search bar at the top of Timeline Activities sidebar, with the activity list filtering in real-time to display only matching results

## Viewing Activity Details

View full roll-up details for any activity item in the sidebar.

When you click on any activity item in the sidebar, the full LTM Roll-Up for that activity displays in the main panel. The roll-up provides detailed information including core tasks, key decisions, documents reviewed, and follow-up actions. You can interact with the roll-up in multiple ways: start a Conversational Chat conversation with that context, export it, edit it, or share it.

Use the `Jump to Summary in Timeline` button (target icon) in the roll-up header to scroll Pieces Timeline back to that activity's position if you've navigated away.

#### Viewing a Roll-Up

Click an activity to view its complete roll-up details.

    Click any activity item in Pieces Timeline.

    The full LTM Roll-Up displays in the main panel with all details.

    Use the `Jump to Summary in Timeline` button to scroll Pieces Timeline back to the activity's position.

> Split screenshot showing an activity item selected in the Timeline Activities sidebar (highlighted) and the corresponding detailed roll-up displayed in the main panel to the right

## Activity Retention

Understand how long your workflow activities are retained.

LTM-2.7 retains your captured workflow context for up to 9 months. This gives you access to a substantial history of your work, allowing you to reference past projects, conversations, and decisions long after they occurred. Activities older than 9 months are automatically removed to ensure optimal performance.

## Tips for Using Timeline Activities

Best practices for navigating and using Timeline Activities effectively.

Following these tips helps you find and access workflow activities more efficiently.

* Use the search function when you remember specific keywords but not the exact date of an activity
* Date groups make it easy to find activities from "that meeting yesterday" or "the work I did last week"
* The emoji and app icons help you quickly scan the list visually—look for specific patterns that match what you're searching for
* If you're looking at a roll-up and want to see where it is in your chronological history, use the `Jump to Summary in Timeline` icon
* Keep the Timeline Activities sidebar open while working to quickly reference past context without losing your place

***

## Next Steps

Now that you know how to browse and search Timeline Activities, learn how to generate instant summaries from your workflow.

[Single-Click Summaries →](/products/desktop/single-click-summaries)

---

## Troubleshooting
Path: /products/desktop/troubleshooting

## Using the Guides

Click one of the links below to get started troubleshooting on your device—or [browse the cross-platform troubleshooting documentation](/products/desktop/troubleshooting/cross-platform) for more general fixes.

    Troubleshooting guides for all platforms

    macOS-specific troubleshooting guides

    Windows-specific troubleshooting guides

    Linux-specific troubleshooting guides

***

## Cross-Platform Issues

This guide covers troubleshooting for the Pieces Desktop App and PiecesOS, including updates, connectivity, system requirements, checking hardware specifications, and fixing crashes, and more.

  Use the Cross-Platform page if you’re not sure where to begin or if your issue isn’t clearly related to your operating system.

  On the [Cross-Platform troubleshooting guide](/products/desktop/troubleshooting/cross-platform), you’ll find:

  * [Tips on restarting PiecesOS and Pieces Desktop App](/products/desktop/troubleshooting/cross-platform#restarting-pieces-suite--checking-updates)

  * [Links to common installation issues on your OS](/products/desktop/troubleshooting/cross-platform#common-installation-issues)

  * [Links to related documentation on checking hardware specifications on your OS](/products/desktop/troubleshooting/cross-platform#checking-hardware)

## macOS Issues

This guide shows how to fix installation and update problems with the Pieces Desktop App on macOS.

It includes steps for manual installation using DMG or Homebrew, checking for updates, and confirming your macOS version and CPU type. It also gives steps to solve common system compatibility and installation errors.

  The [macOS troubleshooting guide](/products/desktop/troubleshooting/macos) provides information and guides on:

  * [Alternative Installation Methods](/products/desktop/troubleshooting/macos#alternative-installation-methods)

  * [How to verify your macOS version](/products/desktop/troubleshooting/macos#checking-os-version)

  * [Updating the Pieces Desktop App](/products/desktop/troubleshooting/macos#updating-the-pieces-desktop-app)

  * [macOS Permissions (Screen Recording & Microphone)](/products/desktop/troubleshooting/macos#macos-permissions)

## Windows Issues

Windows users can find help for fixing problems with the Pieces Desktop App in this guide.

This includes steps for manual installation using .exe or WinGet, how to update the app, solutions for system updates, app dependencies, hardware compatibility, and instructions on checking your Windows version and device specs.

It also covers how to ensure a clean restart after making fixes.

  The [Windows troubleshooting guide](/products/desktop/troubleshooting/windows) provides information and guides on:

  * [Alternative installation methods for non-Suite installs](/products/desktop/troubleshooting/windows#alternative-installation-methods)

  * [Checking for Windows installation updates](/products/desktop/troubleshooting/windows#versions--updates)

  * [Verifying the App Installer is up-to-date](/products/desktop/troubleshooting/windows#updating-the-microsoft-store--app-installer)

  * [Viewing hardware specifications using dxdiag](/products/desktop/troubleshooting/windows#checking-hardware-specifications)

## Linux Issues

This guide explains how to troubleshoot the Pieces Desktop App on Linux, including updating via Snap, checking distribution compatibility, and fixing installation or display issues, and more.

  The [Linux troubleshooting guide](/products/desktop/troubleshooting/linux) provides information and guides on:

  * [Confirming compatibility with your Linux distribution](/products/desktop/troubleshooting/linux#checking-distribution-compatibility)

  * [Using snap commands to update the Pieces Desktop App](/products/desktop/troubleshooting/linux#updating-pieces-desktop)

  * [Adjusting graphics settings if you encounter UI issues](/products/desktop/troubleshooting/linux#adjusting-graphics--display-settings)

## Additional Assistance

If you’ve followed the applicable troubleshooting steps and still experience problems, consider visiting our community forums for additional guidance, opening a GitHub issue, or booking a call with our engineers.

[You can also find additional support resources here.](/products/support)

---

## Cross-Platform Issues
Path: /products/desktop/troubleshooting/cross-platform

***

## Basic Troubleshooting

Find links to detailed sections on specific troubleshooting steps as well as information on system requirements and more.

<on-device-storage />

## Versions & Updates

Many issues can stem from having an out-of-date Pieces Desktop App.

### Updating Pieces Desktop

The Pieces Desktop App will update automatically.

For standalone & alternative installations, updates are checked daily or when you open the application. You'll be prompted to install or delay the update if one is available.

See your platform-specific update instructions on updating the Pieces Desktop App:

* [macOS](/products/desktop/troubleshooting/macos#updating-the-pieces-desktop-app)

* [Windows](/products/desktop/troubleshooting/windows#updating-pieces-desktop-app)

* [Linux](/products/desktop/troubleshooting/linux#updating-pieces-desktop)

## Connection Issues with Pieces Desktop

You may occasionally encounter connection issues between PiecesOS and Pieces Desktop App, resulting in difficulty finding saved materials, issues generating shareable links, and hanging responses from Conversational Search.

The quickest way to resolve this basic connection issue is to restart PiecesOS and the Pieces Desktop App, then check for updates.

### Restarting Pieces Suite & Checking Updates

To restart and check for updates for PiecesOS and Pieces Desktop:

    Ensure PiecesOS is running (look for the Pieces Icon in your system tray or menu bar)

    Click on the PiecesOS icon and press the `power off` button or the `exit` button in the top right.

    Make sure the Pieces Desktop App is closed by clicking the `x` button on the top right or by closing it through task manager.

    After opening Pieces Desktop App, PiecesOS will open automatically

    * If there are updates, you will be prompted to update both PiecesOS and Pieces.

## Common Installation Issues

Common issues can occur when setting up the Pieces Desktop App for the first time.

Platform-specific solutions are detailed on their respective OS pages:

* [macOS](/products/desktop/troubleshooting/macos#common-installation-issues)

* [Windows](/products/desktop/troubleshooting/windows#common-installation-issues)

* [Linux](/products/desktop/troubleshooting/linux#common-installation-issues)

## Checking Hardware

It may be necessary to verify your system’s specifications if you experience ongoing issues.

See the OS-specific pages for instructions on how to check CPU, RAM, and GPU details:

* [macOS](/products/desktop/troubleshooting/macos#checking-os-version)

* [Windows](/products/desktop/troubleshooting/windows#checking-hardware-specifications)

* [Linux](/products/desktop/troubleshooting/linux#checking-system-information)

---

## Issues | Linux
Path: /products/desktop/troubleshooting/linux

## Installation & Updating Fixes

You can find detailed instructions on how to update PiecesOS and the Pieces Desktop App on your Linux device using the terminal.

Additionally, you can check your system's OS and hardware specifications to ensure they meet the minimum recommended requirements.

<on-device-storage />

## Versions & Updates

Many issues can stem from running outdated versions of the Pieces Desktop App on Linux.

### Updating Pieces Desktop

On Linux, the Pieces Desktop App is distributed via snaps (for Ubuntu-based systems).

To update the Pieces Desktop App on Linux:

    For best results, quit the Pieces Desktop App and PiecesOS before updating. This ensures a clean shutdown and avoids conflicts. After updating, launch PiecesOS first, then the Desktop App.

    Run `snap info pieces-for-developers` to check the current version.

    Run `sudo snap refresh pieces-for-developers pieces-os` to update both. Use `sudo snap refresh` to update all snap packages.

## Common Installation Issues

Official support is for **Ubuntu 22.04+ and Ubuntu-based distributions.** Other distributions might work, but *aren’t guaranteed.*

## Checking Distribution Compatibility

Ensure you’re running a supported **Ubuntu-based distribution.**

If not, consider switching to a supported environment, as installation on non-Ubuntu distributions isn’t guaranteed.

### Updating Snapd

Snap-based installations require an up-to-date snap `daemon`:

* Run `sudo snap refresh` to ensure `snapd` and its packages are current

### Adjusting Graphics & Display Settings

If installation or UI issues persist, consider the following:

* **Switch Between X11 and Wayland:** Some applications may work better on one display protocol than the other. Try switching to X11 for compatibility or Wayland for newer features. You can usually select this at the login screen.

  **Supported setup:** **Ubuntu** with **X11**. **Wayland** usually needs follow-up from `pieces-os.doctor`. Other distros are **best-effort**. If capture or LTM fails, try an **X11 session**, re-run `pieces-os.doctor`, or use a **supported Ubuntu** install—**VMs** are the most variable.

* **Update your GPU Drivers:** Ensure they are up to date. For NVIDIA, check for proprietary driver updates. AMD and Intel users should verify that their open-source drivers are up to date.

* **Optimize Graphics Configurations:** Use tools like `nvidia-settings`, `radeon-profile`, or similar utilities to adjust your GPU settings for better performance and stability.

These adjustments can resolve many graphical and display-related issues you may experience while using Pieces.

## Checking System Information

Verify your system's hardware configuration and ensure it meets the recommended specifications by running specific commands in your terminal.

### Checking CPU Information

To determine your CPU type and find other important information, type `lscpu` in your terminal and press `Enter`.

### Checking GPU Information

To determine your GPU type and find other important information, run `lspci | grep -i vga` in your terminal and press `Enter`.

Confirm that your CPU, GPU, and memory resources are sufficient for running PiecesOS.

### Checking Ubuntu Version

If the Pieces Installer is not working as intended, you could have an outdated version of Ubuntu. The minimum Ubuntu version that Pieces will run on is **Ubuntu 22.04 or later**.

To check what version of Ubuntu you’re running:

    Open the **Settings** on Ubuntu by clicking the *options bar* in the top right

    Locate the **System** section at the bottom of the left-hand side menu and click it

    Open the **About** section and locate the **Operating System** label

This section will display your Ubuntu version information.

### Consulting Online Resources

If you encounter persistent installation issues, consult online forums or community guides related to snap and Ubuntu-specific troubleshooting steps.

## Claude Desktop MCP on Linux

Pieces supports Snap and Flatpak installs. For the Claude Desktop MCP connection from Desktop `Settings` → `MCP`, Claude only needs to point at the PiecesOS executable—no additional install is required.

Quit Claude Desktop before `Connect` if it is running, then use `Restart Claude Desktop now` when prompted. Full steps: [Claude Desktop](/products/mcp/claude-desktop).

## Restart & Retry

If you've updated components, checked the hardware, and adjusted configurations without success, try restarting your machine and then try again.

If the problem persists, please open a <a target="_blank" href="https://github.com/pieces-app/support/issues">**GitHub issue**</a> for further assistance or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call with our engineers</a>.

---

## Issues | macOS
Path: /products/desktop/troubleshooting/macos

***

## Installation & Updating Fixes

PiecesOS and the Pieces Desktop App can be downloaded using several installation methods, and they can be updated differently depending on the method used.

You can also find information below on how to determine the CPU architecture and OS version of your Apple device.

<on-device-storage />

## Alternative Installation Methods

If you're having trouble installing the Pieces Desktop App using the recommended `.dmg` method, you can try installing using our unified `.pkg` installers or via Homebrew.

### via PKG

Our `.pkg` files install both PiecesOS and the Pieces Desktop App in a single guided sequence.

  Not sure which installer you need? See [how to check your CPU type](/products/desktop/troubleshooting/macos#checking-cpu-type)

    *macOS 13.0 (Ventura) or higher*

    *macOS 13.0 (Ventura) or higher*

  You can also install PiecesOS manually using Homebrew from your device’s terminal.

  To do so:

  1. Ensure Homebrew is installed on your system.

  2. Run `brew install --cask pieces-os` in your terminal to install the Pieces Homebrew package.

## Versions & Updates

Many issues can stem from out-of-date MCP integrations, PiecesOS, or the desktop app itself. When you check for updates from either the Desktop App or the PiecesOS Quick Menu, both apps update together.

### From the Desktop App

    Click your profile or username in the top-left corner of the Pieces Desktop App.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it, then restart when complete.

> Profile menu in the Pieces Desktop App with `Check for Updates`

### From the PiecesOS Quick Menu

Click the Pieces icon in your menu bar and click `You're up to date` to trigger a check. If an update is available, follow the prompt to install.

> PiecesOS Quick Menu showing your current version and update status

## Common Installation Issues

Common installation issues on Apple devices include having an outdated OS version or choosing the wrong installation package.

### Checking OS Version

Pieces applications need at least **macOS 13.0 (Ventura).** If you're having installation problems, first check that your OS version is up-to-date.

To determine your Apple device’s version of macOS:

    Click the `Apple Icon` in the top-left corner of your screen

    Select `About This Mac`

    Under your device name (i.e. MacBook Air), look for the last line on the list, titled **macOS**

### Checking CPU Type

Intel and Apple Silicon (ARM) devices run on entirely separate CPU architectures, so downloading the wrong package for your Apple device can cause Pieces Desktop to be rendered useless.

To determine what CPU architecture your Apple device utilizes:

    Click the `Apple Icon` in the top-left corner of your screen.

    Select `About This Mac`, and look for the **Overview section.** The first line will contain your CPU type:

    * **Apple Silicon / ARM:** You will see an M-Series processor (i.e., Apple M3)

    * **Intel:** You will see an Intel processor (i.e., 2.6 GHz Intel Core i7)

    Once you’ve determined your CPU architecture, [download the correct installation package accordingly.](/products/desktop/troubleshooting/macos#alternative-installation-methods)

## macOS Permissions

PiecesOS requires specific macOS permissions to function properly. If features like *Long-Term Memory* or *Live Context* aren't working as expected, the most common cause is missing system permissions.

### Screen & System Audio Recording

PiecesOS needs *Screen & System Audio Recording* permission to capture on-screen context for features like *Long-Term Memory* and *Live Context*.

To enable this permission:

    Click the `Apple Icon` in the top-left corner of your screen and select `System Settings`

    Select `Privacy & Security` from the sidebar

    Scroll down and click `Screen & System Audio Recording`

    Find **Pieces OS** in the list and toggle it **on**. If Pieces OS is not listed, click the `+` button at the bottom of the list, then locate and add Pieces OS from your Applications folder.

    > macOS Screen & System Audio Recording settings with Pieces OS enabled.

  macOS may prompt you to quit and reopen Pieces OS for the permission change to take effect.

### Microphone

PiecesOS also requires *Microphone* access to capture audio context for *Long-Term Memory*.

To enable this permission:

    Click the `Apple Icon` in the top-left corner of your screen and select `System Settings`

    Select `Privacy & Security` from the sidebar

    Scroll down and click `Microphone`

    Find **Pieces OS** in the list and toggle it **on**. If Pieces OS is not listed, click the `+` button at the bottom of the list, then locate and add Pieces OS from your Applications folder.

    > macOS Microphone settings with Pieces OS enabled.

## Restart & Retry

If the installation fails because your macOS version is outdated or you installed the wrong package for your device's architecture, restart your machine and try the installation again from the beginning.

If the problem persists, please open a <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> for further assistance, or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call with our engineers</a>.

---

## Issues | Windows
Path: /products/desktop/troubleshooting/windows

***

## Installation & Updating Fixes

PiecesOS and the Pieces Desktop App can be downloaded in several ways, and the update process varies based on the method you used, like whether you installed them via WinGet or `.exe` files.

<on-device-storage />

## Manual Installation Methods

If you’re experiencing difficulties installing the Pieces Desktop App, you can install the software manually by downloading the Windows installer or using WinGet.

    *.EXE*

    *.appinstaller*

  You can also install Pieces manually using **WinGet** from your device’s terminal.

  To do so:

  1. Launch Windows Terminal, Command Prompt, or PowerShell as *administrator.*

  2. In the terminal, type `winget install “Pieces”` and press `enter`.

  You may be prompted to enter `Y` or `N` to agree or disagree with the terms of use when installing the Pieces Desktop App—type and enter `Y` to proceed with the installation.

## Versions & Updates

Many issues can stem from out-of-date MCP integrations or the Desktop App itself. When you check for updates from either the Desktop App or the PiecesOS Quick Menu, both apps update together.

### From the Desktop App

    Click your profile or username in the top-left corner of the Pieces Desktop App.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it, then restart when complete.

> Profile menu in the Pieces Desktop App with `Check for Updates`

### From the PiecesOS Quick Menu

Click the Pieces icon in your system tray and click `You're up to date` to trigger a check. If an update is available, follow the prompt to install.

## Common Installation Issues

Windows users may encounter installation issues for various reasons, such as out-of-date OS components or incomplete dependencies.

### Checking for Windows Updates

Before installing, ensure your Windows system is fully updated:

    Click the `Start` button, then select `Settings`.

    Click `Windows Update` in the sidebar options.

    Install any pending updates and restart your computer.

### Updating the Microsoft Store & App Installer

If you downloaded Pieces software through the Microsoft Store and are experiencing issues with the marketplace interface, try updating the app.

    Press the `Windows` button and search for the **Microsoft Store**, open it.

    Click on `Library `to check for available updates.

    Update the Microsoft Store and the App Installer if prompted.

    Now, you can retry installing Pieces Suite.

## Issues Launching PiecesOS

Some users who have enabled Controlled Folder Access (CFA) as a security measure may receive a notification that Pieces is attempting to bypass this security wall.

To work around this issue, you will need to *add the executable path for PiecesOS* to your allowlist.

  The reason PiecesOS fails to launch when CFA is enabled is that the executable path for the PiecesOS application writes data to your Documents folder.

  CFA disables and blocks any request to modify files (in this case, writing & saving data), so PiecesOS is unable to launch itself.

Keep in mind that this path references the specific PiecesOS version, and so will change over time as long as you continue to update the software. You can also disable CFA as a security measure if you do not require it as part of an enterprise scenario or for any other reason.

PiecesOS uses vision processing to ingest context from foreground applications horizontally.

To decide which apps PiecesOS has access to, you can [easily enable and disable specific sources from the Long-Term Memory Access Control](/products/core-dependencies/pieces-os/quick-menu#long-term-memory-access-control) panel.

## Accessing Pieces Logs

On Windows, PiecesOS and the Desktop App store logs under separate folders in AppData. See [On-Device Storage](/products/core-dependencies/on-device-storage#finding-your-logs) for backup and database paths.

* **PiecesOS logs:**\
  `C:\Users\\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support`

* **Desktop App logs:**\
  `C:\Users\\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\production\logs`

  Replace \ with your Windows account name.

## Checking Hardware Specifications

You may need to check your system's specifications if you continue to experience issues, especially when running the [Long-Term Memory Engine](/products/core-dependencies/pieces-os/quick-menu#long-term-memory-access-control).

To check your device specifications on Windows:

    Press the `Windows` key on your keyboard or the `Windows Icon` in the task bar.

    Type **“run”** and press `enter`.

    Type `dxdiag` and press `enter` or click the blue `OK` button.

The **System** tab displays your processor, the number of CPU cores, and memory (RAM), while the **Display** tab lists your GPU, its manufacturer (e.g., NVIDIA, AMD, Intel), and the available video memory (VRAM).

### Checking Windows Version

If the Pieces Installer isn't working properly, you might be using an outdated version of Windows. Pieces requires at least **Windows 10 20H0 or higher**.

To find out your Windows version, press the `Windows` and `R` keys together, type **winver** in the pop-up window, and press `Enter`.

A new window will open called *About Windows*, which will display your current Windows version.

  If this doesn't work, you’re likely using a Windows version lower than Windows 10.

### Restart the Pieces Desktop App

After trying any of the fixes above, it’s recommended that you restart your desktop and the Pieces Desktop App.

This ensures all caches are clean and the computer is refreshed.

If the problem persists, please open a <a target="_blank" href="https://github.com/pieces-app/support/issues">**GitHub issue**</a> for further assistance or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call with our engineers</a>.

---

## Enterprise
Path: /products/enterprise

## Enterprise

Pieces offers enterprise-grade solutions for teams and organizations. This documentation covers organization management, user onboarding, and enterprise features.

### In this section

[Organizations](/products/enterprise#creating-and-joining) — Create organizations and manage members.

[Onboarding Users](/products/enterprise/onboarding) — Step-by-step walkthrough for new team members to get set up with Pieces. Share this link directly with your team.

[Features](/products/enterprise#enterprise-features) — Enterprise features, security, compliance, and admin controls.

For the full Organizations & Teams documentation, see [Organizations & Teams](/products/organizations-and-teams). For enterprise pricing and custom solutions, visit [pieces.app/enterprise](https://pieces.app/enterprise).

---

## Features
Path: /products/enterprise/features

***

Pieces Enterprise includes features designed for teams and organizations at scale. Admin controls, security, and compliance options help you deploy Pieces across your engineering organization.

> Organization Home page showing admin dashboard, management tools, and resource links

### Enterprise Features

* **Organizations & Teams** — Create organizations and invite members
* **Centralized Settings** — Manage models, API keys, and configuration at the org level
* **Shared Context** — Organization members can share materials, snippets, and workflow context
* **Admin Dashboard** — Overview of members, usage, and organization health

### Security & Compliance

* **Role-based Access** — Owners, admins, and members with appropriate permissions
* **Audit Logs** — Track changes and access for compliance
* **Data Residency** — Options for data location and retention
* **SSO** — Single Sign-On for enterprise authentication

  For specific security and compliance requirements, contact your Pieces account team or [enterprise@pieces.app](mailto:enterprise@pieces.app).

### Admin Controls

Organization owners and admins can:

* Invite and remove members
* Manage member roles and access
* Configure billing and subscription
* Manage API keys and model settings
* Control feature access per member

See [Organization Settings](/products/organizations-and-teams/organization-settings) for feature toggles, API keys, models, and LTM sources. For onboarding, see [Onboarding Users](/products/enterprise/onboarding). For organization structure, see [Organizations](/products/enterprise/organizations).

---

## Onboarding Users
Path: /products/enterprise/onboarding

***

This guide walks admins through getting their team set up with Pieces and walks team members through accepting their invitation and installing Pieces. Share this page directly with your team to get everyone onboarded.

## Setting Up Your Team

As an organization owner or admin, you'll invite team members, ensure you have enough seats, and share resources to help your team get started.

### Creating Your Organization

If you haven't created your organization yet, you'll need to do that first. The process involves choosing a name, selecting seats, picking a subscription plan, and completing checkout.

    Click your `User Profile` in the top left of Pieces Desktop, then click `Settings` and select `Account`. Scroll down to the *Organizations & Teams* section and click `+ Create an organization`. You can also start directly at [portal.pieces.app](https://portal.pieces.app).

    Enter your organization name, choose the number of seats, and select a subscription plan (Enterprise Seat Yearly, Quarterly, or Monthly). Complete checkout to create your organization.

For the full creation walkthrough, see [Creating and Joining Organizations](/products/organizations-and-teams/creating-and-joining-organizations).

### Inviting Team Members

Once your organization is set up, invite your team by email. Each invited member needs an available seat in your subscription.

    Click `Members` in the *sidebar*, then click the `Invite people` button in the top right corner.

    Enter email addresses and select a role for each member:
    * **Owner** — Full control including organization deletion
    * **Admin** — Full access except organization deletion
    * **Write** — Can create and edit resources
    * **Read** — View-only access

    Click `Send Invites & Finish` to send the invitations. Each member will receive an email with instructions to join.

  For large teams, you can bulk invite members by uploading a CSV file with the format `email,role` (one member per line). Click the `Upload CSV` option in the invite modal.

### Sharing Download Links

You can also share direct download links with your team so they can install Pieces before or after accepting their invitation:

* **macOS** — [Download for Mac](/products/meet-pieces/macos-installation-guide)
* **Windows** — [Download for Windows](/products/meet-pieces/windows-installation-guide)
* **Linux** — [Download for Linux](/products/meet-pieces/linux-installation-guide)

Alternatively, team members can download Pieces directly from the organization's Home page in the Pieces portal after they accept their invitation.

### Managing Seats

Make sure you have enough seats for your team before sending invitations. You can view current seat usage on the `Members` page and add seats from the `Billing` page. See [Billing](/products/organizations-and-teams/billing) for details on adjusting seat counts.

## For Team Members: Getting Started

If you've received an invitation to join a Pieces organization, follow these steps to get set up.

  Onboarding users need to sign in with the same email the invitation was sent to.

### Accepting Your Invitation

    You'll receive an email invitation from your organization's admin. The email includes details about the organization and your assigned role.

    Click the link in the email to accept. You'll be taken to the Pieces portal to sign in or create an account.

    If you don't already have a Pieces account, create one using the email address the invitation was sent to. If you already have an account, sign in with your existing credentials.

### Installing Pieces

After accepting your invitation, you'll land on your organization's Home page in the Pieces portal. The *Setup* section at the top provides everything you need to get Pieces installed.

> Organization Home page showing Setup section with download links and sign-in instructions

    If Pieces is already installed, click `Open Pieces Desktop` to launch it. If not, click `Download for Mac` (or your platform) to download the installer. Links for Windows and Linux are also available under *Other platforms*.

    Run the downloaded installer, which sets up both Pieces Desktop and PiecesOS (the background service that powers Pieces). Follow the on-screen prompts to complete installation.

    After installation, sign in to Pieces Desktop and PiecesOS with the same email address associated with your organization. The Home page will remind you which email to use — look for the message that says "Sign in with [your-email] in Desktop & PiecesOS to stay in sync."

  Signing in with your organization email ensures your settings, models, API keys, and features configured by your admin automatically sync to your installation.

### Exploring Resources

The *Resources* section on the Home page provides quick links to help you get the most out of Pieces:

* **Documentation** — Guides and API reference at [docs.pieces.app](https://docs.pieces.app)
* **Pro tip guides** — Tips and best practices for using Pieces effectively
* **Support** — Get help and contact the Pieces team
* **GitHub** — Explore repos and open source projects

## SSO & Provisioning

Enterprise plans support Single Sign-On (SSO) and SCIM user provisioning for streamlined onboarding. SSO lets users sign in with your identity provider, and SCIM provisioning automates user lifecycle management.

Admins can configure SSO by adding a *Descope* Tenant ID in [General Settings](/products/organizations-and-teams/settings-general). For Associated Domains, add your company's email domain to enable automatic user assignment.

  For help setting up SSO or SCIM provisioning, contact [sales@pieces.app](mailto:sales@pieces.app).

***

## Next Steps

Once your team is set up, explore [Organization Settings](/products/organizations-and-teams/organization-settings) to configure features, API keys, models, and LTM sources for your entire team, or see [Features](/products/enterprise/features) for a full overview of enterprise capabilities.

---

## Organizations
Path: /products/enterprise/organizations

***

Organizations in Pieces let you collaborate at scale. Create organizations, invite team members, and maintain consistent settings across your enterprise.

### Creating Organizations

Create a new organization to start collaborating with your team. Organization owners have full control over team settings, member access, and shared resources.

    Click your `User Profile` in the top left, then click `Settings` and select `Account`. Scroll down to the *Organizations & Teams* section and click the `+ Create an organization` button.

    Enter your organization name in the provided field. Choose a name that clearly identifies your team or company.

    Select the number of seats using the `+` and `-` buttons. Choose your subscription plan (Enterprise Seat Yearly, Quarterly, or Monthly).

    Click `Checkout` to proceed. Complete payment through *Paddle*. After payment, you can invite team members or skip for later.

### Managing Members

As an organization owner or admin, you can invite members, assign roles, and manage access. Each role has different permissions:

* **Owner** — Full control including organization deletion
* **Admin** — Full access except organization deletion
* **Write** — Can create and edit resources
* **Read** — View-only access

    Click `Members` in the *sidebar*, then click the `Invite people` button in the top right.

    Enter the email address and select a role from the `Select a role...` dropdown. You can add multiple members or bulk upload via CSV.

    Click `Send Invites & Finish` to send the invitation. Members receive an email with instructions to join.

For billing and settings, see [Managing Organizations](/products/organizations-and-teams/managing-organizations) or [Onboarding Users](/products/enterprise/onboarding).

---

## Glossary
Path: /products/glossary

<glossary-all />

---

## Integrations Overview
Path: /products/integrations-overview

## Connecting Pieces to Your Workflow

Pieces integrates with your development environment in two powerful ways: **MCP Server** for AI-powered IDE integrations, or **CLI** for terminal-based workflows. Both connect to [PiecesOS](/products/core-dependencies/pieces-os) to provide access to your [Long-Term Memory](/products/desktop/long-term-memory) and [Timeline](/products/desktop/timeline)—the primary surfaces for captured workflow context. [Pieces Drive](/products/desktop/drive) remains available as a **legacy** material manager for existing saved snippets; new workflows should rely on LTM and Timeline instead.

## Choosing Your Integration

### MCP Server (Recommended for AI-Powered Development)

The **Model Context Protocol (MCP) Server** connects AI assistants like Claude, GitHub Copilot, and Cursor directly to your Pieces Long-Term Memory. MCP enables your AI coding assistants to understand your workflow context, past decisions, and project history.

**Best for:**
- AI-assisted coding in IDEs (Cursor, VS Code, JetBrains)
- Context-aware AI conversations
- Teams using AI coding assistants
- Visual development workflows

**Supported clients:**
- Cursor, VS Code, GitHub Copilot
- Claude Desktop, Claude Code
- JetBrains IDEs (IntelliJ, PyCharm, WebStorm)
- Windsurf, Cline, Continue.dev, Zed
- And 15+ more AI-powered tools

  Connect AI assistants to your Pieces Long-Term Memory with Model Context Protocol integration.

***

### CLI (Command-Line Interface)

The **Pieces CLI** brings Pieces functionality to your terminal with commands for saving snippets, querying your Long-Term Memory, and accessing Conversational Search from the command line.

**Best for:**
- Terminal-based development workflows
- Command-line power users
- Scripting and automation
- Headless environments

**Key features:**
- Conversational Search from your terminal
- Legacy [Pieces Drive](/products/cli/drive) commands in the CLI (save, search, share materials) for users who still rely on Drive
- Terminal UI (TUI) for visual navigation
- Long-Term Memory queries from CLI

  Access Pieces features directly from your terminal with the command-line interface.

***

## Decision Guide

### Choose MCP Server if you:
- Use AI coding assistants (Claude, GitHub Copilot, Cursor)
- Work primarily in IDEs or code editors
- Want AI to understand your workflow history
- Need context-aware code suggestions

### Choose CLI if you:
- Prefer terminal-based workflows
- Write scripts or automation
- Work in headless or remote environments
- Want quick snippet management from command line

### Use Both!
Many developers use **both** integrations:
- MCP for AI-assisted coding in their IDE
- CLI for quick terminal operations and scripting

***

## Prerequisites

Both integrations require:

1. **[PiecesOS](/products/core-dependencies/pieces-os)** installed and running
2. **[Long-Term Memory enabled](/products/meet-pieces/enabling-long-term-memory)** (for context-aware features)
3. Your development tools installed (IDEs, terminal, etc.)

***

## Quick Start

### MCP Server Setup

    [Download and install PiecesOS](/products/core-dependencies/pieces-os/manual-installation) for your platform (macOS, Windows, Linux).

    Open Pieces Desktop and [enable Long-Term Memory](/products/meet-pieces/enabling-long-term-memory) to start capturing workflow context.

    Select your AI tool or IDE from the [MCP integrations list](/products/mcp) and follow the setup guide.

***

### CLI Setup

    [Download and install PiecesOS](/products/core-dependencies/pieces-os/manual-installation) for your platform.

    Follow the [CLI installation guide](/products/cli/get-started) to install the command-line tool.

    Run `pieces` commands in your terminal or launch the [TUI](/products/cli/tui) with `pieces tui`.

***

## Next Steps

Ready to connect Pieces to your workflow?

  Learn about Model Context Protocol and browse 20+ supported AI clients and IDEs.

  Explore CLI commands, Conversational Search, legacy Drive workflows, and Terminal UI features.

***

## Need Help?

Visit [Support](/products/support) for troubleshooting guides, FAQs, and community resources.

---

## Pieces MCP Server
Path: /products/mcp

***

## Introducing Pieces Model Context Protocol (MCP)

Welcome to Pieces Model Context Protocol (MCP), an innovative way to connect Large Language Models (LLMs) to the context they need from your digital world.

## What is an MCP?

*Model Context Protocol*, or MCP, is an open standard developed by Anthropic that enables LLMs, like Claude and ChatGPT, to access external data sources and tools without needing complex, custom integrations.

In a way, MCP is becoming a *universal* context provider that uses a well-standardized communication protocol to pass information (like external data) or tools to LLM-powered applications.

This is extremely useful—because it means somebody using the Cursor agentic chat system can rope in external context to the LLM, giving it additional context outside of the purview of the active file or codebase they're working in.

## How Pieces Integrates with MCP

The core of the Pieces ecosystem is [PiecesOS](/products/core-dependencies/pieces-os), which powers the Pieces Desktop App and [MCP integrations](/products/mcp) across your editors and tools.

At its heart is the advanced [Long-Term Memory Engine (LTM-2.7)](/products/core-dependencies/pieces-os#ltm-27), which captures, enriches, and locally stores valuable contextual information from your daily workflow, such as code snippets, browser history, notes, and application data.

Pieces leverages the MCP to connect your favorite development tools and AI applications—like Cursor and GitHub Copilot—directly to PiecesOS, enabling smooth, context-rich interactions [entirely on your device.](/products/privacy-security-your-data#data-storage--control)

### Required Dependency

PiecesOS is a required dependency—you won’t be able to use Pieces as an MCP without it.

Read [documentation on PiecesOS](/products/core-dependencies/pieces-os) or jump to the [PiecesOS installation guides](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) to get started.

## Use Cases and Benefits

Discover some critical use cases and benefits to using the Pieces MCP integration as a core tool alongside your daily development process.

### Context-Rich Debugging

Imagine encountering a tricky bug within [Cursor](/products/mcp/cursor).

Instead of manually reviewing logs or searching online, MCP allows Cursor to directly query Pieces LTM:

***

| **Prompt**                                                                                             | **Outcome**                                                                                                          |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| *"Did the team decide to make* `enrichmentLevel` *case-sensitive for the applets? Is that the issue?"* | Cursor retrieves relevant team discussions and code decisions from PiecesOS, clarifying case-sensitivity decisions.  |
| *"Show me log entries from the recent API outages related to token expiration."*                       | Cursor fetches specific API outage logs and token-related errors stored by Pieces LTM for quick diagnosis.           |
| *"Have I previously encountered memory leaks in similar Node.js background tasks?"*                    | Cursor accesses your historical debugging notes and previous Node.js fixes saved in PiecesOS to suggest solutions.   |
| *"What configuration changes were made right before database latency spiked yesterday afternoon?"*     | Cursor gathers recent configuration modifications from PiecesOS to identify the exact changes affecting performance. |

***

### Contextual Queries

When integrated with [GitHub Copilot](/products/mcp/github-copilot), MCP enhances your coding experience by providing context-specific suggestions and history-driven recommendations:

***

| **Prompt**                                                                    | **Outcome**                                                                               |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| *“Show me previous implementations of this authentication method.”*           | Copilot fetches related past implementations from your Pieces LTM history.                |
| *“Show me similar code snippets to this React component.”*                    | Copilot retrieves related React components from your Pieces LTM history.                  |
| *“What fixes have I previously implemented for this type of database error?”* | Copilot accesses historical database error resolutions stored in Pieces LTM.              |
| *“Have I encountered this bug before?”*                                       | Copilot identifies past occurrences and corresponding fixes from your Pieces LTM context. |

***

## Why Users Love Pieces MCP

Pieces MCP empowers users to leverage personal context for AI-driven interactions, significantly reducing manual research, accelerating troubleshooting, and enhancing productivity.

By connecting directly to [PiecesOS](/products/core-dependencies/pieces-os), your context becomes a powerful, personalized source of truth that informs AI interactions:

* **Personalized Context**—The LLM understands your work based on real-time and historical data.

* **Secure and Local**—All data stays local for your [privacy and security.](/products/privacy-security-your-data)

* **Extensible and Open**: Easily integrate new tools and data sources with minimal effort.

***

*Pieces MCP —> Cursor*

***

## Technical Reference

Learn about the foundational layers of MCP architecture and the Pieces → MCP → LLM output flow you can achieve with the Pieces MCP integration.

### MCP Architecture

Pieces MCP consists of three main components that communicate via MCP for dynamic, secure context retrieval.

* **Host:** An AI-powered application (e.g., Cursor, Visual Studio Code).

* **Client:** Connectors embedded within the host, facilitating communication.

* **Server:** Small programs linking to specific tools or data sources, like PiecesOS and the `ask_pieces_ltm` tool.

### Pieces MCP Flow

Let’s take a look at the Pieces + MCP flow as you’d experience it in a familiar development environment:

    User sends a prompt via an AI tool (e.g., [Cursor](/products/mcp/cursor)).

    The MCP client within Cursor identifies relevant context servers (PiecesOS).

    The MCP server fetches relevant data from Pieces LTM-2.7.

    Context is returned and utilized by the AI to respond effectively, and the LLM provides a context-rich response.

***

*Pieces MCP —> GitHub Copilot*

***

## Getting Started

Explore how quickly MCP enhances your productivity by delivering deep, personalized context directly to your AI-driven coding flow.

To begin using Pieces MCP, [install and launch PiecesOS](/products/core-dependencies/pieces-os/manual-installation) on your system, then follow our integration documentation for setting up the MCP server within your favorite IDE or tool:

### One-Click Install

If you use Cursor, VS Code, or Claude Desktop, connect Pieces with one click from Pieces Desktop (`Settings` → `MCP` → `MCP Connections`). Ensure [PiecesOS is running](/products/core-dependencies/pieces-os) and [Long-Term Memory is enabled](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine) first.

For **Claude Desktop**, Pieces includes everything needed to connect; no extra software to install. See [Claude Desktop](/products/mcp/claude-desktop) for the restart prompt and Linux Snap/Flatpak notes.

<mcp-install-badges platforms="cursor,vscode" />

### Setup Tools

* [Advanced Configuration](/products/mcp/mcp-remote): manual setup for apps that need a helper connection (Raycast, Zed, OpenClaw, and similar). Claude Desktop one-click does not need this.
* [ngrok Setup](/products/mcp/ngrok-setup): share PiecesOS for remote access

### Platform Integrations

* [Pieces MCP + Cursor](/products/mcp/cursor)

* [Pieces MCP + Claude Desktop](/products/mcp/claude-desktop)

* [Pieces MCP + Claude Code](/products/mcp/claude-code)

* [Pieces MCP + Claude Cowork](/products/mcp/claude-cowork)

* [Pieces MCP + GitHub Copilot](/products/mcp/github-copilot)

* [Pieces MCP + VS Code](/products/mcp/vs-code)

* [Pieces MCP + Goose](/products/mcp/goose)

* [Pieces MCP + Windsurf](/products/mcp/windsurf)

* [Pieces MCP + Zed](/products/mcp/zed)

* [Pieces MCP + JetBrains IDEs](/products/mcp/jetbrains-ides)

* [Pieces MCP + Continue.dev](/products/mcp/continue-dev)

* [Pieces MCP + Cline](/products/mcp/cline)

* [Pieces MCP + Raycast](/products/mcp/raycast)

* [Pieces MCP + Rovo Dev CLI](/products/mcp/rovo-dev-cli)

* [Pieces MCP + OpenAI Codex CLI](/products/mcp/openai-codex-cli)

* [Pieces MCP + Google Gemini CLI](/products/mcp/google-gemini-cli)

* [Pieces MCP + Amazon Q Developer](/products/mcp/amazon-q-developer)

* [Pieces MCP + ChatGPT Developer Mode](/products/mcp/chatgpt-developer-mode)

* [Pieces MCP + OpenClaw](/products/mcp/openclaw)

***

## What's Next?

The MCP ecosystem continues to expand rapidly, with more integrations and tools on the horizon.

Join the community, build your custom MCP servers, and transform how AI assists your everyday tasks.

  Stay tuned for more detailed guides, examples, and tutorials coming soon.

Happy Coding!

---

## Pieces MCP + Amazon Q Developer Integration
Path: /products/mcp/amazon-q-developer

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Amazon Q Developer brings your workflow context directly into AWS's AI assistant, available both as a CLI and an IDE plugin. You can ask Q about past implementations, similar code, and historical debugging context.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Amazon Q as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Amazon Q Developer

Amazon Q supports both IDE plugin and CLI configurations. The IDE uses `~/.aws/amazonq/default.json` (or the legacy `mcp.json`). Workspace settings take precedence over global settings.

### IDE Plugin Setup (Local)

Edit `~/.aws/amazonq/default.json`:

```json
{
  "servers": {
    "pieces": {
      "type": "http",
      "url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp",
      "timeout": 60
    }
  }
}
```

### CLI Setup

Configure the MCP server in the CLI:

```bash
q mcp add --name pieces --type http --url http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

### Tool Permissions

Amazon Q allows per-tool permission levels. You can configure these in the IDE settings UI after adding the server:

* **Ask** — prompts before each use
* **Always allow** — runs without prompting
* **Deny** — blocked entirely

## Using Pieces MCP Server in Amazon Q

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Amazon Q.

    Start Amazon Q (CLI or IDE).

    MCP servers load in the background; tools become available progressively.

    Ask Q: *"What Pieces tools are available?"* or *"What was I working on yesterday?"*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Edit `~/.aws/amazonq/default.json`, update the `url`, and restart Amazon Q or start a new session.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Amazon Q Developer:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Config Directory Doesn't Exist**: Create `~/.aws/amazonq/` manually.

3. **Legacy vs Current Config**: Both `default.json` and `mcp.json` are supported; `default.json` takes precedence.

4. **MCP Not Loading**: Ensure you have a recent version of Amazon Q Developer.

5. **OAuth Prompt**: Pieces does not require OAuth. Use no-auth configuration.

***

You're now set to enhance your Amazon Q Developer workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Antigravity Integration
Path: /products/mcp/antigravity

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Antigravity brings your workflow context directly into the Antigravity agent panel. With this integration, the Antigravity agent can access your long-term memory over MCP for context-aware assistance.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Antigravity as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    If you do not have PiecesOS, you can download it alongside the [Pieces Desktop App](/products/desktop/download) or [install it standalone](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation).

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Antigravity

### One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to Antigravity is through the MCP Connections feature in Pieces Desktop.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    Click the `Connect` button next to **Antigravity**. Pieces automatically writes the MCP configuration.

    If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown, then click `Retry`.

    Restart or reopen Antigravity for the configuration changes to take effect. Once connected, a green checkmark appears next to Antigravity in the MCP Connections list.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### Manual Configuration

If you prefer manual setup, add the Pieces MCP server URL to your Antigravity configuration:

```text
http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

  The port number (`39300`) may vary depending on your PiecesOS installation. Check the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) for the active MCP endpoint.

## Using Pieces MCP Server in Antigravity

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Antigravity's agent panel.

    Launch Antigravity and open the agent panel.

    Ask context-rich questions about your workflow, such as:
    * *"What was I working on yesterday?"*
    * *"Show me the code changes I made related to authentication."*
    * *"What did my team discuss about the API redesign?"*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Antigravity:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Confirm LTM Engine Activation**: Make sure the [Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine).

3. **Check Connection Status**: In Pieces Desktop, go to Settings → MCP → MCP Connections and verify that Antigravity shows a green checkmark.

4. **Restart After Configuration**: Antigravity may need to be restarted after configuration changes.

5. **Review MCP Endpoint**: Double-check the MCP endpoint URL and port number in your configuration.

***

You're now set to enhance your Antigravity workflow with powerful context retrieval through Pieces MCP.

---

## Pieces MCP + ChatGPT Developer Mode Integration
Path: /products/mcp/chatgpt-developer-mode

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with ChatGPT Developer Mode brings your workflow context directly into ChatGPT in your browser. ChatGPT Developer Mode requires a **remote HTTPS URL**—localhost will not work. You must expose PiecesOS via [ngrok](/products/mcp/ngrok-setup) or another HTTPS proxy first.

  **Remote HTTPS required:** ChatGPT Developer Mode cannot use localhost. You must expose PiecesOS via ngrok or another HTTPS tunnel before adding the connector.

  **Plans required:** ChatGPT Developer Mode is available on Pro, Plus, Business, Enterprise, and Education plans. Status: Beta.

## Prerequisites

There are **three** prerequisites for integrating Pieces with ChatGPT Developer Mode:

    Ensure you have a Pro, Plus, Business, Enterprise, or Education ChatGPT plan.

    PiecesOS must be running locally. This is *required* for the MCP server to provide your workflow data.

    Expose PiecesOS via an ngrok tunnel to get a public HTTPS URL. The tunnel must be active when you add the connector and when you use ChatGPT. See [ngrok Setup](/products/mcp/ngrok-setup) for detailed instructions.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up ChatGPT Developer Mode

ChatGPT uses a Connectors UI to add MCP servers. You cannot add localhost URLs—only remote HTTPS endpoints.

### Setup Steps

    Open [chatgpt.com](https://chatgpt.com) in your browser.

    Click your **profile icon** → **Settings**.

    Go to **Connectors** in the sidebar.

    Scroll to the bottom and click `Advanced Settings`. Toggle `Developer Mode (beta)` ON.

    Return to **Connectors** and click `Create` (appears after enabling Developer Mode).

    * **Connector name:** `Pieces LTM`
    * **MCP Server URL:** `https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp`
    * **Description:** (optional) `Search and retrieve from Pieces Long-Term Memory`

    Click `Create` to save the connector.

  The URL must point to the `/mcp` endpoint path. Subdirectory paths like `/functions/v1/mcp` do not work.

## Using Pieces MCP Server in ChatGPT

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in ChatGPT.

    Start a new conversation in ChatGPT.

    Look for the **tools indicator** in the chat.

    Ask: *"What tools do you have from Pieces?"*

    Try: *"What did I work on yesterday?"* ChatGPT will use the `ask_pieces_ltm` tool to query your Long-Term Memory.

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

To update the ngrok URL after a tunnel restart:

1. Go to **Settings > Connectors**
2. Find "Pieces LTM" and click `Edit`
3. Update the MCP Server URL
4. Save

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with ChatGPT Developer Mode:

1. **Cannot Use localhost**: ChatGPT requires public HTTPS. Use ngrok or another HTTPS proxy.

2. **Connector Not Connecting**: Ensure the ngrok tunnel is running and the URL is accessible in a browser.

3. **Authentication Required**: Use no-auth mode; Pieces does not need OAuth.

4. **Tools Not Appearing**: Refresh the page after adding the connector.

5. **Developer Mode Not Visible**: Ensure you are on a supported plan (Pro/Plus/Business/Enterprise/Education).

6. **Write Actions Need Confirmation**: By default, writes require manual approval in ChatGPT.

***

You're now set to enhance your ChatGPT workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Claude Code Integration
Path: /products/mcp/claude-code

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Claude Code brings your workflow context directly into the Claude Code CLI and VS Code extension. Claude Code is Anthropic's developer-focused AI tool for coding tasks. Setup is simple: add Pieces via the CLI, and it's automatically available in the extension.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Claude Code as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Claude Code

There are three ways to set up Pieces MCP for Claude Code: use the one-click setup in Pieces Desktop, use the Pieces CLI, or add the server manually via the Claude CLI.

### One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to Claude Code is through the MCP Connections feature in Pieces Desktop.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    Click the `Connect` button next to **Claude Code**. Pieces automatically writes the MCP configuration.

    If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown, then click `Retry`.

    Once connected, a green checkmark appears next to Claude Code in the MCP Connections list. The configuration is now available in both the Claude Code CLI and VS Code extension.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### Method 1: CLI Install

The Pieces CLI can automatically configure Pieces MCP for Claude Code—no manual config editing required.

    Install the [Pieces CLI](/products/cli/get-started) if you haven't already.

    In your terminal, run:

    ```bash
    pieces mcp setup
    ```

    A platform selection menu appears with options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate to *Claude Code*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

### Method 2: Manual Setup via Claude CLI

Claude Code supports adding MCP servers via the CLI. Servers added via `claude mcp add` are automatically available in the Claude Code VS Code extension—no additional setup needed.

### Local Setup (Streamable HTTP — recommended)

Run in your terminal:

```bash
claude mcp add --transport http pieces http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

### Local Setup (SSE)

```bash
claude mcp add --transport sse pieces http://localhost:39300/model_context_protocol/2024-11-05/sse
```

### Project-Scoped Setup

To make Pieces MCP available only for the current project (stored in `.mcp.json` at project root):

```bash
claude mcp add --transport http --scope project pieces http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

### Managing Servers

```bash
# List all configured servers
claude mcp list

# Remove a server
claude mcp remove pieces

# Show server details
claude mcp get pieces
```

## Using Pieces MCP Server in Claude Code

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Claude Code.

    Run `claude` in your terminal, or open a project in the Claude Code VS Code extension.

    Ask: *"What MCP tools do you have from Pieces?"* Pieces LTM tools should be listed.

    Ask context-rich questions about your workflow. For example: *"What patterns did I use in my last React component?"* or *"Show me the authentication flow I implemented yesterday."*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

To update the URL, remove and re-add the server:

```bash
claude mcp remove pieces
claude mcp add --transport http pieces https://NEW_URL/model_context_protocol/2025-03-26/mcp
```

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Claude Code:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system. Test with: `curl http://localhost:39300/.well-known/version`

2. **Transport Error**: Try switching between `--transport http` and `--transport sse`.

3. **VS Code Extension Not Seeing Tools**: Restart VS Code after adding via CLI.

4. **Config Location**: User scope uses `~/.claude.json`; project scope uses `.mcp.json` at project root.

***

You're now set to enhance your Claude Code workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Claude Cowork Integration
Path: /products/mcp/claude-cowork

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Claude Cowork brings your workflow context directly into Anthropic's autonomous task automation agent. Claude Cowork is a general-purpose task automation agent that runs within Claude Desktop—it reads, writes, and organizes files, executes multi-step tasks, and works across your filesystem.

With Pieces MCP connected, Cowork can use your Long-Term Memory as context while executing tasks—like generating standups from yesterday's work or creating summary documents from your captured workflow data.

  **Plans required:** Claude Cowork requires Pro, Max, Team, or Enterprise subscription. **Status:** Research preview (launched January 2026, Windows added February 2026).

## Prerequisites

    Claude Cowork runs inside Claude Desktop. Install Claude Desktop first.

    Ensure you have Pro, Max, Team, or Enterprise subscription.

    PiecesOS must be installed and running. Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu).

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Connecting Pieces MCP to Claude Cowork

Cowork uses the **same connection as Claude Desktop**. Prefer one-click setup in Pieces Desktop, where Pieces saves Claude Desktop's settings for you and you do not need to install anything else.

### Option 1: One-Click via Pieces Desktop (Recommended for local use)

    In Pieces Desktop, open `Settings` → `MCP`, then click `Connect` next to **Claude Desktop**. Follow the [Claude Desktop guide](/products/mcp/claude-desktop) if you need the full walkthrough (including Linux quit-first and restart prompts).

    Use `Restart Claude Desktop now` when prompted so Cowork picks up the shared connection.

### Option 2: Via Connectors UI (Pro/Max/Team/Enterprise, for remote URLs)

For remote access, you need a public HTTPS URL. Set up [ngrok](/products/mcp/ngrok-setup) or another tunnel first.

    Open Claude Desktop.

    Go to **Settings > Connectors**.

    Click `Add custom connector` and enter your ngrok URL:
    ```plaintext
    https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp
    ```

    Save and restart Claude Desktop.

### Option 3: Advanced (manual config file)

Use this only if you cannot use one-click `Connect` and need to edit Claude's settings file by hand. See [Advanced Configuration](/products/mcp/mcp-remote) for details.

Install the helper package with a pinned version:

```bash
npm install -g mcp-remote@0.1.38
```

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "http://localhost:39300/model_context_protocol/2024-11-05/sse"
      ]
    }
  }
}
```

See the [Claude Desktop guide](/products/mcp/claude-desktop) and [Advanced Configuration](/products/mcp/mcp-remote) for full details.

## Using Pieces Tools in Claude Cowork

Once connected, start a Cowork session and Pieces LTM tools are available alongside file system access.

**Example tasks:**

* *"Use my Pieces Long-Term Memory to find what I worked on yesterday and write a standup to `~/Desktop/standup.md`"*
* *"Search my Pieces memory for everything I've captured about the authentication redesign and create a summary document in my project folder"*
* *"Use my Pieces audio transcriptions from today's meetings and create a meeting notes file with key decisions and action items"*

## Key Differences from Claude Chat

| Feature | Claude Chat | Claude Cowork |
|---------|-------------|---------------|
| File access | No | Yes (designated folder) |
| Task parallelism | No | Yes (sub-agents) |
| Autonomous execution | No | Yes |
| MCP tools | Yes | Yes |
| Session continuity | Per-conversation | Per-task (no cross-session memory) |

## Verification

    Open Claude Desktop and start a Cowork session (look for the folder/file access UI).

    Ask: *"What Pieces tools are available?"*

    For example: *"Search my Pieces memory for my recent work on [project name] and write a status update to my Desktop"*

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Claude Cowork:

    Ensure you have a Pro, Max, Team, or Enterprise plan.

    Restart Claude Desktop after config changes.

    Confirm the Pieces server is configured in Claude Desktop—Cowork shares Desktop's config.

    Windows support was added February 10, 2026—update Claude Desktop.

***

You're now set to enhance your Claude Cowork workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Claude Integration
Path: /products/mcp/claude-desktop

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Claude Desktop or Claude Code is a powerful way to bring your workflow context directly into your AI assistant.

With this integration, you'll have a Claude agent that knows more about your projects than just the files you copy and paste.

You can ask questions about prior work, like *"What decision did I make in last week's sprint review?"* and instantly reuse that context without searching through notes or commits.

Learn how to integrate the Pieces MCP into Claude Desktop or Claude Code by following the steps below.

  It is imperative that you download and/or update <a target="_blank" href="https://claude.ai/download">Claude Desktop</a> to the latest, most up-to-date version to ensure compatibility with Pieces MCP.

## Prerequisites

There are **two** main things you need to do to connect Pieces with Claude as an MCP:

    Ensure PiecesOS is installed and running. This lets the MCP server connect with your workflow data and share context with Claude.

    If you don't have [PiecesOS](/products/core-dependencies/pieces-os/manual-installation), you can download it with the [Pieces Desktop App](/products/desktop/download) or get it separately [here](https://pieces.app/download).

    To let the MCP server use your workflow context, you need to turn on the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or [the PiecesOS Quick Menu in your toolbar.](/products/core-dependencies/pieces-os/quick-menu)

## Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting up Pieces MCP for Claude Desktop

Connecting Claude Desktop used to mean installing extra tools on your machine. Pieces now includes everything you need on macOS, Windows, and Linux. Pick Claude Desktop, click `Connect`, and Pieces writes the setup for you.

The recommended path is one-click setup in Pieces Desktop. Advanced options (Pieces CLI or editing a config file by hand) are below if you need them.

### One-Click Setup via Pieces Desktop (Recommended)

Connect Claude Desktop from *MCP Connections* in Pieces Desktop. Pieces configures Claude for you using a connection helper that ships inside PiecesOS; nothing else to install.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    On Linux, especially Snap or Flatpak installs, quit Claude Desktop before connecting. If Claude is still running, it can overwrite the settings Pieces just saved. Pieces notices when Claude Desktop is already open and walks you through quitting first.

    Click the `Connect` button next to **Claude Desktop**. Pieces saves the connection settings for you. You do not need to install anything else.

    When the new settings need a restart, Pieces shows a *Restart Claude Desktop* prompt. Click `Restart Claude Desktop now` to relaunch Claude, or `Got it` if you will restart yourself. Once connected, a green checkmark appears next to Claude Desktop in the MCP Connections list.

  Snap and Flatpak installs are supported. As long as Claude Desktop points at the PiecesOS executable, the MCP connection works with no additional install.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### Advanced: Manual Configuration (Direct MCP Command)

This method edits Claude Desktop’s MCP configuration file to point at a CLI command that starts the Pieces MCP server. Use one-click setup above unless you need a custom path.

  With this method, the Claude MCP config points to the Pieces CLI executable and runs `pieces mcp start` whenever Claude starts. This is different from using the CLI to configure Claude directly (the next advanced method).

    Make sure the [Pieces CLI](/products/cli) is installed.

    In your terminal, run the following commands:

    ```powershell
    py -m pip install --upgrade pip
    py -m pip install pieces-cli
    ```

    Next, confirm that the installation was successful:

    ```powershell
    pieces --version
    ```

    The executable path depends on your OS and Python installation method.

    For example:

    1. **Windows →** `C:\Users\\AppData\Local\Programs\Python\Python3XX\Scripts\pieces`

    2. **macOS →** `usr/local/bin/pieces`

    3. **Linux →** `home//.local/bin/pieces`

    Claude Desktop stores its MCP configuration in a user-specific location for each OS.

    Depending on your platform, this might be:

    1. **Windows →** `C:\Users\\AppData\Roaming\Claude\claude_desktop_config.json`

    2. **macOS →** `~/Library/Application Support/Claude/claude_desktop_config.json`

    3. **Linux →** `~/.config/Claude/claude_desktop_config.json`

    If the file exists → open it in a text editor.\
    If it doesn’t exist → create it manually in that directory.

    Paste the following JSON into your Claude config file, adjusting the path to your `pieces` executable for your OS:

    ```json
    {
      "mcpServers": {
        "pieces": {
          "command": "/Users//venv/bin/pieces",
          "args": [
            "--ignore-onboarding",
            "mcp",
            "start"
          ]
        }
      }
    }
    ```

    **Path examples by OS:**
    * **macOS/Linux** — `/Users//venv/bin/pieces` or `~/.local/bin/pieces`
    * **Windows** — `C:\Users\\AppData\Local\Programs\Python\Python3XX\Scripts\pieces.exe`

    Fully quit and reopen Claude Desktop.

    Start prompting Claude. If properly set up, you will be prompted by Claude to enable and allow (on a case-by-case basis, or via `always allow`) Claude to pass prompts through the `ask_pieces_ltm` tool.

    This utility communicates with PiecesOS and your local repository of saved workflow context.

### Advanced: Using the Pieces CLI

This method uses the Pieces CLI to automatically set up and configure Pieces MCP for Claude Desktop.

    Run the following commands to install the Pieces CLI if you haven’t already done so.

    ```powershell
    -m pip install --upgrade pip
    py -m pip install pieces-cli
    ```

    Run:

    ```powershell
    pieces mcp setup
    ```

    A platform selection menu appears with these options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate, hover over *Claude Desktop* or *Claude Code*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install the MCP.

    Once the command completes, restart Claude Desktop and confirm that the Pieces MCP server is connected.

## Adding Pieces MCP to Claude Code

Configure Pieces MCP for Claude Code to make it available across all your projects.

  This section is specifically for Claude Code and does not work with Claude Desktop. For Claude Desktop, use the methods above.

    In your terminal, run the following command:

    ```bash
    claude mcp add --scope user pieces --transport http http://localhost:39300/model_context_protocol/2025-03-26/mcp
    ```

    The `--scope user` flag makes Pieces MCP available globally across all your Claude Code projects, rather than just the current directory.

    Open any project in Claude Code and start asking context-aware questions about your workflow, such as:

    * *"What patterns did I use in my last React component?"*
    * *"Show me the authentication flow I implemented yesterday."*

  Claude Code will use the `ask_pieces_ltm` tool to pull relevant context from PiecesOS.

## Using Pieces MCP Server

Once integrated, you can utilize Pieces LTM directly in Claude Desktop or Claude Code.

1. **Start a Conversation**\
   Launch a new conversation in Claude Desktop or open a project in Claude Code.

2. **Prompt with Context**\
   Ask Claude questions about prior work or files (e.g., *"What was I doing for work yesterday?"*).

3. **Verify MCP Tools Are Active**\
   If configured correctly, Claude will automatically use the `ask_pieces_ltm` tool to pull relevant context.

## Troubleshooting

If you're experiencing issues integrating [Pieces MCP](/products/mcp) with Claude Desktop or Claude Code:

1. **Verify PiecesOS Status**\
   Ensure PiecesOS is actively running on your system.

2. **Confirm LTM Engine Activation**\
   [Long-Term Memory (LTM-2.7)](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine) must be enabled in PiecesOS.

3. **Restart Claude Desktop**\
   After one-click Connect, use `Restart Claude Desktop now` in the Pieces prompt (or fully quit and reopen Claude) so the new config loads.

4. **Linux: Quit Claude Before Connecting**\
   If Connect fails or the connection disappears on Linux, quit Claude Desktop completely, connect again from *MCP Connections*, then restart Claude. See [Linux troubleshooting](/products/meet-pieces/troubleshooting/linux) for Snap and Flatpak notes.

5. **Single MCP Instance**\
   Avoid running multiple Pieces MCP instances in different apps simultaneously.

6. **Check MCP Server Status in Claude**\
   Use the Developer Console (`Ctrl+Shift+I`) to confirm connection messages.

7. **Review Advanced Configuration**\
   If you used a manual JSON edit, ensure paths are correct.\
   If you used the Pieces CLI, rerun:

   ```powershell
   pieces mcp setup
   ```

***

You’re now ready to enhance your Claude Desktop experience with the Pieces MCP, enabling powerful, context-aware conversations and seamless access to your workflow history.

---

## Pieces MCP + Cline Integration
Path: /products/mcp/cline

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Cline brings your workflow context directly into VS Code. Cline is an AI coding agent extension that maintains its own MCP configuration—it does **not** read from `.vscode/mcp.json`.

  **Use SSE, not Streamable HTTP:** Cline has known compatibility issues with Streamable HTTP transport. Use the **SSE endpoint** for the most reliable connection.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Cline as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Cline

Cline stores its MCP configuration in a separate file: `~/.cline/data/settings/cline_mcp_settings.json`.

### Setup via Extension UI

    Open VS Code with the Cline extension installed.

    Click the `Cline` icon in the activity bar, then click the `gear icon` or navigate to **MCP Servers** in the Cline panel.

    Click `Add Server`, select **SSE** as the transport type, and enter:
    ```plaintext
    http://localhost:39300/model_context_protocol/2024-11-05/sse
    ```

    Name it `pieces` and save.

### Manual JSON Config

Edit `~/.cline/data/settings/cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "pieces": {
      "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse",
      "type": "sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Auto-Approve Specific Tools

To skip confirmation prompts for specific Pieces tools:

```json
{
  "mcpServers": {
    "pieces": {
      "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse",
      "type": "sse",
      "autoApprove": ["ask_pieces_ltm", "workstream_summaries_full_text_search"]
    }
  }
}
```

## Using Pieces MCP Server in Cline

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Cline.

    Open the Cline panel in VS Code.

    Check the **MCP** section for `pieces` with a connected status.

    Ensure Cline is in agent mode (not regular chat mode) so it can use MCP tools.

    Ask Cline to search your LTM. For example: *"What was I working on yesterday?"*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Edit the config JSON and save. Cline reloads the server list from disk without requiring a VS Code restart.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Cline:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Cline Uses Its Own Config**: Cline reads from `~/.cline/data/settings/cline_mcp_settings.json`, not `.vscode/mcp.json`.

3. **Use SSE, Not Streamable HTTP**: Cline has compatibility issues with Streamable HTTP—use the SSE endpoint (`/model_context_protocol/2024-11-05/sse`).

4. **Use Agent Mode**: Ensure Cline is in agent mode, not regular chat mode.

5. **Server Disconnected**: Restart VS Code if the server shows as disconnected.

***

You're now set to enhance your Cline workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Continue.dev Integration
Path: /products/mcp/continue-dev

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Continue.dev brings your workflow context directly into your editor. Continue.dev is an open-source coding assistant available as a VS Code or JetBrains extension.

  **Agent mode required:** MCP servers in Continue.dev only work in **agent mode**. They are not available in regular chat or plan modes.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Continue.dev as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Continue.dev

Continue.dev uses **YAML** configuration with an `mcpServers` array. The recommended location is `.continue/config.yaml` at your project root (you can commit it to version control for team sharing).

### Config File Location

| Scope | Path |
|-------|------|
| **Workspace (recommended)** | `.continue/config.yaml` at project root |
| **Alternative JSON** | `.continue/mcpServers/mcp.json` |

### Local Setup (Streamable HTTP — recommended)

Create or edit `.continue/config.yaml`:

```yaml
mcpServers:
  - name: Pieces LTM
    type: streamable-http
    url: http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

### Local Setup (SSE)

```yaml
mcpServers:
  - name: Pieces LTM
    type: sse
    url: http://localhost:39300/model_context_protocol/2024-11-05/sse
```

  Use `streamable-http` (with hyphen), not `streamableHttp` or `http`. The type value is case-sensitive.

## Using Pieces MCP Server in Continue.dev

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Continue.dev.

    Switch Continue.dev to **agent mode** in the UI. MCP servers are only available in agent mode.

    Check the available tools—Pieces LTM tools should appear.

    Ask the agent to search your Long-Term Memory. For example: *"What was I working on yesterday?"*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Edit your `config.yaml` (or JSON file), update the `url`, and switch to agent mode. Continue picks up the change on the next agent session.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Continue.dev:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Use Agent Mode**: MCP tools do not appear in regular chat—you must be in **agent mode**.

3. **YAML Parse Error**: Check indentation; YAML is whitespace-sensitive.

4. **Type Value**: Use `streamable-http` (with hyphen), not `streamableHttp` or `http`.

5. **Server Not Connecting**: Check the PiecesOS port (39300-39333) and URL format.

***

You're now set to enhance your Continue.dev workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Cursor Integration
Path: /products/mcp/cursor

***

## Get Started

Integrating the Pieces MCP with Cursor is a **powerful** and **efficient** way to bring your daily workflow context directly into your IDE.

With this integration, you'll have an in-IDE chatbot that *knows more about your project* than just the active file or project folder.

You can ask questions about additional workflow information, like whether a coworker fixed a bug in last week's PR, and then use that solution to fix a similar error in your code without having to look through old chat logs or GitHub commits.

Learn how to integrate the Pieces MCP into Cursor by following the steps below.

  It is imperative that you download and/or update your version of Cursor to the **latest, most up-to-date version** to ensure compatibility with Pieces MCP.

## Prerequisites

There are **\[2]** primary prerequisites for integrating Pieces with Cursor as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your personal repository of workflow data and pass context through to the Cursor chat agent.

    If you do not have PiecesOS, you can download it alongside the [Pieces Desktop App](/products/desktop/download) or [install it standalone](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) here.

    For the MCP server to interact with your workflow context, you must enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

### Getting the MCP Endpoint for PiecesOS

To use Pieces MCP with Cursor, you'll need the MCP endpoint from PiecesOS:

```markdown
http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

  Keep in mind that the **specific port** (i.e., `39300`) PiecesOS is running on **may vary**.

To find the current MCP endpoint with the active instance of PiecesOS (including the current port number), open the PiecesOS Quick Menu and expand the **Model Context Protocol (MCP) Servers** tab.

There, you can click once to copy the MCP endpoint, which includes the active PiecesOS port number.

You can also do this in the Pieces Desktop App by opening the **Settings** view and clicking **Model Context Protocol (MCP).**

## Setting Up Cursor

There are three ways to set up Pieces MCP for Cursor: use the one-click setup in Pieces Desktop, use the Pieces CLI, or configure manually.

### One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to Cursor is through the MCP Connections feature in Pieces Desktop.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    Click the `Connect` button next to **Cursor**. Pieces automatically writes the MCP configuration to Cursor's global MCP config file.

    If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown (e.g., install Node.js), then click `Retry`.

    Restart Cursor for the configuration changes to take effect. Once connected, a green checkmark appears next to Cursor in the MCP Connections list.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### One-Click Install Badge

Install Pieces MCP in Cursor with a single click. Ensure [PiecesOS is running](/products/core-dependencies/pieces-os) and [Long-Term Memory is enabled](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine) before clicking.

<mcp-install-badges platforms="cursor" />

### Method 2: CLI Install

The Pieces CLI can automatically configure Pieces MCP for Cursor—no manual config editing required.

    Install the [Pieces CLI](/products/cli/get-started) if you haven't already.

    In your terminal, run:

    ```bash
    pieces mcp setup
    ```

    A platform selection menu appears with options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate to *Cursor*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

### Method 3: Manual Configuration (Global MCP)

To set up the Pieces MCP, you can edit the `.json` settings configuration file from within **Cursor Settings.**

    Navigate to **Cursor Settings**, then to the `MCP` section.

    Add a new global MCP server by clicking `Add new global MCP server` and inserting the following `.json` snippet (adjust port if necessary) in the `.json` file that opens:

    ```json
    {
      "mcpServers": {
        "Pieces": {
          "url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
        }
      }
    }
    ```

    Save the configuration file.

    Make sure to refresh the MCP server window by clicking the **refresh icon** and ensure that there is a *green dot* indicating that the server is running and functioning without errors.

    Once the MCP server is set up, make sure to change the chat mode to *Agent* mode. This should automatically utilize the `ask_pieces_ltm` tool.

## Using Pieces MCP Server in Cursor

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Cursor through the built-in chat agent.

    Open the right-hand chat panel by toggling it at the top-right corner, or use the shortcut `⌘+i` (macOS) or `ctrl+i` (Windows/Linux).

    Make sure that you're using the *Cursor Agent* mode, not *Ask* or *Manual.* This is required to use the `ask_pieces_ltm` tool to access context from LTM.

    From this point, you can begin prompting. If PiecesOS was previously installed, try testing out the Pieces MCP integration with a prompt like, “What was I doing for work yesterday?” and click `Use Tool` when prompted.

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

### Configuring Rules

If you want to customize the specific output provided by the Cursor chatbot through working with the `ask_pieces_ltm` tool, you can manually adjust the *rules* for inside of **Cursor Settings.**

To do this, open up **Cursor Settings,** click `Rules`, then add new *User Rules.*

Here’s an example of a straightforward set of rules tailored to a specific use case and work flow:

## Troubleshooting

If you’re experiencing issues integrating Pieces MCP with Cursor, follow these troubleshooting steps:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system. MCP integration requires PiecesOS to be operational.

2. **Confirm LTM Engine Activation**: Make sure the [Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine), as this engine aggregates context necessary for Cursor to retrieve accurate results.

3. **Single MCP Instance:** Make sure that you aren't testing multiple instances of the Pieces MCP server in different IDEs. This cross-contamination conflict with several MCP instances running on the same port can cause issues in different development environments.

4. **Use Agent Mode in Chat**: Cursor must be in *Agent Mode*, not *Ask Mode*, to access the `ask_pieces_ltm` tool. Switch to Agent Mode to enable full MCP integration.

5. **Turn Off Auto-Select**: If Cursor is having issues finding the Pieces tool, de-select `auto-select` and select an individual Agent, such as `claude-3.5-sonnet`.

6. **Check MCP Server Status**: If you’re encountering messages such as “Sorry, I can’t do this,” your MCP server may not be properly configured or running.

7. **Go to** `settings.json` **in Cursor:** Confirm the MCP server status shows "running" (it may say "start" or "pause" otherwise). Restart the server if necessary and inspect terminal outputs for error messages.

8. **Review Configuration Details**: Double-check the MCP endpoint URL and the port number in Cursor settings to ensure accuracy. You can find the current MCP endpoint URL in the Pieces Desktop App under **Settings** → **Model Context Protocol (MCP)**, or in the PiecesOS Quick Menu. It is usually formatted as:

```text
http://localhost:{port_number}/model_context_protocol/2025-03-26/mcp
```

  Ignore any red `.JSON` blobs in the MCP Settings view. The **Chat** pane is the source of truth—if your Pieces queries return formatted summaries there, the integration is functioning normally.

***

You’re now set to enhance your workflow with powerful context retrieval through Pieces MCP integrated seamlessly into Cursor. Happy coding!

---

## Pieces MCP + GitHub Copilot
Path: /products/mcp/github-copilot

***

## Get Started

Connecting [Pieces MCP](/products/mcp) to **GitHub Copilot** enhances context-aware coding by linking your current task with past work.

This integration allows GitHub Copilot to provide insights like past implementations and peer-reviewed solutions.

You can ask context-rich questions, and Copilot can find answers from your local development history without searching through commits or messages.

Follow the steps below to integrate the Pieces MCP with GitHub Copilot for smarter, personalized AI assistance.

## Prerequisites

There are **\[2]** prerequisites for integrating Pieces with GitHub Copilot as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your personal repository of workflow data and pass context through to the GitHub Copilot chat agent.

    If you do not have PiecesOS, you can download it alongside the [Pieces Desktop App](/products/desktop/download) or [install it standalone](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) here.

    For the MCP server to interact with your workflow context, you must enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the detailed set-up instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

### SSE Endpoint

To use Pieces MCP with GitHub Copilot, you first need the Server-Sent Events (SSE) endpoint from PiecesOS:

```markdown
http://localhost:39300/model_context_protocol/2024-11-05/sse
```

  Keep in mind that the **specific port** (i.e., `39300`) PiecesOS is running on **may vary**.

To find the current SSE endpoint with the active instance of POS (including the current port number), open the PiecesOS Quick Menu and expand the **Model Context Protocol (MCP) Servers** tab.

There, you can copy the SSE endpoint with one click, which includes the active PiecesOS port number.

You can also do this in the Pieces Desktop App by opening the **Settings** view and clicking **Model Context Protocol (MCP).**

## Setting Up GitHub Copilot

You can now use the Pieces MCP with both Visual Studio Code and Visual Studio Code (Insider Edition).

Follow the steps below to get started—or watch the video below for a set-up tutorial and live demo.

### One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to GitHub Copilot is through the MCP Connections feature in Pieces Desktop.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    Click the `Connect` button next to **GitHub Copilot**. Pieces automatically writes the MCP configuration to VS Code's settings.

    If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown, then click `Retry`.

    Restart Visual Studio Code for the configuration changes to take effect. Once connected, a green checkmark appears next to GitHub Copilot in the MCP Connections list.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### via Visual Studio Code UI

Adding the Pieces MCP in the built-in MCP menu is the easiest method to setting up your Pieces MCP server and allows you to have the best experience while using the Pieces MCP.

    Open Visual Studio Code and launch the Command Palette by pressing `Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux.

    In the Command Palette, type **MCP: Add Server** and select the command when it appears.

    Select `HTTP (sse)` as the server type when requested.

    Paste your SSE URL into the provided field.

    For Pieces, use:

    ```plaintext
    http://localhost:39300/model_context_protocol/2024-11-05/sse
    ```

      Remember to grab the specific SSE URL (with the *active* PiecesOS port) from either the PiecesOS or Pieces Desktop App MCP menu.

    When prompted to add a new MCP server, enter a name for your server, such as ‘Pieces\` or something easy to remember.

    Then, you can select the `User Settings` option to save the MCP server configuration in your VS Code user settings, so it can be accessed globally across different workspaces—or choose `Workspace Settings` to use it explicitly in your open project.

    Save your configuration. Your VS Code `settings.json` file should now include an entry similar to the example below:

    ```json
    {
      "mcpServers": {
        "Pieces": {
          "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse"
        }
      }
    }
    ```

    Your GitHub Copilot chat, as long as the chat mode is in *Agent* mode, will now see Pieces as an MCP and automatically utilize the `ask_pieces_ltm` tool on-query.

### via Global MCP Configuration

You can manually add the MCP to your MCP settings `.JSON` by following the steps below.

    Click the **Settings Icon** on the bottom left of your IDE and select `Settings` from the list.

    In the VS settings, search for MCP in the search bar at the top of the page. The MCP section will appear—then, select `Edit in settings.json`.

    Replace the entire file, assuming you have no others, with the PiecesOS MCP server `.json`.

    ```json
    {
      "mcpServers": {
        "Pieces": {
          "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse"
        }
      }
    }
    ```

    Save the configuration.

    Your GitHub Copilot chat, as long as it’s in Agent mode, will now see PiecesOS as an MCP.

## Using Pieces MCP Server in GitHub Copilot

Once integrated, you can utilize Pieces LTM directly in Visual Studio Code.

    Launch the GitHub Copilot chat interface in Visual Studio Code by clicking the Copilot icon, or by using `⌘+ctrl+i` (macOS) `ctrl+alt+i` (Windows/Linux).

    Change the Copilot mode from *Ask* to *Agent*.

    Enter your prompt, and click the **send** icon or press `return` (macOS) or `enter` (Windows/Linux) to send your query to the Copilot.

      Do not add the `ask_pieces_ltm` tool as *context* to the conversation. If you are running the chat in *Agent* mode—which is required for the Pieces MCP integration to operate successfully—it will automatically utilize this tool.

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Troubleshooting Tips

If you’re experiencing issues integrating Pieces MCP with GitHub Copilot, follow these troubleshooting steps:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system. MCP integration requires PiecesOS to be operational.

2. **Confirm LTM Engine Activation**: Make sure the [Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine), as this engine aggregates context necessary for GitHub Copilot to retrieve accurate results.

3. **Use Chat Participant**: In VS Code, invoke the Pieces MCP tools by mentioning `@pieces` in GitHub Copilot Chat. Ensure you're using GitHub Copilot Chat (not inline completions) for full MCP integration.

4. **Single MCP Instance:** Make sure that you aren’t testing multiple instances of the Pieces MCP server in different IDEs. This cross-contamination conflict with the SSE and several MCP instances running on the same port can cause issues in different development environments.

5. **Check MCP Server Status**: If you’re encountering messages such as “Sorry, I can’t do this,” your MCP server may not be properly configured or running.

6. **Go to** `settings.json` **in Visual Studio Code:** Confirm the MCP server status shows "running" (it may say "start" or "pause" otherwise). Restart the server if necessary and inspect terminal outputs for error messages.

7. **Review Configuration Details**: Double-check the MCP endpoint URL and the port number in your VS Code MCP configuration menu to ensure accuracy. You can find the current SSE endpoint URL in the Pieces Desktop App under **Settings** → **Model Context Protocol (MCP)**, or in the PiecesOS Quick Menu. It is usually formatted as:

```scss
http://localhost:{port_number}/model_context_protocol/{version}/sse
```

***

You're now ready to improve your workflow with powerful context retrieval using Pieces MCP, seamlessly integrated into Visual Studio Code with GitHub Copilot. Happy coding!

---

## Pieces MCP + Google Gemini CLI Integration
Path: /products/mcp/google-gemini-cli

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Google Gemini CLI brings your workflow context directly into the Gemini command-line agent. Gemini CLI supports stdio, SSE, and Streamable HTTP.

  **Key distinction:** For HTTP servers, use `httpUrl`; for SSE servers, use `url`—they are different fields in the Gemini config.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Gemini CLI as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Google Gemini CLI

### One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to Google Gemini CLI is through the MCP Connections feature in Pieces Desktop.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    Click the `Connect` button next to **Google Gemini CLI**. Pieces automatically writes the MCP configuration to Gemini's settings file.

    If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown, then click `Retry`.

    Once connected, a green checkmark appears next to Google Gemini CLI in the MCP Connections list. Start a new `gemini` session to use Pieces MCP.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### Manual Configuration

Gemini CLI stores its MCP configuration in `~/.gemini/settings.json`. Workspace settings override user settings.

#### Config File Location

| Scope | Path |
|-------|------|
| **User (global)** | `~/.gemini/settings.json` |
| **Workspace** | `YOUR_PROJECT/.gemini/settings.json` |

### Local Setup (Streamable HTTP — recommended)

Edit `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "pieces": {
      "httpUrl": "http://localhost:39300/model_context_protocol/2025-03-26/mcp",
      "timeout": 30000
    }
  }
}
```

### Local Setup (SSE)

For SSE, use `url` instead of `httpUrl`:

```json
{
  "mcpServers": {
    "pieces": {
      "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse",
      "timeout": 30000
    }
  }
}
```

## Using Pieces MCP Server in Gemini CLI

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Gemini CLI.

    Run `gemini` in your terminal.

    Gemini discovers and registers tools from MCP servers on startup. Ask: *"What Pieces tools are available?"*

    Ask context-rich questions about your workflow.

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Edit `~/.gemini/settings.json`, update the URL, and start a new Gemini CLI session.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Gemini CLI:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **HTTP vs SSE Key**: Use `httpUrl` for Streamable HTTP, `url` for SSE—they are different fields.

3. **Settings File Not Found**: Create `~/.gemini/settings.json` manually.

4. **Tools Not Discovered**: Restart Gemini CLI after editing settings.

5. **OAuth Prompt**: Pieces does not require OAuth. Dismiss if prompted.

***

You're now set to enhance your Gemini CLI workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Goose Integration
Path: /products/mcp/goose

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Goose is a powerful way to bring your daily workflow context directly into your command line or desktop interface.

With this integration, you'll have a *command-line AI assistant* that knows more about your coding activities than just the current project.

You can ask Pieces about bug fixes in your code discussed in your team channel, inquire about similar code you've worked on, or prompt it to double-check that your new code meets the criteria your coworker suggested—and much more.

Learn how to integrate the Pieces MCP into Goose by following the steps below.

## Prerequisites

There are **\[2]** primary prerequisites for integrating Pieces with Goose as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory (LTM-2.7)** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your personal repository of workflow data and pass context through to the Goose interface.

    For the MCP server to interact with your workflow context, you must enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

    If you haven't installed Goose yet, follow the <a target="_blank" href="https://goose-docs.ai/docs/getting-started/installation">installation instructions</a>.

### Installing PiecesOS & Configuring Permissions

Follow the detailed set-up instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

### SSE Endpoint

To use Pieces MCP with Goose, you'll need the Server-Sent Events (SSE) endpoint from PiecesOS:

```scss
http://localhost:39300/model_context_protocol/2024-11-05/sse
```

  Keep in mind that the **specific port** (i.e., `39300`) PiecesOS is running on **may vary**.

To find the up-to-date SSE endpoint with the active instance of POS (including the current port number), open the PiecesOS Quick Menu and expand the **Model Context Protocol (MCP) Servers** tab.

There, you can copy the SSE endpoint with one click, which includes the active PiecesOS port number.

You can also find this in the Pieces Desktop App by opening the [Settings](/products/desktop/configuration) view and clicking **Model Context Protocol (MCP)**.

## Setting Up Goose with Pieces MCP

Follow the steps below to set up Pieces MCP with Goose, either through the command line or desktop application.

Make sure you have the latest version of Goose installed to ensure compatibility with Pieces MCP.

  You will need to go through additional set-up steps (such as setting up your LLM provider) which involves setting up your host, choosing your model, using your API key, and more.

  Read the <a target="_blank" href="https://goose-docs.ai/docs/getting-started/installation">official, open-source documentation</a> on completing these set-up steps.

### via CLI

Setting up the Pieces MCP through the Goose Command Line Interface is straightforward.

    Open your terminal (macOS/Linux) or CMD (Windows) and run:

    ```bash
    goose configure
    ```

    From the list of available options, choose `Add Extension`.

    Select `Remote Extension` from the list of extension types.

    Name your extension `Pieces` or something similar.

    From PiecesOS, the Desktop App, or this documentation, obtain the Pieces MCP SSE endpoint URL and paste it into your terminal.

    ```bash
    http://localhost:39300/model_context_protocol/2024-11-05/sse
    ```

      Adjust the port number if your local instance of PiecesOS runs on a different one.

    You’ll be prompted to enter a value for timing out the tool in case of an error or repeated *hangtime*. The default value is `300`—you can enter that value, or another.

    Lastly, you’ll be prompted to add a description or additional environment variables—these are not required. Select `No` to both if you want to proceed.

    You’ll now see a message like `Added Pieces Extension` or similar, depending on the name you’ve attributed to the extension. You can use `goose list extensions` to verify and check the list of integrated extensions within Goose.

  You may see an error message when configuring Goose, like:

  > <mark>Warning: Goose installed, but /Users/you/.local/bin is not in your PATH…</mark>

  You can fix this issue by adding `export PATH=”$HOME/.local/bin:$PATH”` to your your `~/.zshrc` or `~/.bashrc`.

  Then, reload with `source ~/.zshrc` and start a Goose session by using `goose` from anywhere.

## Using Pieces MCP with Goose

Once the integration is set up, you can start using Pieces Long-Term Memory through Goose.

### Starting a Conversation

    Simply type `goose` in your terminal to start a new conversation:

    ```bash
    goose
    ```

    This will open a prompt where you can interact with Goose, which now has access to your Pieces Long-Term Memory.

    You can now start interacting with the Pieces MCP server.

    Try using this prompt:

    ```plaintext
    I need a status update for what I was working on yesterday. Create a report with 5 bullet points based off the most important activities, and give each one a brief description. Use time stamps to accurately report how long I spent working on group of tasks/topics.
    ```

      This prompt is formulated for users already familiar with PiecesOS who use the Long-Term Memory Engine.\
      \
      If you are a first-time user, it is recommended that you launch PiecesOS and enable LTM, then allow some time for data capture before using this prompt for a desirable output.

    Here’s a response using that exact same prompt inside of Goose using the Pieces MCP integration:

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Toggling & Removing Pieces MCP

To remove the Pieces MCP for Goose, you can follow the same process you otherwise would for removing any Goose extension.

    Open up your terminal and type `goose configure`, then press `return` (macOS) or `enter` (Windows/Linux).

    Use your keyboard’s **up** and **down** arrow keys to navigate down to `Toggle Extensions`.

    Using arrow keys to navigate the list, press `space` (macOS/Windows/Linux) when the carrot is pointing towards your targeted extension.

    Then, press `return` (macOS) or `enter` (Windows/Linux) to confirm changes.

    Use `goose configure` to re-enter the configuration menu.

    Use your arrow keys to navigate to `Remove Extensions`, then, using the same `space` and `enter/return` process, first *toggle* then *confirm* your removal of the Pieces MCP extension.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Goose, follow these troubleshooting steps:

1. **Verify PiecesOS Status:** Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os) on your system. MCP integration requires PiecesOS to be operational.

2. **Confirm LTM Engine Activation:** Make sure the [Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine), as this engine aggregates context necessary for Goose to retrieve accurate results.

3. **Single MCP Instance:** Make sure that you aren't testing multiple instances of the Pieces MCP server in different IDEs. This *cross-contamination conflict* with the SSE and several MCP instances running on the same port can cause issues in different development environments.

4. **Check MCP Server Status:** If you're encountering messages such as "Sorry, I can't do this," your MCP server may not be properly configured or running.

5. **Verify Port Configuration:** Double-check the MCP endpoint URL and the port number in your Goose configuration to ensure accuracy. You can find the current SSE endpoint URL in the Pieces Desktop App under **Settings → Model Context Protocol (MCP)**, or in the PiecesOS Quick Menu. It is usually formatted as:

```plaintext
http://localhost:{port_number}/model_context_protocol/{version}/sse
```

6. **Mac PATH Issues:** If you're having trouble with Goose CLI on macOS, try manually adding it to your PATH:

```bash

```

7. **Restart Services:** If problems persist, try restarting both PiecesOS and Goose, then reconfigure the extension with the current port number.

8. **Use the Correct Mode:** You can experience a blockage of LTM data if you are using *any other chat mode* than **Auto** mode. Make sure to use `goose configure` to change chat modes to avoid issues.

***

You're now set to enhance your workflow with powerful context retrieval through Pieces MCP integrated seamlessly into Goose. Happy coding!

---

## Pieces MCP + JetBrains IDEs Integration
Path: /products/mcp/jetbrains-ides

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with JetBrains IDEs brings your workflow context directly into IntelliJ IDEA, PyCharm, WebStorm, GoLand, and other JetBrains editors. The AI Assistant can access your past work, similar code, and historical context.

  **Minimum version:** JetBrains 2025.2 or later is required for MCP support. SSE has limited/deprecated support—use Streamable HTTP for best results.

## Prerequisites

There are **two** prerequisites for integrating Pieces with JetBrains as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up JetBrains IDEs

JetBrains provides an MCP setup UI in Settings. You do not need to edit config files manually.

### Setup via Settings UI

    Go to **Settings** (`Cmd+,` on macOS, `Ctrl+Alt+S` on Windows/Linux).

    Go to **Tools > AI Assistant > Model Context Protocol (MCP)**.

    Click `+` (Add) to create a new server. In the **New MCP Server** dialog, enter the Pieces MCP URL:
    ```plaintext
    http://localhost:39300/model_context_protocol/2025-03-26/mcp
    ```

    Select **Streamable HTTP** as the transport type. Optionally set a working directory.

    Click `OK` to apply your changes.

### Brave Mode (Auto-Execute Tools)

By default, JetBrains prompts for confirmation before executing tools. To enable auto-execution:

Go to **Settings > Tools > AI Assistant > MCP > Brave Mode = enabled**

  Use Brave Mode with caution in production environments.

## Using Pieces MCP Server in JetBrains

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in the AI Assistant panel.

    Open the **AI Assistant** panel in your JetBrains IDE.

    Check that Pieces tools appear in the available tools list.

    Ask the AI Assistant to query your Pieces Long-Term Memory. For example: *"What was I working on yesterday?"*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Go to **Settings > Tools > AI Assistant > MCP**, select the `pieces` server, click `Edit`, update the URL, and apply.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with JetBrains:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Update JetBrains**: MCP support requires JetBrains 2025.2 or later. If the MCP option is not visible, update your IDE.

3. **Use Streamable HTTP**: JetBrains has limited/deprecated SSE support. Use the Streamable HTTP endpoint (`/model_context_protocol/2025-03-26/mcp`).

4. **AI Not Using Tools Automatically**: Enable **Brave Mode** in MCP settings if the AI is not executing tools automatically.

***

You're now set to enhance your JetBrains workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## MCP Bridge
Path: /products/mcp/mcp-remote

## MCP Bridge

Some apps, including Raycast, Zed, and OpenClaw, need a small helper to talk to Pieces. This page covers that advanced, manual setup. Use it when your app is not available in one-click Connect.

  **Claude Desktop** does not need this page for the usual setup. Use one-click `Connect` in Pieces Desktop (`Settings` → `MCP`), where Pieces includes the connection helper and saves the settings for you. See [Claude Desktop](/products/mcp/claude-desktop).

  For other apps, the easiest path is often the Pieces CLI: run `pieces mcp setup` and select your platform. Use the manual steps below only when your app is not listed or you need a custom address (for example, a remote URL).

## Easiest Option: Pieces CLI

The [Pieces CLI](/products/cli/get-started) automatically configures MCP for supported platforms—no manual config editing required.

    In your terminal, run `pieces mcp setup`.

    Use the arrow keys to select your MCP client (VS Code, Cursor, Claude Desktop, Windsurf, Claude Code, Raycast, or Warp) and press Enter.

    The CLI updates the platform's config file and confirms when Pieces MCP is enabled.

  Ensure PiecesOS is running and LTM is enabled. Run `pieces mcp status` to verify your setup.

## Manual Setup

Use manual setup when your client isn't supported by the CLI (e.g Zed and OpenClaw) or when you need to point at a remote PiecesOS URL (see [Tunneling](/products/mcp/ngrok-setup)).

### Prerequisites

    PiecesOS must be installed and running. Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu).

    <pos-download-guide />

    `mcp-remote` requires Node.js 18+. Ensure Node.js and `npm` are in your PATH.

    Install `mcp-remote` globally with a pinned version so your MCP client runs a known, verified binary instead of fetching from the registry at runtime:

    ```bash
    npm install -g mcp-remote@0.1.38
    ```

      Using `npx` to run `mcp-remote` downloads the package from npm each time. For better security, use a locally installed, version-pinned binary as shown above.

### Pieces MCP Endpoints

PiecesOS exposes two endpoints. For `mcp-remote`, use the **SSE** endpoint—it works reliably across all stdio clients:

| **Endpoint** | **URL** | **Use for** |
|--------------|---------|--------------|
| **SSE** | `http://localhost:39300/model_context_protocol/2024-11-05/sse` | mcp-remote, stdio clients |
| **Streamable HTTP** | `http://localhost:39300/model_context_protocol/2025-03-26/mcp` | Clients that support HTTP natively |

  The port may vary. Find yours in the PiecesOS Quick Menu under **Model Context Protocol (MCP) Servers**, or in Pieces Desktop under **Settings** → **Model Context Protocol (MCP)**.

### Configuring Your Client

    Edit `mcp-config.json` (open via **Manage MCP Servers** → **Show Config File in Finder**):

    ```json
    {
      "mcpServers": {
        "pieces": {
          "command": "mcp-remote",
          "args": [
            "http://localhost:39300/model_context_protocol/2024-11-05/sse"
          ]
        }
      }
    }
    ```

    See [Raycast integration](/products/mcp/raycast) for full setup.

    Zed uses `context_servers` (not `mcpServers`). Edit your Zed `settings.json`:

    ```json
    {
      "context_servers": {
        "pieces": {
          "command": {
            "path": "mcp-remote",
            "args": [
              "http://localhost:39300/model_context_protocol/2024-11-05/sse"
            ],
            "env": {}
          },
          "settings": {}
        }
      }
    }
    ```

    See [Zed integration](/products/mcp/zed) for full setup.

    Prefer one-click `Connect` for [Claude Desktop](/products/mcp/claude-desktop), since Cowork shares that setup. Use the steps below only for advanced manual configuration.

    ```json
    {
      "mcpServers": {
        "pieces": {
          "command": "mcp-remote",
          "args": [
            "http://localhost:39300/model_context_protocol/2024-11-05/sse"
          ]
        }
      }
    }
    ```

    Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). See [Claude Cowork](/products/mcp/claude-cowork) for full setup.

    Edit `~/.openclaw/workspace/config/mcporter.json`:

    ```json
    {
      "mcpServers": {
        "pieces": {
          "command": "mcp-remote",
          "args": [
            "http://localhost:39300/model_context_protocol/2024-11-05/sse"
          ]
        }
      }
    }
    ```

    See [OpenClaw integration](/products/mcp/openclaw) for full setup.

For remote setups, use the ngrok URL instead of localhost. See [Tunneling](/products/mcp/ngrok-setup).

### Useful Flags

| **Flag** | **Purpose** |
|----------|-------------|
| `--allow-http` | Allow HTTP URLs; use only in trusted private networks |
| `--debug` | Write verbose logs to `~/.mcp-auth/{hash}_debug.log` |
| `--silent` | Suppress default logs |

## Tips & Troubleshooting

Ensure PiecesOS is running. Test the endpoint: `curl http://localhost:39300/.well-known/version`. Restart your MCP client after changing config, then ask: *"What tools do you have from Pieces?"* or *"What did I work on yesterday?"*

### Troubleshooting

1. **mcp-remote: command not found** — Run `npm install -g mcp-remote@0.1.38` and ensure the global npm bin directory is in your PATH.

2. **Bridge not connecting** — Verify PiecesOS is running and the port is correct. Test with `curl http://localhost:39300/.well-known/version`.

3. **Wrong config key** — Zed uses `context_servers`; Raycast, Claude Cowork, and OpenClaw use `mcpServers`.

4. **Port mismatch** — Check the PiecesOS Quick Menu or Settings → Model Context Protocol (MCP) for the current endpoint.

5. **Stale credentials** — If you have persistent issues, try `rm -rf ~/.mcp-auth` and restart the client.

***

## Next Steps

* [Raycast](/products/mcp/raycast) — macOS launcher with Pieces LTM
* [Zed](/products/mcp/zed) — Zed editor with Pieces LTM
* [Claude Cowork](/products/mcp/claude-cowork) — Claude Cowork with Pieces LTM
* [OpenClaw](/products/mcp/openclaw) — OpenClaw with Pieces LTM
* [Tunneling](/products/mcp/ngrok-setup) — Expose PiecesOS for remote MCP access

---

## Tunneling
Path: /products/mcp/ngrok-setup

## Tunneling with ngrok

Some MCP integrations cannot use localhost. [ChatGPT Developer Mode](/products/mcp/chatgpt-developer-mode) runs in the browser and requires a **remote HTTPS URL**. [OpenClaw](/products/mcp/openclaw) and [Claude Cowork](/products/mcp/claude-cowork) may need to reach PiecesOS from another machine. [ngrok](https://ngrok.com) creates a public HTTPS URL that forwards traffic to your local PiecesOS instance. The tunnel is active only while ngrok is running, and ngrok handles TLS certificates automatically.

  Exposing PiecesOS publicly via ngrok should only be used when required. For local-only integrations (Cursor, VS Code, Claude Desktop on the same machine), use localhost directly.

## Prerequisites

    PiecesOS must be installed and running on the machine where you will run ngrok. Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu).

    <pos-download-guide />

    Sign up at [ngrok.com](https://ngrok.com) and get your [auth token](https://dashboard.ngrok.com/get-started/your-authtoken) from the dashboard.

## Installing ngrok

    Install with Homebrew:

    ```bash
    brew install ngrok
    ```

    Install via the [Windows App Store](https://apps.microsoft.com/detail/9mvs1j51gmk6) or [download directly](https://ngrok.com/download).

    On Debian/Ubuntu:

    ```bash
    curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
      | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
      && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
      | sudo tee /etc/apt/sources.list.d/ngrok.list \
      && sudo apt update \
      && sudo apt install ngrok
    ```

Verify the installation:

```bash
ngrok help
```

## Setting Up the Tunnel

    Add your auth token so ngrok can create tunnels:

    ```bash
    ngrok config add-authtoken YOUR_AUTH_TOKEN
    ```

    Replace `YOUR_AUTH_TOKEN` with the token from your [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken).

    PiecesOS typically runs on port **39300**. To find yours: open the **PiecesOS Quick Menu** (system tray or menu bar) → expand **Model Context Protocol (MCP) Servers** → copy the endpoint (it includes the port). You can also find it in Pieces Desktop under **Settings** → **Model Context Protocol (MCP)**.

    Ensure PiecesOS is running, then:

    ```bash
    ngrok http 39300
    ```

    Replace `39300` with your actual port if different. ngrok will display a forwarding URL like `https://abc123.ngrok-free.app`. Copy the **HTTPS** URL.

## MCP Endpoint URLs

Append the correct path to your ngrok URL:

| **Endpoint** | **Path** | **Use for** |
|--------------|----------|--------------|
| **Streamable HTTP (MCP)** | `/model_context_protocol/2025-03-26/mcp` | ChatGPT, Claude Cowork Connectors UI, OpenClaw (MCPorter + `mcp-remote`) |
| **SSE** | `/model_context_protocol/2024-11-05/sse` | MCP Bridge and other clients that require the legacy SSE endpoint |

Example: if ngrok shows `https://abc123.ngrok-free.app`, use `https://abc123.ngrok-free.app/model_context_protocol/2025-03-26/mcp` for ChatGPT, Claude Cowork, or OpenClaw, or `https://abc123.ngrok-free.app/model_context_protocol/2024-11-05/sse` for MCP Bridge.

## Configuring Your MCP Client

### ChatGPT Developer Mode

    Open [chatgpt.com](https://chatgpt.com) → **Settings** → **Connectors**.

    Click `Create` and add a new connector.

    Set **MCP Server URL** to: `https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp`

    Save. The tunnel must be running whenever you use ChatGPT with Pieces.

See [ChatGPT Developer Mode integration](/products/mcp/chatgpt-developer-mode) for full setup.

### Claude Cowork (Connectors UI)

    Open Claude Desktop → **Settings** → **Connectors**.

    Click `Add custom connector`.

    Enter: `https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp`

    Save and restart Claude Desktop.

See [Claude Cowork integration](/products/mcp/claude-cowork) for full setup.

### OpenClaw (Remote)

Install `mcp-remote` globally (`npm install -g mcp-remote@0.1.38`), then edit `~/.openclaw/workspace/config/mcporter.json`:

```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp"
      ]
    }
  }
}
```

See [OpenClaw integration](/products/mcp/openclaw) for full setup.

## Tips & Troubleshooting

The tunnel is active only while `ngrok http 39300` is running. Start ngrok when you need remote access, or keep it running in a dedicated terminal for regular use.

  Free ngrok accounts get a random subdomain each time you start a tunnel. If the URL changes, update the MCP Server URL in your client (ChatGPT: Settings → Connectors; Claude Cowork: Settings → Connectors; OpenClaw: edit `~/.openclaw/workspace/config/mcporter.json`).

### Troubleshooting

    Ensure PiecesOS is running and listening on the port. Test locally: `curl http://localhost:39300/.well-known/version`

    Use the port from the PiecesOS Quick Menu or **Settings** → **Model Context Protocol (MCP)**. It may not be 39300.

    Verify ngrok is running and the HTTPS URL loads in a browser. Free plans may show an ngrok interstitial page on first visit; that's normal.

    Use the exact paths: `/model_context_protocol/2025-03-26/mcp` or `/model_context_protocol/2024-11-05/sse`. Paths like `/functions/v1/mcp` do not work.

    Restart PiecesOS and ngrok. Ensure no firewall is blocking the port.

### Security

ngrok exposes PiecesOS to the internet—use it only when required. Keep your ngrok auth token private. For private network access, consider [Tailscale](https://tailscale.com) or a VPN instead of a public tunnel.

***

## Next Steps

Configure your MCP client with the ngrok URL: [ChatGPT Developer Mode](/products/mcp/chatgpt-developer-mode), [Claude Cowork](/products/mcp/claude-cowork), [OpenClaw](/products/mcp/openclaw), or [MCP Bridge](/products/mcp/mcp-remote).

---

## Pieces MCP + OpenAI Codex CLI Integration
Path: /products/mcp/openai-codex-cli

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with OpenAI Codex CLI brings your workflow context directly into the Codex command-line agent. Codex uses **TOML** (not JSON) for its configuration.

  **Minimum version:** Codex CLI 0.2.0 or later is required for MCP support.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Codex CLI as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up OpenAI Codex CLI

### One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to Codex is through the MCP Connections feature in Pieces Desktop.

    In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`.

    Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons.

    Click the `Connect` button next to **Codex**. Pieces automatically writes the MCP configuration to Codex's config file, enabling both the CLI and IDE extension.

    If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown, then click `Retry`.

    Once connected, a green checkmark appears next to Codex in the MCP Connections list. Start a new Codex session to use Pieces MCP.

  To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

### Manual Configuration

Codex stores its MCP configuration in `~/.codex/config.toml`. The file format is **TOML**, not JSON.

#### Config File Location

| Scope | Path |
|-------|------|
| **User (global)** | `~/.codex/config.toml` |
| **Project** | `.codex/config.toml` at project root (trusted projects only) |

### Local Setup (Streamable HTTP — recommended)

Edit `~/.codex/config.toml`:

```toml
[mcp_servers.pieces]
url = "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60
```

### Optional: Filter Specific Tools

To only expose specific Pieces tools:

```toml
[mcp_servers.pieces]
url = "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
enabled_tools = ["ask_pieces_ltm", "workstream_summaries_full_text_search"]
```

## Using Pieces MCP Server in Codex CLI

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Codex.

    Run `codex` in your terminal.

    Codex announces available MCP tools on startup. Ask: *"What Pieces tools are available?"*

    Ask context-rich questions about your workflow.

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Edit `~/.codex/config.toml`, update the `url`, and run a new Codex session.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Codex CLI:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system. Verify the URL responds.

2. **Use TOML, Not JSON**: Codex uses TOML format. Creating a `.json` file will not work.

3. **Update Codex**: MCP support requires Codex CLI 0.2.0 or later.

4. **Config File Not Found**: Create `~/.codex/config.toml` manually.

5. **Timeout Errors**: Increase `startup_timeout_sec` or `tool_timeout_sec` if you encounter timeouts.

***

You're now set to enhance your Codex CLI workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + OpenClaw Integration
Path: /products/mcp/openclaw

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with OpenClaw brings your workflow context directly into this open-source continuous AI agent runtime. OpenClaw (formerly ClawdBot, formerly Moltbot) runs as a persistent Node.js service—unlike chatbots that respond to one-off prompts, it runs 24/7, executing tasks proactively via cron jobs and event listeners.

With Pieces MCP connected, OpenClaw gains access to your Long-Term Memory. It can autonomously query your past work, generate standups, monitor recent activity, and surface relevant context without you asking.

## Prerequisites

    Install Node.js 18 or later.

    Clone and configure OpenClaw following the [setup instructions in the OpenClaw getting started](https://docs.openclaw.ai/start/getting-started).

    Install the [Pieces Long-Term Memory (MCP) skill](https://clawhub.ai/jackrosspieces/pieces-mcp) on ClawHub. It is the full agent-facing guide for OpenClaw: MCP-only URLs, tunnels when PiecesOS runs on another machine, `mcporter.json`, `mcp-remote`, gateway restart, and troubleshooting.

    PiecesOS must be running locally (port 39300-39333). Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu).

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up OpenClaw

OpenClaw executes MCP tools via **MCPorter**, its built-in MCP management layer. Edit `~/.openclaw/workspace/config/mcporter.json`.

The [official Pieces MCP skill for OpenClaw](https://clawhub.ai/jackrosspieces/pieces-mcp) documents **MCP-only** integration: point `mcp-remote` at the **`/mcp`** endpoint (`/model_context_protocol/2025-03-26/mcp`), not the legacy **`/sse`** path. That matches how OpenClaw and MCPorter expect to bridge Pieces.

Install `mcp-remote` globally with a pinned version for security:

```bash
npm install -g mcp-remote@0.1.38
```

See [MCP Bridge](/products/mcp/mcp-remote) for why we recommend a locally installed binary over `npx`.

### Local setup (MCP with mcp-remote — recommended)

When OpenClaw and PiecesOS run on the same machine, use the localhost MCP URL with the mcp-remote bridge:

```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
      ]
    }
  }
}
```

### Remote setup (ngrok or other HTTPS tunnel)

When OpenClaw runs on a different machine than PiecesOS, expose PiecesOS (port 39300) with a tunnel and use the **same MCP path** on your tunnel base URL:

```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "https://YOUR_NGROK_URL.ngrok-free.app/model_context_protocol/2025-03-26/mcp"
      ]
    }
  }
}
```

See [Tunneling](/products/mcp/ngrok-setup) for tunnel setup. For step-by-step tunnel checks, `curl` validation, and gateway restarts, follow the [ClawHub skill](https://clawhub.ai/jackrosspieces/pieces-mcp).

## Example Use Cases

Once Pieces MCP is connected to OpenClaw, you can automate workflows like:

**Autonomous daily standup:** Schedule OpenClaw to run every morning, query yesterday's workstream summaries, and post a formatted standup to your Slack or Teams channel.

**Meeting prep:** Before a calendar event, OpenClaw searches audio transcriptions and workstream summaries for context related to the meeting topic and drafts a brief for you.

**Automated debugging log:** When OpenClaw detects a production alert, it queries recent workstream events for error-related content and creates a pieces_memory entry with the incident context.

## Verification

    Launch or connect to your OpenClaw instance as you normally do.

    Ask via your connected messaging platform: *"What Pieces tools do you have?"* Pieces LTM tools should appear in the list.

    Try: *"What did I work on yesterday?"*—OpenClaw should call `ask_pieces_ltm`.

## Security Note

OpenClaw can run with `permissionMode: 'bypassPermissions'` to execute tools autonomously. When combined with Pieces MCP write tools (like `create_pieces_memory`), this is powerful but should be used carefully. Consider:

* Running OpenClaw in Docker with limited filesystem access
* Disabling write tools in MCPorter if running fully autonomously
* Monitoring execution logs

## Updating

Edit `~/.openclaw/workspace/config/mcporter.json`, update the URL, then restart the OpenClaw gateway (for example `openclaw gateway restart` from `~/.openclaw/workspace`, as in the [official skill](https://clawhub.ai/jackrosspieces/pieces-mcp)).

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with OpenClaw:

    Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

    If the config is missing, create `~/.openclaw/workspace/config/` manually.

    Run `npm install -g mcp-remote@0.1.38` and ensure the global npm bin directory is in your `PATH`.

    After editing MCPorter config, restart the gateway (`openclaw gateway restart` per the [ClawHub skill](https://clawhub.ai/jackrosspieces/pieces-mcp)) so OpenClaw picks up the Pieces MCP server.

    If you use ngrok or another tunnel, restart the tunnel when the URL changes and update the URL in MCPorter config. See [ngrok Setup](/products/mcp/ngrok-setup) for details.

***

You're now set to enhance your OpenClaw workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## MCP Prompting
Path: /products/mcp/prompting

## Prompting Guide

The Pieces MCP server exposes a set of tools that let your agent query Long-Term Memory with natural-language questions and traverse the Pieces memory graph across summaries, events, people, and captured sources. Some tools also help the agent move between memory context and your local file system so it can connect what you have worked on to what is on disk.

The primary entry point is the `ask_pieces_ltm` tool, which most agents call automatically when a prompt needs personal context from your workflow. You do not need to invoke tools directly, your client decides which tools to call based on your prompt.

Right now, we recommend setting up the Pieces MCP within [Cursor](/products/mcp/cursor) or [VS Code with GitHub Copilot](/products/mcp/github-copilot).

### Basic Queries

You can start prompting with simple user queries, such as:

1. "What was I working on yesterday?"

2. "Ask Pieces what files I modified last week."

3. “What Google docs were I referring to this morning before my stand-up meeting?”

### Advanced Parameters

To refine your queries further, consider using parameters such as time ranges, application sources, or specific topics.

* **Time Ranges**—Try prompting using time ranges, such as “yesterday” or “April 2nd through April 6th” for more accurate, time-based questions.

* **Application Sources**—Ask Pieces to provide contextual data from specific sources, like “Stack Overflow pages I visited on Chrome” or “meeting notes from Notion” to refine source data.

* **Topics**—If your work is spread across different projects, get more accurate responses by including topic-specific keywords, like “Show recent work I’ve done on the authentication migration project”.

### Combining Parameters

Combine parameters for precise queries—like mixing topic keywords with a specific application name within the scope of a timeframe.

Here are some examples of multi-parameter prompting:

1. "What JavaScript code related to API authentication did I write in VS Code yesterday?"

2. "Find notes on database changes between Monday and Wednesday."

## Controlling Agent Responses with Pieces MCP

You can also control the agent's actions directly through your prompts, allowing Pieces MCP to first retrieve relevant data from your context, then instruct the agent to perform specific tasks or updates.

Here’s an example:

* **Prompt:***"What is the package version update that Mark asked me to make? Make the relevant update in my package manifest."*

* **Outcome:** Pieces MCP retrieves Mark's requested package version update from your context, then automatically directs the agent to apply this update to your `package.json` manifest.

## Effective Prompting Tips

Sometimes, it can be challenging to create a prompt that gets you exactly what you need.

  When using Pieces, especially with its large, on-device repository of personalized workflow data, it's best to use more specific prompts.

Use these techniques and tips to refine your prompting:

* Clearly specify *timeframes*.

* Mention relevant *applications*.

* Include *technical keywords* relevant to your query.

* Refer explicitly to *open files* when relevant.

* Ask *follow-up questions* for refined results.

  If you want to read more information on LTM prompting, [check out this guide.](/products/quick-guides/ltm-prompting)

### Examples of Effective Prompts

Check out these example prompts to see how to effectively combine parameters for specific AI outputs using the Pieces MCP for your Agent.

    * “Show examples of React Context usage."

    * "What was my last implementation of API error handling?"

    * “Have I previously optimized rendering performance in React components?”

    * "Track the evolution of the dashboard feature."

    * "Review documented challenges with the payment system."

    * “Show the decisions made around UI updates for the onboarding flow.”

    * "Find recent bookmarks about Kubernetes."

    * “What resources did I save recently related to Python decorators?”

    * “Show notes taken about GraphQL in March.”

    * “Show code review comments related to database indexing.”

    * “Did we finalize naming conventions for the latest API endpoints?”

    * “What feedback did I leave on recent pull requests?”

---

## Pieces MCP + Raycast Integration
Path: /products/mcp/raycast

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Raycast brings your workflow context directly into your macOS launcher. Raycast does not natively support HTTP-based MCP servers—you need an **stdio-to-HTTP bridge** (like [mcp-remote](/products/mcp/mcp-remote)) to connect to PiecesOS.

  **macOS only:** Raycast is currently available only on macOS.

## Prerequisites

There are **three** prerequisites for integrating Pieces with Raycast:

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

    The `mcp-remote` bridge requires Node.js. Ensure Node.js and `npm` are installed.

    Install `mcp-remote` globally with a pinned version for security:

    ```bash
    npm install -g mcp-remote@0.1.38
    ```

    See [MCP Bridge](/products/mcp/mcp-remote) for why we recommend a locally installed binary over `npx`.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Raycast

There are two ways to set up Pieces MCP for Raycast: use the Pieces CLI for automatic configuration, or configure manually with the mcp-remote bridge.

### Method 1: CLI Install (Recommended)

The Pieces CLI can automatically configure Pieces MCP for Raycast—no manual config editing required.

    Install the [Pieces CLI](/products/cli/get-started) if you haven't already.

    In your terminal, run:

    ```bash
    pieces mcp setup
    ```

    A platform selection menu appears with options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate to *Raycast*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

### Method 2: Manual Configuration with mcp-remote Bridge

Raycast uses `mcpServers` in its config. All servers must use `type: "stdio"` because Raycast does not support HTTP natively.

### Config File Location

Open Raycast, search for **Manage MCP Servers**, then press **Cmd+K** and select **Show Config File in Finder** to locate `mcp-config.json`.

### Local Setup (same machine as PiecesOS)

Add to `mcp-config.json`:

```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "http://localhost:39300/model_context_protocol/2024-11-05/sse"
      ]
    }
  }
}
```

### Adding via Raycast UI

    Open Raycast (Cmd+Space or your hotkey) and search for **Install Server**.

    * **Name:** pieces
    * **Type:** stdio
    * **Command:** mcp-remote
    * **Args:** `http://localhost:39300/model_context_protocol/2024-11-05/sse`

## Using Pieces MCP in Raycast

After setup, use `@pieces` in Raycast AI (Quick AI, AI Chat, or Presets) to invoke Pieces tools. Raycast automatically shows AI all available servers.

    Open Raycast AI Chat.

    Type `@pieces` to mention the Pieces MCP server.

    Ask: *"What tools do you have from Pieces?"* or *"What was I working on yesterday?"*

## Updating

Edit `mcp-config.json` (found via **Show Config File in Finder**), update the URL in `args`, and restart Raycast AI.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Raycast:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **mcp-remote: command not found**: Run `npm install -g mcp-remote@0.1.38` and ensure the global npm bin directory is in your PATH.

3. **Bridge Not Connecting**: Verify the SSE endpoint responds: `curl http://localhost:39300/.well-known/version`

4. **Config File Location**: Use Raycast's **Manage MCP Servers > Show Config File in Finder** to locate the exact path.

***

You're now set to enhance your Raycast workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Rovo Dev CLI Integration
Path: /products/mcp/rovo-dev-cli

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Rovo Dev CLI brings your workflow context directly into Atlassian's AI tool. Rovo Dev CLI supports stdio, SSE, and Streamable HTTP for flexible setup.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Rovo Dev CLI as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Rovo Dev CLI

Rovo Dev CLI stores its MCP configuration in `~/.rovodev/mcp.json`. It uses a `servers` root key with a `transport` field (not `type`).

### Config File Location

| Platform | Path |
|----------|------|
| **All platforms** | `~/.rovodev/mcp.json` |

### Local Setup (Streamable HTTP — recommended)

Edit `~/.rovodev/mcp.json`:

```json
{
  "servers": {
    "pieces": {
      "name": "Pieces LTM",
      "transport": "http",
      "url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
    }
  }
}
```

### Local Setup (SSE)

```json
{
  "servers": {
    "pieces": {
      "name": "Pieces LTM",
      "transport": "sse",
      "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse"
    }
  }
}
```

### Opening the Config in Your Editor

Run this command to open the config file in your default editor:

```bash
acli rovodev mcp
```

## Using Pieces MCP Server in Rovo Dev CLI

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Rovo Dev sessions.

    Start a Rovo Dev session from your terminal.

    Run `/mcp list` to see configured servers and their status.

    Ask: *"What Pieces tools do you have?"* or *"What was I working on yesterday?"*

### Managing Servers in Interactive Mode

Within a Rovo Dev session, use the `/mcp` command to open an interactive interface showing:

* Configured servers and their status
* Available tools from each server
* Enable/disable toggles

## Updating

Edit `~/.rovodev/mcp.json` (via `acli rovodev mcp` or directly), update the URL, and restart the Rovo Dev session.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Rovo Dev CLI:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Use transport, Not type**: Rovo Dev CLI uses the `transport` key (not `type`) for the transport type.

3. **Config File Not Found**: Create `~/.rovodev/` and `~/.rovodev/mcp.json` manually if the directory does not exist.

4. **Restart Session**: Restart the Rovo Dev session after editing the config.

5. **Atlassian OAuth**: Pieces does not require Atlassian OAuth. If prompted, this is for the Atlassian Rovo MCP Server, not Pieces.

***

You're now set to enhance your Rovo Dev CLI workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + VS Code Integration
Path: /products/mcp/vs-code

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Visual Studio Code brings your workflow context directly into your editor. With this integration, your AI assistant can access past implementations, similar code, and historical debugging context—without searching through commits or notes.

## Prerequisites

There are **two** prerequisites for integrating Pieces with VS Code as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data and pass context through to VS Code.

    If you do not have PiecesOS, you can download it alongside the [Pieces Desktop App](/products/desktop/download) or [install it standalone](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) here.

    For the MCP server to interact with your workflow context, you must enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

### Getting the MCP Endpoint for PiecesOS

To use Pieces MCP with VS Code, you'll need the MCP endpoint from PiecesOS. VS Code supports Streamable HTTP (recommended) or SSE.

**Streamable HTTP (recommended):**
```plaintext
http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

**SSE (legacy):**
```plaintext
http://localhost:39300/model_context_protocol/2024-11-05/sse
```

  Keep in mind that the **specific port** (e.g., `39300`) PiecesOS is running on **may vary**.

To find the current MCP endpoint with the active instance of PiecesOS, open the PiecesOS Quick Menu and expand the **Model Context Protocol (MCP) Servers** tab. You can copy the endpoint, which includes the active port number.

You can also find this in the Pieces Desktop App by opening **Settings** and clicking **Model Context Protocol (MCP)**.

## Setting Up VS Code

There are two ways to set up Pieces MCP for VS Code: use the Pieces CLI for automatic configuration, or configure manually.

### One-Click Install

Install Pieces MCP in VS Code with a single click. Ensure [PiecesOS is running](/products/core-dependencies/pieces-os) and [Long-Term Memory is enabled](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine) before clicking.

<mcp-install-badges platforms="vscode" />

### Method 1: CLI Install (Recommended)

The Pieces CLI can automatically configure Pieces MCP for VS Code—no manual config editing required.

    Install the [Pieces CLI](/products/cli/get-started) if you haven't already.

    In your terminal, run:

    ```bash
    pieces mcp setup
    ```

    A platform selection menu appears with options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate to *VS Code*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

    For VS Code, you'll be asked to choose *User Settings* (MCP available in all projects) or *Workspace Settings* (MCP for the current project only).

### Method 2: Manual Configuration

VS Code uses a `servers` root key (not `mcpServers`) in its MCP configuration. The transport type is set with a `type` field.

### Config File Location

| Scope | Path |
|-------|------|
| **Workspace** | `.vscode/mcp.json` in your project root |
| **User (global)** | Via Settings > search "MCP Servers" |

### Local Setup (Streamable HTTP — recommended)

Add or edit `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "pieces": {
      "type": "http",
      "url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
    }
  }
}
```

### Local Setup (SSE — legacy)

```json
{
  "servers": {
    "pieces": {
      "type": "sse",
      "url": "http://localhost:39300/model_context_protocol/2024-11-05/sse"
    }
  }
}
```

### Adding via Command Palette

    Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux).

    Search for **MCP: Add Server** and select the command.

    Select **HTTP** or **SSE** as the transport type.

    Paste your MCP endpoint and name it `pieces`.

## Using Pieces MCP Server in VS Code

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in VS Code through extensions that support MCP, such as GitHub Copilot Chat.

    Open the chat interface for your MCP-enabled extension (e.g., GitHub Copilot Chat).

    If your extension has chat modes, switch to *Agent* mode so it can use the `ask_pieces_ltm` tool.

    Ask context-rich questions about your workflow. For example: *"What was I working on yesterday?"* or *"Show me previous implementations of this authentication method."*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

To update the URL, edit `.vscode/mcp.json` and save. VS Code picks up changes without a restart. You can also use **MCP: Edit Server** in the Command Palette to update the URL for the `pieces` server.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with VS Code:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Confirm LTM Engine Activation**: Make sure the [Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine).

3. **Check Config Location**: The file must be `.vscode/mcp.json` (not `.cursor/mcp.json` or `mcp.json` at root).

4. **Verify Transport Type**: Use `type: "http"` for Streamable HTTP or `type: "sse"` for SSE. Ensure you're using the correct `servers` key (not `mcpServers`).

5. **Tools Not Visible**: Ensure your MCP-enabled extension (e.g., GitHub Copilot Chat) is installed and active. Run **MCP: List Servers** to confirm `pieces` shows as connected.

***

You're now set to enhance your VS Code workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Windsurf Integration
Path: /products/mcp/windsurf

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Windsurf brings your workflow context directly into the Cascade AI panel. With this integration, Windsurf can access your past work, similar code, and historical debugging context to provide smarter, personalized assistance.

## Prerequisites

There are **two** prerequisites for integrating Pieces with Windsurf as an MCP—an active instance of **PiecesOS** and the fully-enabled **Long-Term Memory** engine.

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data and pass context through to Windsurf.

    If you do not have PiecesOS, you can download it alongside the [Pieces Desktop App](/products/desktop/download) or [install it standalone](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) here.

    For the MCP server to interact with your workflow context, you must enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

### Getting the MCP Endpoint for PiecesOS

To use Pieces MCP with Windsurf, you'll need the MCP endpoint from PiecesOS:

```plaintext
http://localhost:39300/model_context_protocol/2025-03-26/mcp
```

  Keep in mind that the **specific port** (e.g., `39300`) PiecesOS is running on **may vary**.

  Windsurf uses **`serverUrl`** (not `url`) for HTTP/remote servers—this is a Windsurf-specific key name.

## Setting Up Windsurf

There are two ways to set up Pieces MCP for Windsurf: use the Pieces CLI for automatic configuration, or configure manually.

### Method 1: CLI Install (Recommended)

The Pieces CLI can automatically configure Pieces MCP for Windsurf—no manual config editing required.

    Install the [Pieces CLI](/products/cli/get-started) if you haven't already.

    In your terminal, run:

    ```bash
    pieces mcp setup
    ```

    A platform selection menu appears with options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate to *Windsurf*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

### Method 2: Manual Configuration

Windsurf stores its MCP configuration in a global config file. Edit `~/.codeium/windsurf/mcp_config.json`:

### Local Setup (Streamable HTTP — recommended)

```json
{
  "mcpServers": {
    "pieces": {
      "serverUrl": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
    }
  }
}
```

### Adding via MCP Marketplace

    Open the Cascade panel in Windsurf.

    Click the `MCP icon` to open the MCP Marketplace.

    Search for Pieces, or click `Add custom` and enter your MCP URL.

## Using Pieces MCP Server in Windsurf

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Windsurf through the Cascade panel.

    Open the Cascade AI panel in Windsurf.

    Check the MCP tools section—Pieces LTM tools should appear. Ask Cascade: *"What Pieces tools are available?"*

    Ask context-rich questions about your workflow. For example: *"What was I working on yesterday?"* or *"Show me similar code snippets to this React component."*

  Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

## Updating

Edit `~/.codeium/windsurf/mcp_config.json`, update the `serverUrl`, then restart Windsurf.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Windsurf:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Confirm LTM Engine Activation**: Make sure the [Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine).

3. **Use serverUrl, Not url**: Windsurf requires the `serverUrl` key—using `url` will not work.

4. **Restart Windsurf**: After editing `mcp_config.json`, restart Windsurf for changes to take effect.

5. **Disable a Server**: Add `"disabled": true` to the server config object if you need to temporarily disable Pieces MCP.

***

You're now set to enhance your Windsurf workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Pieces MCP + Zed Integration
Path: /products/mcp/zed

***

## Get Started

Integrating the [Pieces MCP](/products/mcp) with Zed brings your workflow context directly into the Zed editor. Because Zed currently supports **stdio only** (not native HTTP), you'll use an stdio-to-HTTP bridge such as [mcp-remote](/products/mcp/mcp-remote) to connect to PiecesOS.

## Prerequisites

There are **three** prerequisites for integrating Pieces with Zed:

    Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data.

    Enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

    The `mcp-remote` bridge requires Node.js. Ensure Node.js and `npm` are installed.

    Install `mcp-remote` globally with a pinned version for security:

    ```bash
    npm install -g mcp-remote@0.1.38
    ```

    See [MCP Bridge](/products/mcp/mcp-remote) for why we recommend a locally installed binary over `npx`.

### Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

<pos-download-guide />

## Setting Up Zed with mcp-remote Bridge

Zed uses a custom `context_servers` key (not `mcpServers` or `servers`). Because Zed does not support HTTP MCP servers natively, you must use the `mcp-remote` bridge.

### Config File Location

| Scope | Path |
|-------|------|
| **User settings** | `~/.config/zed/settings.json` (Linux/macOS) |
| **Project settings** | `.zed/settings.json` in your project root |

### Local Setup (same machine as PiecesOS)

Add to `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "pieces": {
      "command": {
        "path": "mcp-remote",
        "args": [
          "http://localhost:39300/model_context_protocol/2024-11-05/sse"
        ],
        "env": {}
      },
      "settings": {}
    }
  }
}
```

  The port (e.g., `39300`) may vary. Find your current PiecesOS port in the PiecesOS Quick Menu under **Model Context Protocol (MCP) Servers**.

### Alternative: supergateway Bridge

You can also use `supergateway` instead of `mcp-remote`. Install with `npm install -g supergateway`, then use `"path": "supergateway"` and `"args": ["--sse", "http://localhost:39300/model_context_protocol/2024-11-05/sse"]`. For security, prefer a locally installed binary over `npx`.

## Using Pieces MCP Server in Zed

Once integrated, you can utilize [Pieces LTM](/products/core-dependencies/pieces-os#ltm-27) directly in Zed's AI assistant panel.

    Open the AI assistant panel in Zed.

    Ask: *"What context tools do you have?"* Pieces LTM tools should be available.

    Ask context-rich questions about your workflow, such as: *"What was I working on yesterday?"*

## Updating

Edit your `settings.json`, update the URL in the `args` array, and save. Zed reloads context servers on config change.

## Troubleshooting

If you're experiencing issues integrating Pieces MCP with Zed:

1. **Verify PiecesOS Status**: Ensure [PiecesOS is actively running](/products/core-dependencies/pieces-os/troubleshooting) on your system.

2. **Use context_servers**: Zed uses `context_servers`, not `mcpServers` or `servers`.

3. **mcp-remote: command not found**: Run `npm install -g mcp-remote@0.1.38` and ensure the global npm bin directory is in your PATH.

4. **Bridge process crashes**: Check that PiecesOS is running and the SSE endpoint responds. You can test with: `curl http://localhost:39300/.well-known/version`

5. **No tools visible**: Restart Zed; ensure `mcp-remote` is in your PATH.

***

You're now set to enhance your Zed workflow with powerful context retrieval through Pieces MCP. Happy coding!

---

## Getting to Know Pieces
Path: /products/meet-pieces

## Introducing Pieces

This documentation provides a high-level overview of the [Pieces Desktop App](/products/desktop) and [PiecesOS](/products/core-dependencies/pieces-os), with quick-start and troubleshooting guides for <a target="_blank" href="/products/meet-pieces/macos-installation-guide">macOS</a>, <a target="_blank" href="/products/meet-pieces/windows-installation-guide">Windows</a>, and <a target="_blank" href="/products/meet-pieces/linux-installation-guide">Linux</a> to help you get started as quickly as possible.

Let’s answer a few basic questions:

### What is Pieces?

At its core, Pieces is an all-in-one productivity tool that helps you work *smarter*, not harder, by keeping track of your activities, important information, and conversations—all in one place, with features like Long-Term Memory, Timeline, and Conversational Chat.

There are **\[3]** core pillars of Pieces functionality:

1. [Long-Term Memory Engine (LTM-2.7)](/products/core-dependencies/pieces-os/long-term-memory): A powerful, AI-powered live context framework that understands what you’re working on across your entire development workflow. The LTM-2.7 helps by outsourcing the burden of memory and retrieval from the developer to AI to maximize space for creativity driven by human intent.

2. [Pieces Timeline](/products/desktop/timeline): Your central workspace for accessing workflow context captured by Long-Term Memory. Generate summaries, review past activities, browse captured memories, and interact with your workflow history—all in one place.

3. [Conversational Search](/products/desktop/conversational-search): An intelligent assistant that helps with answering questions about your workflow, generating content, and providing guidance using the model you choose—with filters for apps, time ranges, and modalities, plus optional file and folder context.

### Who is Pieces For?

Everyone. 

Pieces is an *Artificial Memory* tool that remembers your real-world activity and productivity context with Large Language Models (LLMs). It surfaces useful information, answers questions other AI tools can't, keeps you focused, and gives you an edge on the competition.

Pieces is an **excellent productivity option for users of all levels** and across various fields, including front-end developers, data scientists, DevOps engineers, and students.

Pieces adapts to YOUR workflow, whether you're coding, researching, writing, or collaborating.

    ### Never Lose Your Research Trail
    
    Every article, paper, video, and reference is automatically captured and connected. No more lost tabs or forgotten bookmarks.

        **Academic Research**
        - "Find all papers I read about machine learning last month"
        - "What were the key findings from that Nature article?"
        - "Show me my notes on quantum computing lectures"

        **Market Analysis**
        - "Pull up competitor analysis from Q2"
        - "What trends did I research for the product launch?"
        - "Find that industry report with revenue projections"

      **Real scenario:** A PhD student researching climate models can instantly recall papers from 6 months ago, complete with their highlights, notes, and the context of related research—all searchable by topic, not just title.

    ### Your Team's Collective Memory
    
    Automatically capture who you worked with, what was discussed, and what needs to happen next. Never lose track of decisions or action items.

        **Team Sync**
        - "Who did I discuss the budget with last week?"
        - "What did Sarah say about the timeline?"
        - "Show me all meetings about Project Alpha"

        **Client Management**
        - "What requirements did the client mention?"
        - "Find our last conversation about pricing"
        - "Which stakeholder approved this change?"

      **Real scenario:** A project manager can ask "What did we decide about the API design in Tuesday's meeting?" and get the exact discussion, participants, and follow-up tasks—even months later.

    ### Everything Stays Connected
    
    Your work maintains its context—whether it's code, designs, documents, or creative projects. Every piece knows where it came from and why it exists.

        **Software Development**
        - "Show me the auth implementation from last sprint"
        - "What was the fix for that memory leak?"
        - "Find the component I built for the dashboard"

        **Content Creation**
        - "Pull up the brand guidelines document"
        - "What copy did we use for the last campaign?"
        - "Find the design mockups from March"

      **Real scenario:** A designer can search "gradient styles from product launch" and instantly find not just the CSS/design files, but also the discussion about why those colors were chosen and who approved them.

    ### Reports That Write Themselves
    
    Generate accurate summaries from your actual work history. No more trying to remember what you did last week—Pieces already knows.

        **Status Updates**
        - Weekly team reports with actual progress
        - Sprint reviews with completed tasks
        - Monthly summaries for stakeholders

        **Documentation**
        - Auto-generate project timelines
        - Create knowledge base articles
        - Build onboarding materials from work history

      **Real scenario:** A consultant can generate a complete monthly client report showing all work done, decisions made, and progress achieved—with links to supporting materials and conversations.

Let Pieces do the heavy lifting and preserve your engineering creativity and ingenuity for where you need it most.

### How do I Use Pieces?

PiecesOS serves as the foundational layer of the entire Pieces Suite, much like Docker does for containerized applications—it powers the Pieces Desktop App along with [MCP integrations](/products/mcp) in your editors and tools.

By installing PiecesOS, you enable the full functionality of the desktop app and those integrations, just like how Docker manages various containers.

    Download and install Pieces for your platform. 

        Intel & Apple Silicon

        Windows 10 & 11

      Ubuntu 22+

      PiecesOS runs in the background and powers all Pieces applications. It's lightweight and resource-efficient.

    Select the applications and integrations that fit your workflow:

      **Your central hub** — Manage memories, chat with Conversational Search, and access all Pieces features

        **Command-line power** — Access Pieces from your terminal

        **Connect AI tools** — [Cursor](/products/mcp/cursor), [GitHub Copilot](/products/mcp/github-copilot), [Goose](/products/mcp/goose), and [Claude Desktop](/products/mcp/claude-desktop)

    Configure preferences and start capturing context.
    
    1. Open the Desktop App
    2. Turn on Long-Term Memory in the PiecesOS toolbar
    3. Work as usual—Pieces captures context automatically

      Pro tip: See how to toggle Long-Term Memory in the [Quick Menu](/products/core-dependencies/pieces-os/quick-menu).

    **Captured automatically:**
    - Saved content (copies, files, snippets)
    - Browser tabs and links
    - Documents and code
    - Conversations and decisions

## Private by Design, Local by Default

Read more in our [privacy & security guide](/products/privacy-security-your-data).

    Pieces runs on-device. It's fast, secure, and air-gapped from the cloud.

    Cloud is optional—nothing is sent unless you allow it. Your data stays on your machine.

  No external servers, so your environment stays secure. Perfect for enterprise compliance.

---

## Enabling Long-Term Memory
Path: /products/meet-pieces/enabling-long-term-memory

## What Long-Term Memory does

The **Long-Term Memory (LTM-2.7) Engine** captures workflow context on your device so Pieces can surface relevant summaries, timeline activity, and answers in [Conversational Search](/products/desktop/conversational-search). For a conceptual overview, see [Fundamentals](/products/meet-pieces/fundamentals#ltm-2-7).

## Turn on Long-Term Memory

1. Open the **Pieces Desktop App**.
2. Click your **User Profile** (top left), hover **Settings**, then choose **Long-Term Memory**.
3. In the **Memory Formation** section, ensure the **Long-Term Memory Engine** is **On**.

You can also use the **PiecesOS Quick Menu** in your system tray or menu bar—see [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) for access and shortcuts.

  LTM runs **on-device** for privacy. Grant any prompts for **screen**, **accessibility**, or **microphone** (for LTM Audio) when asked—details are in the full settings guide below.

## Full settings reference

For every toggle, app allowlist, performance option, stored data, and LTM Audio setup, use the complete guide:

**[Long-Term Memory settings (full documentation) →](/products/desktop/configuration/long-term-memory)**

That page is the same in-app **Settings → Long-Term Memory** experience documented end-to-end for power users and troubleshooting.

---

## Core Features of Pieces
Path: /products/meet-pieces/fundamentals

## The Pillars

Pieces helps you work smarter with **\[1] Long-Term Memory Engine (LTM-2.7)**, an "artificial memory" that remembers your workflow and saves context for later.

Next, **\[2] Conversational Search** helps with everyday tasks like answering questions, creating content, and getting help—with as much or as little context as you need.

Finally, **\[3] Timeline** is your main workspace for everything Long-Term Memory captures. You can create summaries, look back at past work, and explore your workflow history.

## LTM-2.7

The Long-Term Memory Engine (LTM-2.7) captures what you're working on, so you can easily find past activities, conversations, and materials.

***

*Conversational Search with LTM-2.7 Context*

***

You can ask questions like, "*What was the link to that document I worked on last week?"* or "*Summarize the brief from the meeting"* to get quick answers with game-changing context enhancements.

Here are some ways to take advantage of the LTM-2.7:

* `Contextual Recall`: LTM-2.7 remembers the websites you visit, the work you do, and what you save. You can access this from the Pieces Desktop App or in Conversational Search inside your IDE via [MCP integration](/products/mcp).

* `Natural Language Queries`: Ask questions about your past work, and LTM-2.7 will find the right link or file path for you. You can also ask it to summarize a webpage you visited earlier.

* `Integrated Access`: Use LTM-2.7 in the Pieces Desktop App or in your favorite tools through browser or IDE integrations.

***

[PiecesOS](/products/core-dependencies/pieces-os) collects LTM data and creates a summary *every 20 minutes,* so you don't have to keep explaining context like you do with other AI tools.

## Conversational Search

Conversational Search uses Large Language Models (LLMs) to help answer questions, create content, and give guidance. You can use it in your IDE, editor, or the Desktop App.

***

*Conversational Search for Content Generation*

***

Conversational Search, available in the Pieces Desktop App, any IDE, or browser integration, helps with:

* `Answering Questions`: Get explanations of complex topics, learn how things work, or explore different approaches.

* `Content Generation`: Create content based on what you need, either by asking directly or using context from your current work.

* `LLM Flexibility`: Switch between model families—Claude, Gemini, and ChatGPT—and choose Fast, Balanced, or Extra Thinking modes.

## Timeline

Timeline is your central workspace in the Pieces Desktop App. It shows summaries of everything Long-Term Memory (LTM-2.7) captures. You can create summaries, look at past work, chat with Conversational Chat, and manage your memories.

***

*Timeline Interface*

***

Timeline has four main features that help you use your workflow context:

* `Single-Click Summaries`: Create quick summaries from your workflow with one click. Choose from preset types like Standup Updates, Day Recaps, and more.

* `Timeline Activities`: Browse a timeline of all your activities and conversations in the sidebar. Search, filter, and find any activity from your workflow history.

* `Conversational Chat`: Ask questions about your workflow and get answers powered by LTM-2.7. The chat knows your memories and gives relevant answers.

Everything you need to understand and use your captured workflow context is in Timeline. [Learn more about Timeline](/products/desktop/timeline).

---

## Installation Guide | Linux
Path: /products/meet-pieces/linux-installation-guide

## Install Pieces for Linux

Pieces for Linux is available via **Snap** (recommended for Ubuntu) or **Flatpak** (for Fedora, Arch, Linux Mint, and other distros). Choose the method that works best for your system.

    Snap package for Ubuntu and Snap-supported distributions.

    Flatpak package for Fedora, Arch, and other distributions.

### General Requirements

* **Minimum OS:** Ubuntu 22+ or equivalent modern Linux distribution
* **Display Server:** Pieces is primarily **supported** on **X11**. **Wayland** support requires manual steps. Run `pieces-os.doctor` after install (Snap only) and follow its output. If **Long-Term Memory** or screen-related features misbehave, especially in some VMs, try logging in with an **X11 session** or see [Linux troubleshooting](/products/meet-pieces/troubleshooting/linux).

  Check your session with `echo $XDG_SESSION_TYPE` (`wayland` or `x11`). On **Wayland**, use `pieces-os.doctor` to wire up interfaces; labels in **Settings → System** vary by distro.

## Updating

On Linux, update PiecesOS and the Desktop App using your package manager. Both packages update together.

### Snap

```bash
sudo snap refresh pieces-os pieces-for-developers
```

> Running `snap refresh` to update Pieces on Linux

### Flatpak

```bash
flatpak update -y com.pieces.os com.pieces.pfd
```

You can also check for updates from the Desktop App by clicking your profile in the top-left corner and selecting `Check for Updates`.

## Additional Resources

See the [Linux troubleshooting guide](/products/meet-pieces/troubleshooting/linux) or reach out to [support](/products/support) for help.

---

## Flatpak Installation | Linux
Path: /products/meet-pieces/linux-installation-guide/flatpak

## Flatpak Installation

[Flatpak](https://flatpak.org) is a universal package format that works across most Linux distributions. It's an excellent alternative for users on Fedora, Arch, Linux Mint, Debian, or other distributions that don't include Snap by default. It's also a good choice for users who prefer Flatpak's sandboxing model.

Pieces provides its own Flatpak repository hosted at `builds.pieces.app`, which contains both **PiecesOS** (`com.pieces.os`) and the **Pieces Desktop App** (`com.pieces.pfd`).

### Flatpak Requirements

* **Flatpak:** Install Flatpak using your distro's package manager. Most distributions include it in their repositories. See [flathub.org/setup](https://flathub.org/setup) for distro-specific instructions.
* **Installation scope:** Use `--user` for both packages, or omit it for both. Flatpak does not share runtimes across user and system scopes, so mixing them will fail.
* **User Permissions:** The commands below use `--user`, so no `sudo` is required. Drop `--user` from both install commands if you prefer a system-wide install.

### Install via a software center

Open the PiecesOS `.flatpakref` in GNOME Software, KDE Discover, or another Flatpak-aware software center. That file adds the Pieces repository and the Flathub repository that provides the shared GNOME runtime, then installs PiecesOS.

[Install PiecesOS (`.flatpakref`)](https://builds.pieces.app/pieces-flatpak-repo/com.pieces.os.flatpakref)

After PiecesOS is installed, open the Desktop App `.flatpakref` the same way:

[Install Pieces Desktop App (`.flatpakref`)](https://builds.pieces.app/pieces-flatpak-repo/com.pieces.pfd.flatpakref)

Do not use the older `pieces-flatpak.flatpakrepo` file on its own. A `.flatpakrepo` file only adds a remote and does not declare the runtime source, so the GNOME runtime may be missing.

### Install via Flatpak

Prefer the command line? Run these commands in order.

    Install PiecesOS, the on-device engine that powers everything — Long-Term Memory, local AI, and MCP.

    ```bash
    flatpak install --user -y --from https://builds.pieces.app/pieces-flatpak-repo/com.pieces.os.flatpakref
    ```

    This adds both the Pieces repository and the Flathub repository that provides the shared GNOME runtime, so no separate setup is needed. It can take a few minutes while Flatpak downloads the runtime. Drop `--user` to install system-wide.

    Install the Pieces Desktop App, your hub for saving, searching, and managing snippets, screenshots, and developer resources.

    ```bash
    flatpak install --user -y --from https://builds.pieces.app/pieces-flatpak-repo/com.pieces.pfd.flatpakref
    ```

    Use the same scope as the previous command — either `--user` for both, or neither.

    Start PiecesOS first. It runs as a background service the Desktop App connects to, and the app won't launch it automatically.

    ```bash
    flatpak run com.pieces.os
    ```

    Once PiecesOS is running, launch the Pieces Desktop App. After the first launch, both appear in your application menu.

    ```bash
    flatpak run com.pieces.pfd
    ```

    Always start PiecesOS before the Desktop App.

  Always start PiecesOS first with `flatpak run com.pieces.os`. The Pieces Desktop App does not currently auto-launch PiecesOS when installed via Flatpak. If you launch the Desktop App without PiecesOS running, it will remain on the connection screen until you start PiecesOS manually.

### Updating

Flatpak apps are updated separately from your system packages. You can update Pieces manually or let Flatpak handle it automatically (if your distro supports automatic Flatpak updates).

To manually update both PiecesOS and the Pieces Desktop App, run:

```bash
flatpak update -y com.pieces.os com.pieces.pfd
```

You can also check for updates from the Desktop App by clicking your profile in the top-left corner and selecting `Check for Updates`. Both apps update together.

  Some desktop environments (like GNOME Software or KDE Discover) can manage Flatpak updates through their graphical interface. Look for Pieces in your software center to update from there.

### Uninstalling

You can remove PiecesOS and the Pieces Desktop App using Flatpak commands. The process involves stopping any running instances, removing the apps, and optionally removing the Pieces repository.

    Before uninstalling, stop any running Pieces processes:

    ```bash
    flatpak kill com.pieces.pfd || true
    flatpak kill com.pieces.os || true
    ```

    Uninstall the Pieces Desktop App and its Flatpak-managed data:

    ```bash
    flatpak uninstall -y --delete-data com.pieces.pfd
    ```

    Uninstall PiecesOS and its Flatpak-managed data:

    ```bash
    flatpak uninstall -y --delete-data com.pieces.os
    ```

    If you no longer want to receive updates from the Pieces Flatpak repository, remove it:

    ```bash
    flatpak remote-delete --user pieces-flatpak
    ```

    Remove any shared runtimes that are no longer needed by other Flatpak apps:

    ```bash
    flatpak uninstall -y --unused
    ```

  Flatpak stores app data separately from your personal Pieces data. The commands above remove Flatpak-managed state (settings, cache). Your actual Pieces data in `~/.local/share/com.pieces.os/` is preserved and must be deleted manually if desired. See [On-Device Storage](/products/core-dependencies/on-device-storage) for paths on all platforms.

### Troubleshooting

If you encounter issues with the Flatpak installation, try these common solutions.

**Pieces Desktop App can't connect to PiecesOS:**

PiecesOS must be running before you launch the Pieces Desktop App. Check if it's running and start it if needed:

```bash
# Check if PiecesOS is running
flatpak ps | grep pieces

# Start PiecesOS manually if it's not running
flatpak run com.pieces.os
```

**Permission or sandbox issues:**

If features aren't working correctly, reset the Flatpak permissions for both apps:

```bash
flatpak permission-reset com.pieces.os
flatpak permission-reset com.pieces.pfd
```

Then restart both applications.

**Missing GNOME runtime (`org.gnome.Platform` was not found):**

This happens when Pieces was installed in a different Flatpak scope than Flathub (for example, Flathub as system and Pieces as `--user`). Uninstall both apps, then reinstall from the `.flatpakref` commands above so both remotes are added in the same scope.

```
error: The application com.pieces.os/x86_64/stable requires the runtime org.gnome.Platform/x86_64/48 which was not found
```

**Verify the Pieces repository is accessible:**

If installation fails, confirm the Pieces repository is reachable:

```bash
curl -fsSIL https://builds.pieces.app/pieces-flatpak-repo/summary
```

You should see `HTTP/2 200` after the redirect completes. The `-L` flag follows the redirect to the storage backend.

**Complete reset (keeps personal data):**

If you need a fresh start, uninstall and reinstall:

```bash
flatpak kill com.pieces.pfd || true
flatpak kill com.pieces.os || true
flatpak uninstall -y --delete-data com.pieces.pfd com.pieces.os
```

Then follow the installation steps above to reinstall.

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [Linux troubleshooting](/products/meet-pieces/troubleshooting/linux) for common solutions.

---

## Snap Installation | Linux
Path: /products/meet-pieces/linux-installation-guide/snap

## Snap Installation (Recommended for Ubuntu)

Snap is the recommended installation method for Ubuntu users. It provides automatic updates, system integration, and simple management through terminal commands.

### Snap Requirements

* **Snap Support:** Ensure `snapd` is installed and enabled. Most Ubuntu releases include it by default.
* **Administrator Access:** You'll need `sudo` privileges to install snap packages.
* **Ubuntu 22.04+** or a compatible distribution with Snap support.

### Install via Snap

  *Ubuntu 22.04+ required.*

  ***

  Run these commands **in order** to install and properly set up the Pieces Desktop App and its core dependencies:

  1. `sudo snap install pieces-os`

  2. `sudo snap connect pieces-os:process-control :process-control`

  3. `sudo snap install pieces-for-developers`

  Then, type `pieces-for-developers` to launch the application directly from your terminal.

See our guide on [determining your OS version].(/products/meet-pieces/troubleshooting/linux#checking-ubuntu-version)

### Connect System Interfaces

After installing via Snap, run `pieces-os.doctor` in your terminal. The script outputs a command you can copy and paste to connect all interfaces with the system. This step is required for full functionality, including features like [LTM Audio](/products/desktop/configuration/long-term-memory#ltm-audio).

### Updating

Update both packages with Snap:

```bash
sudo snap refresh pieces-os pieces-for-developers
```

You can also check for updates from the Desktop App by clicking your profile in the top-left corner and selecting `Check for Updates`. Both apps update together.

> Running `snap refresh` to update Pieces on Linux

### Uninstalling

You can uninstall PiecesOS and the Pieces Desktop App using `snap` commands directly from your terminal.

  When running these commands, you will be prompted to enter your device's local account password due to the `sudo` command.

    `sudo snap remove pieces-for-developers`

    `sudo snap remove pieces-os`

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [Linux troubleshooting](/products/meet-pieces/troubleshooting/linux) for common solutions.

---

## Installation Guide | macOS
Path: /products/meet-pieces/macos-installation-guide

## Install Pieces for macOS

Pieces for macOS is available via **DMG** (recommended), **PKG**, or **Homebrew**. All methods support both Apple Silicon and Intel Macs.

    Disk image for Apple Silicon and Intel Macs.

    Package installer with guided setup.

    Install via the Homebrew package manager.

### Requirements

* **macOS 13.0 (Ventura) or higher**
* **Apple Silicon (M1/M2/M3/M4)** or **Intel** processor

  After installing, PiecesOS will request **Screen & System Audio Recording** and **Microphone** permissions to power features like Long-Term Memory. See [Granting macOS Permissions](/products/meet-pieces/troubleshooting/macos#macos-permissions) for a walkthrough.

## Updating

Pieces automatically downloads and installs updates. When you check for updates from either the Desktop App or the PiecesOS Quick Menu, both apps update together.

### From the Desktop App

    Click your profile or username in the top-left corner of the Pieces Desktop App.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it, then restart when complete.

> Profile menu in the Pieces Desktop App with `Check for Updates`

### From the PiecesOS Quick Menu

    Click the Pieces icon in your menu bar.

    Click `You're up to date` to trigger a check. If an update is available, follow the prompt to install.

> PiecesOS Quick Menu showing your current version and update status

  Pieces often downloads updates automatically and notifies you when a new version is ready. Use either method above to check manually.

## Uninstalling

To quickly remove the applications, open **Finder** → **Applications** and drag both `Pieces` and `PiecesOS` to the Trash.

For a complete uninstall that removes all data, preferences, and caches, see the [Complete Uninstall Guide](/products/meet-pieces/macos-installation-guide/uninstall).

## Additional Resources

See the [macOS troubleshooting guide](/products/meet-pieces/troubleshooting/macos) or reach out to [support](/products/support) for help.

---

## DMG Installation | macOS
Path: /products/meet-pieces/macos-installation-guide/dmg

## DMG Installation (Recommended)

The DMG installer is the recommended method for installing Pieces on macOS. Choose the correct version for your Mac's processor.

    *For M1, M2, M3, M4 Macs*

    macOS 13.0 (Ventura) or higher required.

    *For pre-2020 Macs*

    macOS 13.0 (Ventura) or higher required.

  PiecesOS is a required Core Dependency. After you move Pieces Desktop to your Applications folder and open it for the first time, you'll be guided through installing PiecesOS automatically.

### Install the DMG

    Open your **Downloads** folder (or wherever you saved the installer) and look for the `.dmg` file you just downloaded (e.g., `Pieces.dmg`).

    Double-click the `.dmg` file to mount it.

    Drag the application icon from the mounted `.dmg` window into your **Applications** folder.

    Go back to **Finder**, right-click the mounted image, and select **Eject** to unmount it.

  Put Pieces in **Applications** or another **local** folder—not **iCloud Drive** or other synced locations.

### System Requirements

| **Component**      | **Minimum**                                                                   | **Recommended**                      | **Notes**                                                        |
| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
| *OS Version*       | macOS 13.0 (Ventura)                                                          | macOS 14.0 or higher                 | Apple Silicon or Intel processor.                                |
| *CPU*              | Any modern CPU                                                                | Multi-core CPU                       | Avoid dual-core processors—aim for at least a 4-core CPU.        |
| *RAM*              | 8 GB total system RAM with 1 GB free                                          | 16 GB total system RAM or more       | More RAM improves performance with large workspaces.            |
| *Disk Space*       | 2 GB minimum (1 GB for PiecesOS + 0.5–1 GB for data), with at least 4 GB free | 8 GB with at least 6 GB free or more | Ensure additional free space for data storage and future growth. |

See our guide on [determining your OS type](/products/meet-pieces/troubleshooting/macos#checking-os-version), and here for [how to check your device's CPU architecture](/products/meet-pieces/troubleshooting/macos#checking-cpu-type).

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [macOS troubleshooting](/products/meet-pieces/troubleshooting/macos) for common solutions.

---

## Homebrew Installation | macOS
Path: /products/meet-pieces/macos-installation-guide/homebrew

## Homebrew Installation

Install Pieces using Homebrew for a streamlined terminal-based setup. This method automatically installs both the Pieces Desktop App and PiecesOS.

### Requirements

* **Homebrew:** Ensure Homebrew is installed on your system. Visit [brew.sh](https://brew.sh) if you need to install it.
* **macOS 13.0 (Ventura) or higher**

### Install via Homebrew

    Launch **Terminal** from Applications > Utilities, or use Spotlight (⌘ + Space) and search for "Terminal".

    Copy and run the following command:

    ```bash
    brew install --cask pieces
    ```

    If prompted, enter your administrator password to allow the installation.

    Homebrew will download and install both the Pieces Desktop App and PiecesOS. You'll see a success message when complete.

### Updating via Homebrew

To update Pieces using Homebrew:

```bash
brew upgrade --cask pieces
```

### Uninstalling via Homebrew

To remove Pieces using Homebrew:

```bash
brew uninstall --cask pieces
```

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [macOS troubleshooting](/products/meet-pieces/troubleshooting/macos) for common solutions.

---

## PKG Installation | macOS
Path: /products/meet-pieces/macos-installation-guide/pkg

## PKG Installation

The PKG installer provides a guided installation experience with an installation wizard. Choose the correct version for your Mac's processor.

### Apple Silicon (M-Series / ARM)

    *For M1, M2, M3, M4 Macs*

    macOS 13.0 (Ventura) or higher required.

### Intel

    *For pre-2020 Macs*

    macOS 13.0 (Ventura) or higher required.

### Install the PKG

    Open your **Downloads** folder (or wherever you saved the installer) and look for the `.pkg` file you just downloaded.

    Double-click the `.pkg` file to launch the installer wizard.

    Click through the on-screen prompts—review the license agreement and enter your administrator password when prompted.

    Once the installer finishes, click `Close`. The Pieces Desktop App and PiecesOS are now installed in your **Applications** folder and ready to use.

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [macOS troubleshooting](/products/meet-pieces/troubleshooting/macos) for common solutions.

---

## Complete Uninstall Guide | macOS
Path: /products/meet-pieces/macos-installation-guide/uninstall

This guide walks you through completely removing Pieces from your Mac, including all application data, saved snippets, and Long-Term Memory.

  This process permanently deletes all your saved snippets, conversations, and Long-Term Memory data. If you want to preserve this data, see [backing up your data](/products/privacy-security-your-data#local-backup) before proceeding.

## Uninstall Steps

To remove Pieces and all associated data:

    Click the Pieces icon in your menu bar and select `Quit`. If Pieces isn't responding, open **Activity Monitor** (Applications → Utilities), search for "Pieces", select any Pieces processes, and click the **X** button to force quit.

    Open **Finder** → **Applications**, then drag both `Pieces` and `PiecesOS` to the Trash.

    Open **Finder**, press `Cmd + Shift + G` to open "Go to Folder", and navigate to:

    ```
    ~/Library/
    ```

    Delete the following folders if they exist:
    - `com.pieces.os` — Contains your snippets, Long-Term Memory, and engine data
    - `com.pieces.pfd` — Contains Desktop App settings and logs

    In the same `~/Library/` location, open the `Preferences` folder and delete any files starting with `com.pieces`:

    ```
    ~/Library/Preferences/com.pieces.*
    ```

    Navigate to the `Caches` folder and delete any Pieces-related folders:

    ```
    ~/Library/Caches/com.pieces.*
    ```

    Right-click the Trash icon in your Dock and select `Empty Trash` to permanently delete the files.

### Homebrew Users

If you installed Pieces via Homebrew, run this command instead of manually removing the applications:

```bash
brew uninstall --cask pieces
```

Then continue with Steps 3-6 above to remove application data.

### Terminal Commands (Advanced)

For users comfortable with Terminal, you can run these commands to remove everything at once:

```bash
# Quit Pieces processes
pkill -f "Pieces" 2>/dev/null
pkill -f "PiecesOS" 2>/dev/null

# Remove applications
rm -rf /Applications/Pieces.app
rm -rf /Applications/PiecesOS.app

# Remove application data
rm -rf ~/Library/com.pieces.os
rm -rf ~/Library/com.pieces.pfd

# Remove preferences
rm -f ~/Library/Preferences/com.pieces.*

# Remove caches
rm -rf ~/Library/Caches/com.pieces.*
```

  These commands permanently delete files without moving them to Trash. Double-check before running.

## Verify Removal

To confirm Pieces has been completely removed:

1. Open **Spotlight** (Cmd + Space) and search for "Pieces" — no results should appear
2. Open **Finder**, press `Cmd + Shift + G`, and check that `~/Library/com.pieces.os` no longer exists

## Reinstalling

If you want to reinstall Pieces later, see the [macOS installation guide](/products/meet-pieces/macos-installation-guide) for fresh install instructions.

---

## Managing Your Account
Path: /products/meet-pieces/managing-your-account

## Your Account and PiecesOS

Your Pieces account is managed by **PiecesOS**—the background service that powers every Pieces tool and integration. Signing in authenticates PiecesOS directly, not just the Desktop App. This means your session, subscription entitlements, and LTM access are all tied to PiecesOS, regardless of which Pieces product you use.

A sign-in is required to use Pieces. Anonymous usage is not available.

***

## Signing In

When you launch PiecesOS for the first time (or after signing out), it will prompt you to sign in. You can also initiate sign-in from the **[PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu)**—the Pieces icon in your menu bar (macOS/Linux) or system tray (Windows).

    Click the Pieces icon in your menu bar or system tray.

    If you're not signed in, a `Sign In` option appears. Click it to open the authentication flow in your browser.

    Sign in with GitHub, Google, Microsoft, or email. If using email, check your inbox for a verification code.

    After authenticating in the browser, PiecesOS recognizes your session automatically. If the browser doesn't switch back, return to the app manually—PiecesOS will already be signed in.

> The PiecesOS Quick Menu sign-in prompt on macOS

  Once signed in, you stay signed in automatically across restarts. If you sign out from another device, you'll need to sign in again.

For troubleshooting sign-in issues, see [Sign In to Pieces](/products/meet-pieces/sign-into-pieces).

***

## Signing Out

Sign out from the **PiecesOS Quick Menu** at any time.

    Click the Pieces icon in your menu bar or system tray.

    Click your account name at the top of the Quick Menu.

    Select `Log Out`. PiecesOS will end your session immediately.

You can also sign out from inside the Pieces Desktop App—click your `User Profile` in the top left and select `Log Out`.

***

## What Your Account Unlocks

Your Pieces account connects your tools and preferences across devices. **Pieces Pro** includes:

| Feature | With Pieces Pro |
| --- | --- |
| *Cloud-hosted AI models* (Claude, Gemini, ChatGPT) | Current families and modes |
| *Long-Term Memory* | Capture and search memories |
| *MCP Server* | ✓ |

Without Pro, Pieces no longer forms new memories. You can still browse existing memories, use them with Pieces MCP, use Pieces Drive, and sync with Pieces Cloud.

  LTM capture and memory search via Conversational Search require Pieces Pro, though your existing memories remain accessible on your device. Existing users have full access through August 16, 2026 and may qualify for a discount. Manage your plan in [Account settings](/products/desktop/configuration/account).

  Your subscription is tied to your account, not to a specific device. Sign in on any machine and your plan applies everywhere.

***

## Full Account Settings

Detailed account management—linked accounts, organizations, subscriptions, personal cloud, backup & restore, and privacy settings—is available in the Pieces Desktop App.

  Manage linked accounts, organizations, subscriptions, personal cloud sync, backup & restore, and telemetry settings.

  Step-by-step sign-in instructions, update requirements, and troubleshooting for authentication issues.

---

## Setting Up PiecesOS
Path: /products/meet-pieces/setting-up-piecesos

## What PiecesOS is

**PiecesOS** is a background service on your machine. It powers on-device intelligence for the Pieces suite—**[Long-Term Memory (LTM-2.7)](/products/meet-pieces/enabling-long-term-memory)**, context for **[Conversational Search](/products/desktop/conversational-search)**, and the **[Timeline](/products/desktop/timeline)** in the Pieces Desktop App.

You usually install the **Pieces Desktop App** first; the installer brings **PiecesOS** with it. You can also run PiecesOS-focused workflows (for example MCP) without the desktop app in some setups.

## Typical setup

1. **Install Pieces** using the [installation guides](/products/desktop/download) for your OS.
2. Confirm **PiecesOS** is running (system tray / menu bar on macOS and Windows, or your Linux workflow).
3. If something fails, use **[PiecesOS troubleshooting](/products/core-dependencies/pieces-os/troubleshooting)** or the doctor/CLI steps your OS guide recommends.

  For advanced topics—architecture, LTM internals, MCP without desktop, and more—use the full reference below.

## Full PiecesOS documentation

The canonical guide (same content as **Core Dependencies → PiecesOS**) covers everything in depth:

**[Understanding PiecesOS (full documentation) →](/products/core-dependencies/pieces-os)**

From there you can jump to:

- [Manual installation](/products/core-dependencies/pieces-os/manual-installation)
- [Quick Menu](/products/core-dependencies/pieces-os/quick-menu)
- [Troubleshooting](/products/core-dependencies/pieces-os/troubleshooting)

---

## Getting Started with Sign-In
Path: /products/meet-pieces/sign-into-pieces

## Signing In to Pieces

Whether you're new to Pieces or have used it for years, you'll need to sign in to use Pieces—anonymous usage is no longer available. We've upgraded our sign-in system with more sign-in options, better security, and the ability to combine accounts easily. Your existing account works exactly the same; just sign in like you normally would.

> The Pieces sign-in screen

## Sign-In Process

When you open Pieces, you'll see a sign-in screen. Both new and existing users follow the same sign-in flow.

    Choose how you want to sign in; we offer a wide range of platforms to suit your needs.

    Complete the sign-in process in your web browser.

    If you choose email, check your inbox for a verification code.

    Once you're signed in, you'll continue with the setup process or return to your workspace.

> The sign-in screen you'll see when opening Pieces

### Accessing Sign-In

If the sign-in prompt doesn't appear automatically, you can access it from your system tray or menu bar:

> If you're not signed in, you'll see a prompt to sign in

        Click the Pieces icon in your menu bar (top of screen).

    Click `Sign In` when the Pieces app opens.

        > Pieces menu bar dropdown showing Sign In option

        Click the Pieces icon in your system tray (near the clock).

        Click `Sign In` when the Pieces app opens.

        Click the Pieces icon in your system tray.

        Click `Sign In` when the Pieces app opens.

### Staying Signed In

Once you sign in, you should stay signed in automatically. However, if you sign out from another device or location, you'll need to sign in again. This keeps your account secure across all your devices.

## Requirements and Updates

To use the new sign-in features, you must update both PiecesOS and the Pieces Desktop app to version 15.0.0 or later. Older versions of Pieces Desktop and PiecesOS will be deprecated and will not work anymore.

  You must update to version 15.0.0 or later to use the Pieces Suite. Both PiecesOS and the Desktop App must be updated for sign-in to work properly.

### Update Pieces

When you check for updates, both PiecesOS and the Desktop App update together.

    Launch the Pieces Desktop App and click your profile in the top-left corner.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it.

    Restart when the update completes.

      You can also check for updates from the PiecesOS Quick Menu by clicking `You're up to date` in your menu bar (Mac) or system tray (Windows).

## Troubleshooting

If you encounter issues while signing in, try these solutions:

### Opening Pieces via Command Line

If the Pieces app doesn't open automatically, you can launch it directly from your terminal or command line:

    Open Terminal and run:

    ```bash
    open "pieces-for-developers://open"
    ```

    Open PowerShell or Command Prompt and run:

    ```powershell
    start "pieces-for-developers://open"
    ```

    Open your terminal and run:

    ```bash
    xdg-open "pieces-for-developers://open"
    ```

### Stuck at Startup

If Pieces gets stuck at "Sign In to use Pieces" during startup, simply click the `Sign In` button that appears and complete the process in your browser. This is intentional, as we now require every Pieces user to be logged in to use our platform.

### Authentication Failed

Getting an "authentication failed" error? Make sure you're using the same account you used before with Pieces.

### Browser Doesn't Return

After signing in, your browser might not automatically switch back to Pieces. That's okay—just manually switch back to the Pieces app. It should recognize that you've signed in successfully. If it hasn't, restart your Pieces and follow the sign-in steps again.

### Repeatedly Signed Out

If you keep getting signed out, check that your computer's date and time are set correctly. Authentication relies on accurate time settings to keep your account secure.

> Troubleshooting flowchart for sign-in issues

## Keeping Your Account Safe

Here are simple ways to protect your Pieces account:

* Use a strong password if signing in with email
* Turn on two-factor authentication with your sign-in provider
* Sign out when using shared computers
* Let us know immediately if you see anything suspicious

## Getting Help

Having trouble signing in or have questions? We're here to help:

* **[Live Support](https://calendar.app.google/WVUDtUfNy5Vst3sH7)**: Book a call with our Founders & Engineering Leaders
* **[GitHub Issues](https://github.com/pieces-app/support/issues)**: Report bugs, request features, and track known issues
* **[Discord Community](https://discord.com/invite/getpieces)**: Join our community for support, discussions, and direct interaction with the Pieces team
* **[Community Discussions](https://github.com/pieces-app/support/discussions)**: Create or read through existing discussions to inform our product roadmap
* **[Feedback Form](https://getpieces.typeform.com/to/mCjBSIjF#page=docs-support)**: Leave feedback or report bugs without using GitHub

***

## Next Steps

Now that you're signed in, explore what Pieces can do for you.

[Getting Started with Pieces →](/products/meet-pieces)

---

## Troubleshooting
Path: /products/meet-pieces/troubleshooting

## Using the Guides

Click one of the links below to get started troubleshooting on your device—or [browse the cross-platform troubleshooting documentation](/products/meet-pieces/troubleshooting/cross-platform) for more general fixes.

***

    General troubleshooting for all platforms

    macOS-specific troubleshooting

    Windows-specific troubleshooting

    Linux-specific troubleshooting

***

## Cross-Platform Issues

This cross-platform troubleshooting documentation covers the Pieces Desktop App and PiecesOS, including updates, connectivity, system requirements, and solutions for crashes due to limited resources or GPU compatibility.

  Use the Cross-Platform page if you’re not sure where to begin or if your issue isn’t clearly related to your operating system.

  On the [Cross-Platform troubleshooting guide](/products/meet-pieces/troubleshooting/cross-platform), you’ll find:

  * [Guidance on working with Vulkan-based GPUs](/products/meet-pieces/troubleshooting/cross-platform#vulkan-based-gpus)

  * [Links to related documentation on checking hardware specifications on your OS](/products/meet-pieces/troubleshooting/cross-platform#checking-hardware)

## macOS Issues

This macOS guide helps troubleshoot installation and update issues for PiecesOS and the Pieces Desktop App on macOS, covering manual installs (`PKG`, `DMG`, `Homebrew`), checking macOS version and CPU type, and fixing compatibility or outdated software problems.

  The [macOS troubleshooting guide](/products/meet-pieces/troubleshooting/macos) provides information and guides on:

  * [How to verify your macOS software version](/products/meet-pieces/troubleshooting/macos#checking-os-version)

  * [Determining and choosing the correct installation package for different chipsets](/products/meet-pieces/troubleshooting/macos#checking-cpu-type)

  * [Updating PiecesOS and the Pieces Desktop App](/products/meet-pieces/troubleshooting/macos#versions--updates)

  * [macOS Permissions (Screen Recording & Microphone)](/products/meet-pieces/troubleshooting/macos#macos-permissions)

## Windows Issues

Windows users can find troubleshooting steps for installing, updating, or running PiecesOS and the Pieces Desktop App on Windows. It includes manual installation, update instructions, system checks, and solutions for issues with outdated Windows versions, dependencies, or hardware compatibility.

  The [Windows troubleshooting guide](/products/meet-pieces/troubleshooting/windows) provides information and guides on:

  * [Checking for Windows installation updates](/products/meet-pieces/troubleshooting/windows#checking-for-windows-updates)

  * [Verifying the App Installer is up-to-date](/products/meet-pieces/troubleshooting/windows#versions--updates)

  * [Alternative installation methods for non-Suite installs](/products/meet-pieces/troubleshooting/windows#trying-different-installation-methods)

  * [Viewing hardware specifications using `dxdiag`](/products/meet-pieces/troubleshooting/windows#checking-hardware-specifications)

## Linux Issues

Ubuntu 22+ Linux users can use this guide to troubleshoot PiecesOS and the Pieces Desktop App. It covers updating via Snap, checking system compatibility, and fixing common installation or display issues. It also offers tips for adjusting GPU settings and verifying hardware and Ubuntu version compatibility.

  The [Linux troubleshooting guide](/products/meet-pieces/troubleshooting/linux) provides information and guides on:

  * [Confirming compatibility with your Linux distribution](/products/meet-pieces/troubleshooting/linux#checking-distribution-compatibility)

  * [Using snap commands to update PiecesOS and the Pieces Desktop App](/products/meet-pieces/troubleshooting/linux#updating-piecesos)

  * [Adjusting graphics settings if you encounter UI issues](/products/meet-pieces/troubleshooting/linux#adjusting-graphics--display-settings)

### Additional Assistance

If you’ve followed the applicable troubleshooting steps and still experience problems, consider visiting our community forums for additional guidance, opening a GitHub issue, or booking a call with our engineers.

[You can also find additional support resources here.](/products/support)

---

## Cross-Platform Issues
Path: /products/meet-pieces/troubleshooting/cross-platform

***

## Basic Troubleshooting

Find links to detailed sections on specific troubleshooting steps as well as information on system requirements and more.

<on-device-storage />

## Versions & Updates

Many issues can stem from out-of-date MCP integrations, the Pieces Desktop App, or PiecesOS itself.

### Updating PiecesOS

Both PiecesOS and the Pieces Desktop Application update automatically if installed through the Pieces Suite Installer.

For standalone installations (non-macOS/Linux store-based), updates are checked daily or upon application launch, prompting you to install or delay.

See your specific OS page for platform-specific instructions on updating PiecesOS:

* [macOS](/products/meet-pieces/troubleshooting/macos#updating-piecesos)

* [Windows](/products/meet-pieces/troubleshooting/windows#updating-piecesos)

* [Linux](/products/meet-pieces/troubleshooting/linux#updating-piecesos)

### Updating the Pieces Desktop App

Ensuring the Desktop App is up-to-date is critical.

See your specific OS page for platform-specific update instructions on updating the Pieces Desktop App:

* [macOS](/products/meet-pieces/troubleshooting/macos#updating-the-pieces-desktop-app)

* [Windows](/products/meet-pieces/troubleshooting/windows#updating-the-pieces-desktop-app)

* [Linux](/products/meet-pieces/troubleshooting/linux#updating-the-pieces-desktop-app)

## Connection Issues with PiecesOS

You may occasionally encounter connection issues with PiecesOS or your Personal Cloud, resulting in:

* Conversational Search not generating outputs

* Difficulty finding saved materials

* Trouble sharing code snippets

The quickest way to resolve this basic connection issue is to restart PiecesOS, then check for updates.

### Restarting PiecesOS & Checking Updates

To restart and check for updates to PiecesOS:

1. Restart PiecesOS

2. Ensure PiecesOS is running (look for the Pieces Icon in your system tray or menu bar)

3. Check for and install available updates

4. Verify that the Pieces Desktop Application and the MCP integration you are attempting to use is up-to-date

## Common Installation Issues

Common issues can occur when setting up PiecesOS and the Pieces Desktop App for the first time.

Platform-specific solutions are detailed on their respective OS pages:

* [macOS](/products/meet-pieces/troubleshooting/macos#common-installation-issues)

* [Windows](/products/meet-pieces/troubleshooting/windows#common-installation-issues)

* [Linux](/products/meet-pieces/troubleshooting/linux#common-installation-issues)

## System Requirements

Your device, regardless of platform, should meet the following basic system specifications for using Pieces software.

<pos-pfd-system-reqs />

## Vulkan-based GPUs

NVIDIA and AMD both utilize the Vulkan API framework in their GPUs, but there are known issues with using Vulkan GPUs for AI and LLM-centered workloads.

For example, a corrupted or outdated Vulkan API can cause crashes.

If you are experiencing this issue, you can check Vulkan health in your terminal or command line and scanning for errors or warning message—if there are any issues detected, **update your GPU drivers.**

### Checking Vulkan

To check your Vulkan health status, run `vulkaninfo` in your terminal or command line and look for errors or warnings.

### Updating GPU Drivers

If issues are detected, update your GPU drivers to ensure Vulkan compatibility and stability.

## Checking Hardware

It may be necessary to verify your system’s specifications if you experience ongoing issues.

See the OS-specific pages for instructions on how to check CPU, RAM, and GPU details:

* [macOS](/products/meet-pieces/troubleshooting/macos#checking-cpu-type)

* [Windows](/products/meet-pieces/troubleshooting/windows#checking-hardware-specifications)

* [Linux](/products/meet-pieces/troubleshooting/linux#checking-system-information)

---

## Issues | Linux
Path: /products/meet-pieces/troubleshooting/linux

***

## Installation & Updating Fixes

You can find detailed instructions on updating PiecesOS and the Pieces Desktop App on your Linux device using the terminal.

Additionally, you can check your system's OS and hardware specifications to ensure they meet the minimum recommended requirements.

<on-device-storage />

## Versions & Updates

Many issues can stem from running outdated versions of PiecesOS or the Pieces Desktop App on Linux.

### Updating PiecesOS

On Linux, PiecesOS and the Pieces Desktop App are distributed via snaps (for Ubuntu-based systems).

To update PiecesOS on Linux:

1. Run `snap info pieces-os` to check the current version of PiecesOS

2. Run `sudo snap refresh` to update PiecesOS if a newer version is available

### Updating the Pieces Desktop App

Similar to PiecesOS, you can update the Pieces Desktop App by:

1. Running `snap info pieces-for-developers` to check the current version

2. Running `sudo snap refresh` to apply any available updates

## Common Installation Issues

Official support is provided for **Ubuntu 22.04+ and Ubuntu-based distributions.** Other distributions may work but *aren’t guaranteed.*

### Checking Distribution Compatibility

Ensure you’re running a supported Ubuntu-based distribution.

If not, consider switching to a supported environment, as installation on non-Ubuntu distributions isn’t guaranteed.

### Updating Snapd

Snap-based installations require an up-to-date snap `daemon`:

* Run `sudo snap refresh` to ensure `snapd` and its packages are current

### Adjusting Graphics & Display Settings

If installation or UI issues persist, consider the following:

* **Switch Between X11 and Wayland:** Some applications may work better on one display protocol than the other. Try switching to X11 for compatibility or Wayland for newer features. You can usually select this at the login screen.  

  Restart after changing your graphics engine to ensure Pieces doesn't hit any snags on startup.

  **Supported setup:** **Ubuntu** with **X11**. **Wayland** usually needs follow-up from `pieces-os.doctor`. Other distros are **best-effort**. If capture or LTM fails, try an **X11 session**, re-run `pieces-os.doctor`, or use a **supported Ubuntu** install—**VMs** are the most variable.

* **Update your GPU Drivers:** Ensure they are up to date. For NVIDIA, check for proprietary driver updates. AMD and Intel users should verify that their open-source drivers are up to date.

* **Optimize Graphics Configurations:** Use tools like `nvidia-settings`, `radeon-profile`, or similar utilities to adjust your GPU settings for better performance and stability.

These adjustments can resolve many graphical and display-related issues you may experience while using Pieces or PiecesOS.

## Checking System Information

You can verify your system’s hardware configuration and ensure it meets recommended specifications by running specific commands in your terminal.

### Checking CPU Information

To determine your CPU type and find other important information, type `lscpu` in your terminal and press `Enter`.

### Checking GPU Information

To determine your GPU type and find other important information, `lspci | grep -i vga` in your terminal and press `Enter`.

Confirm that your CPU, GPU, and memory resources are sufficient for running PiecesOS.

See our [minimum hardware recommendations](/products/meet-pieces/troubleshooting/cross-platform#hardware-recommendations) for details.

### Checking Ubuntu Version

If the Pieces Installer is not working as intended, you could have an outdated version of Ubuntu. The minimum Ubuntu version that Pieces will run on is **Ubuntu 18**.

To check what version of Ubuntu you’re running:

* Open the **Settings** on Ubuntu

* Locate the **System** section at the bottom of the left-hand side menu and click it

* Open the **About** section and locate the **Operating System** label

This section will will display your Ubuntu version information.

### Consulting Online Resources

If you encounter persistent installation issues, consult online forums or community guides related to snap and Ubuntu-specific troubleshooting steps.

## Claude Desktop MCP on Linux

Pieces supports Snap and Flatpak installs. For the [Claude Desktop](/products/mcp/claude-desktop) MCP connection via `Settings` → `MCP` → `MCP Connections`, Claude only needs to point at the PiecesOS executable—no additional install is required.

* Quit Claude Desktop completely before clicking `Connect` if Claude is already running. Otherwise Claude can overwrite the settings Pieces just saved.
* When prompted, use `Restart Claude Desktop now` so the new settings load.
* If Connect fails after a Snap or Flatpak update, refresh PiecesOS, quit Claude, connect again, then restart Claude.

## Restart & Retry

If you’ve updated components, checked hardware, and adjusted configurations without success, restart your machine and try again.

If the problem persists, please open a <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> for further assistance, or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call with our engineers</a>.

---

## Issues | macOS
Path: /products/meet-pieces/troubleshooting/macos

***

## Installation & Updating Fixes

PiecesOS and the Pieces Desktop App can be downloaded using several installation methods, and they can be updated differently depending on the method used.

You can also find information below on how to determine your Apple device's CPU architecture and OS version.

<on-device-storage />

## Manual Installation Methods

If you’re experiencing difficulties installing PiecesOS or the Pieces Desktop App, you can manually install both software by downloading the standalone files or using terminal commands.

  Not sure which installer you need? See [how to check your CPU type](/products/meet-pieces/troubleshooting/macos#checking-cpu-type).

### via DMG Files

Make sure to select the correct Pieces `.dmg` files for your macOS device—Apple Silicon (ARM) or Intel.

| **Apple Silicon (ARM)**                                                                                                                                                                  | **Intel**                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a target="_blank" href="https://builds.pieces.app/stages/production/pieces_for_x/dmg-arm64/download?download=true&product=DOCUMENTATION_WEBSITE">Download Pieces Desktop App DMG for macOS (ARM)</a> | <a target="_blank" href="https://builds.pieces.app/stages/production/pieces_for_x/dmg/download?download=true&product=DOCUMENTATION_WEBSITE">Download Pieces Desktop App DMG for macOS (Intel)</a> |
| <a target="_blank" href="https://builds.pieces.app/stages/production/os_server/dmg-arm64/download?download=true&product=DOCUMENTATION_WEBSITE">Download PiecesOS DMG for macOS (ARM)</a> | <a target="_blank" href="https://builds.pieces.app/stages/production/os_server/dmg/download?download=true&product=DOCUMENTATION_WEBSITE">Download PiecesOS DMG for macOS (Intel)</a>              |

### via PKG Files

Make sure to select the correct Pieces `.pkg` for your macOS device—Apple Silicon (ARM) or Intel.

| **Apple Silicon (ARM)**                                                                                                                                                                                      | **Intel**                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a target="_blank" href="https://builds.pieces.app/stages/production/macos_packaging/pkg-pfd-arm64/download?download=true&product=DOCUMENTATION_WEBSITE">Download Pieces PKG for macOS (Apple Silicon / ARM)</a> | <a target="_blank" href="https://builds.pieces.app/stages/production/macos_packaging/pkg-pfd/download?download=true&product=DOCUMENTATION_WEBSITE">Download Pieces PKG for macOS (Intel)</a> |

### via Homebrew

A singular brew command, `brew install—- cask pieces`, automatically manages installing PiecesOS and the Pieces Desktop App.

## Versions & Updates

Many issues can stem from out-of-date MCP integrations, the desktop app, or PiecesOS. When you check for updates from either the Desktop App or the PiecesOS Quick Menu, both apps update together.

### From the Desktop App

    Click your profile or username in the top-left corner of the Pieces Desktop App.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it, then restart when complete.

> Profile menu in the Pieces Desktop App with `Check for Updates`

### From the PiecesOS Quick Menu

    Click the Pieces icon in your menu bar.

    Click `You're up to date` to trigger a check. If an update is available, follow the prompt to install.

> PiecesOS Quick Menu showing your current version and update status

## Common Installation Issues

There are a range of common install issues on Apple devices, like having an out-of-date OS version or selecting the wrong installation package.

### Checking OS Version

Pieces Suite applications require a minimum macOS version of **macOS 13.0 (Ventura).** If you’re experiencing installation issues, you should first check your OS version to make sure it’s up-to-date.

To determine your Apple device’s version of macOS:

1. Click the **Apple** icon in the top-left corner of your screen

2. Select `About This Mac`

3. Under your device name (i.e., MacBook Air), look for the last line on the list, titled `macOS`

The `macOS` line will report what version of macOS installed, e.g., `Sequoia 15.1.1`.

### Checking CPU Type

Intel and Apple Silicon (ARM) devices run on entirely separate CPU architectures, so downloading the wrong package for your Apple device can cause apps from the Pieces Suite to be rendered useless.

To determine what CPU architecture your Apple device utilizes:

1. Click the **Apple () icon** in the top-left corner of your screen.

2. Select **About This Mac**, and look for the **Overview section.** The first line will contain your CPU type:

* **Apple Silicon / ARM:** You will see an M-Series processor, e.g., `Apple M3`

* **Intel:** You will see an Intel processor, e.g., `2.6 GHz Intel Core i7`

Once you’ve determined your CPU architecture, [download the correct installation package accordingly.](/products/meet-pieces/macos-installation-guide#recommended-installation-method)

## macOS Permissions

PiecesOS requires specific macOS permissions to function properly. If features like *Long-Term Memory* or *Live Context* aren't working as expected, the most common cause is missing system permissions.

### Screen & System Audio Recording

PiecesOS needs *Screen & System Audio Recording* permission to capture on-screen context for features like *Long-Term Memory* and *Live Context*.

To enable this permission:

    Click the `Apple Icon` in the top-left corner of your screen and select `System Settings`

    Select `Privacy & Security` from the sidebar

    Scroll down and click `Screen & System Audio Recording`

    Find **Pieces OS** in the list and toggle it **on**. If Pieces OS is not listed, click the `+` button at the bottom of the list, then locate and add Pieces OS from your Applications folder.

    > macOS Screen & System Audio Recording settings with Pieces OS enabled.

  macOS may prompt you to quit and reopen Pieces OS for the permission change to take effect.

### Microphone

PiecesOS also requires *Microphone* access to capture audio context for *Long-Term Memory*.

To enable this permission:

    Click the `Apple Icon` in the top-left corner of your screen and select `System Settings`

    Select `Privacy & Security` from the sidebar

    Scroll down and click `Microphone`

    Find **Pieces OS** in the list and toggle it **on**. If Pieces OS is not listed, click the `+` button at the bottom of the list, then locate and add Pieces OS from your Applications folder.

    > macOS Microphone settings with Pieces OS enabled.

## Restart & Retry

If installation fails due to having an outdated version of macOS or installing the wrong package for your device’s architecture, restart your machine and try the installation again from scratch.

If the problem persists, please open a <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> for further assistance, or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call with our engineers</a>.

---

## Issues | Windows
Path: /products/meet-pieces/troubleshooting/windows

***

## Installation & Updating Fixes

PiecesOS and the Pieces Desktop App can be downloaded in several ways, and the update process varies based on the method you used, like whether you installed them via WinGet or `.exe` files.

<on-device-storage />

## Manual Installation Methods

If you’re experiencing difficulties with installing PiecesOS or the Pieces Desktop App, you can install both applications manually by downloading the standalone `.exe` or `.appinstaller` files.

### via EXE Files

You can download the individual `.exe` files for PiecesOS and the Pieces Desktop App by clicking the download links below.

    **Step 1:** Download PiecesOS (.EXE)

    *Required Core Dependency*

    Windows 10 (1809) or higher required.

    **Step 2:** Download Pieces (.EXE)

    *Alternative Method*

    Windows 10 (1809) or higher required.

### via WinGet

To install the Pieces Desktop App and PiecesOS using WinGet, follow these steps:

1. **Open a Terminal:** Launch Windows Terminal, Command Prompt, or PowerShell as *administrator*.

2. **Run the WinGet Command:** In the terminal, type `winget install “Pieces”` and press `enter`.

You may be prompted to enter `Y` or `N` to agree or disagree with the terms of use when installing the Pieces Desktop App—type and enter `Y` to proceed with the installation.

3. **Install PiecesOS:** Next, install PiecesOS by typing `winget install “Pieces OS”` and pressing `enter`.

You will be prompted to agree or disagree to the terms of use a second time, so enter `Y` to proceed with the installation.

Once this is finished, you can now launch the Pieces Desktop App by pressing the **Windows symbol** (`⊞`) or toggling the search bar and typing **Pieces,** clicking `Pieces Desktop`.

## Versions & Updates

Many issues can stem from out-of-date MCP integrations, the desktop app, or PiecesOS itself. When you check for updates from either the Desktop App or the PiecesOS Quick Menu, both apps update together.

### From the Desktop App

    Click your profile or username in the top-left corner of the Pieces Desktop App.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it, then restart when complete.

> Profile menu in the Pieces Desktop App with `Check for Updates`

### From the PiecesOS Quick Menu

    Click the Pieces icon in your system tray.

    Click `You're up to date` to trigger a check. If an update is available, follow the prompt to install.

> PiecesOS Quick Menu showing your current version and update status

## Issues Launching PiecesOS

Some users who have enabled Controlled Folder Access (CFA) as a security measure may receive a notification that Pieces is attempting to bypass this security wall.

To work around this issue, you will need to *add the executable path for PiecesOS* to your allowlist.

  The reason PiecesOS fails to launch when CFA is enabled is that the executable path for the PiecesOS application writes data to your Documents folder.

  CFA disables and blocks any request to modify files (in this case, writing & saving data), so PiecesOS is unable to launch itself.

Keep in mind that this path references the specific PiecesOS version, and so will change over time as long as you continue to update the software.

You can also disable CFA as a security measure if you do not require it as part of an enterprise scenario or for any other reason.

To decide which apps PiecesOS has access to, you can [easily enable and disable specific sources from the Long-Term Memory Access Control](/products/core-dependencies/pieces-os/quick-menu#long-term-memory-access-control) panel.

## Common Installation Issues

Windows users may encounter installation issues for various reasons, such as out-of-date OS components or incomplete dependencies.

### Checking for Windows Updates

Before installing, ensure your Windows system is fully updated:

1. Click the **Start** button, then select `Settings`

2. Click `Windows Update`

3. Install any pending updates and restart your computer

### Updating the Microsoft Store & App Installer

1. Open the **Microsoft Store**

2. Click on `Library` to check for available updates

3. Update the Microsoft Store and the App Installer if prompted

4. Retry installing the Pieces Suite

## Accessing Pieces Logs

On Windows, PiecesOS and the Desktop App store logs under separate folders in AppData. See [On-Device Storage](/products/core-dependencies/on-device-storage#finding-your-logs) for backup and database paths.

* **PiecesOS logs:**

```plaintext
C:\Users\\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support
```

* **Desktop App logs:**

```plaintext
C:\Users\\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\production\logs
```

  Replace \ with your Windows account name.

## Checking Hardware Specifications

It may be necessary to verify your system’s specifications if you experience ongoing issues, especially when running PiecesOS and the Long-Term Memory Engine.

To check your device specifications on Windows:

* Press the `Windows` key on your keyboard, or the `Windows` icon in the taskbar

* Type `run` and hit `enter`

* Type `dxdiag` and press enter on, or click, the blue `OK` button

The **System** tab displays your processor, the number of CPU cores, and memory (RAM), while the **Display** tab lists your GPU, its manufacturer (NVIDIA, AMD, Intel, etc.), and the available video memory (VRAM).

[Read documentation on the minimum recommended hardware specifications across all OS platforms.](/products/meet-pieces/troubleshooting/cross-platform#hardware-recommendations)

### Checking Windows Version

If the Pieces Installer is not working as intended, you could have an outdated version of Windows. The minimum Windows version that Pieces will run on is **Windows 10 20H0 or higher**.

To check what version of Windows you’re running:

* Press the `Windows` and the `R` keys simultaneously on your keyboard

* A new window will pop up, type `winver` and press `Enter`

A new window will open called **About Windows**, which will display your current Windows version.

  If this doesn't work, you're likely using a Windows version older than Windows 10.

## Restart & Retry

If the problem persists, please open a <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> for further assistance or <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">book a call with our engineers</a>.

---

## Installation Guide | Windows
Path: /products/meet-pieces/windows-installation-guide

## Install Pieces for Windows

Choose your installation method below. AppInstaller is recommended for most users.

    Installs Pieces Desktop and PiecesOS with automatic updates.

    Standalone installer for the Pieces Desktop App.

    Install via the Windows Package Manager.

### Requirements

* **Windows 10 (1809) or higher**
* **64-bit processor**

## Updating

Pieces automatically downloads and installs updates. When you check for updates from either the Desktop App or the PiecesOS Quick Menu, both apps update together.

### From the Desktop App

    Click your profile or username in the top-left corner of the Pieces Desktop App.

    Click `Check for Updates` in the dropdown menu.

    If an update is available, follow the on-screen prompt to install it, then restart when complete.

> Profile menu in the Pieces Desktop App with `Check for Updates`

### From the PiecesOS Quick Menu

    Click the Pieces icon in your system tray.

    Click `You're up to date` to trigger a check. If an update is available, follow the prompt to install.

> PiecesOS Quick Menu showing your current version and update status

  Pieces often downloads updates automatically and notifies you when a new version is ready. Use either method above to check manually.

## Uninstalling

Open **Settings**, then find **Apps** and search `Pieces`.

Two applications will appear—**Pieces Desktop** and **PiecesOS**. Click the three dots to the right of each application title and click `Uninstall`.

## Additional Resources

See the [Windows troubleshooting guide](/products/meet-pieces/troubleshooting/windows) or reach out to [support](/products/support) for help.

---

## AppInstaller | Windows
Path: /products/meet-pieces/windows-installation-guide/appinstaller

## AppInstaller (Recommended)

The AppInstaller method is the recommended way to install Pieces on Windows. It automatically installs PiecesOS alongside the Pieces Desktop App.

    *Recommended Method*

    Windows 10 (1809) or higher required.

  PiecesOS is a **required** Core Dependency. When using the AppInstaller method, PiecesOS will be installed automatically alongside the Pieces Desktop App—there is no need to download it separately.

### Install the AppInstaller

    Open your **Downloads** folder (or wherever you saved the installer) and look for the `.appinstaller` file you just downloaded.

    Double-click the `.appinstaller` file to launch the installation wizard.

    If prompted by Windows' User Account Control, click `Yes` to allow the installer to make changes.

### System Requirements

| **Component**      | **Minimum**                                                                   | **Recommended**                      | **Notes**                                                        |
| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
| *OS Version*       | Windows 10 (1809)                                                             | Windows 11                           | 64-bit required.                                                 |
| *CPU*              | Any modern CPU                                                                | Multi-core CPU                       | Avoid dual-core processors—aim for at least a 4-core CPU.        |
| *RAM*              | 8 GB total system RAM with 1 GB free                                          | 16 GB total system RAM or more       | More RAM improves performance with large workspaces.            |
| *Disk Space*       | 2 GB minimum (1 GB for PiecesOS + 0.5–1 GB for data), with at least 4 GB free | 8 GB with at least 6 GB free or more | Ensure additional free space for data storage and future growth. |

See our guide on [determining your OS version](/products/meet-pieces/troubleshooting/windows#checking-windows-version).

  **Don't install** Pieces or PiecesOS to **OneDrive** or other **cloud-synced** folders (Dropbox, Google Drive, etc.)—sync can interfere with installs and updates. Use the **default path** on a local drive.

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [Windows troubleshooting](/products/meet-pieces/troubleshooting/windows) for common solutions.

---

## EXE Installation | Windows
Path: /products/meet-pieces/windows-installation-guide/exe

## EXE Installation

The EXE installer is an alternative method for installing Pieces on Windows. Use this if the AppInstaller method doesn't work in your environment, such as enterprise systems with restricted policies.

    *Alternative Method*

    Windows 10 (1809) or higher required.

### Install the EXE

    Open your **Downloads** folder (or wherever you saved the file) and look for the `.exe` file you just downloaded.

    Double-click the `.exe` file to launch the Windows installation wizard.

    If prompted by Windows' User Account Control, click `Yes` to allow the installer to make changes.

    Pick a **local** folder (avoid OneDrive or other synced locations). The default path is recommended. Click `Install`.

    Optionally check `Create a desktop shortcut` or `Automatically start Pieces` based on your preferences.

    Click `Install` and wait for the installation to complete. Click `Finish` when done.

  **Don't install** Pieces or PiecesOS to **OneDrive** or other **cloud-synced** folders (Dropbox, Google Drive, etc.)—sync can interfere with installs and updates.

### Enterprise Environments

The EXE installer is recommended for enterprise environments or systems with advanced security settings that may block AppInstaller packages.

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [Windows troubleshooting](/products/meet-pieces/troubleshooting/windows) for common solutions.

---

## WinGet Installation | Windows
Path: /products/meet-pieces/windows-installation-guide/winget

## WinGet Installation

Install Pieces using WinGet for a streamlined terminal-based setup. WinGet is the Windows Package Manager built into Windows 10 and 11.

### Requirements

* **Windows 10 (1809) or higher** with WinGet installed
* WinGet comes pre-installed on Windows 11 and recent Windows 10 versions

### Install via WinGet

    Launch **Windows Terminal**, **Command Prompt**, or **PowerShell**.

    Copy and run the following command:

    ```bash
    winget install "Pieces"
    ```

    When prompted, enter `Y` to agree to the terms of use and proceed with the installation.

    WinGet will download and install Pieces. You'll see a success message when complete.

### Updating via WinGet

To update Pieces using WinGet:

```bash
winget upgrade "Pieces"
```

### Uninstalling via WinGet

To remove Pieces using WinGet:

```bash
winget uninstall "Pieces"
```

## Next Steps

After installation, explore [Conversational Search](/products/desktop/conversational-search) to start chatting with your memories, or configure [Long-Term Memory](/products/desktop/configuration/long-term-memory) to customize how Pieces captures your workflow context.

If you encounter issues, see [Windows troubleshooting](/products/meet-pieces/troubleshooting/windows) for common solutions.

---

## Organizations & Teams
Path: /products/organizations-and-teams

## Creating and Joining Organizations

Create a new organization to start collaborating with your team, or accept an invitation to join an existing organization. As an organization owner, you'll have full control over organization settings, member access, and shared resources.

> Account settings page showing Organizations & Teams section with Create organization button

  Learn how to create a new organization, accept invitations, and get started with team collaboration.

## Managing Organizations

As an organization owner or admin, you can manage members, configure settings, control billing, and oversee all aspects of your organization. Access powerful admin features to maintain team-wide consistency and control.

> Organization Home page showing management tools, setup instructions, and resource links

  Explore organization management features including member management, billing, and settings configuration.

## Organization Member Guide

As a member of an organization, you can collaborate with your team, view shared resources, and participate in team activities. Understand what you can do and how your role affects your access and permissions.

> Organization Home page from a member's perspective showing available features

  Learn about member features, permissions, and how to effectively collaborate within your organization.

## Troubleshooting

Resolve common issues when working with organizations, including authentication problems, workspace loading issues, and access problems.

> Troubleshooting guide showing common issues and solutions

  Find solutions to common organization access issues and authentication problems.

***

If Organizations & Teams isn't what you're looking for, check out [Account Settings](/products/desktop/configuration/account) to manage your personal account, or explore [Connected Applications](/products/desktop/configuration/connected-applications) to integrate third-party services with your organization.

---

## Billing
Path: /products/organizations-and-teams/billing

***

The Billing page allows you to manage your organization's subscription, view billing details, adjust seat counts, and add billing contact information.

> Billing tab showing subscription information, seats, and billing contact

## How to Get to Billing

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Billing` in the *sidebar* navigation.

## Viewing Subscription Information

    Go to [portal.pieces.app](https://portal.pieces.app), sign in, and select your organization. Click `Billing` in the sidebar.

    The *Subscription Information* section displays your current plan (e.g., "Enterprise Seat Yearly") and subscription status shown as an *Active* or *Canceled* badge.

    The *Billing* section shows your pricing breakdown:
    * **Price** — Cost per seat per billing period (e.g., "$275.99/seat per year")
    * **Total** — Combined cost for all seats (e.g., "$275.99 per year")
    * **Next billing date** — When your next payment will be processed
    * **Started** — Date when your subscription began

### Changing Your Plan

Click the `Change plan` button in the *Subscription Information* section to view available plans and switch your subscription to a different billing period or tier.

### Applying a Discount Code

Apply a discount code to your organization's active subscription. The discount takes effect at your next billing cycle.

    In the *Subscription Information* section, click the `Add discount` button.

    In the *Add Discount Code* modal, type your discount code into the input field.

    Click `Apply Discount` to save. The discount takes effect at your next billing cycle and is reflected on your next invoice.

### Changing Seat Count

Update the number of seats in your subscription to accommodate more or fewer team members.

    In the *Seats* section, use the `+` and `-` buttons to increase or decrease the number of seats, or type a number directly into the field.

    Below the seat count, a message shows how many members you have and the minimum seats required (e.g., "You have 1 member, so you need at least 1 seats"). You cannot set seats below this minimum.

## Billing Contact

Add or update billing contact information for invoices and payment correspondence. The *Billing Contact* section is located below the *Subscription Information* and *Seats* sections on the Billing page.

> Billing Contact section with fields for name, email, phone, and address

    From your organization's `Home` page, click `Billing` in the *sidebar* navigation.

    Scroll down past the *Subscription Information* and *Seats* sections. The *Billing Contact* section appears below, with fields for Name, Email, Phone, Country, Street address, City, State, and ZIP Code.

    If no billing contact is on file, click the `Add` button to enter your billing contact details. If a contact exists, edit the fields directly. A save reminder appears at the bottom of the page. Click `Save` to apply.

## Understanding Seat Minimums

Your organization must maintain a minimum number of seats based on your active member count.

* **Active Members** — Each active member requires one seat
* **Minimum Calculation** — Minimum seats equals the number of active members
* **Seat Reduction** — You can only reduce seats if you first remove members to free up seats
* **Seat Increase** — You can add seats at any time, billed according to your subscription plan

***

## Next Steps

Now that you understand billing, learn about [managing members](/products/organizations-and-teams/managing-members) to track seat usage, or explore [organization settings](/products/organizations-and-teams/organization-settings) to configure team-wide settings.

---

## Creating and Joining Organizations
Path: /products/organizations-and-teams/creating-and-joining-organizations

***

Create a new organization to start collaborating with your team, or accept an invitation to join an existing organization. Organizations allow you to share resources, manage team-wide settings, and collaborate effectively.

> Modal showing the walkthrough of creating an organization

## Creating an Organization

Set up a new organization to start collaborating with your team. The creation process includes selecting a subscription plan and configuring initial settings.

    Click your `User Profile` in the top left, then click `Settings` and select `Account`. Scroll down to the *Organizations & Teams* section and click the `+ Create an organization` button. Alternatively, you can access the creation flow from your Personal Workspace.

    You'll be redirected to the Pieces Auth page, where you can sign in with your account credentials. If you encounter issues, you can access the login page directly at [portal.pieces.app/auth/login](https://portal.pieces.app/auth/login).

    Enter your organization name in the *provided* field, then choose a name that clearly identifies your team or company.

    Select the number of seats for your organization using the `+` and `-` buttons or by typing a number. The number of seats determines how many team members can be invited. 
    
    You can adjust this later from the *billing* page.

    Choose your subscription plan:
    * **Enterprise Seat Yearly**: $275.99/seat/yr
    * **Enterprise Seat Quarterly**: $69.99/seat/quarter
    * **Enterprise Seat Monthly**: $22.99/seat/mo

    Click `Checkout` to proceed to the payment screen. Complete the payment process using PayPal, G Pay, or credit card through the *Paddle* payment system.

    After completing payment, you'll see a success screen and receive a confirmation email. Click the `X` in the top right of the *success popup* to proceed to the next step.

    You can invite team members by entering their email addresses and selecting roles (Owner, Admin, Write, or Read). Click `Send Invites & Finish` to complete setup, or click `Skip for Now` to invite members later.

  If you encounter a "Loading your workspace..." issue that prevents you from accessing your organization, you can resolve it by navigating to [portal.pieces.app/auth/logout](https://portal.pieces.app/auth/logout) to forcefully sign out, then sign back in to access your workspace.

## Joining an Organization

Accept an invitation to join an existing organization and start collaborating with your team.

    You'll receive an email invitation from the organization owner or admin. The email will contain details about the organization and your assigned role.

    Click the invitation link in the email to accept the invitation. You'll be immediately redirected to authenticate if needed.

    After accepting the invitation, you can access the organization from your Personal Workspace by clicking the *organization dropdown* in the *sidebar* to select and view the organization.

***

## Next Steps

Now that you've created or joined an organization, learn about [managing organizations](/products/organizations-and-teams/managing-organizations) to explore member management, billing, and settings, or check out the [Organization Home page](/products/organizations-and-teams/organization-overview) to learn how to navigate your organization dashboard.

---

## Inviting Members
Path: /products/organizations-and-teams/inviting-members

***

Add team members by sending invitations. You can invite one at a time, add multiple, or bulk upload via CSV. Each member needs an available seat.

> Invite members modal showing email input, role selection, and CSV upload option

## How to Open the Invite Modal

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click the `Invite people` button in the top right corner. The button is available from any tab (Home, Members, Models, Long Term Memory, Billing, Settings). The invite modal opens.

## Understanding Member Roles

Before inviting members, understand the different roles available and what each role can do within your organization.

> Member roles overview showing Owner, Admin, Write, and Read role descriptions

Each role has different permissions:

* **Owner** - Full control including organization deletion
* **Admin** - Full access except organization deletion
* **Write** - Can create and edit resources
* **Read** - View-only access

## Invitation Methods

Invite team members using different methods depending on your needs and team size.

### Inviting a Single Member

    Go to [portal.pieces.app](https://portal.pieces.app), sign in, and select your organization. Click `Invite people` in the top right corner (available from any tab).

    In the *Invite Organization Members* modal, enter the email address of the person you want to invite in the *email input* field.

    Click the `Select a role...` *dropdown* next to the email field and choose the appropriate role (Owner, Admin, Write, or Read).

    Click the `Send Invites & Finish` button (or `Send Invitations` if available) to send the invitation. The member will receive an email with instructions to join.

### Inviting Multiple Members

    Go to [portal.pieces.app](https://portal.pieces.app), sign in, and select your organization. Click `Invite people` in the top right corner (available from any tab).

    Enter the email address and select a role for the first member.

    Click the `+ Add another member` link below the first member's information.

    Repeat the process to add email addresses and roles for each additional member you want to invite.

    Once all members are added, click `Send Invites & Finish` to send invitations to all members at once.

### Bulk Inviting via CSV

    Go to [portal.pieces.app](https://portal.pieces.app), sign in, and select your organization. Click `Invite people` in the top right corner (available from any tab).

    Create a CSV file with the format: `email,role` (one member per line). For example:
    ```
    john@example.com,Admin
    jane@example.com,Write
    bob@example.com,Read
    ```

    In the *invite* modal, find the *Upload CSV* section. Click the `Upload CSV` button or drag and drop your CSV file into the *upload* area.

    Review the imported members and their roles, then click `Send Invites & Finish` to send all invitations.

## Understanding Seat Limitations

Your organization subscription includes a specific number of seats that determine how many active members you can have. Each active member uses one seat, and you cannot invite more members than you have available seats.

  You can only invite members if you have available seats in your subscription. If you see a "No seats available" warning, you'll need to upgrade your subscription or remove inactive members before inviting new ones.

### Checking Seat Availability

Before inviting members, check your current seat usage:

    From your organization's `Home` page, click `Members` in the *sidebar* navigation.

    At the top of the *Members* page, you'll see the *Seat Usage* card showing how many seats are used out of your total subscription (e.g., "1 of 1 seats used").

    If you need more seats, navigate to the *Billing* tab to increase your seat count. You can also remove inactive members to free up seats.

> Members tab showing seat usage card with current usage and total seats

### Seat Management

Understanding how seats work helps you manage your organization effectively:

* **Seat Usage** - View current seat usage in the *Members* tab
* **Upgrading Seats** - Increase seats from the *Billing* tab when you need to invite more members
* **Minimum Seats** - You must maintain at least one seat based on your number of active members
* **Available Seats** - Available seats = Total seats - Active members

***

## Next Steps

Now that you know how to invite members, learn about [managing members](/products/organizations-and-teams/managing-members) to update roles and handle member-related tasks, or explore [billing](/products/organizations-and-teams/billing) to manage your subscription and seat count.

---

## Managing Members
Path: /products/organizations-and-teams/managing-members

***

The Members tab provides a comprehensive view of all organization members, seat usage, pending invitations, and member management tools. Use this section to track membership, update roles, and manage access.

> Members tab showing seat usage, current members list, and pending invites

## How to Get to Members

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Members` in the *sidebar* navigation.

## Viewing Members and Seat Usage

    From your organization's `Home` page, click `Members` in the *sidebar* navigation.

    At the top of the Members page, you'll see the *Seat Usage* card showing how many seats are used out of your total subscription (e.g., "1 of 1 seats used") with a visual progress bar.

    Scroll down to the *Current Members* section to see a list of all active organization members, their email addresses, and their assigned roles (Owner, Admin, Write, or Read).

### Viewing Pending Invitations

Track invitations that have been sent but not yet accepted by members.

    In the *Members* page, click the `Pending Invites` tab at the top of the page.

    View all invitations that are waiting for acceptance. You'll see the email addresses and roles assigned to each pending invitation.

## Managing Members

Update member roles and remove members from your organization.

### Managing Member Roles

Update member roles to change their permissions and access levels within the organization.

    In the *Current Members* list, find the member whose role you want to change. Click the vertical ellipsis icon (three dots) next to their name to open the *member options* menu.

    Select the role dropdown and choose a new role:
    * **Owner**: Full control including deletion rights
    * **Admin**: Full access except organization deletion
    * **Write**: Can create and edit resources
    * **Read**: View-only access

    A save reminder appears at the bottom of the page. Click `Save` to apply the role change. The member's permissions will update immediately.

### Removing Members

Remove members from your organization when they no longer need access.

    In the *Current Members* list, click the vertical ellipsis icon next to the member you want to remove.

    Select `Remove from Organization` from the options menu.

    Confirm the removal action. The member will immediately lose access to the organization and their seat will become available.

## Understanding Seat Management

Seats are tied to your subscription and determine how many active members your organization can have.

> Seat usage card showing current usage and total seats available

Understanding how seats work helps you manage your organization effectively:

* **Active Members** - Each active member uses one seat
* **Minimum Seats** - You must maintain at least one seat based on your number of active members
* **Seat Availability** - Available seats = Total seats - Active members
* **Upgrading** - Increase seats from the *Billing* tab when you need to invite more members

***

## Next Steps

Now that you understand member management, learn about [billing](/products/organizations-and-teams/billing) to manage your subscription and seat count.

---

## Managing Organizations
Path: /products/organizations-and-teams/managing-organizations

***

## Organization Home

Access your organization's Home page to get set up, navigate to management tools, and find helpful resources for your team.

> Organization Home page showing setup instructions, management links, and resource cards

  Learn how to navigate your organization Home page, access setup resources, and manage your organization.

## Inviting Members

Add team members to your organization by sending invitations. You can invite members individually, add multiple members at once, or bulk upload via CSV.

> Invite members modal showing email input, role selection, and CSV upload option

  Discover how to invite team members, assign roles, and use bulk invitation methods.

## Managing Members

View and manage all organization members, track seat usage, handle pending invitations, and update member roles and permissions.

> Members tab showing seat usage, current members list, and pending invites

  Learn how to manage member roles, view seat usage, and handle member-related tasks.

## Billing

Manage your organization's subscription, update seat counts, view billing information, and configure billing addresses.

> Billing tab showing subscription details, seat count, and billing address options

  Learn how to manage subscriptions, update seats, and configure billing information.

## Models (Organization Management for AI)

The Models section is the organization management area for AI configuration. It appears as a top-level item in the sidebar with two tabs: *Models* (general settings, allow-lists, BYOK) and *API Keys* (OpenAI, Anthropic, GCP credentials).

> Models section showing general settings and API keys configuration

  Configure model allow-lists, BYOK, and API keys for your organization.

## Long Term Memory

Configure context capture settings, application sources, denied websites, and default models for memory processing. Long Term Memory is a top-level item in the sidebar.

> Long Term Memory section showing Memory Formation toggles and Default Models

  Configure context capture, application sources, denied websites, and default models for LTM.

## Organization Settings

Configure organization-wide settings that sync to team members' Pieces Desktop and PiecesOS installations. Settings includes General (contact info, address) and Features (External Cloud, Analytics toggles).

> Settings page showing tabs for General and Features

  Discover how to configure organization settings and control feature toggles.

***

## Next Steps

Now that you understand organization management, learn about [Account Settings](/products/desktop/configuration/account) to manage your personal account, or explore how to [create and join organizations](/products/organizations-and-teams/creating-and-joining-organizations).

---

## Member Overview
Path: /products/organizations-and-teams/member-overview

***

As a member of an organization, you can access the organization's Home page to get set up with Pieces, view resources, and collaborate with your team. Your view is similar to owners and admins, but with limitations on administrative features.

## Accessing Your Organization

Navigate to your organization from your Personal Workspace to access the Home page.

    Click your `User Profile` in the top left, then click `Settings` and select `Account` to access your Personal Workspace.

    In the *sidebar*, click the *organization dropdown* at the top. Select the organization you want to access from the list of organizations you belong to.

    The Home page displays setup instructions, management links, and resources for your organization.

## Understanding Member Limitations

As a member, you have access to collaboration features but cannot access administrative functions.

  Members cannot access:
  * Member management (inviting, removing, or changing roles)
  * Billing and subscription management
  * Organization settings configuration
  
  These features are reserved for Owners and Admins. If you need administrative access, contact your organization owner or admin.

## Available Sidebar Navigation

The *sidebar* includes the following navigation options available to members:

* **Home** — Dashboard showing setup, management, and resource links
* **Members** — View organization members (read-only access)

Administrative sections like *Billing* and *Settings* are not visible to members and are reserved for Owners and Admins.

***

## Next Steps

Now that you understand the member overview, learn about [member permissions](/products/organizations-and-teams/member-permissions) to understand what you can do based on your role, or explore [managing organizations](/products/organizations-and-teams/managing-organizations) if you become an Owner or Admin.

---

## Member Permissions
Path: /products/organizations-and-teams/member-permissions

***

Understanding your role and permissions helps you know what you can do within your organization and what requires owner or admin access. Each role has specific capabilities and limitations.

## Understanding Roles

Organizations have four main roles with different permission levels. Each role determines what you can do within the organization.

> Members tab showing seat usage and member list with role indicators

The four roles are:

* **Owner** - Full control including organization deletion
* **Admin** - Full access except organization deletion
* **Write** - Can create and edit resources
* **Read** - View-only access

## Role Permissions

Each role has specific capabilities and limitations that determine what you can do within an organization.

### Read Role Permissions

Members with the Read role have the most limited access. They can view content but cannot create or modify anything.

**What Read members CAN do:**

* View organization Home page and resources
* View organization members list

**What Read members CANNOT do:**

* Invite or manage members
* Access billing or settings

### Write Role Permissions

Members with the Write role can create and edit content but cannot manage the organization.

**What Write members CAN do:**
* Everything Read members can do, plus:
* Create and manage their own content

**What Write members CANNOT do:**
* Invite or manage members
* Change member roles
* Access billing or settings
* Manage organization-wide settings

### Admin Role Permissions

Admins have extensive access but cannot delete the organization.

**What Admins CAN do:**
* Everything Write members can do, plus:
* Invite and manage members
* Change member roles
* Access billing and manage subscriptions
* Configure organization settings
* Manage all organization content

**What Admins CANNOT do:**
* Delete the organization (reserved for Owners)

### Owner Role Permissions

Owners have full control over the organization.

**What Owners CAN do:**
* Everything Admins can do, plus:
* Delete the organization
* Full control over all organization resources

## How Permissions Affect Daily Use

Your role determines what you see and can do in the organization interface:

* **Sidebar Navigation** - Read and Write members see fewer options than Admins and Owners
* **Action Buttons** - Some buttons (like `Invite people`) only appear for Admins and Owners
* **Settings Access** - Only Admins and Owners can access the *Settings* and *Billing* sections
* **Content Management** - Your ability to manage content depends on your role

## Requesting Access Changes

If you need different permissions to perform your work:

    Contact your organization Owner or Admin to request a role change.

    Explain what you need to do and why you need different permissions.

    If appropriate, the Owner or Admin can update your role. Role changes take effect immediately and affect what you can access in the organization.

***

## Next Steps

Now that you understand member permissions, learn about [member overview](/products/organizations-and-teams/member-overview) to see what features are available to you, or explore [managing organizations](/products/organizations-and-teams/managing-organizations) if you become an Owner or Admin.

---

## Organization Member Guide
Path: /products/organizations-and-teams/organization-member-guide

***

As a member of an organization, you can collaborate with your team, view shared resources, and participate in team activities. This guide covers what you can do as a member and how your role affects your access and permissions.

## Organization Home

Access your organization's Home page to get set up with Pieces and collaborate with your team. Members can view resources and participate in team activities while having limited administrative access.

> Organization Home page from a member's perspective showing available features

  Learn how to navigate your organization Home page and collaborate with your team as a member.

## Understanding Member Permissions

Learn about the different member roles and what each role can and cannot do within an organization.

> Member permissions overview showing role differences and access levels

  Understand member roles, permissions, and how they affect what you can do in your organization.

***

As a member, you have access to collaboration features while administrative functions are reserved for Owners and Admins. Learn more about [managing organizations](/products/organizations-and-teams/managing-organizations) if you become an Owner or Admin.

---

## Organization Overview
Path: /products/organizations-and-teams/organization-overview

## Organization Home

The Home page is your central dashboard for managing your organization in the Pieces User Portal. The sidebar gives you quick access to Members, Models, Long Term Memory, Billing, and Settings.

> Organization Home page with Setup, Manage, and Resources sections

## How to Get to Your Organization

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Or from Pieces Desktop, click your `User Profile` in the top left → `Settings` → `Account`.

    In the *sidebar*, click the *organization dropdown* at the top (shows your org name). Select the organization you want to access.

    The Home page shows setup instructions, management links, and resources. Use the sidebar to jump to any section.

## How to Get to Each Section

Use the sidebar to reach the main organization areas:

    Click `Members` in the sidebar to view members, seat usage, and pending invites. Click `Invite people` to add new members.

    Click `Models` in the sidebar to configure AI models and API keys. Use the *Models* tab for provider toggles and allow-lists; use the *API Keys* tab to add credentials.

    Click `Long Term Memory` in the sidebar to manage context capture, blocked applications, blocked websites, and default models.

    Click `Billing` in the sidebar to view your plan, change seats, and manage billing contact. Owners and Admins only.

    Click `Settings` in the sidebar to configure General (org name, contact, domains) and Features (External Cloud, Analytics). Owners and Admins only.

## Setup, Manage, and Resources

The Home page body has three areas:

* **Setup** — Prompts to sign in with your account email in Desktop & PiecesOS, plus buttons to open or download Pieces Desktop.
* **Manage** — Cards that link directly to Members, Models, and Billing. Click a card to jump to that section.
* **Resources** — Links to documentation, pro tips, support, and GitHub.

***

## Next Steps

[Invite members](/products/organizations-and-teams/inviting-members), configure [Models and API keys](/products/organizations-and-teams/settings-models), or check [Settings](/products/organizations-and-teams/organization-settings) for General and Features.

---

## Organization Settings
Path: /products/organizations-and-teams/organization-settings

***

## How to Get to Settings

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Settings` in the *sidebar* navigation.

## General Settings

Configure basic organization information, contact details, and address. Update your organization's identity and how Pieces reaches you for billing and support.

> General settings tab showing organization name, contact info, and address fields

  Learn how to update organization details, contact information, and address.

## Features Settings

Toggle organization-wide features that sync to team members' Pieces Desktop and PiecesOS. Control external cloud, analytics, and reporting features.

> Features settings tab showing External Cloud and Analytics toggles

  Learn how to enable and disable features that sync across your team's installations.

## Models and Long Term Memory

Model access, API keys, and Long Term Memory settings are managed from separate sections in the sidebar:

* **Models** — Organization management for AI configuration. Click `Models` in the sidebar to access the Models tab (allow-lists, BYOK) and the API Keys tab (OpenAI, Anthropic, GCP credentials).
* **Long Term Memory** — Manage context capture settings, application sources, denied websites, and default models for memory processing. Click `Long Term Memory` in the sidebar to access.

  Configure model access and API keys for your organization.

  Configure Long Term Memory settings and context capture.

***

All organization settings automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring consistent configuration across your team.

## Next Steps

Now that you understand organization settings, learn about [Models and API keys](/products/organizations-and-teams/settings-models) to configure AI providers, or explore [Long Term Memory](/products/organizations-and-teams/settings-ltm-sources) to control context capture and default models.

---

## API Keys Settings
Path: /products/organizations-and-teams/settings-api-keys

***

The API Keys tab is one of two tabs within the *Models* section—the organization management area for AI configuration. From the API Keys tab, you configure credentials for model providers (OpenAI, Anthropic, GCP). These API keys automatically sync to all team members' Pieces Desktop and PiecesOS installations, enabling your team to use these services without individual configuration.

> API Keys tab showing OpenAI, Anthropic, and GCP configuration sections

  All API keys configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, allowing your entire team to use these AI services with organization-managed credentials.

## How to Get to the API Keys Tab

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Models` in the *sidebar* navigation.

    On the Models page, click the `API Keys` tab at the top.

## Configuring API Keys

Set up API credentials for model providers. Each provider has its own configuration section: OpenAI, Anthropic (Claude), and GCP Configuration.

### Configuring OpenAI

Set up OpenAI API credentials for your organization.

    Find the *OpenAI* section with the description "API credentials and organization settings."

    Click the `+ Add API Key` button next to the OpenAI section.

    Fill in the form with:
    * **Name** (required) — A descriptive name (e.g., "Personal Pro", "Production")
    * **API Key** (required) — Your OpenAI API key
    * **Organization ID** (optional) — For OpenAI org-specific usage
    * **Project ID** (optional) — For project-specific usage
    * **Custom API URL** (optional) — Defaults to `https://api.openai.com`

    A save reminder appears at the bottom of the page. Click `Save` to save your OpenAI credentials. The credentials will sync to all team members.

### Configuring Anthropic (Claude)

Set up Anthropic Claude API credentials for your organization.

    Find the *Anthropic (Claude)* section with the description "API credentials."

    Click the `+ Add API Key` button next to the Anthropic section.

    Fill in the Anthropic-specific credential form with your API key and any required configuration details.

    A save reminder appears at the bottom of the page. Click `Save` to save your Anthropic credentials.

### Configuring GCP

Set up GCP API keys and Vertex AI service accounts for your organization.

    Find the *GCP Configuration* section with the description "Manage GCP API keys and Vertex AI service accounts."

    Click the `+ Add API Key` button next to the GCP Configuration section.

    Fill in the GCP-specific credential form with your API key and service account details.

    A save reminder appears at the bottom of the page. Click `Save` to save your GCP credentials.

## Managing API Keys

View, edit, and remove existing API key configurations.

> Edit API Key form showing name, API key, and optional fields

    Review all configured API keys in their respective sections. Each section shows "No API keys configured" if none are set up.

    Use the edit icon to modify an existing key or the delete icon to remove it. When editing, you can update the name, API key, Organization ID, Project ID, or Custom API URL.

    A save reminder appears at the bottom of the page. Click `Save` to apply your changes. A warning appears if you have unsaved changes when navigating away.

***

## Next Steps

Now that you understand API keys settings, explore [Models Settings](/products/organizations-and-teams/settings-models) to configure model access and BYOK, or check out [Features Settings](/products/organizations-and-teams/settings-features) to configure team-wide feature toggles.

---

## Features Settings
Path: /products/organizations-and-teams/settings-features

***

The Features settings tab allows you to control organization-wide feature toggles that automatically sync to all team members' Pieces Desktop and PiecesOS installations. These settings ensure consistent feature availability across your team.

> Features settings tab showing various feature toggles and processing options

  All feature settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring everyone has the same feature availability.

## How to Get to Features Settings

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Settings` in the *sidebar* navigation.

    Click the `Features` tab at the top of the Settings page.

## Feature Categories

Configure organization-wide features organized by category. All feature settings automatically sync to team members' Pieces Desktop and PiecesOS installations. Model access and API keys are configured in the [Models](/products/organizations-and-teams/settings-models) section (organization management for AI).

### External Cloud

Control cloud-related operations and features for your organization.

    Find the *External Cloud* section in the *Features* tab.

    Use the toggle switch next to *External Cloud* to enable or disable cloud connectivity, backup management (create, list, restore, delete), snippet sharing, and cloud allocation updates.

    A save reminder appears at the bottom of the page. Click `Save` to apply. The setting will sync to all team members.

### Analytics

Configure analytics and reporting features for your organization.

    Find the *Analytics* section in the *Features* tab.

    Use the toggle switch next to *Telemetry* to enable or disable BigQuery and Segment analytics integrations.

    Use the toggle switch next to *Send Internal Summary Reports* to enable or disable sending internal summary reports to user team service.

    A save reminder appears at the bottom of the page. Click `Save` to apply your analytics settings.

***

## Next Steps

Now that you understand features settings, explore [Models and API Keys](/products/organizations-and-teams/settings-models) to configure AI providers and BYOK, or check out [Long Term Memory](/products/organizations-and-teams/settings-ltm-sources) to configure context capture and default models.

---

## General Settings
Path: /products/organizations-and-teams/settings-general

***

The General settings tab allows you to configure basic organization information, contact details, associated domains, SSO integration, and delete your organization. These settings control fundamental aspects of your organization's identity and access.

> General settings tab showing organization name, contact info, domains, and danger zone

## How to Get to General Settings

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Settings` in the *sidebar* navigation.

    Click the `General` tab at the top. It's the default tab when you open Settings.

## Configuring Organization Details

Update basic organization information, domains, and integration settings.

### Updating Organization Information

Modify your organization's basic details including name, contact information, and address.

    In the *Organization Name* field, update your organization's name as needed.

    Update the following contact fields:
    * **Name** — Name of the primary contact person
    * **Email** — Primary email address for the organization
    * **Phone** — Contact phone number

    Fill in or modify the organization address fields:
    * **Country** — Select from the *dropdown*
    * **Street address** — Enter street address
    * **City** — Enter city name
    * **State** — Select state from *dropdown*
    * **ZIP Code** — Enter ZIP/postal code

    A save reminder appears at the bottom of the page. Click `Save` to apply your changes.

### Configuring Associated Domains

Set up domains that are associated with your organization for automatic user assignment.

    In the *Associated Domains* section, enter a domain name (e.g., `example.com`) in the *input* field.

    Click the `+` button next to the *domain* field to add additional domains. You can add multiple domains to your organization.

    A save reminder appears at the bottom of the page. Click `Save` to save your domain configuration.

### Setting Up SSO Integration

Configure SSO (Single Sign-On) integration using a tenant ID for *Descope* integration.

    In the *Tenant ID* field, enter your *Descope* tenant ID for SSO integration (e.g., `tenant-1234567890`).

    A save reminder appears at the bottom of the page. Click `Save` to save your SSO configuration. This is optional and only needed if you're using *Descope* for SSO integration.

## Deleting an Organization

Permanently delete your organization and all associated data. This action cannot be undone.

  Deleting an organization is permanent and irreversible. This will permanently delete all organization data, member associations, and billing information. Subscriptions will be cancelled. Make sure you have backups of any important data before proceeding.

    Scroll down to the bottom of the General settings tab to find the *Danger Zone* section, which is highlighted in red.

    Review the warning message that explains what will be deleted:
    * All organization data and settings
    * All member associations
    * All billing and subscription information (subscriptions will be cancelled)

    Type your organization name exactly as it appears (e.g., "Pieces Test Organization") in the *confirmation* field to confirm deletion.

    Click the `Delete Organization` button. You'll be asked to confirm this action one more time before the organization is permanently deleted.

***

## Next Steps

Now that you understand general settings, explore other organization settings like [Features Settings](/products/organizations-and-teams/settings-features) to configure team-wide features, or check out [Models](/products/organizations-and-teams/settings-models) (including the API Keys tab) to configure AI providers and credentials.

---

## Long Term Memory Settings
Path: /products/organizations-and-teams/settings-ltm-sources

***

The Long Term Memory section allows you to configure context capture settings, manage which applications and websites Pieces can access, and set default models for memory processing. These settings automatically sync to all team members' Pieces Desktop and PiecesOS installations. Long Term Memory is a top-level section in the organization sidebar.

> Long Term Memory section showing Memory Formation toggles and Default Models

  All Long Term Memory settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring consistent context capture and model configuration across your team.

  To enable LTM websites or applications: turn **on** the corresponding toggle in the General tab, then use the *Applications* or *Websites* tab to manage what's blocked. To fully turn off: turn the toggle **off** in the General tab.

## How to Get to Long Term Memory

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Select your organization from the *sidebar* dropdown if needed.

    Click `Long Term Memory` in the *sidebar* navigation.

    The *General* tab shows Memory Formation toggles and Default Models. Use *Applications* and *Websites* tabs to manage blocked apps and sites after enabling their toggles.

## Enabling Memory Formation Toggles

The *General* tab has three toggles that control how Pieces captures context. Turn them on or off as needed.

    In the *General* tab, find *Audio Context Capture* and turn the toggle **on** to let Pieces process audio (meetings, conversations) for memory. Turn **off** to disable.

    Turn the *Organization managed application sources* toggle **on** to control which applications Pieces can access. When on, click `Manage applications` or open the *Applications* tab to allow or block apps. Turn **off** to disable organization-managed app control.

    Turn the *Organization managed denied websites* toggle **on** to block specific websites from Long Term Memory. When on, click `Manage websites` or open the *Websites* tab to add blocked sites. Turn **off** to disable organization-managed website blocking.

    A save reminder appears at the bottom of the page. Click `Save` to apply. Settings sync to all team members.

## Configuring Default Models

Default models are used for memory event processing, auto-generated summaries, and audio transcription. Configure them after setting up API keys in [Models](/products/organizations-and-teams/settings-models).

> Default Models section on the LTM General tab showing model assignment options

    In the *General* tab, find the *Default Models* section and click the `Manage models` button.

    For each feature (Memory event processing, Auto-generated summaries, Audio transcription), choose a primary model and optional fallback. Models come from your enabled providers and API keys.

    A save reminder appears at the bottom of the page. Click `Save` to apply. Default models sync to all team members.

## Managing Application Access

When *Organization managed application sources* is enabled in the General tab, click the `Manage applications` button or select the *Applications* tab to manage which applications Pieces can access for context capture.

> Available applications list showing application names, bundle IDs, and toggle switches

### Viewing Applications

The *Applications* tab shows two sections: *Blocked Applications* (apps blocked from context capture) and *Available Applications* (apps that can be allowed or blocked). Each application has a toggle to enable or disable it for context capture.

    Click the `Applications` tab at the top of the Long Term Memory page.

    The *Available Applications* section displays applications Pieces can access. Each application shows:
    * Application name
    * Global tag (if applicable)
    * Related bundle IDs and identifiers

    Use the search bar at the top with the placeholder "Search applications by name..." to quickly find specific applications.

    Each application has a toggle switch. Turn it **on** to allow context capture from that application, or **off** to block it.

### Adding New Applications

Add custom applications to control access for specific tools your team uses.

    Click the `+ Add Application` button at the top of the *Applications* tab.

    In the *Add New Application* modal, enter the application name in the *Application Name* field (e.g., "Chrome", "Safari", "Firefox").

    In the *Bundle IDs* field, enter bundle identifiers to help identify specific applications (e.g., `com.example.app`). Click the `+` icon to add multiple bundle IDs.

    Click the `Create` button to add the application to your list. The application will appear in the *Available Applications* section.

### Enabling or Disabling Applications

Toggle access on or off for specific applications. Enable an application to allow context capture from it; disable it to block it from Long Term Memory.

    Find the application in the *Blocked Applications* or *Available Applications* list.

    Use the toggle switch next to the application name. Turn **on** to allow context capture, or **off** to block it.

    A save reminder appears at the bottom of the page. Click `Save` to apply. The settings will sync to all team members.

## Understanding Global vs Organization Settings

Some applications may have a *Global* tag, indicating they are system-wide applications. Organization-specific settings allow you to override or supplement global settings for your team.

* **Global Applications** - System-wide applications that affect all users
* **Organization Settings** - Your organization's specific access controls that sync to team members

***

## Next Steps

Now that you understand LTM sources settings, explore [LTM Websites Settings](/products/organizations-and-teams/settings-ltm-websites) to configure which websites Pieces is denied from accessing, or check out [Features Settings](/products/organizations-and-teams/settings-features) to configure team-wide features.

---

## LTM Websites Settings
Path: /products/organizations-and-teams/settings-ltm-websites

***

The LTM Websites settings allow you to configure which websites are blocked from Long Term Memory. You must **enable** *Organization managed denied websites* in the General tab first; then use the *Websites* tab to add blocked sites. **Disable** the toggle to fully turn off organization-managed website blocking. These settings automatically sync to all team members' Pieces Desktop and PiecesOS installations.

> Blocked websites list with add input and CSV upload

  All LTM website settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations, ensuring consistent blocked website lists across your team.

## Accessing LTM Websites Settings

Enable the toggle in the General tab, then use the Websites tab to manage blocked sites.

> Enabling Organization managed denied websites in the General tab

    From your organization's `Home` page, click `Long Term Memory` in the *sidebar* navigation.

    In the *General* tab, turn on the *Organization managed denied websites* toggle in the Memory Formation section. You can also click the `Manage websites` button to jump to the Websites tab.

    Click the `Websites` tab at the top of the Long Term Memory page to add or manage blocked websites.

## Managing Blocked Websites

The *Blocked websites* section lists sites that will not be tracked or used for Long Term Memory. Add websites individually or upload multiple sites via CSV.

### Adding Blocked Websites Manually

Add individual websites to the blocked list.

    In the input field (placeholder: "example.com or https://example.com"), enter the URL or domain you want to block (e.g., `example.com` or `https://example.com`).

    Click the `+ Add` button to add the website to your blocked list.

    A save reminder appears at the bottom of the page. Click `Save` to apply. Your blocked websites list will sync to all team members.

### Bulk Uploading Blocked Websites

Upload multiple websites at once using a CSV file. Format: one website per line.

    Create a CSV file with one website URL or domain per line. For example:
    ```
    https://example.com
    another-site.com
    third-site.com
    ```

    Click the `Upload CSV` button or drag and drop your CSV file into the upload area.

    Review the imported websites. A save reminder appears at the bottom of the page. Click `Save` to add them to your blocked list.

### Removing Blocked Websites

To allow a website for Long Term Memory again, remove it from the blocked list.

    Find the website in the *Blocked websites* list.

    Click the trash icon next to the website to remove it from the blocked list.

    A save reminder appears at the bottom of the page. Click `Save` to apply your changes.

## Understanding Blocked Websites

When a website is added to the *Blocked websites* list, it will not be tracked or used for Long Term Memory. This helps you control what information Pieces can collect and use.

* **Privacy Control** — Prevent Pieces from accessing sensitive or private websites
* **Team Consistency** — All team members share the same blocked website list
* **Fully Disable** — Turn off the *Organization managed denied websites* toggle in the General tab to disable organization-managed website blocking entirely

***

## Next Steps

Now that you understand LTM websites settings, explore [LTM Applications](/products/organizations-and-teams/settings-ltm-sources) to control which applications are blocked or allowed for context capture, or check out [Features Settings](/products/organizations-and-teams/settings-features) to configure team-wide features.

---

## Models Settings
Path: /products/organizations-and-teams/settings-models

***

The Models section is the organization management area for AI. From here you control which models are available, enable or disable providers (Google, OpenAI, etc.), and set up API keys. All settings sync to team members' Pieces Desktop and PiecesOS.

With BYOK enabled, your organization chooses exactly which models are available—pick and choose specific models per provider through the allow-list, and manage credentials in the API Keys tab. These organization-level controls live here so members get a consistent, governed model set.

> Models page showing provider sections (Google, OpenAI) with model lists and toggles

  All model settings configured here automatically sync to team members' Pieces Desktop and PiecesOS installations.

## How to Get to the Models Page

    Go to [portal.pieces.app](https://portal.pieces.app) and sign in. Or from Pieces Desktop, click your `User Profile` → `Settings` → `Account` to reach your workspace.

    In the *sidebar*, click the *organization dropdown* at the top and select your organization.

    Click `Models` in the *sidebar* navigation. The Models page opens with the *Models* tab selected. Use the `API Keys` tab to add provider credentials.

## Enabling the Customized Model Allow-List

By default, all models from enabled providers are available. To control which providers and models members can use, you must first enable the customized model allow-list. **The provider toggles (Google, OpenAI, etc.) are only active when the allow-list is enabled.**

    On the Models page, find the *Customized Model Allow-List* toggle and turn it **on**.

    A save reminder appears at the bottom of the page. Click `Save` to apply. The provider sections below become active so you can enable or disable providers and select specific models.

## Enabling or Disabling a Provider (Google, OpenAI, etc.)

  The customized model allow-list must be enabled for provider toggles to be active. See the section above.

Each provider (Google, OpenAI, Anthropic, etc.) has a toggle at the top of its section. Turn it on to make that provider's models available; turn it off to disable them.

> Provider sections with on/off toggles for Google, OpenAI, and other providers

    Ensure the *Customized Model Allow-List* toggle is **on** near the top of the Models page. Provider toggles are inactive until the allow-list is enabled.

    On the Models page, scroll to the provider you want to change (e.g., *Google*, *OpenAI*).

    Use the toggle switch at the top right of the provider section. Turn it **on** to enable that provider's models for your organization, or **off** to disable them.

    A save reminder appears at the bottom of the page. Click `Save` to apply. Changes sync to all team members.

## Selecting Allowed Models

With the allow-list and provider toggles configured, choose which specific models members can use.

    On the Models page, scroll to each enabled provider (e.g., *Google*, *OpenAI*).

    Use the checkboxes or controls next to each model to include or exclude it. Only models you explicitly allow will be available to members.

    A save reminder appears at the bottom of the page. Click `Save` to apply.

## Adding API Keys for Providers

To use models from OpenAI, Anthropic, or GCP, you need to add API keys. Switch to the API Keys tab within Models.

    On the Models page, click the `API Keys` tab at the top.

    Find the provider section (OpenAI, Anthropic, GCP) and click `+ Add API Key`. Enter your credentials and click `Save`.

    Switch back to the *Models* tab to enable that provider and choose which models to use.

For full API key instructions, see [API Keys Settings](/products/organizations-and-teams/settings-api-keys).

***

## Next Steps

Add credentials in [API Keys](/products/organizations-and-teams/settings-api-keys), or configure [Long Term Memory](/products/organizations-and-teams/settings-ltm-sources) for context capture and default models.

---

## Troubleshooting Organizations & Teams
Path: /products/organizations-and-teams/troubleshooting

***

If you encounter issues when creating, accessing, or managing organizations, use this guide to resolve common problems.

> Troubleshooting guide showing common issues and solutions

### "Loading your workspace..." Stuck Issue

If you get stuck on a "Loading your workspace..." screen when trying to access your organization, you can resolve this by forcing a logout and re-authenticating.

    In your browser, navigate directly to [portal.pieces.app/auth/logout](https://portal.pieces.app/auth/logout). This will forcefully sign you out of your current session.

    Wait for the logout process to complete. You should be redirected to a sign-in page or see a confirmation that you've been logged out.

    Navigate to [portal.pieces.app/auth/login](https://portal.pieces.app/auth/login) and sign back in with your account credentials.

    After signing back in, you should be able to access your Personal Workspace and organizations without the loading issue.

### Cannot Access Organization After Creation

If you've created an organization but cannot access it:

    Verify that you received a success email confirming your organization creation. Check your spam folder if you don't see it.

    Ensure you're signed in to the correct account that was used to create the organization.

    Use the logout/login process described above to refresh your session.

    In your Personal Workspace, check the *organization dropdown* in the sidebar to see if your organization appears in the list.

### Cannot Accept Organization Invitation

If you're having trouble accepting an organization invitation:

    Make sure you're clicking the invitation link from the email sent by the organization owner or admin.

    Ensure you're signed in to the account that matches the email address the invitation was sent to.

    If the invitation link doesn't work, try logging in directly at [portal.pieces.app/auth/login](https://portal.pieces.app/auth/login), then check your Personal Workspace for the organization.

    If you still cannot accept the invitation, contact the organization owner or admin to verify the invitation status and resend if needed.

### Cannot Use Pieces After Joining Organization

If you've joined a new organization but cannot use Pieces until you configure models:

    In Pieces Desktop, navigate to *Settings* by clicking your profile picture in the top left and selecting `Settings`, or use the keyboard shortcut `⌘+,` (macOS) or `ctrl+,` (Windows/Linux).

    In the *Settings* sidebar, click on the `Models` tab or category.

    Toggle all models on, or select the specific models you want to use from the available options.

    A save reminder appears at the bottom of the page. Click `Save` to apply your model selections. After saving, you should be able to use Pieces with your organization.

### Organization Not Appearing in Dropdown

If your organization doesn't appear in the organization dropdown:

    Try refreshing your browser page to reload the organization list.

    If you belong to multiple organizations, scroll through the *dropdown* list to find the one you're looking for.

    Confirm that you're still a member of the organization. Contact the organization owner or admin if you believe you should have access.

    Use the logout/login process to refresh your session and organization list.

### Settings Not Syncing to Desktop

If organization settings aren't appearing in your Pieces Desktop installation:

    Confirm that you're a member of the organization and that settings have been configured by an Owner or Admin.

    Ensure your Pieces Desktop is connected to your account and signed in.

    Try restarting your Pieces Desktop application to allow settings to sync.

    In Pieces Desktop, check if there's an *organization settings* section that shows synced settings.

    If settings still don't sync, contact support for assistance with organization settings synchronization.

## Getting Additional Help

If you continue to experience issues after trying the solutions above, here are additional resources:

* **Account Settings Documentation** - Check the [Account Settings](/products/desktop/configuration/account) documentation for account-related issues
* **Setup Guide** - Review the [Creating and Joining Organizations](/products/organizations-and-teams/creating-and-joining-organizations) guide for setup issues
* **Support Team** - [Set up a call with our support team](https://calendar.app.google/WVUDtUfNy5Vst3sH7) to get personalized assistance
* **Organization Admin** - Reach out to your organization Owner or Admin for organization-specific issues

***

## Next Steps

If you've resolved your issue, learn about [managing organizations](/products/organizations-and-teams/managing-organizations) to explore admin features, or check out [creating and joining organizations](/products/organizations-and-teams/creating-and-joining-organizations) if you're setting up a new organization.

---

## Pieces Pro
Path: /products/paid-plans

## About Pieces Pro

Pieces Pro provides access to Pieces' current cloud-hosted AI models, Long-Term Memory, and paid product features for individuals and teams.

## Pricing

Pieces is currently offered through paid plans for individuals and organizations. Monthly and annual options may be available. Checkout is the source of truth for the plan, billing interval, price, taxes, discounts, and any trial shown for your account before you confirm a purchase.

  Prices, intervals, and any trial can vary by account. Review the order summary in the official Pieces checkout before paying.

## Benefits

Pieces Pro combines cloud-hosted AI models with Long-Term Memory and paid product features. Available models and product limits can change as Pieces evolves.

### Premium AI Models

Pieces offers three model families, each available in Fast, Balanced, and Extra Thinking modes:

* **Claude**
* **Gemini**
* **ChatGPT**

Real-time web search is powered by Perplexity. For the current model list and available modes, see [Choose a Model](/products/desktop/conversational-search/models).

## Upgrading to Pieces Pro

Use the built-in controls in Pieces Desktop or PiecesOS to activate your Pro subscription with just a few clicks.

### In Pieces Desktop

    Click the `Unlock Pieces Pro` button in the top bar, located to the right of your profile icon. This opens the upgrade modal, which highlights your new perks.

    Click `Upgrade Now`—this button changes states to `Awaiting Checkout` and launches the checkout window.

    Enter payment details and confirm to activate premium features immediately.

### In PiecesOS

    Locate the PiecesOS icon in your system menu (top bar on Mac, task area on Windows) and click the `PiecesOS icon` to open PiecesOS.

    Below the account section, there’s a new section called `Unlock Pieces Pro`.

    Click `Pro` to open the checkout window—perks are not listed here. The `Pro` button is indicated with a **lock** emoji.

    Enter payment details and confirm to activate premium features immediately.

## Navigating the Checkout

Proceed through the purchase form to enter your contact and payment information.

    Provide your email address, country, and ZIP/postal code.

      You may opt in to receive product updates and offers.

    Check the purchase overview on the right, and switch to annual billing if desired.

    Look for the small green `Add discount` text above the credit card fields. Click it to reveal the discount code input, enter your code, and apply. The totals will update to reflect the discounted price. Apply your code *before* completing payment—most codes cannot be applied retroactively.

    Click `Continue` to advance to the payment form.

    Input your card number, name on card, expiration date, and security code.

    Click `Pay Now` to finalize your subscription.

  The official Pieces checkout page is `checkout.pieces.services`.

After completing your purchase, you'll receive an email receipt along with a separate message containing your subscription details and direct links to update your payment method or cancel your subscription.

  Restart the Pieces Desktop app to force sync your account with the latest subscription status if Pro status doesn't appear.

## Billing & Account Management

Manage your Pieces Pro subscription without leaving the Pieces Desktop app.

### Update Payment Method

Change or add your credit card directly in the *Payment methods* tab.

    Click your `User Profile` in the top left, then hover over `Settings` in the dropdown menu.

    Click `Account` from the settings hover menu to view your account settings, including your subscription.

    Click the `Manage` next to your subscription entry to launch the *Billing Dashboard.*

    Click `Update payment method` to enter a new card and update which card is used for the Pieces Pro subscription.

    Provide your card number, cardholder name, expiration date, and security code.

    Click `Update payment method` to confirm and store the updated payment information to be *used on the next billing cycle*.

### Cancel your Subscription

Click `Cancel subscription` in the *Subscription* tab. You’ll be redirected to the dashboard and shown a confirmation dialog:

    Click your `User Profile` in the top left, then hover over `Settings` in the dropdown menu.

    Click `Account` from the settings hover menu to view your account settings, including your subscription.

    Click the `Manage` next to your subscription entry to launch the billing dashboard.

    Click `Cancel subscription` on the right side of your payment dashboard; this opens a confirmation dialog.

    Click `Cancel subscription` to schedule cancellation at the end of the current billing period, or click `Back` to return without canceling. Your access continues until the effective cancellation date shown in the billing dashboard.

### View Invoices

Browse your billing history in the *Payments* tab. Click `any entry` to view a completed or failed invoice.

    Click your `User Profile` in the top left, then hover over `Settings` in the dropdown menu.

    Click `Account` from the settings hover menu to view your account settings, including your subscription.

    Click the `Manage` next to your subscription entry to launch the billing dashboard.

    On the left side, click the `Payments` tab to open your invoices.

    On the *Payments* tab, you’ll see all of your active and past invoices — click on any one to access the details and edit any information within the invoice.

  You can also update your invoices by clicking on an invoice and clicking `Update invoice` — here you can add your name, company name, tax id, and more.

## Troubleshooting

### Discount Code Not Working?

* **Check for typos** — Discount codes are usually case-sensitive. Enter the code exactly as provided.
* **Verify expiration** — Some codes have an expiration date. Confirm your code is still valid.
* **Plan eligibility** — Certain codes may only apply to Pieces Pro or Pieces Enterprise. Ensure the code matches the plan you're purchasing.
* **Apply before paying** — At checkout, make sure you clicked `Apply` after entering the code. It won't auto-apply. If the discount still doesn't appear, refresh the page and re-enter the code.
* **Already subscribed?** — You can apply a discount code to an existing subscription from the Billing tab at [portal.pieces.app](https://portal.pieces.app). The discount takes effect at your next billing cycle. See [Manage Subscription](/products/paid-plans/manage-subscription#applying-a-discount-code) for details.

### Blank Upgrade Page or Checkout Error

If you're seeing a blank upgrade page with a minimal table showing $0.00 for all values, followed by an error that returns you to the previous screen, this is a known issue related to our payments pipeline.

It commonly occurs when **JavaScript is disabled in your browser** or if an **ad blocker** is interfering with the checkout process.

To get around this and continue with the payment process, make sure \[1] JavaScript is enabled in your browser settings and \[2] any ad blockers, privacy extensions, or content filtering tools are temporarily disabled.

Once you've confirmed both, try the upgrade process again.

  If the issue persists, <a target="_blank" href="https://github.com/pieces-app/support/issues">contact support</a> with details about your browser, device, and any active extensions.

## Support & Resources

### Live Support with Pieces

We aim to make your experience with PiecesOS, the Pieces Desktop App, and our MCP integrations as smooth as possible by engaging with users to improve our products, and you can book a call with our developers for assistance via <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">our support calendar.</a>

### Open a GitHub Issue<a target="_blank" href="/products/support">**​**</a>

You can open GitHub issues for PiecesOS, the Pieces Desktop App, or any other Pieces MCP integration by <a target="_blank" href="https://github.com/pieces-app/support/issues">opening an issue in our GitHub repository.</a>

If you would prefer not to use GitHub, you can still <a target="_blank" href="https://getpieces.typeform.com/to/mCjBSIjF#page=docs-support">leave feedback or report a bug here.</a>

### Join our Discord Community

We have a strong community presence on <a target="_blank" href="https://discord.com/invite/getpieces">our Discord channel,</a> so feel free to reach out to other users or members of the Pieces team.

You can also catch up on product updates, speak with our power users, or participate in weekly Community Events.

***

*Ready to supercharge your productivity? Upgrade to Pieces Pro today!*

---

## Manage Subscription
Path: /products/paid-plans/manage-subscription

## Manage Subscription

View and manage your Pieces Pro subscription from the Billing tab at <a target="_blank" href="https://portal.pieces.app">portal.pieces.app</a>. The Billing page shows your current plan, status, price, and next billing date.

### Applying a Discount Code

Apply a discount code to your active Pieces Pro subscription. The discount takes effect at your next billing cycle.

    Go to <a target="_blank" href="https://portal.pieces.app">portal.pieces.app</a>, sign in, and click `Billing` in the sidebar.

    Click the `Add Discount Code` button below your current plan details.

    In the *Add Discount Code* modal, type your discount code into the input field.

    Click `Apply Discount` to save. The discount takes effect at your next billing cycle and is reflected on your next invoice.

### Other Billing Actions

From the Billing tab you can also:

* **Change Plan** — Switch between monthly and yearly billing, or upgrade/downgrade your plan
* **Manage Billing** — Update payment methods and view billing details in the Paddle customer portal
* **Cancel Subscription** — Schedule your Pieces Pro subscription to end after the current billing period

---

## Privacy, Security & Your Data
Path: /products/privacy-security-your-data

***

## Local-First by Design
**Your data stays on your machine.** Pieces captures and stores your code, chats, and long-term memory context locally on your device—there is no continuous sync and no bulk upload to our cloud.

AI features that need a large language model (like chat) run in the cloud by default. When you use one, only a scoped, per-request slice of context is sent to the model—the rest of your data never leaves your machine. Telemetry is clearly marked, and you keep granular control over everything you share.

  Pieces is **SOC 2 Type II certified** and enterprise-ready. We never use your data to train models, and you can delete everything at any time by removing the `com.pieces.os` folder.

## Where Your Data Lives
All Pieces data is stored in a single folder on your device—easy to back up, copy, move between machines, or delete entirely.

Pieces stores data in `com.pieces.os` (PiecesOS: LTM, engine data, logs) and, on macOS and Windows, `com.pieces.pfd` (Desktop App settings and logs). You can copy these folders to OneDrive, a USB drive, or another machine without using cloud backup.

    **PiecesOS:**
    ```plaintext
    /Users/<username>/Library/com.pieces.os/
    ```

    **Desktop App:**
    ```plaintext
    /Users/<username>/Library/com.pieces.pfd/
    ```

    **PiecesOS:**
    ```plaintext
    C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\
    ```

    **Desktop App:**
    ```plaintext
    C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\
    ```

    ```plaintext
    /home/<username>/.local/share/com.pieces.os/
    ```

  Replace `<username>` with your system username. For detailed backup and migration steps, see [On-Device Storage](/products/core-dependencies/on-device-storage).

## Security Architecture
Pieces keeps your data on your device and limits what reaches the network.

Capture, indexing, and storage run on-device, your data is isolated per user, and AI features send only the context required for a single request.

* **On-device processing** — code analysis, language detection, secret detection, and tag generation run on your machine.
* **Scoped cloud requests** — when you use an AI feature, only the relevant context for that request is sent to a model.
* **Isolated user data** — each developer's data is stored in its own micro-database, preventing cross-contamination.
* **Decentralized by default** — no centralized server holds your data, so there's no single point of failure.

### What Runs On-Device vs. Cloud
Pieces captures and stores your data on-device. AI features that need a large language model run in the cloud.

| **Capability** | **On-Device** | **Cloud** |
| --- | :---: | :---: |
| Data capture & indexing | ✅ | — |
| Long-Term Memory storage | ✅ | — |
| Code analysis | ✅ | — |
| Language detection | ✅ | — |
| Secret detection | ✅ | — |
| Tag & metadata generation | ✅ | — |
| Conversational chat / LLM querying | — | ✅ |
| AI enrichment (cloud LLMs) | — | ✅ |
| Backup & restore (user-initiated) | — | ✅ |

Your memory data stays on your local disk. When you use chat or another AI feature, the request runs in the cloud and only the relevant, scoped context is sent for that request. Cloud backup and restore happen only when you start them.

## Long-Term Memory Security
The Long-Term Memory (LTM-2.7) Engine is the most context-aware part of Pieces, and your memory data stays on your local disk.

* **Local storage** — captured context is stored on your device, not in a central cloud.
* **Scoped enrichment** — when you use an AI feature, only the minimum relevant context is sent to cloud LLMs for that request; the rest of your memory stays local.
* **No bulk upload** — Pieces never continuously syncs or uploads your memory. Data leaves only as scoped, per-request context when you actively use an AI feature.

  Need tighter control over where data is processed? Bring your own keys (BYOK) through your organization—see [BYOK & Org Models](/products/organizations-and-teams/settings-models).

## Privacy Controls
You have full control over what Pieces collects, stores, and sends—no dark patterns, no mandatory telemetry.

Every Pieces product exposes settings for data sharing, cloud connectivity, and telemetry so you can match the tool to your team's policies.

* **AI processing runs in the cloud** — data is sent only as scoped, per-request context when you use an AI feature, never in bulk.
* **User-initiated actions stay in your control** — backup and restore run only when you start them.
* **Telemetry is anonymous and opt-out** — clearly marked, never tied to your code.
* **Granular settings per product** — PiecesOS, the Desktop App, and each integration expose their own privacy controls.

## Data Ownership & Model Training
Your data is never used to train any model at Pieces.

Our nanomodels are trained on synthetic datasets generated using non-user-derived *Oracle models*. This lets Pieces improve performance without inspecting, storing, or training on real user inputs or behaviors.

This applies to all product components, including Long-Term Memory, Copilot interactions, context injection, and metadata generation.

## Cloud Access & Data Transfer
When you use a cloud feature—such as LLM querying or backup and restore—Pieces sends only the minimum required, contextually relevant data.

* **Scoped to your prompt** — data sent to cloud models (for example, Claude or ChatGPT) is pre-filtered and limited to your immediate prompt. Pieces does not transmit unrelated memory or history.
* **No bulk export** — Pieces never sends full memory logs or raw content archives to any third-party service.
* **Encrypted, temporary backups** — backup and restore, when you start them, zip and encrypt your local database and transmit it for temporary storage. There is no persistent cloud sync or continuous upload.

When you enable cloud features, each user gets isolated infrastructure rather than a shared pool, which suits enterprise environments where tenancy and data segregation matter.

* **Per-user cloud instance** — your cloud environment is dedicated to your account, not shared.
* **Unique subdomain per user** — further isolates your data from other tenants.
* **Independent scaling** — performance scales with your usage without affecting other users.
* **Data isolation** — even in cloud mode, your data is segregated from every other user's.

## Compliance & Certifications
Pieces meets the standards required by enterprise security teams, with regular audits and enterprise-grade authentication.

    Our systems meet the stringent requirements of SOC 2 Type II—a critical benchmark for security, availability, and confidentiality in enterprise environments.

    We audit our infrastructure frequently to identify potential vulnerabilities and continuously improve our systems beyond the baseline that certifications require.

    Access is protected through Auth0, with support for multi-factor authentication and the advanced sign-in options enterprise teams expect.

## Privacy Policy & Questions
Our full privacy policy covers the details not addressed here. Reach out if you have specific concerns or need documentation for a security review.

* Read our <a target="_blank" href="https://pieces.app/legal/privacy-policy">Privacy Policy</a>
* <a target="_blank" href="https://calendar.app.google/WVUDtUfNy5Vst3sH7">Book a call</a> with our team
* Open a <a target="_blank" href="https://github.com/pieces-app/support/issues">GitHub issue</a> or join our <a target="_blank" href="https://pieces.app/discord">Discord</a>

***

## Next Steps
Dig deeper into how Pieces stores your data and what runs locally.

[On-Device Storage →](/products/core-dependencies/on-device-storage)

[Support →](/support)

---

## Using Conversational Search with Context
Path: /products/quick-guides/copilot-with-context

## Prerequisites

To complete this Quick Guide, you’ll need:

1. **The Pieces Desktop App** installed and actively running on your device.

2. **Long-Term Memory** enabled in the Pieces Desktop App.

3. **Optional**—Pieces connected in a Python IDE via MCP, such as [Visual Studio Code](/products/mcp/vs-code) or [JetBrains IDEs](/products/mcp/jetbrains-ides) (including PyCharm).

## In This Quick Guide

This Quick Guide shows how to combine **Long-Term Memory** with **Conversational Search**—including scoping a chat to a specific captured memory using **`Chat`** on a Timeline summary—so you can get AI help implementing a feature in a Python app.

As a developer, a common daily task is reviewing a ticket in a tool like GitHub Issues or Jira and then implementing it in a codebase.

This often involves switching back and forth between the code and the ticket, which can affect your productivity due to constant context switching.

With Pieces, Long-Term Memory captures the ticket as you read it. After you work in your project, Pieces can use those **captured memories**—and you can open **Conversational Search** scoped to the right **summary** from Timeline using the **`Chat`** action on the three-dots menu.

### Review a GitHub Issue

The first step is to review the issue by letting Pieces capture it, and then ask Conversational Search about it.

    Open the following GitHub issue in your browser. Slowly scroll through the comments on the issue, taking maybe 30 seconds or so to scroll through it.\
    \
    You can <a target="_blank" href="https://github.com/pieces-app/pieces-certification-course-content/issues/1">use this issue</a> as an example.

    In Conversational Search, start a new chat, ensuring the Long-Term Memory (LTM) context is enabled, and use the following prompt:

    ```plaintext
    Summarize the create a sign up page issue I was just reading
    ```

Pieces will respond with a summary of the issue:

### Clone the Project

This issue refers to a sci-fi store—a small web application written in Python and Flask for an upcoming retail store that sells themed sci-fi toys.

    <a target="_blank" href="https://github.com/pieces-app/pieces-certification-course-content">Clone this GitHub repository.</a>

    Inside the repo is a folder called `scifi_store`.

    If you use an IDE like VS Code or JetBrains PyCharm, open this folder in that IDE.

### Tie the project to Conversational Search (Timeline Chat)

You **cannot** attach a project folder or individual files directly to Conversational Search. Instead, **LTM** must **capture** your work in `scifi_store`, then you **scope** a chat to the summary or event that holds that context.

    With **Long-Term Memory** enabled, spend a few minutes in your IDE inside `scifi_store`—open files, scroll relevant modules, or run the app—so Pieces records useful workflow context.

    In the Pieces Desktop App, open [Pieces Timeline](/products/desktop/timeline). Look for a recent **roll-up** or **summary** that reflects that coding session (for example activity involving your editor and that repo).

    Open that item in the main panel. Click the **three-dots menu** (⋮) on the event header and select **`Chat`**. Conversational Search opens with that memory in scope.

    For more detail, see [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary).

### Prompt Conversational Search

With the GitHub issue in LTM and a **scoped** chat tied to a summary that includes your project activity, you can ask Pieces how to implement the issue.

    In the same Conversational Search chat, use this prompt (or one like it):

    ```plaintext
    How can I implement this issue in this project?
    ```

    The Conversational Search will use **Long-Term Memory**—including the issue you read and the workflow captured from `scifi_store` inside the scoped summary—to propose implementation steps.

    The response may include concrete suggestions such as code for an endpoint, a new page using existing templates, and so on.

    Review these code changes along with the original codebase.

  🎉 Congratulations, you’ve completed the *Using Conversational Search with Context* Quick Guide! 🎉

## Bonus—Try One Prompt

This Quick Guide showed two prompts: one to get the details about the issue and another to learn how to implement it.

This was done in 2 stages to illustrate the information from the Pieces Long-Term Memory, but is *unnecessary*. You can do this in a single prompt!

    Start from home or your IDE, or open **`Chat`** from a Timeline summary that already contains both the issue and recent work in `scifi_store`.

    If you need one focused memory in scope, use **`Chat`** on the relevant summary’s three-dots menu—see [Chat from a summary](/products/desktop/timeline/event-actions#chat-from-a-summary).

    Use this single prompt when interacting with Conversational Search;

    ```plaintext
    How can I implement the create a sign up page issue I was just reading in this Python project?
    ```

    The assistant uses your **Long-Term Memory** (issue + captured IDE activity) to suggest how to implement the ticket—especially if you used **Chat** on a summary that already bundles that context.

---

## Using Long-Term Memory Context
Path: /products/quick-guides/ltm-context

## Prerequisites

To complete this Quick Guide, you’ll need:

1. **The Pieces Desktop App** installed and actively running on your device.

2. **Long-Term Memory** enabled in the Pieces Desktop App.

To enable the LTM-2.7 Engine from PiecesOS, click the PiecesOS icon to open the [Quick Menu](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine) on Windows or macOS, then select `Enable Long-Term Memory Engine`.

## In This Quick Guide

In this Quick Guide, you’ll use [Pieces Long-Term Memory](/products/core-dependencies/pieces-os#ltm-27) to save context from a website, then prompt Conversational Search to tell you what it saw.

  Here’s a <a target="_blank" href="https://tsavo.hashnode.dev/temporal-nano-model-breakthrough">quick read on some of the nano-models</a> we develop that layer into the data retrieval pipeline for LTM-2.7 and the coming *LTM-2.7*

This demonstrates how Pieces can capture information from any application and make it available to you in Conversational Search.

### Capture Context

With LTM enabled, Pieces captures workflow context from every actively used window, including the browser you’re using to read this Quick Guide.

    <a target="_blank" href="https://pieces.app/magic-moments/ltm">Click this link</a> to generate a message Pieces can capture in a new tab.

    Read the message and give Pieces a second or two to capture the context from your browser.

### Prompt the Copilot

Now that Pieces has captured the message, you can prompt Conversational Search through the Pieces Desktop App to retrieve the secret message.

    Open the Pieces Desktop App and start a new chat or use an existing chat.

    Use the following prompt with Conversational Search:

    ```plaintext
    What is my secret message?
    ```

---

## Long-Term Memory Prompting Guide
Path: /products/quick-guides/ltm-prompting

## Why This Matters

With Pieces Long-Term Memory, you can query across captured memories using natural language—like asking a colleague who was there with you. The key to great results is combining a few dimensions in your questions: when, where, what, and who.

These guides show how to query LTM context using Conversational Search in the Pieces Desktop App or any app with a Pieces plugin or extension.

  For any chat, you must activate the **LTM Context** (or Long-Term Memory Context) button in the chat interface. Without it, Conversational Search cannot search your Long-Term Memory—even with a well-structured query.

You also need [LTM-2.7 enabled](/products/core-dependencies/pieces-os/quick-menu#ltm-2-engine) in PiecesOS.

## The Five Keys to Great LTM Queries

Combine these elements in your questions for better results. You don't need all five—even one or two helps significantly.

| **Dimension** | **What to include** | **Example** |
|---------------|---------------------|-------------|
| **Time** | When did it happen? | "yesterday," "last week," "this morning" |
| **Source** | Where did it happen? (which app) | "in VS Code," "from Chrome," "in Teams" |
| **Gesture** | What were you doing? | "copying," "searching," "editing" |
| **Topic** | What project or subject? | "authentication module," "API integration" |
| **People** | Who were you working with? | "Sarah," "the security team" |

**Pro tip:** Be specific when you can. "What did I work on for the customer portal yesterday?" works better than "What was I doing?"

### Modality Filtering

You can narrow results by the type of activity:

| **Scope** | **Use when you want** | **Example phrases** |
|-----------|------------------------|----------------------|
| All sources | General summaries, themes | "everything I did," "my work today" |
| Communications | Emails, chats, meetings | "in my conversations," "in meetings" |
| Code/Technical | Terminal, IDE, code | "commands I ran," "in VS Code" |
| Capture | Clipboard, screenshots | "things I copied," "snippets I saved" |

### Query Best Practices

**Do:**
* Write naturally—ask like you'd ask a colleague
* Be specific about time when it matters ("last Tuesday" > "recently")
* Combine dimensions (time + topic + people works well)
* Mention the project or theme when you remember it

**Don't:**
* Overthink it—start simple and add details if needed
* Be too vague ("show me stuff" won't help)
* Give up after one try—small tweaks often improve results

## Guide Links

Click one of the cards below to jump to that guide.

    Examples of the typical use cases we see for Pieces LTM with the kinds of prompts users ask.

    A selection of popular use cases for the new Pieces Workstream Activity view.

---

## Use Cases and Example Prompts
Path: /products/quick-guides/ltm-prompting/examples

## In This Guide

There are many ways to use and prompt the LTM to find specific information, recall past fixes and solutions, refresh your memory from conversations and shared resources, and much more.

In this guide, you’ll find some carefully selected use cases and examples that our users commonly rely on—but this is just the beginning.

## Summarize & Extract Information

If you're reading a document in your browser, a PDF viewer, or a collaboration tool like Teams, Pieces is reading along with you. This means you can use Pieces to summarize or extract information from those documents.

Try using these prompts to recall information captured by LTM while you were reading text in a browser or application related to your workflow.

    “Summarize the Project Falcon report I was reading last week.”

    “I was reading a Red Team huddle report yesterday. What were the items on the agenda and who were they assigned to?”

    “Last month I was looking at documentation on the Endor API. What is the API endpoint to open the bunker?”

## Get Deep Link URLs

When Pieces captures context from your browser, it saves the URL you were visiting.

It also captures links from other content where the URL is present in the text, so you can search for URLs, such as finding tabs you no longer have open or retrieving links mentioned in chats or emails.

  Note that Pieces is not a search engine—it captures *memories* from your activities. It will return the URLs you viewed, interacted with, or were shared with you, but it doesn't perform web searches.

Use similar prompts that include a little context, so LTM knows what information to surface and return to Conversational Search.

    “Give me the URL of the Yavin JavaScript framework I was reading about this morning.”

    “What is the URL for the Power Converter documentation I was reading last week?”

    “I need the URL that Leia shared with me with the GCP Firestore database containing the plans.”

## Research an Error in Code

When you encounter an error in your code, whether it's in your terminal, a popup in your IDE, or an error in your browser, Pieces captures it.

* If it's an error you've seen *before*, you can ask about it to recall what you did to fix it.

* If it's a *new* error, you can use Long-Term Memory along with file or folder context to help find a solution in your codebase.

One of the most powerful applications of LTM context and Conversational Search is to facilitate intelligent debugging regarding your recent or active development workflow.

    “What was the error I just saw in VS Code? Summarize some of the reasons I may have got this error and give me suggestions to resolve it.”

    “I just had an error log in my browser. What was the error and what file did it reference?”

    “How can I fix the error I just got in Warp in this project? *(Using the project as a folder of context)”*

## Summarize Recent Work

Knowledge workers often have to provide status updates, such as reports on the work they have been doing or the status of a project.

For example, developers often attend a daily standup where they list the tasks they worked on the previous day and the tasks they plan to work on today.

With access to all your activities, Pieces can help automate this process.

  Pieces prioritizes activities based on how often workstream activities are captured. This means that documents or applications you spend more time on will be given higher priority in the response.

If Pieces has access to calendar apps, the column or grid format might not be easily understood by AI, which can lead to confusing responses. You might get better results by adding your calendar apps to the list of disabled sources.

Use some of these time-based example prompts to ask Conversational Search to provide accurate, relevant answers summarizing recent activities.

    “What was I working on yesterday?”

    “Give me a list of all the GitHub issues I was looking at yesterday in the Mustafar project.”

    “Summarize all the documents I was editing yesterday in Chrome and give me back a list of 5 bullet points that lists my main activities.”

### More Examples by Time Horizon

**Daily / 24–48 hours:** "Generate my standup for today: what I accomplished in the past 24 hours, what I'm working on, and any blockers." | "What follow-ups came up in my emails and meetings over the past 48 hours?"

**Weeks to months:** "Find the conversation I had with my team a few weeks ago about [topic] and summarize what we decided." | "Based on my work over the past quarter, give me a performance review."

## Get Next Steps

Pieces can detect any upcoming activities, such as tasks in a task management tool, emails in your inbox, or discussions around future work in chat tools.

You can then ask Pieces to summarize these to give you details on what your next priorities are.

    “What is next on my agenda?”

    “What are the tasks Luke asked me to look at?”

    “What tasks are still open in my to-do app?”

## Get Project History

As you work on multiple activities for a project, Pieces is able to piece together memories by capturing relevant context from multiple applications.

This allows you to prompt asking for information about a project and get a response that reasons over all these memories.

    “Summarize the carbonite freezing project and give me links to relevant documents.”

    “Who are the main contributors to project R2, and what are their email addresses?”

    “Give me an overview of the work done so far on D2, and what are the next steps?”

## Get a Summary of Project Status

If you are in a role where you are often receiving project updates and summaries, it can be hard to stay on top of them all.

Pieces can read these updates with you, and provide summaries or roll-ups as needed.

    “Give me a summary of all the status updates I received last week from Han, Cassian, and Shin.”

    “Write me a summary report on the status of the Phasma testing.”

    “Send me a list of all the Jira tickets mentioned in the Geonosis status updates channel in Teams.”

## Summarize Any Text Resource

Sometimes we come across different sources of information that might conflict or vary in detail. This could include anything from news articles to recommendations for code frameworks, cars, and more.

To help make sense of this and get a clearer understanding, Pieces can read all the sources with you, allowing you to think through these memories.

    “Summarize the 3 articles I was just reading about the recent stock market trends around AI.

    “I was just reading documentation on the best JavaScript framework to use. Provide me a detailed summary containing a list of all the frameworks, their pros and cons, and the maturity of each framework.”

    “Based on the reviews of different SUVs I was just looking at in Edge, which one would be the best for a family of 3? I care most about the lowest environmental impact, and the best crash safety.”

---

## Use Cases for the Pieces Workstream Activity View
Path: /products/quick-guides/ltm-prompting/workstream-activity

The [Pieces Workstream Activity view](/products/quick-guides/ltm-prompting/workstream-activity) provides summaries of all activities captured in 20 minute blocks, called *LTM Roll-Ups.*

You can use these to find memories that you can then query, or to even track new memories that you can share with colleagues to provide relevant context to them.

Workstream Activities can be filtered by keyword to help you find activities related to a project, concept, bug in your code, and more. Once filtered, you can use these results as context for your chats.

## In This Guide

Discover real-life use cases for the Workstream Activity view, and use it capture and filter entire project contexts, generate process documentation, and create detailed standup summaries using LTM roll-ups.

Practical examples demonstrate how to turn these activity ‘snapshots’ into shareable references, from markdown exports to live discussions in Conversational Search chats, or search through them with various filters.

  Workstream Activities can be exported as markdown or raw text, then sent to another Pieces user, who can then add these as context to their own Conversational Search chat.

## Share All Context for a Project

If your project has a unique name, or other identifier that is easy to query for, then you can filter all Workstream Activities for that keyword—this will then give a historical overview of your activities with that project.

Once you have this, you can either open it all in a Conversational Search chat and have the LLM create a detailed summary report to share with someone else, or you can export and share the activities directly, either as markdown files, or as raw text.

## Create a Summary To Document a Process

When some folks are documenting a process, they often create a video which is shared with colleagues.

The problem with this approach is that it misses important context, such as links or text from documentation, which must be shared separately and is difficult for the recipient to search.

By using Pieces, you can go through a process by checking documents, chats, emails, and code—then, you can create a new Workstream Activity for the time you spent.

This summary can be shared with your colleagues and will include text details like links to the documents you read, information about people involved in the conversations, links to code, and more.

## Turn Summaries into PRs and Reports

Pieces can help you create a summary of completed work based on details like tickets. For instance, if you're a developer and need to participate in an asynchronous daily standup, you can use Pieces to create a summary of tickets resolved—deep-links included.

You can do this by going through your ticket system and reviewing all the tickets you worked on the previous day.

Then, create a new Workstream Activity for the time you spent reviewing, which will include deep links to the tickets. You can use this raw content for your daily standup or ask Conversational Search to summarize it in a more suitable format.

---

## Introduction to Pieces Quick Guides
Path: /products/quick-guides/overview

***

## Why Use Quick Guides?

Pieces Quick Guides help you quickly understand and use powerful features like the Long-Term (LTM-2.7) Memory Engine and Conversational Search.

Capture context from your browser, summarize meetings with coworkers, find closed GitHub Issues from last month that were just mentioned in that Slack channel—*and that’s just the beginning.*

You can get a lot done with Pieces, and we want to help you get started!

Visit the links below to read Pieces Quick Guides on various topics, such as using LTM context, adding folders as additional context from different platforms, prompting, and more.

***

    Capture and recall information from webpages with LTM to quickly retrieve important details.

    Reduce context switching and use Conversational Search to turn issues and tasks from your IDE or browser into actionable strategies.

    Unlock the potential of advanced prompting and access context from past activities through search filters for better results.

    Browse typical user scenarios showcasing the versatility of LTM + Conversational Search in real-time.

***

## Ready to Explore?

Jump into any guide above by clicking its card and transform your daily workflow with Pieces! 🌟

## Additional Resources

If you're looking for more specific information, you can read comprehensive Pieces documentation on the [Pieces Desktop App](/products/desktop), the [Core Dependency—PiecesOS](/products/core-dependencies/pieces-os)—or choose how to connect Pieces in the [Integrations overview](/products/integrations-overview) and [MCP setup guides](/products/mcp).

If you need help with a bug, [visit our Support page](/products/support) for links to our GitHub, links to our social media outlets, and for contacting our engineers.

---

## Support
Path: /products/support

***

## Getting Help
The fastest way to get a response depends on what you need—pick the option that matches your situation.

We read every report, reply to GitHub issues directly, and our founders regularly hop on calls with users to make sure Pieces fits your workflow.

    Talk directly with our Founders & Engineering Leaders—great for onboarding help, workflow feedback, or walking through an issue together.

    Report bugs, request features, or track known issues for PiecesOS, the Desktop App, and any MCP integration.

    Chat with the team and other power users, catch release notes, and join weekly community events.

    Prefer not to use GitHub? Drop us a note—bug reports and feature requests both welcome.

  If you're reporting a bug, please include your logs. See [Finding Your Logs](#finding-your-logs) below—attaching them to your GitHub issue helps us reproduce and fix the problem much faster.

## Finding Your Logs

PiecesOS and the Desktop App store logs in separate folders on some platforms. Zip the latest two or three log files before attaching them to a GitHub issue or sending them to support.

For database paths, manual backups, and cloud restore, see [On-Device Storage](/products/core-dependencies/on-device-storage).

    ### macOS
    Open Finder, press `⌘+shift+g`, and paste the path below:

    ```plaintext
    ~/Library/com.pieces.os/production/Support/logs/
    ```

      If the `Library` folder is hidden, press `⌘+shift+.` (period) in Finder to toggle hidden files.

    > Locating Pieces log files on macOS

    ### Windows
    Press `Win+R` to open the Run dialog, then paste:

    **PiecesOS:**
    ```powershell
    C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Support
    ```

    **Desktop App:**
    ```powershell
    C:\Users\<username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces for Developers\com.pieces.pfd\production\logs
    ```

      Replace `<username>` with your system username. If `AppData` is hidden, enable `View → Show → Hidden items` in File Explorer.

    > Locating Pieces log files on Windows

    ### Linux
    Open your file manager or a terminal and navigate to:

    ```bash
    ~/.local/share/com.pieces.os/
    ```

      In most file managers, press `ctrl+h` to toggle hidden files so you can see the `.local` directory.

    > Locating Pieces log files on Linux

## Joining the Community
If you're looking for longer-form conversations, feature brainstorms, or answers from other developers, our community spaces are the right place.

We use these channels to inform the roadmap—feature requests and discussions here genuinely shape what we build next.

* **<a target="_blank" href="https://discord.com/invite/getpieces">Discord</a>** — live chat, release announcements, and weekly community events.
* **<a target="_blank" href="https://github.com/pieces-app/support/discussions">GitHub Discussions</a>** — longer-form threads, Q&A, and roadmap input.

***

## Next Steps
Not finding what you need in the docs? Browse common setup and account questions, or jump back to the product overview.

[Troubleshooting PiecesOS →](/products/core-dependencies/pieces-os/troubleshooting)

[Privacy, Security & Your Data →](/privacy-security-your-data)

---