What Project Memory is
As your team works, it makes a lot of small decisions: the Lead lays out a plan, a gate passes or fails, a card moves from one state to the next, a phase completes. On most tools those moments scroll past in a chat log and are gone. Castforge writes each one to a durable record instead.
Project Memory is the tab where you read that record. It is a time-travelable memory of every planning decision the team made on this project: what happened, who did it, when, and (where it applies) why. Nothing in it is ever overwritten. New entries are added on top; old ones stay exactly as they were written.
You open it from the project workspace, alongside the chat and the board. The tab opens on the Project State digest, a live summary of the project, with the append-only feed described below sitting underneath it. The feed loads the newest entries first, so the most recent thing the team did is always at the top.
The Project State digest
Project State is not a raw dump of everything the team has written. It is kept faithful to where the project actually stands right now, and it is the same summary a fresh agent turn reads before it starts work:
- Stack holds a short, distilled stack line. It is taken first from a clear "Stack:" line or a stack heading in the latest research; when research has not settled on one yet, Castforge falls back to reading your project's own dependency manifests (its
package.jsonorCargo.toml) and lists the frameworks it recognizes there. Either way it stays a short line of recognized frameworks, never the researcher's raw notes and never a dump of every dependency. If neither source yields a stack, Stack stays empty for you to fill in by hand. - Built & Wired fills in with completed work as cards reach done, and also folds in a single summary line of the files that changed across recent turns (for example, "Changed 12 files across 4 turns"), so it grows as the project progresses.
- Current Focus shows the active phase and the card currently in progress, updating live as the board changes.
- Open Questions lists anything blocked, and clears those items again once they are unblocked.
- Key Decisions / Invariants collects the decisions the team recorded during the run plus the acceptance scope the plan was judged against, and it refreshes as work proceeds, not only when a phase finishes.
- Seeded Creds / Test Logins is yours to fill with throwaway dev or test logins. Never put real secrets, provider tokens, or production passwords here: the digest is read by your agents, so treat it like something they will see.
What a returning agent sees
When an agent starts a fresh turn (including after a break, a restart, or a crash), the digest it reads also carries a short Recent changes list: the concrete files touched over the last few turns, with each file marked added, modified, or deleted. This lets the team pick up where it left off from a real record of what changed, instead of having to re-inspect the repository from scratch. Only file names and their added, modified, or deleted status are recorded, never the contents of any change.
When a role records a structured decision during its turn, that decision is written to the record the moment it is made, not held back until the turn finishes. So if a run is interrupted partway through a turn, by a crash or a forced restart, the decisions the team had already reached are still there when it resumes, and the returning team re-orients from them instead of losing that ground. This durability is specific to recorded decisions: other in-progress work from an interrupted turn is not guaranteed to be saved at the moment of the crash, so the team may redo the tail end of whatever it was doing when it stopped.
Show more and show less
A section that grows long is never cut short. The full content is always kept and stays readable: past a certain length a section renders collapsed with a Show more control, and expanding it reveals the whole thing. Show less collapses it again. Short sections never show the toggle at all. Agents do not read the full text on every turn either: they receive a size-bounded summary of the same digest, so a long section does not blow up the context a fresh card starts from.
Editing, pinning, and where a fact came from
Any section can be edited in place, and editing it pins it automatically so automatic updates never overwrite what you wrote by hand. Unpin it at any time to let Castforge maintain the section again. Where a section came from a specific recorded decision, a View source link jumps you to that entry in the feed below. For the full walkthrough of editing and pinning a section, see "Working in a project."
The append-only ledger
Behind the tab is an append-only planning ledger. "Append-only" means entries are only ever added, never edited or deleted in place. That is what makes the history trustworthy: when you look back at why a plan changed three runs ago, you are seeing the original record, not a version someone tidied up later.
Each run of the team adds entries as it goes. Over the life of a project the ledger becomes a full, ordered account of how the work actually unfolded.
What a single entry records
Every entry is one event. It carries a small, consistent set of fields:
| Field | What it is |
|---|---|
| Type | What kind of event this was (a decision, a gate outcome, a transition, and so on). Shown as a color-coded badge. |
| Actor | Who or what caused it: a role like Lead or Reviewer, or system for automatic events. Shown as a small chip. |
| Time | When it happened, as a relative stamp (for example, 2m ago, 3h ago, 1d ago). |
| Body | A plain-language one-line summary of the event. |
| Detail | For entries with more structure, an expandable panel with the full record (see below). |
The badge color tells you the character of the event at a glance: mint for a passed check, coral for a failed one, amber for a skipped one, and neutral for routine transitions.
The categories
Entries fall into a handful of categories, and you can filter the feed to any one of them using the chips at the top:
- All: everything, newest first.
- Decisions: a choice the team recorded, often with a reason, an impact note, and references.
- Criteria: the acceptance criteria the team declared for a plan (how many, across how many phases).
- Gate outcomes: the results of the quality gates, that is, plan checks and goal checks passing, failing, being approved, or being skipped.
- Transitions: lifecycle movement, such as a card changing state, a phase completing, a run starting or finishing, or a milestone advancing.
- Health events: the moments the orchestration had to self-heal or ask for you, such as a card that stalled, a turn that wedged and was auto-resumed, or a run that ended on a question and raised a "Needs you" prompt. These used to exist only as background log lines; now they are recorded so you can see the pattern over time.
Filtering is instant and happens on the entries already loaded. If a filter has no matches on the page you are viewing, Castforge tells you so and points you to load more, rather than showing a blank feed.
Expanding an entry for the full story
Many entries carry more than their one-line summary. When they do, a chevron appears and you can expand the entry to reveal a detail panel. What you see depends on the type:
- Gate outcomes expand to the specifics: the unmet criteria a check found, the individual findings, the criteria that were checked, or the reason a gate was skipped.
- Decisions expand to the full decision text, plus an impact note, any verdict that rode along, and references to related work.
- Criteria declared expands to the list of phases and the criteria themselves.
- Transitions show the surrounding context where it helps, such as the phase title and card identity behind a card move.
Entries that are just a single fact (a run started, a phase advanced) have no chevron, because there is nothing more to show.
Health events: stalls, wedges, and surfaced questions
When a run has to correct itself or wait for you, the ledger now keeps a record instead of letting it pass unseen. A stall marks a card that got stuck and could not continue on its own. A wedge marks a task whose turn ended without moving forward; where Castforge could safely retry it once, an auto-resume entry sits alongside so you can see it recovered by itself. A surfaced question ("idle surfaced") marks the case where a turn ended asking you something with nothing queued to run, so the board raised a "Needs you" prompt rather than going quiet. Each entry carries which role was involved and, for a surfaced question, the text that was waiting on you. Read together they let you spot a project that keeps getting stuck in the same place, which is exactly the signal worth acting on.
Skipped-by-tier entries
If your project's quality tier turns a gate off, the ledger does not stay silent about it. It records a "Skipped (tier)" entry with an amber left edge and a tooltip explaining that the gate was bypassed because of the tier setting. This is deliberate: a gate that did not run is never presented as one that quietly passed. For how the tiers decide which gates run, see "Quality tiers and review gates."
Exporting to decisions.md
The Export decisions button writes the project's decision history to a decisions.md file inside the project's .castforge folder on disk. This gives you a plain-text, version-controllable copy of the record that lives with your code, so it can be committed, reviewed in a pull request, or read outside the app. The export reflects the ledger at the moment you run it; run it again after more work to refresh the file.
The verification.md artifact
Alongside decisions.md, the phase verification gate keeps a verification.md file in the project's .castforge folder. It holds one section per verified phase, newest first, and each section records that phase's verdict (pass, fail, or skipped), the commands the verification actually ran with a trimmed excerpt of their output, any unmet items it found, and any human-verify notes. The file is bounded so it never grows without limit: only the most recent phases are kept and each section is capped in size. It gives you an on-disk, version-controllable record of how each phase was checked, sitting next to your code. For how the phase verification gate itself works, see "Quality tiers and review gates."
Common questions
Where do I find Project Memory? It is a tab in the project workspace, next to the chat and the board. Open a project, then switch to the Project Memory view.
Can I edit or delete an entry? No, and that is the point. The ledger is append-only so the history stays honest. If a decision changes, the team records a new entry rather than rewriting the old one.
Why is the feed empty on a brand new project? Because nothing has happened yet. Decisions and gate outcomes start appearing as soon as your team runs. Until then you see a short "No entries yet" note.
What does the actor "system" mean?
Some events are automatic rather than the direct act of a role, for example a gate being skipped because of the quality tier. Those are attributed to system so you can tell them apart from a role's own actions.
What is the difference between the ledger and decisions.md?
The ledger is the live, in-app record you browse and filter. decisions.md is an on-disk export of it, written into the project's .castforge folder so you can keep a copy alongside your code.
Does filtering change what is stored? No. Filters only change what you are looking at. Every entry stays in the ledger regardless of which chip is selected.
What happens if the app crashes or restarts in the middle of a run? When the team picks the work back up, it first reads the Project State digest and the Recent changes list, so it re-orients from a real record of the stack, the files that recently changed, and the decisions already made, rather than starting cold. Recorded decisions are saved the moment they are made, so a crash loses little decision-level ground. Work that was still in progress in the interrupted turn may be redone when the team resumes.