@neo4j-labs/agent-memory
v0.6.0
Published
Neo4j Labs: TypeScript client for the Neo4j Agent Memory Service (NAMS)
Keywords
Readme
@neo4j-labs/agent-memory
Package installation. Install with
npm install @neo4j-labs/[email protected](package page). Source lives alongside the Python SDK atneo4j-labs/agent-memory(relocated fromneo4j-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_KEYfrom 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]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);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 });
// ...
},
};🧩 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
});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.
