# Pieces Long-Term Memory MCP Skill.md ```markdown --- name: pieces-mcp description: > Connect OpenClaw to Pieces via MCP-only (no SSE) and use Pieces as external long-term memory. Use this when the human runs PiecesOS with LTM enabled on another machine and exposes the MCP server via a tunnel (ngrok, custom domain, or any HTTPS proxy). This skill tells the agent exactly how to prompt the human, configure MCPorter and mcp-remote, use Pieces tools (ask_pieces_ltm, create_pieces_memory, *_full_text_search), and troubleshoot common failures. --- # Pieces MCP Skill for OpenClaw (MCP-Only, No SSE) This skill teaches you, the OpenClaw agent, how to: 1. Know **when** to use Pieces. 2. Guide the human through tunnel setup (ngrok or custom). 3. Wire OpenClaw to the Pieces MCP server using **only `/mcp`**. 4. Use Pieces tools (`ask_pieces_ltm`, `create_pieces_memory`, `*_full_text_search`) in your reasoning. 5. Troubleshoot when something goes wrong. --- ## 0. When to Use This Skill Trigger this skill when: - The human mentions **Pieces**, **PiecesOS**, **MCP**, "ask Pieces", or "long-term memory" in the context of OpenClaw. - They say things like: - "I want OpenClaw to remember what I worked on." - "Hook OpenClaw up to my Pieces long-term memory." - You see or expect a URL like: - `https://...ngrok-free.dev` - `https://username.tunnel.company.stream` - Any HTTPS URL they say is "the Pieces MCP tunnel". If none of that is true, you probably don't need this skill. --- ## 1. Mental Model Think of three components: - **PiecesOS MCP server (remote machine)** - Runs on the human's other machine. - Long-Term Memory (LTM) is enabled. - Exposed via an HTTPS tunnel: `/model_context_protocol/2025-03-26/mcp`. - **OpenClaw host (this machine)** - This is where you (the agent) live. - Uses **MCPorter** to integrate MCP servers. - **Bridge: MCPorter + `mcp-remote`** - `mcporter.json` tells MCPorter about MCP servers. - `mcp-remote` connects to the remote `/mcp` endpoint and exposes it to OpenClaw. > **Important:** This integration is MCP-only. Do **not** use `/sse`. > Always use `/mcp` for both direct calls and the bridge. --- ## 2. Human Checklist (What You Must Confirm) You must guide/confirm these three things: 1. **PiecesOS + LTM is running** on the remote machine. Say something like: > "Make sure PiecesOS is installed and running on your other machine, and that > Long-Term Memory (LTM) is enabled in the Pieces Desktop App." 2. **A tunnel is available** to expose the MCP server. Options include: - **ngrok** (most common): `ngrok http 39300` - **Custom tunnel** (e.g., `username.tunnel.company.stream`) - Any HTTPS proxy that forwards to `localhost:39300` 3. **For ngrok specifically, tell them:** > "On the machine running PiecesOS, please run this in a terminal: > > ```bash > ngrok http 39300 > ``` > > If ngrok asks for login or an authtoken, follow its instructions once. > When it's running, you'll see a forwarding URL like: > > `https://SOMETHING.ngrok-free.dev -> http://localhost:39300` > > Please paste that HTTPS URL here." You cannot proceed until the human pastes a valid HTTPS tunnel URL. --- ## 3. Build and Verify the MCP URL Once you have the base tunnel URL, construct the MCP endpoint. If the human gave you: ```text https://SOMETHING.ngrok-free.dev ``` Or a custom tunnel like: ```text https://name.tunnel.company.stream ``` Define: ``` MCP_URL_BASE = MCP_URL_MCP = /model_context_protocol/2025-03-26/mcp ``` ### 3.1 Quick Sanity Check (Before Initialize) **Always run this GET request first** to confirm the route is alive: ```bash curl -i "MCP_URL_MCP" ``` **Expected success response (HTTP 400):** ```json { "jsonrpc": "2.0", "error": { "code": -32000, "message": "Bad Request: mcp-session-id header or sessionId query parameter is required" }, "id": null } ``` This 400 error is **good** — it means: - ✅ The route exists - ✅ The MCP server is running - ✅ It's ready to accept properly-formed requests **If you get 404, 502, HTML, or timeout** → See Section 9.1: Troubleshooting. ### 3.2 Understanding MCP Request Patterns (Critical!) Before configuring MCPorter, you need to understand how MCP requests work. This section shows the exact request patterns so you don't get confused. #### The Session Management Pattern All MCP interactions follow this flow: 1. **Initialize** → Server assigns you a session-id 2. **Use that session-id** for all subsequent requests 3. **Never reuse your custom session-id** — always use the server-assigned one #### Session ID Format > **What to look for:** The server-assigned session-id is typically a **Unix > timestamp in milliseconds** — a 13-digit numeric string like `1774202062499`. > > Pattern: `17XXXXXXXXXXX` (13 digits starting with `17` in 2025-2026) > > You'll find it in the **response headers**, not the response body: > ``` > mcp-session-id: 1774202062499 > ``` #### Required Headers for ALL Requests ``` Content-Type: application/json Accept: application/json, text/event-stream mcp-session-id: ``` **Missing either `Content-Type` or `Accept` will cause failures!** #### Critical: Use File-Based JSON for curl > **⚠️ Shell quoting can mangle JSON!** Zsh and Bash handle quotes differently, > and inline JSON with `-d '{...}'` is fragile. **Always use file-based JSON > with `--data-binary @filename`** to avoid parsing errors. #### Critical: Use String JSON-RPC IDs > **⚠️ Use `"id": "1"` (string), not `"id": 1` (integer).** > The server is sensitive to id types, and string ids work consistently. --- #### Step 1: Initialize Session Create a file `init.json`: ```json { "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "0.1.0", "capabilities": {}, "clientInfo": { "name": "openclaw-agent", "version": "1.0" } }, "id": "1" } ``` Run: ```bash curl -i -X POST "MCP_URL_MCP" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: init-request-001" \ --data-binary @init.json ``` **What happens:** - You send `mcp-session-id: init-request-001` (can be any string you choose) - Server responds with a **new session-id in the response header** **Look for this in the response headers:** ``` HTTP/2 200 content-type: application/json mcp-session-id: 1774202062499 ... ``` > **Critical:** Extract the `mcp-session-id` value from the **response header** > (e.g., `1774202062499`). This is your server-assigned session ID. Use this > exact value for all subsequent requests — do NOT continue using your initial > `init-request-001`. **Response body (200 OK):** ```json { "jsonrpc": "2.0", "id": "1", "result": { "protocolVersion": "0.1.0", "capabilities": { "tools": {} }, "serverInfo": { "name": "pieces", "version": "1.0.0" } } } ``` --- #### Step 2: Query Long-Term Memory Now use the **server-assigned session-id** for all future requests. Create a file `query.json`: ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "ask_pieces_ltm", "arguments": { "question": "What did I work on today?", "chat_llm": "gpt-4" } }, "id": "2" } ``` Run (replacing `` with the value from Step 1): ```bash curl -i -X POST "MCP_URL_MCP" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: " \ --data-binary @query.json ``` **Example with actual session ID:** ```bash curl -i -X POST "MCP_URL_MCP" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: 1774202062499" \ --data-binary @query.json ``` **Response (200 OK):** ```json { "jsonrpc": "2.0", "id": "2", "result": { "content": [ { "type": "text", "text": "{\"summaries\":[...],\"events\":[...]}" } ] } } ``` **Important for OpenClaw Agents:** The response looks like "raw JSON garbage" to humans, but this is **perfect for you!** You get: - `summaries[]` — Pre-existing memory summaries with relevance scores - `events[]` — Raw activity events (browser, clipboard, audio, etc.) Parse this JSON yourself and synthesize a natural language answer for the human. --- #### Step 3: Create a Memory Create a file `create_memory.json`: ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "create_pieces_memory", "arguments": { "summary_description": "OpenClaw + Pieces: First Integration Session", "summary": "# OpenClaw + Pieces Integration\n\nThis memory documents our initial setup session.\n\n## What We Did\n- Verified Pieces MCP server via tunnel\n- Configured MCPorter with mcp-remote\n- Successfully tested ask_pieces_ltm\n\n## Key Learnings\n- Session management is critical\n- Use file-based JSON to avoid shell quoting issues\n- Use string JSON-RPC ids for consistency", "project": "OpenClaw + Pieces" } }, "id": "3" } ``` Run (using the same server-assigned session ID): ```bash curl -i -X POST "MCP_URL_MCP" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: " \ --data-binary @create_memory.json ``` **Response (200 OK):** ```json { "jsonrpc": "2.0", "id": "3", "result": { "content": [ { "type": "text", "text": "Memory created successfully" } ] } } ``` --- #### Session ID Quick Reference | Stage | Header Value | Source | |-------|--------------|--------| | **Initialize request** | Any string you choose (e.g., `init-001`, `my-session`, `test-123`) | You create it | | **Initialize response** | 13-digit timestamp (e.g., `1774202062499`) | **Extract from response header** | | **All subsequent requests** | The server-assigned value from initialize | Reuse the extracted value | #### Common Mistakes That Will Break Things | ❌ Wrong | ✅ Correct | |----------|-----------| | Inline JSON with `-d '{...}'` | File-based JSON with `--data-binary @file.json` | | Integer id: `"id": 1` | String id: `"id": "1"` | | Missing `Accept` header | Include `Accept: application/json, text/event-stream` | | Using your initial session-id (`init-001`) for all requests | Extract server-assigned session-id from initialize **response header** | | Looking for session-id in response body | Session-id is in the **response headers** | | Thinking raw JSON responses are errors | Parse the JSON — it's structured data for you to synthesize! | | Calling tools before initialize | Always call initialize first to get a session-id | | Forgetting `chat_llm` parameter | Include it (even though responses may still be raw JSON) | --- ## 4. Configure MCPorter (MCP-Only) OpenClaw uses MCPorter to manage MCP servers. The config lives at: ``` ~/.openclaw/workspace/config/mcporter.json ``` As the agent, you should: ### 4.1 Ensure the config directory exists ```bash mkdir -p ~/.openclaw/workspace/config ``` ### 4.2 Create or update mcporter.json You want a `pieces` entry that uses `mcp-remote` pointed at `MCP_URL_MCP`: ```json { "mcpServers": { "pieces": { "command": "mcp-remote", "args": [ "MCP_URL_MCP_GOES_HERE" ] } } } ``` **Example with ngrok:** ```json { "mcpServers": { "pieces": { "command": "mcp-remote", "args": [ "https://SOMETHING.ngrok-free.dev/model_context_protocol/2025-03-26/mcp" ] } } } ``` **Example with custom tunnel:** ```json { "mcpServers": { "pieces": { "command": "mcp-remote", "args": [ "https://username.tunnel.company.stream/model_context_protocol/2025-03-26/mcp" ] } } } ``` No `/sse` here. This is the MCP-only configuration. > **Note:** `mcp-remote` handles the session management (initialize, session-id > extraction, header management) automatically. You don't need to manually manage > sessions when using MCPorter — the examples in Section 3.2 are for understanding > the protocol and direct testing/troubleshooting. ### 4.3 Ensure mcp-remote is installed Install `mcp-remote` globally: ```bash npm install -g mcp-remote@0.1.38 ``` You can run this yourself from the OpenClaw host's shell. --- ## 5. Restart the OpenClaw Gateway After editing `mcporter.json`, restart the OpenClaw gateway so it picks up the Pieces MCP server: ```bash cd ~/.openclaw/workspace openclaw gateway restart ``` Wait a few seconds for it to restart. At this point, OpenClaw should see the Pieces MCP server through MCPorter and `mcp-remote` → `MCP_URL_MCP`. --- ## 6. How and When to Use Pieces Once connected, treat Pieces as your authoritative long-term memory. ### 6.1 When to query Pieces Call Pieces (via `ask_pieces_ltm` / search tools) whenever: **The human asks about something in the past** that you're unlikely to know from this session alone: - "What did I work on today?" - "What did I work on yesterday / last week?" - "What have I been doing on [project] recently?" - "Who is [person]?" **You need context for:** - **Meetings:** - "What is my next meeting?" - "What did we discuss in last week's standup?" - **Debugging / research:** - "What did I try last time I debugged this issue?" - "What fixes have I used before for this type of error?" ### 6.2 Prefer ask_pieces_ltm Use `ask_pieces_ltm` as your first tool for historical questions: **Send a natural-language question, e.g.:** - "What did the user work on today?" - "Summarize the main projects the user has been working on this month." - "Who is the user and what is their role?" **Understand the response format:** - You'll get raw JSON with `summaries[]` and `events[]` arrays - Each entry has a `combined_string` field with the content - Parse this data and synthesize a natural language answer **When you answer, say something like:** > "According to your Pieces long-term memory, …" If `ask_pieces_ltm` times out or is too vague, narrow the query by time and/or topic (see troubleshooting). ### 6.3 Use create_pieces_memory for durable summaries Use `create_pieces_memory` when you want to write an important memory: **Typical use cases:** - **Human profile:** name, role, responsibilities, preferences, current focus. - **Decision summaries:** what was decided, why, who was involved. - **Debugging recaps:** symptoms, steps taken, final fix. - **Project milestones:** what changed, what shipped. **Conceptual signature:** ``` create_pieces_memory( summary_description: string, summary: string, project?: string, files?: string[], externalLinks?: string[], connected_client?: string ); ``` **Guidelines:** - **`summary_description`** — short human-readable label. - Examples: - `"Profile: – Role at "` - `"OpenClaw + Pieces: Initial Setup"` - **`summary`** — full markdown body: - Start with a `#` heading: - `# Profile: – Role at ` - Add a few clear sections: - `## Role` - `## Responsibilities` - `## Current Focus` - `## Notes / Preferences` - **`project`** — (optional) grouping label: - `"OpenClaw + Pieces"`, `"Website"`, `"Standup Automation"`, etc. - **`files` / `externalLinks` / `connected_client`** — optional context and attribution. This makes memories both human-readable and easy for future agents to retrieve and interpret. --- ## 7. Direct Testing vs. MCPorter Usage - **For debugging:** Use the file-based curl examples from Section 3.2 to test the MCP server directly. - **For production:** Once MCPorter is configured, you don't manually manage sessions — `mcp-remote` does it for you. Just call the tools through OpenClaw's MCP integration normally. --- ## 8. Tunnel Options This skill works with any HTTPS tunnel that forwards to `localhost:39300` on the PiecesOS machine: | Tunnel Type | Example URL | Notes | |-------------|-------------|-------| | **ngrok** | `https://abc123.ngrok-free.dev` | Most common; may require auth setup | | **Custom Pieces tunnel** | `https://username.tunnel.company.stream` | Pre-configured by Pieces team | | **Any HTTPS proxy** | `https://your-domain.com` | As long as it forwards to 39300 | The MCP endpoint is always at: ``` /model_context_protocol/2025-03-26/mcp ``` --- ## 9. Troubleshooting ### 9.1 MCP URL check fails (404/502/timeout) **Symptom:** `curl MCP_URL_MCP` returns 404/502/HTML or times out. **What to do:** Ask the human to: 1. Confirm PiecesOS is running on the remote machine. 2. Confirm the tunnel is still running (ngrok or custom). 3. Paste a fresh tunnel URL if ngrok was restarted. Rebuild `MCP_URL_MCP` and test again with the quick sanity check. ### 9.2 Initialize returns HTTP 500 (Internal Server Error) **Symptom:** ```bash curl -i -X POST "MCP_URL_MCP" ... -d '{"jsonrpc": "2.0", ...}' # Returns: HTTP/1.1 500 Internal Server Error ``` **Checklist:** 1. **Confirm route is alive first:** ```bash curl -i "MCP_URL_MCP" ``` → Should return **400** with "mcp-session-id required" message → If you get 404/502, the tunnel is down (see 9.1) 2. **Use file-based JSON (avoid shell quoting issues):** ```bash # Create init.json with your JSON payload curl -i -X POST "MCP_URL_MCP" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "mcp-session-id: init-request-001" \ --data-binary @init.json ``` 3. **Use string JSON-RPC ids:** ```json {"id": "1"} ✅ Correct {"id": 1} ❌ May cause issues ``` 4. **Ensure BOTH headers are present:** - `Content-Type: application/json` - `Accept: application/json, text/event-stream` 5. **If still 500:** Ask the human to restart PiecesOS and/or the tunnel, then re-test. ### 9.3 Tools seem missing or unresponsive **Symptoms:** - `ask_pieces_ltm` never seems to be called. - Pieces tools don't show up in behavior. - Calls time out immediately. **What to check:** 1. **`mcporter.json`:** - Exists at `~/.openclaw/workspace/config/mcporter.json`. - Has a `pieces` server using `mcp-remote` pointed at a valid `/mcp` URL. 2. **`mcp-remote`:** - Is installed globally: ```bash mcp-remote --help ``` - If missing, install: ```bash npm install -g mcp-remote@0.1.38 ``` 3. **Gateway:** - Was restarted after editing `mcporter.json`: ```bash openclaw gateway restart ``` 4. **Test the MCP server directly** using the file-based curl examples from Section 3.2: - If direct curl works but MCPorter doesn't → issue is with the bridge - If direct curl fails → issue is with PiecesOS or the tunnel ### 9.4 ask_pieces_ltm timeouts / vague answers **Symptoms:** - Pieces returns "failed to extract context" or times out. - Answers are too generic. **What to try:** 1. **Narrow the question:** - Add time: - "What did I work on this morning?" - "What did I work on this week related to [project]?" - Add topic: - "What have I done recently around MCP and ngrok?" - "What have I been doing on the website?" 2. **If repeated timeouts continue:** - Test with file-based curl directly (Section 3.2) to isolate whether it's an MCPorter issue - Confirm the MCP server is healthy with `curl -i MCP_URL_MCP` - Confirm the tunnel is still running (human-side) ### 9.5 Getting raw JSON instead of natural language **This is NOT a problem!** - Raw JSON responses are **expected and correct** for OpenClaw agents - The `summaries[]` and `events[]` arrays contain structured data for you to parse - **You should synthesize the natural language answer yourself** If you're getting raw JSON, it means: - ✅ The MCP server is working correctly - ✅ Memory retrieval is working correctly - ✅ You have structured data to work with Simply parse the JSON and create a helpful answer for the human! --- ## 10. Summary of the Flow 1. **Detect the need** for Pieces (user mentions Pieces/MCP/long-term memory). 2. **Guide the human:** - Confirm PiecesOS + LTM is running. - Set up tunnel (ngrok or custom). - Paste the HTTPS tunnel URL. 3. **Build and verify** `MCP_URL_MCP`: - Quick sanity check: `curl -i MCP_URL_MCP` → expect 400 4. **(Optional) Test directly** using file-based curl examples from Section 3.2: - Use string ids (`"id": "1"`) - Use `--data-binary @file.json` - Extract server-assigned session-id from **response headers** (13-digit timestamp) 5. **Configure MCPorter** (`mcporter.json` with `mcp-remote` → `/mcp`). 6. **Ensure `mcp-remote` is installed.** 7. **Restart the OpenClaw gateway.** 8. **Use `ask_pieces_ltm`** for reading history (parse raw JSON responses). 9. **Use `create_pieces_memory`** for writing durable summaries. 10. **Apply troubleshooting steps** if anything fails. If you follow this skill, you should be able to reliably connect to and use Pieces as external long-term memory from a fresh OpenClaw instance with minimal human effort. ```

Pieces Long-Term Memory (MCP)

Description

Latest Changes

Install Pieces Long-Term Memory (MCP) with One Click