# VectIQs - Comprehensive LLM Context & Technical Reference Manual

> Version: 1.0.0
> License: Commercial Source-Available (VectIQs Omni & VectIQs Code) with Free Startup Grant (revenue ≤ $1M USD)
> Free Tier: Free for testing, academic research, and startups with ≤ $1M USD annual gross revenue
> Website: https://vectiqs.com
> GitHub: https://github.com/aniwalunj
> Documentation: https://vectiqs.com/documentation
> llms.txt Index: https://vectiqs.com/llms.txt

---

## 1. Executive Summary & Core Value Proposition

VectIQs is an enterprise-grade, local-first, headless long-term memory engine and cognitive infrastructure layer designed for autonomous AI agents, coding copilots, multi-agent swarms, and LLM applications. 

It sits as a decoupled, stateless persistence and semantic context synthesis layer between your client applications (written in Python, TypeScript/Node.js, Go, Rust, etc.) and any large language model (e.g., local Ollama, vLLM, LM Studio, or cloud endpoints like OpenAI, Anthropic Claude, and Google Gemini).

### Fundamental Architectural Tenets
1. **100% Local-First & Air-Gapped Data Sovereignty**: Operates entirely within your own infrastructure (bare-metal servers, private VPCs, on-premise clusters, or local developer workstations) using a unified PostgreSQL 16 + pgvector storage backbone. Zero third-party telemetry, zero external heartbeat exfiltration, and zero mandatory cloud sync.
2. **Quadratic Token Cost Elimination ($O(N^2) \to O(N)$)**: Naive conversational agents append historical interaction logs linearly into prompts, yielding quadratic token cost inflation ($O(N^2)$). VectIQs replaces context stuffing with associative retrieval bounded by a strict Global Token Budget (e.g., 25,000 to 45,000 tokens), cutting cumulative LLM API consumption by 91% to 99%.
3. **Modular Cognitive Memory Routing**: Unlike generic vector databases that pool all text homogenously, VectIQs routes and organizes knowledge across specialized memory layers designed for production AI systems.
4. **Bring Your Own Model (BYOM)**: Seamlessly switch between local HuggingFace embedding transformers, Ollama, LM Studio, vLLM, and cloud embedding providers without modifying application code or database schemas.
5. **Drop-In OpenAI-Compatible Proxy**: Exposes `POST /v1/chat/completions` which intercepts prompt payloads, executes vector and keyword retrieval, injects synthesized memory context into system instructions, forwards requests to the upstream model, and writes the response turn to persistent memory.

---

## 2. Editions & Feature Breakdown

VectIQs is available in two specialized commercial flagship editions:

| Feature / Capability | VectIQs Code (Engineering & Copilots) | VectIQs Omni (Enterprise Multi-Agent Swarms) |
| :--- | :--- | :--- |
| **Licensing** | Commercial Source-Available (Free ≤ $1M rev) | Commercial Source-Available (Free ≤ $1M rev) |
| **Primary Target** | AI Coding Agents & DevTools Copilots | Multi-Agent Swarms & Enterprise B2B SaaS |
| **Decisions Layer** | Included | Included |
| **Code Memory Layer** | Deep Syntax & AST Parsing | Deep Syntax & AST Parsing |
| **Timeline Layer** | Included | Included |
| **Documentation Layer** | Included | Included |
| **Directives Layer** | Included | Included |
| **Version Registry Layer** | Deep Syntax & Dependency Tracking | Deep Syntax & Dependency Tracking |
| **Entity Graph Layer** | Basic | Full Multi-Hop Disjoint Entity Fusion |
| **Agent File Watcher** | CLI Watcher (`vectiqs watch`) | Distributed Real-Time Watcher |
| **Bipolar Verification Quorum**| Dual-Judge | Multi-Agent Bipolar Quorum |
| **Dual-Timestamp Anchoring** | Standard | Dynamic Real-Time + Narrative Anchors |
| **Multi-Tenancy** | Row-Level & Scoped RBAC | Physical Partitioning & Hardware Vault |

---

## 3. Specialized Memory Layers

VectIQs decomposes cognitive agent state across specialized memory layers to ensure surgical recall accuracy:

