jhonny-editor/code/docs/project-context-engine.md

Project context engine

The project context engine reduces repeated clip, transcript, audio, and timeline analysis without placing customer footage or an entire Premiere project in every model prompt. It is an opt-in local index: no context is captured until an MCP client calls manage_project_context.

Storage and runtime compatibility

PREMIERE_CONTEXT_BACKEND=auto prefers Node's built-in SQLite store when the runtime provides node:sqlite. Supported Node 20 environments fall back to an atomic JSON store without adding a native package dependency. Operators can force sqlite, json, or non-persistent memory behavior. PREMIERE_CONTEXT_DIR overrides the OS application-data directory.

The store persists project names, hashed project/media-path identities, bounded timeline metadata, and explicit enrichments. It does not persist native project or media paths. Enrichment metadata keys that resemble paths, passwords, tokens, secrets, or API keys are discarded.

Recommended workflow

1. Call manage_project_context with action: "capture" while the intended sequence is active. Capture is bounded to 2,000 timeline items and returns the project, source, timeline, and combined context revisions.
2. Analyze only the required sources. Add transcript passages, shot descriptions, audio observations, or editor notes through action: "enrich". Include the returned source revision to reject stale analysis. For a structured, caller-approved bundle, use action: "import_evidence". It accepts transcript passages and speaker labels, shot logs, audio observations, operator notes, and opaque frame-reference IDs. An attachment to a source requires the exact current source revision; an attachment to a sequence or timeline item requires the exact current timeline revision.
3. Call search_project_context with the current editing intent and optional sequence/kind filters. Results contain evidence, stable Premiere identities, source time ranges, and revision provenance.
4. Call create_context_edit_plan for a non-mutating candidate scaffold. Review every candidate, capture again if the timeline changed, and resolve exact identities before building timeline operations.
5. Use preview_edit_plan before apply_edit_plan. The context plan is evidence, not mutation authority or proof that an editorial decision is correct.
6. Clear local project context when it is no longer required.

Revision and invalidation model

Source and timeline state are deliberately separate:

• A source revision uses stable project-item identity plus a hashed media path and, when the local server can stat the media, file size and modification time.
• A timeline revision covers sequence identity, timeline-item identity, source in/out, sequence start/end, speed, media type, and track index.
• The context revision covers both revisions plus all enrichment content.

Moving or trimming a timeline item changes the timeline revision but retains transcript, shot, and audio enrichments for unchanged source media. A changed or relinked source invalidates enrichments tied to the prior source revision. Event loss or an ambiguous state is recovered by capturing a fresh bounded snapshot.

Analysis boundaries

Capture does not transcribe speech, infer speakers, detect shots, calculate loudness, or send footage to a model. Those analyses are explicit enrichments so operators can choose Premiere transcript export, local software, or an approved provider. Premiere's documented transcript APIs support transcript import/export; they do not expose a stable operation for starting Speech-to-Text.

import_evidence does not read the referenced frame, resolve a file path, or call vision, ASR, LLM, Adobe, or a third-party provider. A frame reference is restricted to an opaque identifier, and metadata resembling a path, credential, or secret is removed before the local context index is saved.

Automated tests validate storage, privacy, invalidation, retrieval, and plan contracts. They do not replace validation against a licensed Premiere host.