{"id":45228333,"url":"https://github.com/kailas-cloud/vecdex","last_synced_at":"2026-04-08T19:01:34.933Z","repository":{"id":338642482,"uuid":"1158587009","full_name":"kailas-cloud/vecdex","owner":"kailas-cloud","description":"Lightweight vector search engine on top of Valkey \u0026 Redis","archived":false,"fork":false,"pushed_at":"2026-02-25T16:23:24.000Z","size":1849,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T20:14:59.620Z","etag":null,"topics":["ai","bm25","embedding","go","knn","pytest","rag","redis","valkey","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kailas-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-15T16:09:28.000Z","updated_at":"2026-02-25T15:59:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kailas-cloud/vecdex","commit_stats":null,"previous_names":["kailas-cloud/vecdex"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/kailas-cloud/vecdex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kailas-cloud%2Fvecdex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kailas-cloud%2Fvecdex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kailas-cloud%2Fvecdex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kailas-cloud%2Fvecdex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kailas-cloud","download_url":"https://codeload.github.com/kailas-cloud/vecdex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kailas-cloud%2Fvecdex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31569400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bm25","embedding","go","knn","pytest","rag","redis","valkey","vector-search"],"created_at":"2026-02-20T20:03:23.205Z","updated_at":"2026-04-08T19:01:34.926Z","avatar_url":"https://github.com/kailas-cloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/vecdex-banner.png\" alt=\"vecdex\" width=\"100%\"/\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eLightweight vector search engine on top of Valkey \u0026 Redis\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/kailas-cloud/vecdex\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/kailas-cloud/vecdex\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.codacy.com/gh/kailas-cloud/vecdex/dashboard\"\u003e\u003cimg src=\"https://app.codacy.com/project/badge/Grade/3ebe9ae848f348bca37551c9da1e77e2\" alt=\"Codacy Grade\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.codacy.com/gh/kailas-cloud/vecdex/dashboard\"\u003e\u003cimg src=\"https://app.codacy.com/project/badge/Coverage/3ebe9ae848f348bca37551c9da1e77e2\" alt=\"Codacy Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kailas-cloud/vecdex/actions/workflows/tests.yml\"\u003e\u003cimg src=\"https://github.com/kailas-cloud/vecdex/actions/workflows/tests.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why vecdex?\n\nMost vector databases are **heavy, cloud-locked, or expensive**. vecdex takes a different approach:\n\n- **Zero new infrastructure** — runs on Valkey or Redis you already have\n- **Automatic embeddings** — send text, get vectors (Nebius AI, OpenAI-compatible providers)\n- **Three search modes** — hybrid (RRF), semantic (KNN), keyword (BM25) via one endpoint\n- **Swap the backend** — Valkey or Redis 8, same API, same results\n- **Budget controls** — daily/monthly token limits with automatic tracking\n- **300+ E2E tests** — battle-tested across both backends\n\n## Examples\n\n### Semantic code search\n\nDefine a struct, tag the fields, search with one line:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n\n    vecdex \"github.com/kailas-cloud/vecdex/pkg/sdk\"\n)\n\ntype CodeChunk struct {\n    ID       string `vecdex:\"id\"`\n    Content  string `vecdex:\"content,content\"`\n    Language string `vecdex:\"language,tag\"`\n    Repo     string `vecdex:\"repo,tag\"`\n}\n\nfunc main() {\n    ctx := context.Background()\n    client, _ := vecdex.New(ctx,\n        vecdex.WithValkey(\"localhost:6379\", \"\"),\n        vecdex.WithEmbedder(myEmbedder),       // any OpenAI-compatible provider\n    )\n    defer client.Close()\n\n    idx, _ := vecdex.NewIndex[CodeChunk](client, \"code-chunks\")\n    _ = idx.Ensure(ctx)\n\n    // Index some code\n    _ = idx.UpsertBatch(ctx, []CodeChunk{\n        {ID: \"1\", Content: \"CreateCollection validates the name and builds an FT index\", Language: \"go\", Repo: \"vecdex\"},\n        {ID: \"2\", Content: \"SearchBuilder chains Query, Mode, Where, Limit into a query\", Language: \"go\", Repo: \"vecdex\"},\n        {ID: \"3\", Content: \"BudgetTracker enforces daily and monthly token limits\", Language: \"go\", Repo: \"vecdex\"},\n    })\n\n    // Semantic search — one line\n    hits, _ := idx.Search().\n        Query(\"how does collection creation work\").\n        Mode(vecdex.ModeSemantic).\n        Where(\"language\", \"go\").\n        Limit(5).\n        Do(ctx)\n\n    for _, h := range hits {\n        fmt.Printf(\"%.2f  %s\\n\", h.Score, h.Item.Content)\n    }\n}\n```\n\n\n### Low-level API\n\nFor full control without struct tags:\n\n```go\nclient, _ := vecdex.New(ctx,\n    vecdex.WithRedis(\"localhost:6379\", \"\"),\n    vecdex.WithEmbedder(myEmbedder),\n)\ndefer client.Close()\n\n// Create collection with filterable fields\nclient.Collections().Create(ctx, \"articles\",\n    vecdex.WithField(\"author\", vecdex.FieldTag),\n    vecdex.WithField(\"year\", vecdex.FieldNumeric),\n)\n\n// Upsert a document — embedding happens automatically\nclient.Documents(\"articles\").Upsert(ctx, vecdex.Document{\n    ID:       \"article-1\",\n    Content:  \"Vector search with HNSW indexes in Redis\",\n    Tags:     map[string]string{\"author\": \"alice\"},\n    Numerics: map[string]float64{\"year\": 2025},\n})\n\n// Hybrid search (vector KNN + BM25 fused via RRF)\nresp, _ := client.Search(\"articles\").Query(ctx, \"HNSW performance\", \u0026vecdex.SearchOptions{\n    Mode:  vecdex.ModeHybrid,\n    Limit: 10,\n})\n\nfor _, r := range resp.Results {\n    fmt.Printf(\"%.2f  %s\\n\", r.Score, r.Content)\n}\n```\n\n## How it compares\n\n| | vecdex | Pinecone | Qdrant | Weaviate | pgvector |\n|---|---|---|---|---|---|\n| Self-hosted | Yes | No | Yes | Yes | Yes |\n| Managed cloud | No | Yes | Yes | Yes | Yes |\n| Underlying storage | Valkey / Redis | Proprietary | Custom | Custom | PostgreSQL |\n| Auto-embedding | Yes | No | No | Yes | No |\n| Hybrid search (RRF) | Yes | Yes | Yes | Yes | No |\n| Token budget tracking | Yes | No | No | No | No |\n| Go SDK with generics | Yes | No | Yes | No | No |\n| Setup complexity | Low | None | Medium | High | Low |\n| License | Apache 2.0 | Proprietary | Apache 2.0 | BSD-3 | PostgreSQL |\n\n## Search modes\n\n| Mode | How it works | Embedding cost | Backend support |\n|------|-------------|----------------|-----------------|\n| `hybrid` (default) | Vector KNN + BM25 fused via Reciprocal Rank Fusion | 1 call | Redis 8 |\n| `semantic` | Pure cosine-similarity KNN | 1 call | Redis 8, Valkey 9 |\n| `keyword` | BM25 full-text search | 0 calls | Redis 8 |\n\n## Backend support\n\n| Backend | Status | Notes |\n|---------|--------|-------|\n| **Valkey 9+** (valkey-search) | Supported | Semantic search. Keyword/hybrid when valkey-search adds BM25 |\n| **Redis 8+** (Redis Search) | Supported | Full hybrid search (semantic + keyword + RRF) |\n| AWS ElastiCache | Planned | |\n| PostgreSQL + pgvector | Planned | |\n\n## Key features\n\n| Feature | Description |\n|---------|-------------|\n| **Hybrid search** | Reciprocal Rank Fusion combining vector KNN and BM25 keyword search |\n| **Semantic search** | Pure cosine-similarity KNN over HNSW vectors |\n| **Keyword search** | BM25 full-text search — zero embedding tokens consumed |\n| **Structured filters** | `must` / `should` / `must_not` with tag match and numeric range operators |\n| **Auto-embedding** | Send text, get vectors via any OpenAI-compatible provider |\n| **Typed Go SDK** | Schema-first generics with `TypedIndex[T]` and fluent search builder |\n| **Batch operations** | Upsert/delete up to 100 items per call with per-item status |\n| **Token budget** | Daily/monthly limits with warn or reject policies |\n| **Cursor pagination** | Stable, opaque-cursor pagination for collections and documents |\n| **Embedding cache** | SHA256-keyed cache in Valkey — identical content is never re-embedded |\n| **Prometheus metrics** | Request latency, embedding tokens, budget, cache hit/miss |\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│              Go SDK  (pkg/sdk)                       │\n│  TypedIndex[T] · SearchBuilder · Fluent API          │\n├─────────────────────────────────────────────────────┤\n│              HTTP API  (Chi)                          │\n│  Auth · Metrics · Wide-event logging · Recovery       │\n├─────────────────────────────────────────────────────┤\n│                 Use Cases                             │\n│  Collection · Document · Search · Batch · Embedding   │\n├─────────────────────────────────────────────────────┤\n│                Repositories                           │\n│  Consumer interfaces (ISP) over Store facade          │\n├──────────────────────┬──────────────────────────────┤\n│    Redis backend     │     Valkey backend            │\n│  (rueidis, RESP2)    │   (rueidis, RESP2)            │\n└──────────────────────┴──────────────────────────────┘\n          │                        │\n    Redis 8 + Search         Valkey 9 + valkey-search\n```\n\nEmbedding pipeline (decorator chain):\n```\nOpenAIProvider → CachedProvider → InstrumentedProvider → StringVectorizer\n       ↓               ↓                  ↓\n  Nebius API     SHA256 cache       Prometheus +\n                  in Valkey        BudgetTracker\n```\n\n## API reference\n\n### Go SDK\n\n```\ngo get github.com/kailas-cloud/vecdex\n```\n\n| Type | Description |\n|------|-------------|\n| `vecdex.Client` | Connection to Valkey/Redis, entry point for all operations |\n| `vecdex.TypedIndex[T]` | Generic index with schema inferred from struct tags |\n| `vecdex.SearchBuilder[T]` | Fluent search: `.Query()`, `.Mode()`, `.Where()`, `.Limit()`, `.Do()` |\n| `vecdex.Hit[T]` | Search result with `.Item` and `.Score` |\n| `vecdex.Document` | Untyped document for low-level API |\n| `vecdex.Embedder` | Interface for text-to-vector providers |\n\nStruct tag format: `vecdex:\"name,modifier\"` — modifiers: `id`, `content`, `tag`, `numeric`, `stored`.\n\n### REST API\n\nFull OpenAPI 3.0 specification: [`api/openapi.yaml`](api/openapi.yaml)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/collections` | Create collection |\n| `GET` | `/collections` | List collections (cursor pagination) |\n| `GET` | `/collections/{name}` | Get collection details |\n| `DELETE` | `/collections/{name}` | Delete collection |\n| `PUT` | `/collections/{name}/documents/{id}` | Upsert document (auto-embeds) |\n| `GET` | `/collections/{name}/documents/{id}` | Get document |\n| `PATCH` | `/collections/{name}/documents/{id}` | Partial update (no re-vectorization) |\n| `DELETE` | `/collections/{name}/documents/{id}` | Delete document |\n| `GET` | `/collections/{name}/documents` | List documents (cursor pagination) |\n| `POST` | `/collections/{name}/documents/search` | Search documents |\n| `POST` | `/collections/{name}/documents/batch-upsert` | Batch upsert (up to 100) |\n| `POST` | `/collections/{name}/documents/batch-delete` | Batch delete (up to 100) |\n| `GET` | `/usage` | Embedding usage \u0026 budget info |\n| `GET` | `/health` | Health check |\n| `GET` | `/metrics` | Prometheus metrics |\n\n## Quick start\n\n### Docker Compose (recommended)\n\n```bash\ngit clone https://github.com/kailas-cloud/vecdex.git\ncd vecdex\ncp .env.example .env\n# Edit .env — set NEBIUS_API_KEY and optionally VECDEX_API_KEY\n\ndocker compose up vecdex\n# API is running at http://localhost:8080\n```\n\n### From source\n\n```bash\n# Prerequisites: Go 1.25+, just\ngit clone https://github.com/kailas-cloud/vecdex.git\ncd vecdex\n\njust build\n# Binary at build/vecdex\n\n# Start Valkey locally\njust valkey-up\n\n# Run the server\nENV=local ./build/vecdex\n```\n\n## Configuration\n\nvecdex uses YAML config files from `config/` selected by the `ENV` environment variable (default: `local`). Supports `${VAR_NAME}` interpolation from environment.\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `ENV` | Config file to load (`local`, `dev`, `docker`, `prod`) | `local` |\n| `CACHE_ADDR` | Valkey/Redis address | `localhost:6379` |\n| `DB_PASSWORD` | Database password | — |\n| `HTTP_PORT` | HTTP server port | `8080` |\n| `NEBIUS_API_KEY` | Nebius AI embedding API key | — |\n| `VECDEX_API_KEY` | API authentication key | — |\n\n## Testing\n\n```bash\njust test-unit              # Unit tests (no Valkey needed)\njust test-pytest-valkey     # E2E — Valkey backend (300+ pytest tests)\njust test-pytest-redis      # E2E — Redis backend\njust test-pytest            # E2E — both backends sequentially\njust pre-commit             # build + lint + unit tests\n```\n\nThe pytest E2E suite runs in Docker Compose with a mock embedding server — no API keys required for CI.\n\n## Roadmap\n\n- [ ] `vecdex-cli` — command-line client\n- [ ] Claude Code agent skills integration\n- [ ] Performance \u0026 latency benchmarks\n- [ ] Demo use cases (RAG, code search, etc.)\n- [ ] Valkey full-text search (when valkey-search adds BM25)\n- [ ] AWS ElastiCache backend\n- [ ] PostgreSQL + pgvector backend\n- [ ] Multi-tenancy / namespaces\n- [ ] Reranking support\n- [ ] Additional embedding providers\n- [ ] Admin UI\n- [ ] Helm chart for Kubernetes\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n## Contributing\n\nContributions are welcome! Please open an issue first to discuss what you'd like to change.\n\n```bash\njust build          # Build + fmt + vet\njust lint           # Run linter\njust test-unit      # Fast unit tests\njust pre-commit     # Full pre-commit check\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkailas-cloud%2Fvecdex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkailas-cloud%2Fvecdex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkailas-cloud%2Fvecdex/lists"}