{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/node-sdk-api-client","markdown_url":"https://test.abhinandan.one/node-sdk-api-client.md","article":{"id":"5fe7f2f3-cc0d-411e-8c6f-df794e3c15d3","article_slug":"node-sdk-api-client","parent_article_slug":null,"parent_article_title":null,"kind":"guide","published_at":"2026-08-11T18:54:49.883243+00:00","keywords":["PrimitiveApiClient","@primitivedotdev/sdk/api","client.memories","createPrimitiveClient","Primitive Memories","setMemory getMemory searchMemories deleteMemory"],"meta_description":"Call any generated Primitive operation with PrimitiveApiClient and store durable JSON key-value records with client.memories.set/get/search/delete.","og_image_url":null,"source_file_paths":["sdk-node/src/api/index.ts"],"recording_id":null,"replayable":false,"task_name":"Generated API Client and Primitive Memories","category":"Node.js SDK","summary":null,"description":"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.","content_kind":"repo_page","content_markdown":"Reach for the generated API client when [`client.send`/`reply`/`forward`](node-sdk-sending-email) 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.\n\n<Note>\n\nThe 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?](node-sdk-overview) for how the subpath exports map to each use case.\n\n</Note>\n\n## Call any operation with PrimitiveApiClient\n\n`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?](api-core-overview) and the shared [PrimitiveApiClient reference](primitive-api-client) for the client's construction options and its `PrimitiveApiError` shape.\n\n<Steps>\n\n<Step title=\"Import the client and a generated operation\">\n\nImport `PrimitiveApiClient` and any generated operation function from `@primitivedotdev/sdk/api`:\n\n```ts\nimport { PrimitiveApiClient, getAccount } from \"@primitivedotdev/sdk/api\";\n```\n\n</Step>\n\n<Step title=\"Construct the client with your API key\">\n\n```ts\nconst api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY! });\n```\n\n</Step>\n\n<Step title=\"Call the operation, passing the client's underlying fetch client\">\n\nEvery generated operation function takes `client: api.client` and returns the parsed result:\n\n```ts\nconst result = await getAccount({ client: api.client });\n\nconsole.log(result.data);\n```\n\n</Step>\n\n</Steps>\n\nUse 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](operation-manifest).\n\n## Primitive Memories\n\nPrimitive 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.\n\n<Tip>\n\nInside 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.\n\n</Tip>\n\n### Set up the client\n\n```ts\nimport { createPrimitiveClient } from \"@primitivedotdev/sdk/api\";\n\nconst client = createPrimitiveClient({ apiKey: process.env.PRIMITIVE_API_KEY! });\n```\n\n### Set a memory\n\n```ts\nawait client.memories.set({\n  key: \"thread:latest\",\n  value: { email_id: \"em_123\" },\n});\n```\n\nSet a function-scoped memory by passing an explicit `scope`. The `id` here is the function id UUID, not the function name:\n\n```ts\nawait client.memories.set({\n  key: \"state\",\n  value: { step: 2 },\n  scope: { type: \"function\", id: functionId },\n});\n```\n\n`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](memory-json-value-helper) (`isMemoryJsonValue`) if you want to validate a value ahead of time.\n\n### Get a memory\n\n```ts\nconst memory = await client.memories.get(\"thread:latest\");\n```\n\n### Search memories by key prefix\n\n```ts\nconst page = await client.memories.search({\n  prefix: \"thread:\",\n  includeValue: false,\n});\n```\n\n<Warning>\n\n`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.\n\n</Warning>\n\n### Delete a memory\n\n```ts\nawait client.memories.delete(\"thread:latest\");\n```\n\n### When to use the raw generated operations\n\nThe 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.\n\nIf you want the exact OpenAPI operation shape instead, for example to control query parameters not exposed by the wrapper, import the raw operations directly:\n\n```ts\nimport { setMemory, getMemory, searchMemories, deleteMemory } from \"@primitivedotdev/sdk/api\";\n```\n\nThese remain exported from `@primitivedotdev/sdk/api` for callers who need the generated request/response types verbatim.\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"PrimitiveApiClient\" href=\"primitive-api-client\">\n\nFull reference for the host-aware client's construction options and PrimitiveApiError shape.\n\n</Card>\n\n<Card title=\"Operation Manifest Reference\" href=\"operation-manifest\">\n\nLook up every generated operation's command name, method, path, and inlined request/response schemas.\n\n</Card>\n\n<Card title=\"Agent Accounts\" href=\"node-sdk-agent-accounts\">\n\nCreate zero-touch agent accounts and upgrade them through the email-claim flow.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Forwarding Email\" href=\"node-sdk-sending-email\">\n\nThe default high-level surface for outbound mail, when you don't need the generated client.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/sdk-node/src/api/index.ts","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+Generated+API+Client+and+Primitive+Memories&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fnode-sdk-api-client","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}