Skip to content
AndonDocs
GitHub
Change Andon

Memory internals

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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:

  1. 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.
  2. Selection: accepted chain heads only, filtered to the kinds the run’s subset or recipe allows. proposed entries come only from the card’s own branch, marked (proposed).
  3. 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.
  4. 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 sets memory_restore_budget and knowledge_restore_budget, inherited down the team tree. 0 turns a layer off. A card that says Run without project memory, or has the no-project-memory label, gets none.
  5. Rendering: the prompt carries an index, one line per entry (<id> · <kind> · <title> — <why>), and the bodies go to <runDir>/context/project-memory.md and project-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.
  6. The event: the run’s launched event records what went in, and a memory_given event 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 (findSecret in packages/shared/src/andon-dir/write.ts): the check:personal patterns 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’s confirmed_at moves) 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 to knowledge.

The writers:

  • A run has remember (writes memory/<kind>/<ULID>-<slug>.md as proposed, at most 5 a run) and knowledge (rewrites knowledge/<topic>.md in place). Both are committed with the run’s work, so the pull request carries them.
  • A review round reports memory[] in review_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_proposals row; bulk Accept and Reject insert theirs already queued, 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 on andon-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 and openCompactionPr (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 in history, 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 its confirmed_at as if half the decay window ago.
  • Contradictions: review_result takes memory_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