{"slug": "unifying-agents-md-claude-md-long-term-memory-instruction-files-across-coding", "title": "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", "summary": "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.", "body_md": "**Research date:** 23 June 2026 · **Scope:** Codex CLI, Kimi Code CLI, MiMo Code, Cursor (`cursor-agent`\n\n), Antigravity CLI (`agy`\n\n), OpenCode. Claude Code excluded (already known). Multi-agent cited research.\n\n**Project-level** Every tool here reads an`AGENTS.md`\n\nis effectively universal.`AGENTS.md`\n\nat the repo root. Your existing`AGENTS.md → CLAUDE.md`\n\nsymlink 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`\n\n. A global`~/.claude/CLAUDE.md`\n\n(or`~/.kimi/AGENTS.md`\n\n) 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`@`\n\n-references only resolve in Claude Code`@path`\n\nas plain text — so your CLAUDE.md's references to other`~/.claude/`\n\nfiles 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`\n\n**Cursor's CLI also reads a project**`CLAUDE.md`\n\n.**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.\n\n| Agent | Global instructions file | Project instructions file(s) | Reads project `AGENTS.md` ? |\nFalls back to `~/.claude/CLAUDE.md` ? |\nResolves in-file `@` -imports? |\nNative \"load multiple files\" mechanism |\n|---|---|---|---|---|---|---|\nClaude Code (ref) |\n`~/.claude/CLAUDE.md` |\n`CLAUDE.md` (+ `AGENTS.md` ) |\nYes | — | Yes (`@path` ) |\n`@` -imports |\nCodex CLI |\n`~/.codex/AGENTS.md` (or `AGENTS.override.md` ) |\n`AGENTS.md` (root → cwd, concatenated) |\nYes (native standard) |\nNo | No |\n`project_doc_fallback_filenames` in `~/.codex/config.toml` |\nKimi Code CLI |\nNone (only `~/.kimi/config.toml` , which has no instructions key) |\n`AGENTS.md` / `.kimi/AGENTS.md` / `agents.md` (root → cwd) |\nYes — project only |\nNo | No |\nNone (plain concat, 32 KiB cap) |\nMiMo Code |\n`~/.config/mimocode/AGENTS.md` |\n`AGENTS.md` (+ `CLAUDE.md` fallback) |\nYes (primary) |\nYes (global + project) |\nYes (`@filename` lazy import) |\n`instructions[]` in `mimocode.json` (paths, globs, URLs) |\nCursor (`cursor-agent` CLI) |\nNone for CLI (User Rules are GUI-only, not on disk) |\n`AGENTS.md` , `.cursor/rules/*.mdc` , `.cursorrules` |\nYes (CLI reads `AGENTS.md` and `CLAUDE.md` ) |\nCLI reads project `CLAUDE.md` |\nNo in `AGENTS.md` ; `@file` in `.mdc` pulls source-file context only |\n`.cursor/rules/*.mdc` (glob-scoped rules) |\nAntigravity CLI (`agy` ) |\n`~/.gemini/GEMINI.md` |\n`AGENTS.md` and `GEMINI.md` (both read) |\nYes |\nNo | No (`@` works at prompt-time only) |\nNone in-file |\nOpenCode |\n`~/.config/opencode/AGENTS.md` |\n`AGENTS.md` (+ `CLAUDE.md` fallback) |\nYes (primary) |\nYes (global + project) |\nNo |\n`instructions[]` in `opencode.json` (paths, globs, URLs) |\n\nSources per row are in the per-tool sections below.\n\n**Global:**`~/.codex/AGENTS.md`\n\n.`AGENTS.override.md`\n\nat the same level*replaces*it.`$CODEX_HOME`\n\noverrides the dir. ([OpenAI Codex docs, 2026](https://developers.openai.com/codex/guides/agents-md))**Project:**`AGENTS.md`\n\nat 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`\n\nin`~/.codex/config.toml`\n\n. ([same](https://developers.openai.com/codex/guides/agents-md))— treated as plain text. Open, unmerged feature requests:`@`\n\n-imports: NOT supported[#17401](https://github.com/openai/codex/issues/17401),`@include`\n\ndirective[#3413 file-content inclusion](https://github.com/openai/codex/issues/3413).\n\n**Global instructions: NONE.**`~/.kimi/config.toml`\n\nis the only global config and has**no**`system_prompt`\n\n/`instructions_file`\n\n/`agents_md`\n\nkey. The loader (`load_agents_md()`\n\nin`src/kimi_cli/soul/agent.py`\n\n)**only searches the project hierarchy**(root → cwd) — it never reads`~/.kimi/`\n\nor`~/.claude/`\n\nfor 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`\n\n,`AGENTS.md`\n\n, or lowercase`agents.md`\n\n(uppercase wins) at root or any ancestor up to cwd; concatenated and injected via the`${KIMI_AGENTS_MD}`\n\ntemplate 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/`\n\nor`~/.claude/`\n\n) — Kimi only reads it*inside the project tree*; (2) Kimi was launched from a cwd outside the project; (3) a custom`--agent-file`\n\nwhose system prompt omits`${KIMI_AGENTS_MD}`\n\n; or (4) the file is empty after`.strip()`\n\n.**Global SKILLS are shared though:** Kimi*does*scan`~/.kimi/skills/`\n\n**and** globally — but skills ≠ instructions. (`~/.claude/skills/`\n\n[Kimi skills docs](https://moonshotai.github.io/kimi-cli/en/customization/skills.html))in`@`\n\n-imports: NOT supported`AGENTS.md`\n\n(plain-text concat).\n\n**Global:**`~/.config/mimocode/AGENTS.md`\n\n(+`~/.config/mimocode/mimocode.json`\n\n). ([MiMo Code config docs](https://mimo.xiaomi.com/mimocode/config-files))**Project:**`AGENTS.md`\n\nat root, falling back to`CLAUDE.md`\n\n. Precedence: local`AGENTS.md`\n\n> local`CLAUDE.md`\n\n> global`AGENTS.md`\n\n> global`CLAUDE.md`\n\n,**all merged**. ([MiMo Code rules docs](https://mimo.xiaomi.com/mimocode/rules))** Multi-file / references:**`instructions[]`\n\nin`mimocode.json`\n\naccepts**paths, globs, and remote URLs**;`@filename`\n\ninside`AGENTS.md`\n\nlazy-imports;`{file:path}`\n\ninlines content. ([config docs](https://mimo.xiaomi.com/mimocode/config-files))- Adopts AGENTS.md as primary; ships a\n`CLAUDE.md`\n\nfallback. ([repo](https://github.com/XiaomiMiMo/MiMo-Code))\n\n**Global/User Rules: GUI-only**, stored in app settings —** not a file on disk**, and the`cursor-agent`\n\nCLI 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`\n\n(frontmatter + globs + activation modes),`AGENTS.md`\n\n(plain markdown, read by**both** IDE and CLI), legacy`.cursorrules`\n\n. The CLI explicitly reads`AGENTS.md`\n\n**and**`CLAUDE.md`\n\nat project root. ([Cursor CLI docs](https://cursor.com/docs/cli/using))`@`\n\n-imports:`AGENTS.md`\n\nhas none;`@filename`\n\ninside`.mdc`\n\npulls*source-file*context, not rule composition. ([Cursor Rules docs](https://cursor.com/docs/rules))\n\n**Global:**`~/.gemini/GEMINI.md`\n\n(auto-loaded across all workspaces). Global skills:`~/.gemini/antigravity-cli/skills/`\n\n. Main config:`~/.config/antigravity/config.toml`\n\n. No global`AGENTS.md`\n\nconfirmed. ([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`\n\nand`GEMINI.md`\n\nat root (no rename needed;`AGENTS.md`\n\nis the new convention). Project skills:`.agents/skills/`\n\n. ([AI Builder Club guide](https://www.aibuilderclub.com/blog/antigravity-cli-guide))No data found —`@`\n\n-imports inside instruction files:`@`\n\nworks at prompt-time only. Use`agy inspect`\n\nto see exactly which files were loaded.\n\n**Global:**`~/.config/opencode/AGENTS.md`\n\n,**falling back to** if absent (disable via`~/.claude/CLAUDE.md`\n\n`OPENCODE_DISABLE_CLAUDE_CODE`\n\n). Global config:`~/.config/opencode/opencode.json`\n\n. ([OpenCode Rules docs](https://opencode.ai/docs/rules/))**Project:**`AGENTS.md`\n\nat root, falling back to`CLAUDE.md`\n\n(if both exist, only`AGENTS.md`\n\nis used). ([OpenCode Rules docs](https://opencode.ai/docs/rules/))**Multi-file / references — the key feature:**`instructions[]`\n\nin`opencode.json`\n\naccepts**file paths, globs, and remote URLs**, additively merged (concat + dedup across global/project). In-file`@`\n\n-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))\n\n| Tool | Where its GLOBAL instructions must live |\n|---|---|\n| Claude Code | `~/.claude/CLAUDE.md` (your source of truth) |\n| OpenCode | auto-reads `~/.claude/CLAUDE.md` ✅ free |\n| MiMo Code | auto-reads `~/.claude/CLAUDE.md` ✅ free |\n| Codex CLI | `~/.codex/AGENTS.md` — needs a symlink |\n| Antigravity | `~/.gemini/GEMINI.md` — needs a symlink |\n| Kimi CLI | no global option — project `AGENTS.md` only |\n| Cursor CLI | no global option — project `AGENTS.md` only |\n\nYour `CLAUDE.md`\n\npoints to other `~/.claude/`\n\nfiles. 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.\n\nOne 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.\n\n``` bash\n#!/usr/bin/env bash\n# ~/.claude/sync-agent-config.sh  — run on change (hook/cron) or manually\nset -euo pipefail\n\nSRC=\"$HOME/.claude/CLAUDE.md\"\nFLAT=\"$HOME/.claude/AGENTS.flat.md\"   # self-contained, references inlined\n\n# 1) FLATTEN: inline @-references / linked files into one file.\n#    (Claude Code resolves @-imports itself, so it keeps using CLAUDE.md.\n#     Everyone else gets the flattened, self-contained version.)\n#    Implement the resolver to match how YOUR CLAUDE.md references files —\n#    e.g. expand lines like `@~/.claude/refs/foo.md` or `@refs/foo.md`:\npython3 - \"$SRC\" \"$FLAT\" <<'PY'\nimport re, sys, pathlib\nsrc, out = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])\nbase = src.parent\nseen = set()\ndef expand(p: pathlib.Path) -> str:\n    p = p.expanduser().resolve()\n    if p in seen or not p.exists():           # avoid cycles / missing\n        return f\"<!-- missing or cyclic: {p} -->\"\n    seen.add(p)\n    lines = []\n    for line in p.read_text().splitlines():\n        m = re.match(r'^\\s*@([~./\\w\\-/]+\\.md)\\s*$', line)   # a bare @path import on its own line\n        if m:\n            ref = (base / m.group(1)).expanduser() if not m.group(1).startswith(('/','~')) else pathlib.Path(m.group(1))\n            lines.append(f\"\\n<!-- inlined from {m.group(1)} -->\\n\" + expand(ref))\n        else:\n            lines.append(line)\n    return \"\\n\".join(lines)\nout.write_text(expand(src))\nprint(f\"flattened -> {out}\")\nPY\n\n# 2) FAN-OUT: symlink the flattened file to each tool's GLOBAL path.\nmkdir -p ~/.codex ~/.gemini ~/.config/opencode ~/.config/mimocode\nln -sf \"$FLAT\" ~/.codex/AGENTS.md            # Codex\nln -sf \"$FLAT\" ~/.gemini/GEMINI.md           # Antigravity\nln -sf \"$FLAT\" ~/.config/opencode/AGENTS.md  # OpenCode (overrides the CLAUDE.md fallback w/ the flattened one)\nln -sf \"$FLAT\" ~/.config/mimocode/AGENTS.md  # MiMo  (same)\n\n# 3) PROJECT level (covers Kimi + Cursor CLI, which have NO global option):\n#    symlink AGENTS.md -> the flattened file in each repo you use.\n#    (You already symlink AGENTS.md -> CLAUDE.md; point it at $FLAT instead\n#     so the references resolve for non-Claude agents too.)\n#    e.g.:  ln -sf \"$FLAT\" /path/to/repo/AGENTS.md\necho \"done.\"\n```\n\n**Trigger it automatically** so it stays in sync — you already run a `config_sync`\n\ntmux session and a `sync-claude-config`\n\nskill; add this script there, or wire a Claude Code `Stop`\n\n/`PostToolUse`\n\nhook that re-runs it when `~/.claude/CLAUDE.md`\n\n(or a referenced file) changes.\n\n| Approach | Pros | Cons | Best for |\n|---|---|---|---|\nFlatten + fan-out (above) |\nOne 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 |\nPlain symlink (no flatten)`AGENTS.md → CLAUDE.md` |\nZero scripting; you already do it | `@` -references stay broken in non-Claude tools; no help for Kimi/Cursor global |\nTools where the file is already self-contained |\nPer-tool (OpenCode, MiMo only)`instructions[]` arrays |\nNo 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 |\n(Codex)`project_doc_fallback_filenames` |\nLets Codex pick up a shared custom filename anywhere | Codex-only; still no reference resolution | Registering a shared filename for Codex |\nMake (drop the references)`CLAUDE.md` itself self-contained |\nSimplest mental model; every tool gets the full content | Loses modularity; bigger single file; 32 KiB caps (Codex/Kimi) bite | Small/medium instruction sets |\n\nWatch the\n\n32 KiB capon Codex and Kimi when flattening — keep the combined file under it, or split content so the per-project`AGENTS.md`\n\ncarries only what each repo needs.\n\n**\"Where does Kimi look?\"** Project tree only —`AGENTS.md`\n\n/`.kimi/AGENTS.md`\n\n/`agents.md`\n\nfrom repo root down to cwd.**No global instructions file exists**(only`~/.kimi/config.toml`\n\n, which can't point to one). A global`~/.claude/CLAUDE.md`\n\nis never read by Kimi. Fix: put the (flattened)`AGENTS.md`\n\nin each repo. (Global*skills*in`~/.kimi/skills/`\n\nand`~/.claude/skills/`\n\n*are*read.)**\"Why isn't my symlink perfect?\"** Because (a) the referenced files aren't resolved by non-Claude tools (only Claude Code does`@`\n\n-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`\n\nglobally; Cursor's CLI reads a project`CLAUDE.md`\n\n. So those need the least work.\n\n- OpenAI Codex —\n[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 —\n[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 —\n[repo](https://github.com/XiaomiMiMo/MiMo-Code)·[config files](https://mimo.xiaomi.com/mimocode/config-files)·[rules](https://mimo.xiaomi.com/mimocode/rules) - Cursor —\n[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 —\n[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 —\n[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 —\n[agents.md](https://agents.md/)\n\n*Compiled by SonPH's WC Coordinator agent via 6 parallel research sub-agents, 23 Jun 2026.*", "url": "https://wpnews.pro/news/unifying-agents-md-claude-md-long-term-memory-instruction-files-across-coding", "canonical_source": "https://gist.github.com/Shoora/03b3f5e82e7c8c713b3a4e21a1708432", "published_at": "2026-06-24 03:31:49+00:00", "updated_at": "2026-06-24 03:43:17.630024+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents", "artificial-intelligence"], "entities": ["Codex CLI", "Kimi Code CLI", "MiMo Code", "Cursor", "Antigravity CLI", "OpenCode", "Claude Code", "OpenAI"], "alternates": {"html": "https://wpnews.pro/news/unifying-agents-md-claude-md-long-term-memory-instruction-files-across-coding", "markdown": "https://wpnews.pro/news/unifying-agents-md-claude-md-long-term-memory-instruction-files-across-coding.md", "text": "https://wpnews.pro/news/unifying-agents-md-claude-md-long-term-memory-instruction-files-across-coding.txt", "jsonld": "https://wpnews.pro/news/unifying-agents-md-claude-md-long-term-memory-instruction-files-across-coding.jsonld"}}