How to Migrate from Existing Video Editing Workflows to video-use While Preserving Session Memory in project.md

To migrate from existing video editing workflows to video-use while preserving session memory in project.md, consolidate your raw footage into a single directory, create a markdown file at edit/project.md containing your edit history and strategy, and run the skill—each session automatically appends new decisions to this file, enabling the LLM to resume editing exactly where you left off.

Traditional GUI-based video editors trap your edit state inside proprietary binary files. The video-use framework replaces this with a conversational LLM-driven pipeline that persists every creative decision in a plain-text project.md file, allowing you to migrate any existing workflow into a version-controlled, resumable editing process.

How Session Memory Works in video-use

The session memory mechanism centers on an append-only markdown file that acts as a persistent log of your editing story. According to the SKILL.md source file, the framework treats project.md as the single source of truth for project continuity.

The project.md Append-Only Pattern

Each time a session finishes, video-use writes a markdown section containing the strategy, decisions, reasoning log, and outstanding tasks. This file grows chronologically but remains lightweight because it stores only structured text, not video data. The format follows this structure:

## Session 1 — 2024-09-15

**Strategy:** Produce a 60‑second launch video from the raw takes.  
**Decisions:**  
- Keep take C0103 (0 s–12 s) for intro.  
- Drop filler words in C0108 (13 s–30 s).  
- Apply “warm_cinematic” grade.  
**Reasoning log:**  
- Chose C0103 because its opening line matches the hook.  
**Outstanding:**  
- Add a lower‑third graphic after the second cut.

Startup Recovery Process

When the skill starts, it checks for project.md. If the file exists, the system reads the newest section, extracts a one-sentence summary of the previous session, and presents it to the user before asking whether to continue. This behavior, documented in SKILL.md, ensures the LLM enters the conversation with full context of prior cuts, color grading decisions, and deferred tasks.

Migration Steps from Traditional Workflows

Moving from conventional video editors like Premiere or DaVinci Resolve requires shifting from GUI state to declarative text state. Follow these steps to preserve your existing progress.

1. Collect Existing Assets

Gather your raw footage, existing edit decision lists (EDLs), and any subtitle files into a single project folder (e.g., my-video-project/). The skill expects to find video files alongside the memory file, not embedded in proprietary project databases.

2. Bootstrap project.md from Legacy Notes

Convert your existing edit notes into the video-use markdown format. Even a minimal placeholder enables the persistence mechanism:

## Session 0 — 2024-01-01

**Strategy:** Initial import and transcription.  
**Decisions:** None yet.  
**Reasoning log:** —  
**Outstanding:** Review transcription quality.

Place this content in a file named project.md inside an edit/ subdirectory.

3. Position the Memory File Correctly

The skill specifically looks for project.md at <videos_dir>/edit/project.md. If you use the default layout, the edit/ directory is created automatically on first render, but for migration, you must manually move your bootstrapped file to this location before starting.

4. Resume and Iterate Across Sessions

Launch the skill from your project directory:

cd my-video-project
claude   # or your preferred LLM agent

The skill will load project.md, summarize the last session, and ask if you want to continue. After each editing round completes, the system automatically appends a new markdown section (Session 1, Session 2, etc.) to the file. Because this persists on disk, you can shut down the VM or disconnect the chat and resume weeks later without losing context.

Key Advantages Over GUI-Based Editors

Migrating to video-use provides several architectural benefits over traditional timeline editors:

• No GUI State – All state is plain text, version-controlled, and merge-friendly. You can git diff your editing decisions.
• LLM-Centric Reasoning – The model reads project.md as part of its prompt, referencing past decisions to avoid re-transcribing sources and ensuring continuity.
• Parallel Sub-Agents – Animations, color grading, and subtitle rendering happen concurrently via helpers/render.py, reducing turnaround time compared to sequential GUI workflows.
• Self-Evaluation Loop – Before each render, the skill runs a visual sanity check using helpers/timeline_view.py to prevent pop-ups and subtitle misplacements.

Implementation Examples

Minimal project.md Structure

Create this file at my-video-project/edit/project.md to initialize a project:

## Session 1 — 2024-09-15

**Strategy:** Produce a 60‑second launch video from the raw takes.  
**Decisions:**  
- Keep take C0103 (0 s–12 s) for intro.  
- Drop filler words in C0108 (13 s–30 s).  
- Apply “warm_cinematic” grade.  
**Reasoning log:**  
- Chose C0103 because its opening line matches the hook.  
**Outstanding:**  
- Add a lower‑third graphic after the second cut.

Running Your First Session

Execute the skill from your project root:

cd my-video-project
claude   # launch your LLM agent

# In the LLM session:

> edit these into a launch video

The skill will load project.md, summarize Session 1, propose a strategy for your confirmation, and produce edit/final.mp4.

Scripting project.md Updates

If you need to programmatically inject session data from external tools, treat the file as plain text:

from pathlib import Path
from datetime import date

project_path = Path("my-video-project/edit/project.md")
next_session = f"""

## Session 2 — {date.today()}

**Strategy:** Add overlay animation for the product logo.
**Decisions:** Render overlay slot_1/render.mp4 (0‑5 s).
**Reasoning log:** Visual emphasis on brand at 10 s.
**Outstanding:** None.
"""
project_path.write_text(project_path.read_text() + "\n" + next_session)

Confirming State Persistence

Verify that your session history persists correctly:

cat my-video-project/edit/project.md

You should see all previous sessions concatenated, confirming that the LLM will have the full history on the next run.

Summary

• video-use replaces GUI project files with a conversational LLM pipeline that stores decisions in project.md.
• Place project.md at <videos_dir>/edit/project.md to enable session memory.
• The skill appends a new markdown section after each session, preserving a chronological history of strategies, decisions, and outstanding tasks.
• On startup, the system reads the latest section to summarize the previous session and prompt for continuation.
• This approach enables version-controlled, collaborative video editing that resumes across days or weeks without losing context.

Frequently Asked Questions

What file format does video-use use for session memory?

video-use uses a plain-text markdown file named project.md. As documented in SKILL.md, this file contains structured sections for each session including strategy, decisions, reasoning logs, and outstanding tasks, making it human-readable and version-control friendly.

Where does video-use store the project.md file?

The skill expects project.md to reside at <videos_dir>/edit/project.md. If you follow the default layout, the edit/ directory is created automatically on first render, but for migration, you must manually place your bootstrapped file at this specific path.

Can I manually edit project.md between sessions?

Yes. Because project.md is plain text, you can manually edit it to correct decisions, update the reasoning log, or modify outstanding tasks. The skill reads this file on startup as part of its prompt context, so manual edits directly influence the LLM's understanding of the project state.

How does video-use handle large project histories?

The file grows append-only, storing only structured text rather than video data, so it remains lightweight even after dozens of sessions. The skill reads the entire file on startup to provide full context, though in practice the text size is negligible compared to video assets. For very long projects, you can archive old sessions to a separate file while keeping recent history in the active project.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}