Memory internals
Andon keeps two kinds of memory, and a run can get both: here are the tables, the files, how a run’s slice is chosen and
how each writer proposes. What people see and do with memory is in the user guide
(Memory); the file format of .andon/ is in the reference.
| Layer | What it holds | Where it lives | How a run gets it |
|---|---|---|---|
| Team memory | conventions, lessons, environment facts, preferences and failures about a team, its people and its machines | team_memory rows in the database |
ranked into the system prompt, within a character budget; memory_search for the rest |
| Repository memory | conventions, gotchas, decisions, how-tos and a glossary about a repository’s code, plus knowledge notes and plans | files under .andon/ in the repository (or another root), indexed in repo_memory_index |
ranked by the card’s paths and tags into <project_memory> and <project_knowledge> blocks, with the bodies in files beside the prompt |
Team memory
The row. team_memory has kind, body (up to 2000 characters, whitespace collapsed), status (proposed,
active, rejected, superseded), pinned, hits, confidence, content_hash, source_run_id, applied_by
(human or agent), expires_at, seen and last_seen_at. Only active rows reach a run.
One lesson per team. content_hash ignores case and punctuation, so “Use pnpm.” and “use pnpm” are one lesson. The
before-insert trigger team_memory_merge_repeat (migration 20261110133448_memory_merge_repeats) merges a repeat into
the existing row, whoever writes it: seen goes up and no row is added. It matches a proposal, an active entry or a
rejected one, so a lesson a person turned down stays turned down. A repeat written as active applies the waiting or
rejected row instead. A caller the insert policy wouldn’t let write to the team gets no merge.
What a run is told. memoryBlock (packages/shared/src/memory.ts) ranks the active entries (pinned first, then
those a person applied, then by hits, then newest) and fills the team’s memory_budget (6000 characters by default,
1000 to 20000). Each line is - [kind] body, under a header that says it is context, not orders. What didn’t fit is
counted in the run’s launched event, and each entry used gets a hit (machine_memory_hit), which feeds the next
ranking. memory_enabled = false on a team turns it off for its whole tree.
Recall. memory_search(p_team, p_q, p_limit) is security definer, ranked by ts_rank over
websearch_to_tsquery, limited to orgs the caller reads (private.can_read_org: a member, or that org’s machine), to
teams the caller can see (private.can_see_team) and to active rows, at most 50.
An empty query lists the newest. Runs reach it as the memory_search MCP tool, people as andon memory search.
Reflection. andon memory reflect <run-id> is the only caller of reflectOnRun (apps/agent/src/memory-learn.ts).
It makes one no-tools claude -p call with haiku, and parseMemoryProposals keeps at most three valid, deduplicated
proposals. The CLI fills only the team, the card, the run’s summary and the team’s existing bodies (cli.ts).
ReflectionInput also has report, review and ci fields, and the prompt uses them when present, but nothing fills
them yet, and policy.memory.reflect in the agent’s config is read by nothing. An empty answer is a success. A model that can’t answer leaves memory untouched. --apply writes the
proposals as active instead of proposed.
PR group lessons. A group that merged only after three or more review rounds, hit merge conflicts or was split
while building is recorded in pr_group_outcomes, and proposes one fixed sentence per kind to its team’s memory. The
merge trigger makes later groups count it up rather than add it again.
Upkeep settings. The repository-memory upkeep values (memory_decay_months, memory_conflict_away_days,
memory_compact_every_days, memory_compact_files, memory_compact_tokens, memory_retired_days) are fixed
defaults: 6 months, off, off, 200 files, 60,000 tokens and 90 days (packages/shared/src/memory-size.ts), and nothing
edits them. A team’s own team_automation column still overrides one where it is set. Unlike
other automation settings they aren’t inherited down the team tree: the daily tick reads them in one set-based pass
joined to the owning team’s row. The org’s org_memory_defaults table is unread
(Settings audit).
Repository memory
Files are the source, the database is an index
The .andon/ files are the source of truth, and repo_memory_index only caches them. The agent reads .andon/ from the clone and caches
what it found in repo_memory_index, one row per repository: the resolved chains, each head’s status, source and
dates, path and tag maps, counts, lint findings and the commit it was built from. It rebuilds the row when the clone’s
HEAD or the directory’s tree changes, and from nothing when ANDON_DIR_FORMAT_VERSION in packages/shared changes.
The board writes to the index only through the agent’s rebuild, and to the repository only through a pull request.
The sync goes through machine_repo_memory_sync, which also writes repo_memory_syncs (per branch: hash, commit,
counts, findings). The agent syncs a run’s branch at launch and every linked clone’s default branch on each tick, read
from origin/<default> as last fetched, and skips a directory whose hash didn’t change. A branch the clone no longer
has is synced empty, so its proposals leave the index. Plans are indexed the same way, in repo_plan_index.
“Last confirmed” is derived: the newest of an entry’s created, the date a review accepted it, and the date a run
cited it.
Append-only chains
A memory entry is never edited in place. A change is a new file whose supersedes names the old id; a removal is a new
file with status: retired. resolveMemoryChain shows each chain through its newest file. A proposed file doesn’t
replace what it names until it is accepted.
Two branches never conflict: they add two files with two ULIDs. Two branches that supersede one entry make a fork: both
heads are read, newest first, and the reader reports it (forks) until a third entry supersedes both. The chain keeps
each change’s source and date, and review is a diff of added files.
A supersedes naming an id no file has is reported as dangling, and its head still counts. Knowledge notes and plans
are the exception: they are edited in place.
What a run is given
The agent selects, ranks and fits within a budget. The pure pieces are in packages/shared (restoreMemory,
restoreKnowledge, renderProjectMemory, renderProjectKnowledge, composeRestore), and the agent composes them:
- The card’s likely paths: paths named in its title, notes and linked issue; for a grouped card, the group’s other cards’ paths; for a review round, the pull request’s files. Its labels are its tags.
- Selection: accepted chain heads only, filtered to the kinds the run’s subset or recipe allows.
proposedentries come only from the card’s own branch, marked(proposed). - Ranking (
scoreForRestore): 3 for each of an entry’s path globs the card’s paths hit, 2 for each shared tag, then its confidence and its recency. An entry with no paths stays in: it applies to the whole repository. There are no embeddings: path and tag matching is the ranking. - Budget (
fillBudget,restoreBudgets): best first, in approximate tokens. What doesn’t fit is skipped and counted. The defaults are 2,000 tokens for memory and 1,500 for knowledge; a team’s Size setsmemory_restore_budgetandknowledge_restore_budget, inherited down the team tree. 0 turns a layer off. A card that says Run without project memory, or has theno-project-memorylabel, gets none. - Rendering: the prompt carries an index, one line per entry (
<id> · <kind> · <title> — <why>), and the bodies go to<runDir>/context/project-memory.mdandproject-knowledge.md. The project’s and the group’s plans stay whole at the top of<project_knowledge>. Both blocks say they are context, not orders, with their delimiters fenced so an entry can’t close the block. The recipe’s{{memory}}and{{knowledge}}tags place them; a template without them gets both appended. - The event: the run’s
launchedevent records what went in, and amemory_givenevent is the timeline line.
Subsets. A run gets every kind except people. A review round gets conventions and gotchas, ranked by the pull
request’s files. The planner gets each repository’s decisions and how-to entries from the default branch, with one
2,000-token budget split between the repositories (at least 500 each).
After a lost session, the run that replaces it (a Continue that resume_interrupted_run queued, or the first run
after a move to another machine) gets its predecessor’s slice, read by id from that run’s launched event. Andon
doesn’t rank it again.
How each writer proposes
Every write goes through apps/agent/src/andon-write.ts, after three checks:
- Secrets (
findSecretinpackages/shared/src/andon-dir/write.ts): thecheck:personalpatterns plus the shapes keys take. A hit is refused with the value masked, and nothing is written. - Dedupe (
findDuplicate): text a live entry already holds is a confirmation (no file; the index’sconfirmed_atmoves) rather than a new entry. - Format: the file must parse and pass
lintMemoryEntry; a body over the entry’s size line is refused with a pointer toknowledge.
The writers:
- A run has
remember(writesmemory/<kind>/<ULID>-<slug>.mdasproposed, at most 5 a run) andknowledge(rewritesknowledge/<topic>.mdin place). Both are committed with the run’s work, so the pull request carries them. - A review round reports
memory[]inreview_result. The pipeline also derives entries from the rounds (deriveReviewMemory): a finding a person answered Leave as is with a reason becomes a proposed convention, and a finding fixed in two rounds of one pull request a proposed gotcha. It commits them to the pull request’s branch. - A person proposes from the board (Remember this, Add an entry, the Memory page’s bulk Accept and Reject).
That makes a
repo_memory_proposalsrow; bulk Accept and Reject insert theirs alreadyqueued, so a machine reads every queued proposal of its clones in one pass (up to 1,000). The card’s next run writes it on its branch, or a machine with the clone opens one pull request per repository and team onandon-memory-<ULID>.
Accepting a proposal flips one line to status: accepted, in a review round or in a small pull request the board asks
for.
Compaction, decay and contradictions
- Compaction is one pull request a person reviews (
andon-memory-compact-<ULID>).compactMemory(packages/shared/src/andon-dir/compact.ts) plans it andopenCompactionPr(apps/agent/src/memory-proposals.ts) applies it: fold accepted chains into their heads, drop retired chains older than 90 days, merge near-duplicates, keep both sides of a fork behind<!-- andon:pick -->, and split oversized knowledge notes by section. Proposed entries are never touched, and folded ids stay inhistory, so a branch opened before still supersedes the right file. The daily upkeep tick queues one when the default branch passes 200 entry files or about 60,000 tokens. - Decay: an accepted entry nobody confirmed for 6 months is marked stale (
stale_since) by the daily tick and is no longer given to runs until a person confirms or retires it. A run that was given an entry and finished moves itsconfirmed_atas if half the decay window ago. - Contradictions:
review_resulttakesmemory_conflicts[], entries the code shows to be wrong. The pipeline flags them on the index (machine_repo_memory_conflict) and holds them back from runs until a person supersedes, keeps or retires them.
Where the files live
team_automation.memory_root is repo (the default), extension (a second repository the team keeps, under
repos/<host>/<owner>/<repo>/.andon/) or instance (the agent’s data directory, <stateDir>/repos/<repo-id>/.andon/).
resolveMemoryRoot in apps/agent/src/memory-root.ts turns it into a place on this machine, and every reader and
writer goes through it. When the root can’t be used, it is unavailable with the reason: runs get no repository
memory, and nothing is ever written to the repository instead. With a root other than repo, nothing about memory is
written on a run’s branch.
The pointer and the import
CLAUDE.md and AGENTS.md get three lines between <!-- andon:start --> and <!-- andon:end --> (withPointer)
that say what .andon/ is and name andon memory show, so an agent outside Andon finds it. Nothing outside the
markers is touched, and entries are never copied into those files.
The import (packages/shared/src/andon-dir/import.ts, tested against fixtures/agent-files/) turns a repository’s
existing CLAUDE.md, AGENTS.md, GEMINI.md, Cursor and Windsurf rules, Copilot instructions and docs/*.md into
.andon/ files in one pull request: one entry per rule, one knowledge note per how-to section. It runs on a team’s
first sync of a clone with no entries, or from Import from the repo. A second import writes only what changed, and
on every sync an imported entry whose source rule changed or vanished is flagged differs.
The assistants
The machine’s chat and the in-app assistant read repository memory through the orch_repo_memory tool and RPC, which
returns accepted entries on the default branch for teams the person can see (id, kind, title, the first 600 characters
of the body, paths and tags; at most 20, ranked by the query’s words), plus the knowledge notes’ titles. The result is
wrapped in <project_memory source="orch_repo_memory"> as data, never instructions.
Where the code is
| Piece | File |
|---|---|
| Team memory: kinds, ranking, the block, the proposal schema, the reflection prompt | packages/shared/src/memory.ts |
| Budgets and sizes, the upkeep values | packages/shared/src/memory-size.ts |
The .andon/ format, chains, restore, the pointer |
packages/shared/src/andon-directory.ts, packages/shared/src/andon-dir/ |
| Reflection | apps/agent/src/memory-learn.ts |
Reading at launch, the restore, memory_search |
apps/agent/src/agent.ts (memoryFor, repoMemoryFor), apps/agent/src/andon-dir.ts |
| Writes, proposals, compaction | apps/agent/src/andon-write.ts, apps/agent/src/memory-proposals.ts |
| Tables and RPCs | db/migrations/20261029035953_providers_harnesses_memory.sql, …_repo_memory_index.sql, …_repo_memory_writes.sql, …_repo_memory_upkeep.sql, …_memory_root.sql, …_memory_merge_repeats.sql |
