VS Code Setup

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

Prerequisite: Install the engram binary first via Homebrew or binary download.

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:

{
  "servers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

1. Install engram binary

   brew install gentleman-programming/tap/engram
   
2. Create workspace MCP config

   Create .vscode/mcp.json:

   {
     "servers": {
       "engram": {
         "command": "engram",
         "args": ["mcp"]
       }
     }
   }
   
3. Commit to git

   git add .vscode/mcp.json
   git commit -m "Add engram MCP server"
   
4. Restart VS Code

   Reload the window or restart VS Code.

Option B: User Profile (Global)

Available across all workspaces, but not committed to git.

1. Open Command Palette

   Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)

2. Run MCP: Open User Configuration

   Type “MCP: Open User Configuration” and select it

3. Add engram server

   Add to the opened mcp.json:

   {
     "servers": {
       "engram": {
         "command": "engram",
         "args": ["mcp"]
       }
     }
   }
   
4. Save and restart

   Save the file and reload VS Code.

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:

code --add-mcp "{\"name\":\"engram\",\"command\":\"engram\",\"args\":[\"mcp\"]}"

Using with Claude Code Extension

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

If you’re using the Claude Code extension inside VS Code, follow the Claude Code setup instructions 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 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 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:

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

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:

which engram

Linux

If you installed via Homebrew:

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:

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

# Check PATH
echo $PATH

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

If missing, install via Homebrew or binary download.

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
• Explore MCP Tools
• Set up Git Sync for team memory sharing