> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# tool_xtrace_memory

A RocketRide tool node that gives an agent persistent, shared xTrace memory. Pick it when agents need cross-session context for a user or group, rather than the run-scoped memory used internally by an agent.

## About xTrace Memory

xTrace Memory is a service for storing conversation-derived memory and retrieving relevant context later. It is designed to let separate agents share an organization- or group-scoped memory pool.

## What it does

The node has no data lanes and exposes explicit store and recall operations. `remember` ingests conversation turns and returns the ingest-job state; `recall` searches the configured scope and can return a ready-to-inject context block. Unlike a run-scoped scratchpad, this store is not cleared when a session opens, so agents pointing at the same scope can use the same memories.

## As a tool

The prefix defaults to `xtrace`.

| Function | Description |
|---|---|
| `xtrace.remember` | Ingest conversation turns into shared persistent memory. |
| `xtrace.recall` | Search memory for context relevant to a required query. |

`remember` accepts either `messages` (preferred: objects with `role` and `content`) or one `content` value, plus optional `user_id` and `conv_id`. It returns `success`, `status`, `job_id`, `memories_created`, and `error`; missing content or user scope returns a failed result. `recall` accepts `query`, optional `user_id`, `group_ids`, `mode`, and `limit`, and returns `context`, ranked `results`, `count`, and `error`. A recall with no user, group, agent, or app scope returns an error instead of searching the entire organization.

## Configuration

Set the API key and organization ID first. The remaining defaults work for a basic per-user memory; use the advanced controls only when you need intentional sharing, a narrower scope, or different ingest and recall behavior.

### User id and Group ids (shared memory)

A configured user ID supplies the default owner for both tools. Group IDs are a comma-separated shared scope; use them only when memories should be visible across users or agents. A call can override these values, so keep the configured scope narrow when the same node serves different requests.

### Ingest behavior

Synchronous ingest is on by default, so `remember` waits for extraction to reach a terminal state or the configured 30-second timeout. Turn it off only when the caller can tolerate a pending job. Artifact extraction is off by default; enable it only when that extra extraction is necessary.

### Recall behavior

`compose` is the default recall mode and returns an injected-context block as well as ranked rows. Use `retrieve` when the caller needs only the ranked records. The recall limit defaults to 10 and is clamped from 1 to 100; increase it only when the agent can make use of the additional context.

### Agent and App scope

Optional agent and app IDs are attached at ingest and both narrow recall. Use them to partition one organization memory pool; both values participate in the recall scope.

## Authentication

Set `api_key` and `org_id`. Requests carry them in the `x-api-key` and `X-Org-Id` headers. Failed HTTP requests are returned to the tool as failed result objects; idempotent retrieval retries rate limits, server errors, and timeouts, while ingestion avoids ambiguous retries that could duplicate memory.

## Upstream docs

- [xTrace Memory documentation](https://docs.mem.xtrace.ai)

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

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `xtrace_memory.agent_id` | `string` | **Agent id**<br/>Optional agent scope stamped on ingested memories and AND-narrowed on recall. | `""` |
| `xtrace_memory.api_key` | `string` | **API Key**<br/>xTrace API key (xtk_...). Get it from the <b>Developer Portal</b>: <a href='https://app.xtrace.ai' target='_blank'>app.xtrace.ai</a> → Settings → API Keys (not in mem.xtrace.ai). | `""` |
| `xtrace_memory.app_id` | `string` | **App id**<br/>Optional app scope stamped on ingested memories and AND-narrowed on recall. | `""` |
| `xtrace_memory.base_url` | `string` | **Base URL**<br/>xTrace Memory API base URL. Production by default; use https://api.staging.xtrace.ai for staging. | `"https://api.production.xtrace.ai"` |
| `xtrace_memory.extract_artifacts` | `boolean` | **Extract artifacts**<br/>Opt into artifact extraction (the most expensive stage). Facts and episodes are always extracted. Leave off unless you need it. | `false` |
| `xtrace_memory.group_ids` | `string` | **Group ids (shared memory)**<br/>Optional. Comma-separated group ids (grp_...) to share memory across users/agents. Leave empty for private memory. | `""` |
| `xtrace_memory.ingest_timeout` | `integer` | **Ingest timeout (s)**<br/>Max seconds to wait/poll for an ingest job to reach a terminal state. | `30` |
| `xtrace_memory.org_id` | `string` | **Org id**<br/>xTrace organization id (org_...). Same place as the API key: <a href='https://app.xtrace.ai' target='_blank'>app.xtrace.ai</a> → Settings → API Keys. | `""` |
| `xtrace_memory.search_limit` | `integer` | **Recall limit**<br/>Maximum number of memory rows to retrieve per recall. | `10` |
| `xtrace_memory.search_mode` | `string` | **Recall mode**<br/>'compose' returns a ready-to-inject markdown context block (LLM-selected); 'retrieve' returns ranked rows only. | `"compose"` |
| `xtrace_memory.show_advanced` | `boolean` | **Advanced settings**<br/>Show advanced options. The defaults work for most cases, leave off for a simple setup. | `false` |
| `xtrace_memory.user_id` | `string` | **User id**<br/>Who this memory belongs to (used to store and recall). Can be passed by the agent per call. | `""` |
| `xtrace_memory.wait` | `boolean` | **Synchronous ingest**<br/>When on, ingest waits (up to ~30s) for extraction to finish so the agent gets a terminal result. When off, ingest returns immediately and 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_xtrace_memory)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
