Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(routing): name the parent-directory rule and warn when Claude Code skips AGENTS.md

AkitaOnRailsb975bdc088d4
diff --git a/AGENTS.md b/AGENTS.md
index 2042f1de..a5cf0765 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -81,13 +81,13 @@ Many projects use CLAUDE.md for Claude Code and
AGENTS.md for Codex / OpenCode / OpenCode 2 / Cursor / Gemini CLI / Grok Build CLI / Kimi Code / Kiro CLI / Command Code / GitHub Copilot CLI / Muse Code,
but if the project says one file is canonical, use that file.
-Claude Code 2.1.277 and later reads `AGENTS.md` when no `CLAUDE.md`,
-`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present; when one exists, it
-reads that file instead. In a project where `AGENTS.md` is canonical, give
-`CLAUDE.md` a bare `@AGENTS.md` import line so sessions that read only
-`CLAUDE.md` (older Claude Code, the `claude-md` Project instructions
-setting, or a project that also keeps a `CLAUDE.md`) load the same rules at
-session start.
+Claude Code 2.1.277 and later reads `AGENTS.md` only when no `CLAUDE.md`,
+`.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or
+any directory above it; when one does, it reads that file instead. In a
+project where `AGENTS.md` is canonical, give `CLAUDE.md` a bare `@AGENTS.md`
+import line so sessions that read only `CLAUDE.md` (older Claude Code, the
+AGENTS.md plugin disabled, the `claude-md` Project instructions setting, or a
+developer's own `CLAUDE.local.md`) load the same rules at session start.
If the rule is a standing *user/team* preference that should apply to
every project (tech choices, code style, personal conventions), save it
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac4c4cff..88e07d0a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,12 @@ version in [`docs/changelog/`](docs/changelog/):
credential are still dropped once their attempt budget runs out; they are
never resent with the current token, which would attribute them to the
operator. (#1283)
+- Fixed `install-instructions` writing the block into `AGENTS.md` alone, with
+ no warning, when Claude Code would never read it. Claude Code reads
+ `AGENTS.md` only when no `CLAUDE.md`, `.claude/CLAUDE.md` or
+ `CLAUDE.local.md` exists in the directory or above it, so a developer's
+ `CLAUDE.local.md` hid the block. The command now names the file Claude Code
+ reads instead and how to import `@AGENTS.md` from it. (#1297)
## [3.0.0] - 2026-10-13
diff --git a/CLAUDE.md b/CLAUDE.md
index 240899bb..29cb3196 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,7 +2,8 @@
<!--
Claude Code 2.1.277 and later reads AGENTS.md only when no CLAUDE.md,
-.claude/CLAUDE.md, or CLAUDE.local.md is present. This file is present, so
+.claude/CLAUDE.md, or CLAUDE.local.md exists in this directory or above it.
+This file is present, so
Claude Code reads it instead, and the import on the first line is what loads
the canonical instruction file into a Claude Code session on any version:
https://code.claude.com/docs/en/memory#agents-md
diff --git a/crates/ai-memory-cli/src/commands/install_instructions.rs b/crates/ai-memory-cli/src/commands/install_instructions.rs
index c7937ab1..f2f27db6 100644
--- a/crates/ai-memory-cli/src/commands/install_instructions.rs
+++ b/crates/ai-memory-cli/src/commands/install_instructions.rs
@@ -61,6 +61,17 @@ fn run_inner(
full_block()
};
let targets = resolve_targets(args.target.as_ref())?;
+ if report {
+ let home = env
+ .var_os("HOME")
+ .or_else(|| env.var_os("USERPROFILE"))
+ .map(PathBuf::from);
+ if let Ok(cwd) = std::env::current_dir()
+ && let Some(note) = claude_code_skips_agents_md(&targets, &cwd, home.as_deref())
+ {
+ eprintln!("{note}");
+ }
+ }
let skill_args = if args.no_skills {
None
} else {
@@ -155,6 +166,54 @@ fn resolve_targets(explicit: Option<&std::path::PathBuf>) -> Result<Vec<std::pat
}
}
+/// A note for when the block goes only into `AGENTS.md` but Claude Code will
+/// not read that file (#1297). Claude Code 2.1.277 and later reads
+/// `AGENTS.md` only when no `CLAUDE.md`, `.claude/CLAUDE.md` or
+/// `CLAUDE.local.md` exists in the working directory or above it; when one
+/// does, it reads those instead. The block then reaches Claude Code only if one
+/// of them imports `@AGENTS.md`. The user file `~/.claude/CLAUDE.md` does not
+/// count.
+fn claude_code_skips_agents_md(
+ targets: &[PathBuf],
+ cwd: &std::path::Path,
+ home: Option<&std::path::Path>,
+) -> Option<String> {
+ let named = |name: &str| {
+ targets
+ .iter()
+ .any(|target| target.file_name().and_then(|n| n.to_str()) == Some(name))
+ };
+ if !named("AGENTS.md") || named("CLAUDE.md") {
+ return None;
+ }
+ let mut found = Vec::new();
+ for dir in cwd.ancestors() {
+ for name in ["CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md"] {
+ if name == ".claude/CLAUDE.md" && home == Some(dir) {
+ continue;
+ }
+ let candidate = dir.join(name);
+ if candidate.is_file() {
+ found.push(candidate);
+ }
+ }
+ }
+ let imports_agents_md = |path: &PathBuf| {
+ std::fs::read_to_string(path)
+ .is_ok_and(|text| text.lines().any(|line| line.trim() == "@AGENTS.md"))
+ };
+ let first = found.first()?;
+ if found.iter().any(imports_agents_md) {
+ return None;
+ }
+ Some(format!(
+ "note: {} exists, so Claude Code reads it instead of AGENTS.md and will not see \
+ this block. Add a bare `@AGENTS.md` line to a CLAUDE.md there, or set Claude \
+ Code's Project instructions to `claude-md-and-agents-md`.",
+ first.display()
+ ))
+}
+
fn skill_args_from_instruction_args(
args: &InstallInstructionsArgs,
targets: &[PathBuf],
diff --git a/crates/ai-memory-cli/tests/suite/routing_instructions.rs b/crates/ai-memory-cli/tests/suite/routing_instructions.rs
index 5f26ea07..397ed16d 100644
--- a/crates/ai-memory-cli/tests/suite/routing_instructions.rs
+++ b/crates/ai-memory-cli/tests/suite/routing_instructions.rs
@@ -477,3 +477,43 @@ fn devin_install_instructions_writes_project_devin_skills() {
assert!(!project.path().join(".claude/skills").exists());
assert!(!project.path().join(".agents/skills").exists());
}
+
+/// #1297: with only `AGENTS.md` written, a `CLAUDE.local.md` or
+/// `.claude/CLAUDE.md` makes Claude Code read that instead, so the install
+/// says so. Controls: `AGENTS.md` alone, a `CLAUDE.md` target alongside, and a
+/// shadowing file that already imports `@AGENTS.md` print no note.
+#[test]
+fn install_instructions_warns_when_claude_code_will_skip_agents_md() {
+ let note = "so Claude Code reads it instead of AGENTS.md";
+ let run = |files: &[(&str, &str)]| {
+ let project = tempfile::tempdir().unwrap();
+ let home = tempfile::tempdir().unwrap();
+ fs::write(project.path().join("AGENTS.md"), "# Project\n").unwrap();
+ for (name, text) in files {
+ let path = project.path().join(name);
+ fs::create_dir_all(path.parent().unwrap()).unwrap();
+ fs::write(path, text).unwrap();
+ }
+ let output = run_ai_memory(
+ project.path(),
+ home.path(),
+ &["install-instructions", "--no-skills"],
+ );
+ let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+ assert_success(output);
+ let agents = fs::read_to_string(project.path().join("AGENTS.md")).unwrap();
+ assert!(agents.contains(MARKER_START), "AGENTS.md gets the block");
+ stderr
+ };
+ for shadow in ["CLAUDE.local.md", ".claude/CLAUDE.md"] {
+ let stderr = run(&[(shadow, "# mine\n")]);
+ assert!(
+ stderr.contains(note) && stderr.contains(shadow),
+ "{shadow}: {stderr}"
+ );
+ }
+ assert!(!run(&[]).contains(note));
+ assert!(!run(&[("CLAUDE.local.md", "@AGENTS.md\n")]).contains(note));
+ // A CLAUDE.md alongside becomes a target too, so Claude Code sees the block.
+ assert!(!run(&[("CLAUDE.md", "# claude\n")]).contains(note));
+}
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index 3fe6e666..c9d3cbdb 100644
--- a/crates/ai-memory-core/src/routing_snippet.rs
+++ b/crates/ai-memory-core/src/routing_snippet.rs
@@ -109,13 +109,13 @@ Many projects use CLAUDE.md for Claude Code and
AGENTS.md for Codex / OpenCode / OpenCode 2 / Cursor / Gemini CLI / Grok Build CLI / Kimi Code / Kiro CLI / Command Code / GitHub Copilot CLI / Muse Code,
but if the project says one file is canonical, use that file.
-Claude Code 2.1.277 and later reads `AGENTS.md` when no `CLAUDE.md`,
-`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present; when one exists, it
-reads that file instead. In a project where `AGENTS.md` is canonical, give
-`CLAUDE.md` a bare `@AGENTS.md` import line so sessions that read only
-`CLAUDE.md` (older Claude Code, the `claude-md` Project instructions
-setting, or a project that also keeps a `CLAUDE.md`) load the same rules at
-session start.
+Claude Code 2.1.277 and later reads `AGENTS.md` only when no `CLAUDE.md`,
+`.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or
+any directory above it; when one does, it reads that file instead. In a
+project where `AGENTS.md` is canonical, give `CLAUDE.md` a bare `@AGENTS.md`
+import line so sessions that read only `CLAUDE.md` (older Claude Code, the
+AGENTS.md plugin disabled, the `claude-md` Project instructions setting, or a
+developer's own `CLAUDE.local.md`) load the same rules at session start.
If the rule is a standing *user/team* preference that should apply to
every project (tech choices, code style, personal conventions), save it
@@ -327,7 +327,7 @@ mod tests {
"full snippet should name the Claude Code version that reads AGENTS.md"
);
assert!(
- SNIPPET_BODY.contains("reads `AGENTS.md` when"),
+ SNIPPET_BODY.contains("reads `AGENTS.md` only when"),
"full snippet should state the no-CLAUDE.md fallback"
);
assert!(
diff --git a/docs/install.md b/docs/install.md
index 68e05308..2b306527 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -425,10 +425,11 @@ managed Agent Skills are installed or updated alongside it.
If you install into `AGENTS.md` and the project is also used from Claude Code,
make `CLAUDE.md` import it with a bare `@AGENTS.md` first line. Claude Code
2.1.277 and later reads `AGENTS.md` only when no `CLAUDE.md`,
-`.claude/CLAUDE.md`, or `CLAUDE.local.md` is present. Without that import,
-sessions that read only `CLAUDE.md` (older Claude Code, the `claude-md`
-Project instructions setting, or a project that also keeps a `CLAUDE.md`)
-miss the installed block at session start. See
+`.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or
+any directory above it. Without that import, sessions that read only
+`CLAUDE.md` (older Claude Code, the AGENTS.md plugin disabled, the `claude-md`
+Project instructions setting, or a developer's own `CLAUDE.local.md`) miss the
+installed block at session start. See
[Claude Code memory](https://code.claude.com/docs/en/memory#agents-md).
---
diff --git a/docs/usage.md b/docs/usage.md
index 036092fb..193e3d90 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -369,13 +369,18 @@ installs under `.hermes/skills` (project) or `~/.hermes/skills` (global).
When a project keeps `AGENTS.md` as its canonical instruction file, give it a
`CLAUDE.md` whose first line is a bare `@AGENTS.md` import. Claude Code 2.1.277
and later reads `AGENTS.md` only when no `CLAUDE.md`, `.claude/CLAUDE.md`, or
-`CLAUDE.local.md` is present. Without that import, sessions that read only
-`CLAUDE.md` (older Claude Code, the `claude-md` Project instructions setting, or
-a project that also keeps a `CLAUDE.md`) start without a block installed with
+`CLAUDE.local.md` exists in the working directory or any directory above it.
+Without that import, sessions that read only `CLAUDE.md` (older Claude Code, the
+AGENTS.md plugin disabled, the `claude-md` Project instructions setting, or a
+developer's own `CLAUDE.local.md`) start without a block installed with
`--target AGENTS.md`, or any other project rule in that file. A prose "read
AGENTS.md" pointer does not load the file; it asks the agent to open it, which
leaves adherence to whether the agent does. See
[Claude Code memory](https://code.claude.com/docs/en/memory#agents-md).
+`install-instructions` prints a note when it writes only `AGENTS.md` while a
+`CLAUDE.local.md`, `.claude/CLAUDE.md` or `CLAUDE.md` in the directory or above
+it would make Claude Code read that file instead, unless one of them already
+imports `@AGENTS.md`.
To refresh only the managed Agent Skills: