> ## 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.

# Using your agent's data stores

> Your coworker reads and changes its agent's variables, queries its database and works in its file stores, asking before it writes or sends a secret.

Your coworker works with the information its agent keeps: the prices in an agent variable group, the orders in a Database, the reports in a File Store.

## What it does

An agent can hold [data stores](https://docs.cogniagent.ai/features/data-stores.md). Every coworker in that agent can use them, with no setup:

* **Agent variables.** It reads a value in its instructions with `{{agent.Business.opening_hours}}`. It can list variables, read one and, after asking you, change one.
* **Database.** It lists the tables, runs a query and, after asking you, adds, changes or deletes rows.
* **File Stores.** Each store appears in its session as a folder at `/workspace/files/<key>/`. It opens, writes and saves files there like any folder.

It also uses the stores other agents share with its agent, once its agent uses them (they show under **Shared by other agents**). A store shared to read only is a read-only folder, and changing its variables or rows is refused. Secrets and Connection variables of another agent's group stay with that agent. It never finds a store its agent doesn't use.

## When you'd use it

* "What are our opening hours on a holiday?" answered from an agent variable, never out of date
* "How many open orders does Northwind have?" answered from the Database
* "Add this lead to the CRM" with a row written after your yes
* "Summarize `@Reports/2026/q3.csv`" with the file named by a mention

## Agent variables

Write `{{agent.<group>.<name>}}` in the coworker's instructions, or in the opening text of a session that a workflow, a schedule or a person starts in the app. The value is filled in when the session starts. Messages from outside, such as an email or a chat, are not filled in.

Its tools:

* `list_agent_variables` lists the variable groups of its agent and the variables in them.
* `get_agent_variable` reads one, by group and name.
* `set_agent_variable` changes one, and **asks first**. Allow it for a variable you trust it with under [permission rules](https://docs.cogniagent.ai/cowork/control/permission-rules.md).

It can't change a secret, and it never sees one. See below.

Saving instructions that name an `{{agent.<group>.<name>}}` the agent doesn't have is refused with a plain message. See [A name that doesn't exist](https://docs.cogniagent.ai/features/agent-variables.md#a-name-that-doesnt-exist).

## Secrets

A coworker uses a [secret](https://docs.cogniagent.ai/features/agent-variables.md#secrets) only through its `http_request` tool. It names the secret, and the platform puts the value in when the request is sent. The coworker never sees it.

This tool **always asks**. "Always allow" doesn't apply to it. The approval card names:

* each secret the request uses and where it goes
* that the coworker chose the address
* the hosts each secret is allowed on

A secret goes only to its allowed hosts, over `https`. Redirects aren't followed.

## Database

* `db_list_tables` lists the tables and columns of a database.
* `db_query` runs a read-only SQL query and returns the rows. Long results are cut, and the answer says so.
* `db_execute` runs a statement that changes data, and **asks first**.

If a change times out, the answer says it may have been applied, so your coworker checks before it tries again.

## File Stores

A coworker works in a store's folder during the session. What it saves comes back to the store as a new version, and you can see it in the session's **Files** panel and on the store's page. Mention a file with `@files/<key>/<path>`, for example `@files/orders/2026/q3.csv`; `@files/<key>` names the store's root. Type `@` and pick the file, and the box writes the mention. In text and instructions, write `files/<key>/<path>`. If you change a store's key, these are updated in the agent's items.

Until your workspace's files have moved into File Stores, your team's Workspace files are also at `files/`, with the stores inside as folders. After the move, `files/` holds only the agent's File Stores, and a mention whose first folder is not one of them names no file. The message box warns you: "files/Reports is not one of this agent's File Stores, so the coworker will not find it."

If something on the coworker's computer is in the way of a store's folder, it is moved to `files-before-sync/<name>` in the Task's files, and you see a line in the transcript. What cannot be moved stays only on the coworker's computer and is not synced. You are told about that too.

## Approvals

| Action | Asks first? |
| - | - |
| Read a variable, list tables, run a query, read a file | No |
| `set_agent_variable` | Yes |
| `db_execute` | Yes |
| `http_request` with a secret | Yes, every time |

**Always allow** on an approval saves a rule for `db_execute`, and a rule can cover `set_agent_variable`, so it stops asking. It never applies to `http_request` with a secret. The helpers a coworker starts for a big job can't use these tools. See [Approvals](https://docs.cogniagent.ai/cowork/control/approvals.md).

## Good to know

> [!NOTE]
>
> A store is private to its agent. A coworker can't use a store of another agent, even one in the same workspace.

> [!TIP]
>
> Describe each variable when you add it. The coworker reads the description when it decides which variable to use.

## Next steps

> [card] [Data stores](https://docs.cogniagent.ai/features/data-stores.md)
>
> The three kinds of store, and how the agent uses them.

> [card] [Approvals](https://docs.cogniagent.ai/cowork/control/approvals.md)
>
> What asks for your yes, and how to ask less.

> [card] [Code and files](https://docs.cogniagent.ai/cowork/capabilities/code-and-files.md)
>
> Opening spreadsheets and handing back finished files.

> [card] [Agent variables and secrets](https://docs.cogniagent.ai/features/agent-variables.md)
>
> How values and secrets are kept.


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