---
name: contextstream-workflow
description: "Manage persistent AI memory across sessions with ContextStream MCP."
---

# ContextStream Workflow Skill

## Purpose

Use ContextStream to keep plans, tasks, decisions, lessons, and implementation context available across Copilot sessions.

## Session Lifecycle

### 1. Start the session

Always call `init` at the beginning of a new session:

```
init(
  folder_path="<project_path>",
  context_hint="<user's first message>"
)
```

Then call `context` with the current request:

```
context(
  user_message="<current user message>"
)
```

For later messages in the same session, call `context` first before doing more work.

### 2. Plan multi-step work

Capture a persistent plan:

```
session(
  action="capture_plan",
  title="Implement feature X",
  steps=[
    {"id": "1", "title": "Research the current code path", "order": 1},
    {"id": "2", "title": "Implement the change", "order": 2},
    {"id": "3", "title": "Add verification", "order": 3}
  ]
)
```

Then create linked tasks:

```
memory(
  action="create_task",
  title="Implement the change",
  plan_id="<plan_id>",
  plan_step_id="2",
  priority="high"
)
```

### 3. Track progress while working

Start a task:

```
memory(
  action="update_task",
  task_id="<task_id>",
  status="in_progress"
)
```

Capture a technical decision:

```
session(
  action="capture",
  event_type="decision",
  title="Use repository pattern for data access",
  content="Chose a repository layer to isolate persistence logic and simplify testing."
)
```

Finish a task:

```
memory(
  action="update_task",
  task_id="<task_id>",
  status="completed"
)
```

### 4. Capture lessons

When a mistake or correction happens, save a lesson immediately:

```
session(
  action="capture_lesson",
  title="Check pagination behavior before assuming full results",
  trigger="Assumed the API returned all records in one response",
  impact="Only the first page was processed",
  prevention="Verify pagination semantics before implementing the fetch path",
  severity="medium"
)
```

### 5. Finish the work

Update the plan:

```
session(
  action="update_plan",
  plan_id="<plan_id>",
  status="completed"
)
```

Capture a summary event:

```
memory(
  action="create_event",
  event_type="implementation",
  title="Feature X complete",
  content="Implemented the change, added tests, and verified the result."
)
```

## Search-First Workflow

- Before local code discovery, use `search(mode="auto", query="...")`
- Use `search(mode="keyword")` for exact symbols or strings
- Use `search(mode="pattern")` for glob or regex-style lookup
- Use local reads only after search narrows the file set

## Quick Reference

| Need | Tool |
|------|------|
| Relevant project context | `context(user_message="...")` |
| Code discovery | `search(mode="auto", query="...")` |
| Persistent plan | `session(action="capture_plan")` |
| Task status | `memory(action="update_task")` |
| Decision capture | `session(action="capture", event_type="decision")` |
| Update skill by name | `skill(action="update", name="...", instruction_body="...", change_summary="...")` |
| Past context | `session(action="recall", query="...")` |
| Lessons | `session(action="get_lessons", query="...")` |

## Anti-Patterns

- Do not store trivial file reads or command output as memory
- Do not skip `context(...)` on later turns
- Do not use local file scanning before `search(...)`; for stale/not-indexed projects, wait ~20s for refresh and retry first, then local fallback is allowed
- Do not use editor-only task lists as the persistent record; mirror important work in ContextStream