Files
alan 538143554c Split stage memory into capped essential memory.md and full history.md
Every stage used to be told to read memory.md, the full output of every
earlier turn (19 KB average, 92 KB max), and paid for it on each model call.
memory.md is now essential memory, hard-capped at 4 KB and inlined in the
prompt: the task, the previous stage's # handoff section (or its truncated
output head), a one-line-per-stage outcome ledger and the server-captured
changed files. history.md keeps the old full memory on disk; read-capable
stages are pointed at it and input.md for on-demand detail, and it is never
inlined. The prompt asks each stage for a short # handoff section.
2026-11-04 13:00:48 +00:00

326 lines
9.3 KiB
Go

package turn
import (
"fmt"
"strings"
"unicode/utf8"
)
// EssentialCap is the hard byte cap on a visit's memory.md (essential memory).
// It is small on purpose: the file is inlined into every model call of the
// visit, so its size is paid once per call. Everything else stays on disk in
// history.md and input.md, read only on demand.
const EssentialCap = 4096
const (
essentialLedgerLines = 10
essentialFileLines = 8
essentialLineCap = 100
// essentialHandoffMin is the least room a previous stage's handoff gets
// when the task also needs more than half of the remaining budget.
essentialHandoffMin = 1024
)
// Essential is everything RenderEssential needs for one visit's memory.md.
type Essential struct {
// Task is the run prompt.
Task string
// StageKey is the stage about to run; it marks a revisit.
StageKey string
// Entries are the completed turns in order (the same slice history.md is
// rendered from).
Entries []MemoryEntry
// ChangedFiles is the run's server-captured changed-path list.
ChangedFiles []string
// InputPath and HistoryPath are named as the on-demand detail.
InputPath string
HistoryPath string
}
// RenderEssential renders a visit's essential memory: the task, the previous
// stage's handoff, a one-line-per-stage outcome ledger and the changed files.
// The result never exceeds EssentialCap bytes. The previous stage's handoff is
// its "# handoff" section when it wrote one, otherwise the head of its output;
// either is truncated with a pointer to the full text, so the file stays useful
// whether or not a model followed the handoff convention.
func RenderEssential(e Essential) string {
var fixed strings.Builder
fixed.WriteString("# Essential memory\n\n")
fixed.WriteString("Short handoff for this visit; enough for most work.")
if e.InputPath != "" || e.HistoryPath != "" {
fixed.WriteString(" Read on demand only:")
if e.InputPath != "" {
fmt.Fprintf(&fixed, " %s (full task and previous stage output)", e.InputPath)
}
if e.HistoryPath != "" {
if e.InputPath != "" {
fixed.WriteString(";")
}
fmt.Fprintf(&fixed, " %s (every earlier turn in full)", e.HistoryPath)
}
fixed.WriteString(".")
}
fixed.WriteString("\n")
var tail strings.Builder
if ledger := renderLedger(e.Entries, e.StageKey); ledger != "" {
tail.WriteString("\n## Stage ledger\n\n")
tail.WriteString(ledger)
}
if files := renderFiles(e.ChangedFiles); files != "" {
tail.WriteString("\n## Changed files (server-captured)\n\n")
tail.WriteString(files)
}
taskHeading := "\n## Task\n\n"
task := strings.TrimSpace(demoteHeadings(strings.TrimSpace(e.Task)))
if task == "" {
task = "_(no task text)_"
}
var handoffHeading, handoff string
if n := len(e.Entries); n > 0 {
previous := e.Entries[n-1]
title := capLine(fmt.Sprintf("%s · visit %d%s", oneLine(previous.Stage), previous.Visit, outcomeSuffix(previous.Outcome)), 2*essentialLineCap)
handoffHeading = "\n## Previous stage: " + title + "\n\n"
var source string
handoff, source = previousHandoff(previous.Output)
handoffHeading += source
if public := sortedUnique(previous.PublicFiles); len(public) > 0 {
handoff += "\n\nAdded to public/: " + capLine(strings.Join(public, ", "), 2*essentialLineCap)
}
}
// Budget what is left after the fixed parts between the task and the
// handoff. Unused room on either side flows to the other.
reserve := 2 * len(truncationNote(EssentialCap, EssentialCap, "input.md"))
budget := EssentialCap - fixed.Len() - tail.Len() - len(taskHeading) - len(handoffHeading) - 2 - reserve
if budget < 0 {
budget = 0
}
handoffBudget, taskBudget := 0, budget
if handoffHeading != "" {
half := budget / 2
if half < essentialHandoffMin {
half = min(essentialHandoffMin, budget)
}
switch {
case len(task) <= budget-half:
handoffBudget = budget - len(task)
case len(handoff) <= half:
handoffBudget = len(handoff)
default:
handoffBudget = half
}
taskBudget = budget - min(handoffBudget, len(handoff))
}
var b strings.Builder
b.WriteString(fixed.String())
b.WriteString(taskHeading)
b.WriteString(truncateWithNote(task, taskBudget, "input.md"))
b.WriteString("\n")
if handoffHeading != "" {
b.WriteString(handoffHeading)
b.WriteString(truncateWithNote(handoff, handoffBudget, "input.md"))
b.WriteString("\n")
} else {
b.WriteString("\nThis is the first stage of the run; there is no earlier turn.\n")
}
b.WriteString(tail.String())
out := b.String()
if len(out) > EssentialCap {
// Pathological input (very long stage keys or paths); never exceed the
// cap even if the section budgets could not absorb it.
out = truncateWithNote(out, EssentialCap-len(truncationNote(len(out), len(out), "history.md")), "history.md") + "\n"
if len(out) > EssentialCap {
out = cutAtRune(out, EssentialCap)
}
}
return out
}
// HandoffSection returns the body of the first "handoff" heading (any ATX
// level, outside fenced code) up to the next heading of the same or a higher
// level, trimmed. ok is false when there is no such heading or it is empty.
func HandoffSection(markdown string) (string, bool) {
lines := markdownLines(markdown)
var fence fenceState
start, level := -1, 0
end := len(markdown)
for i, line := range lines {
if fence.open() {
if fence.closes(line.text) {
fence = fenceState{}
}
continue
}
if marker, ok := openingFence(line.text); ok {
fence = marker
continue
}
lvl, text, isHeading := atxHeading(line.text)
if !isHeading {
continue
}
if start < 0 {
if strings.EqualFold(text, "handoff") {
start, level = line.next, lvl
}
continue
}
if lvl <= level {
end = lines[i-1].next
break
}
}
if start < 0 {
return "", false
}
section := strings.TrimSpace(markdown[start:end])
return section, section != ""
}
func previousHandoff(output string) (string, string) {
if section, ok := HandoffSection(output); ok {
return strings.TrimSpace(demoteHeadings(section)), ""
}
body := strings.TrimSpace(demoteHeadings(output))
if body == "" {
return "_(no output)_", ""
}
return body, "_(no `# handoff` section; showing the start of its output)_\n\n"
}
func renderLedger(entries []MemoryEntry, current string) string {
if len(entries) == 0 {
return ""
}
type latest struct {
entry MemoryEntry
order int
}
byStage := map[string]*latest{}
order := []string{}
for i, entry := range entries {
if item, ok := byStage[entry.Stage]; ok {
item.entry, item.order = entry, i
continue
}
byStage[entry.Stage] = &latest{entry: entry, order: i}
order = append(order, entry.Stage)
}
var b strings.Builder
skipped := 0
if len(order) > essentialLedgerLines {
skipped = len(order) - essentialLedgerLines
order = order[skipped:]
}
if skipped > 0 {
fmt.Fprintf(&b, "- … %d earlier stages in history.md\n", skipped)
}
for _, key := range order {
item := byStage[key]
line := fmt.Sprintf("%s · visit %d%s", oneLine(key), item.entry.Visit, outcomeSuffix(item.entry.Outcome))
if key == current {
line += " (this stage's previous visit; detail in history.md)"
}
b.WriteString("- ")
b.WriteString(capLine(line, essentialLineCap))
b.WriteString("\n")
}
fmt.Fprintf(&b, "\n%d turns completed.\n", len(entries))
return b.String()
}
func renderFiles(files []string) string {
files = sortedUnique(files)
if len(files) == 0 {
return ""
}
var b strings.Builder
shown := files
if len(shown) > essentialFileLines {
shown = shown[:essentialFileLines]
}
for _, name := range shown {
b.WriteString("- ")
b.WriteString(capLine(oneLine(name), essentialLineCap))
b.WriteString("\n")
}
if more := len(files) - len(shown); more > 0 {
fmt.Fprintf(&b, "- … and %d more\n", more)
}
return b.String()
}
func outcomeSuffix(outcome string) string {
if outcome == "" {
return ""
}
return " · outcome " + oneLine(outcome)
}
func atxHeading(text string) (int, string, bool) {
trimmed := strings.TrimLeft(text, " ")
if len(text)-len(trimmed) > 3 {
return 0, "", false
}
level := 0
for level < len(trimmed) && trimmed[level] == '#' {
level++
}
if level < 1 || level > 6 {
return 0, "", false
}
rest := trimmed[level:]
if rest != "" && rest[0] != ' ' && rest[0] != '\t' {
return 0, "", false
}
return level, strings.TrimSpace(strings.TrimRight(strings.TrimSpace(rest), "#")), true
}
func oneLine(text string) string {
return strings.Join(strings.Fields(text), " ")
}
func capLine(text string, limit int) string {
if len(text) <= limit {
return text
}
return cutAtRune(text, limit-len("…")) + "…"
}
func truncationNote(shown, total int, where string) string {
return fmt.Sprintf("\n\n_[truncated: %d of %d bytes shown; full text in %s]_", shown, total, where)
}
// truncateWithNote returns text unchanged when it fits limit, otherwise its
// head cut at a line (or rune) boundary followed by a pointer to the full text.
func truncateWithNote(text string, limit int, where string) string {
if len(text) <= limit {
return text
}
if limit < 0 {
limit = 0
}
head := cutAtRune(text, limit)
if i := strings.LastIndexByte(head, '\n'); i > limit/2 {
head = head[:i]
}
head = strings.TrimRight(head, " \t\n")
return head + truncationNote(len(head), len(text), where)
}
func cutAtRune(text string, limit int) string {
if limit <= 0 {
return ""
}
if len(text) <= limit {
return text
}
for limit > 0 && !utf8.RuneStart(text[limit]) {
limit--
}
return text[:limit]
}