Procedural-memory recall (pre-tool-call hook)

curl --request POST \
  --url https://api.production.xtrace.ai/v1/memories/trigger \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "action": {
    "tool": "<string>",
    "args": {},
    "output": "<string>"
  },
  "entities": [
    "tool_loop.py",
    "AbortError"
  ],
  "include": [],
  "namespace": "MemHub-Backend",
  "task": "fix finalize-on-abort in the tool loop",
  "mode": "compose",
  "user_id": "user-123",
  "group_ids": [
    "grp_a1b2c3d4e5f6071829304a5b6c7d8e9f"
  ],
  "agent_id": "bot-7",
  "app_id": "app-3"
}
'

import requests

url = "https://api.production.xtrace.ai/v1/memories/trigger"

payload = {
    "action": {
        "tool": "<string>",
        "args": {},
        "output": "<string>"
    },
    "entities": ["tool_loop.py", "AbortError"],
    "include": [],
    "namespace": "MemHub-Backend",
    "task": "fix finalize-on-abort in the tool loop",
    "mode": "compose",
    "user_id": "user-123",
    "group_ids": ["grp_a1b2c3d4e5f6071829304a5b6c7d8e9f"],
    "agent_id": "bot-7",
    "app_id": "app-3"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: {tool: '<string>', args: {}, output: '<string>'},
    entities: ['tool_loop.py', 'AbortError'],
    include: [],
    namespace: 'MemHub-Backend',
    task: 'fix finalize-on-abort in the tool loop',
    mode: 'compose',
    user_id: 'user-123',
    group_ids: ['grp_a1b2c3d4e5f6071829304a5b6c7d8e9f'],
    agent_id: 'bot-7',
    app_id: 'app-3'
  })
};

fetch('https://api.production.xtrace.ai/v1/memories/trigger', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.production.xtrace.ai/v1/memories/trigger",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => [
        'tool' => '<string>',
        'args' => [
                
        ],
        'output' => '<string>'
    ],
    'entities' => [
        'tool_loop.py',
        'AbortError'
    ],
    'include' => [
        
    ],
    'namespace' => 'MemHub-Backend',
    'task' => 'fix finalize-on-abort in the tool loop',
    'mode' => 'compose',
    'user_id' => 'user-123',
    'group_ids' => [
        'grp_a1b2c3d4e5f6071829304a5b6c7d8e9f'
    ],
    'agent_id' => 'bot-7',
    'app_id' => 'app-3'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.production.xtrace.ai/v1/memories/trigger"

	payload := strings.NewReader("{\n  \"action\": {\n    \"tool\": \"<string>\",\n    \"args\": {},\n    \"output\": \"<string>\"\n  },\n  \"entities\": [\n    \"tool_loop.py\",\n    \"AbortError\"\n  ],\n  \"include\": [],\n  \"namespace\": \"MemHub-Backend\",\n  \"task\": \"fix finalize-on-abort in the tool loop\",\n  \"mode\": \"compose\",\n  \"user_id\": \"user-123\",\n  \"group_ids\": [\n    \"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f\"\n  ],\n  \"agent_id\": \"bot-7\",\n  \"app_id\": \"app-3\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.production.xtrace.ai/v1/memories/trigger")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": {\n    \"tool\": \"<string>\",\n    \"args\": {},\n    \"output\": \"<string>\"\n  },\n  \"entities\": [\n    \"tool_loop.py\",\n    \"AbortError\"\n  ],\n  \"include\": [],\n  \"namespace\": \"MemHub-Backend\",\n  \"task\": \"fix finalize-on-abort in the tool loop\",\n  \"mode\": \"compose\",\n  \"user_id\": \"user-123\",\n  \"group_ids\": [\n    \"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f\"\n  ],\n  \"agent_id\": \"bot-7\",\n  \"app_id\": \"app-3\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.production.xtrace.ai/v1/memories/trigger")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": {\n    \"tool\": \"<string>\",\n    \"args\": {},\n    \"output\": \"<string>\"\n  },\n  \"entities\": [\n    \"tool_loop.py\",\n    \"AbortError\"\n  ],\n  \"include\": [],\n  \"namespace\": \"MemHub-Backend\",\n  \"task\": \"fix finalize-on-abort in the tool loop\",\n  \"mode\": \"compose\",\n  \"user_id\": \"user-123\",\n  \"group_ids\": [\n    \"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f\"\n  ],\n  \"agent_id\": \"bot-7\",\n  \"app_id\": \"app-3\"\n}"

