# How `project.md` Facilitates Session Memory Persistence in Video-Editing Sessions

> Discover how project.md stores editing strategies and decisions, enabling video-use to restore session memory across disconnected editing sessions via an append-only markdown log.

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

---

**The [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) file acts as an append-only markdown log that stores editing strategies, decisions, and reasoning from each session, enabling the video-use skill to restore context across disconnected editing sessions.**

In the `browser-use/video-use` repository, maintaining continuity between video editing sessions requires a lightweight, human-readable persistence mechanism. The [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) file serves as the repository’s "brain," providing **session memory persistence** without requiring external databases or cloud services. This local markdown file captures every decision made during editing, allowing the assistant to resume work exactly where it left off.

## Where [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) Lives and How It Persists

The file resides in a dedicated edit directory within the user’s local filesystem. When a video-editing session begins, the skill creates or reuses an edit directory located at `<videos_dir>/edit/` (typically `~/videos/edit/`).

The full path follows this structure:

```bash
<videos_dir>/edit/project.md

```

Because this file exists outside the repository source tree—in the user’s personal videos directory—it survives between runs of the skill. The persistence is entirely filesystem-based, meaning **session memory persistence** relies on local storage rather than external infrastructure. Additionally, `.gitignore` explicitly excludes [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md), ensuring session-specific data remains private to the user and never enters version control.

## The Append-Only Logging Mechanism

At the end of each editing session, the skill appends a new markdown section to [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md). This append-only approach guarantees that no historical data is ever overwritten, creating a complete audit trail of all editing decisions.

### Session Block Format

Each session entry follows a strict markdown structure defined in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md):

```markdown

## Session N — YYYY-MM-DD

**Strategy:** …
**Decisions:** …
**Reasoning log:** …
**Outstanding:** …

```

The implementation iterates through existing content to determine the next session number, then writes the new block using append mode (`"a"`). This ensures atomic updates without risking data corruption from concurrent writes.

Here is the illustrative Python implementation used by the skill:

```python
import os
from datetime import date

def persist_session(edit_dir: str, strategy: str, decisions: str,
                    reasoning: str, outstanding: str) -> None:
    """Append a new markdown block to <edit>/project.md."""
    project_path = os.path.join(edit_dir, "project.md")
    session_num = 1
    # Count existing sections to get the next session number

    if os.path.exists(project_path):
        with open(project_path, "r") as f:
            for line in f:
                if line.startswith("## Session"):

                    session_num += 1
    block = f"""## Session {session_num} — {date.today().isoformat()}

**Strategy:** {strategy}
**Decisions:** {decisions}
**Reasoning log:** {reasoning}
**Outstanding:** {outstanding}
"""

    with open(project_path, "a") as f:
        f.write("\n" + block)

```

## Restoring Context at Startup

When a new session begins, the skill checks for the existence of [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md). If found, it parses the file to extract the **last** session block and generates a one-sentence summary of the previous strategy. This summary is presented to the user before editing resumes, giving the LLM immediate context about prior work.

The `last_session_summary` function in the codebase handles this restoration:

```python
def last_session_summary(edit_dir: str) -> str:
    """Return a one-sentence summary of the latest session."""
    project_path = os.path.join(edit_dir, "project.md")
    if not os.path.exists(project_path):
        return ""
    with open(project_path, "r") as f:
        lines = f.readlines()

    # Find the last "## Session …" heading and capture the following lines

    last_heading = max(i for i, l in enumerate(lines) if l.startswith("## Session"))

    # Grab the next non‑empty line after the heading (the Strategy line)

    for line in lines[last_heading + 1:]:
        if line.strip().startswith("**Strategy:**"):
            return line.strip().split(": ", 1)[1]
    return ""

```

This parsing logic ensures that **session memory persistence** translates directly into actionable context for the assistant, enabling seamless continuation of complex editing workflows.

## Integration with Helper Modules

The `helpers/` directory—including files like [`render.py`](https://github.com/browser-use/video-use/blob/main/render.py) and [`transcribe.py`](https://github.com/browser-use/video-use/blob/main/transcribe.py)—operates within the `<edit>` folder and relies on the existence of [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) for session continuity. These modules assume the persistent log is available to track which clips have been processed, which transcripts exist, and what rendering decisions were made in previous sessions.

## Summary

- **[`project.md`](https://github.com/browser-use/video-use/blob/main/project.md)** serves as the single source of truth for **session memory persistence**, located at `<videos_dir>/edit/project.md`.
- The file uses an **append-only** strategy, ensuring complete historical preservation of editing decisions and reasoning.
- At startup, the skill reads the last session block to provide context continuity, extracting the strategy line to summarize previous work.
- Persistence is achieved through local filesystem storage, with `.gitignore` preventing accidental commits of session data.
- Helper functions like `persist_session()` and `last_session_summary()` manage the write and read operations respectively.

## Frequently Asked Questions

### Where is [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) stored?

[`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) is stored in the user's local edit directory at `<videos_dir>/edit/project.md`, typically resolving to `~/videos/edit/project.md`. This location places it outside the repository source tree, ensuring it persists on the local filesystem between skill executions.

### What happens if [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) is deleted?

If the file is deleted, the `last_session_summary` function returns an empty string, and the skill treats the next session as a fresh start with no prior context. The user will not see a summary of previous work, and the next session will be numbered as Session 1 when `persist_session` creates a new file.

### How does the skill determine the next session number?

The `persist_session` function counts existing lines starting with `## Session` in the current file. It increments this count to generate the next session number, ensuring sequential ordering even if sessions span multiple days or are interrupted.

### Is session data shared between different video projects?

No. Each project operates within its own edit directory, meaning each video project maintains its own isolated [`project.md`](https://github.com/browser-use/video-use/blob/main/project.md) file. Session memory is project-specific and does not leak across different video editing contexts.