Reliable agent swarm codebase context is not one transcript copied to every worker. It is a set of versioned repository artifacts, bounded task packets, and evidence-rich handoffs that independent coding agents can verify. Use parallel agents for separable work, give each component one owner, and route cross-cutting decisions through an integration owner.
That architecture lets a team reuse repository structure without pretending that agents share live memory. It also preserves the final responsibility to inspect current source, run tests, resolve conflicts, and approve the combined change.
Why Agent Swarms Lose Repository Context
Parallel coding agents begin with different working states. One worker may discover a generated-file rule, another may map the caller chain, and a third may act on an older architecture note. Unless those findings become explicit artifacts, each agent builds a partial repository model and later workers repeat the same searches.
Current product documentation reinforces this boundary. Anthropic says Claude Code subagents start with fresh isolated contexts, while agent-team teammates use fully independent contexts with a shared task list and messages. OpenAI describes Codex subagents as specialized workers whose results return for synthesis and notes that each worker consumes its own model and tool resources. Neither design creates a universal shared token window.
Context loss usually enters through four gaps:
- Unequal discovery: agents inspect different files and infer different boundaries.
- Unversioned evidence: a message names a relationship but not the commit, file, or symbol supporting it.
- Overlapping ownership: two writers modify the same component under incompatible assumptions.
- Missing synthesis: locally correct patches interact badly after merge.
Adding more agents can amplify these gaps. Anthropic’s agent-team guidance warns about coordination overhead and greater token use, especially when work is not independent. The safe objective is not maximum parallelism. It is the smallest set of independent workstreams that improves the accepted result after integration.
Shared Memory vs Shared Code Structure
“Shared agent memory” is useful shorthand but often hides several different artifacts. A swarm needs layers with different owners, freshness rules, and authority.
| Layer | Contents | Authority and lifetime |
|---|---|---|
| Policy | repository instructions, security boundaries, required commands, component ownership | human-reviewed; durable |
| Structure | modules, symbols, imports, calls, schemas, tests, provenance | generated for a named commit; refreshed |
| Task | objective, acceptance criteria, allowed files, relevant evidence, unknowns | task owner; expires with the task |
| Handoff | inspected locations, findings, changes, tests, assumptions, downstream effects | worker-authored; verified by receiver |
| Integration | combined diff, conflict decisions, full checks, unresolved risks | integration owner; retained with review |
Policy can live in scoped AGENTS.md files and reviewed engineering documentation. Structure can come from source indexes, code graphs, and architecture records. Task packets should contain only the evidence and permissions needed for one assignment. Handoffs should carry proof rather than a free-form claim such as “the payment module is unaffected.”
This layered model avoids turning a growing memory file into an unreviewed mixture of rules, guesses, and obsolete task history. The AGENTS.md versus knowledge graph guide explains why human intent and generated code relationships should remain distinct.
For cross-tool teams, sharing repository context across coding agents provides the broader contract. A swarm adds stricter concurrency controls because several workers may read and write from the same base revision at once.
How a Code Graph Reduces Duplicate Reads
A code graph can give each worker the same starting map. Instead of every agent scanning the repository root, a coordinator can query the affected symbol, follow import or call relationships, and attach a bounded neighborhood to the task packet.

Graphify documents graph artifacts that represent code entities and typed relationships such as calls and imports. It also distinguishes EXTRACTED, INFERRED, and AMBIGUOUS edges with provenance. Those labels matter in a swarm: an extracted import can guide navigation, while an inferred semantic relationship remains a hypothesis that a worker must check.
A practical structural packet can include:
- repository commit and graph snapshot time;
- affected nodes and relationship paths;
- source locations for extracted edges;
- confidence and provenance for inferred edges;
- likely tests, owners, and public boundaries;
- explicit gaps that require raw-source inspection.
This can reduce duplicate discovery when several agents need adjacent parts of the same map. It is not a universal speedup and does not make the graph ground truth. Dynamic dispatch, generated code, runtime configuration, cross-repository consumers, and stale indexes can leave relationships incomplete.
Workers should use the graph to choose where to read, then verify consequential paths in the current worktree. After accepted changes alter public symbols, imports, schemas, or calls, refresh the structural layer before assigning downstream tasks. A graph aligned to the base commit but not the current branches is historical evidence, not current context.
Coordination Patterns for Parallel Agents
The best coordination pattern depends on whether workers read, write, or aggregate. Four patterns cover most repository work.
- Read-only fan-out: assign architecture, dependency, test, and risk questions to separate agents. The coordinator compares evidence before any edit begins.
- Component ownership: give each writer a separate component and Git worktree. One owner controls each mutable file or package for the duration of the task.
- Sequential aggregation: let workers produce compact evidence packets that another agent or human combines. Google’s Chain-of-Agents research shows that explicit aggregation can help selected long-context tasks, including a code-completion benchmark; it does not establish that arbitrary swarms share knowledge automatically.
- Independent review: keep the reviewer out of implementation context, then provide the task contract, combined diff, test output, and known uncertainties.
Every assignment should name the objective, base commit, worktree, writable paths, acceptance criteria, graph snapshot, relevant source, required tests, permission limits, and return format. Avoid telling two workers to “handle the backend” when their edits can converge on shared schemas or generated clients.
Every handoff should record:
- task ID, worker, component, base commit, and worktree;
- files and symbols inspected;
- findings with source or graph-path evidence;
- changes made and the resulting commit or patch;
- commands and tests with exact outcomes;
- assumptions, failed approaches, and unresolved questions;
- downstream dependencies and required follow-up;
- permissions, external data, or network access used.
The integration owner decides whether the evidence is sufficient, orders dependent merges, refreshes shared structure, and runs checks against the combined tree. Workers own local correctness; the integrator owns interaction correctness.
Conflict, Drift, and Review Risks
Physical isolation prevents simultaneous filesystem edits, not logical conflict. Two worktrees can independently change an API and its caller in incompatible ways. Component ownership, contract freezes, and serialized integration are still required.

Use these controls:
- Conflict: assign one owner per mutable component; escalate cross-cutting edits to the integrator.
- Evidence drift: attach a commit to every graph, report, and handoff; mark results stale after relevant merges.
- Decision drift: store accepted architecture decisions in reviewed ADRs, not worker transcripts.
- Message risk: treat agent messages as leads. Verify high-impact findings against source, configuration, and tests.
- Permission drift: state allowed tools, writable paths, network access, and secret boundaries in each task.
- Review gaps: inspect the combined diff and run integration tests after all accepted patches land.
Task-local hypotheses should expire when the task closes. Retain reviewed decisions, accepted patches, test evidence, and reusable structural updates; discard speculative notes and superseded plans. If a finding becomes durable repository guidance, move it through normal review before adding it to policy or architecture documents.
Measure the swarm as a system. Useful signals include accepted-patch rate, duplicate file reads, missed dependencies, merge conflicts, reviewer corrections, total tokens, elapsed time, and integration failures. Do not infer value from agent count or wall-clock speed alone.
FAQ
Who resolves conflicting agent findings?
The named integration owner resolves them. That person or agent should compare source evidence, reproduce relevant commands, consult component owners, and record the decision. For security, data, public API, or deployment conflicts, the accountable human owner retains approval.
What should be logged between agents?
Log the task and owner, base commit and worktree, structural snapshot, inspected files and symbols, claims with evidence, changes, test commands and results, assumptions, unresolved questions, downstream dependencies, and permission boundaries. Keep summaries compact, but never omit provenance needed for verification.
How often should swarm memory expire?
Expire task-local context at task completion or when its base commit becomes unsuitable. Rebuild structural context after accepted relationship-changing edits. Keep policy and ADRs until reviewed or superseded. Expiry should follow artifact type and change risk, not one universal timer.
Conclusion
Agent swarms coordinate through explicit artifacts, not magical shared memory. Independent contexts make parallel work possible, but they also create repeated discovery, divergent assumptions, and integration risk.
Use versioned policy, commit-aligned structure, bounded task packets, evidence-bearing handoffs, isolated ownership, and one integration owner. A code graph can shorten navigation, but source and tests remain the authority. Add agents only when the work can be separated and the combined result can be verified.