response = http.request(request)
puts response.read_body

{
  "mode": "retrieve",
  "object": "search",
  "data": [
    {
      "id": "<string>",
      "type": "fact",
      "text": "<string>",
      "object": "memory",
      "user_id": "<string>",
      "agent_id": "<string>",
      "conv_id": "<string>",
      "app_id": "<string>",
      "group_ids": [
        "<string>"
      ],
      "categories": [
        "<string>"
      ],
      "score": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "details": {
        "fact_type": "<string>",
        "status": "<string>",
        "supersedes": "<string>",
        "source_role": "<string>",
        "episode_id": "<string>",
        "artifact_id": "<string>",
        "artifact_ids": [
          "<string>"
        ],
        "source_event_ids": [
          "<string>"
        ]
      }
    }
  ],
  "context": "<string>",
  "stage_timings": {},
  "context_selection_applied": false
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

memories

Procedural-memory recall (pre-tool-call hook)

Procedural-memory recall for a pre-tool-call hook.

Fires the symbol tripwire on the in-flight action (or explicit entities) and returns the lesson/procedure insights past sessions recorded about those symbols — advisory, not a mandate. data: list[Memory] carries the matched rows (type: "lesson" | "procedure"); mode=compose additionally runs an LLM relevance gate over task and assembles a markdown block into context, while mode=retrieve returns the raw matched rows and leaves context null. Scope is enforced server-side from the request’s scope axes (user_id / group_ids / agent_id / app_id).

Unlike POST /v1/memories/search, this endpoint is not metered against the monthly quota — the hook is meant to be called freely before every tool use.

POST

memories

trigger

Procedural-memory recall (pre-tool-call hook)

curl --request POST \
  --url https://api.production.xtrace.ai/v1/memories/trigger \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "action": {
    "tool": "<string>",
    "args": {},
    "output": "<string>"
  },
  "entities": [
    "tool_loop.py",
    "AbortError"
  ],
  "include": [],
  "namespace": "MemHub-Backend",
  "task": "fix finalize-on-abort in the tool loop",
  "mode": "compose",
  "user_id": "user-123",
  "group_ids": [
    "grp_a1b2c3d4e5f6071829304a5b6c7d8e9f"
  ],
  "agent_id": "bot-7",
  "app_id": "app-3"
}
'

import requests

url = "https://api.production.xtrace.ai/v1/memories/trigger"

payload = {
    "action": {
        "tool": "<string>",
        "args": {},
        "output": "<string>"
    },
    "entities": ["tool_loop.py", "AbortError"],
    "include": [],
    "namespace": "MemHub-Backend",
    "task": "fix finalize-on-abort in the tool loop",
    "mode": "compose",
    "user_id": "user-123",
    "group_ids": ["grp_a1b2c3d4e5f6071829304a5b6c7d8e9f"],
    "agent_id": "bot-7",
    "app_id": "app-3"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: {tool: '<string>', args: {}, output: '<string>'},
    entities: ['tool_loop.py', 'AbortError'],
    include: [],
    namespace: 'MemHub-Backend',
    task: 'fix finalize-on-abort in the tool loop',
    mode: 'compose',
    user_id: 'user-123',
    group_ids: ['grp_a1b2c3d4e5f6071829304a5b6c7d8e9f'],
    agent_id: 'bot-7',
    app_id: 'app-3'
  })
};