### 3.1 Decisions Layer (Architectural Decision Records - ADR)
- **Purpose**: Tracks why choices were made, technical rationales, architectural constraints, discarded alternatives, and superseded state.
- **Benefit**: Prevents coding agents and copilots from relitigating previously settled technical decisions or reverting deliberate fixes.

### 3.2 Code Memory Layer
- **Purpose**: Ingests, parses, and indexes programming syntax, function signatures, dependencies, and unified code diffs.
- **Capabilities**: Integrates with the `vectiqs watch` middleware to capture file modifications in real-time using in-memory AST parsing.

### 3.3 Timeline Layer
- **Purpose**: Chronological history of user interactions, agent actions, state changes, and temporal event progressions.
- **Dynamics**: Incorporates temporal decay functions so older interactions gracefully yield priority to recent updates unless explicitly relevant.

### 3.4 Directives & Rules Layer
- **Purpose**: High-priority user constraints, operational boundaries, governance rules, and agent instructions.
- **Recall Trigger**: Always preserved and injected into context with top-tier budget prioritization.

### 3.5 Documentation Layer
- **Purpose**: Grounding manuals, API documentation, design systems, and external tool outputs.
- **Search Hybridization**: Combines dense vector similarity with PostgreSQL full-text sparse keyword search (`tsvector` / BM25) via Reciprocal Rank Fusion (RRF).

### 3.6 Entity Knowledge Graph Layer (Omni)
- **Purpose**: Multi-hop associative knowledge graph connecting entities, dependencies, concepts, and relationships across domains.
- **Capabilities**: Full multi-hop disjoint entity fusion and relational graph traversal.

### 3.7 Version & Dependency Registry Layer
- **Purpose**: Tracks exact library versions, dependency drift, Git commit states, and schema snapshot hashes.
- **Benefit**: Ensures coding agents stay anchored to the active repository versions and avoids hallucinating deprecated or incompatible package APIs.

---

## 4. Hardware Requirements & Installation

### 4.1 System Prerequisites
- **Operating System**: Linux (Ubuntu 20.04+, Debian 11+, RHEL 9+), macOS (Apple Silicon M1-M4 or Intel), Windows 10/11 via WSL2 or native Python.
- **CPU**: Minimum 2 cores (4+ cores recommended for high-throughput concurrency).
- **RAM**: Minimum 2 GB (4 GB recommended for local embedding pipelines).
- **Database**: PostgreSQL 16 with the `pgvector` extension enabled (`CREATE EXTENSION IF NOT EXISTS vector;`).
- **Python**: Version 3.10, 3.11, or 3.12.

---

### 4.2 Local Python Setup (Source Installation)

```bash
# 1. Clone your licensed repository
# Option A: VectIQs Omni (Flagship 7-layer memory suite)
git clone https://github.com/aniwalunj/vectiqs-omni.git
cd vectiqs-omni

# Option B: VectIQs Code (Optimized code memory & AST watcher)
# git clone https://github.com/aniwalunj/vectiqs-code.git
# cd vectiqs-code

# 2. Initialize and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install core dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 4. Configure local environment variables
cp .env.example .env

# 5. Execute database schema migrations
alembic upgrade head

# 6. Start the VectIQs engine daemon
python run.py
```

---

### 4.3 Production Docker Compose Setup

Create a `docker-compose.yml` file in your project directory:

```yaml
version: '3.8'

services:
  vectiqs-db:
    image: pgvector/pgvector:pg16
    container_name: vectiqs-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: vectiqs
      POSTGRES_USER: vectiqs_admin
      POSTGRES_PASSWORD: secure_local_password
    ports:
      - "5432:5432"
    volumes:
      - vectiqs_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U vectiqs_admin -d vectiqs"]
      interval: 5s
      timeout: 5s
      retries: 5

  vectiqs-engine:
    image: vectiqs/engine:latest
    container_name: vectiqs-engine
    restart: unless-stopped
    depends_on:
      vectiqs-db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://vectiqs_admin:secure_local_password@vectiqs-db:5432/vectiqs
      VECTIQS_HOST: 0.0.0.0
      VECTIQS_PORT: 8765
      VECTIQS_API_KEY: viq_live_master_secret_key_12345
      DEFAULT_EMBEDDING_PROVIDER: huggingface
      EMBEDDING_MODEL_NAME: BAAI/bge-small-en-v1.5
      EMBEDDING_DIMENSIONS: 384
    ports:
      - "8765:8765"
    volumes:
      - vectiqs_backups:/backups

volumes:
  vectiqs_pgdata:
  vectiqs_backups:
```

