MCP Integration

Connect Your AI Tools

ContextStream integrates with AI tools via the Model Context Protocol (MCP). Give Codex CLI, Claude, Cursor, Windsurf, Cline, Kilo Code, Roo Code, and Antigravity persistent memory across all your conversations.

Setup Wizard (recommended)

Run one command to authenticate (browser/device login), create an API key, generate rules, and write the correct MCP config for your tool (including VS Code's servers schema).

Terminal (macOS/Linux)

curl -fsSL https://contextstream.io/scripts/mcp.sh | bash

PowerShell (Windows)

irm https://contextstream.io/scripts/mcp.ps1 | iex

Alternative: npx (requires Node.js 18+)

Terminal

contextstream-mcp setup

What it does: writes MCP config (VS Code servers, Cursor/Cline/etc mcpServers), generates rules (Standard/Enhanced), and can link projects to a workspace.

v0.4.x Toolset: The wizard configures ~11 consolidated domain tools by default (~75% token reduction). Optional: router mode (~2 meta-tools, most compact). See full tool catalog.

Preview changes without writing files: contextstream-mcp setup --dry-run

Manual configuration

Use the correct format per client (VS Code uses servers; many other clients use mcpServers).

v0.4.x Toolset: By default, the server exposes ~11 consolidated domain tools (~75% token reduction vs previous versions). For even fewer tools, add "CONTEXTSTREAM_PROGRESSIVE_MODE": "true" to the env block for ~2 router meta-tools. See full tool catalog.

Jump to your tool:

Cursor / VS CodeWindsurfCodex CLIClaude CodeClaude DesktopClineKilo CodeRoo CodeAntigravity

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. With ContextStream's MCP server, your AI tools can:

• Remember conversations and decisions across sessions
• Search your codebase and documentation semantically
• Build and query knowledge graphs
• Share context between different AI tools

Just Use Natural Language

You don't need to memorize tool names or call them directly. Just describe what you want in plain English and your AI assistant will use the right tools automatically.

Just ask naturally:

• • "session summary"
• • "what did we decide about auth?"
• • "remember we're using PostgreSQL"
• • "search for payment code"

The AI handles the rest:

• • Finds relevant context automatically
• • Recalls past decisions when needed
• • Saves important information to memory
• • Searches code and documentation

Example: User types "session summary" in natural language

The AI understands your intent and calls the appropriate ContextStream tools behind the scenes.

Prerequisites

• A ContextStream account (the setup wizard can create an API key via browser login)
• Node.js 18+ installed on your system

Enrich Context with GitHub + Slack

Available

MCP gives your AI persistent memory. Connecting GitHub and Slack makes that memory much richer—your AI can automatically reference PRs, issues, and team discussions when answering questions.

Automatic Context Enrichment

When you call context_smart or session_smart_search, relevant GitHub issues, PRs, and Slack discussions are automatically included. No extra tools needed.

Available

GitHub

Sync issues, PRs, releases, and comments. Decisions are automatically extracted from discussions.

Available

Slack

Sync channels and threads. High-engagement conversations are scored and prioritized.

Example prompts with integrations connected:

• • "What did we decide about authentication?" — finds decisions from GitHub issues + Slack threads
• • "Show me recent activity on the payment system" — surfaces PRs, issues, and team discussions
• • "What lessons did we learn from the last outage?" — retrieves insights from Slack and GitHub
• • "Give me a weekly summary of GitHub activity" — uses integration(provider="github", action="summary", ...)
• • "Search all integrations for database migration discussions" — uses integration(provider="all", action="search", ...)
• • "Give me a weekly team summary across all sources" — uses integration(provider="all", action="summary", ...)

Integration Tool Actions Quick Reference (v0.4.x)

Use integration(provider="github|slack|all", action="...")

GitHub Actions (provider="github")

• action="stats" — Stats and sync status
• action="search" — Search with state/timeframe filters
• action="activity" — Activity feed (days filter)
• action="knowledge" — Extracted decisions/lessons
• action="summary" — Weekly/monthly summary
• action="repos" — List synced repos
• action="issues" — List issues/PRs

Slack Actions (provider="slack")

• action="stats" — Stats and sync status
• action="search" — Search with channel/timeframe filters
• action="discussions" — High-engagement threads
• action="knowledge" — Extracted decisions/lessons
• action="summary" — Weekly/monthly summary
• action="channels" — List synced channels

Cross-Source (provider="all")

• action="status" — Check sync status and health of all connected integrations
• action="search" — Search across all connected integrations in one query
• action="summary" — Unified activity summary across all sources (days filter)
• action="knowledge" — Get decisions, lessons, and insights from all sources

Cursor / VS Code

Cursor and VS Code use different MCP config schemas:

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "contextstream": {
      "command": "contextstream-mcp",
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "your_api_key"
      }
    }
  }
}

