How video-use Handles Session Persistence with project.md and Memory Recovery

video-use persists editing sessions by appending structured Markdown logs to <edit>/project.md, then recovers the last session's strategy on startup to resume workflows without reprocessing source media.

The browser-use/video-use repository implements a lightweight, human-readable session persistence mechanism that stores editing decisions and strategy in a plain Markdown file. By leveraging an append-only log format within the project's edit directory, the tool enables seamless memory recovery across interrupted sessions.

The project.md Append-Only Log Format

Markdown Structure and Session Metadata

Each completed session appends a new section to <edit>/project.md following the header pattern ## Session N — YYYY-MM-DD. According to the SKILL.md specification, every entry records four critical fields: Strategy, Decisions, Reasoning log, and Outstanding items.

This append-only architecture ensures historical context is never overwritten. Instead of binary state or hidden caches, the system generates a permanent, human-readable audit trail that survives crashes and repository migrations.

File Location Within the Edit Directory

The persistence file resides in <videos_dir>/edit/ alongside other generated artifacts like takes_packed.md, edl.json, and master.srt. As documented in the repository's directory layout guidelines, co-locating project.md with session artifacts ensures that memory logs are automatically version-controlled with the rest of the project data.

Memory Recovery Implementation

Parsing the Last Session on Startup

When the skill initializes, it checks for the existence of project.md in the edit directory. If present, the startup routine parses the file to locate the most recent Strategy paragraph. The load_last_summary() helper extracts the first line containing **Strategy:** from the end of the file, returning the previous session's strategic context.

Continuation Workflow

Following successful extraction, the interface presents a one-sentence recap of the prior strategy and prompts the user to continue the previous workflow. If the user declines or if project.md is absent, the skill initializes a fresh session. This mechanism prevents redundant re-transcription of source media and costly reprocessing steps.

Code Implementation Examples

Persisting Session State

The following Python helper demonstrates how video-use appends new session data using standard file operations:

import datetime
import pathlib

def persist_session(edit_dir: pathlib.Path, strategy: str, decisions: str,
                   reasoning: str, outstanding: str) -> None:
    project_file = edit_dir / "project.md"
    # Calculate next session number by counting existing headers

    session_id = sum(1 for _ in project_file.read_text().splitlines() if _.startswith("## Session")) + 1

    header = f"## Session {session_id} — {datetime.date.today().isoformat()}\n\n"

    body = (
        f"**Strategy:** {strategy}\n\n"
        f"**Decisions:** {decisions}\n\n"
        f"**Reasoning log:** {reasoning}\n\n"
        f"**Outstanding:** {outstanding}\n"
    )
    # Append mode ensures we never overwrite previous sessions

    with open(project_file, "a", encoding="utf-8") as f:
        f.write(header + body)

Recovering the Last Session

To recover context on startup, the skill uses a reverse scan to find the last strategy entry:

def load_last_summary(edit_dir: pathlib.Path) -> str | None:
    project_file = edit_dir / "project.md"
    if not project_file.is_file():
        return None
    lines = project_file.read_text().splitlines()
    # Search backwards for the most recent Strategy line

    for i in range(len(lines) - 1, -1, -1):
        if lines[i].startswith("**Strategy:**"):
            return lines[i].removeprefix("**Strategy:** ").strip()
    return None

Integration Workflow

The typical startup sequence combines recovery with user interaction:

edit_dir = pathlib.Path("/path/to/videos_dir/edit")
last = load_last_summary(edit_dir)
if last:
    print(f"Last session summary: {last}")
    continue_ = input("Continue where we left off? (y/n) ")
    if continue_.lower() != "y":
        # Initialize fresh session logic here

        pass

# Proceed with new editing plan

persist_session(edit_dir, strategy, decisions, reasoning, outstanding)

Summary

• Append-only persistence: Each session adds a new Markdown section to project.md without overwriting history, using the format ## Session N — YYYY-MM-DD.

• Human-readable format: Plain Markdown storage enables manual inspection, editing, and version control through standard git workflows.

• Automatic recovery: The startup routine extracts the last Strategy field from project.md to resume workflows without re-transcribing source media.

• Co-located storage: Residing in <videos_dir>/edit/, the file persists alongside EDLs, transcripts, and other session artifacts.

• Crash resilience: No binary state or hidden caches means recovery works across system failures or when the repository is cloned to a new machine.

Frequently Asked Questions

Where does video-use store session memory?

According to the SKILL.md specification in the browser-use/video-use repository, session memory persists in <edit>/project.md within the project's edit directory. This file accumulates an append-only log of all editing sessions, storing each as a Markdown section with Strategy, Decisions, Reasoning log, and Outstanding items.

Can I manually edit project.md without breaking recovery?

Yes. Because project.md uses standard Markdown syntax, you can manually edit entries, fix typos, or merge sessions. The load_last_summary() function simply searches for the last line starting with **Strategy:**, so as long as the Markdown structure remains intact, recovery will function correctly.

What happens if project.md is deleted or corrupted?

If the file is missing, the skill initializes a fresh session without attempting recovery. Since the persistence mechanism relies solely on this plain text file—no binary caches or hidden state—a missing project.md simply triggers a new session start. You can also force a fresh start by ignoring the recovery prompt when the file exists.

Does video-use support concurrent session editing?

The current implementation does not support concurrent writes to project.md. The append-only design assumes sequential access, where each session completes before the next begins. Concurrent modifications could result in race conditions or malformed Markdown headers, so the tool is designed for single-user, sequential editing workflows.

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