Memory
Memory is what your teams’ runs have learned, so the next run starts knowing it. Andon keeps two kinds, split by what the memory is about:
| Team lessons | Repository memory | |
|---|---|---|
| About | the team, its people, machines and accounts: “the Mac mini has the GPU”, “keep PRs short” | the code: its conventions, decisions, traps, how-tos and words |
| Lives in | the board’s database, one list per team | the repository’s .andon/ folder, committed beside the code |
| Changed by | the Memory page, andon memory |
a pull request: runs, reviews and people propose entries, and a merge accepts them |
| Reaches | runs on this board, in their system prompt | every run that works in the repository, and any agent that reads the repository |
Both are reviewed on one page, the Memory page, and nothing reaches a run until a person accepts it.
Turn memory on or off
Memory is on by default. To change it for every team, open Settings → Automation, and set Remember lessons between runs.
To change it for one team:
- Open Settings → Teams and pick the team.
- In its Memory section, set Remember lessons between runs. A team that doesn’t set it follows Automation.
With memory off, a team’s runs get neither its lessons nor its repository memory, and its PR groups propose no
lessons. Runs (with the remember tool) and review rounds can still propose repository entries. Knowledge notes and
project plans still reach the runs.
Review what runs learned
- Open Settings → Automation → Memory. From a team’s settings, Open memory opens the same page for that team, with the number of proposals waiting.
- Pick a team at the top, or leave Every team.
- Pick a tab:
- Proposed: what runs, reviews and people proposed, waiting for you.
- Active: what runs are told now.
- Needs a look: entries a review contradicted, entries nobody has confirmed for six months, and files that don’t read. Its count is highlighted when something waits here.
- Narrow the list by kind, by the run it came from, by branch, or with Search the text.
- Decide on each row, or tick several and press Accept or Reject for all of them. All like this ticks every proposal one run brought in on one branch.
A proposal shows the run it came from, so you can check a lesson against the work that produced it. On a team lesson, Apply makes it active and Reject turns it down for good: the same lesson proposed again stays rejected. An active lesson can be pinned with Pin, which puts it first in every run’s prompt.
Accepting a repository entry opens a pull request on the repository (one for everything you accepted in one go, per repository and team). The entry counts once that pull request merges. An entry that so far exists only on a run’s unmerged branch is decided in that branch’s review instead.
Needs a look
| What you see | What to do |
|---|---|
| A review found an entry wrong, with its evidence and a correction | Supersede opens the edit dialog with the correction filled in. Keep says the review was wrong. Retire removes the entry. |
| An entry nobody has confirmed for six months | Confirm if it is still true, or Retire it. Until you do, runs don’t get it. |
| Two branches changed the same entry, or two entries say the same thing | Supersede both with one entry, or retire one. |
A file under .andon/ that doesn’t read |
Fix the file in the repository. |
An entry also counts as confirmed when a run that was given it finishes without a review contradicting it.
Add to memory yourself
- A team lesson. On the Memory page, Write a lesson: pick the team and kind, write What to remember, and press Write it. It is active at once. If the team has the same lesson already, that one is counted again instead.
- A repository entry. Pick one team on the Memory page, then Add an entry: the repository, Kind, Title and Entry, and optionally Tags and Paths. It becomes a pull request with that one file.
- From a card. On a message in a card’s conversation, or a line of its history, choose Remember this. Write the line, pick its kind (and the repository, when the team has several), and press Remember. The card’s next run writes it on its branch, so the run’s pull request carries it. To send it sooner, open the card’s Memory tab and choose Commit N proposals, which opens one pull request for them.
- From the repository’s own instructions. Pick one team on the Memory page, then Import from the repo. Andon
reads the repository’s
CLAUDE.md,AGENTS.md,GEMINI.md,.cursorrules,.windsurfrules,.github/copilot-instructions.md,.cursor/rules/anddocs/how-tos, and proposes an entry per rule and a knowledge note per how-to, as one pull request. The originals don’t change. Andon does this on its own the first time a machine reads a repository that has no entries yet, so you review it as a pull request.
Andon also adds a short pointer to the repository’s CLAUDE.md or AGENTS.md, so an agent outside Andon knows
.andon/ is there.
How runs learn on their own
- Runs propose repository entries with the
remembertool and edit knowledge notes with theknowledgetool (MCP tools). The built-in code recipes ask for this at the end of every run, at most five entries a run. The proposals ride the run’s pull request. - Reviews propose entries too. A finding you answer Leave as is with a reason becomes a proposed convention, with your reason as its text. A finding that needed fixing in two rounds of one pull request becomes a proposed gotcha.
- PR groups propose a team lesson when a group merged only after three or more review rounds, hit merge conflicts, or was split while building. Each kind is one lesson per team: later groups count it up (“came up 3 times”) rather than add another.
andon memory reflect <run-id>asks a model for up to three team lessons from one finished run. It reads the run’s summary, the card’s title and the team’s existing lessons, nothing else. The lessons wait on the Proposed tab;--applyrecords them as active instead. Seeandon memory.
Choose how much memory a run gets
A run gets the team’s lessons and the repository entries and notes that match what the card is likely to touch, best first, up to a budget. What doesn’t fit is left out and counted: the run’s history has a line saying what it was given, and the card’s Memory tab lists those entries.
To change the budget, open the team’s Memory section and set Size:
| Size | Team lessons | Repository entries | Knowledge notes and plans |
|---|---|---|---|
| Small | 3,000 characters | 1,000 tokens | 750 tokens |
| Standard (the default) | 6,000 characters | 2,000 tokens | 1,500 tokens |
| Large | 12,000 characters | 4,000 tokens | 3,000 tokens |
A team with custom budgets shows Its own budgets until you pick a size.
To keep repository memory out of one card’s run, add the label no-project-memory to the card, or write Run without
project memory in its title or notes.
Where a team keeps repository memory
By default .andon/ is committed in each repository. A team that wants its repositories left clean (a public
repository, say) can keep the same files elsewhere:
- Open the team’s Memory section and expand Advanced.
- Set Where it lives:
- In the repository:
.andon/in each repository, changed by pull requests. - In the extension repository: a second repository the team links for its own tooling. Pick it in the list
that appears. Each repository’s memory sits under
repos/<host>/<owner>/<repository>/.andon/there, and changes open pull requests on the extension repository. - On this instance: in each machine’s data folder, written directly, committed nowhere.
- In the repository:
Changing it doesn’t move the existing files: the new place starts empty, and Andon offers an import on its first read.
Keeping memory small and true
Entries are never edited in place: a change is a new file that supersedes the old one. Over time that adds up, so a
machine with the repository proposes a compaction when .andon/ passes 200 entry files or about 60,000 tokens. It
folds each chain of changes into one file, drops retirements older than 90 days, merges near-duplicates and splits
long notes, all in one pull request you review. It never merges on its own. To ask for one now, pick the team on the
Memory page, open Active and press Compact now beside the repository.
Ask the chat about memory
The board’s chat can read a team’s repository memory: ask it “how does the web team handle migrations?” and it looks up the accepted entries on the default branch, at most 20, and the titles of the knowledge notes. It reads only teams you can see. It can’t change memory; use the Memory page for that.
See also
- The
.andon/directory format: the files, their fields and an example entry. andon memory: list, search and show memory from a terminal.- Writing a recipe: where
{{memory}}and{{knowledge}}go in a prompt. - Memory internals: how selection, ranking, compaction and the index work.
