Skip to content

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

Rust

feat(mcp): add install-mcp --client copilot-cli (#1040)

Maxsuel Einstein1a0391f832fc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a73c087c..e02f0a55 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,8 +19,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`SessionStart` rather than Claude Code's envelope, so handoffs are not
injected yet: recover them with `memory_handoff_accept`. The bare
`install-mcp --client copilot` alias keeps meaning VS Code Copilot;
- `install-mcp --client copilot-cli` and `ai-memory run copilot` follow
- separately. (#1040)
+ `ai-memory run copilot` follows separately. (#1040)
+- Added `install-mcp --client copilot-cli`, which merges ai-memory's remote
+ entry (`type: "http"`, `url`, bearer `headers`, `tools: ["*"]`) into the root
+ `mcpServers` map of `$COPILOT_HOME/mcp-config.json` (default
+ `~/.copilot/mcp-config.json`), preserving other servers. `install-hooks
+ --agent copilot-cli` without `--server-url` now reads the server URL and
+ bearer back from that entry, and `uninstall` removes it. (#1040)
- Added `install-hooks --agent claude-code --scope project`, which writes the
hook configuration to the checkout's gitignored `.claude/settings.local.json`
(where Claude Code reads it: the git root, or the launch directory on
diff --git a/README.md b/README.md
index 1b346eeb..6de9ba6e 100644
--- a/README.md
+++ b/README.md
@@ -132,7 +132,7 @@ caveats is in [`docs/support-matrix.md`](docs/support-matrix.md).
| Kimi Code | Supported |
| Kiro CLI | Supported |
| Pool | Hooks-only |
-| GitHub Copilot CLI | Hooks-only |
+| GitHub Copilot CLI | Supported |
| VS Code Copilot | MCP-only |
| Zed | MCP-only |
| Muse Code | MCP-only |
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index ba5d267b..43454762 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -2495,6 +2495,14 @@ pub enum McpClient {
/// Command Code CLI — `~/.commandcode/mcp.json`.
#[value(alias = "commandcode", alias = "cmdc", alias = "cmd")]
CommandCode,
+ /// GitHub Copilot CLI — `$COPILOT_HOME/mcp-config.json` (default
+ /// `~/.copilot/mcp-config.json`), servers under the root `mcpServers` map
+ /// with `type: "http"` + `url` + optional `headers` (#1040). Pair with
+ /// `install-hooks --agent copilot-cli` for lifecycle capture. Not to be
+ /// confused with `vscode-copilot` (alias `copilot`), the VS Code agent
+ /// mode client.
+ #[value(name = "copilot-cli")]
+ CopilotCli,
/// Swival CLI — project-scoped `.swival/mcp.json` using native HTTP.
/// This integration is MCP-only; Swival's lifecycle callback does not
/// expose a stable session identifier for reliable capture correlation.
@@ -4196,6 +4204,20 @@ mod tests {
// `copilot` already means the VS Code MCP client on `install-mcp`;
// it must not silently select the CLI hook agent here.
assert!(Cli::try_parse_from(["ai-memory", "install-hooks", "--agent", "copilot"]).is_err());
+
+ let mcp = Cli::try_parse_from(["ai-memory", "install-mcp", "--client", "copilot-cli"])
+ .expect("install-mcp --client copilot-cli should parse");
+ let Command::InstallMcp(args) = mcp.command else {
+ panic!("expected install-mcp");
+ };
+ assert_eq!(args.client, McpClient::CopilotCli);
+ // ...while the bare word keeps selecting the VS Code client.
+ let vscode = Cli::try_parse_from(["ai-memory", "install-mcp", "--client", "copilot"])
+ .expect("install-mcp --client copilot should parse");
+ let Command::InstallMcp(args) = vscode.command else {
+ panic!("expected install-mcp");
+ };
+ assert_eq!(args.client, McpClient::VsCodeCopilot);
}
#[test]
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index fffec76c..b33e0d49 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -259,17 +259,13 @@ pub(crate) fn copilot_cli_hooks_path() -> anyhow::Result<std::path::PathBuf> {
copilot_cli_hooks_path_in(std::env::var_os("COPILOT_HOME"))
}
-/// The env value comes in as a parameter so tests can exercise both
-/// branches without mutating process env (mirrors [`codex_hooks_path_in`]).
+/// [`copilot_cli_hooks_path`] with the `COPILOT_HOME` value passed in. Resolves
+/// through the same config dir as `install-mcp --client copilot-cli`
+/// ([`install_mcp::copilot_home_in`]), so the two halves of one install agree.
fn copilot_cli_hooks_path_in(
env_override: Option<std::ffi::OsString>,
) -> anyhow::Result<std::path::PathBuf> {
- if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
- return Ok(dir.join("hooks").join("ai-memory.json"));
- }
- Ok(home_dir()
- .context("could not locate $HOME for ~/.copilot/hooks/ai-memory.json")?
- .join(".copilot")
+ Ok(install_mcp::copilot_home_in(env_override)?
.join("hooks")
.join("ai-memory.json"))
}
@@ -1433,7 +1429,7 @@ fn infer_installed_mcp_config(agent: AgentChoice) -> Result<Option<InferredMcpCo
// Codex uses `http_headers`; Grok uses `headers`. The shared TOML
// inferencer accepts both.
McpClient::Codex => Ok(infer_toml_mcp_config(&content)),
- McpClient::CommandCode => Ok(infer_json_mcp_config(
+ McpClient::CommandCode | McpClient::CopilotCli => Ok(infer_json_mcp_config(
&content,
&["mcpServers", "ai-memory"],
"url",
@@ -1588,9 +1584,7 @@ pub(crate) fn mcp_client_for_agent(agent: AgentChoice) -> Option<McpClient> {
// No first-party Hermes MCP installer ships yet, so there is no config
// file to infer a server URL or token from.
AgentChoice::Hermes => None,
- // `install-mcp --client copilot-cli` is tracked separately (#1040
- // PR2); until it lands there is no config file to scrape.
- AgentChoice::CopilotCli => None,
+ AgentChoice::CopilotCli => Some(McpClient::CopilotCli),
}
}
@@ -12024,6 +12018,28 @@ command = "AI_MEMORY_HOOK_URL=http://old:1 /old/ai-memory/hooks/kimi-code/sessio
);
}
+ /// `install-hooks --agent copilot-cli` without `--server-url` reads the
+ /// server URL and bearer back from an earlier `install-mcp --client
+ /// copilot-cli`, the same root `mcpServers.ai-memory.url` entry it wrote.
+ #[test]
+ fn copilot_cli_hooks_infer_the_copilot_cli_mcp_client() {
+ assert_eq!(
+ mcp_client_for_agent(AgentChoice::CopilotCli),
+ Some(McpClient::CopilotCli)
+ );
+ let inferred = infer_json_mcp_config(
+ r#"{"mcpServers":{"ai-memory":{"type":"http","url":"https://memory.example/mcp","headers":{"Authorization":"Bearer tok"},"tools":["*"]}}}"#,
+ &["mcpServers", "ai-memory"],
+ "url",
+ )
+ .unwrap();
+ assert_eq!(
+ inferred.hook_server_url.as_deref(),
+ Some("https://memory.example")
+ );
+ assert_eq!(inferred.auth_token.as_deref(), Some("tok"));
+ }
+
#[test]
fn kiro_cli_v3_apply_writes_documented_schema_and_is_idempotent() {
let hooks_tmp = TempDir::new().unwrap();
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index df1dca4a..446261eb 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -85,6 +85,7 @@ pub fn run(config: &Config, args: InstallMcpArgs) -> Result<()> {
McpClient::KimiCode => render_kimi_code(&args)?,
McpClient::KiroCli => render_kiro_cli(&args)?,
McpClient::CommandCode => render_command_code(&args)?,
+ McpClient::CopilotCli => render_copilot_cli(&args)?,
McpClient::Swival => render_swival(&args)?,
McpClient::VsCodeCopilot => render_vscode_copilot(&args)?,
McpClient::Zed => render_zed(&args)?,
@@ -165,7 +166,7 @@ pub(crate) fn mcp_config_path(client: crate::cli::McpClient) -> Result<PathBuf>
}
/// [`mcp_config_path`] with the relocation variables (`CLAUDE_CONFIG_DIR`,
-/// `CODEX_HOME`, `GROK_HOME`, `KIMI_CODE_HOME`, `KIRO_HOME`, and OMP's
+/// `CODEX_HOME`, `COPILOT_HOME`, `GROK_HOME`, `KIMI_CODE_HOME`, `KIRO_HOME`, and OMP's
/// `OMP_PROFILE`, `PI_PROFILE`, `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR`) read
/// through `env`,
/// so `ai-memory run --env` can point auto-wire at the same config home
@@ -261,6 +262,11 @@ pub(crate) fn mcp_config_path_with(
.join("settings")
.join("mcp.json"),
McpClient::CommandCode => home()?.join(".commandcode").join("mcp.json"),
+ // Copilot CLI keeps its whole config dir at $COPILOT_HOME when set,
+ // falling back to ~/.copilot; user-level MCP servers live in
+ // mcp-config.json there (project `.mcp.json` / `.github/mcp.json`
+ // files are left to `--config-file`).
+ McpClient::CopilotCli => copilot_home_in(env("COPILOT_HOME"))?.join("mcp-config.json"),
McpClient::Swival => {
let cwd = std::env::current_dir()
.context("could not resolve current dir for .swival/mcp.json default")?;
@@ -454,6 +460,20 @@ fn kiro_home(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
.join(".kiro"))
}
+/// GitHub Copilot CLI's configuration directory: `$COPILOT_HOME` when set and
+/// not blank, otherwise `~/.copilot`. It holds both `mcp-config.json` and the
+/// user-level `hooks/` directory, so `install-hooks --agent copilot-cli`
+/// resolves through here too. The override is injected to keep tests
+/// process-local.
+pub(crate) fn copilot_home_in(env_override: Option<std::ffi::OsString>) -> Result<PathBuf> {
+ if let Some(dir) = crate::commands::path_util::agent_config_home(env_override) {
+ return Ok(dir);
+ }
+ Ok(home_dir()
+ .context("could not locate $HOME for Copilot CLI configuration")?
+ .join(".copilot"))
+}
+
/// Resolve Grok Build CLI's user configuration root. Grok honours
/// `GROK_HOME`; otherwise it uses `~/.grok`.
pub(crate) fn grok_home() -> Result<PathBuf> {
@@ -604,6 +624,7 @@ fn json_mcp_location(client: McpClient) -> Option<JsonMcpLocation> {
| McpClient::KimiCode
| McpClient::KiroCli
| McpClient::CommandCode
+ | McpClient::CopilotCli
| McpClient::Swival => Some(JsonMcpLocation::RootMcpServers),
McpClient::OpenCode => Some(JsonMcpLocation::RootMcp),
// V2 nests servers under `mcp.servers` — the same shape OpenClaw,
@@ -920,6 +941,19 @@ fn build_mcp_entry(args: &InstallMcpArgs) -> Result<serde_json::Value> {
entry.insert("headers".into(), json!({"Authorization": b}));
}
}
+ McpClient::CopilotCli => {
+ // Copilot CLI's `mcp-config.json` remote entry: `type: "http"` +
+ // `url`, optional `headers`, and `tools`, written as `["*"]` (all
+ // tools — Copilot's documented default and its own example).
+ // Verified against
+ // https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.
+ entry.insert("type".into(), json!("http"));
+ entry.insert("url".into(), json!(server_url));
+ if let Some(b) = &bearer {
+ entry.insert("headers".into(), json!({"Authorization": b}));
+ }
+ entry.insert("tools".into(), json!(["*"]));
+ }
_ => bail!("internal: build_mcp_entry called for unsupported client"),
}
Ok(serde_json::Value::Object(entry))
@@ -1505,6 +1539,23 @@ fn render_command_code(args: &InstallMcpArgs) -> Result<String> {
))
}
+fn render_copilot_cli(args: &InstallMcpArgs) -> Result<String> {
+ Ok(format!(
+ "# GitHub Copilot CLI — merge into $COPILOT_HOME/mcp-config.json\n\
+ # (default ~/.copilot/mcp-config.json), or re-run with --apply to merge\n\
+ # it in place preserving other servers. Project-level `.mcp.json` and\n\
+ # `.github/mcp.json` also work: pass that path via --config-file.\n\
+ #\n\
+ # The equivalent CLI registration is:\n\
+ # copilot mcp add --transport http {name} {url}\n\
+ # Pair with `ai-memory install-hooks --agent copilot-cli` for capture.\n\
+ {snippet}\n",
+ name = args.name,
+ url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),
+ snippet = render_json_mcp_fragment(args)?,
+ ))
+}
+
fn render_swival(args: &InstallMcpArgs) -> Result<String> {
Ok(format!(
"# Swival CLI — merge into .swival/mcp.json in the project root
@@ -1755,6 +1806,7 @@ mod tests {
for (client, var, relative) in [
(McpClient::ClaudeCode, "CLAUDE_CONFIG_DIR", ".claude.json"),
(McpClient::Codex, "CODEX_HOME", "config.toml"),
+ (McpClient::CopilotCli, "COPILOT_HOME", "mcp-config.json"),
(McpClient::Grok, "GROK_HOME", "config.toml"),
(McpClient::KimiCode, "KIMI_CODE_HOME", "mcp.json"),
(McpClient::KiroCli, "KIRO_HOME", "settings/mcp.json"),
@@ -1943,6 +1995,45 @@ mod tests {
assert!(rendered.contains("`cmdc` is the native Windows executable"));
}
+ /// Copilot CLI's documented remote entry (#1040): root `mcpServers`,
+ /// `type: "http"` + `url` + `headers`, and `tools: ["*"]`.
+ #[test]
+ fn copilot_cli_renderer_uses_documented_http_schema() {
+ let fragment = render_json_mcp_fragment(&args_with_token(McpClient::CopilotCli)).unwrap();
+ let value: serde_json::Value = serde_json::from_str(&fragment).unwrap();
+
+ assert_eq!(
+ value,
+ json!({
+ "mcpServers": {
+ "ai-memory": {
+ "type": "http",
+ "url": "http://127.0.0.1:49374/mcp",
+ "headers": {
+ "Authorization": "Bearer test-token-deadbeef"
+ },
+ "tools": ["*"]
+ }
+ }
+ })
+ );
+ let rendered = render_copilot_cli(&args_for(McpClient::CopilotCli)).unwrap();
+ assert!(rendered.contains("mcp-config.json"));
+ assert!(rendered.contains("copilot mcp add --transport http ai-memory"));
+ assert!(rendered.contains("install-hooks --agent copilot-cli"));
+ }
+
+ #[test]
+ fn copilot_home_honours_env_override() {
+ assert_eq!(
+ copilot_home_in(Some("/tmp/custom-copilot-home".into())).unwrap(),
+ PathBuf::from("/tmp/custom-copilot-home")
+ );
+ let default = home_dir().unwrap().join(".copilot");
+ assert_eq!(copilot_home_in(Some("".into())).unwrap(), default);
+ assert_eq!(copilot_home_in(None).unwrap(), default);
+ }
+
#[test]
fn zed_apply_preserves_settings_and_siblings_and_is_idempotent() {
let tmp = tempfile::TempDir::new().unwrap();
@@ -2196,6 +2287,7 @@ mod tests {
McpClient::KimiCode => render_kimi_code(&args).unwrap(),
McpClient::KiroCli => render_kiro_cli(&args).unwrap(),
McpClient::CommandCode => render_command_code(&args).unwrap(),
+ McpClient::CopilotCli => render_copilot_cli(&args).unwrap(),
McpClient::Swival => render_swival(&args).unwrap(),
McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),
McpClient::Zed => render_zed(&args).unwrap(),
@@ -2225,6 +2317,7 @@ mod tests {
McpClient::KimiCode,
McpClient::KiroCli,
McpClient::CommandCode,
+ McpClient::CopilotCli,
McpClient::Swival,
McpClient::VsCodeCopilot,
McpClient::Zed,
@@ -2267,6 +2360,7 @@ mod tests {
McpClient::KimiCode,
McpClient::KiroCli,
McpClient::CommandCode,
+ McpClient::CopilotCli,
McpClient::Swival,
McpClient::VsCodeCopilot,
McpClient::Zed,
@@ -2303,6 +2397,7 @@ mod tests {
McpClient::KimiCode => render_kimi_code(&args).unwrap(),
McpClient::KiroCli => render_kiro_cli(&args).unwrap(),
McpClient::CommandCode => render_command_code(&args).unwrap(),
+ McpClient::CopilotCli => render_copilot_cli(&args).unwrap(),
McpClient::Swival => render_swival(&args).unwrap(),
McpClient::VsCodeCopilot => render_vscode_copilot(&args).unwrap(),
McpClient::Zed => render_zed(&args).unwrap(),
@@ -2781,6 +2876,41 @@ mod tests {
assert!(error.to_string().contains("requires HTTPS"), "{error:#}");
}
+ #[test]
+ fn copilot_cli_apply_preserves_siblings_and_is_idempotent() {
+ let tmp = tempfile::TempDir::new().unwrap();
+ let config_path = tmp.path().join("mcp-config.json");
+ fs::write(
+ &config_path,
+ r#"{"mcpServers":{"github":{"type":"http","url":"https://api.githubcopilot.com/mcp/"}}}"#,
+ )
+ .unwrap();
+ let mut args = args_with_token(McpClient::CopilotCli);
+ args.server_url = Some("https://memory.example/mcp".into());
+ args.config_file = Some(config_path.clone());
+
+ apply_to_config_file(&args).unwrap();
+ let first = fs::read_to_string(&config_path).unwrap();
+ apply_to_config_file(&args).unwrap();
+ let second = fs::read_to_string(&config_path).unwrap();
+
+ assert_eq!(first, second);
+ let value: serde_json::Value = serde_json::from_str(&second).unwrap();
+ assert_eq!(
+ value["mcpServers"]["github"]["url"],
+ "https://api.githubcopilot.com/mcp/"
+ );
+ let ours = &value["mcpServers"]["ai-memory"];
+ assert_eq!(ours["type"], "http");
+ // No default flavor: Copilot CLI fronts several model vendors.
+ assert_eq!(ours["url"], "https://memory.example/mcp");
+ assert_eq!(
+ ours["headers"]["Authorization"],
+ "Bearer test-token-deadbeef"
+ );
+ assert_eq!(ours["tools"], json!(["*"]));
+ }
+
#[test]
fn kiro_apply_preserves_siblings_and_is_idempotent() {
let tmp = tempfile::TempDir::new().unwrap();
diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rs
index 7f41de3c..87c9aa99 100644
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@ -410,6 +410,7 @@ fn build_plan(args: &UninstallArgs, data_dir: &Path) -> anyhow::Result<Vec<Plann
KimiCode,
KiroCli,
CommandCode,
+ CopilotCli,
Swival,
Muse,
] {
@@ -1246,6 +1247,7 @@ fn mcp_servers_path(client: McpClient) -> Option<&'static [&'static str]> {
| McpClient::KimiCode
| McpClient::KiroCli
| McpClient::CommandCode
+ | McpClient::CopilotCli
| McpClient::Swival
| McpClient::Devin => Some(&["mcpServers"]),
McpClient::OpenCode => Some(&["mcp"]),
@@ -2152,6 +2154,25 @@ mod tests {
assert!(v["servers"].get("other").is_some());
}
+ /// Copilot CLI keeps servers under the root `mcpServers` map; the strip
+ /// must remove only ai-memory's entry and leave e.g. a `github` server.
+ #[test]
+ fn strip_mcp_copilot_cli_root_mcp_servers() {
+ let content = r#"{"mcpServers":{"ai-memory":{"type":"http","url":"http://127.0.0.1:49374/mcp","tools":["*"]},"github":{"type":"http","url":"https://api.githubcopilot.com/mcp/"}}}"#;
+ let (out, removed) = strip_mcp_json(
+ content,
+ McpClient::CopilotCli,
+ Some("ai-memory"),
+ "http://127.0.0.1:49374/mcp",
+ )
+ .unwrap();
+
+ assert_eq!(removed, vec!["ai-memory".to_string()]);
+ let v: serde_json::Value = serde_json::from_str(&out).unwrap();
+ assert!(v["mcpServers"].get("ai-memory").is_none());
+ assert!(v["mcpServers"].get("github").is_some());
+ }
+
#[test]
fn strip_mcp_zed_context_servers_preserves_other_settings() {
let content = r#"{
diff --git a/docs/install.md b/docs/install.md
index 98934017..4310c583 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1303,17 +1303,24 @@ No first-party `install-mcp` client and no managed workstream
### GitHub Copilot CLI
-Copilot CLI loads user-level hook files from `~/.copilot/hooks/` (or
-`$COPILOT_HOME/hooks/`). `install-hooks --agent copilot-cli` writes
-`ai-memory.json` there — Copilot's standalone `{"version": 1, "hooks": {…}}`
-format — merging around any third-party entries already in the file:
+Copilot CLI keeps its config in `~/.copilot` (or `$COPILOT_HOME`).
+`install-mcp --client copilot-cli` merges the remote server entry into
+`mcp-config.json` there, and `install-hooks --agent copilot-cli` writes
+`hooks/ai-memory.json` — Copilot's standalone `{"version": 1, "hooks": {…}}`
+format — merging around any third-party entries already in each file:
```bash
+ai-memory install-mcp --client copilot-cli --apply \
+ --server-url "http://homelab:49374/mcp" \
+ --auth-token "$TOKEN"
ai-memory install-hooks --agent copilot-cli --apply \
--server-url "http://homelab:49374" \
--auth-token "$TOKEN"
```
+See [the MCP guide](mcp-install.md#github-copilot-cli) for the exact entry and
+the project-level `.mcp.json` / `.github/mcp.json` alternatives.
+
The events are configured with PascalCase names (`SessionStart`,
`PreToolUse`, …), which makes Copilot send the VS Code/Claude-compatible
snake_case payload (`session_id`, `cwd`, `tool_name`, `tool_input`,
@@ -1331,9 +1338,8 @@ not injected yet; recover it via MCP `memory_handoff_list` then
`memory_handoff_accept` with that `handoff_id`. There is no `--scope project`:
Copilot's repository hook files (`.github/hooks/*.json`) are shared with the
team and loaded by the Copilot cloud agent, so they cannot carry per-machine
-script paths. `install-mcp --client copilot-cli` and `ai-memory run copilot`
-are not shipped yet; `install-mcp --client copilot` remains the VS Code
-Copilot client.
+script paths. `ai-memory run copilot` is not shipped yet;
+`install-mcp --client copilot` remains the VS Code Copilot client.
### Hermes Agent (Nous Research)
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index d51fa13b..cdfd53fb 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -225,6 +225,62 @@ native HTTP or generated bridge paths.
---
+## GitHub Copilot CLI
+
+**Status:** MCP and lifecycle hooks are supported. Handoffs are not injected
+at `SessionStart` yet (see below), and there is no managed workstream
+(`ai-memory run copilot`).
+
+**Config files:** `$COPILOT_HOME/mcp-config.json` for MCP and
+`$COPILOT_HOME/hooks/ai-memory.json` for lifecycle hooks (`COPILOT_HOME`
+defaults to `~/.copilot`). Not to be confused with `--client vscode-copilot`
+(alias `copilot`), the VS Code agent-mode client below.
+
+```bash
+ai-memory install-mcp --client copilot-cli --apply \
+ --server-url "http://homelab:49374/mcp" --auth-token "$TOKEN"
+ai-memory install-hooks --agent copilot-cli --apply \
+ --server-url "http://homelab:49374" --auth-token "$TOKEN"
+```
+
+The MCP installer merges the documented remote entry into the root
+`mcpServers` map, preserving other servers (including your own `github`
+entry):
+
+```json
+{
+ "mcpServers": {
+ "ai-memory": {
+ "type": "http",
+ "url": "http://homelab:49374/mcp",
+ "headers": { "Authorization": "Bearer <token>" },
+ "tools": ["*"]
+ }
+ }
+}
+```
+
+The equivalent interactive registration is `copilot mcp add --transport http
+ai-memory http://homelab:49374/mcp` (add `--header "Authorization: Bearer
+<token>"` when bearer auth is on). Copilot also reads project-level
+`.mcp.json` and `.github/mcp.json` files; pass that path via `--config-file` to
+write one, keeping in mind that `.github/mcp.json` is meant to be committed,
+so it should not carry a bearer token. `install-hooks --agent copilot-cli`
+run without `--server-url` reads the URL and token back from this entry.
+
+The hook installer wires Claude Code's nine events plus `PostToolUseFailure`
+with PascalCase names, which makes Copilot send its VS Code/Claude-compatible
+payload; native installs spool events locally and enforce capture exclusions.
+Copilot reads a top-level `additionalContext` from `SessionStart` stdout, not
+the `hookSpecificOutput` envelope ai-memory prints, so the prior session's
+handoff is recovered with `memory_handoff_list` and `memory_handoff_accept`.
+
+- Sources: <https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers>,
+ <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference>,
+ <https://docs.github.com/en/copilot/reference/hooks-reference>
+
+---
+
## VS Code GitHub Copilot
**Status:** ✅ MCP supported (workspace-default). ❌ No lifecycle hooks
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index c25865df..78ce3706 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -34,7 +34,7 @@
| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. |
| Kiro CLI | Supported | MCP config uses `install-mcp --client kiro-cli` (alias `kiro`) and Kiro's Bedrock-compatible schema flavor. `install-hooks --agent kiro-cli` merges v2 hooks into existing agent configs; the explicit `--agent kiro-cli-v3` target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor `$KIRO_HOME`, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use `ai-memory finalize-session --agent kiro-cli`, with `--session-id <uuid>` for concurrent sessions, unless it is an interactive session launched with `ai-memory run kiro`, which finalizes it automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |
| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing committed project files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. |
-| GitHub Copilot CLI | Hooks-only | `install-hooks --agent copilot-cli` writes lifecycle hooks to `$COPILOT_HOME/hooks/ai-memory.json` (default `~/.copilot/hooks/ai-memory.json`). Configured with PascalCase event names, so Copilot sends the VS Code/Claude-compatible payload (`session_id`, `cwd`, `tool_name`, `tool_input`, `tool_result`) and native commands enforce capture exclusions; 10 events, Claude Code's nine plus `PostToolUseFailure`. Entries are flat with no `matcher`, because Copilot rejects it on `SessionStart`/`Stop`/`SessionEnd` and subagent events. Copilot reads a top-level `additionalContext` on `SessionStart` rather than Claude Code's envelope, so capture works but handoff injection does not yet — recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. No `--scope project`: Copilot's repository hook files (`.github/hooks/*.json`) are shared with the team and the cloud agent, so they cannot carry per-machine script paths. `install-mcp --client copilot-cli` and `ai-memory run copilot` are follow-ups (#1040). The bare `--client copilot` alias keeps meaning VS Code Copilot. |
+| GitHub Copilot CLI | Supported | MCP config (`install-mcp --client copilot-cli` → `$COPILOT_HOME/mcp-config.json`, root `mcpServers`, `type: "http"`) + lifecycle hooks: `install-hooks --agent copilot-cli` writes `$COPILOT_HOME/hooks/ai-memory.json` (`COPILOT_HOME` defaults to `~/.copilot`). Configured with PascalCase event names, so Copilot sends the VS Code/Claude-compatible payload (`session_id`, `cwd`, `tool_name`, `tool_input`, `tool_result`) and native commands enforce capture exclusions; 10 events, Claude Code's nine plus `PostToolUseFailure`. Entries are flat with no `matcher`, because Copilot rejects it on `SessionStart`/`Stop`/`SessionEnd` and subagent events. Copilot reads a top-level `additionalContext` on `SessionStart` rather than Claude Code's envelope, so capture works but handoff injection does not yet — recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. No `--scope project`: Copilot's repository hook files (`.github/hooks/*.json`) are shared with the team and the cloud agent, so they cannot carry per-machine script paths. `ai-memory run copilot` is a follow-up (#1040). The bare `--client copilot` alias keeps meaning VS Code Copilot. |
| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
| Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. |
| Muse Code | MCP-only | `install-mcp --client muse` merges a native streamable-HTTP entry with bearer `headers` into the snake_case `mcp_servers` map of `~/.config/muse/settings.json`, preserving sibling servers. The writer adds the mandatory `"schema_version": 1` when absent (without it every `muse` command fails at startup) and never rewrites an existing value, and it sets `"mode": "optional"` because Muse's default `required` aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads `~/.agents/skills`, which `install-skills` already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its `SessionStart` event is not specified. |