Node SDK

Add & Query

The two methods every integration starts with. add stores a single piece of text; query recalls semantically. Both take typed request objects and return typed response objects, so autocomplete in your editor is the documentation you actually use.

add(req: AddRequest)

TYPESCRIPT

const result = await client.add({
  text: "The launch is on Friday.",  // required
  source: "slack",                    // optional label
  tags: ["plan", "launch"],           // optional string[]
  importance: 0.8,                    // optional 0..1 hint
  sessionId: "conv-42",               // optional, ties to chat session
  metadata: { channel: "team" },      // optional record
  endUserId: undefined,               // optional, multi-tenant only
});

Only text is required. Everything else is a hint.

add returns one of two things

TYPESCRIPT

const result = await client.add({ text: "ok" });

if ("status" in result && result.status === "skipped") {
  console.log("nothing stored:", result.reason);
} else {
  console.log("stored as id", result.id, "isSummary?", result.isSummary);
}

query(req: QueryRequest)

TYPESCRIPT

const hits = await client.query({
  query: "when is launch",
  k: 5,
  filters: { tags: ["launch"], source: "slack" },
  sessionId: undefined,
  traversalDepth: 1,                // optional, 1..3 (default 2); follow related memories
});

for (const m of hits.memories) {
  console.log(m.id, m.text, m.score);
}
console.log("server latency:", hits.latencyMs, "ms");

The result is a QueryResponse with memories, an optional context string, the server\u2019s latencyMs, and the sessionId that was actually used.

Every filter you can pass

Filter	Type	Effect
tags	string[]	Match any tag in the array.
source	string	Match an exact source label.
memoryType	string	Restrict to a specific extracted type.
since	ISO datetime string	Only memories created at or after this time.
until	ISO datetime string	Only memories created at or before this time.
includeSummaries	boolean	Whether summary rows are eligible.
tier	"hot" \| "warm" \| "cold"	Restrict to one storage tier.

How big should k be?

For chat-style recall feeding a prompt: k between 3 and 10.
For populating a UI list: k up to a few dozen.
Valid range is 1 to 50 (default 5). Values outside that range are rejected with HTTP 422 ValidationError — there is no silent clamping.

Tying calls to a chat session

TYPESCRIPT

const sessionId = "conv-42";

await client.add({ text: "user prefers concise replies", sessionId });
const hits = await client.query({ query: "preferences", sessionId, k: 3 });

Pitfalls worth flagging

Two common mistakes

Forgetting await (you get the Promise back, not the result) and assuming add always returns a stored memory (the gating pass can return status: "skipped"). Both bite once and never again.

← Previous

Install & Auth

Bulk Operations