Context

MarcoPolo executes queries inside your workspace and returns only summaries to the AI. A 4MB query result becomes a 1KB summary in the conversation. This keeps the context window focused on reasoning, not raw data.

But summaries alone aren't enough. Schemas don't tell your AI that "active users" means users with a session_start event in the last 30 days, or that the revenue column in invoices_eu is in EUR while orders.revenue is in USD. And schema alone won't teach it the right query syntax for Salesforce SOQL vs. PostgreSQL vs. ClickHouse.

The workspace stores three kinds of context that your AI reads before writing any query.

Where context lives

The shape is the same for every connection. Once your AI knows it, switching from Snowflake to Postgres to Salesforce doesn't require relearning where things live.

RULES.md: your business logic

RULES.md files document the knowledge that makes queries correct. Your AI reads them before every query so it arrives with your definitions, conventions, and gotchas already loaded.

A good RULES.md turns your AI from a generic SQL generator into an analyst who understands your data. This is the single highest-leverage thing you can do in MarcoPolo.

Workspace-wide RULES.md

Lives at /workspace/RULES.md. Company-wide context that applies across all connections:

• Descriptions of each connection and what lives where
• Universal metric definitions (DAU, MAU, MRR, churn, LTV)
• Naming conventions and terminology
• Cross-connection relationships and canonical sources of truth
• Anything a new analyst would need on their first day

Per-connection RULES.md

Lives at connections/<name>/RULES.md. Context specific to a single connection:

• Which tables to use (and which to avoid)
• How metrics are calculated in this system
• Known quirks: NULLs, data gaps, encoding issues
• Join keys between tables
• Query patterns that work well (and ones that are slow)

SYNTAX.md: how to query each system

Each connection ships with a connections/<name>/SYNTAX.md written by MarcoPolo. These are query syntax guides tailored to the specific system the connection points at.

For a Salesforce connection, SYNTAX.md covers SOQL queries, REST API passthrough, and metadata operations. For PostgreSQL, it covers SQL dialect specifics. For ClickHouse, it explains FINAL, PREWHERE, and materialized views. Your AI reads the relevant SYNTAX.md before writing a query so it uses the right syntax for the right system.

You don't write these. They're regenerated by the platform.

Metadata snapshots

connection describe <name> --json writes structured snapshots into connections/<name>/metadata/. These are the durable, in-workspace reference for query authoring — stable across sessions, cheaper than re-hitting the live system, and reproducible (the snapshot is what existed at the time of describe, regardless of what changed later upstream).

Your AI re-runs describe only when the snapshot is missing or stale, or when a query fails because the structure no longer matches. Re-running on every query wastes connection resources and pollutes git history.

Saved queries

Existing query files in connections/<name>/queries/ encode patterns that already work in this workspace — connection-specific syntax, naming, filters, and joins. Your AI prefers adapting an existing query file to writing one from scratch.

Over time the queries/ directory becomes a library: the workflow that pulled last quarter's revenue, the diagnostic that flagged the bad partition, the join that finally got the customer match right. They persist, get committed, and stay reusable.

How to edit RULES.md

The platform owns SYNTAX.md and metadata snapshots. RULES.md is yours to write and maintain.

In the web app

Workspace-wide rules: From the MarcoPolo home screen, click the RULES.md button.

Per-connection rules: Open any connection's detail view and click the RULES.md tab.

Through your AI

RULES.md files live in your workspace, so your AI can write and update them directly. After a session where your AI corrected a mistake or discovered a quirk:

You: "Update RULES.md with anything you learned that would have
      helped you answer more accurately."

You: "Add what you discovered about the join between Salesforce
      accounts and our Postgres companies table to the RULES.md."

The AI writes only what it can support from the session: corrections it made, schema details it confirmed, or logic it had to work through.

What to write in RULES.md

Start with things that have caused wrong results. Here are the highest-value patterns:

Metric definitions

## Key Metrics
- **MAU**: Users with at least one `session_start` event in the last 30 calendar days.
  Do NOT use `users.last_active_at`. It is not reliably updated.
- **MRR**: Sum of `subscriptions.monthly_amount` where `status = 'active'`
  and `plan_type != 'trial'`. Exclude one-time charges.

Canonical tables

## Where to find things
- User identity: `core.users`. Do not use `legacy.user_profiles`.
- Revenue: `billing.subscriptions` for recurring, `billing.charges` for one-time.
- Events: `analytics.events` (partitioned by `event_date`).

Gotchas

## Known Issues
- `orders.amount` is in cents, not dollars. Divide by 100.
- The `region` column is NULL for all records before 2022-01-01.
- `users_v2` and `users` are separate tables with different data.
  Always use `users_v2` for anything after the 2023 migration.

Cross-connection joins

## Joining Across Connections
- Salesforce → Postgres: `salesforce.accounts.external_id = postgres.companies.crm_id`
- HubSpot → Postgres: `hubspot.contacts.email = postgres.users.email`

Why this matters

Every data tool requires human judgment to use correctly. A SQL client doesn't stop you from querying a deprecated table. A BI tool doesn't know that two columns with the same name mean different things.

These context artifacts transfer that judgment to your AI. RULES.md encodes your business logic. SYNTAX.md teaches the right query language. Saved queries and metadata snapshots show proven patterns. Together, they turn a generic AI into one that understands your data.

The 15 minutes you spend writing RULES.md will save hours of corrections.