Workspace

Your workspace is where your AI writes queries, runs scripts, caches results, and builds artifacts. It's a dedicated container in the cloud, provisioned for you alone.

Every MarcoPolo user gets their own workspace. Fully isolated from other users. Persistent across sessions.

Workspace layout

/workspace (home directory)
├── docs/               Context and syntax guides (read-only, managed by MarcoPolo)
│   ├── RULES.md            Global business context (editable by you and your AI)
│   └── {datasource}/       Per-datasource documentation
│       ├── RULES.md            Business rules and conventions (editable)
│       └── SYNTAX.md           Query syntax guide (auto-generated)
├── examples/           Verified working query examples (read-only)
├── queries/            Your query files, organized by datasource
│   ├── {datasource}/       e.g. queries/ATHENA/report.sql
│   └── DUCKDB/             Follow-up queries against cached results
├── databases/          Local database files (DuckDB, SQLite)
│   └── workspace.duckdb   Your cached query results and local tables
├── files/              Uploaded files (CSVs, spreadsheets, etc.)
├── downloads/          Files downloaded from storage datasources
└── schedules/          Scheduled/recurring task definitions

The docs/ and examples/ directories are managed by MarcoPolo. Everything else is yours. Your AI creates and organizes files as it works. You can browse it all in the web app.

What's inside

DuckDB (databases/workspace.duckdb): an analytical database for caching query results. Every time your AI queries a data source, results load into a named DuckDB table. Follow-up analysis queries DuckDB directly, so your AI can iterate, filter, and join across sources without hitting your production systems again.

Python and shell access for scripting, data transformation, visualization, and anything that goes beyond SQL.

Your files (files/): CSVs, spreadsheets, and other files you upload through the web app or ask your AI to fetch. Your AI can read, parse, and analyze these alongside connected data sources.

Context artifacts (docs/): RULES.md files with your business logic, SYNTAX.md files with query syntax guides, and example queries. See Context for details.

How your AI uses it

When you ask a data question, your AI works inside your workspace:

1. Reads docs/RULES.md and docs/{datasource}/SYNTAX.md
2. Writes a query file  →  queries/{datasource}/top_accounts.sql
3. MarcoPolo executes it →  results flow through the privileged layer
4. Results load into DuckDB  →  cached as a named table
5. AI analyzes and visualizes  →  charts, tables, summaries
6. Outputs saved to filesystem  →  available in web app and future sessions

Everything stays in the workspace. Your AI can reference previous queries, reuse scripts, and build on cached results in later conversations.

Persistence

The filesystem is permanent. The compute (CPU, memory) scales down when you're idle and spins back up on demand. This means:

• Files, scripts, cached data, and artifacts are always there
• No cold starts on context. Your AI picks up where it left off
• You don't pay for compute when you're not using it

Accessing your workspace

Through your AI. Your AI reads and writes files as part of normal conversations. This is the primary interface. Just ask questions and your AI handles the rest.

Through the web app. Browse files, view dashboards and charts, upload data, download exports. Useful for checking what your AI has generated or sharing artifacts with teammates.

Through any AI tool. Use Claude today, ChatGPT tomorrow, Cursor the day after. They all connect to the same workspace. The context you build carries across every tool.

A growing knowledge base

An empty workspace is a blank slate. Over time, it accumulates queries that worked, RULES.md files documenting your business logic, scripts for recurring transformations, cached results from previous analyses, and artifacts like dashboards and exports.

This is the compounding effect. Each conversation is more productive than the last because your AI doesn't start from scratch. It has your data's history, conventions, and previous work to build on.

Your first conversation starts from zero. Your tenth picks up mid-stride.