copilot-memory-mcp (Python)

Cross-session memory layer for GitHub Copilot agent mode: SQLite for storage, an MCP server (Python SDK) for on-demand recall, and hooks for automatic capture — so a new Copilot session doesn't re-read the whole project or re-diagnose a bug you already fixed.

No Node required, and no LLM API key required either — Copilot does its own summarizing (see "Capture strategy" below). The only third-party dependency is mcp (the official Python SDK), and only server.py needs it — db.py and cli.py are pure stdlib (sqlite3, subprocess), so the hooks work with plain python3 and no virtualenv activation needed at hook-run time if you point them at a venv's interpreter directly.

Capture strategy

Copilot itself calls save_memory before finishing a substantial task — it's instructed to in copilot-instructions.md, and since it already has full conversation context, it writes a better summary than any script staring at a bare diff could. This needs no external API call.

The Stop hook is a safety net only: if a session ends without any memory saved (Copilot forgot, or the task was trivial), it records a plain "these files changed" fallback — no summarization, just enough to grep later. It checks session_has_memory() first so it never duplicates a proper entry Copilot already wrote.

Two files handle two different problems, deliberately kept separate:

• PROJECT_MAP.md — static-ish reference (module structure, entry points). Always loaded, cheap, updated manually when structure changes.

• .copilot-memory/memory.db (SQLite) — episodic fix/decision history. Only a short recent-index is always loaded; full detail is pulled via search_memory only when relevant.

Related MCP server: apex-memory

Setup

1. Copy this folder into your repo as .copilot-memory-mcp/ (or wherever — just keep paths in .vscode/mcp.json and hooks/hooks.json consistent).

2. Create a venv and install the one dependency:

   cd .copilot-memory-mcp
   python3 -m venv venv
   venv/bin/pip install -r requirements.txt

   If your VS Code python3 on PATH already has mcp installed globally (e.g. via pip install --user mcp), you can skip the venv and use python3 directly in the configs below.

3. Register the MCP server — copy .vscode/mcp.json into your repo's .vscode/ folder (merge if one exists). If you used a venv, point command at ${workspaceFolder}/.copilot-memory-mcp/venv/bin/python3 instead of the bare python3. Commit this file so your whole team gets the same server.

4. Wire up the hooks — hooks/hooks.json uses the same SessionStart / Stop hook schema as Claude Code / Copilot CLI. Hook registration location has moved around across VS Code releases, so confirm the exact spot for your version via the /hooks slash command in chat, or Developer: Open Agent Debug Panel to verify it's actually firing. Same venv note applies here if you used one — point python3 at the venv's interpreter.

5. Drop in the templates — copy templates/PROJECT_MAP.md and the contents of templates/copilot-instructions.md into your repo root and .github/copilot-instructions.md respectively. Fill in PROJECT_MAP.md for real (have Copilot draft it, then trim).

6. Gitignore the database:

   .copilot-memory/
   __pycache__/

   It's personal/session history, not something to commit — unlike the MCP config, instructions, and project map, which should all be checked in.

Tools exposed to Copilot

• save_memory — record a fix/decision, called by Copilot itself before finishing a substantial task (see "Capture strategy" above).

• search_memory — look up past fixes by keyword, filename, or error signature before re-investigating something.

• get_recent_context — short recent-fix index (normally already injected by the SessionStart hook, but callable directly too).

Schema

CREATE TABLE memories (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    session_id TEXT,
    summary TEXT NOT NULL,
    root_cause TEXT,
    fix TEXT,
    files_touched TEXT,      -- JSON array
    error_signature TEXT,    -- normalized string for lookup
    tags TEXT                 -- JSON array
);

Notes / known rough edges

• MCP for Copilot Business/Enterprise requires the org-level "MCP servers in Copilot" policy to be enabled — already the case for you, but worth knowing if you take this to other teams.

• Hooks are a newer VS Code feature (landed 1.109, Jan 2026) — behavior and config location may still shift between releases. Re-check after any VS Code update if capture silently stops firing.

• Quality of memory depends on Copilot actually following the instruction to call save_memory — it's a prompt, not a guarantee. Skim search_memory results occasionally and see how many are tagged unsummarized/fallback; a high rate means the instruction isn't landing and may need to be more prominent or repeated closer to task completion.

• Verified locally: db.py round-trips insert/search/recent correctly, and server.py starts cleanly under the mcp SDK.