---

name: vector description: > Create embeddings, run semantic search, and manage vector collections across major providers. USE WHEN: the user says "create embeddings", "set up vector search", "implement RAG retrieval", "embed this document", "search my vectors", "which vector DB should I use", or "set up a vector database". DON'T USE WHEN: the user wants traditional full-text search without embeddings, relational database queries, or non-vector data storage. OUTPUTS: configured vector collections, embedded document chunks with metadata, ranked similarity search results with scores and source citations, and collection status reports.

Vector

Version: 1.1.0 Price: Free Type: Skill

Description

Integration skill for vector databases — the memory layer your agent is missing. Vector teaches your OpenClaw agent how to create embeddings, store them, query them semantically, and manage collections across the major providers: Pinecone, Weaviate, Qdrant, Chroma, and pgvector. Instead of guessing at API parameters or writing broken similarity searches, your agent knows the right calls, the right defaults, and the right patterns from the start.

Covers the full lifecycle: embed, store, search, update, delete. Includes prompting patterns for chunking strategies, metadata filtering, hybrid search, and RAG retrieval — the stuff that takes three Stack Overflow tabs and a blog post to get right on your own.

Prerequisites

• At least one vector database account or local instance:
  • Pinecone: API key from pinecone.io dashboard
  • Weaviate: Self-hosted instance or Weaviate Cloud API key
  • Qdrant: Self-hosted instance or Qdrant Cloud API key
  • Chroma: Local install (pip install chromadb) or Chroma Cloud
  • pgvector: PostgreSQL 15+ with vector extension enabled
• An embedding provider (one of):
  • OPENAI_API_KEY for OpenAI embeddings (text-embedding-3-small, text-embedding-3-large)
  • VOYAGE_API_KEY for Voyage AI embeddings
  • COHERE_API_KEY for Cohere embeddings
  • Any local embedding model (Ollama, sentence-transformers)
• Environment variables set for your chosen provider(s)

Setup

1. Copy SKILL.md into your OpenClaw skills directory (e.g. skills/vector/SKILL.md)
2. Set environment variables for your vector DB and embedding provider
3. Reload OpenClaw
4. Test with: "Show my vector database status"

Commands

Setup & Config

• "Set up a vector database for my project"
• "Which vector DB should I use?"
• "Configure Pinecone for this project"
• "Show my vector database status"

Embedding

• "Embed this document into my vector store"
• "Chunk and embed [file or directory]"
• "What embedding model should I use?"
• "Re-embed my collection with a new model"

Search & Retrieval

• "Search my vectors for [query]"
• "Find similar documents to [text]"
• "Run a hybrid search for [query] with metadata filter [filter]"
• "What are the closest matches to this content?"

Collection Management

• "Create a new collection called [name]"
• "List my vector collections"
• "How many vectors are in [collection]?"
• "Delete collection [name]"
• "Show collection stats"

RAG Patterns

• "Set up RAG retrieval for [use case]"
• "Build a retrieval pipeline for my docs"
• "Optimize my RAG chunking strategy"
• "Test retrieval quality for [query]"

Provider Reference

Pinecone

| Operation | Endpoint | Method | |-----------|----------|--------| | List indexes | GET /indexes | REST | | Create index | POST /indexes | REST | | Upsert vectors | POST /vectors/upsert | REST | | Query | POST /query | REST | | Delete vectors | POST /vectors/delete | REST | | Describe index stats | GET /describe_index_stats | REST |

Base URL: https://{index-name}-{project-id}.svc.{environment}.pinecone.io Auth: Api-Key: ${PINECONE_API_KEY} Control plane: https://api.pinecone.io

Defaults:

• Metric: cosine
• Pod type: s1.x1 (starter) or serverless
• Dimension: must match embedding model (1536 for text-embedding-3-small, 3072 for text-embedding-3-large)

Gotchas:

• Upserts are eventually consistent — queries may not reflect changes immediately
• Metadata values must be strings, numbers, booleans, or lists of strings
• Namespace is optional but recommended for multi-tenant isolation
• Free tier: 1 index, 100K vectors max
• Serverless indexes don't support delete by metadata filter — delete by ID only

Weaviate

| Operation | Endpoint | Method | |-----------|----------|--------| | Create class | POST /v1/schema | REST | | Add object | POST /v1/objects | REST | | Batch import | POST /v1/batch/objects | REST | | Vector search | POST /v1/graphql | GraphQL | | Delete class | DELETE /v1/schema/{class} | REST |

Base URL: http://localhost:8080 (self-hosted) or https://{cluster}.weaviate.network Auth: Authorization: Bearer ${WEAVIATE_API_KEY} (cloud) or none (local)

Defaults:

• Distance metric: cosine
• Vectorizer: text2vec-openai (requires OPENAI_API_KEY on the Weaviate side)
• HNSW index: ef=256, maxConnections=64

Gotchas:

