Generated API Client and Primitive Memories

Reach for the generated API client when client.send/reply/forward don't cover the operation you need, for example calling getAccount directly or reading account-level settings. Use client.memories any time you need durable, org- or function-scoped JSON storage that survives across webhook invocations.

Call any operation with PrimitiveApiClient#

PrimitiveApiClient is a host-aware, authenticated HTTP client generated from Primitive's OpenAPI spec. It exposes every operation in the API, not just the ones wrapped by the high-level send/reply/forward client. Both the CLI and @primitivedotdev/sdk bundle the same underlying implementation from the workspace-internal @primitivedotdev/api-core package (never published on its own); see What is API Core? and the shared PrimitiveApiClient reference for the client's construction options and its PrimitiveApiError shape.

1. 1

   Import the client and a generated operation#

   Import PrimitiveApiClient and any generated operation function from @primitivedotdev/sdk/api:

   import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";
   

2. 2

   Construct the client with your API key#

   const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY! });
   

3. 3

   Call the operation, passing the client's underlying fetch client#

   Every generated operation function takes client: api.client and returns the parsed result:

   const result = await getAccount({ client: api.client });
   
   console.log(result.data);
   

Use the generated API client for anything outside the email send/receive/webhook flow: account settings, domains, semantic search, or any other operation exposed by the operation manifest.

Primitive Memories#

Primitive Memories are durable JSON key-value records, scoped to your org by default. The high-level API client exposes them under client.memories, built on top of the generated setMemory, getMemory, searchMemories, and deleteMemory operations.

Set up the client#

import { createPrimitiveClient } from "@primitivedotdev/sdk/api";

const client = createPrimitiveClient({ apiKey: process.env.PRIMITIVE_API_KEY! });

Set a memory#

await client.memories.set({
  key: "thread:latest",
  value: { email_id: "em_123" },
});

Set a function-scoped memory by passing an explicit scope. The id here is the function id UUID, not the function name:

await client.memories.set({
  key: "state",
  value: { step: 2 },
  scope: { type: "function", id: functionId },
});

value must be a JSON value: a string, finite number, boolean, null, an array, or a plain object. undefined, bigint, NaN, Infinity, class instances, and cyclic values are rejected with a TypeError before any request is sent. See the shared Memory Value Validation Helper (isMemoryJsonValue) if you want to validate a value ahead of time.

Get a memory#

const memory = await client.memories.get("thread:latest");

Search memories by key prefix#

const page = await client.memories.search({
  prefix: "thread:",
  includeValue: false,
});

Delete a memory#

await client.memories.delete("thread:latest");

When to use the raw generated operations#

The high-level client.memories.* methods take the memory fields directly ({ key, value }, not the generated operation's { client, body, query } shape). Passing the generated shape into client.memories.set throws a TypeError naming the mistake, so the failure is loud instead of silently forwarding the wrong body.

If you want the exact OpenAPI operation shape instead, for example to control query parameters not exposed by the wrapper, import the raw operations directly:

import { setMemory, getMemory, searchMemories, deleteMemory } from "@primitivedotdev/sdk/api";

These remain exported from @primitivedotdev/sdk/api for callers who need the generated request/response types verbatim.

Next steps#