> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code Setup

> Native MCP support for Copilot and AI chat extensions in VS Code

<Note>
  **Prerequisite**: Install the `engram` binary first via [Homebrew](/installation#homebrew-macos-linux) or [binary download](/installation#download-binary).
</Note>

VS Code supports MCP servers natively in its chat panel (Copilot agent mode). This works with **any** AI agent running inside VS Code — Copilot, Claude Code extension, or any other MCP-compatible chat provider.

## Option A: Workspace Config (Recommended for Teams)

Commit to source control so the whole team gets Engram automatically.

Create `.vscode/mcp.json` in your project:

```json theme={null}
{
  "servers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}
```

<Steps>
  <Step title="Install engram binary">
    ```bash theme={null}
    brew install gentleman-programming/tap/engram
    ```
  </Step>

  <Step title="Create workspace MCP config">
    Create `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "engram": {
          "command": "engram",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Step>

  <Step title="Commit to git">
    ```bash theme={null}
    git add .vscode/mcp.json
    git commit -m "Add engram MCP server"
    ```
  </Step>

  <Step title="Restart VS Code">
    Reload the window or restart VS Code.
  </Step>
</Steps>

## Option B: User Profile (Global)

Available across all workspaces, but not committed to git.

<Steps>
  <Step title="Open Command Palette">
    Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux)
  </Step>

  <Step title="Run MCP: Open User Configuration">
    Type "MCP: Open User Configuration" and select it
  </Step>

  <Step title="Add engram server">
    Add to the opened `mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "engram": {
          "command": "engram",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Step>

  <Step title="Save and restart">
    Save the file and reload VS Code.
  </Step>
</Steps>

### User MCP Config Paths

| Platform | Path                                               |
| -------- | -------------------------------------------------- |
| macOS    | `~/Library/Application Support/Code/User/mcp.json` |
| Linux    | `~/.config/Code/User/mcp.json`                     |
| Windows  | `%APPDATA%\Code\User\mcp.json`                     |

## Option C: CLI One-Liner

Quick install via command line:

```bash theme={null}
code --add-mcp "{\"name\":\"engram\",\"command\":\"engram\",\"args\":[\"mcp\"]}"
```

## Using with Claude Code Extension

<Info>
  The **Claude Code extension** in VS Code uses its own MCP config at `.claude/settings.json`, not `.vscode/mcp.json`.
</Info>

If you're using the Claude Code extension inside VS Code, follow the [Claude Code setup instructions](/agents/claude-code) instead.

The `.claude/settings.json` config works whether you use Claude Code as:

* A standalone CLI
* A VS Code extension

## Adding the Memory Protocol (Recommended)

Without the Memory Protocol, the agent has the tools but doesn't know WHEN to use them.

### For Copilot

Create a `.instructions.md` file in the VS Code User `prompts/` folder:

| Platform | Path                                                                            |
| -------- | ------------------------------------------------------------------------------- |
| macOS    | `~/Library/Application Support/Code/User/prompts/engram-memory.instructions.md` |
| Linux    | `~/.config/Code/User/prompts/engram-memory.instructions.md`                     |
| Windows  | `%APPDATA%\Code\User\prompts\engram-memory.instructions.md`                     |

Paste the Memory Protocol from [DOCS.md](https://github.com/Gentleman-Programming/engram/blob/main/DOCS.md#memory-protocol-full-text) into this file.

### For Other Chat Extensions

Add the Memory Protocol text to your extension's custom instructions or system prompt configuration.

See [Memory Protocol](/concepts/memory-protocol) for the full text.

## Memory Protocol Content

The Memory Protocol tells the agent:

* **When to save** — After bugfixes, decisions, discoveries, config changes, patterns
* **When to search** — Reactive ("remember", "recall") + proactive (overlapping past work)
* **Session close** — Mandatory `mem_session_summary` before ending
* **After compaction** — Recover state with `mem_context`

Minimal version for VS Code instructions:

```markdown theme={null}
## Memory

You have access to Engram persistent memory via MCP tools (mem_save, mem_search, mem_session_summary, etc.).

- Save proactively after significant work — don't wait to be asked.
- After any compaction or context reset, call `mem_context` to recover session state before continuing.
```

## Platform-Specific Notes

### Windows

Make sure `engram.exe` is in your `PATH`. VS Code resolves MCP commands from the system PATH.

Check:

```powershell theme={null}
where engram
```

If not found, add the directory containing `engram.exe` to your PATH.

### macOS

If you installed via Homebrew, `engram` is automatically in `PATH`:

```bash theme={null}
which engram
```

### Linux

If you installed via Homebrew:

```bash theme={null}
which engram
```

If you downloaded a binary, move it to `/usr/local/bin` or add its directory to `PATH`.

## Troubleshooting

### MCP tools not showing up

Check that `mcp.json` exists and has the correct format:

```bash theme={null}
# Workspace config
cat .vscode/mcp.json

# User config (macOS)
cat ~/Library/Application\ Support/Code/User/mcp.json

# User config (Linux)
cat ~/.config/Code/User/mcp.json

# User config (Windows)
type %APPDATA%\Code\User\mcp.json
```

### Binary not found

VS Code can't find `engram` command:

```bash theme={null}
# Check PATH
echo $PATH

# Check binary location
which engram  # macOS/Linux
where engram  # Windows
```

If missing, install via [Homebrew](/installation#homebrew-macos-linux) or [binary download](/installation#download-binary).

### Extension not loading MCP

Restart VS Code after adding `mcp.json`:

1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Run **Developer: Reload Window**

## Next Steps

* Learn about the [Memory Protocol](/concepts/memory-protocol)
* Explore [MCP Tools](/features/mcp-tools)
* Set up [Git Sync](/features/git-sync) for team memory sharing