Knowledge node

The knowledge node retrieves relevant chunks from a knowledge base and writes the result into run state under the node’s own id. It is how you add retrieval-augmented generation (RAG) to a workflow: search your connected documents for a query, then feed the retrieved context into a downstream LLM node or agent node. The node works against the ModuleX-managed store (modulexdb) and against external vector databases — Qdrant, Pinecone, Weaviate, and MongoDB Atlas. For the broader retrieval model — knowledge bases, ingest, managed vs BYOK — see knowledge & RAG. To pass a dynamic query into the node, use {{node_id.field}} references — the same reference system documented in variables & references and the workflow engine.

What the node does

When the engine compiles your workflow, the knowledge node becomes a single async step (workflow engine). At run time the node:

Resolves the search query. If query_from_input is true, it reads the query from common run-state fields (query, question, input, user_input, message); otherwise it resolves the query string, replacing every {{...}} token with its value from run state.
Coerces the resolved query to a string. If the query is empty, the node returns an empty result (total_results: 0) carrying an error of Empty query rather than failing the run.
Routes by provider_type. modulexdb runs against your native ModuleX knowledge base via the search service; any other value runs against the matching external provider adapter.
For a managed native knowledge base, reserves a retrieval credit before the search and records it on success — see credit impact.
Performs a vector (cosine-similarity) search, returning up to top_k chunks above min_score.
Formats the result per output_format (chunks, a context string, or both) and writes it into run state under the node’s id.

The output of a knowledge node is always stored in run state under the node’s id — for example a node with id: "retrieve_1" writes to {{retrieve_1}}, and its context string is {{retrieve_1.context}}. There is no output_key field on this node; reference results by node id.

Picking the knowledge base

You point the node at a knowledge base through a credential, not a knowledge-base id. Every native ModuleX knowledge base is created with a linked internal credential (the “native KB = credential” pattern), so credential_id resolves to the knowledge base behind it. For an external provider, credential_id is the stored credential for that vector store. See managing credentials.

Managed native store (modulexdb) — set provider_type to modulexdb (the default) and credential_id to the knowledge base’s credential. The node resolves the linked knowledge base and searches it directly; embeddings are handled by the knowledge base’s own configuration, so you do not set embedding_config. Managed retrieval is billed in credits. See managed knowledge (modulexdb) and modulexdb (managed).
External provider — set provider_type to qdrant, pinecone, weaviate, or mongodb_atlas, set credential_id to that provider’s credential, and provide collection_name (required) plus an embedding_config so the node can embed the query before searching. External (BYOK) retrieval is not charged in credits. See external knowledge providers and knowledge providers.

Configuration (`KnowledgeNodeConfig`)

These fields live on the node’s knowledge_config. In the builder you set them through the detail panel; over the API they appear inside the node definition (the builder also accepts a wrapped {config: {...}} form, which the backend normalizes to knowledge_config).

Connection

string

required

The stored credential for the knowledge base or external vector store. Required. For a native ModuleX knowledge base this is the knowledge base’s linked credential, which the node resolves to the knowledge base behind it. See managing credentials.

string (enum)

default:"modulexdb"

Which knowledge provider to query. One of modulexdb, qdrant, pinecone, weaviate, mongodb_atlas. Defaults to modulexdb (the managed native store). See knowledge providers.

Query

string

required

The search query. Required. Supports {{node_id.field}} references for a dynamic query built from upstream output — for example {{intake_1.message}}. The node resolves the template against run state before searching.

boolean

default:"false"

When true, the node ignores query and instead reads the query from run state, trying the fields query, question, input, user_input, then message in order (and, if that value is a dict, its query / input / text key). Use it when the run’s top-level input is itself the search query. When false (the default), the node uses the resolved query field.

Retrieval settings

integer

default:"5"

Maximum number of chunks to retrieve. Range 1–50. Higher values return more context (and cost more tokens downstream); lower values keep the context tight.

number

default:"0.3"

Minimum cosine-similarity score a chunk must reach to be included. Range 0.0–1.0. Chunks below this floor are dropped, so a strict threshold can return fewer than top_k results — or none. Raise it to favor precision; lower it to favor recall.

integer

default:"2000"

Token budget for the formatted context string. Range 100–10000. Only applies when output_format is context or both: the node appends chunks in score order until adding the next chunk would exceed this budget, then stops. Tokens are estimated as roughly 4 characters each. Has no effect on the raw chunks list.

Filtering

object

