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.mdindex 2042f1de..a5cf0765 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -81,13 +81,13 @@ Many projects use CLAUDE.md for Claude Code andAGENTS.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 toevery project (tech choices, code style, personal conventions), save itdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 arenever resent with the current token, which would attribute them to theoperator. (#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-13diff --git a/CLAUDE.md b/CLAUDE.mdindex 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, soClaude Code reads it instead, and the import on the first line is what loadsthe canonical instruction file into a Claude Code session on any version:https://code.claude.com/docs/en/memory#agents-mddiff --git a/crates/ai-memory-cli/src/commands/install_instructions.rs b/crates/ai-memory-cli/src/commands/install_instructions.rsindex 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.rsindex 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.rsindex 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 andAGENTS.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 toevery 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.mdindex 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 Code2.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.mdindex 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.277and 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 "readAGENTS.md" pointer does not load the file; it asks the agent to open it, whichleaves 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: