KV Store Write (KV_STORE_WRITE)

Saves a value under a name (key), so a later run or another module can read it again with KV Store Read. Use it as a step, or connect it to an Agent’s Tools port.

Category: Data Sources · Deployed: yes · Tool-capable: yes

Docker only. The saved values live on the agent server’s own disk. On Kubernetes the agent server refuses a pipeline that runs this module. With Docker, the values stay after the agent is stopped and started again. They are deleted when you delete the agent. Use it with agents that run on Docker.

Ports

Port Kind Purpose

Entry (in_entry)

Input

A JSON object from the previous module with the fields key and value (see below)

Result (out_result)

Output

A short JSON report of the write

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port so the agent can save values itself

Properties

Field Required Meaning

Collection Name (collectionName)

Yes

The group to save the value in. It is created on first use. Use the same name, with the same upper and lower case, in KV Store Read

Static Key (fallback) (key)

No

The key to save under when the previous module sends none. Used only as a step. Not used as a tool, because the agent always names the key

Static Value (fallback) (value)

No

The value to save when the previous module sends none. Saved as plain text. Used only as a step. Not used as a tool

If Collection Name is empty, the pipeline cannot be assigned to an agent, and the designer lists the missing field. If a saved pipeline is deployed anyway, the module is left out. If it was connected to an Agent’s Tools port, it is removed from that agent’s tools too.

What the previous module can send (step)

Input field Meaning

key

The key to save under. It must be text. Missing or blank → the Static Key

value

The value to save. Missing or null → the Static Value. It may be any JSON value, for example text, a number, a list or an object

The two fields are checked one by one. A missing key with no Static Key fails the step. So does a missing value with no Static Value. Plain text that is not a JSON object gives neither field, so only the static fallbacks are used. If you want to save a text from the previous module, put it into a field value, for example with a Template.

Result

The step sends: success (true), key, collectionName and overwritten (true if the key already had a value). The agent gets the same values as a tool.

As a tool

Connected to an Agent’s Tools port, the module becomes the function kv_write_<collection name>. The agent must send both key and value, as text. The Static Key and Static Value are never used here.

Use cases

  • Keep a vector index: Text Splitter → Iterator → Embedding → KV Store Write.

  • State between scheduled runs: save what was processed, so the next run can skip it.

  • Cache expensive results under a key built from the input.

  • As a tool: the agent remembers something the user told it.

Notes

  • A write always replaces the old value. There is no history. The result tells you with overwritten that a value was replaced. Keep the old value yourself if you need it.

  • A value that cannot be stored as it is is saved as its text form instead.

  • Several agents do not share values. Each agent has its own store, so another agent cannot read what this one saved.

  • The collection is a plain key and value list. You cannot search inside values.