Vault Tools for Agents

The vault is a persistent, shared file system accessible to agents across sessions. Think of it as the agent's long-term working directory — a place to save results, build up knowledge bases, and share files between agents and runs.

Vault files live in SynapseOrch's blob store, under <tenant>/vault/. On a self-hosted install that is $SYNAPSE_BLOB_DIR/default/vault/: ~/.synapse/var/blobs/default/vault/ in an installed SynapseOrch, backend/var/blobs/default/vault/ in a source checkout, /data/blobs/default/vault/ in the single-container Docker image and /blobs/default/vault/ in Docker Compose. With the S3_* variables set, the vault is in object storage instead. See Environment Variables.

Tools

Tool	Arguments	Description
`vault_create`	`content`, optional `filename`, `format`	Create a new file. Fails if the file already exists. Without a `filename`, a timestamped name is generated, with the extension from `format` (`json`, `text`, `csv`, `python`, `markdown`; default `json`).
`vault_read`	`path`	Read a file as text (up to 10 MB)
`vault_write`	`path`, `content`	Write a file, creating it or overwriting it
`vault_patch`	`path`, then `find` + `replace`, or `merge`	Edit a file in place — see below
`vault_list`	optional `directory`, `extension`	List files, recursively, optionally under a folder or with one extension (e.g. `.json`)
`vault_delete`	`path`	Delete a file

Paths are relative to the vault root — research/q1.md, not vault/research/q1.md, which would create a folder called vault. The absolute paths the tools return are accepted too. A path that would leave the vault is refused. Intermediate folders are created automatically, and JSON written to a .json file is reformatted with indentation.

Agents also get read-only file tools by default, such as read_file, list_directory, search_files and grep, which can read the vault as well. And execute_python sees the vault read-only at /data — see Python Sandbox.

Reads can be up to an hour stale

Results of read-only tools are cached for an hour, keyed on the tool and its arguments — and that includes vault_read and vault_list. An agent that reads a file it changed within the hour can get the earlier content. For an agent that keeps adding to a file, use vault_patch, which always reads the file afresh, rather than reading, editing and writing it back.

Vault in system prompts

Reference vault files directly in any agent's system prompt:

You are a knowledge assistant.

Company context:
@[context/company.md]
@[context/products.md]
@[context/policies.md]

The files are read each time the agent runs, so an edit takes effect on the next message. The same @[path] mentions work in chat messages, workflow step prompts and scheduled agent prompts. A file larger than the inline limit is replaced by a line naming it — see Vault → What happens to a file that is too big.

Vault in the UI

The vault is under Vault in the menu. You can:

Browse the file tree
Create, edit, and delete .md, .json, and .txt files and folders

On Cloud, Upload files at the top of the file tree brings files in from your computer. Self-hosted, upload works only into a knowledge base's folder (its Upload files to … button); elsewhere, create the file and paste its content, or have an agent write it.

Examples

Saving research results

Save the research findings to research/2024-q1-analysis.md

Building a knowledge base

The agent accumulates facts over time:

Add this new issue to the end of kb/known-issues.md.

Adding with vault_patch — find the last line, replace it with itself plus the new entry — avoids the stale-read problem above.

To have agents search such a folder, with passages and citations, rather than list and read its files, make it a knowledge base.

Agent A writes reports/draft.md. Agent B reads it, reviews it, and writes feedback to reports/feedback.md. Agent A reads the feedback and revises.

`vault_patch` details

Pass find and replace for a text edit, or merge for a JSON merge.

Text find-replace — replaces the first occurrence of find; fails if it isn't found:

{
  "tool": "vault_patch",
  "arguments": {
    "path": "notes/todo.md",
    "find": "- [ ] Task 1",
    "replace": "- [x] Task 1"
  }
}

JSON merge — merge is a JSON string. Objects are deep-merged; if the file holds an array and merge is an array, the items are appended:

{
  "tool": "vault_patch",
  "arguments": {
    "path": "data/config.json",
    "merge": "{\"api_version\": \"v2\", \"debug\": false}"
  }
}

Configuration

Both settings are in Settings → General under Large response handling (on Cloud, the threshold is Large response threshold under Context).

Setting	UI label	Default	Description
`vault_enabled`	Large response handling	`true`	When on, a tool output longer than the threshold is saved to a file under `tool_outputs/` and the agent gets a reference to it. It does not turn the vault tools off.
`vault_threshold`	Character threshold	`100000`	The size, in characters, at which a tool output is saved to the vault. It is also the most an `@[path]` mention inlines, with twice that allowed across one prompt.

Summarising a long conversation is a separate setting, Auto context compaction (on Cloud, Compact automatically), also in Settings → General.

Vault Tools for Agents

On this page