ContextStream MCP Integration

Persistent memory and cross-session learning for AI coding assistants. Cloud-based context management via MCP with semantic code search, dependency analysis, and intelligent session tracking.

Overview

ContextStream v0.4.x provides ~11 consolidated domain tools for ~75% token reduction vs previous versions. It enables AI assistants to maintain context across sessions, learn from mistakes, and leverage semantic code search.

Required Tool Calls

Every Message Pattern

| Message | Required Tool Calls |

|---------|-------------------|

| **First message** | 1. `session_init(folder_path="<cwd>", context_hint="<user_message>")`<br>2. `context_smart(user_message="<user_message>", format="minified", max_tokens=400)` |

| **Second+ messages** | `context_smart(user_message="<user_message>", format="minified", max_tokens=400)` |

| **Capture decisions** | `session(action="capture", event_type="decision", title="...", content="...")` |

| **Before risky work** | `session(action="get_lessons", query="<topic>")` |

| **On user frustration** | `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")` |

Context Pack (Pro+)

For code/file queries with Context Pack enabled:

```

context_smart(user_message="...", mode="pack", distill=true, format="minified", max_tokens=400)

```

If unavailable or disabled, omit `mode` parameter and the API will fall back to standard context retrieval.

Core Domain Tools

1. Search Tool

Semantic, hybrid, keyword, and pattern-based code search:

```

search(mode="semantic", query="authentication logic", limit=3)

search(mode="hybrid", query="database connection", limit=5)

search(mode="keyword", query="TODO", limit=10)

search(mode="pattern", query="*.config.js", limit=5)

```

**Modes:**

2. Session Tool

Session management, context retrieval, and learning:

```

session(action="capture", event_type="decision", title="Use PostgreSQL", content="...")

session(action="capture_lesson", title="Avoid X pattern", trigger="...", impact="...", prevention="...")

session(action="get_lessons", query="database migrations")

session(action="recall", query="previous authentication approach")

session(action="summary", session_id="<uuid>")

session(action="smart_search", query="error handling patterns")

```

**Common Actions:**

3. Memory Tool

CRUD operations for events, nodes, decisions, and timeline:

```

memory(action="list_events", event_type="decision", limit=10)

memory(action="create_event", event_type="milestone", title="...", content="...")

memory(action="search_events", query="refactoring decisions")

memory(action="create_task", title="Implement auth", priority="high", description="...")

memory(action="update_task", task_id="<uuid>", task_status="in_progress")

memory(action="list_tasks", plan_id="<uuid>")

```

4. Graph Tool

Dependency analysis and code relationships:

```

graph(action="dependencies", entity="UserService")

graph(action="impact", entity="database.config")

graph(action="call_path", source="login", target="validateUser")

graph(action="related", entity="auth.middleware")

graph(action="ingest", path="<cwd>")

```

5. Project Tool

Project management and indexing:

```

project(action="list")

project(action="get", project_id="<uuid>")

project(action="index_status")

project(action="ingest_local", path="<cwd>")

project(action="overview")

project(action="statistics")

```

6. Workspace Tool

Workspace and project association:

```

workspace(action="list")

workspace(action="get", workspace_id="<uuid>")

workspace(action="associate", project_id="<uuid>", workspace_id="<uuid>")

workspace(action="bootstrap", name="My Workspace")

```

7. Integration Tool

GitHub and Slack integration:

```

integration(provider="github", action="search", query="authentication")

integration(provider="github", action="get_issue", issue_number="123")

integration(provider="slack", action="search", query="deployment notes")

```

8. Help Tool

Tool documentation and version info:

```

help(action="tools")

help(action="auth")

help(action="version")

help(action="editor_rules")

```

Behavior Rules

Critical Search Priority

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

Session Workflow

1. **First message**: Call `session_init` with `context_hint`, then `context_smart` before any other tool or response

2. **Every subsequent message**: Always call `context_smart` BEFORE responding

3. **After completing work**: Always capture decisions/insights with `session(action="capture")`

4. **On mistakes/corrections**: Immediately capture lessons with `session(action="capture_lesson")`

Code Indexing

Discovery Pattern

1. Use `session(action="smart_search")` or `search(mode="hybrid")` first

2. NEVER use local Glob/Grep/Read first

3. For file/function/config lookups: Use `search`/`graph` first

4. Only fall back to local tools (`rg`/`ls`/`find`) if ContextStream returns no results

5. If ContextStream returns results: Do NOT use local Search/Explore/Read; only open specific files when needed for exact edits

Code Analysis

Use `graph(action="dependencies")` or `graph(action="impact")` for call/dependency analysis instead of manual code traversal.

Plans & Tasks

Creating Plans

```

session(action="capture_plan",

title="Feature X Implementation",

description="...",

goals=["goal1", "goal2"],

steps=[

{id: "1", title: "Design phase", order: 1},

{id: "2", title: "Implementation", order: 2}

]

)

```

Creating Tasks

```

memory(action="create_task",

title="Implement authentication",

plan_id="<plan_uuid>",

priority="high",

description="..."

)

```

Managing Plans & Tasks

Tool Naming Convention

Use exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`).

Example:

```

mcp__contextstream__search(mode="semantic", query="...")

mcp__contextstream__session(action="capture", ...)

```

If a tool call fails with "No such tool available", refresh rules and match the tool list from your MCP client.

Special Response Codes

Best Practices

1. **Always start sessions properly**: `session_init` + `context_smart` on first message

2. **Leverage semantic search**: Use `search(mode="hybrid")` before local file tools

3. **Capture learning**: Record decisions and lessons immediately

4. **Check lessons before risky work**: Use `session(action="get_lessons")` to avoid repeating mistakes

5. **Use graph analysis**: Leverage `graph` tool for dependency/impact analysis instead of manual traversal

6. **Keep context fresh**: Call `context_smart` every message for relevant context

7. **Index early**: Run `project(action="ingest_local")` for semantic search capabilities

Resources

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