# 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](https://andon-docs.pages.dev/guide/memory.md)); the file format of `.andon/` is in [the reference](https://andon-docs.pages.dev/reference/andon-directory.md).

| 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](https://github.com/psci-labs/andon/blob/main/docs/internal/settings-audit.md)).

## 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` |