Launch the cluster:
```bash
docker compose up -d
```

Verify service status:
```bash
curl -s http://localhost:8765/health | jq .
```

---

## 5. Environment Variables & Configuration (.env)

| Variable Name | Default Value | Description |
| :--- | :--- | :--- |
| `DATABASE_URL` | `postgresql://...` | PostgreSQL 16 connection URI with credentials and database name. |
| `VECTIQS_HOST` | `0.0.0.0` | Network binding interface for the HTTP engine server. |
| `VECTIQS_PORT` | `8765` | Target TCP port on which the engine daemon listens. |
| `VECTIQS_API_KEY` | *(None)* | Master administrative bearer key (format: `viq_live_...`). |
| `DEFAULT_EMBEDDING_PROVIDER` | `huggingface` | Active provider: `huggingface`, `ollama`, `lmstudio`, `vllm`, `openai`, `gemini`, `custom`. |
| `EMBEDDING_MODEL_NAME` | `BAAI/bge-small-en-v1.5` | Dense vector embedding model identifier. |
| `EMBEDDING_DIMENSIONS` | `384` | Dimensional width of vector embeddings (e.g. 384, 768, 1536). |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Base endpoint for local Ollama instances. |
| `LMSTUDIO_BASE_URL` | `http://localhost:1234/v1`| Base endpoint for local LM Studio instances. |
| `VLLM_BASE_URL` | `http://localhost:8000/v1`| Base endpoint for vLLM inference server. |
| `OPENAI_API_KEY` | *(Optional)* | API key for OpenAI embedding/proxy integration. |
| `GEMINI_API_KEY` | *(Optional)* | API key for Google Gemini model access. |
| `VECTIQS_CORS_ORIGINS` | `*` | Comma-delimited list of permitted CORS web origins. |
| `VECTIQS_RATE_LIMIT_RPM` | `120` | Sliding-window request rate limit per application ID. |
| `VECTIQS_PARTITION_STRATEGY`| `row_level` | Multi-tenancy isolation model: `row_level` or `physical_table`. |

---

## 6. Command Line Interface (CLI) Manual

VectIQs ships with a native CLI utility (`vectiqs` or `python -m vectiqs.cli`):

### 6.1 Interactive Setup Wizard
```bash
vectiqs setup
```
Discovers available local LLM instances (Ollama, LM Studio) and embedding providers, tests connection latencies, and automatically generates a validated configuration file.

### 6.2 Engine Diagnostic Probe (Doctor)
```bash
vectiqs doctor [--reset-advisories]
```
Checks engine health, validates upstream model provider communication, verifies vector dimension consistency, and displays active security advisories and updates.

### 6.3 Agent File Watcher Middleware
```bash
vectiqs watch [workspace_path] [--conversation-id <id>] [--debounce <sec>] [--port <port>]
```
Silently monitors a local codebase directory for real-time file updates made by AI coding agents (such as Antigravity, Cursor, Claude Code, or Aider). 
- Computes line-by-line unified diffs via in-memory `difflib`.
- Automatically respects `.gitignore` rules and ignores `node_modules/`, `.git/`, and binary assets.
- Transmits syntactic changes to the engine's `POST /v1/memory/add` endpoint with a 1.0-second debounce cooldown.

---

## 7. Universal REST API Specification

Default Base URL: `http://localhost:8765`  
Authentication: `Authorization: Bearer <API_KEY>` or Header `x-api-key: <API_KEY>`

### 7.1 Ingest Memory (POST /v1/memory/add)
Inserts an interaction turn, decision, code diff, or factual statement into associative memory.

**Request Payload**:
```json
{
  "tenant_id": "org_default",
  "conversation_id": "session_frontend_refactor",
  "role": "user",
  "content": "The production PostgreSQL database uses pool_size=25 with pgBouncer transaction pooling.",
  "layer": "semantic",
  "metadata": {
    "environment": "production",
    "component": "database-router",
    "author": "infrastructure-lead"
  }
}
```

