SDKs · Node.js

Node.js Quickstart

Install the Node.js SDK, configure trusted scope, add one memory, and retrieve it. The example is plain JavaScript for Node.js 18 or newer.

Before you start

Node.js 18 or newer.
A MemorySync API key from the dashboard. Creating the key while a project is selected locks the key to that project, so this quickstart does not need MEMORYSYNC_PROJECT_ID.
An ES module file: "type": "module" in package.json, or a .mjs file. The example uses import and top-level await.
A stable opaque ID for the application user.

Install the package

terminal

npm install memorysync-sdk

Set environment variables

PowerShell

$env:MEMORYSYNC_API_KEY="your-api-key"

Add and query memory

quickstart.mjs

import { MemorySyncClient } from "memorysync-sdk";

const apiKey = process.env.MEMORYSYNC_API_KEY;
if (!apiKey) {
  throw new Error("Set MEMORYSYNC_API_KEY to your server-side API key.");
}

const client = new MemorySyncClient({
  apiKey,
  baseUrl: "https://api.memorysync.io",
  // Omit when the API key is already locked to a project.
  projectId: process.env.MEMORYSYNC_PROJECT_ID || undefined,
  endUserId: "usr_7f3a9c2e",
});

const result = await client.add({
  text: "The user prefers concise answers.",
  source: "profile",
  tags: ["preference"],
});

if ("status" in result && result.status === "skipped") {
  console.log("Skipped:", result.reason);
} else {
  console.log("Memory ID:", result.id);
}

const response = await client.query({
  query: "How should I format the answer?",
  k: 5,
});

for (const memory of response.memories) {
  console.log(memory.id, memory.text);
}

Understand the result

Quickstart outcomes

CREATED

A MemoryRecord is returned

Use its numeric ID for later targeted operations.

SKIPPED

No new record was created

Read the reason from the documented skipped response.

EMPTY

Query returned no candidates

An empty memories array is a successful result.

ERROR

A typed error was thrown

Correct permanent failures or apply the production recovery policy.

Keep the integration safe

Resolve project and end-user scope from authenticated server state.
Use the same scope for writes and reads.
Store durable context, not secrets or one-request instructions.
Delimit returned memory as untrusted context before sending it to a model.

Continue

Node.js Memory Client

Learn all 35 memory operations.

Node.js Types & Errors

Use TypeScript narrowing and failure classes.

Memory API Reference

Inspect exact request and response contracts.

Production Patterns

Prepare scope, retry, and logging behavior.

Was this page helpful?

← Previous

Node.js SDK

Memory Client