Format model input
Configure, update, clear, and override embedder and reranker instructions and templates.
Format model input
Use an input format to add the prefixes or task instructions required by your model. If your model does not require these, you can skip this guide. GoodMem stores the format on the embedder or reranker and applies it before sending model input. Configure LLM answer prompts separately.
This guide assumes the model endpoint is already running. Use the
endpoint registration guide for its URL, provider, path,
and credentials. Set GOODMEM_REST_URL and GOODMEM_API_KEY for your GoodMem instance. CLI
commands use your CLI connection configuration.
Find out if a model needs an input format
Read the model card and the configuration of the runtime serving it. Look for query and document
prefixes, a task instruction before a query, or a prompts section in
config_sentence_transformers.json. Configure the model input in one place: a runtime prompt
combined with a GoodMem template can add the same prefix twice.
Usually, GoodMem sends unchanged text when you omit the format. Gemini embedder creation is the exception: omission stores default query and document templates. An explicit empty format suppresses them. GoodMem rejects nonempty formats for Voyage, Cohere, Jina, and all DashScope embedding dialects. See the provider policy.
Configure query and document prefixes
For an E5 endpoint serving intfloat/e5-large-v2, register the query and passage prefixes shown
by that model's documentation. Save this complete body as embedder.json, replacing the endpoint
URL with the running TEI service reachable from GoodMem:
{
"displayName": "E5 large",
"providerType": "TEI",
"endpointUrl": "http://tei-host:8080",
"modelIdentifier": "intfloat/e5-large-v2",
"dimensionality": 1024,
"distributionType": "DENSE",
"inputFormat": {
"queryTemplate": "query: {{ content }}",
"documentTemplate": "passage: {{ content }}"
}
}curl -X POST "$GOODMEM_REST_URL/v1/embedders" \
-H "x-api-key: $GOODMEM_API_KEY" \
-H "Content-Type: application/json" \
-d @embedder.jsonOr create it with the CLI:
goodmem embedder create \
--display-name "E5 large" \
--provider-type TEI \
--endpoint-url "http://tei-host:8080" \
--model-identifier "intfloat/e5-large-v2" \
--dimensionality 1024 \
--query-template "query: {{ content }}" \
--document-template "passage: {{ content }}"The response includes the stored format. Searches send query: <query text>. Ingestion sends
passage: <chunk text>. Use this embedder when you create a space.
In the console, use the resource form's input-format editors.
For syntax and required {{ content }} placement, see the
template rules. For SDK constructors and property
names, see the SDK references.
Add a task instruction to queries
For a running endpoint serving Qwen/Qwen3-Embedding-0.6B, register an instruction and a query template. Confirm its dimensionality and endpoint path against your deployment. This example uses a vLLM endpoint with 1,024-dimensional output:
goodmem embedder create \
--display-name "Qwen3 Embedding" \
--provider-type VLLM \
--endpoint-url "http://vllm-host:8000/v1" \
--model-identifier "Qwen/Qwen3-Embedding-0.6B" \
--dimensionality 1024 \
--instruction "Given a web search query, retrieve relevant passages that answer the query" \
--query-template $'Instruct: {{ instruction }}\nQuery:{{ content }}'Bash and Zsh $'...' quoting supplies a real line break. The missing space after Query: matches the
model card. See whitespace and file handling
for other transports. For the query deployment strategies, the
model receives:
Instruct: Given a web search query, retrieve relevant passages that answer the query
Query:deployment strategiesinstruction is plain text. queryTemplate decides where to put it. See the
instruction-delivery rules before changing
that relationship.
Include document metadata
Choose the metadata before ingestion. To include a memory title with each indexed chunk, set
the embedder's document template at registration, or update it before any space references the
embedder. With EMBEDDER_ID set to the resource ID:
goodmem embedder update "$EMBEDDER_ID" \
--document-template "title: {{ memory.metadata.title | default('none') }} | text: {{ content }}"The CLI preserves the other stored format fields. A memory with metadata
{"title":" Quarterly\n report "} and chunk Revenue increased. produces:
title: Quarterly report | text: Revenue increased.The stored content and metadata remain unchanged. A later metadata edit does not rebuild its vectors. For available facts, scalar conversion, and fallbacks, see template variables.
Configure a reranker
A reranker can format both its query and each retrieved chunk. For a running vLLM reranker, save
this complete body as reranker.json, replacing the endpoint URL for your deployment:
{
"displayName": "Qwen3 Reranker",
"providerType": "VLLM",
"endpointUrl": "http://vllm-host:8000/v1",
"modelIdentifier": "Qwen/Qwen3-Reranker-0.6B",
"inputFormat": {
"instruction": "Rank passages by how well they answer the query",
"documentTemplate": "Title: {{ memory.metadata.title | default('none') }} / {{ content }}"
}
}curl -X POST "$GOODMEM_REST_URL/v1/rerankers" \
-H "x-api-key: $GOODMEM_API_KEY" \
-H "Content-Type: application/json" \
-d @reranker.jsonThe /v1 base URL and GoodMem's default /rerank path compose to /v1/rerank, one of
vLLM's supported rerank routes.
This sends unchanged query text, the instruction in vLLM's instruction field, and a title before
each candidate chunk. Configure the returned reranker ID in the
chat post-processor.
For providers without an instruction field, put the instruction in the query template instead;
see instruction delivery.
Update an input format
Set EMBEDDER_ID to the resource to change. A REST update replaces the entire format, so
include the document template you intend to keep. This example assumes its stored document
template is passage: {{ content }}; preserve the current template exactly for an embedder that
a space references:
curl -X PUT "$GOODMEM_REST_URL/v1/embedders/$EMBEDDER_ID" \
-H "x-api-key: $GOODMEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputFormat":{"queryTemplate":"search: {{ content }}","documentTemplate":"passage: {{ content }}"}}'This replaces the query template, keeps the specified passage template, and removes any stored
instruction. Omitting inputFormat preserves the stored format. To change just one field with
the CLI, supply only that field:
goodmem embedder update "$EMBEDDER_ID" --query-template "search: {{ content }}"The CLI reads the stored format and merges your flags. goodmem reranker update uses the same
flags and merging behavior.
Clear a field or the whole format
An empty flag value removes that field. Clear the instruction and query template together when the query template requires the instruction:
goodmem embedder update "$EMBEDDER_ID" --instruction "" --query-template ""To remove all three fields:
goodmem embedder update "$EMBEDDER_ID" --clear-input-formatThe REST equivalent is PUT /v1/embedders/{id} with body {"inputFormat":{}}. The following
restriction applies if you clear a referenced embedder's document template.
The document template of an embedder in use
GoodMem rejects a document-template change or removal with HTTP 412 (FAILED_PRECONDITION) while
a space references the embedder. To use a different document format for already indexed content:
-
Register a replacement embedder with the desired document template and the endpoint's other required settings, using the create request above as a pattern. Set
NEW_EMBEDDER_IDto its returned ID. -
Create a space with that embedder, preserving the original space's intended chunking settings. For example, to use the default recursive chunking settings:
goodmem space create --name "Reformatted documents" --embedder-id "$NEW_EMBEDDER_ID"Set
NEW_SPACE_IDto the returned space ID. See space creation for other chunking settings. -
Ingest each source document into the new space. Set
SOURCE_FILEto the original document andMETADATA_FILEto its JSON metadata file, then repeat for each document:goodmem memory create --space-id "$NEW_SPACE_ID" --file "$SOURCE_FILE" --metadata "@$METADATA_FILE" -
Wait for ingestion to complete, test retrieval against the new space, then point your application's retrieval requests at it.
For large spaces, automate paginated memory listing and batch creation in bounded requests. Check each batch item's result, then monitor processing until ingestion completes. Plan for reading, parsing, and embedding the content again, plus temporary storage for both spaces. If the original files are unavailable, download stored original content. When GoodMem has no stored source bytes, recover the content from its external source. Preserve metadata and any per-memory chunking settings when creating the replacement memories. The new memories have new IDs and creation times. Keep the old resources until you validate the cutover, then choose retention or cleanup according to your rollback needs.
GoodMem does not automatically rebuild the old vectors. You can change the embedder's instruction and query template while a space references it. You can change all three reranker fields. A resource GET shows the new stored format immediately after an update. Reranker inference uses cached settings that can take up to 30 seconds to refresh.
Override the format for one request
With SPACE_ID set to a space using an instruction-bearing embedder, replace its instruction for
one retrieval:
goodmem memory retrieve \
--space-id "$SPACE_ID" \
--query-instruction "Given a claim, retrieve documents that support or refute the claim" \
"Does vitamin C prevent colds?"Only embedders whose effective query template reads instruction use this value. Other embedders
ignore it. The reranker does not receive it. Stored settings stay unchanged.
To address a particular embedder, set EMBEDDER_ID to an embedder of the requested space:
goodmem memory retrieve \
--space-id "$SPACE_ID" \
--embedder-query-format '{"embedderId":"'"$EMBEDDER_ID"'","queryTemplate":"search_query: {{ content }}"}' \
"deployment strategies"This replaces that embedder's query template for the request. To set a request-wide instruction
and a template that reads it with REST, use POST with the same SPACE_ID and EMBEDDER_ID:
curl -X POST "$GOODMEM_REST_URL/v1/memories:retrieve" \
-H "x-api-key: $GOODMEM_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/x-ndjson" \
--data-binary @- <<JSON
{
"message": "Does vitamin C prevent colds?",
"spaceKeys": [{"spaceId": "$SPACE_ID"}],
"queryInstruction": "Given a claim, retrieve documents that support or refute the claim",
"embedderQueryFormats": [{
"embedderId": "$EMBEDDER_ID",
"queryTemplate": "Instruct: {{ instruction }}\nQuery:{{ content }}"
}]
}
JSONThe entry's query template uses the request-wide instruction. For the behavior of omitted and empty values and precedence, see retrieval overrides.
Override a reranker's format
Reranker overrides are keys in the chat post-processor's config, next to reranker_id. With
RERANKER_ID set to the vLLM reranker from Configure a reranker, replace
its instruction for one retrieval:
curl -X POST "$GOODMEM_REST_URL/v1/memories:retrieve" \
-H "x-api-key: $GOODMEM_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/x-ndjson" \
--data-binary @- <<JSON
{
"message": "deployment strategies",
"spaceKeys": [{"spaceId": "$SPACE_ID"}],
"postProcessor": {
"name": "com.goodmem.retrieval.postprocess.ChatPostProcessorFactory",
"config": {
"reranker_id": "$RERANKER_ID",
"reranker_instruction": "Prefer passages that describe a release procedure"
}
}
}
JSONvLLM receives the new instruction in its instruction field, the unchanged query, and each chunk
with its stored title prefix. reranker_query_template and reranker_document_template replace
the templates in the same way. An empty string or JSON null removes a field for the request.
If the new query template reads {{ instruction }}, the instruction moves into the query, and
GoodMem no longer sends the instruction field. With the CLI, pass the same config object to
goodmem memory retrieve --post-processor-args.
An invalid reranker override produces a streamed status event and returns results without reranking, even when the HTTP retrieval request succeeds. For all key rules and status codes, see the chat post-processor's reranker input format.