**Response (200 OK)**:
```json
{
  "status": "success",
  "memory_id": "mem_01J8X9Q77Y4ABM",
  "tenant_id": "org_default",
  "layer": "semantic",
  "tokens_indexed": 18,
  "vector_dimensions": 384,
  "created_at": "2026-10-29T14:30:00Z"
}
```

---

### 7.2 Associative Memory Extraction (POST /v1/memory/extract)
Extracts relevant memories for an agent's current query, filtered by layer and strictly bounded by token budgets.

**Request Payload**:
```json
{
  "tenant_id": "org_default",
  "conversation_id": "session_frontend_refactor",
  "query": "What are the database connection pooling settings?",
  "layers": ["semantic", "decisions", "code"],
  "max_tokens": 1500,
  "similarity_threshold": 0.70
}
```

**Response (200 OK)**:
```json
{
  "query": "What are the database connection pooling settings?",
  "memories": [
    {
      "memory_id": "mem_01J8X9Q77Y4ABM",
      "content": "The production PostgreSQL database uses pool_size=25 with pgBouncer transaction pooling.",
      "layer": "semantic",
      "score": 0.912,
      "metadata": {
        "environment": "production",
        "component": "database-router"
      },
      "created_at": "2026-10-29T14:30:00Z"
    }
  ],
  "total_tokens": 34,
  "budget_consumed_percent": 2.27
}
```

---

### 7.3 OpenAI-Compatible Proxy (POST /v1/chat/completions)
Seamless drop-in replacement for OpenAI SDKs and frameworks. Intercepts queries, retrieves relevant context, prepends synthesized memory blocks to system instructions, and captures assistant responses.

> **Session Continuity & Architectural Scoping**:
> - **Isolated Chat Tabs (Default)**: Assign distinct session IDs per chat (e.g. `user="chat_tab_01"` vs `user="chat_tab_02"`). Starting a new chat tab with a fresh ID starts a completely clean slate with zero transcript or memory carryover.
> - **Shared Project Brain**: Scope multiple chats/agents working on the same repository to the same project identifier (e.g. `user="project_auth_service"`). Architectural decisions and coding rules learned in Chat A are automatically recalled in Chat B, guarded by semantic relevance.
> - **Fallback Behavior**: If `user` is omitted, VectIQs generates an ephemeral random UUID (`session-<uuid>`) per request, treating each message as a standalone 1-turn conversation without dialogue continuity.

**Request Payload**:
```json
{
  "model": "qwen2.5-coder:32b",
  "user": "developer_aniket",
  "messages": [
    {
      "role": "user",
      "content": "How should I configure our DB client pool size?"
    }
  ],
  "temperature": 0.2
}
```

---

### 7.4 Multi-Tenant API Key Provisioning (POST /api/v1/auth/keys)
Generates an isolated, scoped API key bound to an organization and application ID.

**Request Payload**:
```json
{
  "org_id": "enterprise_corp",
  "app_id": "coding_copilot",
  "permissions": ["read", "write"]
}
```

**Response (200 OK)**:
```json
{
  "status": "success",
  "key": "viq_live_9f81a7b42c90e...",
  "org_id": "enterprise_corp",
  "app_id": "coding_copilot",
  "created_at": "2026-10-29T14:30:00Z"
}
```

---

### 7.5 Disaster Recovery & Backup Endpoints

#### Create Atomic Snapshot (POST /api/v1/backup/create)
```bash
curl -X POST http://localhost:8765/api/v1/backup/create \
  -H "Authorization: Bearer viq_live_..." \
  -H "Content-Type: application/json" \
  -d '{"format": "tar.gz", "label": "pre-upgrade-snapshot"}'
```

#### Real-Time Backup Progress Stream (GET /api/v1/backup/status)
Connect via newline-delimited JSON (NDJSON) streaming to observe real-time database export and hashing progress.

#### Verify Cryptographic Integrity (GET /api/v1/backup/verify/{filename})
Verifies the archive against its `.sha256` sidecar signature to detect file corruption or bit rot.

#### Restore Snapshot (POST /api/v1/backup/restore)
Restores complete SQL relational metadata and vector embeddings with automatic `manifest.json` dimensional guard checks.

