memory-sync

name	memory-sync
description	Use when a repo should keep a single memory file in sync with generated AGENTS.md and a thin CLAUDE.md wrapper, or when memory drift needs to be checked or repaired. Triggers: "memory-sync", "sync memory", "AGENTS.md drift", "CLAUDE.md drift"

Memory Sync

Use a single canonical Markdown memory file and generate host-facing files from it.

Default pattern:

• Canonical source: memory/project.md
• Codex file: AGENTS.md contains the shared memory content
• Claude Code file: CLAUDE.md is a thin wrapper that imports @AGENTS.md
• Optional Claude-only overlay: memory/claude.md

This avoids maintaining two different memory bodies by hand.

When to Use

• The user wants one shared project memory for Codex and Claude Code
• AGENTS.md and CLAUDE.md have drifted
• A repo currently uses manual dual-write memory and should move to one source
• The user wants a reusable memory-sync workflow or helper script

Workflow

1. Pick or confirm the target repo.
2. Initialize the memory layout if it does not exist.
3. Sync the generated files.
4. Run the drift check.
5. Report the canonical file and the generated outputs.

Commands

From the skill directory:

python scripts/memory_sync.py init --repo /path/to/repo
python scripts/memory_sync.py sync --repo /path/to/repo
python scripts/memory_sync.py check --repo /path/to/repo

Output Pattern

AGENTS.md:

• generated from memory/project.md
• contains the shared memory directly

CLAUDE.md:

• generated wrapper
• imports @AGENTS.md
• appends memory/claude.md if present

Rules

• Keep the canonical memory in Markdown, not YAML.
• Do not hand-edit generated AGENTS.md or CLAUDE.md; edit memory/project.md instead.
• Keep CLAUDE.md thin unless there is a real Claude-specific need.
• If the repo already has important CLAUDE.md content, move only the shared part into memory/project.md and preserve the Claude-only remainder as memory/claude.md.

Validation

After any change, run:

python scripts/memory_sync.py check --repo /path/to/repo

Success means the generated files match the canonical source.

Anti-Patterns

Anti-Pattern	What goes wrong	Fix
Editing generated AGENTS.md directly	Drift between canonical and host file; next sync reverts your edits	Always edit memory/project.md instead
Stuffing Claude-only content into memory/project.md	Codex picks up Claude-only behavior and gets confused	Put Claude-only notes in memory/claude.md overlay
Skipping check before committing	Drift slips into git; future agents read stale memory	Run python scripts/memory_sync.py check --repo . as a pre-commit gate
Inlining the full memory body into CLAUDE.md instead of @AGENTS.md import	Two copies drift; one host gets stale	Keep CLAUDE.md as a thin @AGENTS.md wrapper
Storing memory as YAML or JSON	Harder to skim, breaks host conventions that expect Markdown	Markdown only
Hand-editing both files "to keep them in sync"	Defeats the point — the script is the source of truth	Edit canonical, then run sync

See Also

• project-mem-init — Bootstrap project memory files from scratch (complementary to sync)
• meta-init — Install tao-research-skills globally across platforms
• agents-md-writing — Patterns for writing effective CLAUDE.md/AGENTS.md