Skip to content

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

Rust

fix(routing): state Claude Code's AGENTS.md fallback (#1276)

Victor Alencar86a087cfb183
diff --git a/AGENTS.md b/AGENTS.md
index 2c5c431c..23eaef69 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -81,10 +81,11 @@ 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 loads `CLAUDE.md` and does not read `AGENTS.md`. In a project
-where `AGENTS.md` is canonical, give `CLAUDE.md` a bare `@AGENTS.md` import
-line. Without it a rule written to `AGENTS.md` is absent from context at
-session start and reaches Claude Code only if the agent opens the file.
+Claude Code 2.1.277 and later reads `AGENTS.md` when no `CLAUDE.md` or
+`CLAUDE.local.md` is present; when `CLAUDE.md` exists it still wins. In a
+project where `AGENTS.md` is canonical, give `CLAUDE.md` a bare
+`@AGENTS.md` import line so older Claude Code and the CLAUDE.md-first
+mode 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 0a8c0725..4f0251d6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,10 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
### Fixed
+- Fixed the managed routing snippet's Claude Code instruction. Since 2.1.277
+ it reads `AGENTS.md` when no `CLAUDE.md` or `CLAUDE.local.md` is present,
+ and prefers `CLAUDE.md` when that file exists. The `@AGENTS.md` import is
+ how a canonical `AGENTS.md` reaches those sessions. (#1276)
- Fixed Windows capture dropping the body of file and shell tool events
the client had kept. With `[capture] ignore_paths` active, server
re-inspection compiled a POSIX never-match sentinel and treated the
diff --git a/CLAUDE.md b/CLAUDE.md
index e7a5f290..2125f4aa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,9 +1,11 @@
@AGENTS.md
<!--
-Claude Code reads CLAUDE.md and does not read AGENTS.md, so the import on the
-first line is what loads this repository's canonical instruction file into a
-Claude Code session: https://code.claude.com/docs/en/memory#agents-md
+Claude Code 2.1.277 and later reads AGENTS.md when CLAUDE.md and
+CLAUDE.local.md are absent. This file still wins when present, so the
+import on the first line is what loads the canonical instruction file
+into a Claude Code session that loads CLAUDE.md (older versions, and the
+default when this file exists): https://code.claude.com/docs/en/memory#agents-md
A prose "read AGENTS.md" pointer loads nothing at session start; it asks the
agent to open the file, which leaves adherence to whether it does.
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index 6800826a..ab2d95f6 100644
--- a/crates/ai-memory-core/src/routing_snippet.rs
+++ b/crates/ai-memory-core/src/routing_snippet.rs
@@ -109,10 +109,11 @@ 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 loads `CLAUDE.md` and does not read `AGENTS.md`. In a project
-where `AGENTS.md` is canonical, give `CLAUDE.md` a bare `@AGENTS.md` import
-line. Without it a rule written to `AGENTS.md` is absent from context at
-session start and reaches Claude Code only if the agent opens the file.
+Claude Code 2.1.277 and later reads `AGENTS.md` when no `CLAUDE.md` or
+`CLAUDE.local.md` is present; when `CLAUDE.md` exists it still wins. In a
+project where `AGENTS.md` is canonical, give `CLAUDE.md` a bare
+`@AGENTS.md` import line so older Claude Code and the CLAUDE.md-first
+mode 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
@@ -305,6 +306,34 @@ mod tests {
assert!(COMPACT_SNIPPET_BODY.contains("omit `workspace`, `project`, and `cwd`"));
}
+ #[test]
+ fn snippet_does_not_claim_claude_code_ignores_agents_md() {
+ assert!(
+ !SNIPPET_BODY.contains("does not read `AGENTS.md`"),
+ "Claude Code 2.1.277+ reads AGENTS.md when no CLAUDE.md exists"
+ );
+ assert!(
+ !COMPACT_SNIPPET_BODY.contains("does not read `AGENTS.md`"),
+ "compact snippet must not repeat the stale CLAUDE.md-only claim"
+ );
+ }
+
+ #[test]
+ fn snippet_describes_claude_code_agents_md_fallback() {
+ assert!(
+ SNIPPET_BODY.contains("2.1.277"),
+ "full snippet should name the Claude Code version that reads AGENTS.md"
+ );
+ assert!(
+ SNIPPET_BODY.contains("reads `AGENTS.md` when"),
+ "full snippet should state the no-CLAUDE.md fallback"
+ );
+ assert!(
+ SNIPPET_BODY.contains("`CLAUDE.local.md`"),
+ "a CLAUDE.local.md also blocks the AGENTS.md fallback"
+ );
+ }
+
#[test]
fn snippet_distinguishes_session_aware_and_static_scope_routing() {
assert!(SNIPPET_BODY.contains("Session-aware MCP clients"));
diff --git a/docs/install.md b/docs/install.md
index b7ff9d97..3c999572 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -424,8 +424,10 @@ 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
-loads `CLAUDE.md` and does not read `AGENTS.md`, so without that import the
-installed block is absent from context at session start. See
+2.1.277 and later reads `AGENTS.md` when no `CLAUDE.md` or `CLAUDE.local.md`
+is present; when `CLAUDE.md` exists it still wins, so without that import
+older Claude Code and the CLAUDE.md-first mode 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 edab69a1..231ea428 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -367,12 +367,13 @@ Agent, `--skills-agent hermes`
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 loads
-`CLAUDE.md` and does not read `AGENTS.md`, so without that import a block
-installed with `--target AGENTS.md`, along with every project rule in the same
-file, is absent from context at session start. 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.md` whose first line is a bare `@AGENTS.md` import. Claude Code 2.1.277
+and later reads `AGENTS.md` when no `CLAUDE.md` or `CLAUDE.local.md` is present;
+when `CLAUDE.md` exists it still wins, so without that import a block installed
+with `--target AGENTS.md`, along with every project rule in the same file, is
+absent from older Claude Code and from the CLAUDE.md-first mode at session
+start. 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).
To refresh only the managed Agent Skills: