Docs/Workspace Files

Workspace Files

Persistent configuration files that shape your agent's personality, behavior, and memory.

What Are Workspace Files?

Workspace files are markdown documents that live in your agent's workspace directory. Unlike system prompts that reset every session, workspace files persist across conversations — giving your agent consistent personality, rules, and context.

Core Files

🤖 AGENTS.md

Agent behavior rules and workspace conventions. Think of it as the operating manual.

Defines: task management rules, memory protocols, safety boundaries, tool usage patterns.

💜 SOUL.md

Agent personality and identity. Who your agent is.

Defines: tone, communication style, values, opinions, quirks.

👤 USER.md

Information about you — preferences, timezone, context.

Defines: name, timezone, location, working style, communication preferences.

🔧 TOOLS.md

Environment-specific notes — API endpoints, device names, project paths.

Defines: camera names, SSH hosts, voice preferences, project details.

🧠 MEMORY.md

Long-term curated memory — decisions, lessons learned, important context.

Defines: project history, key decisions, learned preferences, important dates.

Editing in Pinchr

Open the Workspace page from the sidebar to view and edit all your workspace files:

  • File tree on the left — click any file to open it
  • Editor on the right — markdown with monospace font
  • Live preview toggle — switch between raw and rendered markdown
  • Cmd+S to save — unsaved changes show a dot indicator

File Templates

When you create a new workspace, Pinchr generates starter templates for each file with helpful comments explaining what to include. You can customize them immediately or let them evolve naturally as you work with your agent.

Best Practices

  • Start small — even a 3-line SOUL.md makes a noticeable difference
  • Be specific — "be concise" is better than "be good"
  • Update regularly — workspace files should evolve as your needs change
  • Keep MEMORY.md curated — distill daily logs into key insights
  • Don't put secrets in workspace files — use environment variables for API keys

💡 Pro Tip

The more context you give your agent through workspace files, the less you need to repeat yourself in every conversation. Think of workspace files as the "long-term memory" that makes your agent truly yours.