.vscode/mcp.json (VS Code native MCP)

{
  "servers": {
    "contextstream": {
      "type": "stdio",
      "command": "contextstream-mcp",
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "your_api_key"
      }
    }
  }
}

Recommended: VS Code inputs (avoid committing API keys)

.vscode/mcp.json (with inputs)

{
  "servers": {
    "contextstream": {
      "type": "stdio",
      "command": "contextstream-mcp",
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "${input:contextstreamApiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "contextstreamApiKey",
      "type": "promptString",
      "description": "ContextStream API Key",
      "password": true
    }
  ]
}

After editing the config, restart your editor for changes to take effect.

Codex CLI

To use ContextStream with the Codex CLI, add the MCP server configuration to your ~/.codex/config.toml file:

~/.codex/config.toml

[mcp_servers.contextstream]
command = "contextstream-mcp"
args = []

[mcp_servers.contextstream.env]
CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
CONTEXTSTREAM_API_KEY = "your_api_key"

After editing the config, restart Codex so it can load the ContextStream MCP server.

Claude Code (CLI)

Add ContextStream to Claude Code by running this command from your project directory:

Terminal

claude mcp add --transport stdio contextstream --env CONTEXTSTREAM_API_URL=https://api.contextstream.io --env CONTEXTSTREAM_API_KEY=your_api_key -- contextstream-mcp

Windows caveat (native Windows, not WSL): use cmd /c contextstream-mcp after --.

Alternative: add-json (stdio)

Terminal

claude mcp add-json contextstream \
'{"type":"stdio","command":"contextstream-mcp","args":[],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key"}}'

Tip: for team setups, prefer a committed .mcp.json file (project scope) instead of embedding keys in shell history.

This adds ContextStream to ~/.claude.json under your project's path, making it available when working in that directory.

MCP Scope Options:

• • Local (default): Private to you, current project only → stored in ~/.claude.json under project path
• • User (--scope user): Private to you, all projects → stored in ~/.claude.json globally
• • Project (--scope project): Shared with team → stored in .mcp.json in project root (commit to git)

For team sharing, use project scope to create a .mcp.json file that can be committed to git:

.mcp.json (project scope)

After adding the MCP server, restart Claude Code for changes to take effect. Verify the server is loaded with claude mcp list. For project-scoped servers from .mcp.json, Claude Code will prompt for approval on first use.

Claude Desktop (GUI App)

Add ContextStream to the Claude Desktop application:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

After editing the config, quit and restart Claude Desktop for changes to take effect.

Windsurf

Add ContextStream to Windsurf by editing the global MCP config file:

Config: ~/.codeium/windsurf/mcp_config.json

~/.codeium/windsurf/mcp_config.json

Rules files:

• • Global: ~/.codeium/windsurf/memories/global_rules.md
• • Project: .windsurf/rules/contextstream.md

Windsurf supports hooks for automatic enforcement of ContextStream rules. After editing the config, restart Windsurf for changes to take effect.

Cline

Add ContextStream to your Cline MCP configuration. Click the MCP Servers icon in Cline, select the "Configure" tab, then click "Configure MCP Servers" to edit:

cline_mcp_settings.json

