TypeScript SDK — @neo4j-labs/agent-memory

The TypeScript SDK is a thin HTTP client over the NAMS hosted service. It runs on Node 22+, Bun, Deno, Cloudflare Workers, and Vercel Edge.

Neo4j Labs project

This project is part of Neo4j Labs and is actively maintained, but not officially supported. There are no SLAs or guarantees around backwards compatibility and deprecation. For questions and support, please use the Neo4j Community Forum.

Install

npm install @neo4j-labs/[email protected]
# or
pnpm add @neo4j-labs/[email protected]
bun add @neo4j-labs/[email protected]

Requires Node.js 22 or newer.

The package declares several optional peer dependencies, each needed only for one integration: @ai-sdk/provider for the Vercel AI SDK middleware types, zod and @modelcontextprotocol/sdk for mcp/register, @strands-agents/sdk for the AWS Strands integration, and @opentelemetry/api for tracing. Install only the ones your app uses.

Source bootstrap

The repository’s example projects and the tutorials pin the SDK with file:../.. so they always run against current source. Contributors build the SDK from source for the same reason — it is not a workaround for a missing release. For the complete source-checkout setup, follow the hosted tutorial:

Use Git, Node.js 22.9 or later with npm, and a POSIX shell. The lesson commands load .env with Node’s --env-file-if-exists flag, added in Node.js 22.9; the SDK itself supports Node.js 22. These lessons share one repository checkout. The example-based lessons build the SDK from source so they run against current source; application code, including the MCP lesson’s standalone my-memory-mcp project, installs the published @neo4j-labs/[email protected] package from npm. Keep this checkout for the remaining TypeScript lessons.

For your first lesson, clone and build the SDK:

git clone https://github.com/neo4j-labs/agent-memory.git
cd agent-memory
export AGENT_MEMORY_TUTORIAL_ROOT="$PWD"
cd typescript
npm ci
npm run build
cd "$AGENT_MEMORY_TUTORIAL_ROOT"

Expected: the build finishes without errors and typescript/dist/index.js exists. The example-based lessons use this built SDK; installing an example does not build it. The MCP lesson’s project uses the npm package instead, so it does not depend on this build.

Continuing from another lesson, keep your existing checkout and skip the clone/build block above. From any directory inside that checkout, run:

cd "$(git rev-parse --show-toplevel)"
export AGENT_MEMORY_TUTORIAL_ROOT="$PWD"

Both entry paths finish at the repository root. If you changed the SDK source since the preceding lesson, rebuild it before continuing with an example-based lesson.

Quick start

Get an API key from memory.neo4jlabs.com, set MEMORY_API_KEY, then:

import { MemoryClient } from "@neo4j-labs/agent-memory";

const client = new MemoryClient();

const conv = await client.shortTerm.createConversation({ userId: "alice" });
await client.shortTerm.addMessage(conv.id, "user", "Hello!");

const entity = await client.longTerm.addEntity("Alice Johnson", "person", {
  description: "Software engineer working on graph memory.",
});

const ctx = await client.shortTerm.getContext(conv.id);
console.log(ctx.recentMessages, ctx.observations, ctx.reflections);

For edge runtimes (Cloudflare Workers, Vercel Edge), pass the API key explicitly — see Edge Runtime.

Framework integrations

The first five ship as subpath exports; the NAMS AI provider is a separate npm package.

Integration Import Guide

Vercel AI SDK

@neo4j-labs/agent-memory/middleware/vercel-ai

Vercel AI SDK

MCP tools

@neo4j-labs/agent-memory/mcp

MCP Tools

LangChain JS

@neo4j-labs/agent-memory/integrations/langchain

LangChain JS

Mastra

@neo4j-labs/agent-memory/integrations/mastra

Mastra

AWS Strands

@neo4j-labs/agent-memory/integrations/strands

Strands

NAMS AI provider

@neo4j-labs/nams-ai-provider (separate package)

Choose a NAMS AI provider mode

Source and releases

Looking for the Python SDK?

See Python SDK. The two SDKs share the same memory model and back onto the same NAMS service. Mixed Python + TypeScript agents can read and write the same memory.

Runnable examples

typescript/examples/ holds ten examples. Start with nextjs-memory-chat/ — the flagship full-stack demo: a Next.js 16 App Router assistant on hosted NAMS with a live entity-graph rail, an extraction-status badge and a reasoning-trace drawer. See the task-oriented guide for the four decisions behind it, or clone the example directly. The CI example matrix checks source compatibility with mocked services. The eve commerce demo currently has unsupported hosted preference/fact paths; see its README before using it as a deployment example. Offline checks do not prove npm artifact availability or live-service behavior.

See also