ContextStream β€” persistent memory and semantic code search for AI coding assistants

ContextStream MCP Server

Persistent memory, semantic code search, and team context for Claude Code, Cursor, VS Code Copilot, Windsurf β€” and every MCP-compatible AI coding assistant.

πŸ† 90.0% on LongMemEval-S β€” the full 500-instance suite with the official judge.
Beats supermemory with statistical significance; matches Zep. See the benchmarks β†’

npm version npm downloads MIT license node version

Documentation β€’ Pricing β€’ FAQ

--- ## Try it in 30 seconds ```bash npx --prefer-online -y @contextstream/mcp-server@latest setup ``` 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. Automating it? Zero-prompt mode takes every default: ```bash npx --prefer-online -y @contextstream/mcp-server@latest setup --yes ```

Animated comparison of an AI coding assistant working without ContextStream versus with ContextStream project memory, search, and graph context

--- ## We win on memory benchmarks β€” measured honestly **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. | System | LongMemEval-S | Notes | |---|:---:|---| | **ContextStream** | **90.0%** | Full 500 instances, official GPT-4o judge | | Zep | 90.2% | Vendor-published β€” a statistical tie (0.2 pt is inside measurement noise) | | supermemory | 85.4% | Vendor-published β€” ContextStream wins with statistical significance | 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%**. 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)** --- ## What is ContextStream? **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. 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. --- ## Which ContextStream runtime am I using? 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. | Runtime | How to identify it | Version line | Canonical release metadata and notes | |---|---|---|---| | **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). | | **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. | | **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). | | **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. | 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. --- ## Why do AI coding assistants forget everything? 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: | Without ContextStream | With ContextStream | |--------|-------| | AI greps files one-by-one, burning tokens | **Semantic code search** finds code by meaning in milliseconds | | Context lost when conversations get long | **Pre-compaction capture** saves critical state before it's gone β€” and restores it after | | Same mistakes repeated across sessions | **Lessons system** surfaces past failures *before* your AI repeats them | | "Why did we choose X?" β€” nobody remembers | **Decisions and plans** persist and resurface when relevant | | Team knowledge scattered across tools | **GitHub, Slack, and Notion knowledge**, queried automatically | | Generic answers with no project awareness | **Workspace context** on every single message | --- ## What your AI can do after setup ### πŸ” Find code by meaning, not keywords 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. ### 🧠 Remember everything that matters 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. ### πŸ’¬ Ask the workspace when stuck 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. ### πŸ•ΈοΈ See the whole graph *"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. ### πŸ“¦ Hand off context between agents **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. ### πŸ›‘οΈ Survive long sessions 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. --- ## Which AI editors and agents does it support? | Editor / Agent | Managed rules | MCP config | Lifecycle hooks | |---|:---:|:---:|:---:| | Claude Code | βœ… | βœ… | βœ… | | Cursor | βœ… (`.cursor/rules/*.mdc`) | βœ… | βœ… | | Windsurf | βœ… | βœ… | βœ… | | Cline | βœ… | βœ… | βœ… | | Roo Code | βœ… | βœ… | βœ… | | Kilo Code | βœ… | βœ… | rules-based | | VS Code + GitHub Copilot | βœ… | βœ… (incl. hosted OAuth) | rules-based | | Codex CLI | βœ… | βœ… | rules-based | | OpenCode | βœ… | βœ… | rules-based | | Aider | βœ… | βœ… | rules-based | | Antigravity | βœ… | βœ… | rules-based | | Claude Desktop | β€” | βœ… | β€” | Anything that speaks the Model Context Protocol can connect β€” the table just shows what the setup wizard configures automatically. --- ## Tools 36 tools in the default surface, organized as consolidated domains so they cost ~75% fewer tokens than individual registrations. The tools your AI gets: - **init** / **context** β€” workspace state + the right context on every message - **search** β€” semantic, hybrid, keyword, pattern, exhaustive, refactor modes - **memory** β€” events, decisions, docs, runbooks, tasks, todos, diagrams, transcripts - **session** β€” capture decisions & lessons, recall past sessions, plans, retroactive capture - **qa** β€” grounded Q&A over your workspace knowledge base, with citations - **graph** β€” dependencies, impact analysis, circular deps, unused code - **capsule** β€” portable, shareable context snapshots for agent handoffs - **entity** β€” tickets, incidents, releases, sprints, OKRs, risks - **project** / **workspace** β€” project indexing, scope, and workspace management - **skill** β€” reusable instruction + action bundles, portable across tools - **media** β€” index and search images, video, audio, and documents - **vcs** / **reminder** / **integration** / **help** β€” repo links, reminders, integrations, diagnostics 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. ### Daily Recaps 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. - `session(action="list_recaps", workspace_id="", limit=30)` lists completed recaps newest-first with `recap_date` and `generated_at` timestamps. - `session(action="trigger_recap", workspace_id="")` queues an asynchronous manual recap. Call `list_recaps` afterward to verify completion. These actions use the same recap history and generation service as the dashboard. --- ## CLI commands ```bash contextstream-mcp setup # interactive onboarding wizard contextstream-mcp setup --yes # zero-prompt setup with sane defaults (great for CI/dotfiles) contextstream-mcp doctor # βœ“/βœ— diagnostics: auth, scope, index health, rules, hooks contextstream-mcp index [path] # index a project folder on demand ``` `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. --- ## Manual configuration > Skip this if you ran the setup wizard.
Claude Code ```bash claude mcp add contextstream -- npx --prefer-online -y @contextstream/mcp-server@latest claude mcp update contextstream -e CONTEXTSTREAM_API_URL=https://api.contextstream.io -e CONTEXTSTREAM_API_KEY=your_key ```
Cursor / Claude Desktop ```json { "mcpServers": { "contextstream": { "command": "npx", "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"], "env": { "CONTEXTSTREAM_API_URL": "https://api.contextstream.io", "CONTEXTSTREAM_API_KEY": "your_key" } } } } ``` **Locations:** `~/.cursor/mcp.json` β€’ `~/Library/Application Support/Claude/claude_desktop_config.json`
OpenCode Local server: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "contextstream": { "type": "local", "command": ["npx", "-y", "contextstream-mcp"], "environment": { "CONTEXTSTREAM_API_KEY": "{env:CONTEXTSTREAM_API_KEY}" }, "enabled": true } } } ``` Remote server: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "contextstream": { "type": "remote", "url": "https://mcp.contextstream.com", "enabled": true } } } ``` For the local variant, export `CONTEXTSTREAM_API_KEY` before launching OpenCode. **Locations:** `./opencode.json` β€’ `~/.config/opencode/opencode.json`
VS Code + GitHub Copilot The easiest path is the hosted remote MCP with built-in OAuth β€” no API key in the config file: ```json { "servers": { "contextstream": { "type": "http", "url": "https://mcp.contextstream.io/mcp?default_context_mode=fast" } } } ``` `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: ```json { "servers": { "contextstream": { "type": "stdio", "command": "npx", "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"], "env": { "CONTEXTSTREAM_API_URL": "https://api.contextstream.io", "CONTEXTSTREAM_API_KEY": "your_key", "CONTEXTSTREAM_TOOLSET": "complete" } } } } ``` Keep both `~/.copilot/mcp-config.json` (uses `mcpServers`) and `.vscode/mcp.json` (uses `servers`) in sync β€” setup writes both.
GitHub Copilot CLI Use `/mcp add` interactively, or add to `~/.copilot/mcp-config.json`: ```json { "mcpServers": { "contextstream": { "command": "npx", "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"], "env": { "CONTEXTSTREAM_API_URL": "https://api.contextstream.io", "CONTEXTSTREAM_API_KEY": "your_key", "CONTEXTSTREAM_TOOLSET": "complete" } } } } ``` See the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) for details.
Unmapped folders (global fallback workspace) 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.
--- ## FAQ ### What is an MCP server? 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. ### Does ContextStream work with Claude Code / Cursor / Copilot / Windsurf? 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. ### Is my code private? 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. ### How much does it cost? 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). ### How does ContextStream score on memory benchmarks? 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). ### How is this different from other AI memory tools? 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. ### Can I use it in CI or scripted environments? Yes: `setup --yes` runs the entire wizard with zero prompts (set `CONTEXTSTREAM_API_KEY` in the environment), `--editors=` scopes it, and `contextstream-mcp doctor` gives scriptable βœ“/βœ— diagnostics. ### Do I have to wait for indexing? 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`. ### How do I uninstall or disable it? 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. --- ## Troubleshooting - **Start with `contextstream-mcp doctor`** β€” it checks auth, API reachability, folder scope, index health, rule files, and hooks, with a fix hint per failure. - Remove duplicate ContextStream entries across Workspace/User config scopes. - Check `CONTEXTSTREAM_API_URL` and `CONTEXTSTREAM_API_KEY` are set; remove stale version pins like `@contextstream/mcp-server@0.3.xx`. - Restart your editor after config changes. - **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. - **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. --- ## Links **Website:** https://contextstream.io β€’ **Docs:** https://contextstream.io/docs β€’ **Changelog:** [CHANGELOG.md](CHANGELOG.md) ---

Stop teaching your AI the same things over and over.
ContextStream makes it brilliant from the first message.