Get Started in Less than 5 Minutes
Connect ContextStream to your AI coding tools for persistent memory across sessions.
Prerequisites
Run the Setup Wizard (recommended)
The fastest way to get set up is the ContextStream wizard. It uses browser/device login, creates an API key for you, installs editor rules, and writes the right MCP config for the tools you select (including VS Code).
npx -y @contextstream/mcp-server setupPrefer manual setup? Create an API key in Account → API Keys and follow Steps 2–3.
Add Editor Rules
Editor rules tell your AI assistant when to use ContextStream. If you ran the setup wizard, it can generate these for you. Otherwise, select your tool below and add the rules file to your project.
These rules are for your AI assistant, not you. After adding them, you can just ask naturally and the AI will use ContextStream automatically.
Create: CLAUDE.md
Location: project root or ~/.claude/CLAUDE.md
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `mcp__contextstream__search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `mcp__contextstream__context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `mcp__contextstream__session_init(folder_path="<cwd>", context_hint="<msg>")` then `mcp__contextstream__context_smart(...)` |
| **2nd+ messages** | `mcp__contextstream__context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `mcp__contextstream__search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `mcp__contextstream__session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code mcp__contextstream__search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `mcp__contextstream__search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `mcp__contextstream__search(mode="hybrid", query="auth", limit=3)` |
| `session` | `mcp__contextstream__session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `mcp__contextstream__memory(action="list_events", limit=10)` |
| `graph` | `mcp__contextstream__graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `mcp__contextstream__session(action="get_lessons", query="<topic>")`
- On mistakes: `mcp__contextstream__session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `mcp__contextstream__session(action="capture_plan", title="...", steps=[...])`
2. `mcp__contextstream__memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
Note: Claude Code uses namespaced tool names (mcp__contextstream__*). Other tools use raw names (session_init, etc.).
Connect via MCP
Add ContextStream to your AI tool's MCP configuration. Select your tool below for the correct config file location and format.
Config file: .mcp.json
Project root (.mcp.json). For user-scope (all projects), use `claude mcp add` (see /docs/mcp).
{
"mcpServers": {
"contextstream": {
"command": "npx",
"args": ["-y", "@contextstream/mcp-server"],
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "YOUR_API_KEY"
}
}
}
}Replace YOUR_API_KEY with your actual API key (from the setup wizard or your account).
If you're self-hosting or using a non-default endpoint, change CONTEXTSTREAM_API_URL. The default is https://api.contextstream.io.
v0.4.x Toolset: By default, the MCP server exposes ~11 consolidated domain tools for ~75% token reduction. Set CONTEXTSTREAM_PROGRESSIVE_MODE=true for ~2 router meta-tools (most compact). See full tool catalog.
Keep Updated
To get the latest features and fixes, update periodically:
npm update -g @contextstream/mcp-serverThe MCP server will warn you when a newer version is available.
Updating rules files: Just ask your AI assistant: "please make sure my rules files are all the latest" and it will update them for you automatically.
What's Next?
Once connected, your AI will automatically use ContextStream. Try asking it to remember a decision or recall past context!