Part 13 left the consumer app's memory index at 138 entries and 15.5 KB, with a new rule for archiving finished tickets. That rule handles future growth from tickets. It doesn't touch the other 40 or so notes, which were never personal in the first place: how-tos, plus facts about the code and the backend.
The developer's reply to the plan was "go, do 2 and 3".
Pay for what you load
Every place an agent can keep knowledge has a loading cost:
- The memory index loads in full in every session, whether a line is relevant or not.
- The instruction file also loads in every session. It is shared through git, so it is for rules the whole team follows.
- A skill costs one description line per session. Its body loads only when a task calls for it.
- A document in the repository costs nothing until someone reads it. A one-line pointer in the instruction file says when to.
- A comment at the code costs nothing until someone opens that file, which is exactly when it matters.
The memory index was paying the highest price for knowledge that belonged further down this list.
Memory has a second cost, and the commit message for the move puts it plainly: "Device know-how lived in one person's agent notes." Auto memory belongs to one developer and lives outside the repository, so a teammate, or another agent on another machine, never sees it.
Procedures became skills
Need Help Implementing This?
Our team can help you put these ideas into action. Get in touch for a free consultation.
Nineteen notes on driving the physical test phones became skill content:
- A new iOS device skill. It covers finding the phone, building a debuggable app, pointing the app at the development server over USB, proving which JavaScript bundle the phone is actually running, recording a gesture the human performs, and reading device logs.
- A shared reference for running code inside the app over the Chrome DevTools Protocol, used by the iOS and Android skills alike. It covers pressing the app's own controls, recording navigation actions, capturing console output and injecting a push notification.
- The existing Android skill gained the device traps and recipes that had been sitting in memory.
The shared reference opens with a rule the developer set earlier that same morning. A previous device check had built the navigation stack by hand and passed, and it missed a real bug. The developer's words were "Your mimicking navigation is so unreliable … Go with proper scenario test". Behaviour checks now walk the real signed-in path on the real phone. Part 7 covers how the phones are driven.
The rest of the how-tos went to two other homes:
- Over-the-air updates. Thirteen notes on the update service went into its runbook in the repository, as a new troubleshooting section. Which person holds which production credential stayed in memory, merged into one note, because that doesn't belong in a commit.
- Figma. Seven notes on reading and building design files became a skill at the user level, outside the client's repository, because they hold workspace details.
Facts moved next to what they describe
The code facts became comments at the code. Some examples:
- A bottom sheet renders its children while it is closed, so that it can measure them. A test that finds the content proves nothing about the sheet being open. Assert on the open state instead.
- A timed-out request never arrives as a timeout error. The data-fetching library reports a timeout only for an error with one particular name, and React Native's
fetchrejects every abort with a different one. Treat any error as the failure. - The profile restored at launch is the one saved at sign-in. After a relaunch it can predate a change of name or email, so gate decisions on a fresh fetch.
- Re-tapping a tab to reset it works on one tab only, and that's a product decision. The comment now says so, so nobody "fixes" it.
Facts about the backend went into a new document of what the backend has been seen to do that its API documents don't say: refresh tokens that don't rotate, filters that are accepted and then ignored, the shape of notification payloads, and how to probe whether a route exists.
The instruction file gained a pointer to that document, three test traps, and a correction. One of the traps: CI runs the tests in UTC while the app renders dates in the device's time zone, so a fixture can pass locally and fail in CI. The correction: the file had said the app supports light and dark mode, but the app is always light. Part 4 quoted that same correction as an example of what goes into memory. It had been sitting in memory, where only one developer's agent could see it, while the shared file told everyone the opposite.
About 20 of the facts turned out to be documented already, in a comment, the feature-flag file or the instruction file. Those notes were plain duplicates. The agent archived them and left the code alone.
Writing at the code is a check
When a fact moves out of memory and into a comment, it gets checked against the code it describes, which never happens to a memory note.
- A wrong name. One new comment cited a query hook by a name that doesn't exist. The agent searched for it before committing, found the real hooks and corrected the comment.
- The usual checks. The full test suite passed (317 suites, 2,893 tests), and type-check, lint and formatting were clean on every changed file. The diff was comments and docs only: 14 files, 569 lines added and 4 removed.
- A stated gap. The commands in the new skills came from earlier sessions where they had worked, and the agent said that it hadn't re-run them end to end.
The agent also kept some things out of the commit: device identifiers, internal network addresses, credential ownership and design-workspace details. Those stayed in memory or in the user-level skill.
The numbers
| Entries | Index size | |
|---|---|---|
| When the developer asked | 154 | 17.2 KB |
| After step 1, the archive | 138 | 15.5 KB |
| After steps 2 and 3 | 49 | 5.7 KB |
The agent had estimated about 70 entries and 8 KB. Ninety notes moved in fifteen minutes. The archive index groups them by where each fact now lives, so a later session can follow an old note to its new home.
The developer's input for the whole overhaul was the opening question, "1", "go, do 2 and 3", and a message once the pull requests had merged.
The full lifecycle in an hour
The bug fixed that morning ended up testing the new rule:
- 08:11. While fixing the bug, the agent wrote a memory note about the trap behind it. On iOS, a screen that blocks going back with
usePreventRemovemust also setgestureEnabled: false. Otherwise the edge swipe starts a native back animation that then gets cancelled, and a redirect fired from that callback can leave the destination screen blank. - 09:11. The fix merged. The agent pointed out that the lesson applied to any such screen, but the repository only explained this one.
- 09:13. A one-line pull request added the lesson to the instruction file's list of gotchas.
- 09:26. That pull request merged, and the agent archived the memory note, because the lesson now lived in the repository.
Once that note was archived, the index stood at 48 entries and 5.6 KB.
The rule that keeps it small
The routing rule lives in memory, the one place guaranteed to load in every session. It says where each kind of fact goes:
| A fact about… | Lives in |
|---|---|
| A trap in the code | A comment at the code |
| Backend behaviour the API docs don't cover | The backend behaviour document |
| Over-the-air updates | The update service's runbook |
| Driving a device | The device skills |
| A team-wide convention | The instruction file |
| The design files | A user-level skill |
| A finished ticket | The archive, after anything live is lifted out |
| The developer's rules, the environment, credentials, open bugs, live decisions | Memory |
In one line: memory keeps only what the repository can't hold.
What we don't know yet
A day later the index has 50 entries and 5.8 KB. Both new entries are notes on new design work, and one of them arguably belongs in the design skill. A rule written as a memory note still depends on the agent applying it.
- One day proves little. Ticket work is still the main source of growth, and archiving only happens when a session notices that its pull request has merged.
- The archive works only if it's searched. Archived notes are dated snapshots, so the code has to be checked before trusting one.
- The skills haven't been fully re-run. Their commands get their first full run the next time someone drives a phone.
What to copy
- Rank storage by loading cost. Push each fact as far down the list as it can go while still being found when it's needed.
- Turn rarely used how-tos into skills. They cost one line until they're used.
- Put code facts in comments at the code, and check each one against the code as you write it.
- Collect undocumented backend behaviour in one document, and point to it from the instruction file.
- Promote a lesson out of personal memory once it applies to everyone, then archive the note.
- Keep machine identifiers, internal addresses and credential ownership out of commits.
- Write the routing rule where it loads in every session.