From bb89ab806aabe0a0aa27004bfd6ce7eee381081a Mon Sep 17 00:00:00 2001 From: Patrick szymkowiak Date: Wed, 25 Mar 2026 19:16:20 +0100 Subject: [PATCH] feat: add Copilot/Windsurf CLI instructions + integration docs - Add .github/copilot-instructions.md (auto-loaded by GitHub Copilot) - Add Copilot and Windsurf to `icm init --mode cli` instruction injection - Add comprehensive docs/integrations.md with setup guide for all 14 tools - Update README with CLI instructions section and link to integration guide --- .github/copilot-instructions.md | 32 ++++ README.md | 19 ++- crates/icm-cli/src/main.rs | 2 + docs/integrations.md | 284 ++++++++++++++++++++++++++++++++ 4 files changed, 336 insertions(+), 1 deletion(-) create mode 100644 .github/copilot-instructions.md create mode 100644 docs/integrations.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..bfce09a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,32 @@ +# ICM — Persistent Memory for AI Agents + +This project uses [ICM](https://github.com/rtk-ai/icm) for persistent memory across sessions. + +## Recall (before starting work) + +Search for relevant past context before each task: + +```bash +icm recall "query" # search memories +icm recall "query" -t "topic-name" # filter by topic +``` + +## Store (MANDATORY triggers) + +You MUST call `icm store` when ANY of the following happens: + +1. **Error resolved** → `icm store -t errors-resolved -c "description" -i high -k "keyword1,keyword2"` +2. **Architecture/design decision** → `icm store -t decisions-{project} -c "description" -i high` +3. **User preference discovered** → `icm store -t preferences -c "description" -i critical` +4. **Significant task completed** → `icm store -t context-{project} -c "summary" -i high` + +Do this BEFORE responding to the user. Not optional. + +## Other commands + +```bash +icm topics # list all topics +icm health # topic hygiene audit +icm update -c "updated content" # edit memory in-place +icm forget # delete a memory +``` diff --git a/README.md b/README.md index beb3692..5fe697e 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ cargo install --path crates/icm-cli icm init ``` -Configures **14 tools** in one command: +Configures **14 tools** in one command ([full integration guide](docs/integrations.md)): | Tool | Config file | Format | |------|------------|--------| @@ -106,6 +106,22 @@ icm init --mode skill Installs slash commands and rules for Claude Code (`/recall`, `/remember`), Cursor (`.mdc` rule), Roo Code (`.md` rule), and Amp (`/icm-recall`, `/icm-remember`). +### CLI instructions + +```bash +icm init --mode cli +``` + +Injects ICM instructions into each tool's instruction file: + +| Tool | File | +|------|------| +| Claude Code | `CLAUDE.md` | +| GitHub Copilot | `.github/copilot-instructions.md` | +| Windsurf | `.windsurfrules` | +| OpenAI Codex | `AGENTS.md` | +| Gemini | `~/.gemini/GEMINI.md` | + ### Hooks (Claude Code) ```bash @@ -470,6 +486,7 @@ All benchmarks use **real API calls** — no mocks, no simulated responses, no c | Document | Description | |----------|-------------| +| [Integration Guide](docs/integrations.md) | Setup for all 14 tools: Claude Code, Copilot, Cursor, Windsurf, Zed, Amp, etc. | | [Technical Architecture](docs/architecture.md) | Crate structure, search pipeline, decay model, sqlite-vec integration, testing | | [User Guide](docs/guide.md) | Installation, topic organization, consolidation, extraction, troubleshooting | | [Product Overview](docs/product.md) | Use cases, benchmarks, comparison with alternatives | diff --git a/crates/icm-cli/src/main.rs b/crates/icm-cli/src/main.rs index ccf1a3f..8c65d03 100644 --- a/crates/icm-cli/src/main.rs +++ b/crates/icm-cli/src/main.rs @@ -1703,6 +1703,8 @@ icm topics # list all topics\n\ ("Claude Code", cwd.join("CLAUDE.md")), ("Codex", cwd.join("AGENTS.md")), ("Gemini", PathBuf::from(&home).join(".gemini/GEMINI.md")), + ("Copilot", cwd.join(".github/copilot-instructions.md")), + ("Windsurf", cwd.join(".windsurfrules")), ]; for (tool_name, path) in &instruction_files { diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 0000000..0093f13 --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,284 @@ +# ICM Integrations + +ICM integrates with **16 AI tools** across 4 integration modes: MCP server, CLI instructions, skills/rules, and hooks. + +## Quick Setup + +```bash +# Install everything for all detected tools +icm init --mode all + +# Or pick a specific mode +icm init --mode mcp # MCP server configs (default) +icm init --mode cli # Inject instructions into CLAUDE.md, AGENTS.md, etc. +icm init --mode skill # Slash commands & rules +icm init --mode hook # Claude Code hooks + OpenCode plugin +``` + +## Supported Tools + +### Editors & IDEs + +#### Claude Code + +```bash +# Option 1: MCP (recommended) +claude mcp add icm -- icm serve + +# Option 2: Full setup (MCP + hooks + skills) +icm init --mode all +``` + +**Config:** `~/.claude.json` → `mcpServers.icm` + +**Hooks (optional):** + +| Hook | Event | What it does | +|------|-------|-------------| +| `icm hook pre` | PreToolUse | Auto-allow `icm` commands | +| `icm hook post` | PostToolUse | Extract facts every 15 calls | +| `icm hook compact` | PreCompact | Extract before context compression | +| `icm hook prompt` | UserPromptSubmit | Inject recalled context | + +**Skills:** `/recall`, `/remember` slash commands. + +--- + +#### Claude Desktop + +```bash +icm init --mode mcp +``` + +**Config:** `~/Library/Application Support/Claude/claude_desktop_config.json` → `mcpServers.icm` + +--- + +#### Cursor + +```bash +icm init --mode mcp +icm init --mode skill # Installs ~/.cursor/rules/icm.mdc +``` + +**MCP Config:** `~/.cursor/mcp.json` → `mcpServers.icm` + +**Rule file:** `~/.cursor/rules/icm.mdc` — Always-on rule that instructs Cursor to use ICM for persistent memory. + +--- + +#### Windsurf + +```bash +icm init --mode mcp # MCP server +icm init --mode cli # Injects instructions into .windsurfrules +``` + +**MCP Config:** `~/.codeium/windsurf/mcp_config.json` → `mcpServers.icm` + +**Rules:** `.windsurfrules` in project root — project-scoped instructions. + +--- + +#### VS Code / GitHub Copilot + +```bash +icm init --mode mcp # MCP server for VS Code +icm init --mode cli # Injects instructions into .github/copilot-instructions.md +``` + +**MCP Config:** `~/Library/Application Support/Code/User/mcp.json` → `servers.icm` + +> Note: VS Code uses `"servers"` as the JSON key, not `"mcpServers"`. + +**Copilot instructions:** `.github/copilot-instructions.md` — automatically loaded by GitHub Copilot at session start. Contains ICM recall/store instructions. + +--- + +#### Zed + +```bash +icm init --mode mcp +``` + +**Config:** `~/.zed/settings.json` → `context_servers.icm` + +Zed uses a nested format: +```json +{ + "context_servers": { + "icm": { + "command": { "path": "/path/to/icm", "args": ["serve"] } + } + } +} +``` + +--- + +### Terminal Tools + +#### Amp + +```bash +icm init --mode mcp +icm init --mode skill # Installs /icm-recall and /icm-remember +``` + +**Config:** `~/.config/amp/settings.json` → `amp.mcpServers.icm` + +**Skills:** `~/.config/amp/skills/icm-recall.md`, `icm-remember.md` + +--- + +#### Amazon Q + +```bash +icm init --mode mcp +``` + +**Config:** `~/.aws/amazonq/mcp.json` → `mcpServers.icm` + +--- + +#### OpenAI Codex CLI + +```bash +icm init --mode mcp # TOML config +icm init --mode cli # Injects into AGENTS.md +``` + +**Config:** `~/.codex/config.toml` + +```toml +[mcp_servers.icm] +command = "/path/to/icm" +args = ["serve"] +``` + +**Instructions:** `AGENTS.md` in project root. + +--- + +#### Gemini Code Assist + +```bash +icm init --mode mcp +icm init --mode cli # Injects into ~/.gemini/GEMINI.md +``` + +**Config:** `~/.gemini/settings.json` → `mcpServers.icm` + +**Instructions:** `~/.gemini/GEMINI.md` + +--- + +#### OpenCode + +```bash +icm init --mode mcp # MCP server config +icm init --mode hook # Installs JS plugin with hooks +``` + +**MCP Config:** `~/.config/opencode/opencode.json` → `mcp.icm` + +**Plugin:** `~/.config/opencode/plugins/icm.js` + +| Event | What it does | +|-------|-------------| +| `tool.execute.after` | Extract facts from tool output | +| `experimental.session.compacting` | Extract before context compression | +| `session.created` | Recall context at session start | + +--- + +### VS Code Extensions + +#### Cline + +```bash +icm init --mode mcp +``` + +**Config:** `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` + +--- + +#### Roo Code + +```bash +icm init --mode mcp +icm init --mode skill # Installs ~/.roo/rules/icm.md +``` + +**Config:** `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` + +**Rule:** `~/.roo/rules/icm.md` + +--- + +#### Kilo Code + +```bash +icm init --mode mcp +``` + +**Config:** `~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json` + +--- + +## Integration Modes Summary + +| Mode | What it does | Tools | +|------|-------------|-------| +| `mcp` | Configures MCP server in each tool's config | All 14 tools | +| `cli` | Injects ICM instructions into instruction files | Claude Code, Codex, Gemini, Copilot, Windsurf | +| `skill` | Creates slash commands and rule files | Claude Code, Cursor, Roo Code, Amp | +| `hook` | Installs hooks/plugins for automatic extraction | Claude Code (4 hooks), OpenCode (JS plugin) | + +## Manual Setup + +For any MCP-compatible tool not listed above: + +```json +{ + "command": "icm", + "args": ["serve"], + "env": {} +} +``` + +Or with compact mode (shorter responses, fewer tokens): + +```json +{ + "command": "icm", + "args": ["serve", "--compact"], + "env": {} +} +``` + +## MCP Tools Available + +When connected via MCP, these 18 tools are available: + +| Tool | Description | +|------|-------------| +| `icm_memory_store` | Store a memory | +| `icm_memory_recall` | Search memories (hybrid: FTS + vector) | +| `icm_memory_update` | Update an existing memory | +| `icm_memory_forget` | Delete a memory | +| `icm_memory_consolidate` | Merge topic memories into one | +| `icm_memory_health` | Topic hygiene audit | +| `icm_memory_embed_all` | Generate embeddings for all memories | +| `icm_memory_extract_patterns` | Detect recurring patterns | +| `icm_memory_list_topics` | List all topics with stats | +| `icm_memory_stats` | Global statistics | +| `icm_memoir_create` | Create a knowledge graph | +| `icm_memoir_show` | Display memoir structure | +| `icm_memoir_add_concept` | Add concept to memoir | +| `icm_memoir_link` | Link concepts | +| `icm_memoir_search` | Search within a memoir | +| `icm_memoir_search_all` | Search across all memoirs | +| `icm_feedback_record` | Record a correction | +| `icm_feedback_search` | Search past corrections |