Memory file formats

Forge stores per-project state in a .forge/ directory at the project root. Most files are markdown, two are TOML, one is JSON. All of them are version-control-safe and editable by hand.

This page documents the shape of each file.

BRIEF.md

Pitch, audience, scope, success criteria. The agent injects this in full on every turn.

# Brief

## What
One-paragraph pitch.

## Who
Audience description.

## Scope
What's in, what's out.

## Success
What "done" looks like.

The headings are conventional, not enforced. Forge reads the whole file regardless of structure. Be terse: every word goes into context on every turn.

DESIGN.md

Game design pillars, mechanics, narrative. Same auto-injection as BRIEF.

# Design

## Pillars
- Pillar one
- Pillar two

## Core mechanics
...

## Narrative
...

STACK.md

Engine, plugins, dependencies, versions.

# Stack

- Engine: Godot 4.5
- Renderer: Forward+
- Audio: Godot's built-in AudioServer
- Build target: HTML5
- Major plugins: ...

DECISIONS.md

Append-only log of architectural decisions. ADR-style entries.

# Decisions

## 2026-04-30 Stamina over mana
Picked stamina to reinforce the survival pillar. Mana-style magic regen
felt too forgiving for the tone we're going for.

## 2026-04-22 Switched to Phaser from PixiJS
PixiJS lacks built-in tilemap support. Phaser's Arcade physics covers
our movement needs without needing Box2D.

The agent injects the most recent entries on every turn (currently the last five). Older entries stay in the file but aren’t auto-injected, although memory search can surface them.

PROGRESS.md

Snapshot of the current state: what’s done, what’s in progress, what’s next. Overwrite-safe; the agent rewrites it as the project progresses.

# Progress

## Done
- Player controller (basic)
- One enemy type with patrol AI
- Save and load to JSON

## In progress
- Combat hit detection
- Inventory UI

## Next
- Boss enemy
- Sound effects pass
- Itch.io page

STYLE.md

Art direction, palette, tone, references. Read by the agent when it generates assets or proposes art-direction changes.

# Style

## Tone
Cozy survival. Warm but not saccharine.

## Palette
Persimmon, teal, muted navy. Avoid pure black or white.

## References
- [Reference image 1](path/to/ref1.png)
- [Studio Ghibli backgrounds]
- [Hyper Light Drifter colour blocking]

ASSETS.md

Auto-updated registry of generated and imported assets.

# Assets

## 2026-04-30
- voice/2026-04-30T143012.mp3 (ElevenLabs, voice "Adam"): "Welcome, traveller"
- music/2026-04-30T144203.mp3 (ElevenLabs Music, 60s): "Calm forest theme, 90s instrumental"
- sprites/2026-04-30T150418.png (Scenario, model "RetroChest"): "Pixel-art chest, four states"

The agent appends here whenever the Asset studio generates something. You can edit by hand to add notes or attribution.

plan.md

The shared checklist between you and the agent. Markdown with task-list syntax. Top-level items carry stable <!-- id: p_xxxxxxxx --> comments minted by Forge so individual items can be focused on by chat tabs.

# Plan: Inventory system

- [ ] Wire up the inventory UI <!-- id: p_a3kx91qm -->
  - Slot grid renders and accepts drops.
  - Hover tooltips show item metadata.
- [ ] Add equip / unequip animations <!-- id: p_b9zv4f2p -->
- [x] Drop sound effect for picking up items <!-- id: p_c1tk7m8r -->
- [~] Save and load inventory state <!-- id: p_d4qn0y6w -->
  blocked on save-system slice

Three checkbox states are recognised: [ ] unchecked, [x] checked, [~] blocked. Top-level items are focusable; indented - [ ] lines under a parent render as a checklist within that parent’s scope.

Forge mints the ids — the agent never invents them. Hand-edited items missing an id show a + id button in the Plan tab to mint one in place.

The Plan tab in the Inspector reads and writes this file. See Plan-mode loop for the full workflow.

tasks.toml

Project commands surfaced in the command palette as Task: <label> entries.

[[tasks]]
name = "dev"
label = "Start dev server"
command = "pnpm dev"
shell = "powershell"  # optional

[[tasks]]
name = "test"
label = "Run tests"
command = "pnpm test"

[preview]
command = "pnpm dev"
url_pattern = "http://localhost:5173"

Each [[tasks]] table needs name, label, and command. shell is optional and overrides your default shell. The [preview] section is consumed by the Web preview tab and is documented in Tasks runner.

workspace.json

Per-project layout state. Forge writes it; you don’t normally edit by hand.

{
  "version": 5,
  "tabs": [
    {
      "id": "tab-chat-1",
      "kind": "chat",
      "sessionId": "session-uuid-1",
      "title": "rendering pass"
    },
    {
      "id": "tab-monaco-player",
      "kind": "monaco",
      "path": "src/Player.gd",
      "title": "Player.gd",
      "dirty": false
    }
  ],
  "panes": [
    { "id": "pane-A", "tabIds": ["tab-chat-1"], "activeTabId": "tab-chat-1" }
  ],
  "activePaneId": "pane-A",
  "panelVisible": {
    "sidebar": true,
    "inspector": true,
    "terminal": false
  }
}

Schema is internal and may evolve. The version field signals the layout. Forge migrates older versions on read.

.index/memory.db

SQLite database holding the FTS5 index over *.md files in .forge/, plus optional embeddings when semantic search is enabled. Generated and not version-control-friendly. The folder is gitignored by default in projects Forge initialises.