Finding things
Images, video, audio, and documents
Index a screenshot, recording, audio file, PDF, or other document; search what is inside it and extract the part you need.
“index this design PDF”
Its text extracted and searchable.
“what's in that architecture video?”
The transcript, with timestamps.
“find the screenshot with the timeout error”
The image, matched on the text inside it.
Media is first-class project context. It does not have to be converted into a Markdown note before your assistant can use it.
When a task mentions an error shown in a screenshot, a rule buried in a PDF, or a design choice explained in a recording, the assistant can choose that evidence path itself. You do not need to translate every non-code artifact into a prompt first.
What it handles
| Type | What's extracted |
|---|---|
| Images and screenshots | Visible text plus a description of what the image depicts |
| Video | A timestamped transcript and representative visual context |
| Audio | A timestamped transcript |
| Documents and PDFs | Text from ordinary and scanned pages, with OCR when needed |
Why bother
The spec is a PDF. The architecture walkthrough is a recording. The bug report is a screenshot. Indexed, these answer questions instead of sitting in a folder — "what did the spec say about rate limits" works when the spec is a PDF nobody has read since March.
Adding a file or URL
Ask—“index this PDF,” “read this screenshot,” or “add that recording”—with a local path or an external URL. Add tags when a future search is likely to use a project name, customer, meeting, or incident that does not appear in the asset itself.
Local files are normally kept inside the active project boundary. Broad outside-project ingest requires an explicit opt-in, and it still does not bypass secret filtering or size limits.
contextstream-mcp index --include-media extends a folder index to cover the
media in it.
Processing and status
Media processing is asynchronous. A short image may finish quickly; a recording or scanned document can take longer. Ask for the asset's status before assuming that an empty search means failure.
You can list the assets available in the current scope, narrow the list by image, video, audio, or document, inspect an individual processing state, and remove an asset that should no longer be retained.
Searching inside it
Search by what the asset says or shows:
find the screenshot that contains "token expired"where in the architecture recording do they explain the retry queue?what does the retention PDF say about support exports?Search can be narrowed to one or more content types. That prevents a common “media” query from being drowned out by ordinary source or session results.
From a screenshot to a fixable bug
A support report contains only a screenshot. The visible error says
upstream request timeout after 30000ms, and the image also shows which page
and account flow produced it.
Index the screenshot, wait until its status says it is ready, then search for the timeout text. Use the extracted match to find the corresponding source constant and request path. Attach the screenshot to the resulting ticket so the evidence stays with the work.
That sequence matters. A screenshot search can tell you what text and visual context were present; source search can tell you where the timeout is set. Neither proves the cause by itself. A good ticket keeps the original image, the matched text, the suspected code path, and the reproduction gap separate.
The same pattern works across formats:
- search a retention PDF for the clause that constrains a support export, then cite the source document in the decision;
- find where an architecture recording explains the retry queue, extract only that timestamp range, and attach the clip to a handoff;
- index a scanned design deck, confirm OCR is complete, and compare its stated empty-state behavior with the current implementation.
Clipping video and audio
extract 1:34 to 2:15 from that recordingUseful for pulling the thirty seconds that matter out of an hour-long call and attaching it to a ticket, handoff, review, or capsule. A clip request can return the raw result or the corresponding FFmpeg or Remotion instructions when another workflow will render it.
Media documents and written documents
A PDF, slide deck, or uploaded document is a media asset: ContextStream extracts and searches what is inside the file.
A ContextStream document is a durable Markdown record such as a runbook, ADR, PRD, or postmortem. Use that when the content should be edited and maintained as project knowledge. It is fine to keep both: the source PDF as evidence and a written decision or runbook derived from it.
Access and deletion
Assets inherit the current workspace and project scope. Personal and shared access still apply. Indexing a file does not turn it into a public link; use a capsule when someone outside the workspace needs a controlled share.
Deleting the media record removes it from the media collection and search. It does not delete the original local file or external URL.
If it doesn't work
A PDF indexed but the text isn't searchable. A scanned page with no text layer needs OCR, which takes longer. Check its status before concluding it failed.
A video is still processing. Long recordings take a while. Status tells you where it is.
The transcript has technical terms wrong. Expected for jargon and product names. Search around them — the surrounding sentence is usually right.
A local file is rejected. It may sit outside the active project, match a secret or credential rule, exceed the size cap, or use an unsupported content type. Move it into scope or make only the narrow opt-in you intend.
The wrong project sees it. Check scope before indexing. An asset belongs to the workspace and project selected at ingest time.