Build a RAG Pipeline with Claude and a Vector Database

You will build a Retrieval-Augmented Generation (RAG) pipeline that uses Claude Code as the orchestrator and a vector database for semantic search. The pipeline ingests documents, stores their embeddings, retrieves relevant context for user queries, and generates answers with Claude. This tutorial takes approximately 90 minutes to complete, assuming you have a basic project structure and accounts ready.

Prerequisites

• A Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account with pre-paid credits
• A terminal or command prompt open in your project directory
• Node.js 18+ installed (for the vector database client and embedding script)
• A vector database service or local instance (the tutorial uses Pinecone as an example; alternatives include Weaviate, Qdrant, or Chroma)
• Basic familiarity with JavaScript/TypeScript and command-line operations
• Git installed (recommended for version control)
• jq installed (for parsing JSON in hook scripts, if you use hooks)

Step 1: Install Claude Code

Claude Code is the CLI tool that connects your terminal to Claude. You will use it to write code, run commands, and orchestrate the RAG pipeline.

macOS, Linux, WSL (Native Install)

Run the official install script:

curl -fsSL https://claude.ai/install.sh | bash

This installs Claude Code and sets up automatic background updates. After installation, confirm it works:

claude --version

Expected output: a version number followed by (Claude Code), for example 0.2.0 (Claude Code).

Windows (PowerShell)

Open PowerShell as Administrator and run:

irm https://claude.ai/install.ps1 | iex

If you see 'irm' is not recognized as an internal or external command, you are in CMD, not PowerShell. Switch to PowerShell (your prompt should show PS C:\).

Windows (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

If you see The token '&&' is not a valid statement separator, you are in PowerShell, not CMD. Switch to CMD (your prompt shows C:\ without PS).

Alternative: Homebrew (macOS)

brew install --cask claude-code

Homebrew installations do not auto-update. Run brew upgrade claude-code periodically to get the latest version.

Alternative: WinGet (Windows)

winget install Anthropic.ClaudeCode

WinGet installations also require manual updates: winget upgrade Anthropic.ClaudeCode.

Verify Installation

Run claude --version from any directory. If the command is not found, ensure the install directory is on your PATH. For the native install, the script typically adds Claude Code to ~/.local/bin or /usr/local/bin. Restart your terminal if needed.

Step 2: Log In to Your Account

Claude Code requires authentication. Start an interactive session:

claude

On first use, you will be prompted to log in. Follow the browser-based authentication flow. You can log in with:

• A Claude subscription (Pro, Max, Team, or Enterprise)
• A Claude Console account (API access with pre-paid credits). On first login, a "Claude Code" workspace is created automatically in the Console for cost tracking.
• Enterprise cloud providers: Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry
• A self-hosted Claude apps gateway (if your organization runs one)

Once authenticated, your credentials are stored locally. You will not need to log in again unless you switch accounts. To switch accounts later, type /login inside a running session.

Step 3: Set Up Your Project Structure

Create a new directory for the RAG pipeline project and navigate into it:

mkdir claude-rag-pipeline
cd claude-rag-pipeline
git init

Inside this directory, create the following structure:

claude-rag-pipeline/
├── documents/          # Place your source documents here
├── scripts/            # Embedding and retrieval scripts
├── .claude/            # Claude Code configuration (optional)
├──   └── settings.json  # Hook definitions (optional)
├── package.json
└── README.md

Initialize a Node.js project:

npm init -y

Install the Pinecone client (or your chosen vector database client) and the OpenAI embedding library (for generating embeddings; you can also use Anthropic's embedding model if available):

npm install @pinecone-database/pinecone openai dotenv

Create a .env file to store your API keys:

PINECONE_API_KEY=your-pinecone-api-key
PINECONE_ENVIRONMENT=your-pinecone-environment
PINECONE_INDEX_NAME=claude-rag-index
OPENAI_API_KEY=your-openai-api-key

Add .env to .gitignore:

echo ".env" >> .gitignore

Step 4: Understand the RAG Architecture

Before writing code, understand the three main stages of the RAG pipeline:

1. Ingestion: Documents are split into chunks, each chunk is converted to a vector embedding, and the embeddings are stored in a vector database along with the original text.
2. Retrieval: When a user asks a question, the question is converted to an embedding, and the vector database returns the most semantically similar chunks.
3. Generation: The retrieved chunks are injected into a prompt to Claude, which generates a grounded answer.

Claude Code will orchestrate these steps. You can run each step as a one-off task or build a script that Claude executes.

Step 5: Write the Embedding Script

Create a file scripts/embed.js that reads documents from the documents/ folder, splits them into chunks, generates embeddings, and upserts them into Pinecone.

// scripts/embed.js
require('dotenv').config();
const fs = require('fs');
const path = require('path');
const { Pinecone } = require('@pinecone-database/pinecone');
const { OpenAI } = require('openai');

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const pinecone = new Pinecone({
  apiKey: process.env.PINECONE_API_KEY,
  environment: process.env.PINECONE_ENVIRONMENT,
});

const INDEX_NAME = process.env.PINECONE_INDEX_NAME;
const CHUNK_SIZE = 500; // characters per chunk
const CHUNK_OVERLAP = 50; // overlap between chunks

// Split text into overlapping chunks
function chunkText(text, size, overlap) {
  const chunks = [];
  let start = 0;
  while (start < text.length) {
    const end = Math.min(start + size, text.length);
    chunks.push(text.slice(start, end));
    start += size - overlap;
  }
  return chunks;
}

// Generate embedding for a single text string
async function getEmbedding(text) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-ada-002',
    input: text,
  });
  return response.data[0].embedding;
}