Provider-specific filter conditions applied to the search. Optional. The accepted shape depends on the provider; for native knowledge bases, document filtering is handled through document_ids (below).

string[]

Restrict the search to specific document ids within the knowledge base. Optional. Native (modulexdb) knowledge bases only — ignored by external providers. Use it to scope retrieval to a known subset of documents.

Output

string (enum)

default:"context"

How results are returned. One of:

context (default) — a single formatted context string ready to drop into a prompt, with chunks numbered and (optionally) labeled by source and score.
chunks — the raw list of matched chunks with their scores and metadata.
both — both the context string and the chunks list.

See outputs for the exact shape of each.

boolean

default:"true"

Include each chunk’s metadata in the results. Optional; defaults to true. Applies to the chunks list.

boolean

default:"true"

Include the source document label in the formatted context string. Optional; defaults to true. When true, each chunk in the context output is prefixed with its source filename and score, for example (Source: manual.pdf, Score: 0.83).

External-provider fields

string

The collection or index name on the external vector store. Required for external providers (qdrant, pinecone, weaviate, mongodb_atlas); a missing collection_name raises an error at run time. Ignored for modulexdb.

string

The namespace within the index, for providers that support one (for example Pinecone). Optional. Ignored for modulexdb.

EmbeddingConfig object

How to embed the query before searching. Required for external providers that do not embed internally (Qdrant, Pinecone, and similar) so query vectors match the vectors stored at ingest time. Not used for modulexdb, which embeds using the knowledge base’s own configuration. See the embedding_config object.

The `embedding_config` object

string

required

The integration name of the embedding provider, for example openai or cohere. Required when embedding_config is set.

string

required

The provider identifier, for example openai. Required when embedding_config is set.

string

required

The embedding model id, for example text-embedding-3-small. Required when embedding_config is set. Use the same embedding model you used to ingest the external collection, so query and stored vectors are comparable.

string

A specific stored credential for the embedding provider. Optional; if omitted, the organization’s default credential for that integration is used. See managing credentials.

Retry configuration

The knowledge node is retry-wrapped. You can attach a retry_config to the node definition itself (not inside knowledge_config) to control how a failed retrieval is retried. If you omit it, the engine applies its default retry policy. Errors are only retried when their type is in retry_on_error_types.

integer

default:"3"

Total attempts including the first. Range 1–10. 1 means no retry; 3 means the initial call plus 2 retries.

number

default:"1.0"

Seconds to wait before the first retry. Range 0.1–60.

number

default:"2.0"

Multiplier applied to the delay between successive retries (exponential backoff). Range 1–5.

string[]

Exception type names that trigger a retry. Errors not in this list fail immediately.

The node already catches retrieval exceptions internally and returns an empty result with an error field rather than raising (see errors). Because of that, retry_config mainly covers transient failures that surface as exceptions before the node’s own handler — most retrieval problems show up as an error field on the node output, not as a retried failure. See error handling & retries.

Inputs and outputs

Inputs

The knowledge node has no fixed input fields. It builds its query from one of two sources:

query with references — {{node_id}} for an entire upstream node output, {{node_id.field}} for a nested value via dot/bracket path (for example {{intake_1.message}}), or {{input}} for the run’s top-level input. A reference that is the whole string keeps its native type and is then coerced to a string; a reference embedded in other text is string-substituted. See variables & references.
query_from_input: true — the node reads the query directly from run state (query, question, input, user_input, message), ignoring the query field.

Outputs

The node writes one value into run state under its id. The shape depends on output_format:

object

The retrieval result.

Show Result fields

integer

The number of chunks the search returned (after min_score filtering and the top_k cap), regardless of output_format.

string | null

The formatted context string. Present (non-null) when output_format is context or both; null when output_format is chunks. Chunks are concatenated in score order until the max_tokens budget is reached, each numbered [1], [2], … and — when include_source is true — prefixed with (Source: <filename>, Score: <score>).

array | null

The list of matched chunks. Present (non-null) when output_format is chunks or both; null when output_format is context. Each chunk carries its content, score, source document info, and (when include_metadata is true) metadata.

string

Present only when retrieval could not be performed — for example Empty query, or the message of a caught retrieval exception. When error is set, chunks is [], context is "", and total_results is 0. See errors.

Downstream nodes read the context with {{retrieve_1.context}}, the raw matches with {{retrieve_1.chunks}}, or a specific match field such as {{retrieve_1.chunks[0].content}}. A common pattern is to feed {{retrieve_1.context}} straight into an LLM node prompt.

