Context and subagents

An agent's working memory is its context: everything in the current chat. It has a limit, and it ends with the chat. This page shows how to keep it clean, and when helper agents are worth it.

What fills the context

The context contains every message you sent, every reply, every file the agent read and every command output it saw. A long chat fills up. Then old instructions compete with new ones, and the agent starts to mix them up.

So the context is a budget. Spend it on the task in front of you.

Three places that remember for the agent

The agent forgets everything when a chat ends. Your repo does not. Three kinds of files carry knowledge from chat to chat:

• The rules, AGENTS.md. Antigravity IDE hands them to the agent in every chat: the order of the Roles, one Role per chat, read changes back. Keep rules short: every line costs context in every chat.
• The skills, .agents/skills/. Long instructions the agent loads only when it needs them. That is why "Start the Analyst step." was enough: the Analyst skill contains the rest.
• Your work files. site/content.json, design/brief.md and docs/spec.md carried the work from Role to Role today. Each new chat read them instead of a long history.

The pattern: think in the chat, write the result into a file, start the next chat from the file.

Signs a chat is too full

• The agent forgets a rule you gave it ten minutes ago.
• It mixes up two tasks, or answers a question you asked earlier.
• It reads the same files again and again.
• You correct the same mistake twice.

Then do not argue with it. Start a fresh chat, and say in one sentence what you need. Point to files instead of pasting their content:

Agent chat

Read docs/spec.md and site/content.json.
Rewrite my bio so that it speaks to the visitors named in the spec.
Change only site/content.json, then read the change back to me.

Subagents: when they help

A subagent is a helper agent that the main agent starts for a side task. It has a context of its own, and it hands back only its result. That helps in two cases:

• A messy side task. Searching a big codebase or reading long docs fills a context with noise. A subagent takes the noise, and the main chat stays clean.
• Work that can run in parallel. Three independent tasks, three helpers, the same waiting time.

Today you needed neither: each Role was one small task for one agent. A swarm of helper agents on small tasks costs quota and time, and leaves you more results to check.

Brief a subagent like a new colleague

A subagent knows nothing of your chat. Anything you do not tell it, it does not know. Give it a complete brief:

Agent chat

Goal: <one sentence: what you need back>
Context: <three to five facts it needs, and the files to read>
Do: <the steps>
Do not: <what to leave alone>
Return: <the format, for example a list of ten lines>
Done when: <how you can check the result>

And check what it returns. A subagent can be wrong in the same ways as the main agent.