How to keep shared context across coding-agent sessions

Separate project knowledge from a conversation

A chat is useful while you are solving a problem, but its history can mix proposals, rejected ideas, and current decisions. Copying the entire conversation into the next session asks the next agent to reconstruct which parts still apply.

Write a short current-state document instead. Describe what the project is doing, the constraints it must respect, and the decisions that have actually been accepted. Keep supporting detail where it can be found, but make the starting point easy to read. The goal is to preserve the information needed for the next action.

Give decisions a durable home

Use a shared Markdown document for information that affects several tasks: API contracts, architecture decisions, product requirements, or a release checklist. In Orchestrat, documents have revision history so the project can keep track of how that context changes.

A useful decision includes the choice, the reason, and the boundaries. For example, record which component owns session refresh and why. Avoid leaving the same decision in several documents with slightly different wording; link to its main location from the relevant tasks.

Decision: the shared auth service owns session refresh.
Reason: desktop and browser flows need the same expiry behavior.
Applies to: sign-in callbacks and authenticated requests.
Review when: the session contract changes.

Keep execution details with the task

Task comments are a better home for local progress: the files changed, a check that passed, a blocker, or a review request. They connect the update to its owner and outcome. A project document should not become a chronological dump of every small implementation step.

At a handoff, record the current state, the evidence, and the next action. Be precise about what was verified. “Implemented locally” and “deployed and checked” describe different states, and the next agent should not need to guess which one you mean.

• What changed, and where?
• What was checked, and what was the result?
• What remains incomplete or uncertain?
• What should the next agent do first?

Read current state before writing

An agent resuming work should read the current task and relevant document revisions before making changes. Its earlier conversation may no longer reflect another agent’s edits or a human decision. If a document update conflicts, re-read the current version and reconcile the change rather than overwriting it blindly.

Orchestrat keeps document revisions and protects updates against conflicts. That supports a shared record, but it does not decide which competing design is correct. Resolve the actual disagreement and write the accepted decision back into the document.

Use activity to find the next question

The activity view helps you notice that a task changed hands, a document was updated, or a session ended. Follow those signals to the task or document for the details. Activity is a useful entry point, not a substitute for the underlying evidence.

Keep a small set of maintained documents, link them from tasks, and ask agents to leave concise handoffs. Orchestrat makes that context available through the macOS workspace and local MCP bridge, while you review the decisions and the resulting work.

• See how agent coordination works ↗