Pinecone Semantic Database

RitoSwap uses Pinecone as the vector store for memes, rhymes, GIFs, and images. It is the backing store for the pinecone_search MCP tool and the agent-rap-verse resource gathering phase.

⚠️

dapp/app/config/pinecone.config.ts is server-only and throws if imported in client code.

Code Map

Configuration

Key	Purpose	Notes
`PINECONE_API_KEY`	Pinecone API key	Required for `pineconeConfig.isConfigured` and all tools/scripts.
`PINECONE_INDEX_1_NAME`	Primary index name	Used by the CLI scripts under `dapp/pinecone`.
`PINECONE_INDEX_1_NAMESPACES`	Comma-separated namespaces	Validates tool input and controls the `seed.ts` namespace allow-list.
`PINECONE_INDEX_2_NAME`/`PINECONE_INDEX_2_NAMESPACES`	Optional additional index	Parsed by `pinecone.config.ts`. The CLI scripts target index 1 only.
`PINECONE_INDEX_3_NAME`/`PINECONE_INDEX_3_NAMESPACES`	Optional additional index	Parsed by `pinecone.config.ts`. The CLI scripts target index 1 only.
`PINECONE_CLOUD`/`PINECONE_REGION`	Index creation spec	Consumed by `create-index.ts` (defaults to aws/us-east-1).

Example .env snippet:


PINECONE_API_KEY=your-key-here
PINECONE_INDEX_1_NAME=rito-search
PINECONE_INDEX_1_NAMESPACES=gifs,rito-pics,ritorhymes
PINECONE_CLOUD=aws
PINECONE_REGION=us-east-1

Multi-Index Note

Current usage seeds and queries only PINECONE_INDEX_1_*. The runtime config can load index 2/3 if those env vars are set, but the dapp/pinecone scripts only target index 1 today.

Index + Namespace Strategy

A single index can host multiple datasets via namespaces, keeping the schema consistent while letting you isolate content.
The JSON datasets in dapp/pinecone are typically seeded into matching namespaces (for example gifs, rito-pics, ritorhymes).
pineconeConfig and seed.ts both validate namespaces against PINECONE_INDEX_1_NAMESPACES, so keep the list in sync with whatever you seed.

Seeding Workflow

Run these commands from dapp/ so the script paths resolve.

1. Create the index

create-index.ts creates a serverless index sized for multilingual-e5-large (1024 dimensions, cosine).


npx tsx pinecone/create-index.ts

2. Seed a namespace

seed.ts embeds text fields with inputType passage and upserts in batches. The namespace must be listed in PINECONE_INDEX_1_NAMESPACES or the script exits.


npx tsx pinecone/seed.ts pinecone/gifs.json gifs

3. Check stats

Use check-stats.ts to confirm vector counts and namespace health.


npx tsx pinecone/check-stats.ts

4. Clear a namespace (destructive)

clear-namespace.ts deletes every vector in the namespace.


npx tsx pinecone/clear-namespace.ts gifs

⚠️

clear-namespace.ts is destructive. It will remove every vector in the target namespace.

Dataset Format

seed.ts expects a JSON array with id, text, and optional metadata. Metadata is sanitized (arrays become string arrays, objects are JSON stringified) and the text field is also attached to metadata for easy retrieval.


[
  {
    "id": "gif_0001",
    "text": "woman makes a flamethrower with a lighter by blowing the flame",
    "metadata": {
      "url": "https://media1.tenor.com/m/...",
      "tags": ["flame", "lighter"],
      "mood": "intense"
    }
  }
]

Runtime Integration

dapp/app/config/pinecone.config.ts parses env, validates index/namespace combos, and blocks client-side imports.
dapp/app/lib/mcp/tools/pinecone-search.ts builds a dynamic input schema from pineconeConfig and uses multilingual-e5-large for query embeddings.
pinecone_search accepts an optional filter object for metadata filtering, passed directly to Pinecone queries.
dapp/app/lib/mcp/tools/index.ts registers pinecone_search only when pineconeConfig.isConfigured is true.
agent-rap-verse calls pinecone_search during the gathering phase to pull memes, images, and rhyme samples.
When the namespace is gifs (case-insensitive), pinecone_search emits <gif> tags so the UI can render the chosen asset.

MCP Tool: pinecone_search GIF Renderer Images & SVGs

Troubleshooting

Pinecone not configured at boot means the API key is missing or no index names were provided.
Index "..." not found or Namespace "..." not found usually means the env list does not match what you seeded.
If results are empty, run check-stats.ts to confirm vectors exist and confirm your namespace name.