Skip to main content

​
Quickstart

This guide walks you through getting an API key, installing the SDK, storing your first vector, querying it back, and verifying it on-chain. The entire flow takes under 5 minutes.

​
Step 1 - Get your API key

Sign up at app.veclabs.xyz to get your free API key. Your key looks like: 
vl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
The free tier includes 100K vectors at no cost. No credit card required.

​
Step 2 - Install the SDK

npm install @veclabs/solvec

​
Step 3 - Initialize with your API key

import { SolVec } from '@veclabs/solvec';

const sv = new SolVec({ apiKey: 'vl_live_...' });
const collection = sv.collection('my-collection', { dimensions: 1536 });
Hosted mode (with an API key) is the recommended way to get started. VecLabs manages your Solana wallet, Shadow Drive storage, and Merkle root posting automatically. See “Self-hosting” at the bottom of this page if you want to bring your own wallet instead.

​
Step 4 - Store a vector

Each vector has an id, a values array (the actual embedding), and optional metadata. 
await collection.upsert([
  {
    id: 'doc_001',
    values: Array(1536).fill(0).map(() => Math.random()), // replace with real embeddings
    metadata: {
      text: 'The quick brown fox jumps over the lazy dog',
      source: 'my-document.pdf',
      page: 1
    }
  }
]);

console.log('Vector stored.');
After upsert, Recall does three things automatically:
  1. Inserts the vector into the in-memory HNSW index (~2ms)
  2. Encrypts and persists to Shadow Drive (async, non-blocking)
  3. Posts a Merkle root to Solana (async, non-blocking)

​
Step 5 - Query

Pass a query vector and get back the most similar vectors ranked by similarity score. 
const results = await collection.query({
  vector: Array(1536).fill(0).map(() => Math.random()), // your query embedding
  topK: 5
});

results.matches.forEach(r => {
  console.log(`${r.id}: score=${r.score.toFixed(4)}`);
  console.log(`  text: ${r.metadata?.text}`);
});
Example output: 
doc_001: score=0.9821
  text: The quick brown fox jumps over the lazy dog

​
Step 6 - Verify on-chain

Call .verify() to fetch the current Merkle root from Solana and confirm it matches the local state of your collection. 
const proof = await collection.verify();

console.log('Verified:', proof.verified);
console.log('On-chain root:', proof.onChainRoot);
console.log('Explorer:', proof.solanaExplorerUrl);
Example output: 
Verified: true
On-chain root: 7f4a2b...
Explorer: https://explorer.solana.com/address/8xjQ2X...
.verify() makes a Solana RPC call and takes ~400ms. It is an integrity check, not part of the normal query path. Your queries remain at sub-5ms regardless.

​
Next steps

Core Concepts

Understand vectors, embeddings, and HNSW from first principles.

Build an AI Agent

Give your AI agent persistent, verifiable memory.

Memory Inspector

Audit every read, write, and delete with timestamps and Merkle proof.

Migrate from Pinecone

Three line changes. Your existing code stays identical.

​
Self-hosting

You can also run Recall without an API key by bringing your own Solana wallet. 
import { SolVec } from '@veclabs/solvec';

// Self-hosted: bring your own Solana wallet
const sv = new SolVec({
  network: 'devnet',
  walletPath: '/path/to/keypair.json',
});
Self-hosted mode gives you full control. You manage your own Solana wallet and Shadow Drive storage. The SDK is MIT licensed and identical in both modes.