cd /news/developer-tools/unifying-agents-md-claude-md-long-te… · home › topics › developer-tools › article
[ARTICLE · art-37155] src=gist.github.com ↗ pub= topic=developer-tools verified=true sentiment=· neutral

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.

read9 min views8 publishedJun 24, 2026

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 anAGENTS.md

is effectively universal.AGENTS.md

at the repo root. Your existingAGENTS.md → CLAUDE.md

symlink per project already works for all of them.Global instructions are the messy part— each tool reads adifferentglobal path, andtwo of the tools have no global instructions file at all.**Kimi's specific issue is now explained: Kimi hasno global instructions file whatsoever**— it only scans theprojecttree forAGENTS.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 projectCLAUDE.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 differencesandthe 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 levelreplacesit.$CODEX_HOME

overrides the dir. (OpenAI Codex docs, 2026)Project:AGENTS.md

at the git root and one per subdirectory down to cwd; allconcatenated(closer to cwd = later = higher effective priority). 32 KiB cap; one file per directory level. (OpenAI Codex docs)Custom filenames: add names viaproject_doc_fallback_filenames

in~/.codex/config.toml

. (same)— treated as plain text. Open, unmerged feature requests:@

-imports: NOT supported#17401,@include

directive#3413 file-content inclusion.

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

is the only global config and hasnosystem_prompt

/instructions_file

/agents_md

key. The (load_agents_md()

insrc/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,soul/agent.py)Project:.kimi/AGENTS.md

,AGENTS.md

, or lowercaseagents.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)Why "Kimi ignores agents.md": almost always because (1) the file is placed at aglobal path(~/.kimi/

or~/.claude/

) — Kimi only reads itinside 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: Kimidoesscan~/.kimi/skills/

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

Kimi skills docs)in@

-imports: NOT supportedAGENTS.md

(plain-text concat).

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

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

). (MiMo Code config docs)Project:AGENTS.md

at root, falling back toCLAUDE.md

. Precedence: localAGENTS.md

localCLAUDE.md

globalAGENTS.md

globalCLAUDE.md

,all merged. (MiMo Code rules docs)** Multi-file / references:**instructions[]

inmimocode.json

acceptspaths, globs, and remote URLs;@filename

insideAGENTS.md

lazy-imports;{file:path}

inlines content. (config docs)- Adopts AGENTS.md as primary; ships a CLAUDE.md

fallback. (repo)

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

CLI doesnot read them. Confirmed gap. (Cursor Rules docs,forum: global rules with cursor CLI)Project:.cursor/rules/*.mdc

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

(plain markdown, read byboth IDE and CLI), legacy.cursorrules

. The CLI explicitly readsAGENTS.md

andCLAUDE.md

at project root. (Cursor CLI docs)@

-imports:AGENTS.md

has none;@filename

inside.mdc

pullssource-filecontext, not rule composition. (Cursor Rules docs)

Global:~/.gemini/GEMINI.md

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

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

. No globalAGENTS.md

confirmed. (Antigravity deep-dive,hands-on guide)Project: readsbothAGENTS.md

andGEMINI.md

at root (no rename needed;AGENTS.md

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

. (AI Builder Club guide)No data found —@

-imports inside instruction files:@

works at prompt-time only. Useagy 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)Project:AGENTS.md

at root, falling back toCLAUDE.md

(if both exist, onlyAGENTS.md

is used). (OpenCode Rules docs)Multi-file / references — the key feature:instructions[]

inopencode.json

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

-imports areNOT parsed — use this array instead. (OpenCode config docs,DeepWiki)

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.

#!/usr/bin/env bash
set -euo pipefail

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

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

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)

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-projectAGENTS.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. (Globalskillsin~/.kimi/skills/

and~/.claude/skills/

areread.)"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 projectCLAUDE.md

. So those need the least work.

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

source & further reading
gist.github.com — original article Azure log analytics extension for Pi coding agent Claude Code Secrets AI-Enabled Development Workflow — Toolkit (Claude Code, Codex, gstack, Compound Engineering, Conductor, superwhisper, Chops)
── more in #developer-tools 4 stories · sorted by recency
── more on @codex cli 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/unifying-agents-md-c…] indexed:0 read:9min 2026-06-24 · —