Memory Notes
Compact durable context for non-obvious repo behavior and decisions
Memory notes store compact knowledge that future agents are unlikely to infer from file names alone. They are for hard-won behaviors, gotchas, setup quirks, and architectural decisions that should survive session boundaries.
In Harness repositories, memory notes sit below source files in authority. They help locate or interpret evidence; they do not replace current repo inspection.
Good Note Material
Write or update a note for:
- a non-obvious setup or config quirk
- an edge case that took investigation
- a project convention that is easy to violate
- a decision that explains why an apparently simpler path is wrong
- a validation trap future agents are likely to repeat
Do not write notes for:
- basic file locations
- generic session summaries
- facts already obvious from current source
- long transcripts
- temporary status that should live in a plan, spec, issue, or log
Index Discipline
The note index should stay lean: one line per note, enough to route future readers. A note should explain why the fact matters, not only what happened. Update an existing note when possible instead of creating parallel fragments.
The same principle applies to routed wiki docs. Durable product or methodology knowledge belongs in wiki pages. A memory note is a routing aid and a gotcha store, not a second article tree.
Use During A Run
Use memory when:
- the user references previous decisions
- the repo task is ambiguous and likely depends on past choices
- a known setup, scaffold, or branch convention could affect the answer
- prior validation failures may explain current symptoms
After reading memory, verify drift-prone facts against current source when verification is cheap. Report unverified memory-derived facts as memory-derived when they matter.
Relationship To Docs Ingest
docs-ingest-phase asks whether a change created durable knowledge. If the answer is yes, put it in the canonical surface:
- routed wiki pages for product, methodology, concepts, and flows
- routed project pages for specs, plans, project operations, and decisions
- root docs or runbooks for setup and operator workflow
- memory notes only for compact gotchas that do not deserve a full page
This keeps memory useful without making it the hidden source of truth.