@contextstream/mcp-server 0.4.82 → 1.0.1

package/NOTICE

@@ -0,0 +1,25 @@
+ContextStream MCP Server
+Copyright (c) 2025-2026 ContextStream
+
+This product is developed and maintained by ContextStream as part of the
+ContextStream platform (https://contextstream.io).
+
+ContextStream is an independently developed cloud service providing persistent
+memory and cross-session context management for AI coding assistants. The
+platform includes proprietary backend services not included in this repository.
+
+This MCP server is a client library that connects to the ContextStream API.
+It requires a ContextStream account and API key to function.
+
+TRADEMARKS
+
+"ContextStream" and the ContextStream logo are trademarks of ContextStream.
+Use of these trademarks requires prior written permission.
+
+THIRD-PARTY LICENSES
+
+This software uses open-source Rust crates recorded in Cargo.lock. The npm
+compatibility launcher has no runtime package dependencies. Release SBOMs and
+license reports provide the exact dependency inventory for each release.
+
+For questions about licensing or trademark usage, contact: legal@contextstream.io

package/README.md

@@ -1,402 +1,286 @@
+<!-- mcp-name: io.github.contextstream/mcp-server -->
+
 <p align="center">
-  <img src="https://contextstream.io/400logo.png" alt="ContextStream — persistent memory and semantic code search for AI coding assistants" width="80" />
+  <img src="assets/contextstream-logo.png" alt="ContextStream" width="112" />
 </p>
 
 <h1 align="center">ContextStream MCP Server</h1>
 
 <p align="center">
-  <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>
+  <em>Intelligence without context is unreliable. Autonomy without context is chaos.<br/>
+  And context without trust becomes surveillance.</em>
 </p>
 
 <p align="center">
-  🏆 <b>90.0% on LongMemEval-S</b> — the full 500-instance suite with the official judge.<br/>
-  Beats supermemory with statistical significance; matches Zep. <a href="https://contextstream.io/benchmarks">See the benchmarks →</a>
+  <strong>Give every coding agent persistent memory, semantic code search, and the right project context on every turn.</strong>
 </p>
 
 <p align="center">
-  <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>
-  <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>
-  <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>
-  <img src="https://img.shields.io/node/v/@contextstream/mcp-server.svg" alt="node version" />
+  Works with Claude Code, Cursor, VS Code + Copilot, Windsurf, Cline, Roo Code, Kilo Code, Codex, OpenCode, Aider, Antigravity, and other MCP clients.
 </p>
 
 <p align="center">
-  <a href="https://contextstream.io/docs">Documentation</a> •
-  <a href="https://contextstream.io/pricing">Pricing</a> •
-  <a href="#faq">FAQ</a>
+  <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>
+  <a href="https://github.com/contextstream/mcp-server/releases/latest"><img src="https://img.shields.io/github/v/release/contextstream/mcp-server" alt="latest release" /></a>
+  <a href="https://github.com/contextstream/mcp-server/actions/workflows/ci.yml"><img src="https://github.com/contextstream/mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
 </p>
 
----
-
-## 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
-```
-
 <p align="center">
-  <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" />
+  <a href="#install-in-30-seconds"><strong>Install in 30 seconds</strong></a> ·
+  <a href="https://contextstream.io/benchmarks">Benchmarks</a> ·
+  <a href="https://contextstream.io/docs/mcp">Documentation</a> ·
+  <a href="https://contextstream.io/signup">Start free</a>
 </p>
 
 ---
 
-## We win on memory benchmarks — measured honestly
+Your AI should not have to rediscover the repository, re-learn the architecture,
+or repeat last week's mistake every time a chat starts. ContextStream gives MCP
+clients a shared context layer that remembers decisions and lessons, searches
+code by meaning, maps dependencies, and restores the thread after compaction.
 
-**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.
+The server in this repository is the canonical, MIT-licensed Rust
+implementation. The recommended editor transport is the hosted MCP at
+`https://mcp.contextstream.io/mcp`; a small local helper keeps explicitly linked
+checkouts in sync.
 
-| 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 |
+## Benchmarks: strong memory, strong retrieval, published methodology
 
-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%**.
+We publish the full method, confidence intervals, comparison caveats, and known
+losses—not just the winning number. The product-level figures below are from
+the published July 2026 report; the LongMemEval-S result was published June 14,
+2026.
 
-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)**
+| Benchmark | ContextStream result | What was measured |
+|---|---:|---|
+| **LongMemEval-S** | **90.0%** | 450/500 correct on the full suite; ~115k-token multi-session histories; official pinned GPT-4o judge; `gpt-5.5` reader with self-consistency `k=3` (89.6% single-shot); Wilson 95% CI [87.1%, 92.3%] |
+| **Pinned-repo code search** | **99.38% Recall@10** | 93.83% Primary@10 and 95 ms successful-response p50 over 177 judged-valid queries, averaged across two cold and two warm runs; 0/708 failed requests; no local checkout |
+| **Agentic project memory** | **96% task success** | Up from 58% without the memory layer; one repository, one agent model, three trials per cell, so this result is directional |
 
