Agent Workspaces

What is an agent workspace?

Every agent in Pinchy has its own workspace — a private folder on the Pinchy server where the agent keeps everything it needs to do its job: who it is, who it's working with, and any files attached to recent conversations.

Think of a workspace like a desk. Each agent gets exactly one. The agent can read what's on its own desk, but it cannot reach over to another agent's desk.

What's in a workspace?

A workspace typically contains:

The agent's identity — its name, role, and personality.
Context files — your personal context (for personal agents) or your organization's context (for shared agents). See Context Management.
Uploaded files — files you drop into the chat. These land in an uploads/ folder where the agent can read them on demand. See Upload Files in Chat. An agent with email Read access downloads attachments into this same uploads/ folder via the email_get_attachment tool — see Connect Email.
Agent deliverables — files the agent itself produces (notes, exports, drafts) live in a workbench/ folder. The agent can read and write here.
The agent's memory — what the agent has learned across conversations, kept in MEMORY.md (curated long-term knowledge) and dated logs under memory/. The agent writes these itself when it decides something is worth keeping or when you tell it to "remember this." See Instructions vs. Memory.

Who can write what

Each workspace separates content by who owns it. Knowing which zone owns what keeps the agent, the user, and Pinchy itself from stepping on each other:

| Zone | Who writes | What lives here | | ----------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Identity files (root) | Pinchy (system) | Who the agent is: SOUL.md, AGENTS.md, IDENTITY.md, USER.md | | MEMORY.md + memory/ | The agent, via pinchy_write | What the agent has learned: curated long-term memory and dated daily notes | | uploads/ | The user (chat upload button) and the agent (email_get_attachment) | Receipts, PDFs, images, documents the user attaches, plus attachments the agent downloaded from a connected mailbox | | workbench/ | The agent, via pinchy_write | Notes, drafts, exports, reports — anything the agent produces |

The agent can read everything in its workspace. It can write to its memory (MEMORY.md and memory/), to workbench/, and — for backward compatibility — to uploads/. It cannot write the identity files at the workspace root: SOUL.md, AGENTS.md, IDENTITY.md, and USER.md are system-managed. The file plugin enforces this file by file, so the agent can update what it remembers but never rewrite who it is. Writing memory requires the agent to have the pinchy_write capability (most agents, including the default Smithers, do).

Personal vs. shared agent workspaces

Workspaces work the same way for both kinds of agents — but the access model is fundamentally different, and that affects what should go inside.

Personal agents

A personal agent (like the Smithers each user gets automatically) belongs to exactly one user. Its workspace is effectively yours: your context, your uploaded files, your working notes. Other users cannot see this workspace because they cannot see the agent at all.

Shared agents

A shared agent is accessible to multiple people, and so is its workspace. The same files, the same context, the same notes — every user with access to the shared agent works with the same workspace.

This has practical consequences:

Files are visible to everyone with access. A document you upload to a shared agent can be read by anyone who chats with that agent. Pinchy reminds you of this in the upload UI.
Context is organizational. Shared agents receive the organization context, not personal user context, in their workspace. Your name and personal context are still passed to the agent at chat time, so it knows who is speaking — they just aren't written into the shared workspace.
No per-user partitioning. If a shared agent has files left over from a teammate's earlier conversation, those files are still there when you start a new chat with it.

When you need to upload sensitive content, prefer your personal agent.

What agents can and cannot do

Each agent's tools are constrained to its own workspace. File-reading tools (such as PDF or image analysis) only see files inside that agent's workspace. They cannot read files from another agent, from the host system, or from mounted data directories — unless Agent Permissions explicitly allow it.

This applies regardless of how a file ended up in the workspace: chat upload, plugin write, or context sync. Once it's in the workspace, the agent's built-in file tools can use it.

Persistence

Workspaces are stored in the pinchy-workspaces Docker volume. They survive container restarts and upgrades, so an agent doesn't lose its working state when you redeploy. Back up this volume the same way you back up your database — it contains the working memory of every agent.

If a workspace is ever lost, the agent starts with a fresh one rebuilt from your database (identity, personality, and context files). Files that were only attached to past conversations would not return.

Uploads and workbench files accumulate

Files in uploads/ and workbench/ stay there indefinitely — Pinchy does not currently age them out. For an active shared agent, both volumes can grow over time. Plan for it: include pinchy-workspaces in your backup rotation, monitor its size as part of your normal disk-usage checks, and prune obsolete files manually if the agent no longer needs them. A future release will add an admin-visible size view and retention controls.

Uploaded files are also reachable through an authenticated API (GET /api/agents/<agent-id>/uploads/<filename>) so the chat can render inline previews. Access is gated by the same agent-permission check as the chat itself — only members who can chat with the agent can fetch its uploaded files.