GoodMemGoodMem
Reference

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 fieldgRPC and Python fieldMeaning
instructioninstructionPlain-text task instruction. Never evaluated as a template.
queryTemplatequery_templateTemplate applied to retrieval query text.
documentTemplatedocument_templateTemplate 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

ResourceProviderNonempty format
EmbedderOPENAI, VLLM, TEI, LLAMA_CPPAccepted. The query template must read any instruction.
EmbedderGEMINIAccepted, with creation defaults described below. The query template must read any instruction.
EmbedderVOYAGE, COHERE, JINA, DASHSCOPERejected.
RerankerAll supported providersAccepted. 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:

  1. When the query template references instruction, the template controls the rendered query. GoodMem omits the provider's instruction field.
  2. Otherwise, a reranker instruction uses the provider's own field: instruction for VLLM, instruct for DASHSCOPE.
  3. 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 instruction needs 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

OperationSyntax
Fallbackvalue | default('fallback') or value | default(default='fallback'). With no argument, the fallback prints as empty text.
Case and whitespacevalue | upper, value | lower, value | trim; no arguments. Case conversion is locale-independent.
Lengthvalue | length; no arguments. Counts UTF-16 code units for text. Returns zero for numbers, booleans, and null.
Concatenationleft ~ right
Comparison==, !=, <, <=, >, >=
Boolean logicand, or, not
Testsvalue is empty, value is defined, value is null, and their is not forms; no arguments.
Conditionalcondition ? 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.

VariableScopeValue
contentQuery and documentQuery text or chunk text.
instructionQuery onlyEffective task instruction.
memory.metadata.<key>Document onlyString, number, or boolean from a top-level memory metadata key.
memory.createdAtDocument onlyMemory creation timestamp in ISO-8601 UTC with exactly three fractional digits (for example, 2026-01-01T00:00:00.000Z).
chunk.sequenceNumberDocument onlyZero-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 valueValue in an expressionPrinted text
StringText. 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.
NumberNumber, available for numeric comparisons.Plain decimal digits without an exponent or trailing fractional zeros.
Booleantrue or false, available directly as a condition.true or false.
Missing key, JSON null, object, array, or oversized numberNull.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

ItemLimit
Instruction2,048 Unicode code points
Each template2,048 Unicode code points
Each {{ }} expression128 tokens, including operators and parentheses; a quoted string is one token
Each intermediate expression value8,192 UTF-16 code units, checked before evaluation
Rendered text added around content8,192 UTF-16 code units
One metadata value256 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 valueResult
Omit inputFormatPreserve stored instruction and templates.
Supply inputFormatReplace 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.

FieldBehavior
queryInstructionRequest-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 \r decode 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-file and --document-template-file remove 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. embedderQueryFormats and the reranker format keys require POST. See the retrieval API.
  • fetchMemory controls 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.

On this page