Primitives documentation

Primitives gives every AI agent its own isolated infrastructure: databases, filesystems, durable queues, long-term memory, a vault of secrets it can use but never read, key-value stores and object storage. A group is a collection of primitives (as many databases, filesystems, queues, memories, vaults, key-value stores and object stores as you need) reached with one API key, and the agent reaches them through the TypeScript SDK, the Python SDK, the REST API or MCP.

The engine is open source and runs on your machine with primitives dev. The hosted cloud at api.useprimitives.com runs the same engine for you.

Why per-agent infrastructure

Agents that share a database, a bucket and an API key also share each other's mistakes. One bad migration or rm -rf reaches every agent, and a leaked key is leaked everywhere. Primitives gives each agent its own world:

• Isolated. An API key scoped to a group reaches exactly that group, and only the tools on its allowlist.
• Forkable. Fork any primitive on its own, into the same group or a fresh one for a sub-agent, or branch a database or a directory, to try risky changes safely.
• Snapshots. Take a named restore point of any primitive and roll it back with one call. Pause a primitive to freeze it.
• Audited. Writes, queue state changes, every secret use and signed uploads land in the group's audit trail.

The primitives

Seven types, and a group can hold any number of each, every one with its own name:

Groups

A group is a collection of primitives for one agent, task or session, reached with one key. It starts empty; you create the primitives you need inside it, each with a name:

import { Primitives } from '@primitives/sdk';

const p = new Primitives(); // http://localhost:7777, or pass { token: 'pk_…' } for the cloud

const group = await p.groups.create({ name: `agent-${agentId}` });
const tasks = await group.db.create('tasks');
const scratch = await group.db.create('scratch');   // a second database, isolated from the first
const workspace = await group.fs.create('workspace');

await tasks.exec('create table tasks (id integer primary key, title text)');
const { rows } = await tasks.sql`select count(*) as n from tasks`;

await tasks.snapshot('before-run');                 // snapshot, fork and pause any primitive on its own
const trial = await workspace.fork({ name: 'workspace-try' });

A group itself only has a name, its primitives and its keys: create, list, get and delete it. Snapshots, forks and pause belong to each primitive.

Ways to connect

All four run through the same API. A table created over MCP can be queried from the SDK, and a job sent over REST can be consumed in Python.

Local and cloud

Next steps

• Quickstart: run the engine and create your first group in a few minutes.
• Groups: primitives by id and name, and how each one snapshots, forks and pauses.
• MCP overview: give an MCP client its own group.
• Queue: durable work for long-running agents.
• Use with a sandbox: reach a group from your code sandbox.
• TypeScript SDK: the full client reference.