• Class names must be PascalCase and start with a capital letter
• Property names must be camelCase
• Weaviate can auto-vectorize on insert if a vectorizer module is configured
• Batch import is dramatically faster than single inserts — always batch
• GraphQL queries use nearText (text input) or nearVector (raw vector)

Qdrant

| Operation | Endpoint | Method | |-----------|----------|--------| | Create collection | PUT /collections/{name} | REST | | Upsert points | PUT /collections/{name}/points | REST | | Search | POST /collections/{name}/points/search | REST | | Scroll | POST /collections/{name}/points/scroll | REST | | Delete collection | DELETE /collections/{name} | REST | | Collection info | GET /collections/{name} | REST |

Base URL: http://localhost:6333 (self-hosted) or https://{cluster}.qdrant.io Auth: api-key: ${QDRANT_API_KEY}

Defaults:

• Distance: Cosine
• On-disk payload index: enabled
• HNSW: m=16, ef_construct=100

Gotchas:

• Point IDs can be integers or UUIDs — pick one and stay consistent
• Payload filtering happens at query time and supports complex boolean expressions
• Quantization (scalar or product) significantly reduces memory for large collections
• Batch upsert limit: 100 points per request recommended
• Scroll endpoint is for iteration, not similarity search

Chroma

| Operation | Method | |-----------|--------| | Create collection | client.create_collection(name, metadata) | | Add documents | collection.add(ids, documents, metadatas, embeddings) | | Query | collection.query(query_texts, n_results, where) | | Update | collection.update(ids, documents, metadatas, embeddings) | | Delete | collection.delete(ids, where) | | Count | collection.count() |

Connection: chromadb.Client() (in-memory), chromadb.PersistentClient(path) (local), or chromadb.HttpClient(host, port) (server)

Defaults:

• Embedding function: all-MiniLM-L6-v2 (384 dimensions) via sentence-transformers
• Distance: l2 (use cosine for most text applications — set via collection metadata)
• Storage: in-memory unless PersistentClient is used

Gotchas:

• Chroma auto-embeds if you pass documents without embeddings — uses the default model
• If you pass your own embeddings, dimensions must be consistent across all adds
• where filters use a MongoDB-like syntax: {"field": {"$eq": "value"}}
• Collections are isolated — no cross-collection queries
• In-memory client loses data on restart — use PersistentClient for anything that matters

pgvector

| Operation | SQL | |-----------|-----| | Enable extension | CREATE EXTENSION vector | | Create table | CREATE TABLE items (id serial, embedding vector(1536), metadata jsonb) | | Insert | INSERT INTO items (embedding, metadata) VALUES ($1, $2) | | Similarity search | SELECT * FROM items ORDER BY embedding <=> $1 LIMIT 10 | | Exact search | SELECT * FROM items ORDER BY embedding <-> $1 LIMIT 10 | | Create index | CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100) |

Connection: Standard PostgreSQL connection string Auth: PostgreSQL credentials

Operators:

• <=> — cosine distance (most common for text)
• <-> — L2 (Euclidean) distance
• <#> — inner product (negative, for max inner product search)

Gotchas:

• Vector dimension is fixed per column — you can't mix 1536 and 3072 in the same column
• IVFFlat indexes require lists parameter — rule of thumb: sqrt(num_rows)
• HNSW indexes (USING hnsw) are slower to build but faster to query — prefer for production
• Always run ANALYZE after bulk inserts to update index statistics
• Without an index, queries do exact brute-force search — fine for <100K rows, slow after

Embedding Model Reference

| Provider | Model | Dimensions | Max Tokens | Best For | |----------|-------|-----------|------------|----------| | OpenAI | text-embedding-3-small | 1536 | 8191 | General purpose, cost-effective | | OpenAI | text-embedding-3-large | 3072 | 8191 | Highest quality, larger storage | | Voyage AI | voyage-3 | 1024 | 32000 | Code and technical content | | Voyage AI | voyage-3-lite | 512 | 32000 | Fast, low-cost | | Cohere | embed-english-v3.0 | 1024 | 512 | English text, Cohere ecosystem | | Cohere | embed-multilingual-v3.0 | 1024 | 512 | Multi-language support | | Local | all-MiniLM-L6-v2 | 384 | 256 | Free, fast, offline | | Local | bge-large-en-v1.5 | 1024 | 512 | Free, high quality |

Rule of thumb: Start with text-embedding-3-small unless you need multilingual (Cohere), code-specific (Voyage), or fully offline (local models).

Chunking Strategies

| Strategy | Chunk Size | Overlap | Best For | |----------|-----------|---------|----------| | Fixed | 512 tokens | 50 tokens | General documents, quick setup | | Sentence | 3-5 sentences | 1 sentence | Conversational content, Q&A | | Paragraph | Natural breaks | None | Well-structured documents | | Recursive | 1000 tokens | 200 tokens | Long-form content, books | | Semantic | Variable | None | Research papers, mixed content | | Code | Function/class level | None | Source code, technical docs |

