README.md

@neo4j-labs/agent-memory

Now on npm. Install with npm install @neo4j-labs/agent-memory (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 or guarantees around backwards compatibility and deprecation. For questions and support, please use the Neo4j Community Forum.

✨ Features

• Three memory subclients in one client: short-term (conversations, messages, three-tier context), long-term (entities, search, relationships, graph view), 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 20+, 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/agent-memory

Requires Node.js 20+.

🚀 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);

On the edge

Edge runtimes (Cloudflare Workers, Vercel Edge) expose environment variables via the request handler scope, not 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 });
    // ...
  },
};

🧩 Integrations

All four 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	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
• Tutorial: First Agent Memory (TypeScript)
• 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 published at neo4j-labs.github.io/agent-memory/typescript/.

🔧 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
});

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.