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

coding-agents-memory-config-research.md

Unifying the "long-term memory" instruction file (AGENTS.md / CLAUDE.md) across coding agents

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.

---

TL;DR

1. Project-level AGENTS.md is effectively universal. Every tool here reads an AGENTS.md at the repo root. Your existing AGENTS.md → CLAUDE.md symlink per project already works for all of them.
2. 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.
3. 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."
4. In-file @-references only resolve in Claude Code (and partly MiMo). Codex, Kimi, Cursor's AGENTS.md, OpenCode, and Antigravity all treat @path as plain text — so your CLAUDE.md's references to other ~/.claude/ files silently break in every non-Claude tool.
5. Two free wins: OpenCode and MiMo Code both fall back to ~/.claude/CLAUDE.md for global instructions if they don't find their own — so they already read your global file for free. Cursor's CLI also reads a project CLAUDE.md.
6. 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.

---

Master reference table

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.

---

Per-tool detail

Codex CLI (OpenAI)

• Global: ~/.codex/AGENTS.md. AGENTS.override.md at the same level replaces it. $CODEX_HOME overrides the dir. (OpenAI Codex docs, 2026)
• 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)
• Custom filenames: add names via project_doc_fallback_filenames in ~/.codex/config.toml. (same)
• @-imports: NOT supported — treated as plain text. Open, unmerged feature requests: #17401 @include directive, #3413 file-content inclusion.

Kimi Code CLI (Moonshot AI) — the crux

• 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, 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)
• 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 ~/.claude/skills/ globally — but skills ≠ instructions. (Kimi skills docs)
• @-imports: NOT supported in AGENTS.md (plain-text concat).

MiMo Code (Xiaomi)

• Global: ~/.config/mimocode/AGENTS.md (+ ~/.config/mimocode/mimocode.json). (MiMo Code config docs)
• 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)
• 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)
• Adopts AGENTS.md as primary; ships a CLAUDE.md fallback. (repo)

Cursor (cursor-agent CLI + IDE)

• 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, forum: global rules with cursor CLI)
• 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)
• @-imports: AGENTS.md has none; @filename inside .mdc pulls source-file context, not rule composition. (Cursor Rules docs)

Antigravity CLI (agy, Google)

• 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, hands-on guide)
• 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)
• @-imports inside instruction files: No data found — @ works at prompt-time only. Use agy inspect to see exactly which files were loaded.

OpenCode (SST)

• Global: ~/.config/opencode/AGENTS.md, falling back to ~/.claude/CLAUDE.md if absent (disable via OPENCODE_DISABLE_CLAUDE_CODE). Global config: ~/.config/opencode/opencode.json. (OpenCode Rules docs)
• Project: AGENTS.md at root, falling back to CLAUDE.md (if both exist, only AGENTS.md is used). (OpenCode Rules docs)
• 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, DeepWiki)

---

The two real problems, and how to solve them

Problem 1 — global instructions land in 6 different places (or nowhere)

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

Problem 2 — @-references break everywhere except Claude Code

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.

Recommended solution: "flatten + fan-out" sync script

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
# ~/.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.

Alternatives & trade-offs

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 AGENTS.md → CLAUDE.md (no flatten)	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 instructions[] arrays (OpenCode, MiMo only)	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
project_doc_fallback_filenames (Codex)	Lets Codex pick up a shared custom filename anywhere	Codex-only; still no reference resolution	Registering a shared filename for Codex
Make CLAUDE.md itself self-contained (drop the references)	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 cap on 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.

---

Quick answers to your exact questions

• "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.

---

Sources

• OpenAI Codex — AGENTS.md guide · issue #17401 · issue #3413
• Kimi CLI — config files · soul/agent.py · AGENTS.md · skills
• MiMo Code — repo · config files · rules
• Cursor — Rules · CLI · forum: global rules w/ CLI
• Antigravity — deep-dive · hands-on guide · Gemini CLI → Antigravity transition
• OpenCode — Rules · Config · DeepWiki config system
• AGENTS.md open standard — agents.md

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