Defaults this skill uses:

• Chunk size: 512 tokens
• Overlap: 50 tokens (10%)
• Separator: paragraph breaks first, then sentence breaks, then token count
• Metadata: source file, chunk index, total chunks, character offset

Workflow

Set Up a New Vector Store

1. Ask: Provider — "Which vector DB? Pinecone, Weaviate, Qdrant, Chroma, or pgvector?"
   • If unsure, recommend based on use case:
     • Prototyping/local: Chroma
     • Production SaaS: Pinecone or Qdrant Cloud
     • Self-hosted control: Weaviate or Qdrant
     • Already using PostgreSQL: pgvector
2. Ask: Embedding model — "Which embedding provider?"
   • Default: OpenAI text-embedding-3-small if OPENAI_API_KEY is set
3. Validate — Confirm API keys are set, test connectivity
4. Create collection/index — Use provider-specific API with correct dimensions
5. Report — Collection name, provider, dimensions, distance metric, ready to use

Embed Documents

1. Receive source — File path, directory, or raw text
2. Chunk — Apply chunking strategy (default: 512 tokens, 50 overlap)
3. Show plan — "Found 47 chunks across 3 files. Estimated cost: ~$0.002. Proceed?"
4. Embed — Call embedding API in batches (max 100 per request for OpenAI)
5. Upsert — Store vectors with metadata (source, chunk index, content preview)
6. Report — Vectors stored, collection size, cost

Search

1. Receive query — Natural language question or text
2. Embed query — Same model used for the collection
3. Search — Top-K similarity search (default: K=5)
4. Apply filters — Metadata filters if specified
5. Return results — Ranked by similarity score with content preview and metadata

RAG Retrieval Pipeline

1. Receive query — User question
2. Retrieve — Semantic search, top K=5 (configurable)
3. Re-rank — Optional: re-rank results by relevance if Cohere re-ranker is available
4. Format context — Assemble retrieved chunks into a context block with source citations
5. Return — Context block ready for LLM consumption, with sources listed

Output Format

Search Results

=== VECTOR SEARCH RESULTS ===
Collection:  project-docs
Query:       "how does authentication work?"
Provider:    Pinecone (serverless)
Results:     5 of 1,247 vectors

#1  Score: 0.94  |  Source: docs/auth.md (chunk 3/8)
    "Authentication uses JWT tokens issued by the /auth/login endpoint.
    Tokens expire after 24 hours and must be refreshed via /auth/refresh..."

#2  Score: 0.89  |  Source: docs/api-reference.md (chunk 12/34)
    "All API endpoints except /auth/login and /health require a valid
    Bearer token in the Authorization header..."

#3  Score: 0.85  |  Source: src/middleware/auth.ts (chunk 1/3)
    "The authMiddleware function extracts the JWT from the Authorization
    header, validates it against the signing key, and attaches..."

#4  Score: 0.79  |  Source: docs/setup.md (chunk 5/12)
    "Set AUTH_SECRET in your .env file. This is the signing key for
    JWT tokens. Generate with: openssl rand -base64 32..."

#5  Score: 0.71  |  Source: README.md (chunk 2/6)
    "Authentication is required for all write operations. See
    docs/auth.md for the full authentication flow..."

Collection Status

=== VECTOR STORE STATUS ===
Provider:    Qdrant (self-hosted)
Endpoint:    http://localhost:6333
Collections: 3

  project-docs     1,247 vectors   1536d   cosine   42MB
  code-index       3,891 vectors   1536d   cosine   128MB
  chat-history       156 vectors   1536d   cosine   5MB

Embedding:   OpenAI text-embedding-3-small (1536d)
Total:       5,294 vectors across 3 collections

Guardrails

• Never stores API keys in vectors or metadata. If a document contains credentials, strip them before embedding. Warn the user.
• Never embeds without showing the plan first. Always display chunk count, estimated cost, and target collection before upserting. Require confirmation for collections with >100 existing vectors.
• Never deletes a collection without explicit confirmation. Deletion is permanent. Show the collection name, vector count, and ask for "yes" or "delete it."
• Never sends document content to unintended endpoints. Embedding API calls go only to the configured provider. Vector upserts go only to the configured vector database. No cross-provider leaks.
• Never mixes embedding dimensions. If a collection uses 1536-dimension vectors, reject attempts to upsert 3072-dimension vectors. Mismatched dimensions corrupt the index.
• Cost transparency. Always estimate embedding costs before processing. OpenAI: ~$0.02 per 1M tokens for text-embedding-3-small. Show the estimate and require confirmation for jobs over $0.10.
• Read-only search. Query operations never modify the collection. Search results are returned, not stored or forwarded.

Why Free?

Vector databases are the memory layer that makes AI agents actually useful. Getting the integration right — chunking, embedding, indexing, querying — shouldn't cost extra on top of the database bill you're already paying.