Pinecone

View saved version →

---
name: assistant
description: Create, manage, and chat with Pinecone Assistants for document Q&A with citations. Handles all assistant operations - create, upload, sync, chat, context retrieval, and list. Recognizes natural language like "create an assistant from my docs", "ask my assistant about X", or "upload my docs to Pinecone".
---

# Pinecone Assistant

Pinecone Assistant is a fully managed RAG service. Upload documents, ask questions, get cited answers. No embedding pipelines or infrastructure required.

> All scripts are in `scripts/` relative to this skill directory.
> Run with: `uv run scripts/script_name.py [arguments]`

Whenever this skill asks the user to choose between options, confirm a destructive step, or pick from a list, ask in plain prose, list the options, and wait for their answer before continuing.

## Operations

| What to do | Script | Key args |
|---|---|---|
| Create an assistant | `scripts/create.py` | `--name` `--instructions` `--region` |
| Upload files | `scripts/upload.py` | `--assistant` `--source` `--patterns` |
| Sync files (incremental) | `scripts/sync.py` | `--assistant` `--source` `--delete-missing` `--dry-run` |
| Chat / ask a question | `scripts/chat.py` | `--assistant` `--message` |
| Get context snippets | `scripts/context.py` | `--assistant` `--query` `--top-k` |
| List assistants | `scripts/list.py` | `--files` `--json` |

For full workflow details on any operation, read the relevant file in `references/`.

---

## Natural Language Recognition

Proactively handle these patterns without requiring explicit commands:

**Create:** "create an assistant", "make an assistant called X", "set up an assistant for my docs"
→ See [references/create.md](references/create.md)

**Upload:** "upload my docs", "add files to my assistant", "index my documentation"
→ See [references/upload.md](references/upload.md)

**Sync:** "sync my docs", "update my assistant", "keep assistant in sync", "refresh from ./docs"
→ See [references/sync.md](references/sync.md)

**Chat:** "ask my assistant about X", "what does my assistant know about X", "chat with X"
→ See [references/chat.md](references/chat.md)

**Context:** "search my assistant for X", "find context about X"
→ See [references/context.md](references/context.md)

**List:** "show my assistants", "what assistants do I have"
→ Run `uv run scripts/list.py`

---

## Conversation Memory

Track the last assistant used within the conversation:
- When a user creates or first uses an assistant, remember its name
- If user says "my assistant", "it", or "the assistant" → use the last one
- Briefly confirm which assistant you're using: "Asking docs-bot..."
- If ambiguous and multiple exist → ask the user to clarify

---

## Multi-Step Requests

Handle chained requests naturally. Example:

> "Create an assistant called docs-bot, upload my ./docs folder, and ask what the main features are"

1. `uv run scripts/create.py --name docs-bot`
2. `uv run scripts/upload.py --assistant docs-bot --source ./docs`
3. `uv run scripts/chat.py --assistant docs-bot --message "what are the main features?"`

---

## Prerequisites

