# Copilot Memory MCP

Give GitHub Copilot CLI (or any MCP-compatible agent) **persistent memory across sessions**.

Without this, Copilot CLI starts every session as a blank slate. With this MCP server running, it can save and recall knowledge — learning from experience just like you do.

## What It Does

- **Saves memories** — fixes, preferences, lessons, code snippets, project context
- **Recalls memories** — full-text search across everything it's ever learned
- **Categorizes knowledge** — preference, lesson, fix, context, convention, environment, snippet
- **Tracks usage** — knows which memories are accessed most often
- **Persists in SQLite** — lightweight, no external services, survives restarts

## Tools Provided

### Memory Tools

| Tool | Description |
|------|-------------|
| `save_memory` | Store a new piece of knowledge with category and tags |
| `recall_memories` | Search or browse past memories (full-text search) |
| `update_memory` | Update an existing memory when things change |
| `forget_memory` | Delete a memory that's no longer relevant |
| `memory_stats` | See what's in the knowledge base |

### Monitoring Tools

These solve the "Copilot stops and asks should I continue?" problem. Each tool runs a long-running polling loop internally, so Copilot uses **one tool call** instead of burning through its iteration limit.

| Tool | Description |
|------|-------------|
| `monitor_command` | Run a command repeatedly, collect output, stop on pattern/change/exit code |
| `watch_file` | Watch a file for changes or a regex pattern match |
| `poll_url` | Poll a URL until expected HTTP status or body pattern |
| `run_long_command` | Run a single long command, stream output, stop on pattern |

## Quick Start

### 1. Clone and install

```bash
git clone <this-repo> ~/projects/copilot-memory-mcp
cd ~/projects/copilot-memory-mcp
uv sync
```

Or if you don't have `uv`:

```bash
cd ~/projects/copilot-memory-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]>=1.20"
```

### 2. Test it works

```bash
# Quick test — should print tool list
uv run mcp dev server.py
```

This opens the MCP Inspector in your browser where you can test the tools interactively.

### 3. Add to GitHub Copilot CLI

Edit (or create) your Copilot MCP config file:

**Linux/macOS:**
```bash
mkdir -p ~/.config/github-copilot
nano ~/.config/github-copilot/mcp.json
```

**Windows:**
```
%LOCALAPPDATA%\github-copilot\mcp.json
```

Add this content:

```json
{
  "mcpServers": {
    "copilot-memory": {
      "command": "uv",
      "args": ["run", "--directory", "/FULL/PATH/TO/copilot-memory-mcp", "server.py"],
      "env": {}
    }
  }
}
```

**Important:** Replace `/FULL/PATH/TO/copilot-memory-mcp` with the actual absolute path.

If you don't have `uv`, use the venv Python directly:

```json
{
  "mcpServers": {
    "copilot-memory": {
      "command": "/FULL/PATH/TO/copilot-memory-mcp/.venv/bin/python",
      "args": ["/FULL/PATH/TO/copilot-memory-mcp/server.py"],
      "env": {}
    }
  }
}
```

### 4. Add the instructions file (recommended)

Copy the included template to your global Copilot instructions so it knows to USE the memory:

```bash
mkdir -p ~/.github
cp copilot-instructions-template.md ~/.github/copilot-instructions.md
```

Or for a specific repo:

```bash
cp copilot-instructions-template.md YOUR_REPO/.github/copilot-instructions.md
```

### 5. Use it

Start Copilot CLI normally. It will now have access to memory tools. The instructions file tells it to check memory at session start and save important learnings.

```
$ copilot

> Hey, can you check what you remember about this project?

# Copilot calls recall_memories() automatically
# and loads any past context
```

## How the Learning Loop Works

```
Session 1:
  You: "Always use pytest, never unittest"
  Copilot saves: {category: "preference", content: "User prefers pytest over unittest"}

Session 2:
  Copilot starts → calls recall_memories() → loads preference
  Copilot: "I'll set up the tests with pytest as you prefer."
  You debug a tricky async issue together
  Copilot saves: {category: "fix", content: "asyncio.gather swallows exceptions — use return_exceptions=True"}

Session 3:
  Copilot starts → recalls all memories → knows your preferences AND past fixes
  You hit a similar async bug
  Copilot: "This looks like the asyncio.gather issue we fixed before — need return_exceptions=True"
```

**Each session makes the next one smarter.**

## Monitoring — No More "Should I Continue?"

The monitoring tools solve Copilot CLI's biggest limitation: it stops and asks
for confirmation during long-running tasks. These tools do the looping internally.

### Example: Watch a Kubernetes deployment

```
You: "Deploy the new version and monitor until all pods are running"

Copilot runs:
  monitor_command(
    command="kubectl get pods -l app=myapp",
    interval_seconds=10,
    timeout_seconds=300,
    stop_pattern="1/1.*Running"
  )

→ Tool polls every 10s for up to 5 minutes
→ Returns all snapshots when pods are Running
→ ONE tool call, no iteration limit hit
```

### Example: Watch a build log

```
You: "Start the build and tell me when it's done"

Copilot runs:
  run_long_command(
    command="npm run build 2>&1",
    timeout_seconds=300,
    stop_pattern="Build complete|ERROR"
  )

→ Captures the entire build output
→ Returns immediately when it sees success or failure
```

### Example: Wait for a service to come up

```
You: "Deploy and let me know when the health check passes"

Copilot runs:
  poll_url(
    url="http://localhost:8080/health",
    expected_status=200,
    expected_body_pattern="healthy",
    interval_seconds=5,
    timeout_seconds=120
  )

→ Polls every 5s until 200 + "healthy" in body
→ Reports back with timing and response details
```

### Max monitoring duration

Default max is 1 hour (3600 seconds). Override with env var:

```json
{
  "mcpServers": {
    "copilot-memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/copilot-memory-mcp", "server.py"],
      "env": {
        "COPILOT_MEMORY_MAX_MONITOR": "7200"
      }
    }
  }
}
```

## Configuration

### Custom database location

By default, memories are stored in `~/.copilot-memory/memory.db`. Override with:

```json
{
  "mcpServers": {
    "copilot-memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/copilot-memory-mcp", "server.py"],
      "env": {
        "COPILOT_MEMORY_DB": "/custom/path/to/memory.db"
      }
    }
  }
}
```

### SSE transport (for HTTP-based clients)

```bash
uv run server.py --transport sse
```

This starts an HTTP server (default port 8000) for clients that prefer SSE over stdio.

## Works With Other Agents Too

This isn't Copilot-specific. Any MCP client can use it:

- **Claude Code** — add to `.mcp.json` in your project
- **Cline (VS Code)** — add to MCP server settings
- **Hermes Agent** — add to `config.yaml` under `mcp.servers`
- **Cursor** — add to MCP configuration
- **Any MCP-compatible tool**

### Claude Code example (`.mcp.json` in project root):

```json
{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/copilot-memory-mcp", "server.py"]
    }
  }
}
```

## File Structure

```
copilot-memory-mcp/
├── server.py                        # The MCP server (all-in-one)
├── copilot-instructions-template.md # Template to tell Copilot to use memory
├── pyproject.toml                   # Python project config
├── uv.lock                          # Dependency lock file
└── README.md                        # You're reading it
```

## License

MIT — do whatever you want with it.