---

### 7.6 Diagnostics & Health Endpoints
- `GET /health`: Liveness probe returning HTTP 200 `{ "status": "healthy" }`.
- `GET /api/v1/system/status`: Real-time hardware utilization (CPU, memory, disk) and PostgreSQL storage statistics.
- `GET /api/v1/embeddings/status`: Currently active embedding model name, dimensional width verification (e.g. 384/768/1536), and index health.

---

## 8. Multi-Tenancy & Agent Swarm Headers

Every request can be scoped dynamically using request headers:
- `Authorization: Bearer viq_live_...`: Authenticates request and resolves tenant identity.
- `X-User-Id`: Uniquely isolates individual human users or end-customer accounts.
- `X-Agent-Id`: Identifies the executing autonomous sub-agent (e.g. `researcher_agent`, `writer_agent`, `qa_agent`).
- `conversation_id`: Scopes conversational threads or execution runs. Governs the turn sequence, historical compaction window, and atomic session deletion lifecycle. If omitted, the engine assigns an ephemeral random `session-<uuid>` for that turn. Reusing a consistent identifier across requests is required to maintain turn-to-turn context.

### 8.1 Multi-Agent Swarm Collaborative Pattern
When multiple agents work on the same task, they specify identical `conversation_id` or `project_id` values while passing distinct `X-Agent-Id` headers. This allows agents to share collective architectural memories while attributing actions to specific worker identities.

### 8.2 Architectural Patterns: Isolated Chat Threads vs. Shared Project Brain
When architecting developer copilots, conversational chatbots, or multi-agent workbenches with sidebar navigation, applications choose between two primary session scoping models:

1. **Pattern A: Isolated Chat Threads (Per-Session Isolation - Default)**
   - **Configuration**: Assign a distinct, unique `conversation_id` (or `user` parameter in Transparent Proxy mode) to each chat tab or session (e.g., `chat_001`, `chat_002`).
   - **Behavior**: Complete isolation. When a user opens a new chat tab (Chat B), it starts with zero knowledge of Chat A. Neither raw conversational transcripts nor distilled specialized memories (decisions, code diffs, timeline events) cross the boundary.
   - **Use Case**: Independent user inquiries, unrelated debugging workflows, or multi-topic chats where cross-contamination must be prevented.

2. **Pattern B: Shared Project Brain (Cross-Chat Collective Memory)**
   - **Configuration**: Scope all chats within a workspace, repository, or project to the same persistent identifier (e.g., `conversation_id: "repo_ecommerce"` or `user: "project_auth_service"`).
   - **Behavior**: Collective memory inheritance. Architectural decisions, schema migrations, and coding directives established in earlier chats are automatically available to new chats within that project.
   - **Semantic Guardrails**: VectIQs evaluates cosine similarity thresholds and intent classification before context injection. Only memories mathematically relevant to the current prompt are surfaced; unrelated topics never bleed across queries.
   - **Use Case**: Collaborative coding agents, long-lived development sprints, shared repository workbenches.

3. **Temporal Session Continuity (Resuming Ended Sessions)**
   - Ending a session and reopening it days later using the original `conversation_id` / `user` parameter instantly reconstructs all previously distilled decisions, milestones, and context without loss.

---

## 9. SDK Integration Examples

### 9.1 Python Integration Example
```python
import os
import requests

VECTIQS_HOST = os.getenv("VECTIQS_HOST", "http://localhost:8765")
API_KEY = os.getenv("VECTIQS_API_KEY", "viq_live_sample_key")

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def store_memory(conversation_id: str, content: str, layer: str = "semantic", metadata: dict = None):
    payload = {
        "tenant_id": "default",
        "conversation_id": conversation_id,
        "role": "user",
        "content": content,
        "layer": layer,
        "metadata": metadata or {}
    }
    res = requests.post(f"{VECTIQS_HOST}/v1/memory/add", json=payload, headers=headers)
    res.raise_for_status()
    return res.json()

def retrieve_context(conversation_id: str, query: str, max_tokens: int = 2000):
    payload = {
        "tenant_id": "default",
        "conversation_id": conversation_id,
        "query": query,
        "max_tokens": max_tokens
    }
    res = requests.post(f"{VECTIQS_HOST}/v1/memory/extract", json=payload, headers=headers)
    res.raise_for_status()
    memories = res.json().get("memories", [])
    return "\n".join([f"- [{m['layer'].upper()}] {m['content']}" for m in memories])

# Example Usage
cid = "refactor-session-101"
store_memory(cid, "Architecture rule: All API route handlers must return unified ResponseWrapper objects.", layer="decisions")
context = retrieve_context(cid, "What are the rules for API responses?")
print("Retrieved Context:\n", context)
```