fetch('https://api.production.xtrace.ai/v1/memories/trigger', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.production.xtrace.ai/v1/memories/trigger",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => [
        'tool' => '<string>',
        'args' => [
                
        ],
        'output' => '<string>'
    ],
    'entities' => [
        'tool_loop.py',
        'AbortError'
    ],
    'include' => [
        
    ],
    'namespace' => 'MemHub-Backend',
    'task' => 'fix finalize-on-abort in the tool loop',
    'mode' => 'compose',
    'user_id' => 'user-123',
    'group_ids' => [
        'grp_a1b2c3d4e5f6071829304a5b6c7d8e9f'
    ],
    'agent_id' => 'bot-7',
    'app_id' => 'app-3'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.production.xtrace.ai/v1/memories/trigger"

	payload := strings.NewReader("{\n  \"action\": {\n    \"tool\": \"<string>\",\n    \"args\": {},\n    \"output\": \"<string>\"\n  },\n  \"entities\": [\n    \"tool_loop.py\",\n    \"AbortError\"\n  ],\n  \"include\": [],\n  \"namespace\": \"MemHub-Backend\",\n  \"task\": \"fix finalize-on-abort in the tool loop\",\n  \"mode\": \"compose\",\n  \"user_id\": \"user-123\",\n  \"group_ids\": [\n    \"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f\"\n  ],\n  \"agent_id\": \"bot-7\",\n  \"app_id\": \"app-3\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.production.xtrace.ai/v1/memories/trigger")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": {\n    \"tool\": \"<string>\",\n    \"args\": {},\n    \"output\": \"<string>\"\n  },\n  \"entities\": [\n    \"tool_loop.py\",\n    \"AbortError\"\n  ],\n  \"include\": [],\n  \"namespace\": \"MemHub-Backend\",\n  \"task\": \"fix finalize-on-abort in the tool loop\",\n  \"mode\": \"compose\",\n  \"user_id\": \"user-123\",\n  \"group_ids\": [\n    \"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f\"\n  ],\n  \"agent_id\": \"bot-7\",\n  \"app_id\": \"app-3\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.production.xtrace.ai/v1/memories/trigger")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": {\n    \"tool\": \"<string>\",\n    \"args\": {},\n    \"output\": \"<string>\"\n  },\n  \"entities\": [\n    \"tool_loop.py\",\n    \"AbortError\"\n  ],\n  \"include\": [],\n  \"namespace\": \"MemHub-Backend\",\n  \"task\": \"fix finalize-on-abort in the tool loop\",\n  \"mode\": \"compose\",\n  \"user_id\": \"user-123\",\n  \"group_ids\": [\n    \"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f\"\n  ],\n  \"agent_id\": \"bot-7\",\n  \"app_id\": \"app-3\"\n}"

response = http.request(request)
puts response.read_body

