ContextStream MCP Integration

Persistent memory and cross-session learning for AI coding assistants. Cloud-based context management via MCP (Model Context Protocol) for semantic code search, dependency analysis, and workflow continuity.

What This Skill Does

Enables AI assistants to maintain context across sessions using the ContextStream MCP server. Provides semantic code search, dependency analysis, decision capture, and lesson learning with ~75% token reduction through consolidated domain tools.

Key Features

Instructions

Initial Setup (v0.4.x)

**Tool Naming Convention**: Use the exact tool names exposed by your MCP client. Most clients use `mcp__<server>__<tool>` format where `<server>` matches your MCP config (typically `contextstream`). If a tool call fails with "No such tool available", verify the tool name matches your client's exposed tools.

Required Calls for Every Message

| Message Type | Required Actions |

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

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

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

| **After completing work** | `session(action="capture", event_type="decision", title="...", content="...")` |

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

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

Context Pack (Pro+ Feature)

For code/file queries, use enhanced context packing when available:

```

context_smart(..., mode="pack", distill=true)

```

If unavailable or disabled, omit `mode` parameter and proceed with standard `context_smart`.

Core Domain Tools

| Tool | Purpose | Example Usage |

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

| `search` | Find code, files, patterns | `search(mode="semantic", query="authentication logic", limit=3)` |

| `session` | Session management & memory | `session(action="capture", event_type="decision", ...)` |

| `memory` | Event/node CRUD operations | `memory(action="list_events", limit=10)` |

| `graph` | Dependency & impact analysis | `graph(action="dependencies", identifier="functionName")` |

| `project` | Project management & indexing | `project(action="list")` or `project(action="ingest_local", path="<cwd>")` |

| `workspace` | Workspace operations | `workspace(action="list")` |

| `integration` | GitHub/Slack integration | `integration(provider="github", action="search", query="...")` |

| `help` | Documentation & rules | `help(action="tools")` |

Critical Behavior Rules

1. **STOP Before Local Search**: ALWAYS call `search(mode="hybrid")` FIRST before using any local Search/Glob/Grep/Read/Explore tools. Only use local tools if ContextStream returns 0 results.

2. **Context-First Responses**: Never respond to user messages without first calling `context_smart` to retrieve relevant context.

3. **Ingest Recommendation**: On `[INGEST_RECOMMENDED]` notice, ask user: "Would you like to enable semantic code search? Indexing your codebase enables AI-powered code search, dependency analysis, and better context. This takes a few minutes." If user agrees, run the provided `project(action="ingest_local")` command.

4. **Index Status Checks**: Before searching files/code, check `project(action="index_status")`. If missing/stale, run `project(action="ingest_local", path="<cwd>")` or `project(action="index")`.

5. **Discovery Pattern**: Use `session(action="smart_search")` or `search(mode="hybrid")` for discovery. NEVER use local Glob/Grep/Read first.

6. **Rules Updates**: On `[RULES_NOTICE]`, use `generate_rules()` to update rules.

7. **No Redundant Local Reads**: If ContextStream returns results, do NOT use local Search/Explore/Read tools. Only open specific files when needed for exact edits.

Search Modes

Session Actions

| Action | Purpose | Example |

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

| `capture` | Record decisions/insights | `session(action="capture", event_type="decision", title="...", content="...")` |

| `capture_lesson` | Learn from mistakes | `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")` |

| `get_lessons` | Retrieve past lessons | `session(action="get_lessons", query="error handling")` |

| `recall` | Resume previous context | `session(action="recall", query="last refactoring session")` |

| `smart_search` | Advanced contextual search | `session(action="smart_search", query="...")` |

Plans & Tasks Management

**Create a Plan:**

```

session(action="capture_plan",

title="Feature Implementation Plan",

description="Implement user authentication",

goals=["Add OAuth", "Secure endpoints"],

steps=[{id: "1", title: "Setup OAuth", order: 1}, ...])

```

**Create Tasks:**

```

memory(action="create_task",

title="Configure OAuth Provider",

plan_id="<plan_id>",

priority="high",

description="Setup Google OAuth integration")

```

**Manage Existing Plans/Tasks:**

Graph Actions for Code Analysis

| Action | Purpose | Example |

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

| `dependencies` | Find what a symbol depends on | `graph(action="dependencies", identifier="calculateTotal")` |

| `impact` | Find what depends on a symbol | `graph(action="impact", identifier="userModel")` |

| `call_path` | Trace call hierarchy | `graph(action="call_path", from_id="main", to_id="helper")` |

| `related` | Find related code | `graph(action="related", identifier="authService")` |

| `ingest` | Index code for graph analysis | `graph(action="ingest", path="src/")` |

Usage Example

**First Message in Session:**

```

Initialize session

session_init(folder_path="/home/user/myproject", context_hint="implement user authentication")

Get relevant context

context_smart(user_message="implement user authentication", format="minified", max_tokens=400)

Search for existing auth code

search(mode="hybrid", query="authentication login", limit=5)

[Work on implementation]

Capture decision

session(action="capture", event_type="decision",

title="Chose JWT for auth",

content="Selected JWT over sessions for scalability")

```

**Subsequent Message:**

```

Always get context first

context_smart(user_message="add password reset feature", format="minified", max_tokens=400)

Check lessons before risky work

session(action="get_lessons", query="password reset security")

Search for related code

search(mode="semantic", query="password reset email", limit=3)

```

Important Notes

Documentation

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