After editing the config, restart Cline for changes to take effect. You can also use alwaysAllow to auto-approve specific tools.

Kilo Code

Add ContextStream to your Kilo Code MCP configuration. You can configure MCP servers globally or per-project:

Global: Click Settings → MCP Servers → Installed → Edit Global MCP to open mcp_settings.json

Project: .kilocode/mcp.json in your project root

.kilocode/mcp.json (or mcp_settings.json)

Project-level configs take precedence over global configs. Restart Kilo Code after editing.

Roo Code

Add ContextStream to your Roo Code MCP configuration. You can configure MCP servers globally or per-project:

Global: Click the settings icon → Edit Global MCP to open mcp_settings.json

Project: .roo/mcp.json in your project root

.roo/mcp.json (or mcp_settings.json)

Project-level configs take precedence over global configs. Restart Roo Code after editing.

Antigravity (Google)

Antigravity uses project-scoped .mcp.json files with the same format as Cursor/Claude Desktop:

.mcp.json (project root)

Windows users: Use cmd wrapper

.mcp.json (Windows)

{
  "mcpServers": {
    "contextstream": {
      "command": "cmd",
      "args": ["/c", "contextstream-mcp"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "your_api_key"
      }
    }
  }
}

Rules files:

• • Global: ~/.gemini/GEMINI.md
• • Workspace: .agent/rules/contextstream.md

Access via the "..." menu → "MCP Servers" → "View raw config" to verify your configuration. Restart Antigravity after editing.

Improve Automatic ContextStream Usage

Recommended

ContextStream's auto-context feature loads workspace context automatically when you use any ContextStream tool. However, AI assistants may not always proactively save decisions or recall past context. Adding editor AI rules improves consistency and ensures the AI automatically captures decisions, preferences, and important context throughout your conversations.

Critical: MCP Tool Naming Conventions

Different AI tools use different naming conventions for MCP tools. Using the wrong format will cause tools to not be found.

AI Tool	Tool Name Format	Example
Claude Code	mcp____	mcp__contextstream__session_init
Codex CLI	(raw name)	session_init
Cursor / Windsurf / Cline	(raw name)	session_init
Kilo Code / Roo Code	(raw name)	session_init

Summary: Only Claude Code uses the mcp__contextstream__ prefix. All other tools use raw tool names.

You can add ContextStream rules at two levels: Global (applies to all projects) or Project (applies to one project).

Global Rules (All Projects)

Add these once and they'll apply to every project automatically:

Editor	Global Rules Location
Cursor	Settings → General → Rules for AI
Windsurf	~/.codeium/windsurf/memories/global_rules.md
Cline	~/Documents/Cline/Rules/ folder
Kilo Code	~/.kilocode/rules/ folder
Roo Code	~/.roo/rules/ folder
Claude Code	~/.claude/CLAUDE.md
Codex CLI	~/.codex/AGENTS.md (global) or parent folder (e.g. ~/dev/AGENTS.md)

Project Rules (Single Project)

Add these to a specific project. For Cursor folder-based rules, set the activation mode to "Always On" so the rules are always active.

