Pinecone

# Pinecone API Skill

## Quick Start
Pinecone stores vector embeddings for fast similarity search, serving as the memory layer for RAG (Retrieval-Augmented Generation) applications.

```bash
npm install @pinecone-database/pinecone
```

## Common Workflows
### RAG (Retrieval-Augmented Generation)
1. Convert a user query to a vector embedding (e.g., using OpenAI `text-embedding-3-small`).
2. Query Pinecone for the top 5 most similar vectors.
3. Inject the retrieved metadata text into the LLM system prompt.

## Production Patterns
### Metadata Filtering
Do not rely entirely on vector similarity if exact categorical constraints exist. Attach metadata (e.g., `tenant_id`, `document_type`) to your vectors and use Pinecone's filter syntax to restrict the search space before calculating cosine similarity.

## Error Recovery
Handle rate limits (`HTTP 429`) and index initialization delays. Serverless indexes scale automatically but may temporarily reject massive, sudden bursts of write operations. Use backoff retries for upserts.

## Security Notes
Pinecone Serverless environments do not support VPC peering. Ensure data is encrypted at rest and secure your API keys tightly. Segment tenant data utilizing namespaces or strict metadata filters.

## Performance Considerations
Vector search latency scales with dimensionality and index size. Batch your upsert operations in chunks of 100-500 vectors. Query latency is typically <50ms; if slower, ensure you are querying the correct geographic region.

## Testing Guidance
Mock the Pinecone client in unit tests. For integration tests, utilize an isolated `namespace` (e.g., `test_run_123`) to prevent test data from contaminating the primary index, and delete the namespace post-test.

## Troubleshooting
If similarity search returns irrelevant results, verify that the embedding model used for the query is exactly the same model used during the upsert phase. Mismatched dimensions or models will produce garbage results.

## References
- [API Reference](https://docs.pinecone.io/reference/api/introduction)

## Related Skills
- [OpenAI](/skills/openai)
- [Anthropic](/skills/anthropic)
- [Upstash](/skills/upstash)

## Why use this skill
Use this when your agent works with **pinecone** — structured patterns beat pasted docs and prevent common hallucinations.

## AI pitfalls
- Inventing column names or schema fields
- Using deprecated driver methods or wrong connection strings
- Omitting connection pooling or transaction boundaries

## Production checklist
- [ ] Migrations version-controlled and applied via CI
- [ ] Connection limits and pooling configured
- [ ] Backups and restore procedure documented

## Related skills
- [`openai`](../openai/SKILL.md) — related to
- [`anthropic`](../anthropic/SKILL.md) — related to
- [`upstash`](../upstash/SKILL.md) — related to

---
> **Last Verified:** 2026-07-02