Skip to content

architecture.md

Latest commit

 

History

History
104 lines (73 loc) · 2.62 KB

architecture.md

File metadata and controls

104 lines (73 loc) · 2.62 KB

Architecture

Agents Remember separates four surfaces that are easy to confuse:

  • the agents-remember-md source checkout
  • the installed ar-coordination runtime
  • a target code repository
  • the target repository's memory root

Source Checkout

agents-remember-md/
  installer/
  runtime/
  docs/
  roadmap/

The source checkout packages the runtime assets and public documentation. Agents working on this repository itself follow the root AGENTS.md in the checkout. Users of the runtime normally point their agent at the installed ar-coordination/AGENTS.md.

Installed Runtime

ar-coordination/
  AGENTS.md
  scripts/
  skills/
  system/
  memory-repos/
  tasks/
  notes/
  worktrees/
  temp/

The installer copies package-owned assets from runtime/ into this tree. Installed skills default to this runtime as their coordination root, so normal users do not need to set AR_COORDINATION_ROOT.

Target Code Repository

This is the repository the agent is actually changing. It may contain internal memory:

my-app/
  src/
  ar-memory/

When internal memory exists, C-08 resolves it before checking for external memory.

Internal Memory

Internal memory is the default. Durable memory lives inside the code repository:

my-app/ar-memory/
  onboarding/
  docs/
  system/
    settings.md
    settings.json
    sources.md
    tools.md

C-00 creates this scaffold. C-03 bootstraps onboarding content. C-05 maintains file-level onboarding and repo entity catalogs.

External Memory

External memory stores durable memory in one repo per selected code repository:

ar-coordination/memory-repos/ar-my-app/
  memory.md
  onboarding/
  docs/
  system/

Use external memory when teams need a separate memory repository, branch-specific memory movement, or memory review outside the code repository.

Resolution Order

C-08 resolves a target repository by checking:

  1. explicit inputs such as code_repository_root, coordination_root, or task contract
  2. repo-local internal memory at <repo>/ar-memory/
  3. external memory at <coordination-root>/memory-repos/ar-<repo>/

If neither supported memory location exists, C-08 fails and asks the caller to initialize memory instead of inventing an empty context.

Ownership Boundaries

Runtime install owns package assets under ar-coordination.

C-00 owns memory-root creation or repair.

C-03 owns repo onboarding bootstrap and route/slice maintenance.

C-05 owns file-level onboarding and repo entity catalog maintenance.

C-08 owns context resolution facts only.

C-09 owns worktree lifecycle, direct closeout, and approved commit sequencing.