Zvec Agent Skills

Official AI Agent skills for building with Zvec vector database.

Zvec Assistant is an AI Agent Skill that provides developers with complete technical guidance for the Zvec vector database. It supports Python and Node.js development environments, covering comprehensive documentation from basic concepts to advanced usage.

What is Zvec?

Zvec is an open-source, high-performance, lightweight in-process vector database built on Alibaba's Proxima engine. No server or external infrastructure required, ready to use out of the box.

Key Features:

• ⚡ Sub-millisecond search latency, supporting billions of vectors
• 🧩 Single package installation, zero configuration, ready to use
• ✨ Supports dense vectors + sparse vectors, native multi-vector queries
• 🎯 Hybrid search: semantic similarity + structured filtering
• 📦 Pure in-process library, runs anywhere

Use Cases

• RAG Systems: Document retrieval capabilities for LLM applications
• Semantic Search: Intelligent search based on vector similarity
• Recommendation Systems: Similar product/content recommendations
• Multimodal Search: Joint image + text search
• Keyword + Semantic Hybrid Search: BM25 + vector embeddings

Installation

Install as AI Agent Skill

npx skills add github:zvec-ai/zvec-agent-skills --skill "zvec"

Install Zvec Package

Choose installation based on your development language:

Python:

pip install zvec

Node.js:

npm install @zvec/zvec

Quick Start

Python

import zvec

# Create Collection
schema = zvec.CollectionSchema(
    name="my_collection",
    fields=[
        zvec.FieldSchema(name="title", data_type=zvec.DataType.STRING),
    ],
    vectors=[
        zvec.VectorSchema(
            name="embedding",
            data_type=zvec.DataType.VECTOR_FP32,
            dimension=768,
            index_param=zvec.HnswIndexParam(
                metric_type=zvec.MetricType.COSINE
            ),
        ),
    ],
)

collection = zvec.create_and_open("./my_data", schema)

# Insert document
collection.upsert(zvec.Doc(
    id="doc_1",
    vectors={"embedding": [0.1] * 768},
    fields={"title": "Hello World"},
))

# Search
results = collection.query(
    vectors=zvec.VectorQuery(
        field_name="embedding",
        vector=[0.1] * 768,
    ),
    topk=10,
)

Node.js

import { ZVecCreateAndOpen, ZVecCollectionSchema, ZVecFieldSchema, ZVecVectorSchema, ZVecDataType, ZVecHnswIndexParams, ZVecMetricType } from "@zvec/zvec";

const schema = new ZVecCollectionSchema({
  name: "my_collection",
  fields: [new ZVecFieldSchema({ name: "title", dataType: ZVecDataType.STRING })],
  vectors: [new ZVecVectorSchema({
    name: "embedding",
    dataType: ZVecDataType.VECTOR_FP32,
    dimension: 768,
    indexParams: new ZVecHnswIndexParams({ metricType: ZVecMetricType.COSINE }),
  })],
});

const collection = ZVecCreateAndOpen("./my_data", schema);

Project Structure

zvec-agent-skills/
├── skills/                       # Built skill output directory
│   └── zvec/
│       ├── SKILL.md              # Skill main document
│       ├── quick-start/          # Quick start
│       │   ├── python.md
│       │   └── typescript.md
│       ├── collection-management/# Collection management
│       ├── data-operations/      # Data operations
│       ├── vector-search/        # Vector search
│       ├── rag-system/           # RAG system
│       ├── hybrid-search/        # Hybrid search
│       ├── multimodal-search/    # Multimodal search
│       ├── data-model.md         # Data model
│       ├── api-cheatsheet.md     # API cheatsheet
│       └── troubleshooting.md    # Troubleshooting
├── src/                          # Source code directory
│   └── zvec/
│       ├── SKILL.md              # Skill main document source
│       ├── templates/            # Markdown templates
│       ├── code/                 # Code examples
│       │   ├── python/
│       │   └── typescript/
│       └── general/              # General documents
├── scripts/                      # Build scripts
│   └── build-skills.ts           # Skill build script
├── package.json                  # Project configuration
├── CLAUDE.md                     # Developer guide
└── README.md                     # Project readme

Build

This project uses a build system to convert source code into distributable skills.

# Install dependencies
bun install

# Build skills
bun run build

The built output is located in the skills/zvec/ directory.

Usage Scenarios

RAG Document Retrieval

Build intelligent document retrieval systems for LLM applications:

I want to build a RAG system with Python and Zvec for technical support knowledge base.
Documents are in Markdown format and need semantic search support.

E-commerce Product Search

Implement semantic product search with filtering capabilities:

I need to implement e-commerce product search in a Node.js project:
- Support semantic search by product name and description
- Filter by price, category, and brand
- Support multimodal (image + text) search

Log Troubleshooting Knowledge Base

Store and search system log failure cases:

I want to use Zvec to store system log failure cases and support semantic search for similar issues.
Using Python with about 100k data entries.

Available Topics

Python

• Quick Start - Quick start with Zvec Python API
• Collection Management - Create, open, and manage Collections
• Data Operations - Insert, update, and delete documents
• Vector Search - Single-vector, multi-vector, and hybrid search
• RAG System - Build document retrieval system
• Hybrid Search - Vector similarity + scalar filtering
• Multimodal Search - Image + text joint search

Node.js

• Quick Start - Quick start with Zvec Node.js API
• Collection Management - Create, open, and manage Collections
• Data Operations - Insert, update, and delete documents
• Vector Search - Single-vector, multi-vector, and hybrid search
• RAG System - Build document retrieval system
• Hybrid Search - Vector similarity + scalar filtering
• Multimodal Search - Image + text joint search

General

• Data Model - Zvec data model overview
• API Cheatsheet - Python & Node.js API quick reference
• Troubleshooting - Common issues and solutions

Usage Examples

Hybrid Search (Vector + Filter)

# Search similar products while filtering by price and stock
results = collection.query(
    vectors=zvec.VectorQuery(
        field_name="description_vec",
        vector=query_vector,
    ),
    filter="price >= 100 AND price <= 500 AND in_stock == true",
    topk=10,
)

Multi-Vector Search

# Search using both image and text vectors
results = collection.query(
    vectors=[
        zvec.VectorQuery(field_name="image_vec", vector=image_query),
        zvec.VectorQuery(field_name="text_vec", vector=text_query),
    ],
    reranker=zvec.WeightedReRanker(
        topn=10,
        metric=zvec.MetricType.COSINE,
        weights={"image_vec": 0.7, "text_vec": 0.3},
    ),
)

Best Practices

For detailed usage guidelines in Claude Code and Claude Desktop, see CLAUDE.md.

Quick Tips

• Specify your development language when asking questions (Python or Node.js)
• Describe your use case for more targeted recommendations
• Ask for architectural advice when designing your schema and indexing strategy

Contributing

Contributions are welcome! Please check CONTRIBUTING.md to learn how to participate.

License

This project is licensed under the Apache License 2.0.

Related Links

• GitHub Repository
• Zvec Official Documentation
• Zvec Python API
• Zvec Node.js API
• Zvec GitHub