@neo4j-labs/agent-memory

Package installation. Install with npm install @neo4j-labs/[email protected] (package page). Source lives alongside the Python SDK at neo4j-labs/agent-memory (relocated from neo4j-labs/agent-memory-tck).

TypeScript client for the Neo4j Agent Memory Service — short-term, long-term, and reasoning memory for AI agents, backed by Neo4j.

⚠️ Neo4j Labs Project

This project is part of Neo4j Labs and is actively maintained, but not officially supported. There are no SLAs, backward-compatibility guarantees, or scheduled deprecation commitments. APIs may change without notice. For questions and support, please use the Neo4j Community Forum.

The Python and TypeScript packages in this repository are versioned and released independently; the status badge above reflects this package's own maturity, not the Python SDK's.

✨ Features

• Three memory subclients in one client: short-term (conversations, messages, three-tier context), long-term (entities, search, returned graph views), and reasoning (steps, traces, provenance, tool calls).
• Zero-config construction — reads MEMORY_API_KEY from the environment and defaults to the hosted service.
• Works in Node 22+, Bun, Deno, Cloudflare Workers, and Vercel Edge.
• Five framework integrations: Vercel AI SDK middleware, MCP tools, LangChain JS, Mastra, and AWS Strands Agents.
• Built-in request logging, request-id correlation, and edge-friendly fetch-only transports.
• TCK Bronze conformance verified by the agent-memory-tck cross-language test suite.

📦 Installation

npm install @neo4j-labs/[email protected]
Copy

Requires Node.js 22+. This README describes the current source; changes made since the 0.5.0 release are listed under Unreleased in the CHANGELOG. The source examples build the SDK before installing their local file: dependency.

🚀 Quick start

Get an API key from memory.neo4jlabs.com, export it as 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);
Copy

On the edge

Edge runtimes differ in how they expose environment variables: Cloudflare Workers pass bindings to the handler, while others (such as Vercel Edge) may provide process.env. Pass the key explicitly:

export default {
  async fetch(req: Request, env: { MEMORY_API_KEY: string }) {
    const client = new MemoryClient({ apiKey: env.MEMORY_API_KEY });
    // ...
  },
};
Copy

🧩 Integrations

All five ship as subpath exports. See each integration's example and how-to guide for a runnable walkthrough.

Integration	Import	Example
Vercel AI SDK	@neo4j-labs/agent-memory/middleware/vercel-ai	examples/vercel-ai
MCP tools	@neo4j-labs/agent-memory/mcp, …/mcp/register	examples/mcp
LangChain JS	@neo4j-labs/agent-memory/integrations/langchain	examples/langchain
Mastra	@neo4j-labs/agent-memory/integrations/mastra	examples/mastra
AWS Strands	@neo4j-labs/agent-memory/integrations/strands	examples/strands

📖 Documentation

• TypeScript SDK landing page
• Start here: store and read back hosted memory
• Build an agent with memory
• How-to guides — authentication, edge deployment, error handling, observability, framework integrations
• Concept: short-term vs long-term vs reasoning memory
• Architecture overview
• Troubleshooting

Full API reference (TypeDoc) is bundled with the docs site — see the TypeScript API reference.

🔧 Configuration

The client accepts a small options bag:

new MemoryClient({
  endpoint: "https://memory.neo4jlabs.com/v1",  // default
  apiKey: "nams_...",                            // falls back to MEMORY_API_KEY env
  timeout: 30_000,                               // ms; default 30s
  headers: { "X-My-Trace": "..." },              // additional request headers
  logger: (event) => console.log(event),         // request/response/error events
});
Copy

connect() is optional — the first request acts as the implicit auth check. Call it explicitly if you prefer fail-fast at startup.

🤝 Contributing

We welcome contributions. See the repo-root CONTRIBUTING.md for the development setup, test commands, and PR conventions — there is a dedicated "TypeScript contributions" section covering Node setup, vitest, linting, and the TCK bridge.

This package lives alongside the Python SDK (neo4j-agent-memory) in neo4j-labs/agent-memory. The two SDKs implement the same memory model and share the same backend (NAMS). The cross-language behavioral contract is defined and certified by the agent-memory-tck spec repo, which consumes this package from npm.

💬 Support

• Neo4j Community Forum — questions and discussion (primary)
• GitHub Issues — bug reports and feature requests
• Security vulnerabilities: see SECURITY.md

📝 License

Apache-2.0 — see LICENSE.