Documentation

API reference, MCP tools, and integration guides.

Get an API Key

Every snippet below expects a nams_... key. Replace the placeholder with your own.

Sign in to open your workspace - a default key is created for you, and the in-console Quick Start fills it into every snippet automatically. Or generate one on the API Keys page. Keys expire after 90 days.

REST: Make your first call

API keys work as Bearer tokens directly - no exchange step needed.

List entities

curl https://memory.neo4jlabs.com/v1/entities \
  -H "Authorization: Bearer nams_YOUR_API_KEY"

1. Create a conversation

curl -X POST https://memory.neo4jlabs.com/v1/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nams_YOUR_API_KEY" \
  -d '{"userId": "user-1"}'

# Response: {"id": "conv-abc-123", ...}

2. Add a message

curl -X POST https://memory.neo4jlabs.com/v1/conversations/CONV_ID/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nams_YOUR_API_KEY" \
  -d '{"role": "user", "content": "John works at Acme Corp in Denver"}'

3. Check extracted entities

curl https://memory.neo4jlabs.com/v1/entities \
  -H "Authorization: Bearer nams_YOUR_API_KEY"

# Returns entities extracted from your messages:
# John (person), Acme Corp (organization), Denver (location)

Connect your agent

Install the nams-hooks plugin for your agent CLI - memory turns on automatically, with no manual MCP config. The agent gets all the NAMS memory, ontology, and workspace tools.

Installs nams-hooks as a Claude Code plugin. The plugin bundles the runtime, hook config, and a credential prompt for your API key.

claude plugin marketplace add neo4j-labs/nams-plugins@latest
claude plugin install nams-hooks@nams-plugins

Then configure and reload it inside Claude Code:

/plugin configure nams-hooks@nams-plugins
/reload-plugins

Set NAMS_API_KEY (and NAMS_BASE_URL=https://memory.neo4jlabs.com) via the plugin's credential prompt, ~/.nams/config.json, or environment variables. Then pick a workspace:

/nams-hooks:nams:workspace use <workspace-id-or-name>

Prefer a raw MCP client config (Claude Desktop, Cursor, Windsurf…)? See the Plugins or MCP Tools tab.

Prefer OAuth 2.0?

MCP clients that support OAuth can authenticate interactively with PKCE - no static key to manage. Discovery endpoints:

# Protected Resource Metadata (RFC 9728)
https://memory.neo4jlabs.com/mcp/.well-known/oauth-protected-resource

# Authorization Server Metadata (RFC 8414)
https://memory.neo4jlabs.com/mcp/.well-known/oauth-authorization-server

# Dynamic Client Registration (RFC 7591)
POST https://memory.neo4jlabs.com/mcp/oauth/register

Access tokens are short-lived (1 hour); clients refresh automatically.

Base URLs

APIhttps://memory.neo4jlabs.com/v1
Authhttps://memory.neo4jlabs.com/v1/auth
MCPhttps://memory.neo4jlabs.com/mcp