# Unifying AGENTS.md / CLAUDE.md long-term-memory instruction files across coding agents (Codex, Kimi Code, MiMo Code, Cursor, Antigravity CLI, OpenCode) — research, June 2026

> Source: <https://gist.github.com/Shoora/03b3f5e82e7c8c713b3a4e21a1708432>
> Published: 2026-06-24 03:31:49+00:00

**Research date:** 23 June 2026 · **Scope:** Codex CLI, Kimi Code CLI, MiMo Code, Cursor (`cursor-agent`

), Antigravity CLI (`agy`

), OpenCode. Claude Code excluded (already known). Multi-agent cited research.

**Project-level** Every tool here reads an`AGENTS.md`

is effectively universal.`AGENTS.md`

at the repo root. Your existing`AGENTS.md → CLAUDE.md`

symlink per project already works for all of them.**Global instructions are the messy part**— each tool reads a*different*global path, and**two of the tools have no global instructions file at all.****Kimi's specific issue is now explained:** Kimi has**no global instructions file whatsoever**— it only scans the*project*tree for`AGENTS.md`

. A global`~/.claude/CLAUDE.md`

(or`~/.kimi/AGENTS.md`

) is simply never read. That's why "Kimi doesn't use agents.md."**In-file**(and partly MiMo). Codex, Kimi, Cursor's AGENTS.md, OpenCode, and Antigravity all treat`@`

-references only resolve in Claude Code`@path`

as plain text — so your CLAUDE.md's references to other`~/.claude/`

files silently break in every non-Claude tool.**Two free wins:****OpenCode and MiMo Code both fall back to** for global instructions if they don't find their own — so they already read your global file for free.`~/.claude/CLAUDE.md`

**Cursor's CLI also reads a project**`CLAUDE.md`

.**Recommended fix:** a tiny**"flatten + fan-out" sync script**— resolve the references into ONE self-contained file, then symlink it to each tool's global path. This solves both the filename/location differences*and*the cross-file-reference problem in one shot.

| Agent | Global instructions file | Project instructions file(s) | Reads project `AGENTS.md` ? |
Falls back to `~/.claude/CLAUDE.md` ? |
Resolves in-file `@` -imports? |
Native "load multiple files" mechanism |
|---|---|---|---|---|---|---|
Claude Code (ref) |
`~/.claude/CLAUDE.md` |
`CLAUDE.md` (+ `AGENTS.md` ) |
Yes | — | Yes (`@path` ) |
`@` -imports |
Codex CLI |
`~/.codex/AGENTS.md` (or `AGENTS.override.md` ) |
`AGENTS.md` (root → cwd, concatenated) |
Yes (native standard) |
No | No |
`project_doc_fallback_filenames` in `~/.codex/config.toml` |
Kimi Code CLI |
None (only `~/.kimi/config.toml` , which has no instructions key) |
`AGENTS.md` / `.kimi/AGENTS.md` / `agents.md` (root → cwd) |
Yes — project only |
No | No |
None (plain concat, 32 KiB cap) |
MiMo Code |
`~/.config/mimocode/AGENTS.md` |
`AGENTS.md` (+ `CLAUDE.md` fallback) |
Yes (primary) |
Yes (global + project) |
Yes (`@filename` lazy import) |
`instructions[]` in `mimocode.json` (paths, globs, URLs) |
Cursor (`cursor-agent` CLI) |
None for CLI (User Rules are GUI-only, not on disk) |
`AGENTS.md` , `.cursor/rules/*.mdc` , `.cursorrules` |
Yes (CLI reads `AGENTS.md` and `CLAUDE.md` ) |
CLI reads project `CLAUDE.md` |
No in `AGENTS.md` ; `@file` in `.mdc` pulls source-file context only |
`.cursor/rules/*.mdc` (glob-scoped rules) |
Antigravity CLI (`agy` ) |
`~/.gemini/GEMINI.md` |
`AGENTS.md` and `GEMINI.md` (both read) |
Yes |
No | No (`@` works at prompt-time only) |
None in-file |
OpenCode |
`~/.config/opencode/AGENTS.md` |
`AGENTS.md` (+ `CLAUDE.md` fallback) |
Yes (primary) |
Yes (global + project) |
No |
`instructions[]` in `opencode.json` (paths, globs, URLs) |

Sources per row are in the per-tool sections below.

**Global:**`~/.codex/AGENTS.md`

.`AGENTS.override.md`

at the same level*replaces*it.`$CODEX_HOME`

