n8n-nodes-xmemory

xmemory is a memory interface with natural-language inputs and outputs, backed by schema under the hood.

Community n8n node for xmemory read, write, and create instance operations. This overview gives detailed description of xmemory.

n8n is a fair-code licensed workflow automation platform.

Installation

Check out installation guide and register your interest at xmemory website to get an API key.

Operations

• Create Instance: Calls POST /clusters/{cluster_id}/instances. Pick a Cluster (from the list by name, or by ID), and provide an Instance Name and a valid XMD Schema (JSON or YAML). Xmemory requires a schema to create an instance.
• Write: Calls POST /instances/{instance_id}/write. Writes text into memory using the instance schema. Fast (default) and deep extraction modes are supported. Optionally pass a Trace ID and toggle Diff Engine.
• Read: Calls POST /instances/{instance_id}/read. Queries memory using a free-form natural-language query. Supported modes: single-answer (short summary), raw-tables (structured SQL-like representation), xresponse (schema-based structured response). Optionally restrict the read to specific objects via Scope Objects (identified by their user-defined primary key) together with a Relations Scope (no_relations or all_relations), and pass a Trace ID.

Every operation returns the xmemory API payload directly: the response envelope ({ids, items, errors, console_url}) is unwrapped, so downstream nodes receive the operation result (read result, write_id, created instance, …). Errors are raised as node errors.

When a Read query bundles several independent questions, the server may decompose it into sub-queries and answer each one. The read result keeps the combined reader_result and adds reader_results — one entry per sub-query ({ sub_query, reader_result, error }), so downstream nodes can consume each answer separately. A single-intent query yields one entry.

How account errors surface

When the xmemory accounts API rejects a call, the node turns the structured error envelope (errors[0].code / details) into a readable node-error message rather than a bare HTTP status:

• Quota exhausted (HTTP 402, code QUOTA_EXCEEDED): the message notes the daily or monthly limit and, when the server provides one, a retry after Ns hint. This is not retried automatically — the tenant has used up its plan allowance.
• Trial ended / subscription lapsed (HTTP 402, code TRIAL_ENDED): the message hints to subscribe to continue. Not retryable.
• Rate limited (HTTP 429, code RATE_LIMITED): a genuine velocity limit; the message labels it as such. n8n's HTTP layer may itself retry 429s, but the node adds no extra retry logic.

If you enable workflow-level Retry On Fail, note that quota and trial errors are not transient and will keep failing until the underlying account state changes.

Credentials

• Base URL: xmemory API base URL, for example https://api.xmemory.ai.
• API Key: API key used to authenticate against the xmemory API (sent as Authorization: Bearer <key>). Register your interest at xmemory.ai; we will reach out to discuss your scenario and issue an API key.

Every request this node makes also carries X-Xmemory-Client: n8n-nodes-xmemory/<version> (n8n), so xmemory can tell this node's traffic apart from generic HTTP clients. It is a dedicated header rather than User-Agent, which n8n and its HTTP stack set for themselves.

Resources

• tutorial for xmemory usage from n8n
• xmemory documentation
• n8n community nodes documentation

Compatibility

This package targets the current community-node API version (n8nNodesApiVersion: 1). Validate against the n8n version you run in your environment.

Releasing

Releases are manual and version-driven:

1. Bump the version in package.json via a pull request and merge it to main. Keep it to three numeric components of at most three digits, without leading zeros (a prerelease or build suffix is fine) — the build fails otherwise, because the API records no version for anything else.
2. Follow CLIENT-HEADER-VERIFY.md to confirm the X-Xmemory-Client header this node sends actually reaches the API on all three request paths. Nothing in this repo can check that — the code that applies the credential's headers lives in the n8n runtime, which this package does not depend on. Do this before publishing; an npm version cannot be replaced once it is out.
3. Run the Publish workflow (Actions → Publish → Run workflow, or gh workflow run publish.yml).

The workflow publishes the current package.json version to npm and then pushes a matching git tag (X.Y.Z). If a tag for that version already exists, the run fails — bump the version first.