Category guide
How to share context across AI coding agents—without sharing every conversation
Teams working across chats, coding agents, and Git keep losing the plot between sessions. The useful move is smaller than it sounds: keep a project-owned record of what is true now, and leave the raw archive where it belongs.
Direct answer
Share a small, project-owned current state—not a merge of raw transcripts. The next agent needs direction, accepted decisions, facts, constraints, open questions, the live handoff, and pointers to evidence. Moving more text between tools is not the same as sharing context.
Definition
What shared context actually is
Shared context is the current understanding of a project that a new person or agent can start from without reconstructing the history. It is not every file in the repo, every message in a thread, or a larger prompt. It is the short, living account of what the work is, what has been decided, what must not be violated, and what is still unknown.
Transport and retrieval are not enough on their own. A protocol can move a payload. A search step can fetch more of the past. Neither tells the next session which claims are still current, who had authority to make them, where two sources contradict each other, what evidence would settle a challenge, or what must stay private. Without those five conditions, “more context” is often just more noise.
Durable state
What belongs in the record that survives a session
Keep the shared file small enough to reread. If a line would not change what the next agent should do, it probably belongs in the local archive instead.
Direction
The outcome the team is aiming at right now, in a sentence or two. If this changes, later work should change with it.
Decisions
Accepted choices and the reason they bind the work. A confident suggestion is not a decision until someone with authority accepts it.
Facts
Settled observations that later sessions should not have to rediscover: what shipped, what failed, what a measurement actually showed.
Constraints
The hard edges: legal, product, technical, or time limits that make an otherwise clever change wrong.
Open questions
Unresolved disagreements and unknowns, with an owner when one exists. Leaving these implicit is how agents invent a false consensus.
Current work
The live handoff: what is in progress, what is blocked, where the last known-good point is, and what the next session should do first.
Evidence
Pointers to the session, commit, issue, or note that supports each durable claim. Shared state should be checkable, not merely memorable.
Privacy boundary
What should remain local
The shared record should travel light. Private source material can stay on the machine or account that produced it, with only the accepted claim and a source reference crossing the boundary.
This is not only a confidentiality issue. Pasting the full discussion into a shared file makes staleness harder to see. The next agent cannot tell the discarded option from the one the team kept.
- Raw chat logs and agent transcripts
- Credentials, tokens, and local paths
- Customer data and production dumps
- Unreviewed drafts and speculative asides
- Personal preferences for one tool
- Auto-saved memories nobody accepted
Boundaries
Each common source solves only part of the problem
Transcripts, instruction files, Git history, and generic memory are all useful. None of them is a current project story by itself.
| Source | Holds well | Cannot do alone |
|---|---|---|
| Transcripts | How a single session unfolded, including false starts. | Which claims are still true, which were rejected, and what must stay private. |
| Repo instruction files | Standing conventions, style, and durable project rules. | What changed this week, who accepted it, and what is still open. |
| Git history | What actually landed in the codebase, and when. | Why a path was deferred, what was decided outside the repo, and current questions. |
| Generic memory | Recalled snippets from earlier sessions. | Freshness, authority, and a way to stop a stale or private claim from spreading. |
| Shared current state | What is true now, who accepted it, and where to check the evidence. | Implementation skill. A clear brief still cannot write the hard parts for you. |
The missing layer
Freshness, authority, contradiction, provenance, privacy
A shared-context system has to do more than store text. It has to keep the current story distinguishable from the old one, keep suggestions from becoming decisions, surface conflicts instead of smoothing them, point every durable claim at evidence, and refuse to spread material that should stay local.
Skip any one of those and the next agent inherits a plausible story that is slightly wrong. Slightly wrong context is often worse than a thin brief, because the session spends its effort executing a stale premise.
A concrete example
Cedar Receipts, one week later
Lena, who owns a small invoicing tool called Cedar Receipts, decides in a planning chat that version one will support USD only. Multi-currency is deferred. She also sets a constraint: tax line items stay on the invoice, not in a side PDF. Both points live in that chat, plus a year-old design note that still mentions currency conversion.
A week later Omar asks a coding agent to finish the export job. The agent can see the repository, the old design note, and a pasted excerpt from an earlier brainstorm. It does not see that multi-currency was explicitly deferred. It starts threading conversion into the export path.
The useful shared state would have been short:
- Direction. Ship a USD-only export that accountants can trust.
- Decision. Multi-currency is deferred past v1. Accepted by Lena.
- Constraint. Tax lines remain on the invoice itself.
- Open question. Whether EU VAT fields belong in the next milestone.
- Current work. PDF and CSV export; last known-good is the draft renderer on the feature branch.
- Evidence. Planning note from 6 August; issue #42; no transcript attached.
That brief would not have written the export for Omar. It would have stopped the agent from solving last month’s problem. The rest is still implementation: naming, wiring, and tests.
Continuity workflow
Six steps that keep the story current
You can do this in an ordinary project file. The discipline matters more than the container.
- 01
Separate state from debris
When a session ends, extract only the claims that should survive. Leave the transcript where it is. The archive is not the brief.
- 02
Write what is true now
Update direction, decisions, facts, constraints, and open questions. Replace stale lines. Do not append a diary that later agents have to reinterpret.
- 03
Mark authority
Record who accepted a decision, or mark it as a proposal. An agent should not be able to promote its own suggestion into project truth by sounding sure.
- 04
Leave contradictions visible
If two sources disagree, write the conflict and who owns it. Averaging them into one smooth paragraph creates a consensus nobody actually made.
- 05
Point to evidence
Attach the commit, issue, note, or session that supports each durable claim. Share the pointer, not a paste of the private source.
- 06
Hand off a brief
The next person or agent gets the current state, the live constraints, the open questions, and the next action. Not a merged chat log.
Before you hand off
A compact handoff checklist
If the next agent cannot answer these from the brief alone, keep editing. Do not add the transcript to fill the gaps.
- One- or two-sentence direction
- Decisions that bind this task, with who accepted them
- Constraints that would make a change wrong
- Settled facts the next session should not rediscover
- Open questions, disagreements, and owners
- Current work, blockers, and last known-good point
- Evidence the next agent can inspect if a claim is challenged
- An explicit note about what was not shared
Limits
What this method will not do
Good context cannot compensate for weak implementation skill. A current brief can keep an agent on the right problem. It cannot choose the right pattern, wire a feature correctly, or notice a subtle regression. Treat context as orientation, not as a substitute for review.
A shared file also goes stale the moment nobody updates it. Instruction files encode standing rules, not this week’s work. Git history is complete and still not a narrative. Memory features will happily retain a claim that was never accepted. And a clean brief can still be wrong if the team recorded the wrong decision.
This page is a working method, not a claim that any particular product already performs it for you.
Short answers
Questions this usually comes down to
What is shared context, if it is not the transcript?
It is the current, project-owned understanding a new collaborator needs in order to start: direction, accepted decisions, facts, constraints, open questions, and the live handoff. The transcript is how you got there. Shared context is what is true now, with enough evidence to check it.
Why is pasting several chats into the next agent a poor default?
Merged transcripts mix discarded ideas with current ones, hide who had authority, and often include private material. The next agent then has to reconstruct the project under time pressure. A small current state is slower to write once and much cheaper to reuse.
What should stay out of the shared file?
Raw conversations, credentials, customer data, unreviewed drafts, and personal tool settings. Share the accepted claim and a pointer to the source. If the next person needs the full discussion, they can open that source with the right access—not through a prompt dump.
Does better context make an agent write better code?
Not by itself. A July 2026 ablation of context-injection strategy found that adding context files did not measurably improve correctness on the tasks it tested. Agents still failed on implementation skill: feature design, pattern selection, and exact wiring. Good context can stop a session from solving the wrong problem. It cannot compensate for weak execution.
What should a handoff contain?
The current story, the constraints that still bind, the questions that are still open, the work in motion, and the evidence behind those claims. If the next agent cannot tell what is accepted, what is disputed, and what to do first, the handoff is not finished.
Sources
Further reading
- Do context files help coding agents?
July 2026 ablation across two frontier agents. In the tasks it tested, context injection did not measurably improve correctness; failures clustered on implementation skill rather than missing repository knowledge.
- What developers put in persistent project context
A qualitative study of 401 repositories with developer-authored rule files. It characterizes that context; it does not claim that writing more of it automatically improves agent output.
- Model Context Protocol architecture
MCP standardizes how applications exchange context with servers. It does not dictate how an application decides what is current, who had authority, or what should stay private.
- Agent Project Context introduction
One proposal for a project-owned contract, kept separate from runtime sessions and private configuration. It is a useful example of where that boundary can be drawn.
Adjacent problems
Related guides
Vespyn
If you want this kept current for you
Vespyn is being built around shared project state for people and agents. It is not generally available. The next step is the waitlist.
Join waitlist