Project Name
ZeroG VectorSearch (0g-vector-search)
Project Website
https://www.npmjs.com/package/0g-vector-search
Project Brief
What problem we’re solving
0G Storage provides robust KV and Log layers for data persistence, but lacks native semantic search capabilities. AI agents and dApps building on 0G currently face two bad options:
- Use centralized vector databases (Pinecone, Weaviate, Qdrant) — defeating the purpose of building on decentralized infrastructure
- Build custom search from scratch — high engineering cost with no ecosystem reuse
There is no way to perform approximate nearest neighbor search, RAG retrieval, or AI agent memory natively on 0G’s storage layer.
Our solution and key features
ZeroG VectorSearch is the first decentralized vector search SDK built directly on 0G’s sharded KV layer. It implements a Hierarchical Navigable Small World (HNSW) index with O(log N) query complexity, designed as a drop-in extension of `@0glabs/0g-ts-sdk`.
Key features:
- HNSW Vector Index — Multi-layer graph with approximate nearest neighbor search, supporting cosine, euclidean, and dot product distance metrics
- Deterministic Sharding — FNV-1a consistent hashing maps vector IDs to 0G shard_ids, ensuring queries only hit relevant storage nodes and minimizing DA gas costs
- Hybrid Search — Combines BM25 keyword matching with semantic vector search using score fusion (following the 0gmem retrieval pattern) for maximum accuracy
- Security Layer — PoRA-compatible proof commitments, shard health monitoring with fallback routing, and alignment verification to detect data injection attacks
- One-line Developer Experience — `npm install 0g-vector-search` and you have decentralized vector search
import { VectorStore } from “0g-vector-search”;
const store = new VectorStore({ dimensions: 768, zeroG: { endpoint, streamId, privateKey, flowContract } });
await store.upsert(“doc_1”, embedding, { source: “arxiv” }, “paper text…”);
const results = await store.search(queryEmbedding, { topK: 10 });
Target users and market
- AI Agent developers building on 0G who need persistent memory and retrieval
- dApp builders implementing RAG pipelines, document search, or recommendation systems
- 0G ecosystem projects that need semantic search without leaving the 0G stack
- Web3 AI startups looking for fully decentralized alternatives to Pinecone/Weaviate
What makes this project unique
1. First mover — No other project provides native vector search on 0G Storage
2. Deep 0G integration — Not a wrapper around an external DB; vectors are stored directly in 0G’s KV layer using hex-encoded keys compatible with 0G’s storage spec
3. Already built and published — The core SDK is complete with 21 passing tests and is live on npm, not just a concept
4. Hybrid search — Combines keyword + semantic retrieval unlike pure vector DBs
5. Security-first — PoRA verification, alignment checks, and data availability guards built in from day one
How will you integrate 0G?
Technical implementation details
The SDK integrates directly with 0G’s storage stack through `@0glabs/0g-ts-sdk`:
- Reads: Uses `KvClient.getValue()` to retrieve vector data, graph connections, and metadata from 0G’s KV layer
- Writes: Uses `Batcher.streamDataBuilder.set()` to batch multiple KV writes (vector data + HNSW connections + metadata) into a single 0G transaction, minimizing gas costs
- Node discovery: Uses `Indexer.selectNodes()` for KV node selection
KV Key Structure (all hex-encoded for 0G compatibility):
| Key Pattern | Data Stored |
|—|—|
| `vec::` | Raw vector embedding (Float32 buffer) |
| `idx:::` | HNSW graph connections per layer |
| `meta::` | Vector metadata (JSON) |
| `bm25::` | BM25 term frequencies for keyword search |
| `cfg:global:index_state` | Index config, entry point, max level |
Architecture:
┌──────────────────────────────────────────────────┐
│ VectorStore SDK │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ HNSW │ │ BM25 │ │ Security │ │
│ │ Index │ │ Index │ │ Layer │ │
│ └────┬─────┘ └────┬─────┘ └───────┬───────┘ │
│ ┌────┴──────────────┴───────────────┴────────┐ │
│ │ Shard Router (FNV-1a Hashing) │ │
│ └────────────────┬───────────────────────────┘ │
│ ┌────────────────┴───────────────────────────┐ │
│ │ 0G KV Layer (KvClient / Batcher) │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```
Which features will use 0G services
- All vector storage — Every vector, graph connection, and metadata entry is persisted to 0G’s KV layer
- Proof generation — PoRA-compatible commitments for validator verification of stored vectors
- Shard routing — Deterministic mapping to 0G’s shard architecture for efficient querying
- Data availability — Health monitoring of 0G storage shards with graceful fallback
**
Timeline for integration**
| Phase | Deliverables | Timeline |
|—|—|—|
| Phase 1 (DONE) | Core SDK: HNSW index, shard router, hybrid search, security layer, KV adapter, 21-test suite, npm published | Complete |
| **Phase 2** | Testnet validation via 0G onebox, performance benchmarks, live KV node integration tests | 2-3 weeks |
| Phase 3 | Distributed shard search, concurrent write control, streaming insert API, full API docs | 4-6 weeks |
| Phase 4 | Claude Skill for instant vector queries, example apps (AI agent memory, RAG pipeline), community tutorials | 3-4 weeks |
Expected benefits from using 0G
- Decentralized vector search — Eliminates dependency on centralized vector DB providers
- Data availability guarantees — 0G’s PoRA mechanism ensures stored vectors are verifiably available
- Cost efficiency — Batched KV writes minimize on-chain transaction costs
- Ecosystem growth — Makes 0G the first decentralized storage layer with native AI/ML search capabilities
GitHub Repository
Demo/Prototype
- npm package (live): link above
- Install: `npm install 0g-vector-search`
Documentation
- README with quick start, architecture diagram, and API reference: on Github
Social Media
- Twitter/X: [sage_senpeak]
- Discord: [not_davisage]
- Telegram: [sage_senpeak]
- Other: [portfolio-dvyne.vercel.app]