agents-remember

Use External Memory

Most repositories should start with internal memory under <repo>/ar-memory/. Use external memory when you intentionally want durable memory in a separate repository.

When External Memory Helps

External memory is useful when:

• code and memory should be reviewed or permissioned separately
• several code repositories share one coordination root
• long-running branches need matching code and memory versions
• c-12-closeout worktree closeout should record code-memory ledger mappings

Layout

projects/
  agents-remember/
  ar-coordination/
    AGENTS.md
    skills/
    memory-repos/
      ar-my-app/
        memory.md
        onboarding/
        docs/
        system/
  my-app/

Each selected code repository gets one memory repo:

ar-coordination/memory-repos/ar-<repo-name>/

Initialize

Install the runtime first through the MCP server:

runtime_install()

Then ask the agent to run c-00-initialize-memory-repo in external-memory mode for the target repository. External mode should be explicit; the c-00-initialize-memory-repo skill defaults to internal memory.

Configure

External memory uses memory-repo storage:

{
  "version": 2,
  "onboarding": {
    "storage": {
      "mode": "memory-repo"
    },
    "pathRules": {
      "include": {
        "paths": ["README.md", "docs/**", "src/**"],
        "fileTypes": [".md", ".py", ".ts", ".tsx"]
      },
      "exclude": {
        "paths": ["node_modules/**", "vendor/**", "dist/**", "build/**", ".env", ".env.*"],
        "fileTypes": [".png", ".zip"]
      }
    }
  },
  "crossRepo": {
    "allow": []
  }
}

In a one-repo memory repo, unscoped path rules are fine. In shared coordinator settings, scope rules by repository path when one settings file covers more than one repo.

Resolve

The c-08-ar-coordination-context-resolver skill checks internal memory first, then external memory:

<repo>/ar-memory/
<ar-coordination>/memory-repos/ar-<repo>/

An external memory repo does not force sibling repositories into external mode. Resolution is per target repository.

Closeout

External-memory changes need code and memory to stay mapped. c-12-closeout handles that sequence for both direct edits in the current checkout and worktree-backed tasks:

1. commit code
2. refresh onboarding metadata against the code commit
3. commit memory content
4. update memory.md

Do not manually update the ledger unless you are deliberately repairing memory history.

This site is open source. Improve this page.