Bulk-add episodes to memory graph (maintenance lane)

Ingest a batch of episodic payloads into one knowledge-graph scope.

The bulk counterpart to POST /memories/graph for backfills and other operator-driven batches. The batch executes on the maintenance worker lane, so it never occupies realtime capacity, while still passing through the written scope's FIFO so it cannot race realtime graph writes. Episodes ingest in order with per-episode idempotency, so a retried batch resumes after the last committed episode. Always asynchronous — poll GET /memories/graph/status/{job_id}.

POST

https://truememory-api.mvstg.com/memories/graph/bulk

View as Markdown

Authorization

HTTPBearerHTTPrequired

Header parameters

X-On-Behalf-Ofoptional
One of the following:
string
null
}
X-External-User-Idoptional
One of the following:
string
null
}
X-App-Idoptional
One of the following:
string
null
}

Request bodyJSONrequired

episodesarray ofobjectrequired
- datastringrequired
  maxLength: 50000
- typemessageorjsonortextordocumentornoteortranscriberequired
- source_descriptionoptional
  One of the following:
  string
  null
- created_atoptional
  One of the following:
  string
  null
}
agent_idoptional
Target the calling user's memory, scoped by this agent. Provide exactly one of agent_id or graph_id.
One of the following:
string
null
}
graph_idoptional
Target a shared namespace instead of user memory. Requires a service token.
One of the following:
string
null
}
modeoptionalappendorseed
append: sequential ingestion with full edge invalidation against the existing graph. seed: one bulk extraction pass over the batch — the fast path for migrating into a fresh or replaced graph.

default: "append"
replaceoptionalboolean
Expire the scope's existing memory edges before ingesting (start from fresh). User scopes (agent_id) only.

default: false

Returns

202

Successful Response

JSON

job_idstringrequired
Poll GET /memories/graph/status/{job_id} with this.
episodesintegerrequired
Number of episodes queued.
statusoptionalstring
default: "processing"

422

Validation Error

JSON

detailoptionalarray ofobject
- locarray ofrequired
  One of the following:
  string
  integer
- msgstringrequired
- typestringrequired
- inputoptionalunknown
- ctxoptionalobject
}

curl --request POST \ --url https://truememory-api.mvstg.com/memories/graph/bulk \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "episodes": [ { "data": "string", "type": "message", "source_description": "string", "created_at": "2019-08-24T14:15:22Z" } ], "agent_id": "string", "graph_id": "string", "mode": "append", "replace": false } '