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

> Discover how video-use ensures session persistence with project.md. Learn how it recovers your last editing session, saving you time and preventing media reprocessing.

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

---

**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`](https://github.com/browser-use/video-use/blob/main/takes_packed.md), [`edl.json`](https://github.com/browser-use/video-use/blob/main/edl.json), and `master.srt`. As documented in the repository's directory layout guidelines, co-locating [`project.md`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.