----
-
-## 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?
+On the standard memory benchmark, 90.0% is statistically above supermemory's
+published 85.4% and statistically tied with Zep's published 90.2%. Those
+comparisons use each vendor's published result; they are not presented as a
+private same-run head-to-head.
 
-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.
+**[Read the full benchmark report, methodology, per-category results, and losses →](https://contextstream.io/benchmarks)**
 
-| 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 repository also includes Criterion suites for JSON-RPC parsing, tool
+dispatch, response serialization, and stdio/HTTP transport primitives. Run
+them locally with `cargo bench --locked -p mcp-server`.
 
-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.
+## Install in 30 seconds
 
----
-
-## 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 |
-
----
+Pick the command for your platform. Each installer downloads the current native
+release and launches the guided setup wizard.
 
-## 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="<uuid>", limit=30)` lists completed recaps newest-first with `recap_date` and `generated_at` timestamps.
-- `session(action="trigger_recap", workspace_id="<uuid>")` 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
+### macOS and Linux
 
 ```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
+curl -fsSL https://contextstream.io/scripts/setup.sh | bash
 ```
 
-`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.
+Native releases are published for macOS Apple Silicon and Intel, plus Linux
+ARM64 and x64.
 
----
+### Windows PowerShell
 
-## Manual configuration
+```powershell
+irm https://contextstream.io/scripts/setup.ps1 | iex
+```
 
-> Skip this if you ran the setup wizard.
+The Windows installer uses the native x64 binary and installs it in your user
+profile, so it does not need an administrator shell.
 
-<details>
-<summary><b>Claude Code</b></summary>
+### npm alternative (Node.js 20+)
 
 ```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
+npx -y @contextstream/mcp-server@latest setup
 ```
 
-</details>
+The dependency-free npm launcher selects the matching release artifact,
+verifies its SHA-256 checksum, caches it by exact package version, and starts
+the Rust binary. It supports macOS ARM64/x64, Linux ARM64/x64, and Windows x64.
 
-<details>
-<summary><b>Cursor / Claude Desktop</b></summary>
+### What the wizard does
 
-```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`
+The wizard signs you in, detects supported editors, writes their hosted MCP
+configuration and managed rules, installs lifecycle hooks where supported,
+links the exact project folder you choose, starts indexing, and checks the
+result. You review the choices before it makes changes.
 
-</details>
+After setup, restart the editor and try:
 
-<details>
-<summary><b>OpenCode</b></summary>
+> Use ContextStream to summarize this repository, cite the files you relied on,
+> and tell me one active decision or risk that should affect my next change.
 
-Local server:
+Want to inspect the changes first? Every setup write can be previewed:
 
-```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
-    }
-  }
-}
+```bash
+contextstream-mcp setup --dry-run
 ```
 
-Remote server:
+Already configured and troubleshooting? Run:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "contextstream": {
-      "type": "remote",
-      "url": "https://mcp.contextstream.com",
-      "enabled": true
-    }
-  }
-}
+```bash
+contextstream-mcp doctor --scope=all --only-configured
 ```
 
