From 84a1318f710659f289245660640936d115df6a2b Mon Sep 17 00:00:00 2001 From: kartik-mem0 Date: Wed, 29 Jul 2026 22:33:55 +0530 Subject: [PATCH] docs(n8n,zapier): rewrite both integration pages in the task-first house style Both pages opened with an endpoint table and left the reader to work out setup themselves. Restructure them the way the stronger integration pages read: problem statement, prerequisites with API-key links, a Steps-based setup with a verification callout, a runnable quickstart, then the field reference, then troubleshooting. Every documented field is checked against the source rather than a schema: the Zapier action input fields come from src/creates and src/searches, and Wait for Completion is correctly documented as off by default there (it is on by default in n8n). Adds the n8n self-hosted-only prerequisite and the Zapier App Directory availability note, both of which users hit first. --- docs/integrations/n8n.mdx | 125 ++++++++++++++++++++++++---------- docs/integrations/zapier.mdx | 126 +++++++++++++++++++++++++++++------ 2 files changed, 195 insertions(+), 56 deletions(-) diff --git a/docs/integrations/n8n.mdx b/docs/integrations/n8n.mdx index 1fe8ed568..ad1c02951 100644 --- a/docs/integrations/n8n.mdx +++ b/docs/integrations/n8n.mdx @@ -3,46 +3,94 @@ title: n8n description: "Add long-term memory to n8n workflows and AI Agents with the Mem0 community node, no code required." --- -The [`@mem0/n8n-nodes-mem0`](https://www.npmjs.com/package/@mem0/n8n-nodes-mem0) community node brings [Mem0](https://mem0.ai) memory to [n8n](https://n8n.io). Add, search, and manage long-term memories inside any workflow, and use it as a tool for the n8n AI Agent. +Your n8n workflows start from zero on every run. The [`@mem0/n8n-nodes-mem0`](https://www.npmjs.com/package/@mem0/n8n-nodes-mem0) community node fixes that: store durable facts as memories, recall them in any later run, and hand the node to an [n8n AI Agent](https://docs.n8n.io/advanced-ai/) as a tool so it can remember and recall on its own. ## Overview -The node wraps the hosted Mem0 REST API and supports six operations on the **Memory** resource: +1. Install the node from n8n's community nodes panel. +2. Connect your Mem0 API key once as a credential. +3. Drop a **Mem0** node into any workflow to add, search, or manage memories. +4. Optionally attach it to an **AI Agent** node, where it becomes a tool the agent calls itself. -| Operation | Endpoint | -| --- | --- | -| **Add** | `POST /v3/memories/add/` | -| **Search** | `POST /v3/memories/search/` | -| **Get** | `GET /v1/memories/{id}/` | -| **Get Many** | `POST /v3/memories/` | -| **Update** | `PUT /v1/memories/{id}/` | -| **Delete** | `DELETE /v1/memories/{id}/` | +## Prerequisites -It is marked `usableAsTool`, so the n8n AI Agent (Tools Agent) can call it directly to remember and recall information. +1. A Mem0 API key from the API Keys dashboard (sign up at app.mem0.ai if you do not have an account). +2. A **self-hosted** n8n instance. Installing community nodes from npm is a self-hosted feature; n8n Cloud only offers nodes that n8n has verified. +3. Owner access to that instance, since only instance owners can install community nodes. ## Installation -Install it like any n8n community node: + + + In n8n, go to **Settings → Community Nodes** and select **Install**. + + + Enter `@mem0/n8n-nodes-mem0`, tick the risk acknowledgement, and select **Install**. + + + Add a new **Mem0 API** credential and paste your API key. Leave **Base URL** at `https://api.mem0.ai` unless you run Mem0 somewhere else. + + -1. In n8n, go to **Settings → Community Nodes → Install**. -2. Enter `@mem0/n8n-nodes-mem0` and confirm. + + **Verify the install:** search the nodes panel for `Mem0`. The node should appear with a **Memory** resource offering Add, Search, Get, Get Many, Update, and Delete. + -The node then appears in the nodes panel under the AI category. +## Quickstart -## Authentication +A two-node workflow that writes a memory and reads it back: -Create a **Mem0 API** credential in n8n: +```text +Manual Trigger → Mem0 (Add) → Mem0 (Search) +``` -- **API Key**: from the Mem0 API Key dashboard. Sent as `Authorization: Token `. -- **Base URL**: defaults to `https://api.mem0.ai`. + + + Add a **Mem0** node, keep **Operation: Add**, set **User ID** to `alice`, and add one message with **Role** `user` and **Content**: + + `I am vegetarian and I never eat mushrooms.` + + + Add a second **Mem0** node with **Operation: Search**, **User ID** `alice`, and **Query** `what does the user eat?`. + + + Select **Test workflow**. The Search node returns the extracted dietary memory. + + + + + Extraction is asynchronous. The Add node's **Wait for Completion** option is on by default, so it polls until extraction finishes before the next node runs. If you turn it off, allow a few seconds before searching for what you just wrote. + + +## Use it as an AI Agent tool + +The node is marked `usableAsTool`, so an n8n **AI Agent** (Tools Agent) can call it without any wiring on your side: + +```text +Chat Trigger → AI Agent ──tool──▶ Mem0 (Search) + ──tool──▶ Mem0 (Add) +``` + +Attach one Mem0 node set to **Search** and one set to **Add**. The agent searches memory before answering and writes back durable facts after a meaningful exchange. Keep **User ID** the same on both. ## Operations +The node wraps the hosted Mem0 REST API and supports six operations on the **Memory** resource: + +| Operation | What it does | Endpoint | +| --- | --- | --- | +| **Add** | Extract and store memories from messages | `POST /v3/memories/add/` | +| **Search** | Semantic search over stored memories | `POST /v3/memories/search/` | +| **Get Many** | List stored memories (one page, or **Return All**) | `POST /v3/memories/` | +| **Get** | Fetch a single memory by ID | `GET /v1/memories/{id}/` | +| **Update** | Change a memory's text or metadata | `PUT /v1/memories/{id}/` | +| **Delete** | Delete a single memory by ID | `DELETE /v1/memories/{id}/` | + ### Add -Extracts and stores memories from one or more messages. Provide at least one entity id (**User ID**, or **Agent ID** / **App ID** / **Run ID** in Additional Fields); the node validates this before calling the API. +Extracts and stores memories from one or more messages. Supply at least one entity id (**User ID**, or **Agent ID** / **App ID** / **Run ID** under Additional Fields); the node checks this before calling the API. -Additional Fields also expose: +**Additional Fields:** | Field | Purpose | | --- | --- | @@ -56,37 +104,46 @@ Additional Fields also expose: | **Includes** | Only extract memories matching this description | | **Excludes** | Skip memories matching this description | -**Includes** and **Excludes** filter what extraction keeps. Sending *"I am vegetarian and I never eat mushrooms. I drive a blue Toyota Corolla and my parking spot is B12"* stores three memories by default; with `Includes: "only record food and diet preferences"` it stores only the dietary one. - -Extraction is asynchronous. **Wait for Completion** (on by default) polls the event until it finishes and returns the resulting memories; turn it off to return immediately with the event ID. +**Includes** and **Excludes** narrow what extraction keeps. Sending *"I am vegetarian and I never eat mushrooms. I drive a blue Toyota Corolla and my parking spot is B12"* stores three memories by default; with `Includes: "only record food and diet preferences"` it stores just the dietary one. ### Search -Semantic search over stored memories. Provide a **Query**, at least one entity id, and an optional **Limit**. +Semantic search over stored memories. Takes a **Query**, at least one entity id, and an optional **Limit**. ### Get Many -Lists stored memories for the entity ids you supply. Turn on **Return All** to page through every memory automatically; leave it off to fetch a single **Page**. **Page Size** applies either way. +Lists stored memories for the entity ids you supply. Turn on **Return All** to page through everything automatically, or leave it off to fetch a single **Page**. **Page Size** applies either way. -### Entity filters on Search and Get Many +### Get, Update, Delete -Both operations take **User ID**, **Agent ID**, **App ID**, and **Run ID**. At least one is required (the API rejects a query with no entity scope), and the node fails with a clear message before making the call if you leave all four empty. +Operate on one memory by **Memory ID**. Update accepts new **Text** and/or **Metadata (JSON)**. -Supply several and they are combined with **OR**, so the result set is the union of those scopes: +## Entity filters on Search and Get Many + +Both operations take **User ID**, **Agent ID**, **App ID**, and **Run ID**. At least one is required, since the API rejects a query with no entity scope, and the node fails with a clear message before making the call if all four are empty. + +Supply several and they combine with **OR**, so the result is the union of those scopes: ```json { "OR": [{ "user_id": "alice" }, { "agent_id": "support-bot" }] } ``` -This is deliberate. Mem0 indexes each entity separately, so an `AND` across `user_id` and `agent_id` matches nothing even when a memory was written with both. To narrow rather than widen, run one operation per entity id. + + This is deliberate, not a shortcut. Mem0 indexes each entity separately, so an `AND` across `user_id` and `agent_id` matches nothing even when a memory was written with both. To narrow rather than widen, run one operation per entity id. + -### Get / Update / Delete +## Choosing a User ID -Operate on a single memory by **Memory ID**. Update accepts new **Text** and/or **Metadata (JSON)**. +The **User ID** is a stable string you pick to identify whose memories these are. It is not looked up in the dashboard, so any consistent value works: your app's internal user ID, an email, or a UUID. Use the same value across Add, Search, and Get Many or recall returns nothing. -## Choosing a `userId` +## Troubleshooting -The `userId` is a stable string you choose to identify whose memories these are. It is not looked up in the dashboard. Common choices are your app's internal user ID, an email, or a UUID. Use the same value across Add, Search, and Get Many so recall works. +- **The node does not appear in the panel**: community nodes install on self-hosted n8n only, and only instance owners can install them. On n8n Cloud, this node is not yet available. +- **`401 Unauthorized`**: the API key is wrong or was revoked. Regenerate it in the API Keys dashboard and update the credential. +- **"Provide at least one of User ID, Agent ID, App ID, or Run ID"**: every Add, Search, and Get Many needs an entity scope. Fill in at least one. +- **Search returns nothing right after an Add**: extraction is asynchronous. Leave **Wait for Completion** on, or add a short Wait node before searching. +- **Searching two entity ids returns more than expected**: multiple ids are combined with OR by design. Run one operation per id to narrow. +- **"Timed out waiting for memory event"**: the add was accepted and is likely still finishing on the server. A timeout here does not mean it failed. diff --git a/docs/integrations/zapier.mdx b/docs/integrations/zapier.mdx index 9bbb74d88..687ebfaa6 100644 --- a/docs/integrations/zapier.mdx +++ b/docs/integrations/zapier.mdx @@ -3,51 +3,133 @@ title: Zapier description: "Add, search, and manage Mem0 memories from any Zap using the Mem0 Zapier app, no code required." --- -The [Mem0](https://mem0.ai) Zapier app lets you add, search, list, and delete long-term memories from any [Zapier](https://zapier.com) workflow. Wire "remember" and "recall" into thousands of apps without writing code. +Zaps fire and forget. The [Mem0](https://mem0.ai) app gives them memory: store durable facts from a form submission, a support ticket, or a chat message, then recall them later from any of [Zapier's](https://zapier.com) thousands of apps. No code, no server. ## Overview -The app wraps the hosted Mem0 REST API and exposes four actions: +1. Connect your Mem0 API key once as a Zapier connection. +2. Use **Add Memory** to store what a Zap learns. +3. Use **Search Memories** or **Get Memories** to pull that context back into a later step. +4. Use **Delete Memory** to remove one by ID. -| Type | Action | Endpoint | -| --- | --- | --- | -| Create | **Add Memory** | `POST /v3/memories/add/` | -| Create | **Delete Memory** | `DELETE /v1/memories/{id}/` | -| Search | **Search Memories** | `POST /v3/memories/search/` | -| Search | **Get Memories** | `POST /v3/memories/` | +## Prerequisites -## Authentication +1. A Mem0 API key from the API Keys dashboard (sign up at app.mem0.ai if you do not have an account). +2. A Zapier account on any plan. -The app uses API key authentication. Grab a key from the Mem0 API Key dashboard and paste it when connecting your Mem0 account in Zapier. The key is sent as `Authorization: Token ` on every request. + + The Mem0 app is not yet listed in Zapier's public App Directory, so you need an invite link to add it to a Zap. Email [support@mem0.ai](mailto:support@mem0.ai) to request one. + + +## Setup + + + + In the Zap editor, search for **Mem0** and pick an action such as **Add Memory**. + + + Select **Sign in**, paste your **Mem0 API Key** (it starts with `m0-`), and leave **Base URL** at `https://api.mem0.ai` unless you run Mem0 somewhere else. + + + Zapier validates the key against Mem0 the moment you save it. A connection labelled **Mem0** means the key works. + + + + + The key is a password field, so Zapier masks it in the editor. It is sent to Mem0 as `Authorization: Token `. + + +## Quickstart + +Remember what a user tells you: + +```text +Trigger (form, chat, ticket) → Mem0: Add Memory +``` + +Set **Content** to the message text and **User ID** to a stable identifier for that person, such as their email. + +Then recall it in a later Zap: + +```text +Trigger (new message) → Mem0: Search Memories → Send reply +``` + +Set **Query** to the incoming message and **User ID** to the same value. The matched memories become available to every step after it. + + + Extraction is asynchronous. **Add Memory** returns immediately with an event ID by default, so a Search fired a second later may not see the new memory yet. See [Waiting for extraction](#waiting-for-extraction). + ## Actions +| Type | Action | What it does | Endpoint | +| --- | --- | --- | --- | +| Create | **Add Memory** | Extract and store memories from a message | `POST /v3/memories/add/` | +| Search | **Search Memories** | Semantic search over stored memories | `POST /v3/memories/search/` | +| Search | **Get Memories** | List stored memories, one page at a time | `POST /v3/memories/` | +| Create | **Delete Memory** | Delete a single memory by ID | `DELETE /v1/memories/{id}/` | + ### Add Memory -Extracts and stores memories from a message. Fields: +| Field | Required | Purpose | +| --- | --- | --- | +| **Content** | Yes | The message text to extract memories from | +| **Role** | | `User` (default), `Assistant`, or `System` | +| **User ID** | | Scopes the memory to a person | +| **Agent ID** | | Scopes the memory to an agent | +| **Run ID** | | Scopes the memory to a single session or run | +| **Metadata (JSON)** | | Arbitrary JSON attached to each extracted memory | +| **Custom Instructions** | | Free-text guidance steering what the extractor keeps or ignores, for this call | +| **Custom Categories (JSON)** | | JSON array of `{category: description}` objects, replacing the project-level catalog for this call | +| **Includes** | | Only extract memories matching this description | +| **Excludes** | | Skip memories matching this description | +| **Infer** | | On by default. Turn off to store the message verbatim instead of running LLM extraction | +| **Wait for Completion** | | Off by default. Turn on to poll until extraction finishes and return the resulting memories | -- **Content** (required): the message text to extract memories from. -- **Role**: `user`, `assistant`, or `system`. -- **User ID / Agent ID / Run ID**: entity the memory belongs to. -- **Metadata (JSON)**: optional structured metadata. -- **Infer**: run LLM extraction (default) or store the message verbatim. -- **Wait for Completion**: off by default. Extraction is asynchronous, so the action returns immediately with an event ID. Turn this on to poll until extraction finishes and return the resulting memories. Extraction can take longer than a single Zapier step is allowed to run, so a timeout here does not mean the add failed; it usually still completes on the server. +**Includes** and **Excludes** narrow what extraction keeps. Sending *"I am vegetarian and I never eat mushrooms. I drive a blue Toyota Corolla and my parking spot is B12"* stores three memories by default; with `Includes: "only record food and diet preferences"` it stores just the dietary one. + +#### Waiting for extraction + +Extraction runs asynchronously, so **Add Memory** returns an event ID and moves on unless you turn on **Wait for Completion**. When you do, the step polls for up to 60 seconds and returns the extracted memories instead. + + + Extraction can take longer than Zapier allows a single step to run, which is why waiting is opt-in. If the step times out, the add was still accepted and typically completes on Mem0's side, so do not retry it blindly. + ### Search Memories -Semantic search over stored memories. Provide a **Query**, a **User ID** (required, the API needs an entity filter), and an optional **Limit**. +| Field | Required | Purpose | +| --- | --- | --- | +| **Query** | Yes | Natural-language search text | +| **User ID** | Yes | Whose memories to search. The API needs an entity filter | +| **Limit** | | Maximum results, default `50` | ### Get Memories -Lists stored memories for a user. Provide a **User ID** (required), a **Limit** (page size), and a **Page** (1-based) to page through larger result sets. +| Field | Required | Purpose | +| --- | --- | --- | +| **User ID** | Yes | Whose memories to list | +| **Limit** | | Memories per page, default `50` | +| **Page** | | Which page to return, 1-based, default `1` | + +Returns one page per run. Raise **Page** to walk through larger result sets. ### Delete Memory -Deletes a single memory by its **Memory ID**. +Takes a **Memory ID** and deletes that memory. Pair it with **Search Memories** or **Get Memories** to get the ID first. -## Choosing a `userId` +## Choosing a User ID -The `user_id` is a stable string you choose to identify whose memories these are. It is not looked up in the dashboard. Common choices are your app's internal user ID, an email, or a UUID. Use the same value across Add, Search, and Get so recall works. +The **User ID** is a stable string you pick to identify whose memories these are. It is not looked up in the dashboard, so any consistent value works: your app's internal user ID, an email, or a UUID. Use the same value on Add, Search, and Get Memories or recall returns nothing. + +## Troubleshooting + +- **Mem0 does not appear in the Zap editor**: the app is not yet in the public App Directory. Email [support@mem0.ai](mailto:support@mem0.ai) for an invite link. +- **The connection fails when you paste the key**: check that it starts with `m0-` and has not been revoked in the API Keys dashboard. +- **Search returns nothing right after an Add**: extraction is asynchronous. Turn on **Wait for Completion**, or put a Zapier **Delay** step before the Search. +- **"Metadata must be valid JSON" or "Custom Categories must be valid JSON"**: those fields take raw JSON. Check for smart quotes and trailing commas. +- **The Add step times out**: the memory was still accepted and is likely finishing server-side. Confirm with **Get Memories** before re-running.