Quickstart
Get started in less than 5 minutes.
Connect ContextStream to your AI coding tools for persistent memory across sessions.
Prerequisites
Before you begin.
- A ContextStream accountView Plans
- An AI coding tool (Claude Code, Codex CLI, OpenCode CLI, Cursor, Cline, etc.)
01Step 01
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).
curl -fsSL https://contextstream.io/scripts/mcp.sh | bashPrefer manual setup? Create an API key in Account → API Keys and follow Steps 2–3.
★Step ★
After login on a team (checklist)
If your account has team membership (Team plan or dual-context), the setup wizard shows extra guidance after authentication. Use this checklist whether you ran setup or joined an existing workspace.
Team onboarding checklist
- 1.Select the shared team workspace during setup (step 3) — not a personal sandbox.
- 2.Link this repo to the correct project so indexing and tickets map to the same context.
- 3.Open your editor and confirm session(action="context") surfaces team recommendations on the first message.
- 4.Share a team skill: skill(action="share", scope="team") for workflows everyone should reuse.
- 5.Refresh hooks/rules after onboarding: contextstream-mcp update-hooks --scope=global; contextstream-mcp update-rules --scope=all
Dual-context accounts can switch scope anytime with --account-mode=team|personal|auto or CONTEXTSTREAM_ACCOUNT_MODE. See team setup and CLI shortcuts.
02Step 02
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.
Create: 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
mcp__contextstream__*). Other tools use raw names (session_init, etc.).03Step 03
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
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"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:
curl -fsSL https://contextstream.io/scripts/mcp.sh | bashirm https://contextstream.io/scripts/mcp.ps1 | iexThe 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
Pick a path and keep going.
Once connected, your AI will automatically use ContextStream. Try asking it to remember a decision or recall past context!