THE LONG MEMORY

Cross-session intelligence that makes every build smarter.

Every project accumulates knowledge that code review can't catch. API rate limits. The reason you chose Postgres over SQLite. That one root cause that took three sessions to find. Without LEARNINGS.md, your next session starts from zero. With it, every agent reads the operational context before writing a single line.

Bashir

WHAT ARE OPERATIONAL LEARNINGS?

Operational learnings are verified facts discovered by live testing that code review alone cannot catch. They live in docs/LEARNINGS.md and persist across sessions.

WHAT GOES IN

API quirks — “Stripe webhooks retry 3x with exponential backoff, but the retry header is undocumented”
Decision rationale — “We chose Redis over Memcached because we need sorted sets for the leaderboard”
Root causes — “The NaN comparison bug was caused by passing a config object where a number was expected”
Environment constraints — “Vercel functions timeout at 10s, not 30s, on the free tier”

WHAT STAYS OUT

Code patterns — belong in docs/LESSONS.md (cross-project)
Methodology gaps — belong in field reports (upstream fixes)
Config values — belong in .env
Opinions — don't belong anywhere persistent

THE LIFECYCLE

Learnings flow through a pipeline. They're proposed, approved, read, and eventually promoted or archived.

1
DISCOVER
During a build or campaign, agents encounter operational facts — an API that behaves differently than documented, a decision that needs rationale, a root cause that took multiple attempts to identify.
2
EXTRACT
/debrief proposes candidate learnings after each session. O'Brien traces root causes, Nog proposes solutions, and Bashir drafts structured entries with category, scope, and evidence.
3
APPROVE
You review each candidate. Approved entries are written to docs/LEARNINGS.md. Rejected ones are discarded. You control what persists.
4
CATCH
/vault runs at session end and catches any learnings that /debrief missed. This is the safety net — if a learning was discovered but not captured, the vault catches it.
5
READ
Next session: /build, /campaign, /architect, /assemble, /qa, and /security all load LEARNINGS.md at startup. Every agent starts informed.
6
PROMOTE
Learnings that appear in 2+ projects get promoted to docs/LESSONS.md via Wong's pipeline. The original entry is replaced with a pointer. Facts move forward; they don't duplicate.

GUARDRAILS

entry hard cap

90d

staleness flag

projects → promotion

The file is created automatically when you approve your first learning. Projects that don't need it get zero overhead.

The Prophets see all timelines at once. Your agents don't — but with LEARNINGS.md, they see every timeline you've already walked. That's the closest thing to prophecy this forge has.