[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77RAMMCFN8AZQF48SAJQX2C":3,"skill-same:01M77RAMMCFN8AZQF48SAJQX2C":45},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":20,"frontMatter":21,"refName":22,"commitSha":23,"skillDirectory":24,"forksCount":25,"repositoryHtmlUrl":26,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M77RAMMCFN8AZQF48SAJQX2C","pieces-mcp",null,"Lord1Egypt\u002Fawesome-skill-forge","Lord1Egypt","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F99746359?v=4","01M7592YDNT0XK9WJ0T2MQVPDN","Mohamed Mounir Ali AL Keshita","01M75GRFNHC8VZNWEB8DKDE433",3,"MIT","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fcommunity\u002Fclawhub\u002Fp\u002Fpieces-mcp\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"# Pieces Long-Term Memory MCP Skill.md\n\n\n```markdown\n---\nname: pieces-mcp\ndescription: >\n  Connect OpenClaw to Pieces via MCP-only (no SSE) and use Pieces as external\n  long-term memory. Use this when the human runs PiecesOS with LTM enabled on\n  another machine and exposes the MCP server via a tunnel (ngrok, custom domain,\n  or any HTTPS proxy). This skill tells the agent exactly how to prompt the\n  human, configure MCPorter and mcp-remote, use Pieces tools (ask_pieces_ltm,\n  create_pieces_memory, *_full_text_search), and troubleshoot common failures.\n---\n\n# Pieces MCP Skill for OpenClaw (MCP-Only, No SSE)\n\nThis skill teaches you, the OpenClaw agent, how to:\n\n1. Know **when** to use Pieces.\n2. Guide the human through tunnel setup (ngrok or custom).\n3. Wire OpenClaw to the Pieces MCP server using **only `\u002Fmcp`**.\n4. Use Pieces tools (`ask_pieces_ltm`, `create_pieces_memory`,\n   `*_full_text_search`) in your reasoning.\n5. Troubleshoot when something goes wrong.\n\n---\n\n## 0. When to Use This Skill\n\nTrigger this skill when:\n\n- The human mentions **Pieces**, **PiecesOS**, **MCP**, \"ask Pieces\", or \"long-term memory\"\n  in the context of OpenClaw.\n- They say things like:\n  - \"I want OpenClaw to remember what I worked on.\"\n  - \"Hook OpenClaw up to my Pieces long-term memory.\"\n- You see or expect a URL like:\n  - `https:\u002F\u002F...ngrok-free.dev`\n  - `https:\u002F\u002Fusername.tunnel.company.stream`\n  - Any HTTPS URL they say is \"the Pieces MCP tunnel\".\n\nIf none of that is true, you probably don't need this skill.\n\n---\n\n## 1. Mental Model\n\nThink of three components:\n\n- **PiecesOS MCP server (remote machine)**  \n  - Runs on the human's other machine.\n  - Long-Term Memory (LTM) is enabled.\n  - Exposed via an HTTPS tunnel:\n    `\u002Fmodel_context_protocol\u002F2025-03-26\u002Fmcp`.\n\n- **OpenClaw host (this machine)**  \n  - This is where you (the agent) live.\n  - Uses **MCPorter** to integrate MCP servers.\n\n- **Bridge: MCPorter + `mcp-remote`**  \n  - `mcporter.json` tells MCPorter about MCP servers.\n  - `mcp-remote` connects to the remote `\u002Fmcp` endpoint and exposes it to\n    OpenClaw.\n\n> **Important:** This integration is MCP-only. Do **not** use `\u002Fsse`.  \n> Always use `\u002Fmcp` for both direct calls and the bridge.\n\n---\n\n## 2. Human Checklist (What You Must Confirm)\n\nYou must guide\u002Fconfirm these three things:\n\n1. **PiecesOS + LTM is running** on the remote machine.  \n   Say something like:\n   > \"Make sure PiecesOS is installed and running on your other machine, and that\n   > Long-Term Memory (LTM) is enabled in the Pieces Desktop App.\"\n\n2. **A tunnel is available** to expose the MCP server.  \n   Options include:\n   - **ngrok** (most common): `ngrok http 39300`\n   - **Custom tunnel** (e.g., `username.tunnel.company.stream`)\n   - Any HTTPS proxy that forwards to `localhost:39300`\n\n3. **For ngrok specifically, tell them:**\n\n   > \"On the machine running PiecesOS, please run this in a terminal:\n   >\n   > ```bash\n   > ngrok http 39300\n   > ```\n   >\n   > If ngrok asks for login or an authtoken, follow its instructions once.\n   > When it's running, you'll see a forwarding URL like:\n   >\n   > `https:\u002F\u002FSOMETHING.ngrok-free.dev -> http:\u002F\u002Flocalhost:39300`\n   >\n   > Please paste that HTTPS URL here.\"\n\nYou cannot proceed until the human pastes a valid HTTPS tunnel URL.\n\n---\n\n## 3. Build and Verify the MCP URL\n\nOnce you have the base tunnel URL, construct the MCP endpoint.\n\nIf the human gave you:\n\n```text\nhttps:\u002F\u002FSOMETHING.ngrok-free.dev\n```\n\nOr a custom tunnel like:\n\n```text\nhttps:\u002F\u002Fname.tunnel.company.stream\n```\n\nDefine:\n\n```\nMCP_URL_BASE = \u003Cthe tunnel URL>\nMCP_URL_MCP  = \u003Cthe tunnel URL>\u002Fmodel_context_protocol\u002F2025-03-26\u002Fmcp\n```\n\n### 3.1 Quick Sanity Check (Before Initialize)\n\n**Always run this GET request first** to confirm the route is alive:\n\n```bash\ncurl -i \"MCP_URL_MCP\"\n```\n\n**Expected success response (HTTP 400):**\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"error\": {\n    \"code\": -32000,\n    \"message\": \"Bad Request: mcp-session-id header or sessionId query parameter is required\"\n  },\n  \"id\": null\n}\n```\n\nThis 400 error is **good** — it means:\n- ✅ The route exists\n- ✅ The MCP server is running\n- ✅ It's ready to accept properly-formed requests\n\n**If you get 404, 502, HTML, or timeout** → See Section 9.1: Troubleshooting.\n\n### 3.2 Understanding MCP Request Patterns (Critical!)\n\nBefore configuring MCPorter, you need to understand how MCP requests work. This section shows the exact request patterns so you don't get confused.\n\n#### The Session Management Pattern\n\nAll MCP interactions follow this flow:\n\n1. **Initialize** → Server assigns you a session-id\n2. **Use that session-id** for all subsequent requests\n3. **Never reuse your custom session-id** — always use the server-assigned one\n\n#### Session ID Format\n\n> **What to look for:** The server-assigned session-id is typically a **Unix \n> timestamp in milliseconds** — a 13-digit numeric string like `1774202062499`.\n> \n> Pattern: `17XXXXXXXXXXX` (13 digits starting with `17` in 2025-2026)\n>\n> You'll find it in the **response headers**, not the response body:\n> ```\n> mcp-session-id: 1774202062499\n> ```\n\n#### Required Headers for ALL Requests\n\n```\nContent-Type: application\u002Fjson\nAccept: application\u002Fjson, text\u002Fevent-stream\nmcp-session-id: \u003CSESSION_ID>\n```\n\n**Missing either `Content-Type` or `Accept` will cause failures!**\n\n#### Critical: Use File-Based JSON for curl\n\n> **⚠️ Shell quoting can mangle JSON!** Zsh and Bash handle quotes differently,\n> and inline JSON with `-d '{...}'` is fragile. **Always use file-based JSON\n> with `--data-binary @filename`** to avoid parsing errors.\n\n#### Critical: Use String JSON-RPC IDs\n\n> **⚠️ Use `\"id\": \"1\"` (string), not `\"id\": 1` (integer).**  \n> The server is sensitive to id types, and string ids work consistently.\n\n---\n\n#### Step 1: Initialize Session\n\nCreate a file `init.json`:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"0.1.0\",\n    \"capabilities\": {},\n    \"clientInfo\": {\n      \"name\": \"openclaw-agent\",\n      \"version\": \"1.0\"\n    }\n  },\n  \"id\": \"1\"\n}\n```\n\nRun:\n\n```bash\ncurl -i -X POST \"MCP_URL_MCP\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"Accept: application\u002Fjson, text\u002Fevent-stream\" \\\n  -H \"mcp-session-id: init-request-001\" \\\n  --data-binary @init.json\n```\n\n**What happens:**\n\n- You send `mcp-session-id: init-request-001` (can be any string you choose)\n- Server responds with a **new session-id in the response header**\n\n**Look for this in the response headers:**\n\n```\nHTTP\u002F2 200\ncontent-type: application\u002Fjson\nmcp-session-id: 1774202062499\n...\n```\n\n> **Critical:** Extract the `mcp-session-id` value from the **response header** \n> (e.g., `1774202062499`). This is your server-assigned session ID. Use this \n> exact value for all subsequent requests — do NOT continue using your initial \n> `init-request-001`.\n\n**Response body (200 OK):**\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"1\",\n  \"result\": {\n    \"protocolVersion\": \"0.1.0\",\n    \"capabilities\": {\n      \"tools\": {}\n    },\n    \"serverInfo\": {\n      \"name\": \"pieces\",\n      \"version\": \"1.0.0\"\n    }\n  }\n}\n```\n\n---\n\n#### Step 2: Query Long-Term Memory\n\nNow use the **server-assigned session-id** for all future requests.\n\nCreate a file `query.json`:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools\u002Fcall\",\n  \"params\": {\n    \"name\": \"ask_pieces_ltm\",\n    \"arguments\": {\n      \"question\": \"What did I work on today?\",\n      \"chat_llm\": \"gpt-4\"\n    }\n  },\n  \"id\": \"2\"\n}\n```\n\nRun (replacing `\u003CSERVER_SESSION_ID>` with the value from Step 1):\n\n```bash\ncurl -i -X POST \"MCP_URL_MCP\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"Accept: application\u002Fjson, text\u002Fevent-stream\" \\\n  -H \"mcp-session-id: \u003CSERVER_SESSION_ID>\" \\\n  --data-binary @query.json\n```\n\n**Example with actual session ID:**\n\n```bash\ncurl -i -X POST \"MCP_URL_MCP\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"Accept: application\u002Fjson, text\u002Fevent-stream\" \\\n  -H \"mcp-session-id: 1774202062499\" \\\n  --data-binary @query.json\n```\n\n**Response (200 OK):**\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"2\",\n  \"result\": {\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"{\\\"summaries\\\":[...],\\\"events\\\":[...]}\"\n      }\n    ]\n  }\n}\n```\n\n**Important for OpenClaw Agents:**\n\nThe response looks like \"raw JSON garbage\" to humans, but this is **perfect for you!**\n\nYou get:\n- `summaries[]` — Pre-existing memory summaries with relevance scores\n- `events[]` — Raw activity events (browser, clipboard, audio, etc.)\n\nParse this JSON yourself and synthesize a natural language answer for the human.\n\n---\n\n#### Step 3: Create a Memory\n\nCreate a file `create_memory.json`:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"tools\u002Fcall\",\n  \"params\": {\n    \"name\": \"create_pieces_memory\",\n    \"arguments\": {\n      \"summary_description\": \"OpenClaw + Pieces: First Integration Session\",\n      \"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\",\n      \"project\": \"OpenClaw + Pieces\"\n    }\n  },\n  \"id\": \"3\"\n}\n```\n\nRun (using the same server-assigned session ID):\n\n```bash\ncurl -i -X POST \"MCP_URL_MCP\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"Accept: application\u002Fjson, text\u002Fevent-stream\" \\\n  -H \"mcp-session-id: \u003CSERVER_SESSION_ID>\" \\\n  --data-binary @create_memory.json\n```\n\n**Response (200 OK):**\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"3\",\n  \"result\": {\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"Memory created successfully\"\n      }\n    ]\n  }\n}\n```\n\n---\n\n#### Session ID Quick Reference\n\n| Stage | Header Value | Source |\n|-------|--------------|--------|\n| **Initialize request** | Any string you choose (e.g., `init-001`, `my-session`, `test-123`) | You create it |\n| **Initialize response** | 13-digit timestamp (e.g., `1774202062499`) | **Extract from response header** |\n| **All subsequent requests** | The server-assigned value from initialize | Reuse the extracted value |\n\n#### Common Mistakes That Will Break Things\n\n| ❌ Wrong | ✅ Correct |\n|----------|-----------|\n| Inline JSON with `-d '{...}'` | File-based JSON with `--data-binary @file.json` |\n| Integer id: `\"id\": 1` | String id: `\"id\": \"1\"` |\n| Missing `Accept` header | Include `Accept: application\u002Fjson, text\u002Fevent-stream` |\n| Using your initial session-id (`init-001`) for all requests | Extract server-assigned session-id from initialize **response header** |\n| Looking for session-id in response body | Session-id is in the **response headers** |\n| Thinking raw JSON responses are errors | Parse the JSON — it's structured data for you to synthesize! |\n| Calling tools before initialize | Always call initialize first to get a session-id |\n| Forgetting `chat_llm` parameter | Include it (even though responses may still be raw JSON) |\n\n---\n\n## 4. Configure MCPorter (MCP-Only)\n\nOpenClaw uses MCPorter to manage MCP servers. The config lives at:\n\n```\n~\u002F.openclaw\u002Fworkspace\u002Fconfig\u002Fmcporter.json\n```\n\nAs the agent, you should:\n\n### 4.1 Ensure the config directory exists\n\n```bash\nmkdir -p ~\u002F.openclaw\u002Fworkspace\u002Fconfig\n```\n\n### 4.2 Create or update mcporter.json\n\nYou want a `pieces` entry that uses `mcp-remote` pointed at `MCP_URL_MCP`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pieces\": {\n      \"command\": \"mcp-remote\",\n      \"args\": [\n        \"MCP_URL_MCP_GOES_HERE\"\n      ]\n    }\n  }\n}\n```\n\n**Example with ngrok:**\n\n```json\n{\n  \"mcpServers\": {\n    \"pieces\": {\n      \"command\": \"mcp-remote\",\n      \"args\": [\n        \"https:\u002F\u002FSOMETHING.ngrok-free.dev\u002Fmodel_context_protocol\u002F2025-03-26\u002Fmcp\"\n      ]\n    }\n  }\n}\n```\n\n**Example with custom tunnel:**\n\n```json\n{\n  \"mcpServers\": {\n    \"pieces\": {\n      \"command\": \"mcp-remote\",\n      \"args\": [\n        \"https:\u002F\u002Fusername.tunnel.company.stream\u002Fmodel_context_protocol\u002F2025-03-26\u002Fmcp\"\n      ]\n    }\n  }\n}\n```\n\nNo `\u002Fsse` here. This is the MCP-only configuration.\n\n> **Note:** `mcp-remote` handles the session management (initialize, session-id \n> extraction, header management) automatically. You don't need to manually manage \n> sessions when using MCPorter — the examples in Section 3.2 are for understanding \n> the protocol and direct testing\u002Ftroubleshooting.\n\n### 4.3 Ensure mcp-remote is installed\n\nInstall `mcp-remote` globally:\n\n```bash\nnpm install -g mcp-remote@0.1.38\n```\n\nYou can run this yourself from the OpenClaw host's shell.\n\n---\n\n## 5. Restart the OpenClaw Gateway\n\nAfter editing `mcporter.json`, restart the OpenClaw gateway so it picks up the\nPieces MCP server:\n\n```bash\ncd ~\u002F.openclaw\u002Fworkspace\nopenclaw gateway restart\n```\n\nWait a few seconds for it to restart.\n\nAt this point, OpenClaw should see the Pieces MCP server through MCPorter and\n`mcp-remote` → `MCP_URL_MCP`.\n\n---\n\n## 6. How and When to Use Pieces\n\nOnce connected, treat Pieces as your authoritative long-term memory.\n\n### 6.1 When to query Pieces\n\nCall Pieces (via `ask_pieces_ltm` \u002F search tools) whenever:\n\n**The human asks about something in the past** that you're unlikely to know from\nthis session alone:\n\n- \"What did I work on today?\"\n- \"What did I work on yesterday \u002F last week?\"\n- \"What have I been doing on [project] recently?\"\n- \"Who is [person]?\"\n\n**You need context for:**\n\n- **Meetings:**\n  - \"What is my next meeting?\"\n  - \"What did we discuss in last week's standup?\"\n- **Debugging \u002F research:**\n  - \"What did I try last time I debugged this issue?\"\n  - \"What fixes have I used before for this type of error?\"\n\n### 6.2 Prefer ask_pieces_ltm\n\nUse `ask_pieces_ltm` as your first tool for historical questions:\n\n**Send a natural-language question, e.g.:**\n\n- \"What did the user work on today?\"\n- \"Summarize the main projects the user has been working on this month.\"\n- \"Who is the user and what is their role?\"\n\n**Understand the response format:**\n\n- You'll get raw JSON with `summaries[]` and `events[]` arrays\n- Each entry has a `combined_string` field with the content\n- Parse this data and synthesize a natural language answer\n\n**When you answer, say something like:**\n\n> \"According to your Pieces long-term memory, …\"\n\nIf `ask_pieces_ltm` times out or is too vague, narrow the query by time and\u002For\ntopic (see troubleshooting).\n\n### 6.3 Use create_pieces_memory for durable summaries\n\nUse `create_pieces_memory` when you want to write an important memory:\n\n**Typical use cases:**\n\n- **Human profile:** name, role, responsibilities, preferences, current focus.\n- **Decision summaries:** what was decided, why, who was involved.\n- **Debugging recaps:** symptoms, steps taken, final fix.\n- **Project milestones:** what changed, what shipped.\n\n**Conceptual signature:**\n\n```\ncreate_pieces_memory(\n  summary_description: string,\n  summary: string,\n  project?: string,\n  files?: string[],\n  externalLinks?: string[],\n  connected_client?: string\n);\n```\n\n**Guidelines:**\n\n- **`summary_description`** — short human-readable label.\n  - Examples:\n    - `\"Profile: \u003Cname> – Role at \u003Ccompany>\"`\n    - `\"OpenClaw + Pieces: Initial Setup\"`\n\n- **`summary`** — full markdown body:\n  - Start with a `#` heading:\n    - `# Profile: \u003Cname> – Role at \u003Ccompany>`\n  - Add a few clear sections:\n    - `## Role`\n    - `## Responsibilities`\n    - `## Current Focus`\n    - `## Notes \u002F Preferences`\n\n- **`project`** — (optional) grouping label:\n  - `\"OpenClaw + Pieces\"`, `\"Website\"`, `\"Standup Automation\"`, etc.\n\n- **`files` \u002F `externalLinks` \u002F `connected_client`** — optional context and attribution.\n\nThis makes memories both human-readable and easy for future agents to retrieve\nand interpret.\n\n---\n\n## 7. Direct Testing vs. MCPorter Usage\n\n- **For debugging:** Use the file-based curl examples from Section 3.2 to test\n  the MCP server directly.\n\n- **For production:** Once MCPorter is configured, you don't manually manage\n  sessions — `mcp-remote` does it for you. Just call the tools through OpenClaw's\n  MCP integration normally.\n\n---\n\n## 8. Tunnel Options\n\nThis skill works with any HTTPS tunnel that forwards to `localhost:39300` on the\nPiecesOS machine:\n\n| Tunnel Type | Example URL | Notes |\n|-------------|-------------|-------|\n| **ngrok** | `https:\u002F\u002Fabc123.ngrok-free.dev` | Most common; may require auth setup |\n| **Custom Pieces tunnel** | `https:\u002F\u002Fusername.tunnel.company.stream` | Pre-configured by Pieces team |\n| **Any HTTPS proxy** | `https:\u002F\u002Fyour-domain.com` | As long as it forwards to 39300 |\n\nThe MCP endpoint is always at:\n```\n\u003Ctunnel_url>\u002Fmodel_context_protocol\u002F2025-03-26\u002Fmcp\n```\n\n---\n\n## 9. Troubleshooting\n\n### 9.1 MCP URL check fails (404\u002F502\u002Ftimeout)\n\n**Symptom:**\n\n`curl MCP_URL_MCP` returns 404\u002F502\u002FHTML or times out.\n\n**What to do:**\n\nAsk the human to:\n\n1. Confirm PiecesOS is running on the remote machine.\n2. Confirm the tunnel is still running (ngrok or custom).\n3. Paste a fresh tunnel URL if ngrok was restarted.\n\nRebuild `MCP_URL_MCP` and test again with the quick sanity check.\n\n### 9.2 Initialize returns HTTP 500 (Internal Server Error)\n\n**Symptom:**\n\n```bash\ncurl -i -X POST \"MCP_URL_MCP\" ... -d '{\"jsonrpc\": \"2.0\", ...}'\n# Returns: HTTP\u002F1.1 500 Internal Server Error\n```\n\n**Checklist:**\n\n1. **Confirm route is alive first:**\n   ```bash\n   curl -i \"MCP_URL_MCP\"\n   ```\n   → Should return **400** with \"mcp-session-id required\" message\n   → If you get 404\u002F502, the tunnel is down (see 9.1)\n\n2. **Use file-based JSON (avoid shell quoting issues):**\n   ```bash\n   # Create init.json with your JSON payload\n   curl -i -X POST \"MCP_URL_MCP\" \\\n     -H \"Content-Type: application\u002Fjson\" \\\n     -H \"Accept: application\u002Fjson, text\u002Fevent-stream\" \\\n     -H \"mcp-session-id: init-request-001\" \\\n     --data-binary @init.json\n   ```\n\n3. **Use string JSON-RPC ids:**\n   ```json\n   {\"id\": \"1\"}  ✅ Correct\n   {\"id\": 1}    ❌ May cause issues\n   ```\n\n4. **Ensure BOTH headers are present:**\n   - `Content-Type: application\u002Fjson`\n   - `Accept: application\u002Fjson, text\u002Fevent-stream`\n\n5. **If still 500:** Ask the human to restart PiecesOS and\u002For the tunnel, then\n   re-test.\n\n### 9.3 Tools seem missing or unresponsive\n\n**Symptoms:**\n\n- `ask_pieces_ltm` never seems to be called.\n- Pieces tools don't show up in behavior.\n- Calls time out immediately.\n\n**What to check:**\n\n1. **`mcporter.json`:**\n   - Exists at `~\u002F.openclaw\u002Fworkspace\u002Fconfig\u002Fmcporter.json`.\n   - Has a `pieces` server using `mcp-remote` pointed at a valid `\u002Fmcp` URL.\n\n2. **`mcp-remote`:**\n   - Is installed globally:\n     ```bash\n     mcp-remote --help\n     ```\n   - If missing, install:\n     ```bash\n     npm install -g mcp-remote@0.1.38\n     ```\n\n3. **Gateway:**\n   - Was restarted after editing `mcporter.json`:\n     ```bash\n     openclaw gateway restart\n     ```\n\n4. **Test the MCP server directly** using the file-based curl examples from\n   Section 3.2:\n   - If direct curl works but MCPorter doesn't → issue is with the bridge\n   - If direct curl fails → issue is with PiecesOS or the tunnel\n\n### 9.4 ask_pieces_ltm timeouts \u002F vague answers\n\n**Symptoms:**\n\n- Pieces returns \"failed to extract context\" or times out.\n- Answers are too generic.\n\n**What to try:**\n\n1. **Narrow the question:**\n   - Add time:\n     - \"What did I work on this morning?\"\n     - \"What did I work on this week related to [project]?\"\n   - Add topic:\n     - \"What have I done recently around MCP and ngrok?\"\n     - \"What have I been doing on the website?\"\n\n2. **If repeated timeouts continue:**\n   - Test with file-based curl directly (Section 3.2) to isolate whether it's\n     an MCPorter issue\n   - Confirm the MCP server is healthy with `curl -i MCP_URL_MCP`\n   - Confirm the tunnel is still running (human-side)\n\n### 9.5 Getting raw JSON instead of natural language\n\n**This is NOT a problem!**\n\n- Raw JSON responses are **expected and correct** for OpenClaw agents\n- The `summaries[]` and `events[]` arrays contain structured data for you to parse\n- **You should synthesize the natural language answer yourself**\n\nIf you're getting raw JSON, it means:\n\n- ✅ The MCP server is working correctly\n- ✅ Memory retrieval is working correctly\n- ✅ You have structured data to work with\n\nSimply parse the JSON and create a helpful answer for the human!\n\n---\n\n## 10. Summary of the Flow\n\n1. **Detect the need** for Pieces (user mentions Pieces\u002FMCP\u002Flong-term memory).\n\n2. **Guide the human:**\n   - Confirm PiecesOS + LTM is running.\n   - Set up tunnel (ngrok or custom).\n   - Paste the HTTPS tunnel URL.\n\n3. **Build and verify** `MCP_URL_MCP`:\n   - Quick sanity check: `curl -i MCP_URL_MCP` → expect 400\n\n4. **(Optional) Test directly** using file-based curl examples from Section 3.2:\n   - Use string ids (`\"id\": \"1\"`)\n   - Use `--data-binary @file.json`\n   - Extract server-assigned session-id from **response headers** (13-digit timestamp)\n\n5. **Configure MCPorter** (`mcporter.json` with `mcp-remote` → `\u002Fmcp`).\n\n6. **Ensure `mcp-remote` is installed.**\n\n7. **Restart the OpenClaw gateway.**\n\n8. **Use `ask_pieces_ltm`** for reading history (parse raw JSON responses).\n\n9. **Use `create_pieces_memory`** for writing durable summaries.\n\n10. **Apply troubleshooting steps** if anything fails.\n\nIf you follow this skill, you should be able to reliably connect to and use\nPieces as external long-term memory from a fresh OpenClaw instance with minimal\nhuman effort.\n```",{},"master","4aa004da461d820f4ea5499e58eb8d196cf99016","community\u002Fclawhub\u002Fp\u002Fpieces-mcp",0,"https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge","https:\u002F\u002Fskill-explorer-rho.vercel.app","https:\u002F\u002Fgithub.com\u002FLord1Egypt","Unbreakable. Unstoppable. Unmatched⚡.\r\n Speaker of machine tongues 🤖  | World-builder of decentralized dreams 🌐 | Defender of the digital realm🛡️.","2026-06-10 08:21:01",{"source":7,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add Lord1Egypt\u002Fawesome-skill-forge --skill pieces-mcp",{"tool":37,"command":38},"bunx","bunx skills add Lord1Egypt\u002Fawesome-skill-forge --skill pieces-mcp",{"tool":40,"command":41},"pnpm","pnpm dlx skills add Lord1Egypt\u002Fawesome-skill-forge --skill pieces-mcp","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fcommunity\u002Fclawhub\u002Fp\u002Fpieces-mcp\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":18},"01M785WKJB99G3STR1NF9NRTJW","youtube-content","YouTube transcripts to summaries, threads, blogs.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fyoutube-content\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":18},"01M785WEFHB0G2S9YA6EPR3H0E","xurl","X\u002FTwitter via xurl CLI: post, search, DM, media, v2 API.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fxurl\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":18},"01M785W98EDN4EFJXJPMQEHCRC","touchdesigner-mcp","Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Ftouchdesigner-mcp\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":18},"01M785W5S9FP3QBH2V191E025P","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":18},"01M785W2AS08NSSH9YATCV6FJB","teams-meeting-pipeline","Operate the Teams meeting summary pipeline via Hermes CLI — summarize meetings, inspect pipeline status, replay jobs, manage Microsoft Graph subscriptions.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fteams-meeting-pipeline\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":18},"01M785VXKW4T34BTP1SCHW1R7F","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002FLord1Egypt\u002Fawesome-skill-forge\u002Fblob\u002Fmaster\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[]]