Memory

Your canonical memory lives in memory/AGENTS.md and renders to each agent’s native memory file — CLAUDE.md for Claude, AGENTS.md for OpenCode.

Compose from fragments

Keep the top-level file small and pull in reusable pieces with @import:

~/.agentsync/memory/AGENTS.md

# Coding conventions

@import ./fragments/style.md
@import ./fragments/security-rules.md

layout

~/.agentsync/memory/
├── AGENTS.md
└── fragments/
    ├── style.md
    └── security-rules.md

…where each fragment holds a focused piece:

~/.agentsync/memory/fragments/style.md

Prefer clarity over cleverness.

~/.agentsync/memory/fragments/security-rules.md

Never log secrets.

At apply time agentsync expands the imports and writes the fully-composed memory into each agent’s native file, wrapping each fragment in HTML-comment boundary markers (so the expansion can be reversed — see below):

~/.claude/CLAUDE.md (rendered by apply)

# Coding conventions

<!-- agentsync:fragment style.md -->
Prefer clarity over cleverness.
<!-- /agentsync:fragment style.md -->
<!-- agentsync:fragment security-rules.md -->
Never log secrets.
<!-- /agentsync:fragment security-rules.md -->

Edit a fragment once and every agent’s memory updates on the next apply.

Fragments are reusable

A fragment like security-rules.md can be imported by several memory files (for example a user-level memory and a project overlay). Define the rule once, use it everywhere.

Fragments round-trip both ways

On apply, agentsync wraps each inlined fragment in HTML-comment boundary markers in the native file (<!-- agentsync:fragment style.md --> … <!-- /agentsync:fragment style.md -->). They read as metadata, not instructions, and let import/reconcile reverse the expansion: a native memory edit made inside a fragment block is captured back into that fragment file, with the @import structure preserved — never flattened into AGENTS.md. If the markers are absent (a fragment whose text contains the marker token disables them) or were hand-mangled into an unbalanced/ambiguous state, agentsync refuses the write-back rather than guess; the drift still shows in status/diff and you fold it in by hand.

The managed-file banner

Every rendered memory file is prepended with a short agentsync notice — a blockquote naming the file and pointing edits back at the canonical source:

~/.claude/CLAUDE.md (rendered by apply)

<!-- agentsync:managed memory-banner -->
> **Managed by [agentsync](https://agentsync.cc) — do not edit `CLAUDE.md` directly.**
> To change it, edit `.agentsync/memory/AGENTS.md` (or the relevant
> `.agentsync/memory/fragments/*.md` fragment) and run `agentsync apply`.
> Direct edits here are reported as drift and overwritten on the next apply.
<!-- /agentsync:managed memory-banner -->

# Coding conventions
…

It nudges an agent (or a teammate) editing the native file toward the canonical source instead.

The banner never enters your canonical source

The banner is written by agentsync, not stored in memory/AGENTS.md. It is wrapped in <!-- agentsync:managed memory-banner --> markers, stripped on import/reconcile (and on ingest), and re-rendered on every apply — so it never compounds, and because the text is static it never shows up as drift. It is on by default; opt out with [memory] banner = false in agentsync.toml (see the configuration reference). The first apply after upgrading adds the banner to existing memory files — a one-time pending.

`agentsync:managed` is a reserved marker

If your memory/AGENTS.md or a fragment contains the literal agentsync:managed marker, agentsync errors and asks you to remove it, so it can’t collide with the banner. Capture is conservative in the other direction too: it strips only agentsync’s own banner, so any other content you keep is never deleted.

Per-agent rendering

Agent	Native memory file
Claude Code	~/.claude/CLAUDE.md
OpenCode	~/.config/opencode/AGENTS.md
Codex	~/.codex/AGENTS.md
Cursor	AGENTS.md (project root)
Gemini CLI	~/.gemini/GEMINI.md (user) · GEMINI.md (project root)

Memory is ✓ native on Claude, OpenCode, Codex, and Gemini CLI — the same markdown, full fidelity (~/.codex/AGENTS.md for Codex, ~/.gemini/GEMINI.md for Gemini). Cursor keeps user-level rules in app-local storage, so memory projects to a project-root AGENTS.md only (◐). See the capability matrix for detail.

Project-local memory A repo's .agentsync/ project tree carries its own memory/AGENTS.md, appended after your user-level memory on apply.