Troubleshooting

AuthenticationError: Authentication failed: 401

Your MEMORY_API_KEY is missing, mistyped, or revoked.

  • Check the env var is set: node -e 'console.log(Boolean(process.env.MEMORY_API_KEY))' on Node. This checks presence without printing the secret.

  • On Cloudflare Workers or Vercel Edge, process.env is not in scope at module init — pass the key explicitly: new MemoryClient({ apiKey: env.MEMORY_API_KEY }).

  • Sign up for a key at https://memory.neo4jlabs.com if you don’t have one.

  • The error’s requestId field can be quoted in a Community Forum thread for service-side correlation.

NotSupportedError: Method 'X' has no equivalent in the hosted REST API

You’re calling a bridge-only operation against the hosted service (or vice versa). The hosted service exposes a richer surface (three-tier context, entity feedback, graph view); the bridge supports the legacy long-term/reasoning operations from the TCK.

Either:

  • Choose a supported hosted operation using the capability map. There is no direct hosted replacement for every bridge operation, including preferences/facts.

  • Use the bridge transport explicitly for conformance testing — import BridgeTransport from @neo4j-labs/agent-memory/testing and supply it to the MemoryClient constructor.

Entity search returns empty

Long-term entity extraction is asynchronous on the hosted service. After you add a message, the service runs entity extraction in the background and indexes the result for search. There is no fixed completion time guaranteed by this SDK.

For an explicitly known entity, use longTerm.addEntity() and inspect its returned id. To wait for asynchronous extraction, use a bounded waitForExtraction predicate or expected name. An empty result or timeout does not by itself mean message storage failed.

The entity I created came back with a different name

longTerm.addEntity() returned an Entity whose name (or type) doesn’t match what you passed in. This is expected: on the hosted service, addEntity can auto-merge onto a sufficiently similar existing entity instead of creating a new one, and the returned Entity is that canonical entity. Check entity.metadata?.nams_resolution — when present, its resolution is "merged" and merged_into names the entity your create resolved onto. See the long-term memory reference for the full merge and fallback behavior.

Edge runtime: process is not defined

Some edge bundlers throw at build time if process.env appears in imported code. The client guards every process.env read with typeof process !== "undefined" — if you still see this error, it’s likely coming from a different dependency. Run with wrangler dev --verbose (Workers) to see which module is referencing process directly.

TypeScript: Cannot find module '@neo4j-labs/agent-memory/middleware/vercel-ai'

For a repository example, first build the SDK: cd typescript && npm ci && npm run build, then install the example from its directory. Local file: dependencies do not create missing dist exports on installation.

Make sure tsconfig.json has "moduleResolution": "bundler", or use "Node16" / "NodeNext" together with ESM output. The package uses ESM-only subpath exports, which require modern module resolution.

Hook timeout in Vitest e2e tests

If you wrote your own e2e tests against the live hosted service and see "Hook timed out in 10000ms" on beforeAll(client.connect): vitest’s default hookTimeout is 10s, but the first connect on a cold path can take longer. Add this key to your existing vitest.config.ts object — it’s a partial fragment, not a full config file:

test: { testTimeout: 30_000, hookTimeout: 30_000 }

Still stuck?