arch: pick a direction for agents/{name}/history.md vs the governed memory model #1243

Summary

Squad currently has two parallel paths for an agent to record "I learned X", and they have very different behavior. The runtime supports both without a clear story for which to prefer. This issue asks the maintainers to pick a direction.

The two paths today

Path 1 — append to .squad/agents/{name}/history.md

• Direct file append; no classification, no audit
• Loaded in full at every spawn of that agent (subject to the 12KB summarization rule documented at docs/src/content/docs/concepts/memory-and-knowledge.md)
• Owner-only read (no search, no cross-agent visibility)
• This is the "Personal history" layer in the three-layer memory model

Path 2 — squad memory write --class LOCAL --author {name} --content "..."

• Routed through LocalMemoryStore.write() at packages/squad-sdk/src/memory/index.ts:667-861
• Lands at .squad/memory/local/{author}-{slug}-{id}.md (per destinationPath() at memory/index.ts:1328-1338)
• Classified, audited, indexed; default loadGuidance: ON-DEMAND (per loadGuidanceFor() at memory/index.ts:428-440)
• NOT auto-loaded at spawn — only surfaces via memory.search when an agent (or the coordinator) explicitly queries
• Searchable cross-agent

Side-by-side comparison

Why this matters

A user reading the docs writes a directive like "Always run SDK tests before merging". Two things can happen:

• An agent appends this to its history.md → it's part of every future spawn of that agent (heavy context cost; correct content survives but every other agent doesn't see it)
• The coordinator calls memory.write --class POLICY → it lands in policy-inbox/, Scribe merges into decisions.md → every agent sees it on next spawn, audited, classified

The runtime supports both. Today there's no rule for which path takes which kind of write. The result:

• Inconsistent context cost (some agents heavy, others light)
• Inconsistent governance (some content audited, some not)
• Inconsistent visibility (some learnings cross-agent, some siloed)
• No migration story (a team that started before governed memory has heavy history.md files; a team starting after has light ones)

Three concrete options for the maintainers

Option A — Keep both paths as-is, just document the rule

• history.md stays as the auto-loaded personal context
• Governed memory stays as the audited, searchable, on-demand layer
• Document when to use each: history for "this agent's persistent context", governed memory for "team-wide signals + safety governance"
• No code change. Just docs.

Option B — Derive history from governed memory

• history.md becomes a generated VIEW of the memory index filtered by author={agent name}
• All "I learned X" writes go through memory.write --class LOCAL
• Spawn-time history load = "give me the LOCAL entries authored by this agent, classified ALWAYS"
• One write path. Governance and audit on every write. Per-author scoping preserved.
• Code change: rewrite history append, rewrite history read at spawn, migration tooling for existing history.md files

Option C — Make history.md class-aware

• Each entry in history.md gets a class + loadGuidance via frontmatter
• Spawn-time read pulls only loadGuidance: ALWAYS entries; surfaces ON-DEMAND on search
• Massive context-cost reduction per spawn (most "I learned X" is ON-DEMAND, not ALWAYS)
• Code change: history format, history read path, Scribe summarization rules, possibly the spawn prompt builder

What's NOT being proposed

• Removing history.md entirely (would break existing agents)
• Forcing governed memory for everything (some content really is single-agent context)
• Changing decisions.md behavior (it works; this is about the per-agent layer)

Evidence — code citations

• Three-layer memory model docs: docs/src/content/docs/concepts/memory-and-knowledge.md (3 layers: Skills / Decisions / History)
• Governed memory write paths: packages/squad-sdk/src/memory/index.ts:1328-1338 (destinationPath() — never writes to agents/)
• Load guidance defaults: packages/squad-sdk/src/memory/index.ts:428-440 (loadGuidanceFor() — LOCAL defaults to ON-DEMAND)
• History.md spawn-time read: packages/squad-sdk/src/tools/index.ts:592 (reads history.md content — separate from memory store)
• Coordinator spawn template: .github/agents/squad.agent.md "Full Spawn Template" section — instructs to inline charter/history/decisions

Decision needed

This issue isn't blocking anything urgent. But the longer the runtime supports two parallel paths without a documented preference, the more inconsistent team behavior gets — both within a team and across teams adopting Squad at different points in 0.10.x.

What would help:

• A maintainer comment picking A, B, or C (or a fourth option I missed)
• If A: a docs PR can follow this issue
• If B or C: a design discussion before any code change