How project.md Maintains Session Memory Across Video-Use Editing Sessions

The project.md file acts as an append-only markdown log stored in the user's edit directory, capturing strategy, decisions, and reasoning from each session to provide persistent context across video editing workflows.

The browser-use/video-use repository implements a lightweight persistence mechanism for video editing sessions through a single markdown file. This project.md session memory system eliminates the need for external databases while maintaining a complete, human-readable history of editing decisions. By leveraging simple file operations in the user's local edit directory, the skill creates a durable record that survives between runs.

Where project.md Lives and How It Persists

When a user initiates a video-editing session, the skill creates or reuses an edit directory inside the user's <videos_dir> folder (typically ~/videos/edit/). The memory file lives at the fixed path:

<videos_dir>/edit/project.md

Because project.md resides outside the repository source tree on the user's local filesystem, it is persisted between runs without requiring cloud services or databases. The file remains available across system restarts and skill re-invocations, providing continuums context for the LLM assistant. According to the repository's SKILL.md, this location serves as the single source of truth for session continuity.

The Append-Only Log Structure

The file operates as an append-only log, meaning content is never overwritten—only extended. At the end of each session, the skill writes a new markdown section containing the session's strategy, decisions, reasoning, and outstanding items using this fixed format:

## Session N — YYYY-MM-DD

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

This structure ensures the full history of edits remains on disk, creating a complete audit trail of the editing process. The sequential numbering allows the system to track session progression chronologically without complex state management.

Reading Session Memory on Startup

When a new session begins, the skill checks for the existence of project.md in the edit directory. If present, the file is read and the last session block is extracted automatically. The system generates a one-sentence summary from the Strategy line of the most recent entry and presents it to the user before asking whether to continue.

This read operation gives the LLM immediate context about previous work, allowing the assistant to resume editing where it left off. The logic relies on simple text parsing to locate the final ## Session heading and extract the subsequent metadata fields.

Implementation Details

The persistence layer is implemented through two core operations: appending completed sessions and retrieving historical context.

Appending New Sessions

The persist_session function handles the write operation, automatically incrementing session numbers by counting existing headers:

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)

Retrieving the Last Session

The last_session_summary function parses the file to extract the strategy from the most recent entry, returning an empty string if no file exists:

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 ""

Helper modules such as helpers/render.py and helpers/transcribe.py operate within the same edit directory structure, relying on the existence of project.md for session continuity.

File Security and Version Control

The repository's .gitignore explicitly excludes project.md, ensuring session-specific data remains a local artifact. This prevents accidental sharing of personal editing histories or project-specific strategies while allowing users to maintain their own local archives. The file is treated as a user-data artifact rather than source code, aligning with the skill's philosophy of filesystem-based persistence.

Summary

• project.md lives at <videos_dir>/edit/project.md and persists on the local filesystem between runs.
• The file uses an append-only markdown format with numbered sessions containing strategy, decisions, reasoning, and outstanding items.
• At startup, the skill reads the last session block to provide context for continuing edits.
• The .gitignore file excludes project.md from version control, keeping session data private and local.
• No external databases are required—the markdown file itself serves as the persistent store.

Frequently Asked Questions

Where is the project.md file stored on my system?

The file is created at <videos_dir>/edit/project.md, typically resolving to ~/videos/edit/project.md on Unix systems. This location is determined by the user's environment and remains outside the repository source tree to ensure persistence across skill updates.

What happens if I delete project.md?

If the file is missing, the skill initializes a fresh session without historical context. The last_session_summary function returns an empty string, and the system begins counting sessions from 1 again. No data is recovered, but the skill continues functioning normally for new edits.

Why does video-use use an append-only format?

The append-only approach guarantees an immutable history of editing decisions while preventing accidental data loss. By never overwriting previous content, users retain a complete audit trail of their video editing workflow, and the LLM can reference any prior session if needed.

Is session data shared with cloud services or version control?

No. The .gitignore file explicitly prevents project.md from being committed to git, and the file never leaves the user's local machine. The design intentionally avoids cloud synchronization to keep sensitive editing strategies and project metadata private.

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