forgev0.19
Docs pages

Project memory

Every dispatch starts a fresh model session. Without help, the tenth run in a repo would rediscover what the first one learned. Project memory is that help.

Two small files

FileWhat it is
.forge/memory.mdA short list of facts about the repo, given to every later run. At most 40 lines.
.forge/ledger.tsvOne line per dispatch, ever. Never shown to a model; memory is rebuilt from it.
## Verify
- pytest -q runs the suite; make test also lints and is 4x slower

## Known traps
- tests/test_api.py::test_timeout is flaky under -n auto  [tests/test_api.py]

## Recurring QA findings
- 3x: route added without updating openapi.yaml  [src/routes]

How a fact gets in

The model that just did the work writes it down in its final message. The one that stepped on the landmine records it, with no extra model call:

FORGE_LEARNING: trap | src/proto/*_pb2.py is generated, never hand-edit [src/proto]
  • A test command or a trap is kept the first time. A review finding must show up in two different runs to count as a pattern.
  • A fact tied to a path is dropped once that path is gone, so memory stays true as code moves.
  • When it's full, the least useful facts are trimmed.
  • Models are told most runs teach nothing durable. A wrong fact costs every future run; a missing one costs one rediscovery.

Builders and planners get everything. Reviewers get the traps and the recurring findings, so they notice the fourth time the same bug ships.

Should you commit it?

forge never commits .forge/. Your choice:

You wantDo this
memory shared with your teamcommit .forge/, both files
memory on your machine onlyadd .forge/ to .gitignore
no memory--no-memory, or FORGE_MEMORY=off

Commit both files or neither. memory.md is rebuilt from ledger.tsv. A teammate with your memory but not your ledger rebuilds it from their own short ledger on their next run, and your shared facts are gone.

Ignoring the folder doesn't turn memory off; it just stays on your machine. Contributing to someone else's project? Ignore it: forge's notes to itself are noise in their pull requests.

Looking inside

forge memory show ~/dev/api        # what a dwarf would be told
forge memory learnings ~/dev/api   # every learning and whether it's in memory yet
forge memory spend ~/dev/api       # what forge has spent in this repo

Editing memory.md by hand doesn't stick. To drop a learning, forget it: its ledger rows go and memory is rebuilt.

forge memory forget ~/dev/api trap:"b is generated" --dry-run
forge memory forget ~/dev/api trap:"b is generated"

forge-ui's Projects screen shows each repository's memory, and with controls on, forgets the learnings you select.

Full reference Every flag and edge case: docs/memory.md