Vector Store Node

A Vector Store is a knowledge container that an AI agent can read from to answer questions about your own documents — PDFs, Markdown, FAQs, policies, manuals, anything textual. Drop the node, fill it with docs, wire it into an agent, and the agent's answers stay grounded in your material instead of guessing.

How it works — vectors & embeddings

A vector store doesn't keyword-search your documents — it searches by meaning. When you add a document, the store splits it into chunks and runs each chunk through an embedding model, which turns the text into a list of numbers (a "vector") that captures its meaning. Chunks about similar topics get similar vectors.

When you (or an agent) ask a question, the store embeds the question the same way and returns the chunks whose vectors are closest — the passages most related in meaning, even when they don't share the exact words. Those chunks are then handed to the AI as grounding for its answer.

Two consequences worth knowing up front:

• The documents and the query must be embedded by the same model — they share one "vector space," so mixing models produces meaningless matches. That's why switching a store to higher quality rebuilds its index.
• Circuitry keeps that model reachable wherever the workflow runs — in your browser, on your other devices, and on Circuitry's servers for webhooks and schedules. See Stores in webhooks and scheduled workflows.

Quick start

1. Drag a Store node from the side panel (the database-cylinder icon with three connected nodes, between 2Vec and Sheet).
2. Double-click (or double-tap) the node. The store's editor opens in a tab.
3. Click Add files (or drop files onto the editor) — PDFs, Markdown, text. The store chunks and indexes them automatically.
4. Use the chat area on the right to ask questions of just those docs. Answers cite which document each fact came from.
5. Back in the workflow, connect the Store node to an Agent, from above or below. The agent will use the store's content when answering.

Filling the store with documents

Inside the linked editor, the left column is your source-docs list. Drop in:

• PDF files — text is extracted and chunked.
• Markdown / Text — added as-is.
• Most plain-text formats (CSV, JSON, source code, YAML, etc.) work the same way.

Each doc is broken into chunks (roughly half a page each) and indexed. You'll see the chunk count appear when indexing finishes. The first time you add documents on a device, the search model downloads (about 25 MB, cached after that).

Asking the store directly

The middle column is a chat that knows only about the docs you've added. Use it to verify the store has the knowledge you expect before wiring it up to a real agent. Citation chips below each answer show which doc supplied the information.

This chat is independent of any agent in your workflow — it's a sanity-check tool.

Letting the Prompt Wizard write the agent for you

If you'd rather describe what you want in plain English, click the ✨ Prompt Wizard button on any Agent node. The wizard reads your workflow context — including every store wired to that agent plus your other resolvable stores — and turns intents like "use Product FAQ for product lookups, FCA Regulations for compliance" into a properly-structured agent prompt with the right {{store:…}} template variables already in place.

Add hints like "closed-book" / "only use the store" / "fall back to general knowledge" and the wizard adds matching strictness instructions to the prompt. The output is regular editable text — you can tweak it by hand afterwards.

Three ways to use a store in a workflow

Pick the mode that matches how deterministic you want the behavior to be. They compose: an agent can use one mode for one store and a different mode for another.

1. Attach it to an Agent — "give the agent this knowledge"

Place the Store above or below the Agent and drag a wire from it to the Agent. The store sits beside your flow, not in it: nothing has to pass through it, so it never holds the flow up, and one store can serve several agents. You don't need to name the store anywhere.

Each time the agent runs, the store is searched with the store node's own settings:

• Query — what to search with, worked out from what the agent is working on. Leave it empty and the agent's input is used: its question (or query or text) field when it has one, otherwise the input itself. Or write a path such as input.value.question, or a template such as {{input.value.question}}.
• Top-K — how many passages to use (5 unless you change it).

What the agent gets depends on its model:

• Models that can look things up themselves get a search_<store> tool, named after the store, and a short note that the store is there. They decide on each turn whether to search. With several stores attached, each is its own tool.
• Models that can't (Apple Intelligence on your device, and command-line agents) are given the store's top passages for the current input — each message, or each item in a loop — before they answer.

The agent's settings list the attached stores under Knowledge (name and Top-K). Tap one to open that store.

