Manage memory, state, and execution

3.1 Implement agent memory strategies

Short-term, long-term and external memory

An agent should not rely on a single stream of context. Organize what it knows into three tiers, each with a different lifetime and purpose.

flowchart TB
  subgraph EXT["External memory — the source of truth"]
    direction TB
    subgraph LT["Long-term memory — curated, reusable"]
      direction TB
      ST["Short-term memory<br/>the current session's context window"]
    end
  end

Choose where each kind of information lives

Copilot Memory

Copilot Memory (public preview) lets Copilot build its own understanding of a repository and of your preferences, instead of making you restate them or maintain ever-growing instruction files. It is used by Copilot cloud agent, Copilot code review, Copilot CLI and agentic autofix, and a fact learned by one can be used by another.

• Retention: any fact or preference that goes unused is deleted automatically after 28 days; the timer can reset whenever Copilot successfully validates and uses the entry.
• Validation: only validated facts are used — a fact captured from a PR that was closed unmerged has no effect unless the current code still supports it.
• Enablement: per user, not per repository. On by default for individual plans; off by default for organization and enterprise plans until an administrator enables the policy, after which users are opted in and can opt out. With licences from several organizations, the most restrictive setting wins.
• Audit: exports, deletions and user opt-outs appear in the organization or enterprise audit log.

Scope memory to task-relevant information

Memory should contain only what affects the outcome: requirements and constraints, decisions that shape the implementation, and how to validate it. Temporary intermediate steps and duplicated context should not be kept — they crowd the context window and invite outdated information back in.

• Use path-specific instructions so payment rules load only for payment code, and excludeAgent to keep a file away from code review or cloud agent.
• Place nested AGENTS.md files next to the code they describe — the nearest one in the directory tree takes precedence.
• Prefer skills for long procedures: they load only when relevant, instead of occupying every request.
• In Copilot CLI, very large tool outputs (over 20 KiB by default) are saved to a file and only a preview enters the context.

---
applyTo: "src/payments/**"
excludeAgent: "code-review"
---

- Money is stored as integer cents; never use floating point.
- Every change here needs a unit test in tests/payments/.
- Decision record: docs/adr/0007-idempotency-keys.md is the source of truth for retries.

Define memory expiration, pruning and reset rules

- name: Upload plan and evidence
  uses: actions/upload-artifact@v7
  with:
    name: agent-evidence-${{ github.sha }}
    path: |
      plan.json
      reports/
    retention-days: 30      # shorter than the repository default of 90

3.2 Persist agent state and manage context drift

Capture progress and decisions as durable artifacts

Memory tells an agent what matters; state records what has been done, what was decided and what remains. In GitHub, state is not in one place — it is spread across artifacts that together act as persistent memory:

• The issue holds requirements and acceptance criteria.
• The pull request is the state anchor: task description, link to the issue, current plan, progress updates and decisions — GitHub aggregates commits, checks and discussion there.
• Commits represent incremental progress.
• Workflow runs capture validation results on every push.

Copilot cloud agent keeps the PR title and body current as it iterates, and its commit messages link back to the session log. Copilot CLI persists each session under ~/.copilot/session-state/ (checkpoints, a plan.md, created files), which is what makes --resume and --continue work.

Resume without repeating steps or diverging

flowchart LR
  OPEN["Open the existing PR"] --> READ["Re-read description<br/>and linked issue"]
  READ --> COMMITS["Check commits<br/>already pushed"]
  COMMITS --> CHECKS["Check the Checks tab<br/>latest results"]
  CHECKS --> CONTINUE["Continue from<br/>the latest state"]

// Copilot SDK. A session is only resumable if you give it your own ID —
// otherwise the SDK generates a random one you cannot find again.
await client.createSession({ sessionId: "alice-pr-214-review", model: "gpt-5.4" });

// Later, from a new client instance or after a restart:
const session = await client.resumeSession("alice-pr-214-review");
await session.sendAndWait({ prompt: "Continue with step 3 of the plan." });

// State lives in ~/.copilot/session-state/alice-pr-214-review/
//   checkpoints/  conversation snapshots
//   plan.md       the agent's planning state
//   files/        artifacts the agent created

Detect and correct drift

Context drift is when the agent's actions stop matching the original goal or earlier decisions — common in long, multi-step runs. Watch for:

• PR changes that do not satisfy the acceptance criteria.
• Commits that contradict decisions recorded in the PR or ADRs.
• Files changed outside the agreed scope.
• Required checks failing or, worse, missing.

flowchart TB
  SIG["Drift signal<br/>criteria unmet · decision contradicted · scope creep · checks failing"] --> ANCHOR["Re-anchor to the source of truth<br/>issue · PR description · instructions"]
  ANCHOR --> COMPARE["Compare changes<br/>with acceptance criteria"]
  COMPARE --> UPDATE["Update the PR description<br/>or steer the session"]
  UPDATE --> RERUN["Push a fix and re-run checks"]

# .github/workflows/scope-check.yml — flags drift outside the agreed paths
name: Scope check
on:
  pull_request:

permissions:
  contents: read

jobs:
  scope:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - name: Fail on files outside the allowed paths
        run: |
          allowed='^(src/|tests/|package(-lock)?\.json$)'
          outside=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD" | grep -Ev "$allowed" || true)
          if [ -n "$outside" ]; then
            echo "::error::Changes outside the agreed scope:"
            echo "$outside"
            exit 1
          fi

3.3 Ensure continuity of memory and state across tools and environments

Share agent state

Work often starts in an IDE, continues in the CLI and finishes in a cloud agent session. Share state through durable references — issue and PR URLs, branch names, commit SHAs, workflow run links — that every environment can resolve, not by copying context between chats.

flowchart LR
  IDE["IDE agent mode"] --> PR
  CLI["Copilot CLI"] --> PR
  CCA["Copilot cloud agent"] --> PR
  PR["Pull request #214<br/>branch · commits · checks · decisions"] --> ISSUE["Issue #198<br/>requirements · acceptance criteria"]

• /delegate (or an & prefix) in Copilot CLI hands the task to cloud agent, committing local changes as a checkpoint on a new branch first.
• Cloud agent sessions are shared with repository collaborators by default; local CLI and IDE sessions are private unless you share them, and synced sessions can be searched from Copilot Chat.
• Copilot Memory is shared across cloud agent, code review and the CLI for the same repository.

Prevent conflicting context

Conflicting context is the same information in several places with different values. Give each type of information one source of truth, update the original instead of making copies, and never restate acceptance criteria in prompts — link the issue.

Prevent stale context

Stale context is outdated information used as if it were current. Typical causes and fixes: