Make the Repository the System of Record
A chat window is RAM: fast, and wiped the moment the session ends. The repo is the disk. Anything that needs to outlive today has to be written down where tomorrow's session can find it.
If a road is not drawn on the map, the driver cannot take it, no matter how well they know the city in their head. A new agent session knows only what the repository tells it. A rule that lives in Slack, in your memory, or in a closed chat is a road that does not exist as far as the agent is concerned.
Volatile memory vs. durable state
Everything an agent "knows" mid-session lives in a context window that will be summarized, truncated, or discarded. Treat that as working memory, never as the source of truth. The moment a rule, a decision, or a piece of progress only exists in the chat, you have a single point of failure that the next session cannot recover.
The fix is a discipline: anything that must survive gets written to a file and committed. The repo becomes the one place both you and the agent agree is real.
flowchart LR S["Rules in chat"] --> W["Write into repo files"] Head["Rules in your head"] --> W W --> Repo["feature_list.json, AGENTS.md, handoff.md"] Repo --> A["New session reads the repo"]
What belongs in the repo
- Rules and constraints, in
AGENTS.mdand topic docs, not re-explained each session. - The plan and its status, a feature list the agent updates as it goes.
- Decisions and their rationale so they are not silently reversed later.
- Handoff notes, what was done, what is next, what is risky.
If it is not committed, assume it is gone. Git history then doubles as an audit log of how the work actually unfolded.
How Agentum reinforces it
Agentum's Harness Engine treats the repo as the record literally. It persists each feature's state, pending → coding → verifying → done, back into .agentum-harness/feature_list.json, so a restarted daemon (or you, opening the board) sees the live truth from disk, not from a session's memory. After every green feature it overwrites handoff.md with the current state. The harness directory lives in your working tree, versioned and recoverable, not in a chat on someone else's server.
Key takeaways
- The chat is working memory; the repository is the system of record.
- If it matters past this session and it is not committed, it does not exist.
- Rules, plan, decisions, and handoff notes all belong in files the agent reads.
- Git history becomes a recoverable audit trail of the work.
Exercises
- Audit visibility. List three rules your agents should follow. For each, is it written in the repo or only in your head?
- Move one rule. Take the most important unwritten rule and commit it to AGENTS.md.