# Vectros

**The secure data, document, search, and AI back-end that developers build apps on.**

Vectros gives an application team the back-end substrate an AI product needs — a typed
data store, a document pipeline, hybrid search, citation-grounded retrieval, multi-tenant
isolation, least-privilege access control, and an audited compliance posture — behind one
coherent API, a Node SDK, a CLI, and an MCP server. You bring the product and the domain
logic; Vectros brings the retrieval substrate, the tenancy and identity model, the
streaming inference stack, and the compliance scaffolding. The common case — store
content, retrieve it, ground a model on it, all isolated per customer — takes minutes
instead of months.

Two framings capture what Vectros is, depending on what you're building:

- **"Stripe for the AI-application back-end."** The same way Stripe is the payments layer
  you don't build yourself, Vectros is the secure data/search/AI layer you don't build
  yourself. You integrate a small, well-shaped API surface instead of standing up your own
  database design, search cluster, embedding pipeline, tenant-isolation model, key-scoping
  system, and audit trail.

- **"The enterprise memory and knowledge layer for agents."** Agents need somewhere
  durable, searchable, and access-controlled to keep what they know. Vectros is that
  layer — reachable from your own code over the API and SDK, or natively by an agent over
  the Model Context Protocol (MCP). It backs the full range of agent memory: long-term and
  semantic recall (hybrid + vector search), episodic history (records with full version
  history over time), facts and entities (schema'd records with lookups and references),
  document and RAG memory (ingest plus citation-grounded retrieval), and shared multi-agent
  memory (context isolation plus access control).

Vectros comes out of building a HIPAA-grade clinical application — so data isolation,
audit, and sensitive-data handling were design constraints from the first line of code,
not retrofits. That lineage makes regulated and healthcare workloads home turf, but the
same substrate serves vertical SaaS, private knowledge bases and chat-with-your-docs,
document-heavy workflows, and platforms that serve their own customers.

## The pillars

- **Structured data and documents** — Define your own typed record schemas (fields,
  validation, indexing, references, sensitivity) and write records against them. Ingest
  documents inline or by file upload, organize them in folders, and retrieve their text and
  download URLs. Every write to an audited model is versioned. Optimistic concurrency
  protects against lost updates.

- **Hybrid search and grounded RAG** — One search call spans both records and documents,
  in keyword, semantic, or hybrid mode. The same indexed content grounds the inference
  surface: chat, retrieval-augmented generation over your own data, and document-scoped
  question answering — all streamed, with citations back to the source.

- **Identity, per-customer isolation, and least-privilege keys** — Every data-plane
  resource is partitioned by an auth-derived context that fails closed; lookups never cross
  a context boundary. Scoped keys carry exactly the permissions you grant and no more, and
  the identity plane (users, organizations, clients) models your customers and their
  groupings.

- **Compliance and trust posture** — Audit and version history retained compliantly,
  sensitive fields destroyed at write time, sensitive data kept out of the search index,
  read-time masking unless a caller is explicitly scoped to reveal, and per-customer
  hard-delete. The platform has been hardened across two formal independent security audits
  with Criticals remediated.

## The surfaces

How a developer meets Vectros. Pick the surface that fits where you work; they all speak to
the same platform.

| Surface | What it is |
|---|---|
| **API** | The core REST surface — data, documents, search, inference, identity, and auth. Everything else is a client on top of it. |
| **Node SDK** | A typed client library. Construct it once with a token and environment, then call sub-clients grouped by area (`records`, `schemas`, `documents`, `folders`, `search`, `inference`, `identity`). |
| **CLI** | A command-line tool for the blueprint lifecycle — initialize, validate, plan, bootstrap, and end-to-end test an app's back-end from config. |
| **MCP server** | Twenty-one data-plane tools that let an AI agent read and write your Vectros data directly over the Model Context Protocol. Vectros data-plane tools only — no web or external-search tools. |
| **Blueprints / no-code path** | A declarative way to describe an app's back-end (schemas, access, a service principal, seed data) and provision it in one command — then drive it from an agent with zero application code. |
| **Reference apps** | Forkable reference front-ends: a data-plane app to fork for a customer-facing UI, and a control-plane admin app. |

## The map

The documentation is organized by area. Each area has three documents, following the
[Diátaxis](https://diataxis.fr/) model: an **explanation** (the concept — what it is and
why it exists), a **how-to** (runnable, goal-oriented guides on real calls), and a
**reference** (every option, field, limit, and error, with an honest account of what each
feature does *not* do).

### Data model — records, documents, folders, schemas

| Document | What's in it |
|---|---|
| [explanation](./data-model/explanation.md) | Why Vectros is schema-first; how records, documents, folders, and schemas relate; versioning and concurrency. |
| [how-to](./data-model/how-to.md) | Define a schema, write and update records, ingest and upload documents, organize folders, read version history. |
| [reference](./data-model/reference.md) | Every method, field type, validation rule, the response envelope, limits, error codes, and notes on what isn't supported. |

### Search and RAG — find and ground

| Document | What's in it |
|---|---|
| [explanation](./search-rag/explanation.md) | Keyword vs. semantic vs. hybrid search; how unified record + document search works; how retrieval grounds inference. |
| [how-to](./search-rag/how-to.md) | Run a hybrid search, narrow by content type and filters, ask a question over your data, ask against a single document. |
| [reference](./search-rag/reference.md) | Search parameters and modes, inference endpoints and streaming, the citation shape, limits, and notes & limits. |

### Identity and access — isolation and keys

| Document | What's in it |
|---|---|
| [explanation](./identity-access/explanation.md) | Per-customer context isolation, the identity plane, scoped least-privilege keys, and the scope grammar. |
| [how-to](./identity-access/how-to.md) | Model your customers as users/orgs/clients, mint and scope a key, narrow data access, and reason about what a scope grants. |
| [reference](./identity-access/reference.md) | Identity methods, the scope grammar in full, the data-plane allowlist, what coarse and wildcard scopes do *not* grant, and error codes. |

### Operations and trust — compliance, audit, lifecycle

| Document | What's in it |
|---|---|
| [explanation](./operations-trust/explanation.md) | The trust posture as a whole — isolation, audit, sensitive-data handling, and lifecycle — and why it's foundational rather than bolted on. |
| [how-to](./operations-trust/how-to.md) | Enable audit history on a schema, mark and handle sensitive fields, reveal masked fields with scope, and tear down a customer context. |
| [compliance](./operations-trust/compliance.md) | The compliance story in precise, honest terms: audit & version history retained compliantly, tamper-evident state continuity, redact-at-write, search-exclusion, read-time masking, and per-customer hard-delete — with the boundaries clearly drawn. |
| [reference](./operations-trust/reference.md) | Audit/versioning behavior, the three distinct sensitive-data mechanisms, retention behavior, teardown semantics, and notes & limits. |

### Clients — the surfaces in depth

| Document | What's in it |
|---|---|
| [SDK](./clients/sdk.md) | Constructing the Node SDK, the sub-client map, the response envelope and how to drain it, and version reality. |
| [CLI](./clients/cli.md) | The CLI command set and the blueprint lifecycle from `init` through `bootstrap` to end-to-end test. |
| [MCP](./clients/mcp.md) | The MCP server, its twenty-one data-plane tools, how an agent connects, and the boundaries of the agent surface. |
| [blueprints](./clients/blueprints.md) | The blueprint format — what a blueprint can express — and the no-code provisioning path. |

## How these docs are organized (Diátaxis)

Every area follows the same shape, so you always know where to look:

- **explanation.md** answers *what is this and why* — the mental model, with no steps to
  follow. Read it first when an area is new to you.
- **how-to.md** answers *how do I do X* — short, runnable, goal-oriented guides built on
  real SDK, CLI, and MCP calls, with synthetic data only. Reach for it when you know what
  you want to accomplish.
- **reference.md** answers *what are all the options* — the exhaustive list of methods,
  parameters, limits, and error codes, plus a frank "notes & limits" account of each
  feature's edges.

If you'd rather learn by following a complete, opinionated build end-to-end, see the
**blueprint walkthroughs** (getting-started, clinical-intake, coding-agent-memory, and
second-brain) — they assemble these pillars into working applications and are documented
separately.

## Where the line is

These docs explain the concepts, show real calls, and enumerate the options honestly. They
are deliberately not a hand-maintained copy of every endpoint and field — for the
canonical, always-current request and response shapes, see the **generated API reference**
(rendered from the OpenAPI specification). When this set shows a snippet, it's grounded in
calls that actually run against the platform; when a feature has an edge or a limit, the
relevant **reference** says so plainly rather than rounding up.

A note on version reality: the API specification is at **0.29.9**. The CLI and MCP server
bundle a **0.26** staging SDK build; the React toolkit and the reference web apps
(app.vectros.ai, the Admin App) still pin a **0.23** staging build. A small set of calls —
partial updates to records, documents, and folders (RFC-7386 PATCH), and creating a record
by either schema name or schema id — require **SDK 0.26+**. Wherever a how-to uses one of
these, it is marked **(SDK 0.26+)** so you know what your client supports today. Because the
reference web apps are still on a 0.23 build, those 0.26+ calls are reachable through the
SDK, CLI, and MCP server but **not** through those apps' own UI — if you fork a reference
app, expect to add those calls yourself. The 0.27 specification also adds an optional
lower-cost global-region path for inference (`allowGlobalRegion`) for tenants entitled to
it — see [Search and RAG](./search-rag/reference.md) and
[Operations and trust](./operations-trust/reference.md).

## Where to go next

- [Quickstart](./getting-started/quickstart.md) — **new here? start here.** Define a schema,
  write a record, search it, and ground an answer in one runnable thread.
- [Data model](./data-model/explanation.md) — start here if you're modeling your data.
- [Search and RAG](./search-rag/explanation.md) — start here if retrieval and grounded
  answers are the point.
- [Identity and access](./identity-access/explanation.md) — start here for multi-tenant
  isolation and key scoping.
- [Operations and trust](./operations-trust/explanation.md) — start here for the
  compliance and audit story.
- [Clients: SDK](./clients/sdk.md) · [CLI](./clients/cli.md) ·
  [MCP](./clients/mcp.md) · [Blueprints](./clients/blueprints.md) — start here to choose
  how you'll talk to the platform.