How Copilot Memory works in VS Code

copilotmemory.md

Overall algorithm

This is currently speculation:

1. When starting a session, it retrieves memories from the associated GitHub repository for the current branch and injects those into the initial user message.
2. When it sees something it should remember (like if I say "Remember that..."), it uses the memory tool to "view" existing memories, and then uses the memory tool to save the existing memory.
3. A hook then saves local memories to the GitHub repository and clears them from the local file system.

System prompt: How to use memory

When the memory tool is enabled, this instruction is added to the system prompt:

<repoMemory>
If you come across an important fact about the codebase that could help in future code review or generation tasks, beyond the current task, use the memory tool to store it. Use the `create` command with a path under `/memories/repo/` to store repository-scoped facts. The file content should be a JSON object with these fields: `subject`, `fact`, `citations`, `reason`, and `category`.

Facts may be gleaned from the codebase itself or learned from user input or feedback. Such facts might include:
- Conventions, preferences, or best practices specific to this codebase that might be overlooked when inspecting only a limited code sample
- Important information about the structure or logic of the codebase
- Commands for linting, building, or running tests that have been verified through a successful run

<examples>
- "Use ErrKind wrapper for every public API error"
- "Prefer ExpectNoLog helper over silent nil checks in tests"
- "Always use Python typing"
- "Follow the Google JavaScript Style Guide"
- "Use html_escape as a sanitizer to avoid cross site scripting vulnerabilities"
- "The code can be built with `npm run build` and tested with `npm run test`"

</examples>

Only store facts that meet the following criteria:
<factsCriteria>
- Are likely to have actionable implications for a future task
- Are independent of changes you are making as part of your current task, and will remain relevant if your current code isn't merged
- Are unlikely to change over time
- Cannot always be inferred from a limited code sample
- Contain no secrets or sensitive data

</factsCriteria>

Always include the reason and citations fields.
Before storing, ask yourself: Will this help with future coding or code review tasks across the repository? If unsure, skip storing it.

Note: Only `create` is supported for `/memories/repo/` paths.
If the user asks how to view or manage their repo memories refer them to https://docs.github.com/en/copilot/how-tos/use-copilot-agents/copilot-memory.

</repoMemory>

Initial user message: Existing memories

Any existing memories are inserted into the first user message:

<repository_memories>
The following are recent memories stored for this repository from previous agent interactions.
These memories may contain useful context about the codebase conventions, patterns, and practices.
However, be aware that memories might be obsolete or incorrect or may not apply to your current task.
Use the citations provided to verify the accuracy of any relevant memory before relying on it.\n\n

**markdown headings**
- Fact: Use sentence case for markdown headings in this repo (e.g., \"Phase 1: Merge PR\" not \"Phase 1: Merge PR\").
- Citations: User input: \"Remember that we always prefer sentence case for markdown headings for this repo\"
- Reason: This convention applies to all markdown files in the repository. It will be useful when creating or editing any .md files — issue descriptions, PR templates, documentation, AGENTS.md, README.md, etc. — to ensure consistent heading capitalization throughout the project.
Be sure to consider these stored facts carefully. Consider whether any are relevant to your current task. If they are, verify their current applicability before using them to inform your work.

If you come across a memory that you're able to verify and that you find useful, you should use the memory tool to store the same fact again. Only recent memories are retained, so storing the fact again will cause it to be retained longer.
If you come across a fact that's incorrect or outdated, you should use the memory tool to store a new fact that reflects the current reality.
</repository_memories>

Tool call: Retrieve memories

This tool call retrieves any memories that are stored locally.

Call:

id   : toolu_vrtx_01P5bnPxN7BNqCtXEnHGGr1P__vscode-1770850683905
tool : memory
args : {
  "command": "view",
  "path": "/memories"
}

Response:

No memories found.

Tool call: Store memories

This tool call stores a memory locally.

Call:

id   : toolu_vrtx_01KYCL2qPmCPzCkvGsLzBwKS__vscode-1770850683906
tool : memory
args : {
  "command": "create",
  "path": "/memories/repo/frontend-serving.json",
  "file_text": "{
  \"subject\": \"Frontend serving architecture\",
  \"fact\": \"The frontend is built with React (TypeScript, Vite) but the Python Quart backend serves the built frontend assets. The backend renders/serves the frontend rather than the frontend being served independently.\",
  \"citations\": [\"User input: 'this repo uses React for the frontend but that the backend is the one that renders the frontend'\", \"app/backend/app.py\", \"app/frontend/\"],
  \"reason\": \"Important architectural detail for understanding how the app is deployed and how frontend/backend interact. Affects how you think about routing, static file serving, and deployment.\",
  \"category\": \"architecture\"
}"
}

Response:

File created successfully at: /memories/repo/frontend-serving.json