-For the local variant, export `CONTEXTSTREAM_API_KEY` before launching OpenCode.
-
-**Locations:** `./opencode.json` • `~/.config/opencode/opencode.json`
-
-</details>
+## No-install hosted connection
 
-<details>
-<summary><b>VS Code + GitHub Copilot</b></summary>
-
-The easiest path is the hosted remote MCP with built-in OAuth — no API key in the config file:
+If your MCP client supports Streamable HTTP and OAuth, connect directly—there
+is no local MCP process to keep running:
 
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "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"
-      }
+      "url": "https://mcp.contextstream.io/mcp"
     }
   }
 }
 ```
 
-Keep both `~/.copilot/mcp-config.json` (uses `mcpServers`) and `.vscode/mcp.json` (uses `servers`) in sync — setup writes both.
-
-</details>
+Some clients use a different root key or config format, which is why the setup
+wizard is the easiest path. The hosted gateway is the default; the installed
+helper only syncs the local checkouts you explicitly link.
 
-<details>
-<summary><b>GitHub Copilot CLI</b></summary>
-
-Use `/mcp add` interactively, or add to `~/.copilot/mcp-config.json`:
+Clients that require stdio can use the verified npm launcher:
 
 ```json
 {
   "mcpServers": {
     "contextstream": {
       "command": "npx",
-      "args": ["--prefer-online", "-y", "@contextstream/mcp-server@latest"],
+      "args": ["-y", "@contextstream/mcp-server@latest"],
       "env": {
-        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
-        "CONTEXTSTREAM_API_KEY": "your_key",
-        "CONTEXTSTREAM_TOOLSET": "complete"
+        "CONTEXTSTREAM_API_KEY": "your-api-key"
       }
     }
   }
 }
 ```
 
-See the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) for details.
-
-</details>
+For production automation, pin an exact 1.x package version instead of
+`latest`.
 
-<details>
-<summary><b>Unmapped folders (global fallback workspace)</b></summary>
+## What your agent gets
 
-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.
-
-</details>
-
----
+| Capability | What changes in practice |
+|---|---|
+| **Grounded context** | Each turn starts with the relevant workspace rules, prior decisions, lessons, and current project state. |
+| **Semantic code search** | Find implementations by intent, with hybrid, keyword, pattern, exhaustive, and refactor-aware modes when precision matters. |
+| **Durable memory** | Decisions, plans, tasks, runbooks, preferences, and session transcripts remain queryable across chats and tools. |
+| **Compaction survival** | Important state is checkpointed before long conversations compact and restored afterward. |
+| **Dependency intelligence** | Trace blast radius, dependencies, circular imports, complexity, and unused code without manually rebuilding the graph. |
+| **Agent handoffs** | Package verified state and next steps into durable handoffs and portable ContextCapsules. |
+| **Team context** | Bring shared workspace knowledge and supported GitHub, Slack, and Notion context into the same MCP surface. |
 
-## FAQ
+The default tool surface is grouped into focused domains—`context`, `search`,
+`memory`, `session`, `graph`, `entity`, `capsule`, `project`, `workspace`,
+`skill`, `media`, `vcs`, and more—so agents get broad capability without an
+enormous tool-registration prompt.
 
-### What is an MCP server?
+## Supported editors and agents
 
-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.
+The wizard currently detects and configures:
 
-### Does ContextStream work with Claude Code / Cursor / Copilot / Windsurf?
+- Claude Code
+- Cursor
+- Windsurf
+- VS Code + GitHub Copilot
+- Cline
+- Kilo Code
+- Roo Code
+- OpenAI Codex
+- Aider
+- Antigravity
+- OpenCode
 
-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.
+Anything else that speaks the Model Context Protocol can connect to the hosted
+URL or use the stdio launcher.
 
-### Is my code private?
+## What is open source?
 
-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.
+This repository contains the canonical Rust MCP server, protocol types, client
+and session layers, editor setup, hooks, public transport code, release
+automation, and the MongoDB-free acceleration foundation. It builds as seven
+workspace crates:
 
-### How much does it cost?
+- `mcp-server`
+- `mcp-tools`
+- `mcp-client`
+- `mcp-session`
+- `mcp-types`
+- `mcp-model-registry`
+- `mcp-acceleration-products`
 
-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).
+The hosted backend, credentials, production deployment configuration, and
+premium provider implementations are not included. Public-build compatibility
+traits remain no-op so the core protocol surface stays stable. See
+[`docs/architecture.md`](docs/architecture.md) for the boundary.
 
-### How does ContextStream score on memory benchmarks?
+## Privacy and data controls
 
-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).
+Setup shows a disclosure before changing editor configuration or indexing a
+project. You choose the folder and workspace relationship; only matching source
+files from a validated project can be indexed. Transcript capture, local Git
+metadata capture, ignore rules, kill switches, retention behavior, and deletion
+paths are documented in [`docs/data-handling.md`](docs/data-handling.md).
 
-### How is this different from other AI memory tools?
+Review that document before using `setup --yes` in automation. The CLI also
+provides `--dry-run` for setup, repair, migration, and uninstall workflows.
 
-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.
+## Build and test from source
 
-### Can I use it in CI or scripted environments?
+The workspace uses the Rust toolchain pinned in `rust-toolchain.toml`.
 
-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.
+```bash
+cargo build --locked -p mcp-server --bin contextstream-mcp
+cargo test --locked --workspace
+cargo bench --locked -p mcp-server
+```
 
-### Do I have to wait for indexing?
+To build the hosted HTTP gateway foundation:
 
-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`.
+```bash
+cargo build --locked --release -p mcp-server --bin contextstream-mcp \
+  --features remote-acceleration
+```
 
-### How do I uninstall or disable it?
+## Release integrity
 
-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.
+Every release publishes native binaries, `checksums.txt`, `version.json`, and
+an SPDX SBOM. The npm launcher downloads only from the immutable path for its
+exact package version, verifies manifests and binary SHA-256, uses an atomic
+versioned cache, and supports verified offline reuse with
+`CONTEXTSTREAM_MCP_OFFLINE=1`.
 
----
+See [`docs/release.md`](docs/release.md) for the release contract and
+[the latest GitHub release](https://github.com/contextstream/mcp-server/releases/latest)
+for artifacts.
 
-## Troubleshooting
+All 1.x npm releases preserve these executable aliases:
 
-- **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.
+- `mcp-server`
+- `contextstream-mcp`
+- `contextstream-hook` (forwards to the Rust `hook` subcommand)
 
----
+## Contributing and security
 
-## Links
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md),
+[SECURITY.md](SECURITY.md), and [GOVERNANCE.md](GOVERNANCE.md). Contributions
+must include the Developer Certificate of Origin sign-off (`git commit -s`).
 
-**Website:** https://contextstream.io • **Docs:** https://contextstream.io/docs • **Changelog:** [CHANGELOG.md](CHANGELOG.md)
+The code is MIT licensed. ContextStream trademarks and the hosted-service
+boundary are described in [NOTICE](NOTICE).
 
 ---
 
 <p align="center">
-  <strong>Stop teaching your AI the same things over and over.</strong><br/>
-  <sub>ContextStream makes it brilliant from the first message.</sub>
+  <strong>Stop teaching your coding agent the same project twice.</strong><br />
+  <a href="#install-in-30-seconds">Install ContextStream</a> ·
+  <a href="https://contextstream.io/signup">Start free</a> ·
+  <a href="https://contextstream.io/docs/mcp">Read the docs</a>
 </p>

package/npm/bin/contextstream-hook.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../launcher.mjs";
+
+try {
+  await run({ mode: "hook" });
+} catch (error) {
+  console.error(`ContextStream launcher: ${error?.message ?? error}`);
+  process.exitCode = 1;
+}

package/npm/bin/contextstream-mcp.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../launcher.mjs";
+
+try {
+  await run({ mode: "server" });
+} catch (error) {
+  console.error(`ContextStream launcher: ${error?.message ?? error}`);
+  process.exitCode = 1;
+}