Use when working with Pieces — the on-device AI memory and productivity platform for developers. Covers: PiecesOS setup and architecture, Long-Term Memory (LTM) queries, MCP integration with Claude/Cursor/GitHub Copilot/VS Code/Zed/JetBrains and 15+ other clients, CLI usage (save/search snippets), Desktop App (Timeline, summaries, Copilot), IDE plugins (VS Code, JetBrains), and the Obsidian plugin. Trigger on: "pieces", "PiecesOS", "LTM", "Pieces MCP", "pieces copilot", "pieces drive", "pieces obsidian", "pieces timeline", or any task involving Pieces integrations.
Pieces is built on three interconnected pillars:
Privacy: Fully on-device by default. Air-gapped from cloud. Cloud LLMs are opt-in.
The required background service (like a Docker daemon) that everything depends on.
localhost:39300–39399GET http://localhost:39300/.well-known/health → returns a UUIDaccess-control-allow-origin: */.well-known/health, /user, /applicationsPiecesOS must be running before CLI, MCP, IDE plugins, or Obsidian plugin will work.
Settings available in Desktop App: Account, LTM, Models, Copilot Chats, Machine Learning, MCP, Connected Applications, Views & Layouts, Appearance, Troubleshooting.
The central hub for the Pieces suite.
Timeline
One-Click Summaries — preset types:
What's Top of Mind — current focus areasStandup Update — yesterday/today/blockersDay Recap — end-of-day overviewCustom Summary — user-defined promptAI Habits — patterns in your workflowConversational Search — chat interface for querying LTM. Suggested prompts appear on load. Examples: "What was the link to that doc I worked on last week?" / "What did I decide about auth?"
AI assistant available across all Pieces surfaces.
Use local models for privacy/speed; cloud models for more capability. Switch per conversation.
Install: pip install pieces-cli or conda install pieces-cli
pieces run # Interactive loop mode (omit 'pieces' prefix for all commands inside)
pieces list # List all Pieces Drive materials (alias: drive)
pieces list models # Show available AI models
pieces create # Save clipboard content as a snippet
pieces search "query" # Fuzzy search
pieces search "query" --mode ncs # Neural code search
pieces search "query" --mode fts # Full text search
pieces edit # Rename/reclassify a snippet
pieces delete # Remove a snippet
pieces ask "question" # Ask Pieces Copilot
pieces chats # List past conversations
pieces commit # Auto-generate git commit message (--push to push)
pieces share # Generate shareable snippet URL
pieces mcp setup # Configure Pieces MCP for a platform (interactive)
pieces version # Show PiecesOS + CLI versions
pieces help # List all commands
Attach context to ask:
-m 1 2 — attach saved materials by index
-f ./path — attach file or folder
Navigate search results with arrow keys; Enter to view snippet with full metadata
Inside pieces run, omit the pieces prefix: just create, search "query", etc.
Connects PiecesOS context into AI clients via the ask_pieces_ltm tool.
Requirement: PiecesOS running + Long-Term Memory enabled.
ask_pieces_ltm — the core MCP tool. Queries your captured LTM history. Use it to:
Claude Code (fastest setup):
pieces mcp setup # interactive — select "Claude Code"
# or manually:
claude mcp add --transport http pieces http://localhost:39300/model_context_protocol/2025-03-26/mcp
Stdio-only clients (Claude Desktop, Zed): Use mcp-remote — see references/mcp-remote.md.
Remote access: Tailscale (point at 100.x.x.x:39300) or ngrok (expose port 39300).
See references/mcp-platforms.md for all platform configs. See scripts/add-pieces-mcp.sh to automate Claude Code setup.
Minimum version: 2023.1. Install from JetBrains Plugin Marketplace.
Right-click menu actions:
| Action | What it does |
|---|---|
Save Current Selection/File to Pieces | Save with AI-enriched metadata |
Ask Copilot About Selection | Get suggestions or explanations |
Modify Selection with Copilot | Refine selected code with AI |
Comment Selection with Copilot | Auto-generate inline docs |
Explain Selection with Copilot | LLM-powered explanation |
Share via Pieces Link | Generate a shareable link |
Search Pieces Drive | Find saved snippets |
Inline Quick Actions: Pieces: Explain and Pieces: Comment appear above functions automatically.
Search shortcut: Double-tap Shift → Pieces search window.
One-click MCP install available. Copilot and Drive features mirror JetBrains.
Install from the Obsidian plugin marketplace.
Save a snippet from clipboard:
pieces create
Query past work context (via MCP in any connected AI client):
ask_pieces_ltm: "What auth approach did I use last week?"
Search for a saved snippet:
pieces search "jwt middleware" --mode ncs
Check if PiecesOS is alive:
curl http://localhost:39300/.well-known/health
Generate a standup update: Desktop App → Timeline → select yesterday's range → "Standup Update"