# 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.

## 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:**
   ```bash
   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

```sql
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.