---

### 9.2 TypeScript / Node.js Integration Example
```typescript
interface MemoryExtractResponse {
  query: string;
  memories: Array<{
    memory_id: string;
    content: string;
    layer: string;
    score: number;
  }>;
  total_tokens: number;
}

const VECTIQS_HOST = process.env.VECTIQS_HOST || 'http://localhost:8765';
const API_KEY = process.env.VECTIQS_API_KEY || 'viq_live_sample_key';

export async function fetchAgentMemory(
  conversationId: string, 
  prompt: string, 
  maxTokens = 2000
): Promise<string> {
  const res = await fetch(`${VECTIQS_HOST}/v1/memory/extract`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      tenant_id: 'default',
      conversation_id: conversationId,
      query: prompt,
      max_tokens: maxTokens
    })
  });

  if (!res.ok) {
    throw new Error(`VectIQs memory extraction failed: ${res.statusText}`);
  }

  const data: MemoryExtractResponse = await res.json();
  return data.memories.map(m => m.content).join('\n');
}
```

---

## 10. Mathematical Foundations & Benchmark Records

### 10.1 Token Inflation Mathematical Formulation
Let an agent conversational session span $N$ consecutive interaction turns, where turn $i$ contributes $T_i$ tokens (with average turn length $T_{\text{turn}}$).

In traditional, naive agent loops where conversation logs are concatenated directly:
$$\text{Total Tokens}(N) = \sum_{i=1}^{N} \left( \sum_{j=1}^{i} T_j \right) \approx \frac{N(N+1)}{2} T_{\text{turn}} = \mathcal{O}(N^2)$$

With VectIQs associative retrieval bounded by Global Token Budget $B_{\text{max}}$:
$$\text{Total Tokens}(N) \le N \cdot B_{\text{max}} = \mathcal{O}(N)$$

As $N \to 1,000$ turns, cumulative token consumption drops by **91% to 99%**, preventing token budget exhaustion and prompt dilution.

---

### 10.2 Hybrid Search Reciprocal Rank Fusion (RRF)
To balance semantic conceptual matching with exact syntactic identifiers (function names, variable symbols, error codes):
$$RRF(d) = \sum_{m \in M} \frac{1}{k + r_m(d)}$$
Where $M$ is the set of retrieval channels (Dense HNSW + Sparse BM25), $r_m(d)$ is document rank within channel $m$, and $k$ is the smoothing constant ($k = 60$).

---

### 10.3 Benchmark Recall Accuracy Records

