> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data stores

> Give an agent variables, a small database and file folders of its own, and use them from its workflows, conversation flows and coworkers.

A data store is a place where an agent keeps its own information. Your business hours go in one, your customer records in another, the reports it writes in a third. Everything the agent runs reads and writes them directly, with no keys and no setup.

Add a store under an agent the same way you add a workflow or a coworker: open the agent, click **Add**, and pick one of three kinds.

| Kind | What it holds | Use it for |
| - | - | - |
| [Variable groups](https://docs.cogniagent.ai/features/agent-variables.md) | Named values in groups: text, numbers, dates, lists and secrets | Opening hours, prices, an API key, a feature switch |
| [Database](https://docs.cogniagent.ai/features/databases.md) | Tables of rows you can search and change | Orders, leads, tickets, anything with many records |
| [File Store](https://docs.cogniagent.ai/features/file-stores.md) | A folder tree of files, with versions and a Trash | Reports, uploads, documents the agent works on |

An agent can hold any number of each, named as you like. Each shows in the sidebar under the agent, and on the agent's home with its other parts.

## Who can use a store

A store belongs to its agent. The agent's own workflows, conversation flows and coworkers use it with no setup. Another agent uses it only when you share it with other agents, and your own app or an AI assistant only with one of the agent's endpoint keys.

Under the store's name, **Shared with** says who may use it now, or **Not shared**. Click **Manage access** to change it: choose **Off**, **Read** or **Read & write**, then who: **Other agents**, **Apps (API)** or **AI assistants (MCP)**. **Other agents** needs no key: "Any agent in this workspace can use it." A store in a project is shared with that project's agents. The footer of the store's page says it in words, for example "It belongs to Front desk. Other agents in this workspace can read it too." A store in **Unsorted** can't be shared. See [Agent data API](https://docs.cogniagent.ai/api/stores.md) for apps and AI assistants.

> [!NOTE]
>
> A store never reaches another agent by accident. Only a store you share with other agents shows in their pickers, and only at the level you chose. Move an item to another agent and the move window asks whether to bring along the stores of its agent it uses. If you leave them behind, the item is marked as needing attention and lists what it can no longer reach.

## Use a store another agent shares

When another agent shares a store with other agents, your agent's pickers list it after its own, under **Shared by other agents**, named with the agent that shares it: "Pricing (Front desk)". A store shared to read only carries a **Read** badge, and a step that changes data offers only stores shared at **Read & write**. Pick it, and the whole agent can use it from then on: its other items find it too.

To use one before any step needs it, click **Add** on the agent and pick **Use a store another agent shares**. The window lists what other agents share with this one, grouped by agent, each with **Read** or **Read & write**. Click **Use it**. One the agent already uses says **In use**. The window stays open so you can use more than one; click **Close** when you are done. If nothing is shared yet, the window says where a store is shared from.

A store your agent uses shows once in the sidebar under the agent and on its home, under **Shared by other agents**: "Pricing · from Front desk". It opens that store's page with your own rights on the other agent, if you can open it at all: using a store never lets you change it. Its menu has **Stop using it**, refused while an item of your agent still uses it, with the items named. An item you move to another agent keeps using it there when that agent may use it too; the move window says so first, for example "Pricing · from Front desk: Sales will use it too."

| | Read | Read & write |
| - | - | - |
| **Variable group** | Read its variables with `{{agent.…}}` and the tools that read them | Also change them, with [Update Agent Variable](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md), `set_agent_variable` and the coworker tools |
| **Database** | Find rows and run read-only queries | Also add, change and delete rows |
| **File Store** | List, read and search its files. A coworker's folder for it is read-only | Also write, move and delete files |

What other agents never get:

* **Secrets.** A secret of a shared variable group shows greyed in the pickers, with why, and a step that names it is refused when you save it, and when it runs.
* **Connection variables.** They hold the sharing agent's accounts and are used only by its own items. They show greyed too, and are refused the same way.
* **Moving files across.** A File Store step moves or copies files only between stores of its own agent.

A store shared with your agent always reaches the sharing agent's **Production**: its values, rows and files, whatever [environment](https://docs.cogniagent.ai/features/environments.md) either agent runs in. While your agent runs in another environment, it can read the store but not change it: "Demo can read Leads from Sales but not change it. Only Production can." `{{agent.environment}}` stays your agent's own. Your agent's **Start** counts the values it reads that are empty in the sharing agent's Production.

Calls from other agents show in the store's **Activity**, named "Front desk · Lead intake", as far as you can open them. So does each copy of its contents into a copy of an agent that uses it: **Copied into a shared agent**.

### When a store stops being shared

The agent that shares a store may close **Other agents**, set it to **Off** or **Read**, or delete it. Before it closes or lowers the store while other agents use it, it is asked to confirm, with the items that use it named, for example "Stop sharing with other agents? Lead intake and Quote helper of Front desk use it." Your agent is never changed by it. Instead it shows **Needs attention**, with **Open Lead intake** and, when you can, **Open Pricing**:

* "Lead intake uses Pricing from Front desk, which no longer shares it with other agents."
* "Lead intake uses Pricing from Front desk, which other agents can only read now." Only the places that change it.
* "Lead intake uses Pricing from Front desk, which is in another project now."
* "Lead intake uses Pricing from Front desk, which was deleted."

Those places are refused when they run until the store is shared again, or you point them at another store. A store that other agents use can't be deleted: **Delete** opens a window that lists what uses it, named as far as you can open it, and offers only **Close**.

Deleting the agent that shares a store lists, before anything goes, the other agents' items that use its stores. Deleted with everything inside, its store goes, and your agent's uses read as deleted. Deleted keeping its items, its store moves to **Unsorted**, which shares nothing, so your agent's uses read as not shared any more.

## Where each kind is used

| | Variable group | Database | File Store |
| - | - | - | - |
| **Workflow** | `{{agent.…}}` in any field, and the [Update Agent Variable](https://docs.cogniagent.ai/nodes/actions/update-agent-variable.md) step | The [Database](https://docs.cogniagent.ai/nodes/actions/database.md) step | The [File Store](https://docs.cogniagent.ai/nodes/actions/workspace-files.md) step, Read File, the file trigger and Execute Code |
| **Conversation flow** | `{{agent.…}}` in instructions, messages and starting values | **Data stores** on an actor, read or read & write | Not available |
| **Coworker** | `{{agent.…}}` in its instructions, plus tools to read and change variables | Tools to list tables, query and change rows | Each store appears as a folder in its session |

See [Data stores for conversation flows](https://docs.cogniagent.ai/conversation-flows/build/capabilities.md#data-stores) and [Data stores for coworkers](https://docs.cogniagent.ai/cowork/capabilities/data-stores.md).

## In each environment

When an agent has more than one [environment](https://docs.cogniagent.ai/features/environments.md), such as Production and Demo, each store says what it holds in each:

| Kind | In each environment |
| - | - |
| **Variable group** | Always its own value for each variable. The variables are the same everywhere |
| **Database** | Its own rows when it is **Separate in each environment**, the default for a new one. One set of rows when it is **The same in every environment**. Its tables are the same everywhere either way |
| **File Store** | Its own files when it is **Separate in each environment**, the default for a new one. One set of files when it is **The same in every environment** |

Work in Demo reads and writes Demo's values, rows and files, and never Production's. A store's page has a pill for each environment, opens on Production and marks the one the agent runs in. See [Database](https://docs.cogniagent.ai/features/databases.md#in-each-environment) and [File Stores](https://docs.cogniagent.ai/features/file-stores.md#in-each-environment).

## Store key and name

Every store has a **name** that people read, such as "Business hours", and a **key** that text uses, such as `Business_hours`. The key is made from the name when you add the store. You can change the key from the store's page, and items that use the old key are rewritten to the new one.

## What the store page shows

* **Used by** lists the items that read or write the store, so you know what a change touches, also those of other agents. Items you can't open show as a count.
* **Shared with** and **Manage access** say and change who may use the store. The drawer's **Access** tab sets the level and the ways in, with the web addresses under **For developers**, and its **Activity** tab lists the calls made.
* **Move** and **Delete** work like they do for other items. Deleting an agent deletes its stores, after a list of what will go.

## Sharing an agent with stores

A copy of a shared agent carries its stores. A variable group comes with its values, and a database with its rows and a file store with its files when you include them, each from the environment you [share from](https://docs.cogniagent.ai/features/sharing-agents.md#share-from-an-environment). Secrets never travel, and every store of a copy is shared with no one. A store another agent shares with yours travels as the copy's own store: its structure, and its contents only when you may share that store and include them. See [Stores from other agents](https://docs.cogniagent.ai/features/sharing-agents.md#stores-from-other-agents).

## Next steps

> [card] [Agent variables and secrets](https://docs.cogniagent.ai/features/agent-variables.md)
>
> Named values your agent reads everywhere, and keys it can use but never show.

> [card] [Database](https://docs.cogniagent.ai/features/databases.md)
>
> Tables of rows with a designer, a SQL console and CSV import.

> [card] [File Stores](https://docs.cogniagent.ai/features/file-stores.md)
>
> A folder tree per store, with versions and a Trash.

> [card] [Agent data API](https://docs.cogniagent.ai/api/stores.md)
>
> Let other agents, your app or an AI assistant read or change a store.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.