Editor	Project Rules Location
Cursor	.cursorrules or .cursor/rules/*.mdc
Windsurf	.windsurf/rules/contextstream.md
Cline	.clinerules file or .clinerules/ folder
Kilo Code	.kilocode/rules/ folder
Roo Code	.roo/rules/contextstream.md file or .roo/rules/ folder
Claude Code	CLAUDE.md in project root
Codex CLI	AGENTS.md in project root
Aider	.aider.conf.yml in project root

Activation Modes (Cursor, Kilo Code & Roo Code)

When using folder-based rules (e.g., .cursor/rules/), each rule file has an activation mode:

• Always On — Always active (recommended for ContextStream)
• Manual — Only when you @mention the rule
• Model Decision — AI decides based on description
• Glob — Active for matching file patterns

Global rules and root-level files (.cursorrules) are always active.

Prefer the setup wizard? Run it first. Otherwise, add these standard rules manually. Examples for each editor:

Claude Code

For Claude Code, create a CLAUDE.md file in your project root or add to your global ~/.claude/CLAUDE.md:

CLAUDE.md (Standard)

## 🚨 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

Show enhanced rules (verbose)

CLAUDE.md (Enhanced)

---

ContextStream v0.4.x Integration (Enhanced)

You have access to ContextStream MCP tools for persistent memory and context. v0.4.x uses ~11 consolidated domain tools for ~75% token reduction vs previous versions. Rules Version: 0.4.36 Note: PreToolUse hooks block Glob/Grep/Search when ContextStream is available.

TL;DR - REQUIRED EVERY MESSAGE

Message	What to Call
1st message	mcp__contextstream__session_init(folder_path="...", context_hint="<user's message>"), then mcp__contextstream__context_smart(user_message="<user's message>", format="minified", max_tokens=400)
2nd+ messages	mcp__contextstream__context_smart(user_message="<user's message>", format="minified", max_tokens=400)
🔍 ANY code search	mcp__contextstream__search(mode="hybrid", query="...") — ALWAYS before Glob/Grep/Search/Read
Before risky/non-trivial work	mcp__contextstream__session(action="get_lessons", query="<topic>")
After completing task	mcp__contextstream__session(action="capture", event_type="decision", ...) - MUST capture
User frustration/correction	mcp__contextstream__session(action="capture_lesson", ...) - MUST capture lessons

NO EXCEPTIONS. Do not skip even if you think you have enough context.

First message rule: After session_init, always call context_smart before any other tool or response.

Context Pack (Pro+): If enabled, use mcp__contextstream__context_smart(..., mode="pack", distill=true) for code/file queries. If unavailable or disabled, omit mode and proceed with standard context_smart (the API will fall back).

Tool naming: Use the exact tool names exposed by your MCP client. Claude Code typically uses mcp__<server>__<tool> where <server> matches your MCP config (often contextstream). If a tool call fails with "No such tool available", refresh rules and match the tool list.

---

Consolidated Domain Tools Architecture

v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:

Standalone Tools (Always Call)

• session_init - Initialize session with workspace detection + context
• context_smart - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after session_init)

Domain Tools (Use action/mode parameter)

Domain	Actions/Modes	Example
search	mode: semantic, hybrid, keyword, pattern, exhaustive, refactor	mcp__contextstream__search(mode="hybrid", query="auth implementation", limit=3)
session	action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace	mcp__contextstream__session(action="capture", event_type="decision", title="Use JWT", content="...")
memory	action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary	mcp__contextstream__memory(action="list_events", limit=10)
graph	action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions	mcp__contextstream__graph(action="impact", symbol_name="AuthService")
project	action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local	mcp__contextstream__project(action="statistics")
workspace	action: list, get, associate, bootstrap	mcp__contextstream__workspace(action="list")
reminder	action: list, active, create, snooze, complete, dismiss	mcp__contextstream__reminder(action="active")
integration	provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues	mcp__contextstream__integration(provider="github", action="search", query="...")
help	action: tools, auth, version, editor_rules, enable_bundle	mcp__contextstream__help(action="tools")

---

Why context_smart is Required (Even After session_init)

Common mistake: "session_init already gave me context, I don't need context_smart"

This is WRONG. Here's why:

• session_init returns the last ~10 items BY TIME (chronological)
• context_smart SEARCHES for items RELEVANT to THIS message (semantic)

Example failure:

• User asks: "how should I implement authentication?"
• Auth decisions were made 20 conversations ago
• session_init won't have it (too old, not in recent 10)
• context_smart FINDS it via semantic search

Without context_smart, you WILL miss relevant older context.

---

Search & Code Intelligence (ContextStream-first)

⚠️ STOP: Before using Search/Glob/Grep/Read/Explore → Call mcp__contextstream__search(mode="hybrid") FIRST. Use local tools ONLY if ContextStream returns 0 results.

❌ WRONG workflow (wastes tokens, slow):

Grep "function" → Read file1.ts → Read file2.ts → Read file3.ts → finally understand

✅ CORRECT workflow (fast, complete):

mcp__contextstream__search(mode="hybrid", query="function implementation") → done (results include context)

Why? ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.

Search Mode Selection:

Need	Mode	Example
Find code by meaning	hybrid	"authentication logic", "error handling"
Exact string/symbol	keyword	"UserAuthService", "API_KEY"
File patterns	pattern	".sql", "test_.py"
ALL matches (grep-like)	exhaustive	"TODO", "FIXME" (find all occurrences)
Symbol renaming	refactor	"oldFunctionName" (word-boundary matching)
Conceptual search	semantic	"how does caching work"

Token Efficiency: Use output_format to reduce response size:

• full (default): Full content for understanding code
• paths: File paths only (80% token savings) - use for file listings
• minimal: Compact format (60% savings) - use for refactoring
• count: Match counts only (90% savings) - use for quick checks

---

---

When user asks to create a plan or implementation roadmap:

1. Create plan: mcp__contextstream__session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])
2. Get plan_id from response, then create tasks: mcp__contextstream__memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")

To manage existing plans/tasks:

• List plans: mcp__contextstream__session(action="list_plans")
• Get plan with tasks: mcp__contextstream__session(action="get_plan", plan_id="<uuid>", include_tasks=true)
• List tasks: mcp__contextstream__memory(action="list_tasks", plan_id="<uuid>") or mcp__contextstream__memory(action="list_tasks") for all
• Update task status: mcp__contextstream__memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")

---

Rules Update Notices

• If you see [RULES_NOTICE], update rules via mcp__contextstream__generate_rules(overwrite_existing=true) (preserves custom rules).
• If you see [VERSION_NOTICE], tell the user to update MCP using the provided command.

See full documentation: https://contextstream.io/docs/mcp/tools

#### Codex CLI

For Codex CLI, create an `AGENTS.md` file in your project root (project rules) or in `~/.codex/AGENTS.md` (global rules) to provide rules to Codex:

Important: Codex vs Claude Tool Names

**Codex CLI** uses raw MCP tool names (e.g., `session_init`).**Claude Code** uses namespaced tool names (e.g., `mcp__contextstream__session_init`). Use the correct format for your AI tool.

AGENTS.md (Standard)

<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>

---

| Action | Tool Call |
|--------|-----------|
| **1st message** | `session_init(folder_path="<cwd>", context_hint="<msg>")` then `context_smart(...)` |
| **2nd+ messages** | `context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `session(action="capture", event_type="decision", ...)` |

### Search Modes

| Mode | Use Case |
|------|----------|
| `hybrid` | General code search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |

❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `search(mode="hybrid")` (1 call, returns context)

| Tool | Example |
|------|---------|
| `search` | `search(mode="hybrid", query="auth", limit=3)` |
| `session` | `session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `memory(action="list_events", limit=10)` |
| `graph` | `graph(action="dependencies", file_path="...")` |

- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`

When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `session(action="capture_plan", title="...", steps=[...])`
2. `memory(action="create_task", title="...", plan_id="<id>")`

AGENTS.md (Enhanced)

---

Message	What to Call
1st message	session_init(folder_path="...", context_hint="<user's message>"), then context_smart(user_message="<user's message>", format="minified", max_tokens=400)
2nd+ messages	context_smart(user_message="<user's message>", format="minified", max_tokens=400)
🔍 ANY code search	search(mode="hybrid", query="...") — ALWAYS before Glob/Grep/Search/Read
Before risky/non-trivial work	session(action="get_lessons", query="<topic>")
After completing task	session(action="capture", event_type="decision", ...) - MUST capture
User frustration/correction	session(action="capture_lesson", ...) - MUST capture lessons

Context Pack (Pro+): If enabled, use context_smart(..., mode="pack", distill=true) for code/file queries. If unavailable or disabled, omit mode and proceed with standard context_smart (the API will fall back).

---

Domain	Actions/Modes	Example
search	mode: semantic, hybrid, keyword, pattern, exhaustive, refactor	search(mode="hybrid", query="auth implementation", limit=3)
session	action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace	session(action="capture", event_type="decision", title="Use JWT", content="...")
memory	action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary	memory(action="list_events", limit=10)
graph	action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions	graph(action="impact", symbol_name="AuthService")
project	action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local	project(action="statistics")
workspace	action: list, get, associate, bootstrap	workspace(action="list")
reminder	action: list, active, create, snooze, complete, dismiss	reminder(action="active")
integration	provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues	integration(provider="github", action="search", query="...")
help	action: tools, auth, version, editor_rules, enable_bundle	help(action="tools")

---

---

⚠️ STOP: Before using Search/Glob/Grep/Read/Explore → Call search(mode="hybrid") FIRST. Use local tools ONLY if ContextStream returns 0 results.

✅ CORRECT workflow (fast, complete):

search(mode="hybrid", query="function implementation") → done (results include context)

---

---

When user asks to create a plan or implementation roadmap:

1. Create plan: session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])
2. Get plan_id from response, then create tasks: memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")

To manage existing plans/tasks:

• List plans: session(action="list_plans")
• Get plan with tasks: session(action="get_plan", plan_id="<uuid>", include_tasks=true)
• List tasks: memory(action="list_tasks", plan_id="<uuid>") or memory(action="list_tasks") for all
• Update task status: memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")

---

• If you see [RULES_NOTICE], update rules via generate_rules(overwrite_existing=true) (preserves custom rules).
• If you see [VERSION_NOTICE], tell the user to update MCP using the provided command.

#### Windsurf

For Windsurf, create a `.windsurf/rules/contextstream.md` file in your project root or add to your global `~/.codeium/windsurf/memories/global_rules.md`:

.windsurf/rules/contextstream.md (Standard)

---

### Search Modes

.windsurf/rules/contextstream.md (Enhanced)

---

---

---

---

---

---

---

#### Kilo Code

For Kilo Code, create a Markdown file in `.kilocode/rules/`:

.kilocode/rules/contextstream.md (Standard)

---

### Search Modes

.kilocode/rules/contextstream.md (Enhanced)

---

---

---

---

---

---

---

#### Cline

For Cline, create a `.clinerules` file in your project root or use the `.clinerules/` folder:

.clinerules (Standard)

---

### Search Modes

.clinerules (Enhanced)

---

---

---

---

---

---

---

#### Roo Code

For Roo Code, create a `.roo/rules/contextstream.md` file or use the `.roo/rules/` folder:

.roo/rules/contextstream.md (Standard)

---

### Search Modes

.roo/rules/contextstream.md (Enhanced)

---

---

---

---

---

---

---

Auto-Generate Rules

You can also ask the AI to generate these rules automatically by saying:"Use generate\_rules to create ContextStream rules for this project"

## Lessons Learned System

Learn From Mistakes - Never Repeat Them

The Lessons System captures mistakes, corrections, and user frustrations so AI assistants never repeat the same errors. Lessons are automatically surfaced in `session_init` and `context_smart` responses when relevant.

### When to Capture Lessons

Lessons should be captured automatically when any of these situations occur:

| Trigger           | Example User Message                              | Severity    |
| ----------------- | ------------------------------------------------- | ----------- |
| Production issue  | "The site is down because of that change"         | critical    |
| User frustration  | "NO! I told you NOT to do that", "WTF", caps lock | high        |
| Correction        | "That's wrong, you should...", "Fix this"         | medium      |
| Breaking change   | "This broke the tests", "The build failed"        | medium/high |
| Preference stated | "I prefer it this way", "Always do X instead"     | low         |

### Lesson Fields Explained

| Field      | Description                                                             | Example                                                  |
| ---------- | ----------------------------------------------------------------------- | -------------------------------------------------------- |
| title      | What to remember (imperative)                                           | "Always verify assets in git before pushing"             |
| severity   | critical, high, medium, low                                             | "critical" for production issues                         |
| category   | workflow, code\_quality, verification, communication, project\_specific | "workflow"                                               |
| trigger    | What action caused the problem                                          | "Pushed code referencing images without committing them" |
| impact     | What went wrong                                                         | "Production 404 errors - broken landing page"            |
| prevention | How to prevent in future                                                | "Run git status to check untracked files before pushing" |
| keywords   | Keywords for matching in future contexts                                | \["git", "images", "assets", "push"\]                    |

### Full Example

session\_capture\_lesson call

// User says: "OH COME ON! You pushed the code but the images are missing // and now the production site shows broken images!"

session_capture_lesson({ title: "Always verify assets in git before pushing code references", severity: "critical", category: "workflow", trigger: "Pushed code referencing /screenshots/*.png without committing images", impact: "Production 404 errors - broken landing page with missing images", prevention: "Run 'git status' to check untracked files before pushing code that references static assets", keywords: ["git", "images", "assets", "push", "404", "static", "screenshots"] })

### How Lessons Are Surfaced

Captured lessons are automatically returned in future sessions when relevant:

#### `session_init`

High and critical severity lessons from this workspace are included in session initialization, warning the AI before it can make the same mistake.

#### `context_smart`

When the AI asks for context, lessons matching the query keywords are included. E.g., asking about "git push" surfaces lessons with "git" or "push" keywords.

### Retrieving Lessons

Use `session_get_lessons` to retrieve and filter lessons:

session\_get\_lessons examples

// Get all critical lessons session_get_lessons({ severity: "critical" })

// Get workflow lessons session_get_lessons({ category: "workflow" })

// Search for relevant lessons session_get_lessons({ query: "git push images" })

// Combine filters session_get_lessons({ category: "verification", severity: "high", limit: 5 })

**Pro tip:** Add rules to your editor (see Editor AI Rules section above) to automatically capture lessons when users express frustration or corrections. This builds a knowledge base that prevents repeated mistakes.

## MCP Tools

See the full MCP tool reference (PRO badges and common usage examples).

View MCP Tools Reference

v0.4.x uses \~11 consolidated domain tools for \~75% token reduction vs previous versions.

## Usage Examples

Once connected, you can ask your AI assistant things like:

"Remember that we decided to use PostgreSQL for the database"

"What were our previous decisions about authentication?"

"Search our codebase for how we handle API rate limiting"

"Show me related context about the payment system"

### Lesson Examples

The AI should automatically capture lessons when you express frustration or corrections:

User says:

"NO! You pushed without running tests and now production is broken!"

→ AI captures lesson with severity: critical, category: verification

User says:

"That's wrong. Always use snake\_case for database columns, not camelCase."

→ AI captures lesson with severity: medium, category: code\_quality

User says:

"I prefer TypeScript strict mode. Please always enable it."

→ AI captures lesson with severity: low, category: project\_specific

These lessons are automatically surfaced in future sessions when relevant context is requested.

## Keeping Up to Date

To get the latest features, bug fixes, and improvements, update the MCP server periodically:

Alternative: npm (requires Node.js 18+)

Terminal

npm install -g @contextstream/mcp-server@latest

The MCP server will automatically warn you when a newer version is available. After updating, restart your AI tool to use the new version.

## Troubleshooting

### MCP server not starting

Ensure `contextstream-mcp` is installed and available in your PATH. Try running `contextstream-mcp --version` manually to check for errors.

### Authentication errors

Verify your API key is correct and has not expired. You can generate a new key from your ContextStream dashboard.

### Tools not appearing

Restart your AI application after modifying the config. Check the application logs for MCP connection errors.

### No workspace found (first-time setup)

If your account has no workspaces yet, ContextStream will prompt your AI assistant to ask you for a workspace name. The current folder will be created as a project. See MCP Tools for `workspace_bootstrap`.

## Next Steps

### Team Setup

Invite members, share context

### Lessons Learned

Capture mistakes, never repeat them

### Memory Events

Learn about memory types

### Semantic Search

Search by meaning