- `PINECONE_API_KEY` must be available:
- Codex CLI: run `export PINECONE_API_KEY="your-key"` in the shell you start `codex` from. The bundled MCP server reads it from Codex's environment.
- Codex Desktop on macOS: run `launchctl setenv PINECONE_API_KEY "your-key"`, then quit Codex fully and open it again.
- For scripts, you can also use `uv run --env-file .env scripts/...`.
- `uv` must be installed — [install uv](https://docs.astral.sh/uv/getting-started/installation/)
- Get a free API key at: https://app.pinecone.io/?sessionType=signup

Referenced files: 12 — file references are metadata, not package contents.

View saved version →

---
name: cli
description: Guide for using the Pinecone CLI (pc) to manage Pinecone resources from the terminal. The CLI supports ALL index types (standard, integrated, sparse) and all vector operations — unlike the MCP which only supports integrated indexes. Use for batch operations, vector management, backups, namespaces, CI/CD automation, and full control over Pinecone resources.
argument-hint: install | auth | index [op] | vector [op] | backup | namespace
---

# Pinecone CLI (`pc`)

Manage Pinecone from the terminal. The CLI is especially valuable for vector operations across **all index types** — something the MCP currently can't do.

## CLI vs MCP

| | CLI | MCP |
|---|---|---|
| Index types | All (standard, integrated, sparse) | Integrated only |
| Vector ops (upsert, query, fetch, update, delete) | ✅ | ❌ |
| Text search on integrated indexes | ✅ | ✅ |
| Backups, namespaces, org/project mgmt | ✅ | ❌ |
| CI/CD / scripting | ✅ | ❌ |

---

## Setup

### Install (macOS)
```bash
brew tap pinecone-io/tap
brew install pinecone-io/tap/pinecone
```

Other platforms (Linux, Windows) — download from [GitHub Releases](https://github.com/pinecone-io/cli/releases).

### Authenticate

```bash
# Interactive (recommended for local dev)
pc login
pc target -o "my-org" -p "my-project"

# Service account (recommended for CI/CD)
pc auth configure --client-id "$PINECONE_CLIENT_ID" --client-secret "$PINECONE_CLIENT_SECRET"

# API key (quick testing)
pc config set-api-key $PINECONE_API_KEY
```

Check status: `pc auth status` · `pc target --show`

> **Note for agent sessions**: If you need to run `pc login` inside an agent loop, the browser auth link may not surface correctly. It's best to authenticate **before** starting an agent session. Run `pc login` in your terminal directly, then invoke the agent once you're authenticated.

### Authenticating the CLI does not set `PINECONE_API_KEY`

`pc login` authenticates the CLI tool itself — it does **not** set `PINECONE_API_KEY` in your environment. Python scripts, Node.js SDKs, and other tools that use the Pinecone SDK need `PINECONE_API_KEY` set separately.

Use the CLI to create a key and export it in one step:

```bash
KEY=$(pc api-key create --name agent-sdk-key --json | jq -r '.value')
export PINECONE_API_KEY="$KEY"
```

Without `jq`: run `pc api-key create --name agent-sdk-key --json` and copy the `"value"` field manually.

---

## Common Commands

| Task | Command |
|---|---|
| List indexes | `pc index list` |
| Create serverless index | `pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1` |
| Index stats | `pc index stats -n my-index` |
| Upload vectors from file | `pc index vector upsert -n my-index --file ./vectors.json` |
| Query by vector | `pc index vector query -n my-index --vector '[0.1, ...]' -k 10 --include-metadata` |
| Query by vector ID | `pc index vector query -n my-index --id "doc-123" -k 10` |
| Fetch vectors by ID | `pc index vector fetch -n my-index --ids '["vec1","vec2"]'` |
| List vector IDs | `pc index vector list -n my-index` |
| Delete vectors by filter | `pc index vector delete -n my-index --filter '{"genre":"classical"}'` |
| List namespaces | `pc index namespace list -n my-index` |
| Create backup | `pc backup create -i my-index -n "my-backup"` |
| JSON output (for scripting) | Add `-j` to any command |

---

## Interesting Things You Can Do

### Query with custom vectors (not just text)
Unlike the MCP, the CLI lets you query any index with raw vector values — useful when you generate embeddings externally (OpenAI, HuggingFace, etc.):
```bash
pc index vector query -n my-index \
  --vector '[0.1, 0.2, ..., 0.9]' \
  --filter '{"source":{"$eq":"docs"}}' \
  -k 20 --include-metadata
```

### Pipe embeddings directly into queries
```bash
jq -c '.embedding' doc.json | pc index vector query -n my-index --vector - -k 10
```

### Bulk metadata update with preview
```bash
# Preview first
pc index vector update -n my-index \
  --filter '{"env":{"$eq":"staging"}}'

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: docs
description: Curated documentation reference for developers building with Pinecone. Contains links to official docs organized by topic and data format references. Use when writing Pinecone code, looking up API parameters, or needing the correct format for vectors or records.
---

# Pinecone Developer Reference

A curated index of Pinecone documentation. Fetch the relevant page(s) for the task at hand rather than relying on training data.

---

## NOTE TO AGENT
Please attempt to fetch the url listed when relevant. If you run into an error, please attempt to append ".md" to the url to retrieve the markdown version of the Docs page.

In case you need it: A full reference to ALL relevant URLs can be found here: https://docs.pinecone.io/llms.txt

Use this as a last resort if you cannot find the relevant page below.

---

## Getting Started

| Topic | URL |
|---|---|
| Quickstart for all languages and coding environments (Cursor, Claude Code, n8n, Python, JavaScript, Java, Go, C#) | https://docs.pinecone.io/guides/get-started/quickstart |
| Pinecone concepts — namespaces, terminology, and key database concepts | https://docs.pinecone.io/guides/get-started/concepts |
| Data modeling for text and vectors | https://docs.pinecone.io/guides/index-data/data-modeling |
| Architecture of Pinecone | https://docs.pinecone.io/guides/get-started/database-architecture |
| Pinecone Assistant overview | https://docs.pinecone.io/guides/assistant/overview |

---

## Indexes

| Topic | URL |
|---|---|
| Create an index | https://docs.pinecone.io/guides/index-data/create-an-index |
| Index types and conceptual overview | https://docs.pinecone.io/guides/index-data/indexing-overview |
| Integrated inference (built-in embedding models) | https://docs.pinecone.io/guides/index-data/indexing-overview#integrated-embedding |
| Dedicated read nodes — predictable low-latency performance at high query volumes | https://docs.pinecone.io/guides/index-data/dedicated-read-nodes |

---

## Upsert & Data

| Topic | URL |
|---|---|
| Upsert vectors and text | https://docs.pinecone.io/guides/index-data/upsert-data |
| Multitenancy with namespaces | https://docs.pinecone.io/guides/index-data/implement-multitenancy |

---

## Search

| Topic | URL |
|---|---|
| Semantic search | https://docs.pinecone.io/guides/search/semantic-search |
| Hybrid search | https://docs.pinecone.io/guides/search/hybrid-search |
| Lexical search | https://docs.pinecone.io/guides/search/lexical-search |
| Full-text search (preview) — document-schema FTS indexes with `text` / `query_string` / dense / sparse scoring | https://docs.pinecone.io/guides/search/full-text-search |
| Metadata filtering — narrow results and speed up searches | https://docs.pinecone.io/guides/search/filter-by-metadata |

---

## API & SDK Reference

| Topic | URL |
|---|---|
| Python SDK reference | https://docs.pinecone.io/reference/sdks/python/overview |
| Example Colab notebooks | https://docs.pinecone.io/examples/notebooks |

---

## Production

| Topic | URL |
|---|---|
| Production checklist — preparing your index for production | https://docs.pinecone.io/guides/production/production-checklist |
| Common errors and what they mean | https://docs.pinecone.io/guides/production/error-handling |
| Targeting indexes correctly — don't use index names in prod | https://docs.pinecone.io/guides/manage-data/target-an-index#target-by-index-host-recommended |

---

## Data Formats

See [references/data-formats.md](references/data-formats.md) for vector and record schemas.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: full-text-search
description: Create, ingest into, and query a Pinecone full-text-search (FTS) document index using the graduated document-schema API (Python SDK 10.0.0, API version 2026-07). Use when the user or agent asks to build a text search index on Pinecone, add dense or sparse vector fields, ingest documents, construct score_by clauses (text / query_string / dense_vector / sparse_vector), or compose with text-match filters ($match_phrase / $match_all / $match_any). Ships `scripts/ingest.py` for safe bulk ingestion (batch_upsert + error inspection + readiness polling); query construction is documented inline in this skill — write `documents.search(...)` calls directly, validated against `pc.indexes.describe(...)` output.
---

# Pinecone Full-Text Search

> **Requires `pinecone` Python SDK ≥ 10.0.0** (`pip install pinecone>=10.0.0`). The document-schema API graduated out of `pinecone.preview` in 10.0.0 — it is now a first-class, SemVer-covered part of the SDK, reachable directly off `pc` (`pc.indexes`, `pc.index(...)`). If you land on this skill from an older habit of importing `pinecone.preview`, stop: that package is deleted outright in 10.0.0 (`ModuleNotFoundError`, no shim). The packaged helper script pins `pinecone==10.0.0` via PEP 723 inline metadata; if you're writing your own code against this skill, pin at least that version. The wire API version is `2026-07`.

> **Authoritative reference (last resort).** If you hit a question this skill and its `references/*.md` files don't answer, the official Pinecone FTS docs are at <https://docs.pinecone.io/guides/search/full-text-search>. Prefer this skill's content for anything covered here — the docs may describe surfaces (e.g. classic vector API, or the older `pinecone.preview` shape) that don't apply to the graduated document-schema path. Consult the link only when you're genuinely stuck.

> **Tell the user up front:** "This skill ships a helper at `scripts/ingest.py` that handles bulk ingestion safely (batched upsert, error inspection, readiness polling). When we get to the ingest step, I'll use it." Surface this at the start of the conversation so the user knows the helper exists. Query construction is hand-written `documents.search(...)` per the **Querying** section below — there is no query helper.

A workflow skill for building a Pinecone full-text-search index with the graduated document-schema API (`pc.indexes`, `pc.index(name)`, API version `2026-07`). Covers schema design (text, dense vector, sparse vector, filterable metadata), ingestion (including async indexing and polling), and query construction (`text` / `query_string` / `dense_vector` / `sparse_vector` scoring; `$match_phrase` / `$match_all` / `$match_any` text-match filters; `$eq` / `$in` / `$gte` / `$exists` / `$and` / `$or` / `$not` metadata filters).

## Scope — this skill is for the document-schema FTS API only

This skill covers `pc.indexes.create(..., schema=...)`, `pc.index(name)`, `idx.documents.upsert(...)` / `idx.documents.batch_upsert(...)` / `idx.documents.search(...)`. If you find yourself reaching for any of the following, **stop** — those are different Pinecone APIs and this skill's guidance and helpers won't apply:

- **Classic vector / records API**: `pc.Index(name)`, `index.upsert(vectors=[...])`, `index.query(vector=..., sparse_vector=...)`, `pc.create_index(dimension=..., metric=..., spec=ServerlessSpec(...))`. This is the *deprecated sugar* path in 10.0.0 — it still runs, but it creates a schemaless index served by the vector data plane, addressing the vector by the reserved `_values` field. It cannot hold `full_text_search` fields.
- **Integrated-embedding / records indexes**: `pc.create_index_for_model(...)` / `pc.indexes.create_for_model(...)` with `embed={...}`. Pinecone vectorizes text server-side, and the resulting `semantic_text` field is served by the **records** API (`upsert_records` / `search_records`), not the documents API. Different upsert/search shapes. A `s

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: help
description: Overview of all available Pinecone skills and what a user needs to get started. Invoke when a user asks what skills are available, how to get started with Pinecone, or what they need to set up before using any Pinecone skill.
---

# Pinecone Skills — Help & Overview

Pinecone is the leading vector database for building accurate and performant AI applications at scale in production. It's useful for building semantic search, retrieval augmented generation, recommendation systems, and agentic applications.

Here's everything you need to get started and a summary of all available skills.

Ask Codex for any skill by name — for example `pinecone:quickstart` or `pinecone:n8n` — or just describe what you want and Codex picks the skill.

---

## What You Need

### Required
- **Pinecone account** — free to create at https://app.pinecone.io/?sessionType=signup
- **API key** — create one in the Pinecone console after signing up, then make it
  available to this environment:
  - Codex CLI: run `export PINECONE_API_KEY="your-key"` in the shell you start `codex` from. The bundled MCP server reads it from Codex's environment.
- Codex Desktop on macOS: run `launchctl setenv PINECONE_API_KEY "your-key"`, then quit Codex fully and open it again.
- For scripts, you can also use `uv run --env-file .env scripts/...`.

### Optional (unlock more capabilities)

| Tool | What it enables | Install |
|---|---|---|
| **Pinecone MCP server** | Use Pinecone directly inside your AI agent/IDE without writing code | [Setup guide](https://docs.pinecone.io/guides/operations/mcp-server#tools) |
| **Pinecone CLI (`pc`)** | Manage all index types from the terminal, batch operations, backups, CI/CD | `brew tap pinecone-io/tap && brew install pinecone-io/tap/pinecone` |
| **uv** | Run the packaged Python scripts included in these skills | [Install uv](https://docs.astral.sh/uv/getting-started/installation/) |

---

## Available Skills

| Skill | What it does |
|---|---|
| `pinecone:quickstart` | Step-by-step onboarding — create an index, upload data, and run your first search |
| `pinecone:query` | Search integrated indexes using natural language text via the Pinecone MCP |
| `pinecone:cli` | Use the Pinecone CLI (`pc`) for terminal-based index and vector management |
| `pinecone:assistant` | Create, manage, and chat with Pinecone Assistants for document Q&A with citations |
| `pinecone:mcp` | Reference for all Pinecone MCP server tools and their parameters |
| `pinecone:full-text-search` | Build a full-text-search index — schema design, safe bulk ingestion, and query construction (`text` / `query_string` / dense / sparse scoring with text-match and metadata filters). **Document-schema API (`2026-07`); requires `pinecone` Python SDK ≥ 10.0.0.** |
| `pinecone:docs` | Curated links to official Pinecone documentation, organized by topic |
| `pinecone:n8n` | Build n8n workflows with the Pinecone Assistant node or Pinecone Vector Store node, including best practices and full workflow JSON generation |

---

## Which skill should I use?

**Just getting started?** → `pinecone:quickstart`

**Want to search an index you already have?**
- Integrated index (built-in embedding model) → `pinecone:query` (uses MCP)
- Any other index type → `pinecone:cli`

**Working with documents and Q&A?** → `pinecone:assistant`

**Building a full-text search index (BM25-style keyword/phrase matching, optionally combined with dense or sparse vectors)?** → `pinecone:full-text-search` (document-schema API, needs `pinecone` Python SDK ≥ 10.0.0)

**Building an n8n workflow with Pinecone (RAG pipeline, chat with docs)?** → `pinecone:n8n`

**Need to manage indexes, bulk upload vectors, or automate workflows?** → `pinecone:cli`

**Looking up API parameters or SDK usage?** → `pinecone:docs`

**Need to understand what MCP tools are available?** → `pinecone:mcp`

View saved version →

---
name: mcp
description: Reference for the Pinecone MCP server tools. Documents all available tools - list-indexes, describe-index, describe-index-stats, create-index-for-model, upsert-records, search-records, cascading-search, and rerank-documents. Use when an agent needs to understand what Pinecone MCP tools are available, how to use them, or what parameters they accept.
---

# Pinecone MCP Tools Reference

The Pinecone MCP server exposes the following tools to AI agents and IDEs. For setup and installation instructions, see the [MCP server guide](https://docs.pinecone.io/guides/operations/mcp-server#tools).

> **Key Limitation:** The Pinecone MCP only supports **integrated indexes** — indexes created with a built-in Pinecone embedding model. It does not work with standard indexes using external embedding models. For those, use the Pinecone CLI.

---

## `list-indexes`

List all indexes in the current Pinecone project.

---

## `describe-index`

Get configuration details for a specific index — cloud, region, dimension, metric, embedding model, field map, and status.

**Parameters:**
- `name` (required) — Index name

---

## `describe-index-stats`

Get statistics for an index including total record count and per-namespace breakdown.

**Parameters:**
- `name` (required) — Index name

---

## `create-index-for-model`

Create a new serverless index with an integrated embedding model. Pinecone handles embedding automatically — no external model needed.

**Parameters:**
- `name` (required) — Index name
- `cloud` (required) — `aws`, `gcp`, or `azure`
- `region` (required) — Cloud region (e.g. `us-east-1`)
- `embed.model` (required) — Embedding model: `llama-text-embed-v2`, `multilingual-e5-large`, or `pinecone-sparse-english-v0`
- `embed.fieldMap.text` (required) — The record field that contains text to embed (e.g. `chunk_text`)

---

## `upsert-records`

Insert or update records in an integrated index. Records are automatically embedded using the index's configured model.

**Parameters:**
- `name` (required) — Index name
- `namespace` (required) — Namespace to upsert into
- `records` (required) — Array of records. Each record must have an `id` or `_id` field and contain the text field specified in the index's `fieldMap`. Do not nest fields under `metadata` — put them directly on the record.

**Example record:**
```json
{ "_id": "rec1", "chunk_text": "The Eiffel Tower was built in 1889.", "category": "architecture" }
```

---

## `search-records`

Semantic text search against an integrated index. Pass plain text — the MCP embeds the query automatically using the index's model.

**Parameters:**
- `name` (required) — Index name
- `namespace` (required) — Namespace to search
- `query.inputs.text` (required) — The text query
- `query.topK` (required) — Number of results to return
- `query.filter` (optional) — Metadata filter using MongoDB-style operators (`$eq`, `$ne`, `$in`, `$gt`, `$gte`, `$lt`, `$lte`)
- `rerank.model` (optional) — Reranking model: `bge-reranker-v2-m3`, `cohere-rerank-3.5`, or `pinecone-rerank-v0`
- `rerank.rankFields` (optional) — Fields to rerank on (e.g. `["chunk_text"]`)
- `rerank.topN` (optional) — Number of results to return after reranking

---

## `cascading-search`

Search across multiple indexes simultaneously, then deduplicate and rerank results into a single ranked list.

**Parameters:**
- `indexes` (required) — Array of `{ name, namespace }` objects to search across
- `query.inputs.text` (required) — The text query
- `query.topK` (required) — Number of results to retrieve per index before reranking
- `rerank.model` (required) — Reranking model: `bge-reranker-v2-m3`, `cohere-rerank-3.5`, or `pinecone-rerank-v0`
- `rerank.rankFields` (required) — Fields to rerank on
- `rerank.topN` (optional) — Final number of results to return after reranking

---

## `rerank-documents`

Rerank a set of documents or records against a query without performing a vector search first.

**Parameters:**
- `model` (required) 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: n8n
description: Build n8n workflows using the Pinecone Assistant node or Pinecone Vector Store node. Use when building RAG pipelines, chat-with-docs workflows, configuring Pinecone nodes in n8n, troubleshooting Pinecone n8n nodes, or asking about best practices for Pinecone in n8n.
---

# Pinecone n8n Workflow Skill

Ask Codex for `pinecone:n8n` to invoke this skill.

This skill helps you build n8n workflows with Pinecone nodes following best practices. It covers two Pinecone nodes:
- **Pinecone Assistant** (`@pinecone-database/n8n-nodes-pinecone-assistant`) — recommended for most use cases
- **Pinecone Vector Store** (`@n8n/n8n-nodes-langchain.vectorStorePinecone`) — for advanced control

**Core rule:** Always use the node's built-in resources and operations. Never suggest using the HTTP node to call the Pinecone REST API directly.

---

## Step 1: Understand the user's scenario

Ask the user what they're trying to do:
- Build a new workflow from scratch
- Configure or understand a specific Pinecone node
- Debug a workflow that isn't working
- Review an existing workflow for best practices

---

## Step 2: Node selection (for new workflows and configuration questions)

Always present the Pinecone Assistant node as the recommended choice first. Do NOT skip this step based on your own inference about which node fits better — even if the use case mentions specific triggers (Google Drive, webhooks, etc.) or file types (text, markdown, PDF), those details do not determine which node to use.

**Only skip this step if:**
- The user explicitly names a specific node (e.g. "I want to use the Vector Store node", "help me set up pineconeAssistant")
- The user is debugging or configuring an existing workflow that already has a specific Pinecone node in it

**If the user has not named a node, always ask or recommend the Assistant node first.** If the user said "use defaults" or you cannot ask, default to the Pinecone Assistant node and proceed with the Assistant path.

Ask the user which node they want to use, presenting these two options:

**Pinecone Assistant (Recommended)**
- Fully managed RAG — Pinecone handles chunking, embedding, and indexing automatically
- Built-in citations with file names and URLs
- Simpler setup: no embedding model or text splitter needed in n8n
- Great for: document Q&A, chat with files, knowledge base search

**Pinecone Vector Store**
- Full control over embedding model, chunking strategy, and metadata
- Works with any embedding model (OpenAI, Cohere, HuggingFace, etc.)
- Required when: you need custom embeddings, have an existing Pinecone index, need metadata filtering, or need fine-grained control over chunking

---

## Pinecone Assistant Node — Best Practices and Workflow Generation

### Node package names
- File operations (upload, list, delete): `@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistant`
- Chat/retrieval as AI Agent tool: `@pinecone-database/n8n-nodes-pinecone-assistant.pineconeAssistantTool`

### Prerequisites
- Create a Pinecone Assistant in the Pinecone Console at https://app.pinecone.io/organizations/-/projects/-/assistant before running the workflow
- Set up a Pinecone credential in n8n with your API key

### Workflow architecture
The standard pattern is a two-phase workflow:

**Phase 1 — Ingestion** (run once or on a schedule):
```
Manual Trigger → Set file URLs → Split Out → HTTP Request (download) → Pinecone Assistant (uploadFile)
```

**Phase 2 — Chat**:
```
Chat Trigger → AI Agent ← Pinecone Assistant Tool (connected as ai_tool)
                        ← OpenAI Chat Model (connected as ai_languageModel)
```

### Key configuration rules
1. **assistantData parameter**: Always include BOTH `name` and `host` fields:
   ```json
   {"name": "your-assistant-name", "host": "https://your-assistant-host.pinecone.io"}
   ```
   Find your assistant's host in the Pinecone Console: open the assistant detail page and copy the host URL (format: `https://<region>-data.<subdoma

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: query
description: Query integrated indexes using text with Pinecone MCP. IMPORTANT - This skill ONLY works with integrated indexes (indexes with built-in Pinecone embedding models like multilingual-e5-large). For standard indexes or advanced vector operations, use the pinecone:cli skill instead. Requires PINECONE_API_KEY environment variable and Pinecone MCP server to be configured.
argument-hint: query [q] index [indexName] namespace [ns] topK [k] reranker [rerankModel]
---

# Pinecone Query Skill

Search for records in Pinecone integrated indexes using natural language text queries via the Pinecone MCP server.

Whenever this skill asks the user to choose between options, confirm a destructive step, or pick from a list, ask in plain prose, list the options, and wait for their answer before continuing.

## What is this skill for?

This skill provides a simple way to query **integrated indexes** (indexes with built-in Pinecone embedding models) using text queries. The MCP server automatically converts your text into embeddings and searches the index.

### Prerequisites

**Required:**
1. ✅ **Pinecone MCP server must be configured** - Check if MCP tools are available
2. ✅ **PINECONE_API_KEY environment variable must be set** - Get a free API key at https://app.pinecone.io/?sessionType=signup
3. ✅ **Index must be an integrated index** - Uses Pinecone embedding models (e.g., multilingual-e5-large, llama-text-embed-v2, pinecone-sparse-english-v0)

### When NOT to use this skill

**Use the pinecone:cli skill instead if:**
- ❌ Your index is a standard index (no integrated embedding model)
- ❌ You need to query with custom vector values (not text)
- ❌ You need advanced vector operations (fetch by ID, list vectors, bulk operations)
- ❌ Your index uses third-party embedding models (OpenAI, HuggingFace, Cohere)

**MCP Limitation**: The Pinecone MCP currently only supports integrated indexes. For all other use cases, use the pinecone:cli skill.

## How it works

Utilize Pinecone MCP's `search-records` tool to search for records within a specified Pinecone integrated index using a text query.

## Workflow

**IMPORTANT: Before proceeding, verify the Pinecone MCP tools are available.** If MCP tools are not accessible:
- Inform the user that the Pinecone MCP server needs to be configured
- Check if `PINECONE_API_KEY` environment variable is set
- Direct them to the MCP setup documentation or the `pinecone:help` skill

1. Parse the user's input for:
   - `query` (required): The text to search for.
   - `index` (required): The name of the Pinecone index to search.
   - `namespace` (optional): The namespace within the index.
   - `reranker` (optional): The reranking model to use for improved relevance.

2. If the user omits required arguments:
   - If only the index name is provided, use the `describe-index` tool to retrieve available namespaces and ask the user to choose.
   - If only a query is provided, use `list-indexes` to get available indexes, ask the user to pick one, then use `describe-index` for namespaces if needed.

3. Call the `search-records` tool with the gathered arguments to perform the search.

4. Format and display the returned results in a clear, readable table including field highlights (such as ID, score, and relevant metadata).

---

## Troubleshooting

**`PINECONE_API_KEY` is required.** Get a free key at https://app.pinecone.io/?sessionType=signup

If you get an access error, the key is likely missing. Ask the user to set it and restart their IDE or agent session:
- Codex CLI: run `export PINECONE_API_KEY="your-key"` in the shell you start `codex` from. The bundled MCP server reads it from Codex's environment.
- Codex Desktop on macOS: run `launchctl setenv PINECONE_API_KEY "your-key"`, then quit Codex fully and open it again.
- For scripts, you can also use `uv run --env-file .env scripts/...`.

**IMPORTANT** At the moment, the pinecone:query skill can only be used with integrated indexes, which use hosted Pin

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: quickstart
description: Interactive Pinecone quickstart for new developers. Choose between two paths - Database (create an integrated index, upsert data, and query using Pinecone MCP + Python) or Assistant (create a Pinecone Assistant for document Q&A). Use when a user wants to get started with Pinecone for the first time or wants a guided tour of Pinecone's tools.
---

# Pinecone Quickstart

Welcome! This skill walks you through your first Pinecone experience using the tools available to you. In this quickstart,
you will learn how to do a simple form of semantic search over some example data.

Whenever this skill asks the user to choose between options, confirm a destructive step, or pick from a list, ask in plain prose, list the options, and wait for their answer before continuing.

## Prerequisites

Before starting either path, verify the API key works by calling `list-indexes` via the Pinecone MCP. If it succeeds, proceed. If it fails, ask the user to set their key:

- Codex CLI: run `export PINECONE_API_KEY="your-key"` in the shell you start `codex` from. The bundled MCP server reads it from Codex's environment.
- Codex Desktop on macOS: run `launchctl setenv PINECONE_API_KEY "your-key"`, then quit Codex fully and open it again.
- For scripts, you can also use `uv run --env-file .env scripts/...`.

Then retry `list-indexes` to confirm.

## Step 0: Choose Your Path

Ask the user which path they want:

- **Database** – Build a vector search index. Best for developers who want to store and search embeddings. Uses the Pinecone MCP + a Python upsert script.
- **Assistant** – Build a document Q&A assistant. Best for users who want to upload files and ask questions with cited answers. No code required.

---

## Path A: Database Quickstart

For each step, explain to the user what will happen. An overview is here:

1. Check if MCP is set
2. Create an integrated index with MCP
3. Upsert sample data using the bundled script (9 sentences across productivity, health, and nature themes)
4. Run a semantic search query and explore further queries
5. Optionally try reranking
6. Offer the complete standalone script

### Step 1 – Verify MCP is Available

The prerequisite check already called `list-indexes`. If it succeeded, the MCP is working — proceed to Step 2.

If it failed because MCP tools were unavailable (not an auth error):
- Tell the user the MCP server needs to be configured
- Point them to: https://docs.pinecone.io/reference/tools/mcp

### Step 2 – Create an Integrated Index

Use the MCP `create-index-for-model` tool to create a serverless index with integrated embeddings:

```
name: quickstart-skills
cloud: aws
region: us-east-1
embed:
  model: llama-text-embed-v2
  fieldMap:
    text: chunk_text
```

**Explain to the user what's happening:**
- An *integrated index* uses a built-in Pinecone embedding model (`llama-text-embed-v2`)
- This means you send plain text and Pinecone handles the embedding automatically
- The `field_map` tells Pinecone which field in your records contains the text to embed

Wait for the index to become ready before proceeding. Waiting a few seconds is sufficient.

### Step 3 – Upsert Sample Data

Run the bundled upsert script to seed the index with sample records.

If `PINECONE_API_KEY` is set in the environment:
```bash
uv run scripts/upsert.py --index quickstart-skills
```

If using a `.env` file:
```bash
uv run --env-file .env scripts/upsert.py --index quickstart-skills
```

**Explain to the user what's happening:**
- The script uploads 9 sample records across three themes: **productivity** (getting work done), **health** (feeling unwell), and **nature** (outdoors/wildlife)
- The dataset is intentionally varied so semantic search can show its value — the queries below use completely different words than the records, but the right ones still surface
- Each record has an `_id`, a `chunk_text` field (the text that gets embedded), and a `category` field
- This is the same structure you'd use for 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.