Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(mcp): add VS Code GitHub Copilot client

Thiago Zanlucaec4e75f08800
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b1dfeec..2360433b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
+### Added
+- `install-mcp --client vscode-copilot` renders (and `--apply` writes) a
+ workspace-scoped `.vscode/mcp.json` for VS Code GitHub Copilot's agent
+ mode. The renderer uses VS Code's MCP framework schema — top-level
+ `servers` key, `type: "http"`, `url`, and an inline `headers` map for
+ the bearer token — and includes a note that VS Code Copilot does not
+ yet expose lifecycle hooks, so ai-memory's automatic capture is not
+ active there (the MCP tools must be called explicitly from chat).
+ Aliases: `copilot`, `github-copilot`. `uninstall --only mcp` strips
+ the same entry idempotently.
## [1.0.0] - 2026-06-12
### Added
diff --git a/README.md b/README.md
index b0967ca7..9665a585 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,7 @@
| Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. |
| OpenClaw | Supported | MCP config + native plugin lifecycle hooks. |
| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). |
+| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
| Embedding providers | Supported | OpenAI, Voyage, and Google Gemini. |
@@ -78,8 +79,9 @@ priors are at the [bottom](#influences-and-prior-art).
mode. Mounted on the same axum server as MCP.
- **Multi-agent + multi-machine ready.** Supported clients: Claude
Code, Codex, OpenCode, Cursor, Claude Desktop (via `mcp-remote`),
- Gemini CLI, Antigravity CLI, OpenClaw, and Oh My Pi / OMP
- (`pi` / `omp` aliases).
+ Gemini CLI, Antigravity CLI, OpenClaw, Oh My Pi / OMP
+ (`pi` / `omp` aliases), and VS Code GitHub Copilot agent mode
+ (MCP-only, workspace `.vscode/mcp.json`).
Server runs local (loopback) OR on a homelab box (LAN/VPN/cloud)
with bearer-token auth. Shared servers can opt into
[`[auto_scope]` modes](docs/auto-scope.md) for per-user or
@@ -269,8 +271,8 @@ use `--mcp-url` if you installed MCP with a custom endpoint, and
and staged hook scripts. Redeploy remote servers separately.
For Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI,
-OpenClaw, curl-based hook installs, source builds, CLI env vars, and the full
-subcommand reference, see [`docs/install.md`](docs/install.md).
+OpenClaw, VS Code Copilot, curl-based hook installs, source builds, CLI env vars,
+and the full subcommand reference, see [`docs/install.md`](docs/install.md).
## Security
@@ -521,7 +523,7 @@ diagram, crate breakdown, schema notes, and invariants.
| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation. |
| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: default single-slot routing, session-aware isolation, and multi-user `per_actor` behavior. |
| [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and current hook/MCP harness caveats. |
-| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes (Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP). |
+| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes (Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP, VS Code Copilot). |
| [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, pointers to the TLS guide. |
| [`docs/users.md`](docs/users.md) | **Multi-user attribution (v0.8).** Four-rung auth ladder, `ai-memory user add/list/expire/revive/rotate-token` walkthrough, backward-compat migration for pre-v0.8 installs, token storage rationale. |
| [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS (multi-user, non-loopback) and when you don't (loopback / stdio). Copy-paste docker compose templates for Caddy + Let's Encrypt, Caddy + internal CA (LAN-only), Cloudflare Tunnel (no open ports), and external cert files; plus native-Caddy + nginx recipes. The "thinking you're secure when you're not" failure modes explicitly called out. |
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 046fbc80..59ea15d3 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -747,6 +747,19 @@ pub enum McpClient {
/// Google Antigravity CLI (`agy`) — `~/.gemini/antigravity-cli/mcp_config.json`.
#[value(alias = "antigravity", alias = "agy")]
AntigravityCli,
+ /// VS Code GitHub Copilot (agent mode) — per-workspace
+ /// `.vscode/mcp.json`. Copilot's agent mode reads MCP servers
+ /// from VS Code's own MCP framework (top-level `servers` key),
+ /// so the same JSON file works for any MCP-capable VS Code
+ /// extension, not just Copilot. Default scope is the current
+ /// workspace; pass `--config-file ~/path/to/mcp.json` to target
+ /// the user-level config instead.
+ ///
+ /// The hook surface (PreToolUse/PostToolUse/SessionStart) does
+ /// not yet exist in VS Code Copilot — this is MCP-only by
+ /// design. See `install-mcp --client vscode-copilot`.
+ #[value(name = "vscode-copilot", alias = "copilot", alias = "github-copilot")]
+ VsCodeCopilot,
}
/// Arguments for `commit`.
@@ -1188,6 +1201,29 @@ mod tests {
}
}
+ #[test]
+ fn vscode_copilot_aliases_parse_to_same_variant() {
+ for alias in ["vscode-copilot", "copilot", "github-copilot"] {
+ let cli = Cli::try_parse_from([
+ "ai-memory",
+ "install-mcp",
+ "--client",
+ alias,
+ "--server-url",
+ "http://example.test:49374/mcp",
+ ])
+ .unwrap_or_else(|e| panic!("failed to parse install-mcp alias {alias}: {e}"));
+
+ let Command::InstallMcp(args) = cli.command else {
+ panic!("expected install-mcp command for alias {alias}");
+ };
+ assert!(
+ matches!(args.client, McpClient::VsCodeCopilot),
+ "alias {alias} must resolve to the VS Code Copilot MCP client"
+ );
+ }
+ }
+
#[test]
fn auth_login_openai_oauth_parses() {
let cli = Cli::try_parse_from([
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index a2cefd03..0e44e785 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -283,6 +283,12 @@ fn infer_installed_mcp_config(agent: AgentChoice) -> Option<InferredMcpConfig> {
infer_json_mcp_config(&content, &["mcpServers", "ai-memory"], "serverUrl")
}
McpClient::ClaudeDesktop => None,
+ // MCP-only client: no AgentChoice counterpart routes here.
+ // Reachable only if a future install_hooks flow targets VS
+ // Code Copilot directly.
+ McpClient::VsCodeCopilot => {
+ infer_json_mcp_config(&content, &["servers", "ai-memory"], "url")
+ }
}
}
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index bd2c66a8..028f7cc1 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -31,6 +31,12 @@ enum JsonMcpLocation {
RootMcpServers,
RootMcp,
NestedMcpServers,
+ /// Top-level `servers` key — what VS Code's MCP framework expects
+ /// in `.vscode/mcp.json` (workspace) or the user-level mcp.json.
+ /// Distinct from `RootMcpServers` despite the similar shape: VS
+ /// Code documents `servers`, not `mcpServers`, and writing the
+ /// wrong key produces a silent no-op rather than an error.
+ RootServers,
}
/// Run the `install-mcp` subcommand.
@@ -58,6 +64,7 @@ pub fn run(config: &Config, args: InstallMcpArgs) -> Result<()> {
McpClient::Openclaw => render_openclaw(&args)?,
McpClient::Pi => render_pi(&args)?,
McpClient::AntigravityCli => render_antigravity_cli(&args)?,
+ McpClient::VsCodeCopilot => render_vscode_copilot(&args)?,
};
println!("{snippet}");
Ok(())
@@ -135,6 +142,16 @@ pub(crate) fn mcp_config_path(client: crate::cli::McpClient) -> Result<PathBuf>
.join(".gemini")
.join("antigravity-cli")
.join("mcp_config.json"),
+ // VS Code MCP is workspace-scoped by default: `.vscode/mcp.json`
+ // at the current workspace root. The user-level alternative is
+ // managed through VS Code's `MCP: Add server` palette and not
+ // a single canonical file path, so we don't try to detect it
+ // here — `--config-file` is the escape hatch for users who
+ // want to target a non-standard location.
+ McpClient::VsCodeCopilot => std::env::current_dir()
+ .context("could not resolve current dir for .vscode/mcp.json default")?
+ .join(".vscode")
+ .join("mcp.json"),
})
}
@@ -183,6 +200,7 @@ fn json_mcp_location(client: McpClient) -> Option<JsonMcpLocation> {
| McpClient::AntigravityCli => Some(JsonMcpLocation::RootMcpServers),
McpClient::OpenCode => Some(JsonMcpLocation::RootMcp),
McpClient::Openclaw => Some(JsonMcpLocation::NestedMcpServers),
+ McpClient::VsCodeCopilot => Some(JsonMcpLocation::RootServers),
McpClient::Codex => None,
}
}
@@ -231,6 +249,14 @@ fn upsert_json_mcp_entry(
.context("`mcp.servers` is present but not an object")?;
servers.insert(args.name.clone(), entry);
}
+ JsonMcpLocation::RootServers => {
+ let servers = root
+ .entry("servers")
+ .or_insert_with(|| serde_json::Value::Object(serde_json::Map::new()))
+ .as_object_mut()
+ .context("`servers` is present but not an object")?;
+ servers.insert(args.name.clone(), entry);
+ }
}
Ok(())
}
@@ -248,6 +274,9 @@ fn render_json_mcp_fragment(args: &InstallMcpArgs) -> Result<String> {
JsonMcpLocation::NestedMcpServers => json!({
"mcp": { "servers": { args.name.as_str(): entry } }
}),
+ JsonMcpLocation::RootServers => json!({
+ "servers": { args.name.as_str(): entry }
+ }),
};
Ok(serde_json::to_string_pretty(&fragment)?)
}
@@ -306,6 +335,18 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
entry.insert("headers".into(), json!({"Authorization": b}));
}
}
+ McpClient::VsCodeCopilot => {
+ // VS Code MCP framework schema: `type: "http"` + `url`,
+ // headers map for auth. Verified against
+ // https://code.visualstudio.com/docs/agents/reference/mcp-configuration.
+ // The `mcpServers` key (used by Claude Code/Cursor/Gemini)
+ // is silently ignored here — VS Code reads `servers`.
+ entry.insert("type".into(), json!("http"));
+ entry.insert("url".into(), json!(args.server_url));
+ if let Some(b) = &bearer {
+ entry.insert("headers".into(), json!({"Authorization": b}));
+ }
+ }
_ => bail!("internal: build_mcp_entry called for unsupported client"),
}
Ok(serde_json::Value::Object(entry))
@@ -584,6 +625,29 @@ fn render_antigravity_cli(args: &InstallMcpArgs) -> Result<String> {
))
}
+fn render_vscode_copilot(args: &InstallMcpArgs) -> Result<String> {
+ Ok(format!(
+ "# VS Code GitHub Copilot (agent mode) — write to one of:\n\
+ # - .vscode/mcp.json (workspace, recommended — matches\n\
+ # ai-memory's per-cwd auto-scoping)\n\
+ # - ~/.vscode/mcp.json (user-level, all workspaces)\n\
+ #\n\
+ # VS Code's MCP framework uses `servers` (NOT `mcpServers`) as the\n\
+ # top-level key, `type: \"http\"` for streamable-HTTP endpoints, and\n\
+ # an inline `headers` map for Authorization. Copilot's agent mode\n\
+ # reads this config along with any other MCP-capable VS Code\n\
+ # extension. Toggle the server from the MCP view in the\n\
+ # Extensions sidebar after editing.\n\
+ #\n\
+ # NOTE: VS Code Copilot does not yet expose lifecycle hooks\n\
+ # (PreToolUse / PostToolUse / SessionStart), so ai-memory's\n\
+ # automatic capture is NOT active here — call `memory_query`,\n\
+ # `memory_write_page`, etc. from chat when you need them.\n\
+ {snippet}\n",
+ snippet = render_json_mcp_fragment(args)?,
+ ))
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -622,6 +686,7 @@ mod tests {
McpClient::Openclaw => render_openclaw(&args).unwrap(),
McpClient::Pi => render_pi(&args).unwrap(),
McpClient::AntigravityCli => render_antigravity_cli(&args).unwrap(),
+ McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),
}
}
@@ -639,6 +704,7 @@ mod tests {
McpClient::Openclaw,
McpClient::Pi,
McpClient::AntigravityCli,
+ McpClient::VsCodeCopilot,
] {
let out = render_with_token(client);
// Every client embeds the token as `Authorization:
@@ -670,6 +736,7 @@ mod tests {
McpClient::Openclaw,
McpClient::Pi,
McpClient::AntigravityCli,
+ McpClient::VsCodeCopilot,
] {
let out = render_for_test(client);
assert!(
@@ -691,6 +758,7 @@ mod tests {
McpClient::Openclaw => render_openclaw(&args).unwrap(),
McpClient::Pi => render_pi(&args).unwrap(),
McpClient::AntigravityCli => render_antigravity_cli(&args).unwrap(),
+ McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),
}
}
@@ -750,6 +818,14 @@ mod tests {
assert!(render_for_test(McpClient::Codex).contains("[mcp_servers.ai-memory]"));
assert!(render_for_test(McpClient::Pi).contains("~/.omp/agent/mcp.json"));
assert!(render_for_test(McpClient::AntigravityCli).contains("\"serverUrl\""));
+ // VS Code Copilot must use the `servers` top-level key — the
+ // `mcpServers` form is silently ignored by VS Code's MCP
+ // framework. Regression guard against a future copy-paste
+ // from the Cursor / Claude Code renderer.
+ let vsc = render_for_test(McpClient::VsCodeCopilot);
+ assert!(vsc.contains("\"servers\""));
+ assert!(!vsc.contains("\"mcpServers\""));
+ assert!(vsc.contains("\"type\": \"http\""));
}
/// The Codex apply path must emit block-form `[mcp_servers.<name>]`
diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rs
index d67b7fed..760789b3 100644
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@ -183,6 +183,7 @@ fn build_plan(args: &UninstallArgs) -> anyhow::Result<Vec<PlannedChange>> {
Openclaw,
Pi,
AntigravityCli,
+ VsCodeCopilot,
] {
let Ok(path) = install_mcp::mcp_config_path(client) else {
continue;
@@ -588,6 +589,7 @@ fn mcp_servers_path(client: McpClient) -> Option<&'static [&'static str]> {
| McpClient::AntigravityCli => Some(&["mcpServers"]),
McpClient::OpenCode => Some(&["mcp"]),
McpClient::Openclaw => Some(&["mcp", "servers"]),
+ McpClient::VsCodeCopilot => Some(&["servers"]),
McpClient::Codex => None,
}
}
diff --git a/docs/install.md b/docs/install.md
index 017983be..114033b5 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -9,7 +9,7 @@ path (docker + Claude Code). This page covers everything else:
- [Arch Linux native packages (AUR)](#arch-linux-native-packages-aur)
(systemd system service or user service)
- [Configuring other agent CLIs](#configuring-other-agent-clis)
- (Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw)
+ (Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, VS Code Copilot)
- [Installing hooks without docker](#installing-hooks-without-docker)
(curl-based installer)
- [Running ai-memory without docker](#running-ai-memory-without-docker)
@@ -528,7 +528,7 @@ files owned by the user running the command. Prefer it as the
default; reach for `setup-agent` only when your docker setup is
known not to remap UIDs.
-### Cursor, Gemini CLI, Claude Desktop, OpenClaw, Antigravity CLI
+### Cursor, Gemini CLI, Claude Desktop, OpenClaw, Antigravity CLI, VS Code Copilot
See [**`docs/mcp-install.md`**](mcp-install.md) for the per-client MCP
config file path and snippet, or one-shot it via:
@@ -569,11 +569,16 @@ docker run --rm akitaonrails/ai-memory:latest \
docker run --rm akitaonrails/ai-memory:latest \
install-hooks --agent openclaw --auth-token "$TOKEN" \
--server-url "http://homelab:49374"
+
+docker run --rm akitaonrails/ai-memory:latest \
+ install-mcp --client vscode-copilot --auth-token "$TOKEN" \
+ --server-url "http://homelab:49374/mcp"
```
Cursor, Gemini CLI, Antigravity CLI, and OpenClaw support both `install-mcp` and
-`install-hooks`. Claude Desktop is MCP-only here, so you'll need to
-nudge the model to call `memory_query` / `memory_handoff_accept` itself.
+`install-hooks`. Claude Desktop and VS Code Copilot are MCP-only here,
+so you'll need to nudge the model to call `memory_query` /
+`memory_handoff_accept` itself.
For clients with `install-hooks` support, the capture path handles
handoff injection at session start or the client's closest equivalent
(Antigravity CLI uses `PreInvocation`).
@@ -1086,6 +1091,6 @@ write to `~/.local/share/ai-memory/hooks/`.
- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI,
routing snippet, and raw-wiki inspection
- [`docs/mcp-install.md`](mcp-install.md) - per-client MCP config
- reference for Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP
+ reference for Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP, VS Code Copilot
- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actually
running inside ai-memory
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 2ed748f7..b2c12db0 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -113,6 +113,84 @@ metadata.
---
+## VS Code GitHub Copilot
+
+**Status:** ✅ MCP supported (workspace-default). ❌ No lifecycle hooks
+(Copilot's agent mode does not expose `PreToolUse` / `PostToolUse` /
+`SessionStart` yet, so ai-memory's automatic capture is not active in
+VS Code — call `memory_query`, `memory_write_page`, etc. from chat).
+
+**Config file:**
+- Workspace (recommended): `.vscode/mcp.json` in the repo root. Matches
+ ai-memory's per-cwd auto-scoping.
+- User-level: `~/.vscode/mcp.json`, or managed through the **MCP: Add
+ server** palette command.
+
+**Schema (verified against VS Code's MCP reference):** top-level key is
+`servers` (NOT `mcpServers`). HTTP endpoints use `type: "http"` and the
+`url` field; the bearer token goes into an inline `headers` object.
+
+```json
+{
+ "servers": {
+ "ai-memory": {
+ "type": "http",
+ "url": "http://127.0.0.1:49374/mcp"
+ }
+ }
+}
+```
+
+**With a bearer token** (rendered when `--auth-token` is passed):
+
+```json
+{
+ "servers": {
+ "ai-memory": {
+ "type": "http",
+ "url": "http://127.0.0.1:49374/mcp",
+ "headers": {
+ "Authorization": "Bearer <token>"
+ }
+ }
+ }
+}
+```
+
+**Install command:**
+
+```bash
+# Print the snippet:
+ai-memory install-mcp --client vscode-copilot
+
+# Or write .vscode/mcp.json in the current workspace directly:
+ai-memory install-mcp --client vscode-copilot --apply
+```
+
+Aliases: `copilot`, `github-copilot`.
+
+**Gotchas:**
+- The top-level key must be `servers`. The `mcpServers` form (used by
+ Claude Code / Cursor / Gemini CLI) is silently ignored by VS Code.
+- After editing, open the MCP view in the Extensions sidebar and start
+ the server (or use **MCP: Show installed servers**). VS Code does not
+ auto-reload `.vscode/mcp.json` while the window is focused on another
+ tab.
+- Copilot Enterprise behaves the same as Copilot Individual/Business
+ for MCP — your org may restrict which MCP servers Copilot is allowed
+ to call; check **Settings → Copilot → MCP servers** if the server
+ shows as blocked.
+- Lifecycle hooks aren't possible until VS Code Copilot adds an agent
+ hook surface. Until then, the auto-handoff flow that other agents
+ enjoy (SessionStart auto-fetches a "where you left off" block) does
+ not run here — ask the agent to call `memory_handoff_accept`
+ manually if you want it.
+- Sources:
+ <https://code.visualstudio.com/docs/copilot/customization/mcp-servers>,
+ <https://code.visualstudio.com/docs/agents/reference/mcp-configuration>
+
+---
+
## Claude Desktop
**Status:** ✅ MCP supported (via stdio shim for HTTP). ❌ No lifecycle hooks.