---
title: "Generated API Client and Primitive Memories"
canonical: "https://test.abhinandan.one/node-sdk-api-client"
markdown_url: "https://test.abhinandan.one/node-sdk-api-client.md"
publisher: "Primitive SDKs"
kind: "guide"
content_type: "reference"
category: "Node.js SDK"
description: "Call any generated Primitive operation with PrimitiveApiClient and store durable JSON key-value records with client.memories.set/get/search/delete."
keywords: ["PrimitiveApiClient", "@primitivedotdev/sdk/api", "client.memories", "createPrimitiveClient", "Primitive Memories", "setMemory getMemory searchMemories deleteMemory"]
last_modified: "2026-08-11T18:54:50.093263+00:00"
published_at: "2026-08-11T18:54:49.883243+00:00"
source_files:
  - "sdk-node/src/api/index.ts"
sections:
  - {anchor: "call-any-operation-with-primitiveapiclient", title: "Call any operation with PrimitiveApiClient"}
  - {anchor: "step-import-the-client-and-a-generated-operation", title: "Import the client and a generated operation"}
  - {anchor: "step-construct-the-client-with-your-api-key", title: "Construct the client with your API key"}
  - {anchor: "step-call-the-operation-passing-the-clients-underlying-fetch-client", title: "Call the operation, passing the client's underlying fetch client"}
  - {anchor: "primitive-memories", title: "Primitive Memories"}
  - {anchor: "set-up-the-client", title: "Set up the client"}
  - {anchor: "set-a-memory", title: "Set a memory"}
  - {anchor: "get-a-memory", title: "Get a memory"}
  - {anchor: "search-memories-by-key-prefix", title: "Search memories by key prefix"}
  - {anchor: "delete-a-memory", title: "Delete a memory"}
  - {anchor: "when-to-use-the-raw-generated-operations", title: "When to use the raw generated operations"}
  - {anchor: "next-steps", title: "Next steps"}
---

> Documentation index: https://test.abhinandan.one/llms.txt

# Generated API Client and Primitive Memories

Call any Primitive HTTP endpoint directly through the generated, host-aware PrimitiveApiClient, and use client.memories to store, fetch, search, and delete durable JSON records scoped to your org or a Primitive Function.

Reach for the generated API client when [`client.send`/`reply`/`forward`](https://test.abhinandan.one/node-sdk-sending-email.md) 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.

> **Note:** The high-level `send`/`reply`/`forward` surface is the default way to interact with the Primitive API from application code. Drop to the generated client only for advanced or uncommon operations, see [What is the Primitive Node.js SDK?](https://test.abhinandan.one/node-sdk-overview.md) for how the subpath exports map to each use case.

## 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?](https://test.abhinandan.one/api-core-overview.md) and the shared [PrimitiveApiClient reference](https://test.abhinandan.one/primitive-api-client.md) for the client's construction options and its `PrimitiveApiError` shape.

### 1. Import the client and a generated operation

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

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

### 2. Construct the client with your API key

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

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

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

```ts
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](https://test.abhinandan.one/operation-manifest.md).

## 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.

> **Tip:** Inside a Primitive Function, an omitted scope resolves to that Function's id automatically. Passing an explicit function scope elsewhere requires the function id UUID, not the function name.

### Set up the client

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

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

### Set a memory

```ts
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:

```ts
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](https://test.abhinandan.one/memory-json-value-helper.md) (`isMemoryJsonValue`) if you want to validate a value ahead of time.

### Get a memory

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

### Search memories by key prefix

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

> **Warning:** `client.memories.search` is key-prefix search, not free-text or semantic search. It lists memory records whose key starts with `prefix`. For searching mail content, use `client.semanticSearch(...)` instead.

### Delete a memory

```ts
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:

```ts
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.