Vectora
Core Formula: Functional Agent = Model (Gemini 3 Flash) + [Harness Runtime](/concepts/harness-runtime/) + Governed Context (Voyage 4 + MongoDB Atlas)
The Problem Vectora Solves
| Failure in Generic Agents | Practical Impact | How Vectora Mitigates |
|---|---|---|
| Shallow Context | Search for “authentication” returns 50 irrelevant files | Reranker 2.5 filters by real semantic relevance, not raw cosine similarity |
| No Pre-Execution Validation | Dangerous tool calls run before being audited | Harness Runtime intercepts, validates via Struct Validation, and applies Guardian before execution |
| Lack of Isolation | Project data leaks between sessions | Namespace Isolation via app-level RBAC + mandatory backend filtering |
| Unpredictable Consumption | LLMs generate overfetch, wasting tokens on boilerplate | Context Engine decides scope, applies compaction (head/tail), and injects only relevance |
| Fragile Security | Blocklists depend on (jailbreakable) prompts | Hard-Coded Guardian is compiled into the Go binary, impossible to bypass via prompt |
The Solution: Sub-Agent Architecture
Vectora is exposed exclusively via MCP. There is no chat CLI, TUI, or direct conversational interface. It operates silently as a governance and context layer:
graph LR
A[Principal Agent] -->|MCP Tool Call| B[Harness Runtime]
B --> C{Guardian + Native Validation}
C -->| Approved| D[Context Engine]
D --> E[Embed via Voyage 4]
D --> F[Rerank via Voyage 2.5]
E --> G[MongoDB Atlas Vector Search]
F --> G
G --> H[Composed Context + Metrics]
H -->|MCP Response| A
Core Components
| Module | Responsibility | Documentation |
|---|---|---|
| Harness Runtime | Orchestrates execution, validates schemas, intercepts tool calls, persists state | Infrastructure that connects the LLM to the real world, not a testing framework |
| Context Engine | Decides scope (filesystem vs vector), applies AST parsing, multi-hop compaction | Pipeline Embed → Search → Rerank → Compose → Validate |
| Provider Router | Routes to curated stack, manages BYOK fallback, tracks quota | No generic layers. Official SDKs, stable parsing |
| Tool Executor | Validates args via Strong Typing, executes with exponential retry, sanitizes output | Immutable blocklist applied before any call |
Curated Stack & Infrastructure
Vectora is not provider-agnostic. We operate with models rigorously calibrated to guarantee metric consistency, parsing stability, and predictable costs:
| Layer | Technology | Why we chose it | Docs |
|---|---|---|---|
| LLM (Inference) | gemini-3-flash | Latency <30ms, stable tool calling, 90% lower cost vs Pro | Gemini 3 |
| Embeddings | voyage-4 | AST-aware, captures functional similarity (validateToken ≈ checkJWT) | Voyage 4 |
| Reranking | voyage-rerank-2.5 | Cross-encoder optimized for code, latency <100ms, +25% precision vs BM25 | Reranker |
| Vector DB + Metadata | MongoDB Atlas | Unified backend (vectors + docs + state + audit), scalable, no ETL | MongoDB Atlas |
Vectora Cloud Only:
Vectora is a 100% cloud-based solution optimized for the Gemini + Voyage stack. We do not support local models (Ollama, LlamaCpp, etc.) or other generic providers to ensure engine accuracy.
Security, Governance & BYOK
Security in Vectora is implemented at the application layer, not delegated to the database:
| Layer | Implementation | Document |
|---|---|---|
| Hard-Coded Guardian | Immutable blocklist (.env, .key, .pem, binaries, lockfiles) executed before any tool call | Guardian |
| Trust Folder | Path validation with fs.realpath + per-namespace/project scope | Trust Folder |
| Application RBAC | Roles (reader, contributor, admin, auditor) validated at runtime | RBAC |
| BYOK or Managed | User keys (Free) or included credits (Plus) | Free Plan |
| Managed (Plus) | Managed quota included in Pro and Team plans | Pro Plan |
Plans & Retention Policy
Vectora operates with a Digital Sovereignty First model, offering BYOK (Bring Your Own Key) for total control or Managed (Plus) for convenience:
| Plan | Price | Storage | API Quota | Retention | Docs |
|---|---|---|---|---|---|
| Free | $0/month | 512MB total | Pure BYOK | 30 days inactivity = vector index deletion | Free |
| Pro | $29/month | 5GB total | Unlimited (Plus) or BYOK | 90 days post-cancellation | Pro |
| Team | Custom | Custom | Unlimited (Plus) or BYOK | Compliance Policy | Team |
| Enterprise | Custom | Unlimited (VPC/Dedicated) | Per contract | Custom policy | Overview |
Retention Rules: Free accounts inactive for 30 days have their vector index automatically deleted. Metadata is preserved for +90 days for export via vectora export. Downgrades notify of limit reduction and grant 7 days for backup. Details in Retention Policy.
Operation Flow (MCP-First)
- Detection: Principal Agent identifies need for deep context and triggers
context_searchvia MCP. - Interception: Harness Runtime captures call, validates namespace, applies Guardian.
- Decision: Context Engine chooses scope (filesystem, vector, or hybrid) and applies AST parsing.
- Embed + Rerank: Query is embedded via
voyage-4, raw results are refined byvoyage-rerank-2.5. - Search & Compaction: MongoDB Atlas returns top-N with compaction (head/tail + pointers) to avoid context rot.
- Structured Response: Validated context + metrics are returned to the principal agent, which generates the final user response.
Where to Start?
| Category | Document | Description |
|---|---|---|
| Quick Start | Getting Started | winget install kaffyn.vectora, Systray setup, MCP integration |
| Concepts | Sub-Agents | Why Sub-Agent and not passive MCP tools? Active governance vs static functions |
| Harness Runtime | Harness Runtime | Tool Execution, Context Engineering, State Management, Verification Hooks |
| Context & RAG | Context Engine | AST parsing, compaction, multi-hop reasoning, hybrid ranking |
| Reranking | Reranker · Local Reranker | VectorDB + cross-encoder or late binding for mutable data, cost trade-offs |
| Models | Gemini 3 · Voyage 4 | Curated stack, BYOK fallback, config schema, per-query costs |
| Backend | MongoDB Atlas | Vector Search, collections, state persistence, multi-tenant isolation |
| Security | Guardian · RBAC | Hard-coded blocklist, Trust Folder, sanitization, per-namespace roles |
| Plans | Overview | Free/Pro/Team, managed quota, automatic fallback, retention policy |
| Integrations | Claude Code · Gemini CLI | MCP configuration, IDE extensions, custom agents |
| Reference | MCP Tools · Config YAML | Tool schema, native-validated config.yaml, error codes |
| Implementation | Engineering | Golang Architecture, Core Migration, CLI Engine, Systray UX |
| Contributing | Guidelines | Strict Golang, performance tests, PRs, public roadmap |
Phrase to remember: “Vectora doesn’t respond to the user. It delivers governed context to your agent. Managed backend, API under your key, security in the application, your data always yours.”
Navigation Guide
- Getting Started — Installation, BYOK setup, and MCP integration.
- Core Concepts — Understand Sub-Agents, Context Engine, and Reranking.
- Security & Governance — Details on Guardian, Trust Folder, and RBAC.
- Authentication — SSO flows, Unified Identity, and API Keys.
- Models & Providers — Curated stack with Gemini 3 and Voyage AI.
- Backend — MongoDB Atlas.
- Integrations — How to use with Claude Code, Gemini CLI, and Cursor.
- Plans & Pricing — Feature comparison and retention policy.
- Technical Reference — MCP tool schema and Config YAML.
- Contributing — Guidelines, code standards, and roadmap.
- FAQ — Troubleshooting and common questions.
- Protocols — MCP Protocol specifications in Vectora.
External Linking
| Concept | Resource | Link |
|---|---|---|
| MongoDB Atlas | Atlas Vector Search Documentation | www.mongodb.com/docs/atlas/atlas-vector-search/ |
| MCP | Model Context Protocol Specification | modelcontextprotocol.io/specification |
| MCP Go SDK | Go SDK for MCP (mark3labs) | github.com/mark3labs/mcp-go |
| Voyage Embeddings | Voyage Embeddings Documentation | docs.voyageai.com/docs/embeddings |
| Voyage Reranker | Voyage Reranker API | docs.voyageai.com/docs/reranker |
| Gemini API | Google AI Studio Documentation | ai.google.dev/docs |
Part of the Vectora ecosystem · Open Source (MIT) · Contributors