@contextstream/mcp-server 0.4.80 → 0.4.82

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +173 -183
  2. package/dist/hooks/auto-rules.js +162 -17
  3. package/dist/hooks/post-write.js +703 -28
  4. package/dist/hooks/runner.js +871 -147
  5. package/dist/hooks/session-init.js +37 -3
  6. package/dist/hooks/user-prompt-submit.js +11 -4
  7. package/dist/index.js +24163 -23400
  8. package/package.json +24 -7
package/README.md CHANGED
@@ -1,142 +1,194 @@
1
1
  <p align="center">
2
- <img src="https://contextstream.io/400logo.png" alt="ContextStream" width="80" />
2
+ <img src="https://contextstream.io/400logo.png" alt="ContextStream — persistent memory and semantic code search for AI coding assistants" width="80" />
3
3
  </p>
4
4
 
5
5
  <h1 align="center">ContextStream MCP Server</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>Give your AI coding assistant brilliant memory, deep context, and superpowers it never had.</strong>
8
+ <strong>Persistent memory, semantic code search, and team context for Claude Code, Cursor, VS Code Copilot, Windsurf — and every MCP-compatible AI coding assistant.</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ 🏆 <b>90.0% on LongMemEval-S</b> — the full 500-instance suite with the official judge.<br/>
13
+ Beats supermemory with statistical significance; matches Zep. <a href="https://contextstream.io/benchmarks">See the benchmarks →</a>
9
14
  </p>
10
15
 
11
16
  <p align="center">
12
17
  <a href="https://www.npmjs.com/package/@contextstream/mcp-server"><img src="https://img.shields.io/npm/v/@contextstream/mcp-server.svg" alt="npm version" /></a>
13
- <a href="https://www.npmjs.com/package/@contextstream/mcp-server"><img src="https://img.shields.io/npm/dm/@contextstream/mcp-server.svg" alt="downloads" /></a>
14
- <a href="https://github.com/contextstream/mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@contextstream/mcp-server.svg" alt="license" /></a>
18
+ <a href="https://www.npmjs.com/package/@contextstream/mcp-server"><img src="https://img.shields.io/npm/dm/@contextstream/mcp-server.svg" alt="npm downloads" /></a>
19
+ <a href="https://github.com/contextstream/mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@contextstream/mcp-server.svg" alt="MIT license" /></a>
20
+ <img src="https://img.shields.io/node/v/@contextstream/mcp-server.svg" alt="node version" />
15
21
  </p>
16
22
 
17
23
  <p align="center">
18
24
  <a href="https://contextstream.io/docs">Documentation</a> •
19
- <a href="https://contextstream.io/pricing">Pricing</a>
25
+ <a href="https://contextstream.io/pricing">Pricing</a> •
26
+ <a href="#faq">FAQ</a>
20
27
  </p>
21
28
 
22
29
  ---
23
30
 
24
- <div align="center">
31
+ ## Try it in 30 seconds
25
32
 
26
33
  ```bash
27
34
  npx --prefer-online -y @contextstream/mcp-server@latest setup
28
35
  ```
29
36
 
30
- </div>
37
+ That one command detects your AI editors, writes their MCP configs and rules, installs lifecycle hooks where supported, indexes your project in the background, and **verifies everything it just did** — then you restart your editor and your AI has memory. Free tier available.
38
+
39
+ Automating it? Zero-prompt mode takes every default:
40
+
41
+ ```bash
42
+ npx --prefer-online -y @contextstream/mcp-server@latest setup --yes
43
+ ```
31
44
 
32
45
  <p align="center">
33
- <img src="compare1.gif" alt="ContextStream in action" width="700" />
46
+ <img src="contextstream-mcp-comparison.gif" alt="Animated comparison of an AI coding assistant working without ContextStream versus with ContextStream project memory, search, and graph context" width="600" />
34
47
  </p>
35
48
 
36
49
  ---
37
50
 
38
- ## Get Started (VS Code + Copilot)
51
+ ## We win on memory benchmarks — measured honestly
39
52
 
