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

A June 2026 research survey of six coding agents—Codex CLI, Kimi Code CLI, MiMo Code, Cursor, Antigravity CLI, and OpenCode—found that while all support a project-level AGENTS.md file, global instructions are fragmented: each tool reads a different global path, and Kimi Code CLI and Cursor's CLI have no global instructions file at all. In-file @-imports only work in Claude Code, breaking cross-file references in other tools. The recommended fix is a flatten-and-fan-out sync script that resolves references into a single file and symlinks it to each tool's global path.

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.