Agents Remember is built around a small set of concepts. The names matter because agents use them to decide what to read, what to trust, and what they are allowed to change.
An onboarding unit is durable repository knowledge that an agent can retrieve deterministically.
In the default repo-local mode, a source file maps to a mirrored Markdown file:
src/foo/bar.ts
ar-memory/onboarding/src/foo/bar.ts.md
The onboarding unit should explain what the code does not make obvious: invariants, intent, boundaries, conventions, cross-repo edges, and risky assumptions. It should not duplicate code, type signatures, or obvious implementation details.
The memory root is where durable memory for one code repository lives.
Internal memory:
<repo>/ar-memory/
External memory:
<ar-coordination>/memory-repos/ar-<repo>/
Internal memory is the default. External memory is for teams that intentionally want memory in a separate repository.
The coordination root is the installed runtime and local work area:
ar-coordination/
It owns installed skills, installed AGENTS.md templates, task files, notes, worktrees, temporary drift reports, and external memory repo checkouts.
Agents reach memory through three substrates, matched to what they already know.
src/foo/bar.ts → ar-memory/onboarding/src/foo/bar.ts.md. No lookup, ranking, or index step — the path is the address. Reads stay predictable, and unrelated-but-similar material stays out of context.code → onboarding: a vague description leads to an onboarding note, whose path then names the code file, with pointers to the surrounding logic.By-path notes are the core and need nothing extra; meaning and relationship are opt-in providers. The router that chooses among them is described next (it names the three Intent, Semantics, and Relationship). Whatever the route, what becomes durable memory is still drift-checked and approval-gated — finding is not the same as trusting.
File-level onboarding remains path-derived and verifiable, but agents often need
different retrieval strategies before they know which file-level memory to read.
The c-04-retrieval-strategy-router skill is the retrieval strategy router for that job.
The router starts from the model’s current intent: what kind of missing context does the agent need next, and in what shape should that context arrive? It then chooses the memory substrate that best fits that intent.
Semantics: use when the concept is known, but the structure or location is
unknown. A semantic memory provider can search memory repos for candidate
routes or files.Relationship: use when an anchor is known, but the surrounding
relationships, impact paths, callers, callees, or dependencies are unknown. A
relationship provider can search code structure for candidate connections.Intent: use when an anchor or location is known, but the hidden contracts,
invariants, behavioral expectations, branch-valid truths, or code intent are
unknown. Onboarding plus bounded source confirmation is the default substrate
for this layer.These substrates are complementary. A triage task may start from anchors in a ticket, use the Relationship substrate to understand nearby structure, then move to the Intent substrate to learn the code truths that make a change safe.
Provider output is candidate routing evidence, not proof. Source files, verified onboarding, drift checks, branch validity, and approved memory promotion remain the truth controls.
Each file-level sidecar onboarding unit records verification metadata, including the source commit it was checked against. Before planning against onboarding, c-02-memory-quality-control compares the source file with that verification point.
Common outcomes:
up to date: no source diff since verificationdrifted: source changed and onboarding needs reviewmissing verification: the onboarding unit lacks enough metadata to trustorphaned: the source file no longer existsunsupported: the storage or file shape cannot be verified safelyStale onboarding can still be read directionally when that trust level is explicit, but it should not silently become current truth.
Onboarding records approved current state. It does not record speculation.
That means:
w-02-light-task-workflow tasks wait for task approval before implementationThe root onboarding overview gives repo-level orientation. Larger repositories can also use route-local overviews in the mirrored onboarding hierarchy when a package, module, or source slice needs its own durable context.
File-level onboarding remains one-to-one with source files. Route-local overviews add structure; they do not replace file-specific onboarding when file-specific facts matter.
External memory repos use memory.md as a ledger that maps code commits to memory commits. This lets a branch carry the memory version that matches its code state.
The ledger matters for worktree-backed tasks and external-memory closeout because code and memory may move together but still live in separate repositories.