Skip to content

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

Rust

docs(routing): name the sessions that read only CLAUDE.md (#1276)

Victor Alencard066eefa8d96
diff --git a/AGENTS.md b/AGENTS.md
index 23eaef69..2042f1de 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -81,11 +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` 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.
+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.
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 4f0251d6..2fe9d4c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,10 +12,11 @@ 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 the managed routing snippet's claim that Claude Code never reads
+ `AGENTS.md`. Claude Code 2.1.277 and later reads it when no `CLAUDE.md`,
+ `.claude/CLAUDE.md`, or `CLAUDE.local.md` is present, and reads that file
+ instead when one exists. The `@AGENTS.md` import is how a canonical
+ `AGENTS.md` reaches sessions that read only `CLAUDE.md`. (#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 2125f4aa..240899bb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,11 +1,11 @@
@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
+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 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
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 ab2d95f6..3fe6e666 100644
--- a/crates/ai-memory-core/src/routing_snippet.rs
+++ b/crates/ai-memory-core/src/routing_snippet.rs
@@ -109,11 +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` 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.
+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.
If the rule is a standing *user/team* preference that should apply to
every project (tech choices, code style, personal conventions), save it
@@ -332,6 +334,14 @@ mod tests {
SNIPPET_BODY.contains("`CLAUDE.local.md`"),
"a CLAUDE.local.md also blocks the AGENTS.md fallback"
);
+ assert!(
+ SNIPPET_BODY.contains("`.claude/CLAUDE.md`"),
+ "a .claude/CLAUDE.md also blocks the AGENTS.md fallback"
+ );
+ assert!(
+ SNIPPET_BODY.contains("the `claude-md` Project instructions"),
+ "name Claude Code's real setting, not an invented mode"
+ );
}
#[test]
diff --git a/docs/install.md b/docs/install.md
index 3c999572..537c8786 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -424,10 +424,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` 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
+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 Code memory](https://code.claude.com/docs/en/memory#agents-md).
---
diff --git a/docs/usage.md b/docs/usage.md
index 231ea428..036092fb 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -368,12 +368,13 @@ 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` 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
+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
+`--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).
To refresh only the managed Agent Skills: