Agent Memory vs Shared Project State

Agent memory can help a coding assistant recall conventions and past context. It does not, by itself, tell a second agent whether a task is still owned, whether a person approved a change, or whether yesterday’s test result covers today’s files. For work that crosses sessions or tools, use three layers: conversational memory for useful leads, repository instructions for standing rules, and a current shared work record for ownership, decisions, and evidence. The distinction matters most when an interrupted task looks ready to resume but its state changed while the first agent was away.

This guide is for engineers coordinating coding assistants across sessions or editors. The interrupted feature below is an original illustration, not a customer story or observed AppHandoff run. As of October 2026, product-specific details follow the repository’s current MCP getting-started documentation; the broader descriptions of memory and instructions are grounded in GitHub’s Copilot Memory documentation and Anthropic’s Claude Code memory documentation. Their behaviors differ, so check the product and setting you actually use.

Three kinds of context answer different questions

Conversational memory is a way for an assistant or client to reuse information from earlier interactions. That may include a preference, an architectural fact, or a summary of a previous task. Its scope is product-specific. For example, GitHub documents repository-level facts and user-level preferences in Copilot Memory, currently in public preview, and says cited repository facts are checked against the current branch before use. That documented check is valuable, but it is not a universal promise for every agent memory product, and a code citation cannot show who currently owns a work item.

Repository instructions are checked-in guidance such as AGENTS.md, CLAUDE.md, or a client-specific instruction file. They can tell an agent where the code lives, which tests to run, how to handle secrets, and when to ask for approval. GitHub’s repository instructions guide describes both repository-wide and path-specific guidance. Instructions travel with a repository revision, so read the version on the branch in front of you. A standing rule can say to check the board before editing; it cannot reliably state which person owns a particular card this morning.

Authoritative project state is the current record of a particular job: its owner, stage, approved boundaries, latest decision, and proof. A ticket or project board can provide that record if participating agents read the same source and writes are controlled. The word authoritative is conditional: a board only deserves that role when its entries are maintained, scoped to the right project, and checked at the point of action. A stale board entry is still stale. The practical rule is to verify a mutable fact where it is maintained, record the source and revision, and refresh it before a decision that depends on it.

A task that resumes after its owner changes

Imagine a team adding a password reset screen. On Monday, Agent A reads a task card, claims the UI portion, and learns from a conversation that the team uses a shared form component. It writes half the screen and stops when its session ends. On Tuesday, a maintainer narrows the card: the backend endpoint is delayed, and Agent B takes ownership of the UI to align it with a revised design. Agent A returns on Wednesday with a plausible memory: ‘I own the reset screen, and the endpoint is ready.’ Both clauses may have been true at one time; neither is safe to act on now.

The repository can answer some questions. A checked-in instruction may say to use the central form component; the branch shows which files changed; a test report may show that a component test passed on a particular commit. It cannot infer the Tuesday reassignment from Monday’s transcript. The shared work item should carry the current owner and scope, link the revised design decision, and identify the endpoint dependency. A returning agent first reads that item, then inspects the branch and any cited proof. If the card and branch disagree, it asks the owner to resolve the conflict before editing the overlapping screen.

A useful handoff in this example is specific: ‘Reset UI, card revision 4; Agent B owns the form files; backend endpoint remains blocked; design decision linked on the card; component test passed on commit abc123 before the latest design update; next action is to recheck the form against that update.’ The identifier and hash are illustrative placeholders. The wording separates a source, a version, an owner, evidence, and a next action. It also makes the expired test proof visible instead of silently upgrading an old pass into a current one.

Record facts with provenance and refresh rules

A memory entry can point an agent toward a project convention. To make it useful, attach the path or document from which the convention came and check that source on the working branch. For a decision, record who approved it, where that approval lives, and what scope it covers. For test evidence, record the command, outcome, commit or revision, and environment. These are different kinds of facts; giving them the same ‘remembered’ label hides whether they are still current.

Refresh frequency follows how quickly a fact can change. A formatting rule may stay valid until its file changes. A task claim may change while another agent is active, so read the current card immediately before taking ownership or editing a contested path. A passing test is tied to the code and environment it exercised; rerun the focused check after a relevant change. An approval applies to its stated action and scope, not to every later variation. If the source is unavailable, mark the dependent fact unknown rather than filling the gap with a confident recollection.

1. Identify the work item and project; read the current card rather than trusting a conversation summary.
2. Confirm owner, approved scope, stage, and the latest decision before changing overlapping files.
3. Read the applicable instruction files on the active branch and inspect the actual changed paths.
4. Match each proof claim to its command, result, revision, and environment; rerun checks affected by newer edits.
5. Write back a concise outcome with links to evidence and a named next action, subject to the project’s write rules.

This checklist is a decision aid, not an automatic safety guarantee. A repository instruction could be stale, a card could have an unrecorded verbal decision, and a test can miss a defect. When sources conflict, expose the conflict and ask the authorized owner to settle it. See the engineering handoffs guide for the costs of missing context and the cross-client orchestration guide for dividing work across editors.

Where a shared MCP record helps

MCP can give a compatible client a discoverable tool interface to a shared service. The official 2026-07-28 MCP tools specification defines listing and calling tools; it does not decide which teammate owns a ticket or grant project approval. Those are application rules behind the tool. An MCP connection also depends on the specific client, account, and permission scope. A tool appearing in a catalog is not proof that a write will succeed, and a remembered tool name is not a substitute for current discovery.

AppHandoff’s documented endpoint is https://api.apphandoff.com/mcp. Its current service has eight tools: bootstrap, get, find, ticket, plan, message, project, and decide_lifecycle_proposal. The last is for a signed-in human approval card, not a model action, and may be hidden from clients without that support. With an authorized connection, an agent can use bootstrap to resolve the project, then get for a known card or find for a list. Writes depend on scope, project rules, and any required human approval. The AppHandoff MCP overview and connection guide explain the surface.

A read still needs judgment. Check that the resolved project matches the requested repository, that the card is the intended one, and that the returned revision is recent enough for the action. Use the card to find the decision and test evidence, then inspect those sources. A missing record should produce an explicit unknown, not an invented status. This is why the shared record complements memory: memory speeds orientation, while the current read can reveal a changed owner or blocked dependency that no earlier conversation contained.

Choose the smallest durable record

A one-session code edit may only need the repository rules and a concise final report. A change that crosses people, agents, or days benefits from a shared item with owner, scope, decisions, and evidence. Do not paste full transcripts or secrets into it. Summarize the verified facts and link to their source. If the team already has a reliable issue system, use it; the important property is that every participant can read the same current record and that the write policy matches the team’s authority model.

For a single interrupted session, the agent handoff generator can format the facts you enter into a draft. It is deterministic: it does not inspect your repository, read a card, check ownership, run tests, or approve an action. Review each field against current sources before sharing the result. For a recurring multi-agent workflow, pair that concise handoff with a maintained shared work item so the next agent can refresh mutable facts rather than inherit an attractive but outdated story.

A practical boundary for memory

Use agent memory to shorten rediscovery: where a module lives, which document describes the workflow, and which conventions tend to matter. Use repository instructions to tell agents how to work in this codebase. Use the current work record to decide who acts next and under which approval. In the reset-screen example, memory correctly points to the shared form component; the instruction file confirms how to use it; the current card reveals that Agent B owns the changed UI and the endpoint is blocked. That separation lets a returning agent resume safely without pretending that recall is a lock, a test result, or an authorization decision.