# Primitives

> A lightweight, on-demand cloud for AI agents. Every agent gets its own isolated filesystem, database, queue, memory, vault, key-value store and object storage, accessible instantly through MCP. Snapshot, fork and pause any primitive on its own.

## Getting started

- [Introduction](https://useprimitives.com/docs): What Primitives is, the seven primitive types, and how a group collects as many of each as you need.
- [Quickstart](https://useprimitives.com/docs/quickstart): Run the engine locally or use the cloud, create a group, and connect an MCP client.
- [Groups](https://useprimitives.com/docs/concepts/groups): The unit of isolation: primitives by id and name, per-primitive snapshots, forks and pause, access and the audit trail.
- [Audit log](https://useprimitives.com/docs/concepts/audit): What the audit trail records, filtering it by group, primitive, action, actor and time, and retention per plan.

## Primitives

- [Database](https://useprimitives.com/docs/primitives/database): Named SQLite databases, as many per group as you need: parameterized SQL, atomic batches, branches and export.
- [Filesystem](https://useprimitives.com/docs/primitives/filesystem): Named virtual filesystems with glob, full-text search and directory forks that share large files.
- [Queue](https://useprimitives.com/docs/primitives/queue): Durable queues with leases, heartbeats, retries, delays and dead letters.
- [Memory](https://useprimitives.com/docs/primitives/memory): Typed long-term memory with hybrid recall, owners, supersede and duplicate consolidation.
- [Vault](https://useprimitives.com/docs/primitives/vault): Secrets injected by reference: use them without ever reading them.
- [KV](https://useprimitives.com/docs/primitives/kv): A key-value store with JSON or byte values, TTLs, versions for compare-and-swap, atomic increments and batches.
- [Storage](https://useprimitives.com/docs/primitives/storage): Object storage with metadata, ETags, range reads and signed URLs for token-free uploads and downloads.

## MCP

- [MCP overview](https://useprimitives.com/docs/mcp): Every primitive exposed as MCP tools over Streamable HTTP or stdio, scoped to one group.
- [Connect a client](https://useprimitives.com/docs/mcp/setup): Add Primitives to Claude Code, Cursor or any MCP client, locally or in the cloud.
- [Tools reference](https://useprimitives.com/docs/mcp/tools): Every MCP tool, what it does, and whether it writes.
- [Auth & scoping](https://useprimitives.com/docs/mcp/auth): Scoped API keys, OAuth for MCP clients, tool allowlists and how secrets stay out of context.

## Guides

- [Fork and snapshot primitives](https://useprimitives.com/docs/guides/forking): Snapshot, fork or branch individual primitives to explore safely, then keep or discard the result.
- [Use with a sandbox](https://useprimitives.com/docs/guides/sandboxes): Use a group from E2B, Daytona, Modal or your own containers with a scoped API key.

## Reference

- [TypeScript SDK](https://useprimitives.com/docs/reference/typescript): The @primitives/sdk client: groups and every primitive's methods.
- [Python SDK](https://useprimitives.com/docs/reference/python): The useprimitives package (import primitives): an async client for every primitive.
- [REST API](https://useprimitives.com/docs/reference/api): Authentication, errors, rate limits, usage and plan limits, pagination and every /v1 endpoint.

## MCP tools

Server: https://mcp.useprimitives.com/mcp (the group is resolved from the API key or OAuth grant)

- `primitive_list`: List this group's primitives (id, name, type). Call it first: other tools take one as `primitive`.
- `primitive_create`: Create a named database, filesystem, queue, memory, vault, key-value store or object storage in this group.
- `primitive_snapshot`: Create a named restore point for one primitive.
- `primitive_fork`: Copy one primitive into a new primitive in this group.
- `db_query`: Run a read-only SQL query and return rows.
- `db_exec`: Execute a write statement or migration.
- `db_branch`: Create, promote or discard a database branch.
- `fs_read`: Read a file or list a directory.
- `fs_write`: Write, move or delete files.
- `fs_search`: Glob and full-text search across the workspace.
- `fs_fork`: Fork a directory for a sub-agent; large files are shared, not copied.
- `queue_send`: Enqueue a message with optional delay and dedupe key.
- `queue_receive`: Lease the next message from a queue.
- `queue_ack`: Acknowledge, retry or dead-letter a leased message.
- `memory_remember`: Store a typed memory (episodic, semantic, procedural).
- `memory_recall`: Hybrid search over memories, filtered by kind and tags.
- `memory_forget`: Delete or supersede a memory.
- `vault_list`: List secret names granted in a vault. Never values.
- `vault_use`: Make an HTTP request with a secret injected by reference.
- `kv_get`: Read one key or many (value, version, expiry).
- `kv_list`: List keys by prefix, optionally with values; paginated by cursor.
- `kv_set`: Set a key (JSON or base64 bytes) with optional TTL and compare-and-swap, set many at once, or atomically increment.
- `kv_delete`: Delete one or more keys, optionally only at a given version.
- `storage_list`: List objects by prefix; with a delimiter, folders roll up into prefixes.
- `storage_read`: Read an object's bytes (text or base64, capped) or just its metadata.
- `storage_write`: Put, copy or delete objects, with content type, metadata and if-match/if-none-match conditions.
- `storage_sign`: Create a time-limited URL to download or upload one object without a token.