overrides the dir. ([OpenAI Codex docs, 2026](https://developers.openai.com/codex/guides/agents-md))**Project:**`AGENTS.md`

at the git root and one per subdirectory down to cwd; all**concatenated**(closer to cwd = later = higher effective priority). 32 KiB cap; one file per directory level. ([OpenAI Codex docs](https://developers.openai.com/codex/guides/agents-md))**Custom filenames:** add names via`project_doc_fallback_filenames`

in`~/.codex/config.toml`

. ([same](https://developers.openai.com/codex/guides/agents-md))— treated as plain text. Open, unmerged feature requests:`@`

-imports: NOT supported[#17401](https://github.com/openai/codex/issues/17401),`@include`

directive[#3413 file-content inclusion](https://github.com/openai/codex/issues/3413).

**Global instructions: NONE.**`~/.kimi/config.toml`

is the only global config and has**no**`system_prompt`

/`instructions_file`

/`agents_md`

key. The loader (`load_agents_md()`

in`src/kimi_cli/soul/agent.py`

)**only searches the project hierarchy**(root → cwd) — it never reads`~/.kimi/`

or`~/.claude/`

for an instructions file. ([Kimi config docs](https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html),[soul/agent.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py))**Project:**`.kimi/AGENTS.md`

,`AGENTS.md`

, or lowercase`agents.md`

(uppercase wins) at root or any ancestor up to cwd; concatenated and injected via the`${KIMI_AGENTS_MD}`

template variable. ([kimi-cli AGENTS.md](https://raw.githubusercontent.com/MoonshotAI/kimi-cli/main/AGENTS.md))**Why "Kimi ignores agents.md":** almost always because (1) the file is placed at a**global path**(`~/.kimi/`

or`~/.claude/`

) — Kimi only reads it*inside the project tree*; (2) Kimi was launched from a cwd outside the project; (3) a custom`--agent-file`

whose system prompt omits`${KIMI_AGENTS_MD}`

; or (4) the file is empty after`.strip()`

.**Global SKILLS are shared though:** Kimi*does*scan`~/.kimi/skills/`

**and** globally — but skills ≠ instructions. (`~/.claude/skills/`

[Kimi skills docs](https://moonshotai.github.io/kimi-cli/en/customization/skills.html))in`@`

-imports: NOT supported`AGENTS.md`

(plain-text concat).

**Global:**`~/.config/mimocode/AGENTS.md`

(+`~/.config/mimocode/mimocode.json`

). ([MiMo Code config docs](https://mimo.xiaomi.com/mimocode/config-files))**Project:**`AGENTS.md`

at root, falling back to`CLAUDE.md`

. Precedence: local`AGENTS.md`

> local`CLAUDE.md`

> global`AGENTS.md`

> global`CLAUDE.md`

,**all merged**. ([MiMo Code rules docs](https://mimo.xiaomi.com/mimocode/rules))** Multi-file / references:**`instructions[]`

in`mimocode.json`

accepts**paths, globs, and remote URLs**;`@filename`

inside`AGENTS.md`

lazy-imports;`{file:path}`

inlines content. ([config docs](https://mimo.xiaomi.com/mimocode/config-files))- Adopts AGENTS.md as primary; ships a
`CLAUDE.md`

fallback. ([repo](https://github.com/XiaomiMiMo/MiMo-Code))

**Global/User Rules: GUI-only**, stored in app settings —** not a file on disk**, and the`cursor-agent`

CLI does**not** read them. Confirmed gap. ([Cursor Rules docs](https://cursor.com/docs/rules),[forum: global rules with cursor CLI](https://forum.cursor.com/t/global-rules-with-cursor-cli/132240))**Project:**`.cursor/rules/*.mdc`

(frontmatter + globs + activation modes),`AGENTS.md`

(plain markdown, read by**both** IDE and CLI), legacy`.cursorrules`

. The CLI explicitly reads`AGENTS.md`

**and**`CLAUDE.md`

at project root. ([Cursor CLI docs](https://cursor.com/docs/cli/using))`@`

-imports:`AGENTS.md`

has none;`@filename`

inside`.mdc`

pulls*source-file*context, not rule composition. ([Cursor Rules docs](https://cursor.com/docs/rules))

**Global:**`~/.gemini/GEMINI.md`

(auto-loaded across all workspaces). Global skills:`~/.gemini/antigravity-cli/skills/`

. Main config:`~/.config/antigravity/config.toml`

. No global`AGENTS.md`

confirmed. ([Antigravity deep-dive](https://agentpedia.codes/blog/antigravity-cli-deep-dive),[hands-on guide](https://dev.to/arindam_1729/antigravity-cli-a-hands-on-guide-to-googles-terminal-coding-agent-5bc7))**Project:** reads**both**`AGENTS.md`

and`GEMINI.md`

at root (no rename needed;`AGENTS.md`

is the new convention). Project skills:`.agents/skills/`

. ([AI Builder Club guide](https://www.aibuilderclub.com/blog/antigravity-cli-guide))No data found —`@`

-imports inside instruction files:`@`

works at prompt-time only. Use`agy inspect`

to see exactly which files were loaded.

**Global:**`~/.config/opencode/AGENTS.md`

,**falling back to** if absent (disable via`~/.claude/CLAUDE.md`

`OPENCODE_DISABLE_CLAUDE_CODE`

). Global config:`~/.config/opencode/opencode.json`

. ([OpenCode Rules docs](https://opencode.ai/docs/rules/))**Project:**`AGENTS.md`

at root, falling back to`CLAUDE.md`

(if both exist, only`AGENTS.md`

is used). ([OpenCode Rules docs](https://opencode.ai/docs/rules/))**Multi-file / references — the key feature:**`instructions[]`

in`opencode.json`

accepts**file paths, globs, and remote URLs**, additively merged (concat + dedup across global/project). In-file`@`

-imports are**NOT** parsed — use this array instead. ([OpenCode config docs](https://opencode.ai/docs/config/),[DeepWiki](https://deepwiki.com/sst/opencode/3-configuration-system))

| Tool | Where its GLOBAL instructions must live |
|---|---|
| Claude Code | `~/.claude/CLAUDE.md` (your source of truth) |
| OpenCode | auto-reads `~/.claude/CLAUDE.md` ✅ free |
| MiMo Code | auto-reads `~/.claude/CLAUDE.md` ✅ free |
| Codex CLI | `~/.codex/AGENTS.md` — needs a symlink |
| Antigravity | `~/.gemini/GEMINI.md` — needs a symlink |
| Kimi CLI | no global option — project `AGENTS.md` only |
| Cursor CLI | no global option — project `AGENTS.md` only |

Your `CLAUDE.md`

points to other `~/.claude/`

files. Only Claude Code resolves those; every other tool reads them as dead text. So even where the global file *is* picked up (OpenCode, MiMo via fallback), the referenced content is missing.

One canonical source, flattened into one self-contained file, fanned out to each tool's expected path. This fixes **both** problems with no per-tool divergence.

``` bash
#!/usr/bin/env bash
# ~/.claude/sync-agent-config.sh  — run on change (hook/cron) or manually
set -euo pipefail

SRC="$HOME/.claude/CLAUDE.md"
FLAT="$HOME/.claude/AGENTS.flat.md"   # self-contained, references inlined

# 1) FLATTEN: inline @-references / linked files into one file.
#    (Claude Code resolves @-imports itself, so it keeps using CLAUDE.md.
#     Everyone else gets the flattened, self-contained version.)
#    Implement the resolver to match how YOUR CLAUDE.md references files —
#    e.g. expand lines like `@~/.claude/refs/foo.md` or `@refs/foo.md`:
python3 - "$SRC" "$FLAT" <<'PY'
import re, sys, pathlib
src, out = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])
base = src.parent
seen = set()
def expand(p: pathlib.Path) -> str:
    p = p.expanduser().resolve()
    if p in seen or not p.exists():           # avoid cycles / missing
        return f"<!-- missing or cyclic: {p} -->"
    seen.add(p)
    lines = []
    for line in p.read_text().splitlines():
        m = re.match(r'^\s*@([~./\w\-/]+\.md)\s*$', line)   # a bare @path import on its own line
        if m:
            ref = (base / m.group(1)).expanduser() if not m.group(1).startswith(('/','~')) else pathlib.Path(m.group(1))
            lines.append(f"\n<!-- inlined from {m.group(1)} -->\n" + expand(ref))
        else:
            lines.append(line)
    return "\n".join(lines)
out.write_text(expand(src))
print(f"flattened -> {out}")
PY

# 2) FAN-OUT: symlink the flattened file to each tool's GLOBAL path.
mkdir -p ~/.codex ~/.gemini ~/.config/opencode ~/.config/mimocode
ln -sf "$FLAT" ~/.codex/AGENTS.md            # Codex
ln -sf "$FLAT" ~/.gemini/GEMINI.md           # Antigravity
ln -sf "$FLAT" ~/.config/opencode/AGENTS.md  # OpenCode (overrides the CLAUDE.md fallback w/ the flattened one)
ln -sf "$FLAT" ~/.config/mimocode/AGENTS.md  # MiMo  (same)

# 3) PROJECT level (covers Kimi + Cursor CLI, which have NO global option):
#    symlink AGENTS.md -> the flattened file in each repo you use.
#    (You already symlink AGENTS.md -> CLAUDE.md; point it at $FLAT instead
#     so the references resolve for non-Claude agents too.)
#    e.g.:  ln -sf "$FLAT" /path/to/repo/AGENTS.md
echo "done."
```

**Trigger it automatically** so it stays in sync — you already run a `config_sync`

tmux session and a `sync-claude-config`

skill; add this script there, or wire a Claude Code `Stop`

/`PostToolUse`

hook that re-runs it when `~/.claude/CLAUDE.md`

(or a referenced file) changes.

| Approach | Pros | Cons | Best for |
|---|---|---|---|
Flatten + fan-out (above) |
One source of truth; references actually resolve everywhere; one self-contained file | Need a small flattener; must re-run on change | Recommended — universal, handles both problems |
Plain symlink (no flatten)`AGENTS.md → CLAUDE.md` |
Zero scripting; you already do it | `@` -references stay broken in non-Claude tools; no help for Kimi/Cursor global |
Tools where the file is already self-contained |
Per-tool (OpenCode, MiMo only)`instructions[]` arrays |
No flattening; explicit, glob/URL support; native | Only OpenCode + MiMo have it; doesn't help Codex/Kimi/Cursor/Antigravity | OpenCode/MiMo if you prefer config over symlinks |
(Codex)`project_doc_fallback_filenames` |
Lets Codex pick up a shared custom filename anywhere | Codex-only; still no reference resolution | Registering a shared filename for Codex |
Make (drop the references)`CLAUDE.md` itself self-contained |
Simplest mental model; every tool gets the full content | Loses modularity; bigger single file; 32 KiB caps (Codex/Kimi) bite | Small/medium instruction sets |

Watch the

32 KiB capon Codex and Kimi when flattening — keep the combined file under it, or split content so the per-project`AGENTS.md`

carries only what each repo needs.

**"Where does Kimi look?"** Project tree only —`AGENTS.md`

/`.kimi/AGENTS.md`

/`agents.md`

from repo root down to cwd.**No global instructions file exists**(only`~/.kimi/config.toml`

, which can't point to one). A global`~/.claude/CLAUDE.md`

is never read by Kimi. Fix: put the (flattened)`AGENTS.md`

in each repo. (Global*skills*in`~/.kimi/skills/`

and`~/.claude/skills/`

*are*read.)**"Why isn't my symlink perfect?"** Because (a) the referenced files aren't resolved by non-Claude tools (only Claude Code does`@`

-imports), and (b) two tools (Kimi, Cursor CLI) have no global slot at all. Flattening + per-project symlinks fixes both.**"Free wins?"** OpenCode and MiMo already fall back to`~/.claude/CLAUDE.md`

globally; Cursor's CLI reads a project`CLAUDE.md`

. So those need the least work.

- OpenAI Codex —
[AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)·[issue #17401](https://github.com/openai/codex/issues/17401)·[issue #3413](https://github.com/openai/codex/issues/3413) - Kimi CLI —
[config files](https://moonshotai.github.io/kimi-cli/en/configuration/config-files.html)·[soul/agent.py](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py)·[AGENTS.md](https://raw.githubusercontent.com/MoonshotAI/kimi-cli/main/AGENTS.md)·[skills](https://moonshotai.github.io/kimi-cli/en/customization/skills.html) - MiMo Code —
[repo](https://github.com/XiaomiMiMo/MiMo-Code)·[config files](https://mimo.xiaomi.com/mimocode/config-files)·[rules](https://mimo.xiaomi.com/mimocode/rules) - Cursor —
[Rules](https://cursor.com/docs/rules)·[CLI](https://cursor.com/docs/cli/using)·[forum: global rules w/ CLI](https://forum.cursor.com/t/global-rules-with-cursor-cli/132240) - Antigravity —
[deep-dive](https://agentpedia.codes/blog/antigravity-cli-deep-dive)·[hands-on guide](https://dev.to/arindam_1729/antigravity-cli-a-hands-on-guide-to-googles-terminal-coding-agent-5bc7)·[Gemini CLI → Antigravity transition](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/) - OpenCode —
[Rules](https://opencode.ai/docs/rules/)·[Config](https://opencode.ai/docs/config/)·[DeepWiki config system](https://deepwiki.com/sst/opencode/3-configuration-system) - AGENTS.md open standard —
[agents.md](https://agents.md/)

*Compiled by SonPH's WC Coordinator agent via 6 parallel research sub-agents, 23 Jun 2026.*