# tool_mem0

Long-term, shared agent memory exposed as **tools** (`mem0.remember` / `mem0.recall`),
backed by the hosted [Mem0 Platform](https://docs.mem0.ai) REST API.

This is a `tool` node (`classType: ["tool"]`, no data lanes), not the agent's run-scoped
`memory` subsystem, it complements it. Wire it to an agent via `control` (class `tool`).

## About Mem0

Mem0 is a memory platform for AI applications. It stores conversation-derived
facts and supports semantic retrieval, which makes it suitable when several
agents or pipeline runs need a shared memory outside a single run.

## What it does

This node gives an agent persistent, externally hosted memory through two
tools and has no data lanes. Pick it over an in-run memory component when a
fact must be available to later agents or pipeline executions that use the
same configured scope.

## As a tool

- **`mem0.remember`** → `POST /v1/memories/`: ingest conversation turns; Mem0 extracts and
  stores salient facts server-side.
- **`mem0.recall`** → `POST /v1/memories/search/`: semantic search over the pool; returns
  ranked memories.

## Configuration

`api_key` is required (or set `MEM0_API_KEY`); a scope is required to store and recall. The full
field set is in the [Schema](#schema) section below and in `services.json`.

**Scope with `user_id`.** On the hosted platform a memory added with an `agent_id` / `app_id` is
stored under the `user_id` but doesn't reliably carry that id, while `recall` AND-narrows by every
id set, so configuring `agent_id` can make recalls come back empty even though the write
succeeded (verified against the live API). Use `user_id` (and `run_id` for sessions); leave
`agent_id` / `app_id` empty unless verified for your account.

### Ingestion and recall behavior

Leave **Infer memories** on to let Mem0 derive salient facts from supplied
turns; turn it off only when raw messages are the desired stored form. Keep
**Synchronous store** on when a following recall must see the just-added fact;
turning it off returns before background extraction completes. Increase the
store timeout only when extraction regularly outlives its 30-second default,
and adjust the recall limit when the agent needs a broader or narrower result
set.

## Notes

### Direct REST integration

This node calls the Mem0 REST API directly with `requests` rather than the `mem0ai` SDK: the
SDK hard-pins `openai<1.110`, which is unsatisfiable alongside the engine's OpenAI nodes
(`openai>=2.38`). The REST surface is identical: the entity ids
(`user_id` / `agent_id` / `run_id` / `app_id`) go top-level in the JSON body for both `add` and
`search`, built from one internal scope helper. Deps (`requests`, `tenacity`) are already in the
engine: no new third-party packages, no version conflict.

Mem0's `add` is asynchronous (queues extraction, returns an `event_id`). By default `remember`
polls `GET /v1/event/{event_id}/` until the job is terminal (or `ingest_timeout` elapses) so a
following `recall` sees the memory, like xTrace's synchronous ingest. Turn `wait` off for
fire-and-forget. `search` returns ranked rows (handled whether the API returns a bare list or a
`{"results": […]}` object).

### Credentials

Get an API key (`m0-…`) from [app.mem0.ai](https://app.mem0.ai) → API Keys. Never commit keys:
use node config (encrypted) or the env var.

## Upstream docs

- [Mem0 documentation](https://docs.mem0.ai)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `mem0.agent_id` | `string` | **Agent id**<br/>Optional agent scope. Caution: on the hosted Mem0 platform an agent_id is not reliably stored on the memory but still narrows recall, so setting it can make recalls come back empty. Prefer scoping by user id; leave this empty unless you have verified it works. | `""` |
| `mem0.api_key` | `string` | **API Key**<br/>Mem0 Platform API key (m0-...). Get it from the <b>Mem0 dashboard</b>: <a href='https://app.mem0.ai' target='_blank'>app.mem0.ai</a> → API Keys. | `""` |
| `mem0.app_id` | `string` | **App id**<br/>Optional app scope. Same caveat as Agent id: it narrows recall but is not reliably stored on the hosted platform, so setting it can hide memories. Prefer scoping by user id. | `""` |
| `mem0.base_url` | `string` | **Base URL**<br/>Mem0 REST API base URL. Defaults to the hosted endpoint; override for self-hosted / enterprise deployments. | `"https://api.mem0.ai"` |
| `mem0.infer` | `boolean` | **Infer memories**<br/>When on (default), Mem0 runs LLM extraction to derive salient facts from the turns. When off, the raw messages are stored verbatim. | `true` |
| `mem0.ingest_timeout` | `integer` | **Store timeout (s)**<br/>Max seconds 'remember' waits/polls for background extraction to finish before returning a 'queued' result. | `30` |
| `mem0.run_id` | `string` | **Run id**<br/>Optional session/run scope stamped on stored memories and used to narrow recall. Can be passed by the agent per call. | `""` |
| `mem0.search_limit` | `integer` | **Recall limit**<br/>Maximum number of memory rows to retrieve per recall. | `10` |
| `mem0.show_advanced` | `boolean` | **Advanced settings**<br/>Show advanced options. The defaults work for most cases, leave off for a simple setup. | `false` |
| `mem0.user_id` | `string` | **User id**<br/>Who this memory belongs to (used to store and recall). Can be passed by the agent per call. At least one scope (user id, or an advanced agent/run/app id) is required. | `""` |
| `mem0.wait` | `boolean` | **Synchronous store**<br/>When on (default), 'remember' polls Mem0 until background extraction finishes, so a following 'recall' can see the new memory. When off, 'remember' returns immediately and extraction runs in the background. | `true` |

## Dependencies

- `requests`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_mem0)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->