async function main() {
  const docsDir = path.join(__dirname, '..', 'documents');
  const files = fs.readdirSync(docsDir).filter(f => f.endsWith('.txt') || f.endsWith('.md'));

  if (files.length === 0) {
    console.error('No .txt or .md files found in documents/ directory.');
    process.exit(1);
  }

  const index = pinecone.Index(INDEX_NAME);
  let totalVectors = 0;

  for (const file of files) {
    const filePath = path.join(docsDir, file);
    const content = fs.readFileSync(filePath, 'utf-8');
    const chunks = chunkText(content, CHUNK_SIZE, CHUNK_OVERLAP);

    console.log(`Processing ${file}: ${chunks.length} chunks`);

    for (let i = 0; i < chunks.length; i++) {
      const chunk = chunks[i];
      const embedding = await getEmbedding(chunk);
      const id = `${file}-chunk-${i}`;

      await index.upsert([{
        id,
        values: embedding,
        metadata: { text: chunk, source: file, chunkIndex: i },
      }]);

      totalVectors++;
      console.log(`  Upserted chunk ${i + 1}/${chunks.length}`);
    }
  }

  console.log(`Done. Total vectors upserted: ${totalVectors}`);
}

main().catch(console.error);

This script:

• Reads all .txt and .md files from the documents/ directory
• Splits each file into overlapping chunks of 500 characters with 50-character overlap (adjust these values based on your document length and retrieval needs)
• Generates an embedding for each chunk using OpenAI's text-embedding-ada-002 model
• Upserts each vector into the Pinecone index with metadata (the original text, source file, and chunk index)

Run the script with Claude Code. From your project root, start a Claude Code session:

claude

Then ask Claude to run the embedding script:

run the script scripts/embed.js

Claude will execute the command and show you the output. If you prefer to run it directly from the terminal:

node scripts/embed.js

Expected output: a series of log lines showing each file being processed, each chunk upserted, and a final summary: Done. Total vectors upserted: N.

Step 6: Write the Retrieval and Generation Script

Create scripts/query.js that takes a user question, retrieves relevant chunks from Pinecone, and generates an answer using Claude Code's built-in capabilities. Since Claude Code can execute shell commands and read files, you can build a script that Claude orchestrates.

// scripts/query.js
require('dotenv').config();
const { Pinecone } = require('@pinecone-database/pinecone');
const { OpenAI } = require('openai');

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const pinecone = new Pinecone({
  apiKey: process.env.PINECONE_API_KEY,
  environment: process.env.PINECONE_ENVIRONMENT,
});

const INDEX_NAME = process.env.PINECONE_INDEX_NAME;

async function retrieveRelevantChunks(question, topK = 3) {
  const questionEmbedding = await openai.embeddings.create({
    model: 'text-embedding-ada-002',
    input: question,
  });

  const index = pinecone.Index(INDEX_NAME);
  const queryResponse = await index.query({
    vector: questionEmbedding.data[0].embedding,
    topK,
    includeMetadata: true,
  });

  return queryResponse.matches.map(match => ({
    text: match.metadata.text,
    score: match.score,
    source: match.metadata.source,
  }));
}

async function main() {
  const question = process.argv[2];
  if (!question) {
    console.error('Usage: node scripts/query.js "<your question>"');
    process.exit(1);
  }

  console.log(`Question: ${question}`);
  console.log('Retrieving relevant chunks...');

  const chunks = await retrieveRelevantChunks(question);

  if (chunks.length === 0) {
    console.log('No relevant chunks found.');
    process.exit(0);
  }

  console.log(`Found ${chunks.length} relevant chunks:\n`);
  chunks.forEach((chunk, i) => {
    console.log(`[${i + 1}] (score: ${chunk.score.toFixed(4)}) from ${chunk.source}`);
    console.log(chunk.text);
    console.log('---');
  });

  // Output JSON for Claude to consume
  const output = {
    question,
    context: chunks.map(c => c.text).join('\n\n'),
  };
  console.log('\n---CONTEXT_JSON_START---');
  console.log(JSON.stringify(output));
  console.log('---CONTEXT_JSON_END---');
}

main().catch(console.error);

This script:

• Takes a question as a command-line argument
• Generates an embedding for the question
• Queries Pinecone for the top 3 most similar chunks (adjust topK as needed)
• Prints the chunks with similarity scores and source information
• Outputs a JSON block that Claude Code can parse to get the context for generation

Test the retrieval script with a sample question. From your terminal:

node scripts/query.js "What is the main topic of the documents?"

Expected output: the script prints each retrieved chunk with its score and source, followed by a JSON block between ---CONTEXT_JSON_START--- and ---CONTEXT_JSON_END---.