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

The 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 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 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:

<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, 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. 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:

## 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:

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. 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:

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 and transcribe.py—operates within the <edit> folder and relies on the existence of 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 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 stored?

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 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 file. Session memory is project-specific and does not leak across different video editing contexts.

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