| Benchmark Suite | VectIQs (Gemini 3.8 Flash) | Hindsight | mem0 | Honcho | LIGHT |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **BEAM 100K** | **92.0%** (#1 in World) | 73.4% | - | 63.0% | 35.8% |
| **BEAM 1M** | **87.5%** (#1 in World) | 73.9% | 64.1% | 61.8% | 33.6% |
| **BEAM 10M** | **80.0%** (#1 in World) | 64.1% | 48.6% | 40.9% | 26.6% |
| **LoCoMo** | **93.75%** (#1 in World) | 92.0% | 92.5% | 89.9% | - |

---

## 11. Production Deployment & High-Scale Scaling Architecture

VectIQs is architected to scale linearly to handle tens of thousands of concurrent AI agents and high-throughput enterprise workloads.

### 11.1 Concurrency & Connection Pooling Architecture (PgBouncer)
- **Problem**: Opening raw PostgreSQL connections for each HTTP request exhausts database backend processes (`max_connections`) under high concurrency.
- **Solution**: VectIQs mandates transaction-mode connection pooling via PgBouncer.
- **Recommended PgBouncer Configuration**:
  ```ini
  [databases]
  vectiqs = host=127.0.0.1 port=5432 dbname=vectiqs auth_user=postgres

  [pgbouncer]
  listen_port = 6432
  listen_addr = *
  auth_type = scram-sha-256
  auth_file = /etc/pgbouncer/userlist.txt
  pool_mode = transaction
  max_client_conn = 10000
  default_pool_size = 50
  min_pool_size = 10
  reserve_pool_size = 5
  reserve_pool_timeout = 5
  max_db_connections = 100
  server_idle_timeout = 60
  ```
- **Throughput Multiplier**: Enables 10,000+ client agents to multiplex over 50–100 physical PostgreSQL connections without connection starvation or backend lock thrashing.

### 11.2 PostgreSQL 16 & pgvector Engine Tuning
For memory servers indexing large collections of vector embeddings:
- `shared_buffers = 25% of total system RAM` (e.g., 16 GB on a 64 GB host).
- `work_mem = 64MB` to allow parallel sorting and multi-tenant partition filters.
- `maintenance_work_mem = 2GB` to accelerate HNSW index generation.
- `effective_cache_size = 75% of total system RAM`.
- `wal_buffers = 16MB` and `checkpoint_completion_target = 0.9`.
- **HNSW Index Parameters**:
  ```sql
  CREATE INDEX IF NOT EXISTS idx_memories_embedding_hnsw 
  ON memories USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
  ```

### 11.3 Scaled Multi-Tenant Directives & Token Budgeting
- **Global User Guidelines & Constraints**: High-priority user rules, negative constraints (e.g. "Never use SQLite"), and design directives stored in the Directives layer are pinned to top priority during associative extraction.
- **Query Decoupling**: Directives bypass distance-threshold pruning and are guaranteed inclusion into the context payload before variable conversational memories consume the remaining budget.
- **Concurrency Protection**: Read queries route to read-replica pools, ensuring write-heavy telemetry or memory additions never stall latency-critical context synthesis.

### 11.4 Asynchronous Webhooks & Idempotent Licensing
- **PayPal Webhooks**: Live asynchronous listeners (`PAYMENT.CAPTURE.COMPLETED`, `PAYMENT.CAPTURE.REFUNDED`) guarantee key issuance even if client browser tabs close mid-checkout, and revoke licenses immediately upon dispute/refund.
- **Evaluation Licenses**: 14-day evaluation trial licenses are cryptographically verified offline (RS256) or dynamically validated online via the universal license verification API.

---

## 12. Security, Sovereign RBAC & Compliance

- **Zero Remote Telemetry**: Strict local-first architecture. VectIQs does not transmit customer telemetry, user prompts, or embeddings to central servers.
- **SHA-256 Key Hashing**: Plaintext API keys (`viq_live_...`) are hashed using SHA-256 upon generation. Only cryptographically secure hashes are stored in PostgreSQL.
- **Role-Based Access Control (RBAC)**: Supports discrete permission tiers (`read`, `write`, `admin`).
- **Encrypted Local Storage**: Master encryption credentials and OS-level settings are protected via AES-256 Fernet encryption bound to local machine hardware identifiers.
- **Compliance Ready**: Fully air-gapped capable for enterprise HIPAA, GDPR, SOC 2 Type II, and ISO 27001 regulated operating environments.

---

## 13. Licensing & Commercial Terms

1. **Commercial Source-Available Licenses (VectIQs-Omni & VectIQs-Code)**:
   - Purpose-built for commercial multi-agent swarms and software engineering copilots.
   - Complete source code transparency on GitHub, on-premises deployment, and zero cloud vendor lock-in.
   - **Free Startup Grant**: 100% free of charge for individual developers, testing, academic research, and any commercial organization generating less than **$1,000,000 USD** in annual gross revenue.
   - **Enterprise & Scale Tiers**: Transparent scale-based commercial licenses for organizations exceeding $1M revenue.
   - Includes enterprise SLAs, custom adapter engineering, and priority support.
2. **Future Open Source Roadmap**:
   - We plan to release a dedicated open-source community edition in future releases to empower grassroots developers and researchers.

For enterprise inquiries or activation keys, visit: `https://vectiqs.com/pricing` or contact `licensing@vectiqs.com`.
