ContextStream

Docs · Browse sections

01 · Setup wizard

One command, fully configured.

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 · terminal · macOS / Linux

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

terminal · powershell · Windows

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

Already installed? Re-run the setup wizard

terminal · terminal · re-run

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.

Consolidated 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

Team workflows

Shared memory, skills, and context surfacing.

Team accounts get more than shared projects. During contextstream-mcp setup, the wizard detects team capability and surfaces workspace tips. In your editor, every session(action="context") call can include team recommendations, governance cues, priority signals, and linked artifacts.

Pick the shared workspace

Link each repo to the team workspace during setup so indexing, decisions, and tickets stay aligned.

Share team skills

skill(action="share", scope="team") publishes reusable workflows teammates auto-match in session(action="context").

Switch execution scope

Dual-context accounts use --account-mode=team|personal|auto or session set_account_mode in MCP.

Track work with entities

Tickets, handoffs, incidents, and releases use indexed refs — durable across sessions and teammates.

Hosted remote is the default. Local binary MCP is recovery-only — set CONTEXTSTREAM_ALLOW_LOCAL_MCP=1 when explicitly needed. See team setup for invite/roles and the post-login checklist.

CLI shortcuts

Non-interactive commands (CI & refresh).

Run these without the interactive wizard — ideal after upgrades, team onboarding, credential rotation, or workspace changes. Also surfaced in contextstream-mcp --help.

Command When to use contextstream-mcp update-hooks --scope=global After upgrade or joining a team workspace — refresh PreToolUse/UserPromptSubmit hooks. contextstream-mcp update-rules --scope=all Regenerate .cursorrules / CLAUDE.md / AGENTS.md with latest team workflow guidance. contextstream-mcp update-configs --scope=global Rewrite MCP configs after API key or workspace changes. contextstream-mcp migrate-remote --scope=all Convert legacy local stdio configs to hosted remote transport. contextstream-mcp detect-editors --format=json Script which editors are installed (bootstrap/CI). contextstream-mcp generate-configs --transport=remote --preauth Emit JSON config payloads without writing files. contextstream-mcp configure --transcripts=on --scope=all Set transcript capture defaults non-interactively.

terminal · account mode · team vs personal

# Default: follow account (auto)
contextstream-mcp --account-mode=auto

# Force team-scoped reads/writes
contextstream-mcp --account-mode=team

# Or set once in shell profile:
export CONTEXTSTREAM_ACCOUNT_MODE=team

02 · Manual configuration

Per-client configs.

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

Consolidated toolset: By default, the server exposes ~11 consolidated domain tools (~75% token reduction vs legacy granular tools). 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 Code Windsurf Codex CLI OpenCode CLI Claude Code Claude Desktop Cline Kilo Code Roo Code Antigravity

What is MCP?

An open protocol for AI.

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

Natural language

Just ask. The AI handles the tools.

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 · "session summary"

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

Prerequisites

What you need.

• A ContextStream account (the setup wizard can create an API key via browser login).

Enrich context

GitHub + Slack integrations

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.

GitHubSync issues, PRs, releases, and comments. Decisions are automatically extracted from discussions.SlackSync channels and threads. High-engagement conversations are scored and prioritized.

Example prompts

• · "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

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

GitHub (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 (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

Client · Cursor / VS Code

Cursor / VS Code

Cursor and VS Code use different MCP config schemas. Cursor still uses a local MCP process, but VS Code/Copilot can now use the hosted ContextStream MCP directly over HTTP.

terminal · .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"
 }
 }
 }
}

Recommended for VS Code / Copilot: one-click remote install

Install the hosted ContextStream MCP and let VS Code handle OAuth on first use. No local binary or API key needs to live in .vscode/mcp.json.

Install in VS CodeVS Code MCP Docs

terminal · .vscode/mcp.json (VS Code native MCP, remote)

{
 "servers": {
 "contextstream": {
 "type": "http",
 "url": "https://mcp.contextstream.io/mcp?default_context_mode=fast"
 }
 }
}

Prefer command line? Add the remote server with code --add-mcp

terminal · terminal

code --add-mcp '{"name":"contextstream","type":"http","url":"https://mcp.contextstream.io/mcp?default_context_mode=fast"}'

On first use, VS Code should prompt to authorize ContextStream and then finish setup automatically.

Self-hosted? Point the same remote config at your own MCP gateway URL instead of https://mcp.contextstream.io/mcp?default_context_mode=fast.

Client · OpenCode CLI

OpenCode CLI

To use ContextStream with OpenCode CLI, add the MCP server configuration to your ~/.config/opencode/opencode.json file (or opencode.json in your project root):

terminal · ~/.config/opencode/opencode.json

{
 "$schema": "https://opencode.ai/config.json",
 "mcp": {
 "contextstream": {
 "type": "local",
 "command": ["contextstream-mcp"],
 "enabled": true,
 "environment": {
 "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
 "CONTEXTSTREAM_API_KEY": "your_api_key"
 }
 }
 }
}

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

Client · Codex CLI

Codex CLI

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

