Model input formats
Fields, template syntax, provider policy, and request overrides for embedder and reranker input.
Model input formats
An input format shapes the text sent to an embedder or reranker. It changes model input, while stored memory content and metadata stay unchanged. For configuration tasks, see Format model input.
Stored fields
The resource's inputFormat object (gRPC: input_format) has three optional fields:
| REST field | gRPC and Python field | Meaning |
|---|---|---|
instruction | instruction | Plain-text task instruction. Never evaluated as a template. |
queryTemplate | query_template | Template applied to retrieval query text. |
documentTemplate | document_template | Template applied to each indexed chunk for an embedder, or each retrieved chunk for a reranker. |
An absent template sends that text unchanged. An empty template and a blank instruction count as absent. Other values retain their leading and trailing whitespace.
A whitespace-only template is nonempty and fails the content-placement rule below.
Instructions and templates cannot contain a NUL character (U+0000).
Providers
| Resource | Provider | Nonempty format |
|---|---|---|
| Embedder | OPENAI, VLLM, TEI, LLAMA_CPP | Accepted. The query template must read any instruction. |
| Embedder | GEMINI | Accepted, with creation defaults described below. The query template must read any instruction. |
| Embedder | VOYAGE, COHERE, JINA, DASHSCOPE | Rejected. |
| Reranker | All supported providers | Accepted. Instruction delivery depends on the provider and template. |
GoodMem accepts an empty format ({}) for every provider. Voyage, Cohere, Jina, and DashScope's
native embedding dialect receive a query or document role from GoodMem. The restriction also covers
DashScope's contents dialect, which has no query or document role field.
Gemini defaults
When you create a Gemini embedder and omit inputFormat, GoodMem stores these templates:
{
"queryTemplate": "task: search result | query: {{ content }}",
"documentTemplate": "title: {{ memory.metadata.title | default('none') }} | text: {{ content }}"
}The create response shows the stored values. An explicitly supplied format stores only the fields
supplied; GoodMem does not fill unspecified fields with defaults. This also applies when you set
any input-format flag on a CLI create command. {} suppresses both defaults. Defaults are a
creation rule, not a fallback applied on each request. See Gemini registration.
Instruction delivery
GoodMem selects one delivery channel:
- When the query template references
instruction, the template controls the rendered query. GoodMem omits the provider's instruction field. - Otherwise, a reranker instruction uses the provider's own field:
instructionforVLLM,instructforDASHSCOPE. - GoodMem rejects a supplied instruction if neither channel can deliver it. No supported embedding provider has a separate instruction field.
A template can transform, omit, or repeat the instruction. For example,
{{ instruction | length }}|{{ content }} sends its length, and
{{ instruction }}|{{ instruction }}|{{ content }} repeats it. To include the instruction
unchanged, output {{ instruction }} once without a filter or condition. The delivery channel
does not guarantee that the backend or model uses the instruction as intended.
Template rules
Templates use a restricted subset of Pebble expressions:
- Use
{{ }}expressions. GoodMem rejects tags ({% %}), comments, function calls, and method calls. - Output
{{ content }}exactly once, without a filter, operator, or condition around it. - Other expressions can use the supported operations below within the permitted variable scope.
- A query template that reads
instructionneeds an instruction or a fallback, such as{{ instruction | default('Retrieve relevant passages') }}.
GoodMem validates creation, updates, and effective request overrides. If a create request, update
request, or embedder override has an invalid format, GoodMem returns HTTP 400 (INVALID_ARGUMENT).
Reranker override failures use the
post-processor's streamed status behavior.
Supported expressions
| Operation | Syntax |
|---|---|
| Fallback | value | default('fallback') or value | default(default='fallback'). With no argument, the fallback prints as empty text. |
| Case and whitespace | value | upper, value | lower, value | trim; no arguments. Case conversion is locale-independent. |
| Length | value | length; no arguments. Counts UTF-16 code units for text. Returns zero for numbers, booleans, and null. |
| Concatenation | left ~ right |
| Comparison | ==, !=, <, <=, >, >= |
| Boolean logic | and, or, not |
| Tests | value is empty, value is defined, value is null, and their is not forms; no arguments. |
| Conditional | condition ? thenValue : elseValue |
GoodMem supports parentheses, string and numeric literals, booleans, and null. Numeric literals
can be negative, as in memory.metadata.temp < -1.5 and default(-1). It rejects other
filters, operators, tests, and collection literals. The format and replace filters
are unavailable because they can allocate large intermediate strings before GoodMem writes output.
The abbreviate filter is unavailable because it can split a Unicode surrogate pair.
Use literal text, concatenation, or a conditional for simple formatting.
When the instruction is absent, it is unbound: instruction is defined is false, and
instruction | default('fallback') safely supplies text. instruction is empty does not guard
an unbound variable under strict evaluation; use instruction is defined or default instead.
The chat post-processor uses a separate prompt-template contract. Its
template limitations
also exclude the range function and .. operator.
GoodMem checks every expression before evaluation, including both conditional branches and all
arguments. Each intermediate value must have a conservative size bound within the limit below;
applying length afterward does not excuse an oversized intermediate. Bounds
allow for Unicode case expansion, so GoodMem can reject a long chain of upper and lower even
when you supply ASCII text. Simplify the expression or shorten its inputs in that case.
Variables
These names are literal template identifiers in every SDK. Python property names use snake_case,
but the text inside a template still uses memory.createdAt and chunk.sequenceNumber.
| Variable | Scope | Value |
|---|---|---|
content | Query and document | Query text or chunk text. |
instruction | Query only | Effective task instruction. |
memory.metadata.<key> | Document only | String, number, or boolean from a top-level memory metadata key. |
memory.createdAt | Document only | Memory creation timestamp in ISO-8601 UTC with exactly three fractional digits (for example, 2026-01-01T00:00:00.000Z). |
chunk.sequenceNumber | Document only | Zero-based integer position within the memory. Use chunk.sequenceNumber == 0 for the first chunk. An unknown position is null. |
Use memory.metadata['my key'] for keys that are not simple names. GoodMem does not traverse
nested objects or arrays. Missing metadata, an unknown creation time, and an unknown sequence number
render as empty text. Query templates cannot read memory or chunk facts. Document templates cannot read instruction.
Metadata values
Document templates evaluate JSON scalars with their original types.
| JSON value | Value in an expression | Printed text |
|---|---|---|
| String | Text. GoodMem trims whitespace, collapses each internal whitespace run to one space, and keeps the first 256 Unicode code points. | The normalized text. A string such as "007" keeps its leading zeros. |
| Number | Number, available for numeric comparisons. | Plain decimal digits without an exponent or trailing fractional zeros. |
| Boolean | true or false, available directly as a condition. | true or false. |
| Missing key, JSON null, object, array, or oversized number | Null. | Empty text. |
For example, this template adds a draft label only when draft is true, and a low-stock label
when the numeric count is less than 10:
{{ memory.metadata.draft ? 'DRAFT ' : '' }}{{ memory.metadata.count < 10 ? 'Low stock: ' : '' }}{{ content }}With {"draft": false, "count": 0} and content Paper, the model receives Low stock: Paper.
A missing count makes the comparison false. A missing or null flag also counts as false in
not, and, or, and conditional expressions. For example, not memory.metadata.draft is true
when the memory has no draft flag. The string "false" is nonempty text and selects the true branch.
Ordering requires numeric operands. GoodMem rejects memory.metadata.count < '10' at registration.
When a conditional branch or a default fallback supplies a value to an ordering comparison,
use a number or null. For example,
(memory.metadata.count | default(-1)) < 10 uses -1 for a missing count.
To display a label for a missing count, put the comparison inside the other branch, as in
memory.metadata.count is null ? 'n/a' : (memory.metadata.count < 10 ? 'low' : 'high').
With memory.metadata.count < 10, a memory containing the string "7" or the boolean true
produces a formatting error when GoodMem renders that memory. Metadata numbers use double
precision. Store identifiers that require exact large-integer precision as strings.
A formatting error during ingestion stops the processing of that memory. Its processing status
becomes FAILED, and GoodMem does not retry it. The error names the embedder and the template
problem. Correct the metadata and create the memory again, or correct the template. If a space
references the embedder, the template cannot change; use a
replacement embedder. A formatting error during reranking
skips reranking for that request and returns the results in retrieval order, with a status event.
See the post-processor's status table.
The default filter replaces missing or empty values and preserves boolean false and numeric
zero. The trim filter expects text and fails on numbers and booleans. To apply a text filter
to a scalar's printed value, concatenate it with an empty string first. For example,
(memory.metadata.draft ~ '') | length returns 5 for the boolean false.
Use a fallback to supply a title when the metadata has none:
title: {{ memory.metadata.title | default('none') }} | text: {{ content }}Limits
| Item | Limit |
|---|---|
| Instruction | 2,048 Unicode code points |
| Each template | 2,048 Unicode code points |
Each {{ }} expression | 128 tokens, including operators and parentheses; a quoted string is one token |
| Each intermediate expression value | 8,192 UTF-16 code units, checked before evaluation |
| Rendered text added around content | 8,192 UTF-16 code units |
| One metadata value | 256 Unicode code points for text. Oversized numbers read as empty. |
Checks apply during validation and every rendering, including cached templates. Output exceeding
the limit fails with INVALID_ARGUMENT; GoodMem discards the partial rendering. GoodMem inserts the actual query or
document content afterward; it does not count toward the surrounding-text limit.
The format limits do not replace the model's input or token limits. Templates consume part of that budget. A backend can truncate input or reject it at its own limits. Truncation behavior depends on the backend. Also check whether the serving runtime adds a prefix of its own: a duplicate prefix can change the input even when the request succeeds.
Updates and request overrides
Stored updates
REST and gRPC updates replace the entire format:
| Submitted value | Result |
|---|---|
Omit inputFormat | Preserve stored instruction and templates. |
Supply inputFormat | Replace all three fields. Remove any omitted inner fields. |
Supply inputFormat: {} | Clear the format. |
The CLI merges the input-format flags you supply with the current stored format before sending
the replacement. An empty flag value removes that field. --clear-input-format clears all three.
See the update task.
Embedder retrieval overrides
A request can override query formatting without changing stored configuration or document inputs.
| Field | Behavior |
|---|---|
queryInstruction | Request-wide instruction, used only by embedders whose effective query template reads instruction. Other embedders ignore it. Empty or blank counts as omitted and preserves the stored instruction. Never sent to the reranker. |
embedderQueryFormats[] | Per-embedder entry with embedderId and an optional instruction, queryTemplate, or both. Omitted fields preserve the next applicable value. An empty or blank instruction clears the instruction, and "" clears the query template for this request. |
For instructions, precedence is per-embedder entry, then queryInstruction, then stored
instruction. For query templates, precedence is per-embedder entry, then stored template.
Clearing an instruction still requires a fallback if the effective template reads it. Clearing a
query template sends unchanged query text. Explicitly addressing a nonempty instruction to an
embedder without a template that reads it is invalid.
Per-embedder entries must name distinct valid UUIDs, set at least one override field, and refer to embedders used by the requested spaces. Their providers must accept input formats, even when an entry clears values. GoodMem validates the effective formats before embedding the query.
Reranker retrieval overrides
The chat post-processor accepts reranker_instruction, reranker_query_template, and
reranker_document_template. Omission preserves the stored field. An empty string or JSON null
clears it for that request. A nonempty string overrides it; other types are invalid. The effective
format must still satisfy the instruction-delivery rules. These are separate from embedder overrides. See the processor reference for their
configuration, complete example, and status and fallback behavior.
An invalid reranker override produces a streamed status event and returns results without reranking.
The HTTP retrieval request can still succeed, so clients must inspect the stream's status events.
Whitespace and transport
GoodMem preserves literal LF, CRLF, and CR line breaks, including immediately after }} and at
the end of a template. Spaces and tabs are also significant.
Text extraction can end a chunk with a line break. For example, the last chunk of a plain-text
memory ends with one. That line break is part of {{ content }}, so the model receives it after
any text that the template adds before the content. The examples on these pages omit it.
- REST JSON:
\n,\r\n, and\rdecode to actual line breaks before template evaluation. - CLI inline flags: the shell must supply the actual characters. In Bash/Zsh,
$'Instruct: {{ instruction }}\nQuery:{{ content }}'contains an LF. - CLI template files:
--query-template-fileand--document-template-fileremove one leading UTF-8 BOM, if present, and one final LF or CRLF. All other characters remain, including meaningful whitespace and a final CR. Use two terminal line breaks to retain one in the submitted template. If no content remains, the CLI rejects the file. To clear a template, use an explicit empty inline flag, such as--query-template "". - Console: press Enter in a template field. The exact-value display exposes whitespace in the configured value. It does not render a query or call the server to preview model input.
Pebble quoted strings do not interpret backslash escapes for newlines or tabs. GoodMem rejects
\n, \r, or \t inside them. This JSON is invalid because \\n decodes to the literal
backslash sequence inside the Pebble string:
{
"instruction": "Retrieve relevant passages",
"queryTemplate": "{{ instruction ~ '\\n' }}{{ content }}"
}Place a literal line break between expressions instead.
Indexed vectors and propagation
An embedder's document template defines the text used to compute indexed vectors. Changing or
clearing it while any space references the embedder fails with HTTP 412
(FAILED_PRECONDITION). The guard is a space-reference check. It is not a separate test for
running ingestion jobs.
To change the document format of already indexed content, create a replacement embedder and a space using it, then ingest the source content and intended metadata into that space. GoodMem does not automatically rebuild existing vectors or re-embed existing chunks after a metadata edit. Reranking reads the available metadata when it runs.
Embedder instruction and query-template changes affect subsequent retrievals. You can update all reranker format fields. A resource GET returns the new stored format immediately after an update. Reranker inference uses cached configuration that can take up to 30 seconds to refresh.
Where formats apply
- Embedder document templates apply during ingestion. Query templates apply during retrieval. Reranker templates apply when the post-processor reranks retrieved chunks.
- Ping, health checks, and diagnostics use unchanged test text.
- Inference proxy calls forward the caller's provider payload. Stored formats do not apply.
- REST GET retrieval supports
queryInstruction.embedderQueryFormatsand the reranker format keys require POST. See the retrieval API. fetchMemorycontrols memory definitions returned to the caller. Setting it to false does not remove metadata needed internally for document formatting.- LLM answer-generation prompts use the separate ChatPostProcessor prompt configuration. Console Search prompt controls edit those answer prompts and do not expose retrieval-format overrides.
GoodMem has no server-backed preview of rendered model input. To verify end-to-end formatting, inspect requests received by a development model endpoint while ingesting and retrieving sample content. Ping and proxy requests bypass formatting and cannot verify it.
For individual resource operations, see the REST API, CLI, and SDK references.
Filter Expressions Reference
Detailed reference for the GoodMem metadata filter language including syntax, types, operators, and functions.
Client-Specified Identifiers
Learn how to use client-provided UUIDs for deterministic resource creation, Infrastructure-as-Code, and multi-environment synchronization.