40
- ### Option 1: Rust MCP (recommended)
53
+ **ContextStream scores 90.0% on the full LongMemEval-S benchmark**, the standard test of conversational memory over ~115k-token multi-session histories. That's the complete 500-instance suite with the official GPT-4o judge — 450/500 correct (89.6% single-shot, 90.0% with self-consistency k=3; Wilson 95% CI [87.1%, 92.3%]). Published June 14, 2026.
41
54
 
42
- ```bash
43
- curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
44
- ```
55
+ | System | LongMemEval-S | Notes |
56
+ |---|:---:|---|
57
+ | **ContextStream** | **90.0%** | Full 500 instances, official GPT-4o judge |
58
+ | Zep | 90.2% | Vendor-published — a statistical tie (0.2 pt is inside measurement noise) |
59
+ | supermemory | 85.4% | Vendor-published — ContextStream wins with statistical significance |
45
60
 
46
- ```powershell
47
- irm https://contextstream.io/scripts/mcp.ps1 | iex
48
- ```
61
+ On **multi-session recall** — the memory that actually matters for a coding agent working across days of sessions — ContextStream scores **81.2% vs Zep's published 57.9%** in the per-family comparison. And on the agentic project-memory benchmark, the same memory raises **agent task success from 58% to 96%**.
49
62
 