terminal · ~/.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.

Client · Claude Code

Claude Code (CLI)

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

terminal · 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 · terminal · add-json

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:

terminal · .mcp.json (project scope)

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

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.

Client · Claude Desktop

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

terminal · claude_desktop_config.json

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

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

Client · Windsurf

Windsurf

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

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

terminal · ~/.codeium/windsurf/mcp_config.json

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

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.

Client · Cline

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:

terminal · cline_mcp_settings.json

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

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

Client · Kilo Code

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

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

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

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

Client · Roo Code

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

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

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

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

Client · Antigravity

Antigravity (Google)

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

terminal · .mcp.json (project root)

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

Windows users: use cmd wrapper

terminal · .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.

Editor rules

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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

Search Modes

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

Lessons (Past Mistakes)

• After session_init: Check for lessons field and apply before work
• Before risky work: mcp__contextstream__session(action="get_lessons", query=" ")
• 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=" ")

Full docs: https://contextstream.io/docs/mcp/tools

 Show enhanced rules (verbose)

 terminal · CLAUDE.md (Enhanced)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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 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

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__ __ where 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)

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:

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

Lessons (Past Mistakes)

• After session_init: Check for lessons field and apply before work
• Before risky work: mcp__contextstream__session(action="get_lessons", query=" ")
• On mistakes: mcp__contextstream__session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")

Plans & Tasks

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=" ", 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=" ", include_tasks=true)
• List tasks: mcp__contextstream__memory(action="list_tasks", plan_id=" ") or mcp__contextstream__memory(action="list_tasks") for all
• Update task status: mcp__contextstream__memory(action="update_task", task_id=" ", 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 / OpenCode CLI

 Create an `AGENTS.md` file in your project root (project rules) or in `~/.codex/AGENTS.md` (Codex global) / `~/.config/opencode/AGENTS.md` (OpenCode global):

 Codex / OpenCode vs Claude tool names

 **Codex / OpenCode** use 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.

 terminal · AGENTS.md (Standard)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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

Search Modes

Why ContextStream First?

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

ContextStream search is indexed and returns semantic matches + context in ONE call.

Quick Reference

Lessons (Past Mistakes)

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

Plans & Tasks

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=" ")

Full docs: https://contextstream.io/docs/mcp/tools

 Show enhanced rules (verbose)

 terminal · AGENTS.md (Enhanced)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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 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

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 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__ __ where 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)

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 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):

 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:

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

Lessons (Past Mistakes)

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

Plans & Tasks

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=" ", 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=" ", include_tasks=true)
• List tasks: memory(action="list_tasks", plan_id=" ") or memory(action="list_tasks") for all
• Update task status: memory(action="update_task", task_id=" ", task_status="pending|in_progress|completed|blocked")

Rules Update Notices

• 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.

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

#### Windsurf

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

 terminal · .windsurf/rules/contextstream.md (Standard)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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

Search Modes

Why ContextStream First?

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

ContextStream search is indexed and returns semantic matches + context in ONE call.

Quick Reference

Lessons (Past Mistakes)

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

Plans & Tasks

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=" ")

Full docs: https://contextstream.io/docs/mcp/tools

 Show enhanced rules (verbose)

 terminal · .windsurf/rules/contextstream.md (Enhanced)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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 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

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 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__ __ where 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)

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 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):

 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:

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

Lessons (Past Mistakes)

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

Plans & Tasks

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=" ", 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=" ", include_tasks=true)
• List tasks: memory(action="list_tasks", plan_id=" ") or memory(action="list_tasks") for all
• Update task status: memory(action="update_task", task_id=" ", task_status="pending|in_progress|completed|blocked")

Rules Update Notices

• 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.

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

#### Kilo Code

 Create a Markdown file in `.kilocode/rules/`:

 terminal · .kilocode/rules/contextstream.md (Standard)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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

Search Modes

Why ContextStream First?

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

ContextStream search is indexed and returns semantic matches + context in ONE call.

Quick Reference

Lessons (Past Mistakes)

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

Plans & Tasks

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=" ")

Full docs: https://contextstream.io/docs/mcp/tools

 Show enhanced rules (verbose)

 terminal · .kilocode/rules/contextstream.md (Enhanced)

🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨

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

You MUST display the 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 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

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 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__ __ where 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)

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 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):

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

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 Format Example Claude Code mcp__ __ mcp__contextstream__session_init Codex CLI / OpenCode 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/ Kilo Code ~/.kilocode/rules/ Roo Code ~/.roo/rules/ Claude Code ~/.claude/CLAUDE.md Codex CLI ~/.codex/AGENTS.md (global) or parent folder (e.g. ~/dev/AGENTS.md) OpenCode CLI ~/.config/opencode/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/ Roo Code .roo/rules/contextstream.md or .roo/rules/ folder Claude Code CLAUDE.md in project root Codex CLI AGENTS.md in project root OpenCode 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

Create a CLAUDE.md file in your project root or add to your global ~/.claude/CLAUDE.md:

terminal · CLAUDE.md (Standard)