# How Session Persistence Works with project.md in video-use

> Learn how session persistence with project.md enables project.md editing session resumes. video-use uses an append-only log to resume your work.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: internals
- Published: 2026-07-03

---

**The video-use skill maintains an append-only log of editing sessions in [`edit/project.md`](https://github.com/browser-use/video-use/blob/main/edit/project.md), reading the last entry on startup to generate a one-sentence summary that lets users resume work across multiple sessions.**

The `video-use` repository by browser-use implements a lightweight **session persistence** mechanism that enables editors to resume video editing projects across days or weeks. By storing an immutable history of decisions and strategies in a human-readable markdown file, the system ensures no context is lost between sessions. This persistence layer centers on [`edit/project.md`](https://github.com/browser-use/video-use/blob/main/edit/project.md), which serves as the canonical memory for the entire editing workflow.

## The Append-Only Log Architecture

### File Location and Conventions

Session state persists in [`edit/project.md`](https://github.com/browser-use/video-use/blob/main/edit/project.md) within your configured `<videos_dir>/edit/` folder. According to the source code in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md), this file follows an append-only pattern where new session data is concatenated to the end rather than overwriting previous entries. This design guarantees a complete audit trail where no data is ever lost.

### Markdown Structure Specification

Each session entry follows a strict format defined in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) (lines 91-104). The structure uses ATX headings to delineate sessions and includes four critical fields:

```markdown

## Session N — YYYY-MM-DD

**Strategy:** <one-paragraph description of the approach>
**Decisions:** <cuts, grades, animations + why>
**Reasoning log:** <one-line rationale for non-obvious decisions>
**Outstanding:** <deferred items>

```

Because the file is never overwritten—only new sections are added—[`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) builds a chronological memory of the entire editing history.

## Resuming Editing Sessions

### Reading and Summarizing the Last Session

When a new session begins, the skill looks for [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) in the edit folder. If it exists, the file is read and the last entry is summarized in one sentence. As implemented in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) line 104, the system extracts the **Strategy** field from the most recent session to present a brief recap. This gives the user immediate context without overwhelming them with details.

### User Confirmation Flow

After displaying the summary, the skill explicitly prompts the user to confirm continuation. This prevents accidental overwrites and allows users to decide whether to proceed with the existing project or start a fresh editing session. The LLM only proceeds with the normal workflow (inventory, strategy, execution) after receiving confirmation.

## Implementing Session Persistence in Code

### Loading the Previous Session

The Python implementation parses [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) using regex to extract the strategy line from the final section:

```python
from pathlib import Path
import re

def load_last_summary(edit_dir: Path) -> str | None:
    project_file = edit_dir / "project.md"
    if not project_file.is_file():
        return None

    # Read the whole file, split into sections by markdown heading

    sections = project_file.read_text().split("\n## Session ")

    if len(sections) <= 1:
        return None

    # The last non-empty section is the most recent session

    last_section = sections[-1].strip()
    # Grab the first paragraph (strategy line) as the one-sentence summary

    match = re.search(r"\*\*Strategy:\*\*\s*(.+)", last_section)
    return match.group(1).strip() if match else None

```

### Appending New Session Entries

At the end of each session, a new markdown section is appended to the same file. Helper functions like those in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) and [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) rely on this log to know when a session has finished:

```python
def append_session(edit_dir: Path, session_num: int, date: str,
                   strategy: str, decisions: str,
                   reasoning: str, outstanding: str) -> None:
    project_file = edit_dir / "project.md"
    entry = f"""

## Session {session_num} — {date}

**Strategy:** {strategy}
**Decisions:** {decisions}
**Reasoning log:** {reasoning}
**Outstanding:** {outstanding}
"""
    project_file.write_text(entry, mode="a")

```

## Summary

- **Session persistence** relies on an append-only markdown log at [`edit/project.md`](https://github.com/browser-use/video-use/blob/main/edit/project.md) that records every editing decision chronologically
- On startup, the system reads the last session's **Strategy** field to generate a one-sentence summary for the user
- The format specified in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) includes Strategy, Decisions, Reasoning log, and Outstanding items
- User confirmation is required before proceeding, preventing accidental overwrites while enabling multi-day editing workflows

## Frequently Asked Questions

### Where does video-use store session history?

The session history is stored in [`edit/project.md`](https://github.com/browser-use/video-use/blob/main/edit/project.md) within your videos directory. This file uses an append-only structure where each new session adds a markdown section rather than replacing existing content, ensuring a complete history is maintained indefinitely.

### How does the system know what I was working on last?

When starting a new session, the skill parses [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) to extract the **Strategy** field from the most recent session entry. It presents this as a one-sentence summary to remind you of the previous session's approach before asking whether to continue.

### Can I start a fresh session without deleting the history?

Yes. The user confirmation flow explicitly asks whether to continue from the previous session. If you decline, the system can start a new session while still preserving the complete history in [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) for future reference.

### What information is saved in each session entry?

Each entry records the editing strategy, specific decisions made (cuts, grades, animations), reasoning behind non-obvious choices, and any outstanding deferred items. This format is defined in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) and ensures comprehensive audit trails of every edit decision.