50
- Then run:
63
+ Full methodology, per-family breakdowns, and judge-comparability notes (competitor numbers are cited from each vendor's own publications): **[contextstream.io/benchmarks](https://contextstream.io/benchmarks)**
51
64
 
52
- ```bash
53
- contextstream-mcp setup
54
- ```
55
-
56
- ### Option 2: Node MCP
65
+ ---
57
66
 
58
- ```bash
59
- npx --prefer-online -y @contextstream/mcp-server@latest setup
60
- ```
67
+ ## What is ContextStream?
61
68
 
62
- After setup, restart VS Code/Copilot.
69
+ **ContextStream is a Model Context Protocol (MCP) server that gives AI coding assistants long-term memory and deep codebase understanding.** It indexes your code for semantic search, records your decisions, lessons, and plans across sessions, maps your dependency graph, and pulls in team knowledge from GitHub, Slack, and Notion — then delivers exactly the right slice of all that to your AI on every message.
63
70
 
64
- **Works with:** Claude Code • Cursor • VS Code • Claude Desktop • Codex CLI • OpenCode • Antigravity
71
+ It works with any MCP client: Claude Code, Cursor, VS Code + GitHub Copilot, Windsurf, Cline, Roo Code, Kilo Code, Codex CLI, OpenCode, Aider, Antigravity, and Claude Desktop.
65
72
 
66
73
  ---
67
74
 
68
- ## This Isn't Just Memory. This Is Intelligence.
75
+ ## Which ContextStream runtime am I using?
69
76
 
70
- Other tools give your AI a notepad. **ContextStream gives it a brain.**
77
+ ContextStream has independent release lines. A `0.5.x` hosted version and a `0.4.x` npm version are different runtimes, not evidence that either updater is broken.
71
78
 
72
- Your AI doesn't just remember things—it *understands* your entire codebase, learns from every conversation, pulls knowledge from your team's GitHub, Slack, and Notion, and delivers exactly the right context at exactly the right moment.
79
+ | Runtime | How to identify it | Version line | Canonical release metadata and notes |
80
+ |---|---|---|---|
81
+ | **Hosted MCP** | Your editor config uses `https://mcp.contextstream.io/mcp`. `help(action="version")` reports `runtime_type: rust-mcp`. | Rust MCP `0.5.x` | `help(action="version")` returns release notes inline when published and links the [machine-readable R2 manifest](https://pub-68429b9f7857416c9484b75bf1887b96.r2.dev/mcp/latest/version.json). |
82
+ | **Installed Rust MCP** | Your editor launches a `contextstream-mcp` binary installed by `https://contextstream.io/scripts/mcp.sh`; run `contextstream-mcp --version`. | Rust MCP `0.5.x` | The same [machine-readable R2 manifest](https://pub-68429b9f7857416c9484b75bf1887b96.r2.dev/mcp/latest/version.json); `help(action="version")` maps this runtime to that manifest. |
83
+ | **Legacy npm MCP (this repository)** | Your editor launches `npx ... @contextstream/mcp-server` or a global npm install. `help(action="version")` reports `runtime_type: legacy-typescript-mcp`; `npm list -g @contextstream/mcp-server` shows the installed package. | TypeScript MCP `0.4.x` | [GitHub releases](https://github.com/contextstream/mcp-server/releases) and this repository's [CHANGELOG.md](CHANGELOG.md). |
84
+ | **ContextStream Desktop** | Check the app's About/update UI. Desktop may run the local sync bridge, but that does not change the MCP runtime configured in your editor. | Desktop `0.3.x` (independent) | The in-app updater and the public [Desktop version JSON](https://api.contextstream.io/api/v1/desktop/version), which includes `release_notes` and platform downloads. |
73
85
 
74
- **One setup. Instant transformation.**
86
+ The `version` reported by `help(action="version")` is always the MCP process serving that tool call. Desktop's version is separate, even when Desktop added or indexed the local repository.
75
87
 
76
88
  ---
77
89
 
78
- ## What Changes When You Install This
90
+ ## Why do AI coding assistants forget everything?
91
+
92
+ Because every conversation starts from zero. Your AI re-reads the same files, re-derives the same architecture, repeats last week's mistake, and loses the thread the moment the context window compacts. ContextStream fixes the whole class of problem:
79
93
 
80
- | Before | After |
94
+ | Without ContextStream | With ContextStream |
81
95
  |--------|-------|
82
- | AI searches files one-by-one, burning tokens | **Semantic search** finds code by meaning in milliseconds |
83
- | Context lost when conversations get long | **Smart compression** preserves what matters before compaction |
84
- | Team knowledge scattered across tools | **Unified intelligence** from GitHub, Slack, Notion—automatically |
85
- | Same mistakes repeated across sessions | **Lessons system** ensures your AI learns from every failure |
86
- | Generic responses, no project awareness | **Deep context** about your architecture, decisions, patterns |
96
+ | AI greps files one-by-one, burning tokens | **Semantic code search** finds code by meaning in milliseconds |
97
+ | Context lost when conversations get long | **Pre-compaction capture** saves critical state before it's gone — and restores it after |
98
+ | Same mistakes repeated across sessions | **Lessons system** surfaces past failures *before* your AI repeats them |
99
+ | "Why did we choose X?" — nobody remembers | **Decisions and plans** persist and resurface when relevant |
100
+ | Team knowledge scattered across tools | **GitHub, Slack, and Notion knowledge**, queried automatically |
101
+ | Generic answers with no project awareness | **Workspace context** on every single message |
87
102
 
88
103
  ---
89
104
 
90
- ## The Power Under the Hood
105
+ ## What your AI can do after setup
91
106
 
92
- ### Semantic Code Intelligence
93
- Ask "where do we handle authentication?" and get the answer instantly. No grep chains. No reading 10 files. Your AI understands your code at a conceptual level.
107
+ ### 🔍 Find code by meaning, not keywords
108
+ Ask *"where do we handle authentication?"* and get ranked, snippet-level answers instantly. Hybrid semantic + keyword search with exact-token fusion, so a symbol lookup like `resolveWriteScope` lands the definition — not lookalikes. Search works the moment setup finishes: keyword results come back immediately while the semantic index builds in the background.
94
109
 
95
- ### SmartRouter Context Delivery
96
- Every message is analyzed. Risky refactor? Relevant lessons surface automatically. Making a decision? Your AI knows to capture it. The right context, every time, without you asking.
110
+ ### 🧠 Remember everything that matters
111
+ Decisions, lessons, preferences, plans, tasks, docs, runbooks — captured during work and surfaced automatically on later turns, in later sessions, even after context compaction. Every prior session's transcript is indexed and queryable: *"what did we decide about the id format last week?"* just works.
97
112
 
98
- ### Team Knowledge Fusion
99
- Connect GitHub, Slack, and Notion. Discussions from months ago? Surfaced when relevant. That architecture decision buried in a PR comment? Your AI knows about it.
113
+ ### 💬 Ask the workspace when stuck
114
+ The built-in **Agent Q&A** tool lets your AI ask your workspace's knowledge base — prior decisions, conventions, runbooks, guardrails — and get a grounded answer with citations for every claim.
100
115
 
101
- ### Code Graph Analysis
102
- "What depends on UserService?" "What's the impact of changing this function?" Your AI sees the connections across your entire codebase.
116
+ ### 🕸️ See the whole graph
117
+ *"What depends on `UserService`?" "What breaks if I change this function?"* Dependency mapping, impact analysis, circular-dependency and dead-code detection over your whole codebase.
103
118
 
104
- ### Context Pressure Awareness
105
- Long conversation? ContextStream tracks token usage, auto-saves critical state, and ensures nothing important is lost when context compacts.
119
+ ### 📦 Hand off context between agents
120
+ **ContextCapsule** packages project state into a portable, shareable snapshot — bootstrap a fresh agent, hand off to a teammate, or share a token-gated link with an external agent.
121
+
122
+ ### 🛡️ Survive long sessions
123
+ Token pressure is tracked continuously (with thresholds sized to your model's context window). Before compaction hits, critical state is checkpointed; after it, context restores.
106
124
 
107
125
  ---
108
126
 
109
- ## The Tools Your AI Gets
127
+ ## Which AI editors and agents does it support?
128
+
129
+ | Editor / Agent | Managed rules | MCP config | Lifecycle hooks |
130
+ |---|:---:|:---:|:---:|
131
+ | Claude Code | ✅ | ✅ | ✅ |
132
+ | Cursor | ✅ (`.cursor/rules/*.mdc`) | ✅ | ✅ |
133
+ | Windsurf | ✅ | ✅ | ✅ |
134
+ | Cline | ✅ | ✅ | ✅ |
135
+ | Roo Code | ✅ | ✅ | ✅ |
136
+ | Kilo Code | ✅ | ✅ | rules-based |
137
+ | VS Code + GitHub Copilot | ✅ | ✅ (incl. hosted OAuth) | rules-based |
138
+ | Codex CLI | ✅ | ✅ | rules-based |
139
+ | OpenCode | ✅ | ✅ | rules-based |
140
+ | Aider | ✅ | ✅ | rules-based |
141
+ | Antigravity | ✅ | ✅ | rules-based |
142
+ | Claude Desktop | — | ✅ | — |
143
+
144
+ Anything that speaks the Model Context Protocol can connect — the table just shows what the setup wizard configures automatically.
110
145
 
111
- ```
112
- init → Loads your workspace context instantly
113
- context → Delivers relevant context every single message
114
- search → Semantic, hybrid, keyword—find anything by meaning
115
- session → Captures decisions, preferences, lessons automatically
116
- memory → Builds a knowledge graph of your project
117
- graph → Maps dependencies and analyzes impact
118
- project → Indexes your codebase for semantic understanding
119
- media → Index and search video, audio, images (great for Remotion)
120
- integration → Queries GitHub, Slack, Notion directly
121
- ```
146
+ ---
147
+
148
+ ## Tools
122
149
 
123
- Your AI uses these automatically. You just code.
150
+ 36 tools in the default surface, organized as consolidated domains so they cost ~75% fewer tokens than individual registrations. The tools your AI gets:
151
+
152
+ - **init** / **context** — workspace state + the right context on every message
153
+ - **search** — semantic, hybrid, keyword, pattern, exhaustive, refactor modes
154
+ - **memory** — events, decisions, docs, runbooks, tasks, todos, diagrams, transcripts
155
+ - **session** — capture decisions & lessons, recall past sessions, plans, retroactive capture
156
+ - **qa** — grounded Q&A over your workspace knowledge base, with citations
157
+ - **graph** — dependencies, impact analysis, circular deps, unused code
158
+ - **capsule** — portable, shareable context snapshots for agent handoffs
159
+ - **entity** — tickets, incidents, releases, sprints, OKRs, risks
160
+ - **project** / **workspace** — project indexing, scope, and workspace management
161
+ - **skill** — reusable instruction + action bundles, portable across tools
162
+ - **media** — index and search images, video, audio, and documents
163
+ - **vcs** / **reminder** / **integration** / **help** — repo links, reminders, integrations, diagnostics
164
+
165
+ Plus focused write tools (`capture_plan`, `memory_create_doc`, `session_capture_lesson`, …) so agents that display tool names show *what* they're doing. Your AI uses all of this automatically — you just code.
166
+
167
+ ### Daily Recaps
168
+
169
+ Daily Recaps are generated around **23:00 in your configured timezone** when there is enough activity. They are not triggered by closing an editor, changing an MCP `session_id`, or starting a new chat, so long-lived VS Code/Copilot connections do not suppress the nightly job.
170
+
171
+ - `session(action="list_recaps", workspace_id="<uuid>", limit=30)` lists completed recaps newest-first with `recap_date` and `generated_at` timestamps.
172
+ - `session(action="trigger_recap", workspace_id="<uuid>")` queues an asynchronous manual recap. Call `list_recaps` afterward to verify completion.
173
+
174
+ These actions use the same recap history and generation service as the dashboard.
124
175
 
125
176
  ---
126
177
 
127
- ## Global Fallback Workspace (Unmapped Folders)
178
+ ## CLI commands
128
179
 
129
- ContextStream now supports a catch-all mode for random folders (for example `~` or ad-hoc dirs) that are not associated with a project/workspace yet.
180
+ ```bash
181
+ contextstream-mcp setup # interactive onboarding wizard
182
+ contextstream-mcp setup --yes # zero-prompt setup with sane defaults (great for CI/dotfiles)
183
+ contextstream-mcp doctor # ✓/✗ diagnostics: auth, scope, index health, rules, hooks
184
+ contextstream-mcp index [path] # index a project folder on demand
185
+ ```
130
186
 
131
- - `init(...)` resolves normal folder mappings first (`.contextstream/config.json`, parent/global mappings).
132
- - If no mapping exists, it uses a single hidden global fallback workspace (`.contextstream-global`) in workspace-only mode.
133
- - Context/memory/session tools continue to work without hard setup errors.
134
- - Project-bound actions (for example `project(action="ingest_local")`) return guided remediation to create/select a project instead of failing with a raw `project_id required` error.
135
- - As soon as you enter a mapped project folder, that real workspace/project is prioritized and replaces fallback scope.
187
+ `setup --editors=claude,cursor` limits configuration to specific editors; `doctor` tells you exactly what's misconfigured and how to fix it — it runs automatically at the end of every setup.
136
188
 
137
189
  ---
138
190
 
139
- ## Manual Configuration
191
+ ## Manual configuration
140
192
 
141
193
  > Skip this if you ran the setup wizard.
142
194
 
@@ -215,11 +267,9 @@ For the local variant, export `CONTEXTSTREAM_API_KEY` before launching OpenCode.
215
267
  </details>
216
268
 
217
269
  <details>
218
- <summary><b>VS Code</b></summary>
219
-
220
- For GitHub Copilot in VS Code, the easiest path is the hosted remote MCP with built-in OAuth. Marketplace installs should write this remote server definition automatically.
270
+ <summary><b>VS Code + GitHub Copilot</b></summary>
221
271
 
222
- **Hosted remote MCP (recommended)**
272
+ The easiest path is the hosted remote MCP with built-in OAuth — no API key in the config file:
223
273
 
224
274
  ```json
225
275
  {
@@ -232,177 +282,117 @@ For GitHub Copilot in VS Code, the easiest path is the hosted remote MCP with bu
232
282
  }
233
283
  ```
234
284
 
235
- On first use, VS Code should prompt you to authorize ContextStream in the browser and then complete setup without an API key in the config file.
236
-
237
- `npx @contextstream/mcp-server@latest setup` now defaults VS Code/Copilot to this hosted remote when you are using the production ContextStream cloud. To force a local runtime instead, run setup with `CONTEXTSTREAM_VSCODE_MCP_MODE=local`.
238
-
239
- For self-hosted or non-default API deployments, local runtime remains the default:
240
-
241
- **Rust MCP (recommended)**
285
+ `setup` defaults VS Code/Copilot to this hosted remote on the production cloud. To force a local runtime, run setup with `CONTEXTSTREAM_VSCODE_MCP_MODE=local`, or use stdio directly:
242
286
 
243
287
  ```json
244
288
  {
245
289
  "servers": {
246
290
  "contextstream": {
247
291
  "type": "stdio",
248
- "command": "contextstream-mcp",
249
- "args": [],
292
+ "command": "npx",
293
+ "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
250
294
  "env": {
251
295
  "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
252
296
  "CONTEXTSTREAM_API_KEY": "your_key",
253
- "CONTEXTSTREAM_TOOLSET": "complete",
254
- "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
255
- "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
256
- "CONTEXTSTREAM_SEARCH_LIMIT": "15",
257
- "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
297
+ "CONTEXTSTREAM_TOOLSET": "complete"
258
298
  }
259
299
  }
260
300
  }
261
301
  }
262
302
  ```
263
303
 
264
- **Node MCP server**
304
+ Keep both `~/.copilot/mcp-config.json` (uses `mcpServers`) and `.vscode/mcp.json` (uses `servers`) in sync — setup writes both.
305
+
306
+ </details>
307
+
308
+ <details>
309
+ <summary><b>GitHub Copilot CLI</b></summary>
310
+
311
+ Use `/mcp add` interactively, or add to `~/.copilot/mcp-config.json`:
265
312
 
266
313
  ```json
267
314
  {
268
- "servers": {
315
+ "mcpServers": {
269
316
  "contextstream": {
270
- "type": "stdio",
271
317
  "command": "npx",
272
318
  "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
273
319
  "env": {
274
320
  "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
275
321
  "CONTEXTSTREAM_API_KEY": "your_key",
276
- "CONTEXTSTREAM_TOOLSET": "complete",
277
- "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
278
- "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
279
- "CONTEXTSTREAM_SEARCH_LIMIT": "15",
280
- "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
322
+ "CONTEXTSTREAM_TOOLSET": "complete"
281
323
  }
282
324
  }
283
325
  }
284
326
  }
285
327
  ```
286
328
 
329
+ See the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) for details.
330
+
287
331
  </details>
288
332
 
289
333
  <details>
290
- <summary><b>GitHub Copilot CLI</b></summary>
334
+ <summary><b>Unmapped folders (global fallback workspace)</b></summary>
291
335
 
292
- Use the Copilot CLI to interactively add the MCP server:
336
+ Folders that aren't associated with any project (your home directory, ad-hoc scratch dirs) still work: `init` falls back to a hidden catch-all workspace in workspace-only mode, memory/session/context tools keep functioning, and project-bound actions return guided remediation instead of raw errors. The moment you enter a mapped project folder, the real workspace/project takes over.
293
337
 
294
- ```bash
295
- /mcp add
296
- ```
338
+ </details>
297
339
 
298
- Or add to `~/.copilot/mcp-config.json` (pick one runtime):
340
+ ---
299
341
 
300
- **Rust MCP (recommended)**
342
+ ## FAQ
301
343
 
302
- ```json
303
- {
304
- "mcpServers": {
305
- "contextstream": {
306
- "command": "contextstream-mcp",
307
- "args": [],
308
- "env": {
309
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
310
- "CONTEXTSTREAM_API_KEY": "your_key",
311
- "CONTEXTSTREAM_TOOLSET": "complete",
312
- "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
313
- "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
314
- "CONTEXTSTREAM_SEARCH_LIMIT": "15",
315
- "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
316
- }
317
- }
318
- }
319
- }
320
- ```
344
+ ### What is an MCP server?
321
345
 
322
- **Node MCP server**
346
+ An MCP (Model Context Protocol) server exposes tools and context to AI assistants over a standard protocol. Claude Code, Cursor, VS Code Copilot, Windsurf, and most modern AI coding tools are MCP clients — install one server, and every client you use gets the same capabilities.
323
347
 
324
- ```json
325
- {
326
- "mcpServers": {
327
- "contextstream": {
328
- "command": "npx",
329
- "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
330
- "env": {
331
- "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
332
- "CONTEXTSTREAM_API_KEY": "your_key",
333
- "CONTEXTSTREAM_TOOLSET": "complete",
334
- "CONTEXTSTREAM_TRANSCRIPTS_ENABLED": "true",
335
- "CONTEXTSTREAM_HOOK_TRANSCRIPTS_ENABLED": "true",
336
- "CONTEXTSTREAM_SEARCH_LIMIT": "15",
337
- "CONTEXTSTREAM_SEARCH_MAX_CHARS": "2400"
338
- }
339
- }
340
- }
341
- }
342
- ```
348
+ ### Does ContextStream work with Claude Code / Cursor / Copilot / Windsurf?
343
349
 
344
- For more information, see the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).
350
+ Yes — all of them, plus Cline, Roo Code, Kilo Code, Codex CLI, OpenCode, Aider, Antigravity, and Claude Desktop. The setup wizard configures each editor's MCP config, managed rules, and (where the editor supports them) lifecycle hooks automatically.
345
351
 
346
- </details>
352
+ ### Is my code private?
347
353
 
348
- ---
354
+ Your code is private and securely stored, isolated per workspace with no cross-tenant access. You control exclusions with `.contextstream/ignore` (gitignore syntax), and `project(action="purge")` completely de-indexes a project on demand — without touching your captured memory.
349
355
 
350
- ## VS Code + Copilot Tips
356
+ ### How much does it cost?
351
357
 
352
- - Run setup once and keep both config files:
353
- - `~/.copilot/mcp-config.json`
354
- - `.vscode/mcp.json`
355
- - Rust install: use `contextstream-mcp` as the command.
356
- - Node install: use `npx --prefer-online -y @contextstream/mcp-server@latest` as the command.
357
- - Force local VS Code/Copilot setup with `CONTEXTSTREAM_VSCODE_MCP_MODE=local`.
358
- - Force hosted remote VS Code/Copilot setup with `CONTEXTSTREAM_VSCODE_MCP_MODE=remote`.
359
- - Use `mcpServers` in Copilot CLI config and `servers` in VS Code config.
358
+ There's a free tier to start with. Larger indexes, the full code graph, and team features are on paid plans: see [pricing](https://contextstream.io/pricing).
360
359
 
361
- ## Quick Troubleshooting
360
+ ### How does ContextStream score on memory benchmarks?
362
361
 
363
- - Remove duplicate ContextStream entries across Workspace/User config scopes.
364
- - Check `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` are set.
365
- - Remove stale version pins like `@contextstream/mcp-server@0.3.xx`.
366
- - Restart VS Code/Copilot after config changes.
362
+ 90.0% on the full 500-instance LongMemEval-S suite with the official GPT-4o judge (89.6% single-shot) — beating supermemory's published 85.4% with statistical significance and matching Zep's published 90.2% within the confidence interval. On multi-session recall specifically, ContextStream scores 81.2% vs Zep's published 57.9%. Methodology and per-family breakdowns: [contextstream.io/benchmarks](https://contextstream.io/benchmarks).
367
363
 
368
- ## Known Limitations
364
+ ### How is this different from other AI memory tools?
369
365
 
370
- ### HTTP transport OAuth and vscode.dev dependency
366
+ Most tools store notes. ContextStream combines **memory** (decisions, lessons, plans, session transcripts), **semantic code search** over your indexed codebase, a **dependency/knowledge graph**, **grounded Q&A with citations**, and **team integrations** (GitHub, Slack, Notion) behind one MCP server — and proactively delivers the relevant slice on every message instead of waiting to be asked.
371
367
 
372
- The hosted HTTP MCP transport (`https://mcp.contextstream.io/mcp`) uses OAuth authentication that routes through `vscode.dev` for the redirect flow. This can fail in environments where `vscode.dev` is blocked (corporate networks, regional restrictions, CDN-level blocks).
368
+ ### Can I use it in CI or scripted environments?
373
369
 
374
- **Workaround:** Use the stdio transport (Rust binary or Node.js) with API key authentication instead:
370
+ Yes: `setup --yes` runs the entire wizard with zero prompts (set `CONTEXTSTREAM_API_KEY` in the environment), `--editors=<list>` scopes it, and `contextstream-mcp doctor` gives scriptable ✓/✗ diagnostics.
375
371
 
376
- ```json
377
- {
378
- "contextstream": {
379
- "type": "stdio",
380
- "command": "npx",
381
- "args": ["-y", "@contextstream/mcp-server@latest"],
382
- "env": {
383
- "CONTEXTSTREAM_API_KEY": "your-api-key"
384
- }
385
- }
386
- }
387
- ```
372
+ ### Do I have to wait for indexing?
388
373
 
389
- ### SDK version compatibility
374
+ No. Project indexing runs in the background — keyword search works immediately, and semantic results fill in as the index builds. Check progress anytime with `contextstream-mcp doctor`.
390
375
 
391
- `@modelcontextprotocol/sdk` versions 1.28.0 and above introduce breaking changes. The `package.json` pins the SDK to `>=1.25.1 <1.28.0` to prevent incompatible resolutions. If you experience Zod schema errors on startup, ensure your SDK version is below 1.28.0.
376
+ ### How do I uninstall or disable it?
392
377
 
393
- ## Marketplace Note
378
+ Remove the `contextstream` entry from your editor's MCP config, and set `CONTEXTSTREAM_HOOK_ENABLED=false` (or re-run setup) to disable hooks. `project(action="forget_local")` unbinds a folder locally without touching server-side data.
394
379
 
395
- The MCP marketplace entry now targets the hosted remote MCP at `https://mcp.contextstream.io/mcp?default_context_mode=fast` so VS Code can use the native OAuth flow instead of writing a local npm-based stdio config.
380
+ ---
396
381
 
397
- Use the Rust or Node local runtime configs above only when you explicitly want local execution, custom/self-hosted endpoints, or editor environments that do not support the hosted remote flow.
382
+ ## Troubleshooting
383
+
384
+ - **Start with `contextstream-mcp doctor`** — it checks auth, API reachability, folder scope, index health, rule files, and hooks, with a fix hint per failure.
385
+ - Remove duplicate ContextStream entries across Workspace/User config scopes.
386
+ - Check `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` are set; remove stale version pins like `@contextstream/mcp-server@0.3.xx`.
387
+ - Restart your editor after config changes.
388
+ - **Hosted HTTP OAuth:** the remote transport's OAuth flow routes through `vscode.dev`; where that's blocked (corporate networks), use stdio with an API key instead.
389
+ - **SDK compatibility:** `@modelcontextprotocol/sdk` 1.28.0+ introduces breaking changes; this package pins `>=1.25.1 <1.28.0`. If you see Zod schema errors on startup, check your SDK resolution.
398
390
 
399
391
  ---
400
392
 
401
393
  ## Links
402
394
 
403
- **Website:** https://contextstream.io
404
-
405
- **Docs:** https://contextstream.io/docs
395
+ **Website:** https://contextstream.io • **Docs:** https://contextstream.io/docs • **Changelog:** [CHANGELOG.md](CHANGELOG.md)
406
396
 
407
397
  ---
408
398