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.mdindex 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### Addeddiff --git a/README.md b/README.mdindex 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: ClaudeCode, 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, andand 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.mdindex 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 thedefault; reach for `setup-agent` only when your docker setup isknown not to remap UIDs.-### Cursor, Gemini CLI, Claude Desktop, OpenClaw, Antigravity CLI+### Cursor, Gemini CLI, Claude Desktop, OpenClaw, Antigravity CLI, VS Code CopilotSee [**`docs/mcp-install.md`**](mcp-install.md) for the per-client MCPconfig 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 handleshandoff 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 actuallyrunning inside ai-memorydiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 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.