Streaming

A knowledge node streams at the node level over SSE, like every workflow node. When the node finishes, the engine publishes a node_update event carrying the node’s output. On the wire this event is flat and uses the keys node and output — for example {type, node, output} — not the typed model field names. The run then ends with a done event.

The realtime wire dicts differ from the typed event models: the node_update frame uses node and output, and done carries only a message. Parse each SSE frame as JSON and switch on its type field — there is no SSE event: line. Details on SSE run streaming.

Credit impact

Retrieval credits depend on whether the knowledge base is managed or BYOK:

Managed native (modulexdb)

A native knowledge base whose embedding provider is ModuleX-managed (modulexai) is billed in credits. The node reserves one retrieval base credit before the search and records the base plus the query-embedding token cost on success. See credits & metering and managed knowledge (modulexdb).

BYOK / external

A bring-your-own-key knowledge base or external vector store (Qdrant, Pinecone, Weaviate, MongoDB Atlas) is uncosted — no ModuleX credits are charged for retrieval. You pay your provider directly. See external knowledge providers.

How the reservation works for a managed native knowledge base:

Before embedding and searching, the node reserves one retrieval base credit (the managed-retrieval admission step).
On a successful search, it settles the base credit and records the query-embedding token cost.
On a search error, it releases the reservation so the credit is not consumed.

Inside a running workflow, the managed-retrieval gate is best-effort: a billing hiccup or credit exhaustion does not crash the workflow. This differs from the interactive knowledge search API, which rejects-before-write and returns a DenialEnvelope on the request itself. Workflow run, Composer, Assistant, and the managed-knowledge surfaces are gated by the billing admission gate, which can return a DenialEnvelope as 402 / 403 / 429. The flat envelope shape is {code, layer, key, current, limit, reason}. See errors & status codes and usage gating & limits.

A retrieval base credit is one credit (RETRIEVAL_BASE = 1); at the managed-usage scale that is $0.01 plus the query-embedding token cost. See credits & metering for the credit unit and metering details.

Errors

The knowledge node is defensive: it catches retrieval failures and returns an empty result with an error field instead of failing the run. The cases below describe how each surfaces.

Empty query

If the resolved query is empty (no query, or query_from_input found nothing in run state), the node does not search. It returns {chunks: [], context: "", total_results: 0, error: "Empty query"} under its node id and the run continues. Check that your {{...}} reference resolves and that the upstream node ran first.

Missing knowledge_config

If a knowledge node has no knowledge_config, compilation fails with a configuration error (Knowledge node <id> missing knowledge_config). Ensure credential_id and query are set.

Credential or knowledge base not found

If credential_id does not match a credential in the current organization, or no knowledge base is linked to it, the node’s retrieval raises and is caught: the output carries an error such as Credential not found: <id> or No knowledge base linked to credential: <id>, with empty chunks/context. Confirm the credential id and that the native knowledge base still exists. See managing credentials.

External provider misconfiguration

For an external provider, a missing collection_name raises collection_name is required for external provider: <type>, caught and returned as the node’s error. Provide collection_name and an embedding_config whose model_id matches the model used at ingest. See external knowledge providers.

Embedding or search failure

A failure while embedding the query or running the search (provider error, network error, embedding-provider error) is caught and returned as the node’s error with empty results; for a managed native knowledge base the reserved retrieval credit is released. The run continues with an empty context — guard downstream nodes for the empty case, or branch on {{node_id.total_results}} with a conditional node.

Credit exhaustion mid-run (managed)

Because the managed-retrieval gate is best-effort inside a workflow, exhausted credits do not crash the run; retrieval may simply return empty. To avoid silent empty context, monitor credits and top up the wallet or upgrade your plan. On the interactive knowledge search API (not the workflow node), the same condition returns a DenialEnvelope (402/429) on the request. See usage gating & limits.

For the full taxonomy of error-envelope shapes and which surface emits each, see errors & status codes.

Full example

A two-node RAG workflow: a knowledge node retrieves context for the user’s question from a native ModuleX knowledge base, then an LLM node answers using only that context. The first tab shows the knowledge node definition as it appears in a workflow over the API; the next tabs run the workflow end to end with the SDKs and read the node’s output from run state.