{
  "mode": "retrieve",
  "object": "search",
  "data": [
    {
      "id": "<string>",
      "type": "fact",
      "text": "<string>",
      "object": "memory",
      "user_id": "<string>",
      "agent_id": "<string>",
      "conv_id": "<string>",
      "app_id": "<string>",
      "group_ids": [
        "<string>"
      ],
      "categories": [
        "<string>"
      ],
      "score": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "details": {
        "fact_type": "<string>",
        "status": "<string>",
        "supersedes": "<string>",
        "source_role": "<string>",
        "episode_id": "<string>",
        "artifact_id": "<string>",
        "artifact_ids": [
          "<string>"
        ],
        "source_event_ids": [
          "<string>"
        ]
      }
    }
  ],
  "context": "<string>",
  "stage_timings": {},
  "context_selection_applied": false
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

{
  "detail": {
    "code": "memory_not_found",
    "message": "Memory 0fa1c0e6-... not found"
  }
}

Authorizations

x-api-key

string

header

required

Long-lived org API key. Alternative: Authorization: Bearer <key>.

Body

application/json

POST /v1/memories/trigger — procedural-memory recall for a pre-tool-call hook.

An agent calls this right before (or just after) a tool runs to pull the lesson/procedure insights that past sessions recorded about the symbols it's touching — what worked, what didn't. Recall fires on the symbol tripwire, never a semantic query: the server extracts greppable identifiers from action (tool / args / output) or takes them straight from entities, and matches them exactly against directives' trigger_entities.

What comes back is advisory, not a mandate — ranked :class:Memory rows (type: "lesson" | "procedure") in the shared :class:SearchResponse, with the assembled markdown in context under mode="compose".

Scope follows "scope by what you pass": every axis you supply ANDs; org_id is derived server-side from your API key. At least one of user_id / agent_id / app_id / group_ids is required — an unscoped org-wide recall is rejected.

action

ActionContext · object | null

The in-flight tool call the agent is touching right now — the firing signal for recall. Greppable identifiers are extracted server-side (tool name, args values, optional output) and matched exactly against directives' trigger_entities. Supply this or entities.

Show child attributes

entities

string[] | null

Escape hatch: pre-extracted greppable identifiers to fire on, bypassing server-side extraction from action. Use when the client already knows the exact symbols the agent is touching.

Example:

["tool_loop.py", "AbortError"]

include

enum<string>[]

Which procedural corpora to recall. Defaults to both (lesson/procedure); subset to restrict (e.g. ["lesson"]).

Available options:

lesson,

procedure

namespace

string | null

Namespace the agent is working in right now — repo, customer account, service (whatever was passed at ingest). Narrows recall to directives learned under that namespace plus global ones (ingested with no namespace) — it never hides global directives, so it is always safe to pass. Unrelated to the tenancy axes.

Maximum string length: 256

Example:

"MemHub-Backend"

task

string | null

The agent's current goal, in one line. Fed to the relevance gate under mode=compose so it keeps only the insights that help with THIS task.

Maximum string length: 2000

Example:

"fix finalize-on-abort in the tool loop"

mode

enum<string>

default:compose

Pipeline depth selector.

compose (default) — symbol-tripwire recall plus an LLM relevance-gate step that keeps only the insights relevant to task, then assembles a markdown block. data carries the gated rows; context carries the markdown. One LLM call.
retrieve — recall only. No LLM, cheaper and faster. data carries the matched rows; context is null.

Available options:

retrieve,

compose

user_id

string | null

Scope key. When supplied, applied as an AND pin so reads are tenant-isolated at the storage filter layer. Optional: omit it and pass group_ids to read a shared group across users. At least one of user_id / agent_id / app_id / group_ids is required.

Example:

"user-123"

group_ids

string[]

Optional group tags — another AND scope axis. When non-empty, matched rows must be tagged to at least one of the requested group(s). Group ids are server-generated unguessable handles (see POST /v1/groups); knowing the id is the access boundary.

Example:

["grp_a1b2c3d4e5f6071829304a5b6c7d8e9f"]

agent_id

string | null

Optional agent scope. When set, ANDs onto the active primary scope (whether that's user_id or group_ids): matched rows must also carry this exact agent_id.

Example:

"bot-7"

app_id

string | null

Optional app scope. When set, ANDs onto the active primary scope (like agent_id): matched rows must also carry this exact app_id.

Example:

"app-3"

Response

Successful Response

POST /v1/memories/search response.

data is always populated — both modes return the ranked Memory rows from retrieval. context is populated only when mode='compose' with the assembled markdown block from the LLM context-selection step. stage_timings is always present for per-stage latency attribution.

Note that under mode='compose' the rows in data are the retrieval candidates — a possibly larger set than the subset the LLM selected and wove into context. Useful for showing "everything we found" alongside "what we sent to the model."

mode

enum<string>

required

Echoes the request's mode. compose ⇒ both data and context populated; retrieve ⇒ data populated and context null.

Available options:

retrieve,

compose

object

string

default:search

Constant discriminator for the resource type.

Allowed value: "search"

data

Memory · object[]

Ranked Memory rows from retrieval. Populated for both modes. Semantic rows (fact/artifact/episode) are ordered by score desc; when include requests lesson/procedure, those directive rows are precision-gated (not vector-scored, score is null) and lead the list ahead of the semantic rows. For mode=compose, the semantic rows are the candidates considered by the context-selection step — a (possibly larger) superset of what ended up in context.

Show child attributes

context

string | null

Assembled markdown context block ready for prompt insertion. Populated only when mode=compose; null otherwise.

stage_timings

Stage Timings · object

Per-stage retrieval-pipeline latencies (seconds). Populated in both modes.

Show child attributes

context_selection_applied

boolean

default:false

True when the LLM context-selection step ran. False indicates the pipeline fell through (e.g. an empty candidate pool, or context selection disabled by config).

memories

groups

usage

webhooks

Procedural-memory recall (pre-tool-call hook)

Authorizations

Body

Response