Give each store a clear description (in the editor's settings) — that's the single most important thing for the AI to pick the right tool at the right moment.

2. Place the passages in the prompt — "always look it up, right here"

Write a store reference in the agent's prompt (or system prompt) and it is replaced by the top passages when the agent runs:

Use these passages to answer:

{{store}}

Customer question: {{input.value.question}}

• {{store}} — the store(s) attached to this agent, searched with each store node's Query and Top-K.
• {{store|q=…|k=N}} — the same, with your own query and number of passages.
• {{store:Name|q=…|k=N}} — any store by name, attached or not — handy for a shared knowledge base used across many workflows.

q= takes a path (q=input.value.question), a template (q={{input.value.question}}, or q={{input}} for the whole input, searched by its question field), or plain words (q=refund policy). Leave it out to search with the agent's input. k defaults to 5.

When the prompt places a store's passages like this, the store is not searched a second time for the same run — use whichever form you prefer, not both.

3. As a pipeline step — "always inject the chunks"

Chat → Vector Store → Agent. The chat output becomes the store's query, the store outputs chunks, and the chunks flow into the agent as input data. Useful when you want retrieval to happen every turn AND you want a non-tool-capable model to receive the chunks as graph data (no tool calls required).

Insert a Code node in the middle if you want to rewrite the query before retrieval: Chat → Code (extract keywords) → Vector Store → Agent.

Chat → Agent (driver mode)

When a Chat node is wired straight into an Agent node, typing a message in the chat doesn't just pass text to the agent — the chat borrows the agent's prompt and model for the reply. The setup is: you author the agent's prompt (manually or via the Prompt Wizard) with whatever template variables and store references you want; the chat then becomes a low-friction UI for talking to that configured agent.

In this mode the chat send:

• Resolves {{input}} in the agent's prompt to the message you typed.
• Resolves any {{store}} / {{store:…}} references in the prompt (retrieval fires before the reply).
• Gives a model that can look things up search_<store> tools for the stores attached to the agent; a model that can't is given their top passages for your message instead.

You don't have to "Run" the workflow — sending a message triggers the agent automatically.

Closed-book vs open-book — controlling strictness

Independent of the integration mode above, you control whether the AI is constrained to your store's content or augmented by it:

You set strictness by phrasing in the agent's system prompt — for example:

• Closed-book: "Use ONLY the provided context. If the answer isn't there, say so."
• Hybrid: "Use the provided context first. For anything outside its scope, answer from your general knowledge."
• Open-book: "Use the provided context to enhance your answer where relevant."

The store editor's scoped chat has a Closed / Open toggle so you can verify both modes against the same docs before deploying.

Writing good store descriptions

The description (set in the store's settings) is the single most important thing for retrieval quality when stores are wired into agents. The AI reads it to decide whether and how to use the store. Vague descriptions like "FAQ docs" get ignored; specific ones like "UK Financial Conduct Authority regulations on consumer credit. Use for licensing and compliance questions." get used at the right moment.

Search quality

Every new store uses Circuitry's free search model. It's picked for you, and a store built with it works in the editor, on all your devices, and in webhook and scheduled workflows.

The store's settings let you choose a different search model:

• Higher quality (uses credits) — a cloud model that finds better matches in large or subtle collections. Indexing and each search use credits. Works everywhere the free model does.
• Apple on-device (Apple devices only) — offered on a Mac, iPhone or iPad. Private and needs no download, but a store built with it can be searched only on an Apple device.

Changing the model rebuilds the index — your documents stay.

Stores in webhooks and scheduled workflows

Nothing to set up: a workflow triggered by a webhook or a schedule searches its stores on Circuitry's servers with the same model that built them.

One exception: a store that uses Apple on-device search can't be searched on a server. In a webhook workflow its Store node shows a red badge before you deploy, and a run that uses it stops and says so. Switch the store to the free model in its settings to use it there.

Workflow-local vs global stores

By default, a store belongs to the workflow you created it in. Flip the Global toggle in the store's settings to make it available to any of your workflows — useful for shared knowledge bases.

When to use which:

• Workflow-local — domain-specific to one workflow. A shopping bot's product catalog, a single customer's documents, etc. Default. No sharing risk.
• Global — shared across all of your workflows. A company handbook, a regulation set you reference everywhere, customer history common to all your support flows. Promote to global from the editor's settings panel.

Template-variable lookups ({{store:name}}) resolve workflow-local stores first, then your globals — so a workflow-local store can shadow a global of the same name.

Picking a store from another workflow: the store-picker dropdown on the Vector Store node header lists workflow-local stores at the top and your globals below. Selecting a global from one workflow makes the new node a second view of the same store — same docs, same chunks, but with the new node's own retrieval settings (top-K, etc.).

Cross-device & cross-account: stores you create while signed in mirror to cloud storage automatically. Opening the same workflow on another machine pulls the store down without re-ingesting. (Stores created while signed out stay local until you sign in and edit them.)

Per-node tuning

Each Vector Store node has its own retrieval settings, accessible from the right config panel (the gear button on the node):

• Top-K — how many chunks to retrieve per query (default 5). Set 0 to bypass retrieval entirely.
• Max tokens injected — hard cap on total tokens in the retrieval output (default 4000). Low-rank chunks beyond this are dropped.
• Query — a template string used in place of the upstream input. E.g. {{input.value}}.
• Output format — with-titles (chunks separated by source doc), flat (chunks only), or json (structured).

Two nodes referencing the same store can have different retrieval settings — one returns 3 chunks for a summariser, another returns 10 for a detailed researcher.

Multiple Vector Store nodes per workflow

Drop as many as you like. By default, each new node creates a fresh empty store. If you want two nodes to share a store, point both at the same store ID (the right config panel shows the backing store ID).

Renaming the store on the canvas, in the editor, or via the node header all keep in sync — there's one source of truth.

Troubleshooting

• "The store has no relevant content for this question." — Either your docs don't cover this topic, or the indexed chunks are too granular. Try asking the editor's scoped chat the same question to confirm it's a content issue, not a wiring one.
• The AI ignores the store — Wire it directly into the agent (not via an intermediate node), or check the store's description. Vague descriptions don't get used.
• Tab name doesn't update after rename — known limitation; close and reopen the tab.
• A webhook or scheduled run says the store "works only on Apple devices" — the store uses Apple on-device search. Switch it to the free model in the store's settings; your documents stay and the index rebuilds.