Retrieve

The Retrieve node performs the R of RAG: vector similarity search over an embedded string storage, attaching the top matches to the current interaction as a knowledge component.

It does not modify the prompt directly. Rendering is delegated to the downstream Generate node's Mustache template, which decides where and how the attached components appear in the prompt.

NodeType: Retrieve.

Parameters

Param	Type	Default	Range	Structural	Description
embedded_string_storage	Optional[str]	inherit model default	—	✓	Named embedded string storage (EmbeddedStringStorageManager). Structural because the storage is resolved and referenced at construction.
embedding_model	Optional[str]	inherit model default	—	✓	Embedding model catalog name. Structural because the model context is allocated at construction.
top_k	int	2	1.0 – 1000.0	—	Number of chunks to retrieve.
threshold	float	0.0	0.0 – 1.0	—	Maximum cosine distance; results above this threshold are dropped. Zero disables filtering (no threshold).
source	Optional[str]	inherit model default	—	—	Label attached to the KnowledgeComponent; defaults to node name.
filter	Optional[str]	inherit model default	—	—	JSON filter compiled against the storage's metadata schema. Empty string = no filter. Mutable — recompiles the filter on change.

Exits

Each exit is a structural string field on the node's params; its value names the target node (empty = END).

Exit	Param field	Description
found	found_exit	Exit taken when retrieval returned at least one chunk above threshold. Empty string = END.
not_found	not_found_exit	Exit taken when retrieval produced no results. Empty string = END.

Exit routes

Route	Fires when
found	At least one chunk survived threshold filtering.
not_found	No usable human message, or zero chunks after filtering.

Both routes must be wired in the graph — either to different targets or to the same target. A missing wire is a compilation failure (error 3003).

Side effects

• Embeds the current user message via the configured embedding model.
• Queries the storage's HNSW index and applies the threshold filter.
• Attaches a knowledge block (source + surviving chunks) to the current turn. If nothing survives filtering, an empty block is still attached (the Mustache {{#knowledge_<source>}} section simply renders nothing).

The attached knowledge is rendered into the prompt on the next Generate node, via the template and placement params on that node.

Diagnostics

When enable_diagnostics = true, the node contributes these keys to TurnComplete.debug_info:

Key	Meaning
source	The source label attached to the component.
query	The human message text that was embedded.
top_k	Number of chunks requested.
threshold	Max cosine distance used for filtering (or "inf" when disabled).
raw_result_count	Chunks returned by the index before filtering.
filtered_count	Chunks removed by the threshold filter.
result_count	Chunks actually attached to the component.
result[NNN].id	Chunk id (zero-padded, sorted by rank).
result[NNN].distance	Cosine distance (lower = more similar).
result[NNN].text	Chunk text that will be rendered into the prompt.
filter	Raw JSON of the active filter (empty when no filter is set).

Minimum working example

PythonC++UnityUnreal

from tryll_client.graph import GraphDescription, GenerateParams, RetrieveParams, Placement

RAG_TEMPLATE = (
    "{{#knowledge}}"
    "{{name}}:\n{{#chunks}}- {{text}}\n{{/chunks}}\n"
    "{{/knowledge}}"
)

graph = (
    GraphDescription()
    .add_node("knowledge", RetrieveParams(
        embedded_string_storage="aquarium_kb",
        embedding_model="All-MiniLM-L6-v2 (Q4_K_M)",
        top_k=3,
        threshold=0.6,
        found_exit="answer",
        not_found_exit="answer",
    ))
    .add_node("answer", GenerateParams(
        template=RAG_TEMPLATE,
        placement=Placement.BeforeUserAsSystem,
        default_exit="",   # empty = END
    ))
    .set_start_node("knowledge")
    .set_default_model_name("My Local Model")
)

agent = client.create_agent(graph)

using namespace Tryll::Client;
using namespace Tryll::NodeParams;

RetrieveParamsT kp;
kp.embedded_string_storage = "aquarium_kb";
kp.embedding_model         = "All-MiniLM-L6-v2 (Q4_K_M)";
kp.top_k                   = 3;
kp.threshold               = 0.6f;
kp.found_exit              = "answer";
kp.not_found_exit          = "answer";

GenerateParamsT gp;
gp.template_  = "{{#knowledge}}{{name}}:\n{{#chunks}}- {{text}}\n{{/chunks}}\n{{/knowledge}}";
gp.placement  = ::Tryll::Placement::BeforeUserAsSystem;
// gp.default_exit = ""; // empty = END (the default)

GraphDescription graph;
graph.AddRetrieve("knowledge", std::move(kp))
     .AddGenerate("answer",    std::move(gp))
     .SetStartNode("knowledge")
     .SetDefaultModelName("My Local Model");

auto agent = client.CreateAgent(graph);

using Tryll.Client;

var graph = new TryllGraphBuilder()
    .AddRetrieve("knowledge", new TryllRetrieveParams
    {
        EmbeddedStringStorage = "aquarium_kb",
        EmbeddingModel        = "All-MiniLM-L6-v2 (Q4_K_M)",
        TopK                  = 3,
        Threshold             = 0.6f,
        FoundExit             = "answer",
        NotFoundExit          = "answer",
    })
    .AddGenerate("answer", new TryllGenerateParams
    {
        Template  = "{{#knowledge}}{{name}}:\n{{#chunks}}- {{text}}\n{{/chunks}}\n{{/knowledge}}",
        Placement = TryllPlacement.BeforeUserAsSystem,
    })
    .SetStartNode("knowledge")
    .SetDefaultModelName("My Local Model")
    .Build();

#include "Generated/TryllGraphBuilder.Nodes.h"
#include "Generated/TryllNodeParamsFactory.h"

UTryllRetrieveParams* KP = UTryllNodeParamsFactory::MakeRetrieveParams(this);
KP->bOverrideEmbeddedStringStorage = true;
KP->EmbeddedStringStorage = TEXT("aquarium_kb");
KP->bOverrideEmbeddingModel = true;
KP->EmbeddingModel = TEXT("All-MiniLM-L6-v2 (Q4_K_M)");
KP->TopK      = 3;
KP->Threshold = 0.6f;
KP->FoundExit    = TEXT("answer");
KP->NotFoundExit = TEXT("answer");

UTryllGenerateParams* GP = UTryllNodeParamsFactory::MakeGenerateParams(this);
GP->bOverrideTemplate = true;
GP->Template  = TEXT("{{#knowledge}}{{name}}:\n{{#chunks}}- {{text}}\n{{/chunks}}\n{{/knowledge}}");
GP->Placement = ETryllPlacement::BeforeUserAsSystem;

FTryllGraphDescription Graph = FTryllGraphBuilder()
    .AddNode(TEXT("knowledge"), KP)
    .AddNode(TEXT("answer"),    GP)
    .SetStartNode(TEXT("knowledge"))
    .SetDefaultModelName(TEXT("My Local Model"))
    .Build();

See the full walkthrough in How to create a simple RAG assistant.

Client bindings

• C++: GraphDescription::AddRetrieve(name, RetrieveParamsT) — GraphDescription.h
• Python: GraphDescription.add_node(name, RetrieveParams(...)) — tryll_client.graph
• Unity: TryllGraphBuilder.AddRetrieve(name, new TryllRetrieveParams{...}) — Runtime/Generated/TryllGraphBuilder.Nodes.cs
• Unreal: AddRetrieveNode(builder, name, UTryllRetrieveParams*) — Generated/TryllGraphBuilder.Nodes.h

Related

• Embedded String Storage
• Concept: RAG
• How to create a simple RAG assistant
• How to use Mustache templates
• Glossary