{
  "id": "retrieve_1",
  "type": "knowledge",
  "name": "Retrieve product docs",
  "x": 320,
  "y": 160,
  "retry_config": {
    "max_attempts": 3,
    "initial_interval": 1.0,
    "backoff_factor": 2.0
  },
  "knowledge_config": {
    "credential_id": "a1b2c3d4-5e6f-4789-90ab-cdef01234567",
    "provider_type": "modulexdb",
    "query": "{{input.question}}",
    "top_k": 5,
    "min_score": 0.3,
    "max_tokens": 2000,
    "output_format": "context",
    "include_metadata": true,
    "include_source": true
  }
}

{
  "id": "answer_1",
  "type": "llm",
  "name": "Answer from context",
  "x": 640,
  "y": 160,
  "llm_config": {
    "llm": {
      "integration_name": "modulexai",
      "provider_id": "openrouter",
      "model_id": "claude-sonnet-4.6",
      "temperature": 0.2
    },
    "system_prompt": "Answer the question using only the provided context. If the context does not contain the answer, say you do not know.",
    "user_prompt": "Context:\n{{retrieve_1.context}}\n\nQuestion: {{input.question}}"
  }
}

# Run a workflow whose first node is the retrieve_1 knowledge node
curl -X POST https://api.modulex.dev/workflows/run \
  -H "Authorization: Bearer mx_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organization-ID: org_4d2b18" \
  -H "Content-Type: application/json" \
  -d '{
        "workflow_id": "wf_7f3a9c",
        "input": {
          "question": "How do I rotate an API key?"
        }
      }'

from modulex import ModuleX

client = ModuleX(
    api_key="mx_live_xxxxxxxxxxxxxxxxxxxx",
    organization_id="org_4d2b18",
)

run = client.workflows.run(
    "wf_7f3a9c",
    input={"question": "How do I rotate an API key?"},
)

# retrieve_1 wrote its retrieval result under its node id
print(run.state["retrieve_1"]["total_results"])  # -> 5
print(run.state["retrieve_1"]["context"][:120])   # -> "[1] (Source: api-keys.md, Score: 0.84) ..."

# answer_1 answered from that context
print(run.state["answer_1"])

import { ModuleX } from "@modulex/sdk";

const client = new ModuleX({
  apiKey: "mx_live_xxxxxxxxxxxxxxxxxxxx",
  organizationId: "org_4d2b18",
});

const run = await client.workflows.run("wf_7f3a9c", {
  input: { question: "How do I rotate an API key?" },
});

// retrieve_1 wrote its retrieval result under its node id
console.log(run.state.retrieve_1.total_results); // -> 5
console.log(run.state.retrieve_1.context.slice(0, 120)); // -> "[1] (Source: api-keys.md, Score: 0.84) ..."

// answer_1 answered from that context
console.log(run.state.answer_1);

Every request authenticates with Authorization: Bearer mx_live_… plus X-Organization-ID. See authentication and the run-a-workflow guide. To build and query a knowledge base end to end before wiring it into a workflow, see build a RAG knowledge base. To stream the run instead of waiting for the final state, see SSE run streaming.

Knowledge & RAG

The retrieval model: knowledge bases, ingest, managed vs BYOK, and how RAG works.

LLM node

Feed {{retrieve_1.context}} into a model call to answer from your documents.

Knowledge providers

modulexdb, Qdrant, Pinecone, Weaviate, and MongoDB Atlas.

Variables & references

How {{node_id.field}} references resolve against run state.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

What the node does

Picking the knowledge base

Configuration (`KnowledgeNodeConfig`)

Connection

Query

Retrieval settings

Filtering

Output

External-provider fields

The `embedding_config` object

Retry configuration

Inputs and outputs

Inputs

Outputs

Streaming

Credit impact

Managed native (modulexdb)

BYOK / external

Errors

Full example

Knowledge & RAG

LLM node

Knowledge providers

Variables & references

​What the node does

​Picking the knowledge base

​Configuration (KnowledgeNodeConfig)

​Connection

​Query

​Retrieval settings

​Filtering

​Output

​External-provider fields

​The embedding_config object

​Retry configuration

​Inputs and outputs

​Inputs

​Outputs

​Streaming

​Credit impact

Managed native (modulexdb)

BYOK / external

​Errors

​Full example

​Related

Knowledge & RAG

LLM node

Knowledge providers

Variables & references

What the node does

Picking the knowledge base

Configuration (`KnowledgeNodeConfig`)

Connection

Query

Retrieval settings

Filtering

Output

External-provider fields

The `embedding_config` object

Retry configuration

Inputs and outputs

Inputs

Outputs

Streaming

Credit impact

Errors

Full example

Related