Vault

The Vault is SynapseOrch's built-in file storage — a persistent, shared file system where you create and manage documents that agents can read and write across sessions.

Use it to store documents and structured data, pass context between agents, and inject reference material directly into agent system prompts — and make a folder of documents searchable as a knowledge base.

Vault files live in SynapseOrch's blob storage — on a self-hosted install, SYNAPSE_BLOB_DIR/default/vault/ (~/.synapse/var/blobs in an installed SynapseOrch, backend/var/blobs in a source checkout, /data/blobs in the single-container Docker image, /blobs in Docker Compose), or the S3 bucket when one is configured — and are managed from Vault in the rail.

Opening the Vault

Open Vault in the menu.

The Vault opens in a two-panel layout: a file tree on the left and an inline editor on the right.

Creating files and folders

New folder

  1. Click New folder (the folder+ icon) at the top of the file tree
  2. Enter a folder name and click Create (on Cloud, Create folder)

You can also hover over any existing folder in the tree and click its New file icon (file+) to create a file directly inside it.

New file

  1. Click New file (the file+ icon) at the top of the file tree
  2. Choose a file type:
    • Markdown (.md) — for prose, notes, and context documents. Includes a preview.
    • JSON (.json) — for structured data and configuration. Includes inline validation.
    • Text (.txt; on Cloud, Plain text) — for plain unformatted text.
    • On Cloud, also CSV (.csv).
  3. Enter a file name (the extension is appended automatically if omitted)
  4. Click Create (on Cloud, Create file) — the file opens immediately in the editor

Nested files

To create a file inside an existing folder, hover the folder row and click its New file icon on the right. The new file dialog shows the target location.

Editing files

Select any file in the tree to open it in the editor panel.

Markdown editor

.md files have two tabs: Write for the raw markdown and Preview for the rendered view.

JSON editor

.json files include live syntax validation. A red error bar appears at the bottom of the editor if the JSON is malformed, showing the exact parse error. The Save button stays active so you can continue editing before fixing the error.

Plain text editor

.txt files open in a minimal textarea with no formatting or validation.

Saving

Click Save to persist changes. The header shows Unsaved when the file has been modified, and a successful save says Saved.

Deleting files and folders

Hover any file or folder row in the tree to reveal the trash icon on the right. Click it and confirm the deletion prompt. Deleting a folder removes all its contents — this cannot be undone.

Knowledge bases in the Vault

A folder that is a knowledge base shows a Knowledge badge, and each file in it its status beside its name — Indexed, Partly indexed, Failed and so on, with the reason on hover. An open file says which base it is in, its status, and Open in Knowledge.

Anything saved into the folder is indexed by itself. To upload into a base from here, hover a folder inside it and use its upload button; on SynapseOrch Cloud, uploading into a base's folder also takes Word, Excel and PowerPoint files and files up to 100 MB, which the Vault alone does not.

A base's _web and _records folders are filled by Knowledge — fetched pages and records — so the Vault offers no upload or new file there. Deleting a file deletes its document; a fetched page comes back on its source's next crawl unless the source excludes it.

Referencing vault files with @[path]

A @[path] mention inlines a vault file's text wherever prompts are written:

Where
Agent system promptsThe agent carries the file every session
Workflow step promptsOne step gets the file
Chat messagesYou hand a file to the agent in passing
SchedulesA scheduled run carries it

The file is read from the vault as it is now, every time — never from a cached copy. An edit on the vault page takes effect on the next run, including on a replica that has been warm for days.

In system prompts

You are a support assistant.

Product documentation:
@[context/products.md]

Known issues:
@[context/known-issues.md]

The files are injected at the start of each session, so updating the vault file takes effect on the next one.

What happens to a file that is too big

A mention is capped at the tenant's vault_threshold, and a whole prompt has a total cap. Past either, the model is not handed a truncated file — it gets a reference line naming the file, its size, and the tool that can read it, so it can fetch the parts it needs with the vault tools.

A binary file is always a reference line. A path that is missing, unreadable, or not a vault path at all is left exactly as typed, so a stray @[...] in your prose stays prose.

A mentioned file is text, not a template

In a templated prompt, mentions are set aside while {state.x} and {{ global.key }} are rendered, and the file's text goes in only afterwards.

That ordering is a security boundary, not an implementation detail. A vault file containing {{ global.API_KEY }} reaches the model as those literal words rather than as the secret — so a file someone else wrote cannot read your variables. In the same way, a state value that happens to contain @[something] is treated as a value, not as a mention.

@-mention autocomplete

When writing a system prompt in the agent editor, type @ to open the vault file picker:

  • Start typing to filter by filename or path
  • Use ↑ / ↓ to navigate
  • Press Enter or Tab to insert the reference
  • Press Esc to dismiss

The inserted reference looks like @[folder/file.md].

Agent tools

Agents with the Vault tool enabled can read, write, and patch files at runtime:

ToolDescription
vault_readRead the content of a file
vault_writeWrite or overwrite a file
vault_patchApply a targeted text find-replace or JSON deep merge
vault_listList files (with optional path filter)
vault_deleteDelete a file

Example — agent accumulating research:

Save the findings to vault/research/2025-q1.md

Example — two agents collaborating:

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

File format reference

ExtensionIcon colorEditor features
.mdBlueEdit + rendered preview, monospace input
.jsonAmberLive JSON validation, parse error display
.txtGrayPlain textarea

What's stored

Vault files are not included in Import/Export bundles — bundles contain workflows, agents, MCP servers and custom tools only. Back up the vault separately by copying its folder:

# An installed SynapseOrch
cp -r ~/.synapse/var/blobs/default/vault ./vault-backup-$(date +%F)

# A source checkout
cp -r backend/var/blobs/default/vault ./vault-backup-$(date +%F)

# The single-container Docker image
docker cp synapse:/data/blobs/default/vault ./vault-backup-$(date +%F)

Configuration

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

SettingUI labelDefaultDescription
vault_enabledLarge response handlingtrueWhen on, a tool output longer than the threshold is saved to tool_outputs/ in the vault and the agent gets a reference to it. It does not turn the vault tools off
vault_thresholdCharacter threshold100000The size, in characters, at which a tool output is saved to the vault — and the most one @[path] mention inlines, with twice that allowed across a prompt

A mention past the inline limit is replaced by a line naming the file; see What happens to a file that is too big. Summarising a long conversation is a separate setting, Auto context compaction (on Cloud, Compact automatically).

On this page