All pages

Agentic development foundations · Lesson 2.2 · 12 min

Context that sticks

Pinned files, notes, memory and project instructions that carry across sessions.

After this lesson you can decide where each thing the agent should know belongs, so the next session starts from what the last one learned: project instructions in the repository, notes for the work in hand, pinned files, memory, and the conversation's own scratchpad.

Time: 12 minutes · Works on: macOS app.

The agent forgets, so write it down

Every new conversation starts empty. Whatever you explained yesterday, the command that runs the tests, the folder nobody should touch, the reason you chose one library over another, is gone unless it was written somewhere the agent reads. If you find yourself typing the same sentence into a third brief, that sentence belongs in context, not in the brief.

But more context isn't better context. Everything you load costs tokens on every turn and competes for the model's attention. A file of forty stale rules is worse than a file of five true ones, because the agent learns to skim it. The skill is putting each fact in the right place, at the right lifetime, and keeping it true.

Where each fact belongs

Think of context as layers, from the longest-lived to the shortest.

Layer Lives for Put here
Project instructions (AGENTS.md, CLAUDE.md) The life of the repo, shared with the team How to build and test, conventions, where things are, what not to touch
Standing rules (docs/doctrine/*.md) The life of the repo Decisions every agent must follow, each with its reason
Memory Across conversations Your preferences, corrections you've made, pointers to outside systems
Project notes This stretch of work What you're doing this week, a flaky service, a branch to avoid
Pinned files Until you unpin them The schema or style guide every task needs
Scratchpad One conversation The agent's own working notes on a long task
The brief and @ files One message Anything specific to this task

Two rules decide most cases.

  • If a teammate, or an agent on another machine, needs it, it goes in the repository. Files in the repo are versioned, reviewed in a diff, and travel with the code. Notes and memory live in TRMNLY's data on your Mac.
  • If it will stop being true soon, keep it out of the repository. "The staging database is down until Thursday" is a note, not an instruction.

Write project instructions that work

An instructions file is read on every turn, by every agent. Write it as you would a page of onboarding for a sharp new hire who has one minute.

# AGENTS.md

## Build and test
- `npm install` once, then `npm test` for the suite.
- One file: `npm test -- path/to/file.test.ts`.
- `npm run lint` must pass before a commit.

## Layout
- `server/` is the API (Express). `web/` is the Next.js app.
- Database migrations are in `server/migrations/`, numbered. Never edit
  an existing migration; add a new one.

## Conventions
- Money is integer cents everywhere. Format only at the edge.
- New endpoints get a test in the matching `*.test.ts` file.

## Don't
- Don't touch `vendor/`. It's generated.
- Don't add dependencies without saying why in the commit message.

Each line is either a command the agent can run, a fact it can't easily discover, or a rule with a reason close by. Leave out anything the agent can work out in one ls. Review the file when an agent gets something wrong: if the answer was in the file and it was missed, the file is too long; if it wasn't there, add one line.

Let memory hold what's about you

Memory is for what's true across projects or about how you work: "prefers small commits", "use pnpm, not npm, in personal projects", "the team dashboard is at this URL". When you correct the agent and the correction should outlast the conversation, tell it to remember. When a memory goes stale, delete it. A wrong memory does more harm than a missing one, because the agent trusts it.

Do it in TRMNLY

Set up each layer once, then look at exactly what the model receives.

  1. Project instructions. Make sure the project has an AGENTS.md or CLAUDE.md at its root. The built-in agent reads files like AGENTS.md, CLAUDE.md, README.md and package.json from the root when the Project README / docs source is on. Open the agent's gear menu, choose Scope (projects & tabs)…, and check it under Include. The project-wide default is in Project agent settings… as Include project context (CLAUDE.md, README.md, …).
  2. Standing rules. For rules several agents must follow, create a docs/doctrine/ folder in the repo and add a short .md file per decision. TRMNLY adds those files to the context of agents working the project. Create the folder yourself; TRMNLY won't write into your repository unasked.
  3. Project notes. Choose More → Notes in the right sidebar and write what's true this week. Make sure Project notes is on in the scope sheet. A project can have several notes; the active one is the one the agent reads.
  4. Pinned files. In the Files tab, select the schema or style guide and use Pin to agent. Pins are capped at 24 KB per file, so pin the small, dense files and let the agent read the rest on demand. Review pins with the gear menu's Pinned files….
  5. Memory. Tell the agent, for example, Remember that I want one commit per logical change. Then open the gear menu's Memory… to see what it saved. Memories are typed as user, feedback, project or reference. Edit or delete anything that's wrong.
  6. Scratchpad. On a long task, ask the agent to keep its plan and progress in the scratchpad. Open Scratchpad… from the gear menu to read or edit it.
  7. Check the result. Open What the model sees… from the gear menu. The Context Inspector shows the context for the next turn, block by block. Turn a source off in the scope sheet and open the inspector again to watch it disappear. Use this whenever the agent ignores something you thought it knew.
  8. Give Claude Code the same footing. Claude Code doesn't get the context the built-in agent assembles; it reads its own CLAUDE.md files. In Settings → AI Agent, under Project context (TRMNLY.md), press Add TRMNLY.md to current project. That writes a TRMNLY.md telling Claude Code which TRMNLY tools it has, adds @TRMNLY.md to CLAUDE.local.md so Claude Code actually reads it, and keeps both files out of git so nothing tracked changes. Your shared instructions still belong in CLAUDE.md or AGENTS.md.

Check yourself

  • You can say which layer a new fact belongs in, and why.
  • Your project's instructions file names the test command, and the agent used it without being told.
  • What the model sees… shows your pinned file and your project note.
  • Memory… holds a memory you asked for, and you deleted or fixed one that was wrong.

Go further

  • Context and memory — every context source, step by step
  • Specs before code — the context a larger change needs
  • Projects — project context and TRMNLY.md in detail
  • Notes — several notes per project and the notes tools
  • Fleet — doctrine for many agents on one project