memory-sync
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"
Best use case
memory-sync is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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"
Teams using memory-sync should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/memory-sync/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How memory-sync Compares
| Feature / Agent | memory-sync | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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"
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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: ```bash 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: ```bash 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