# Workspace layout

> The folders and files an Eggent workspace is made of — projects, the orchestrator, chats, attachments, settings, schedules — and which of them you may edit by hand.

Source: https://eggent.ai/docs/workspace-layout/

All of a workspace's state is ordinary files in the `data/` folder. In the cloud it lives on the server; on your own server, next to the installation. The agent works inside `data/projects/`.

## Overview {#overview}

```text
data/
├── projects/            # the orchestrator's files and every project
├── chats/               # chat history
├── chat-files/          # chat attachments, one folder per chat
├── settings/            # settings, the API token, the sign-in secret
├── board/               # the task board: one file per card
├── versions/            # versions of files: what each held before every change
├── memory/              # memory's internal data
├── learning/            # internal: counters and a journal of what the agent learned
├── models/whisper/      # the speech recognition model
└── pi-agent/            # the runtime: keys, models, packages
```

## The orchestrator and projects {#projects}

```text
data/projects/
├── context.md           # the orchestrator's context
├── memory.md            # the orchestrator's memory
├── learned.md           # short notes the agent keeps about you and the work
├── skills/              # the orchestrator's skills, including ones the agent wrote
│   └── .archive/        # learned skills nobody has used for a long time
├── .mcp.json            # the orchestrator's MCP servers
├── Messages/            # in a company: files from each thread, one folder per person
├── .shared/             # in a company: company folders given to you (not in the history)
│
└── <project-id>/
    ├── project.json     # the project's name and description
    ├── context.md       # the project's context
    ├── memory.md        # the project's memory
    ├── model.json       # the project's own model (if set)
    ├── skills/          # the project's skills
    ├── .mcp.json        # the project's MCP servers
    ├── .pi/             # internal: schedules and state
    ├── generated-images/# images the agent drew
    └── …                # the project's files
```

A project's folder is its working folder: the agent reads and writes files here, and the **Files** panel shows the same folder.

## What you may edit by hand {#editable}

| File | OK? | Best done via |
| --- | --- | --- |
| `context.md`, `memory.md` | Yes | **Settings → Context / Memory**, or ask the agent |
| `learned.md` | Yes | **Settings → Memory → What the agent has learned**: one note per line, starting with `- ` |
| `skills/<name>/SKILL.md` | Yes | Any editor, the agent or the **Files** panel |
| `.mcp.json` | Yes | **Settings → MCP** |
| `model.json` | Yes | **Settings → Models**, scope set to the project |
| `.pi/subagent-schedules/*` | **No** | Only through the agent: "move the task…". Editing by hand breaks a running schedule |
| `data/settings/*`, `data/pi-agent/auth.json` | No | Through the settings interface |

## Where secrets live {#secrets}

- Model provider keys — `data/pi-agent/auth.json`.
- The external API token and the sign-in secret — `data/settings/`.
- MCP server tokens — in the project's or orchestrator's `.mcp.json`.
- The Telegram bot token — `data/settings/telegram-integration.json`.

Credentials that were pasted into a chat or printed by a tool are masked in the stored chats under `data/chats/`; `data/secrets-sweep.json` records that the one-time cleanup of older chats has run. The runtime's own session files under `data/pi-sessions/` are the agent's memory and are not changed.

When backing up or moving a workspace, treat the whole `data/` folder as a secret.