fix(agents): avoid injecting memory file twice on case-insensitive mounts by Lanfei · Pull Request #26054 · openclaw/openclaw

Lanfei · 2026-02-25T03:19:44Z

Summary

Problem: On case-insensitive file systems mounted into Docker from macOS, both MEMORY.md and memory.md pass fs.access() even when they are the same underlying file.
Why it matters: The previous dedup via fs.realpath() failed in this scenario because realpath does not normalise case through the Docker mount layer, so both paths were treated as distinct entries and the same content was injected into the bootstrap context twice, wasting tokens on every session start.
What changed: Replaced collect-then-dedup with early-exit — try MEMORY.md first, fall back to memory.md only when absent. The function now returns at most one entry regardless of filesystem case-sensitivity. Renamed resolveMemoryBootstrapEntries → resolveMemoryBootstrapEntry to reflect the singular return type.
What did NOT change: Behaviour on case-sensitive Linux (native or Docker) is identical. memory.md fallback still works. No other bootstrap files affected.

Change Type (select all)

Bug fix
Refactor

Scope (select all touched areas)

Memory / storage

Linked Issue/PR

Related feat(agents): add MEMORY.md to bootstrap files #2318 (original memory bootstrap PR whose dedup this fixes)

User-visible / Behavior Changes

On Docker Desktop (macOS host), agents no longer receive duplicate memory context at session start, reducing unnecessary token usage.

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

Repro + Verification

Environment

OS: macOS (host), Linux (Docker container)
Runtime/container: Docker Desktop on macOS with workspace volume mount
Model/provider: any
Integration/channel: any

Steps

Create a workspace with a file named memory.md (lowercase)
Mount that workspace into a Docker container running OpenClaw
Start an agent session and inspect bootstrap files

Expected

One memory entry injected into context

Actual (before fix)

Two memory entries injected with identical content (MEMORY.md and memory.md both pass fs.access(), realpath returns different strings through the mount layer, dedup fails)

Evidence

Failing test/log before + passing after — pnpm test src/agents/workspace.test.ts passes (12 tests)

Human Verification (required)

Verified scenarios: unit tests cover MEMORY.md present, memory.md fallback, neither present
Edge cases checked: early-exit ensures at most one entry on any filesystem
What you did not verify: live Docker on macOS manual repro (deduced from fs.realpath behaviour through Docker mount layers)

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No

Failure Recovery (if this breaks)

How to disable/revert this change quickly: revert src/agents/workspace.ts to restore collect-then-dedup
Files/config to restore: src/agents/workspace.ts, src/agents/workspace.test.ts
Known bad symptoms: agent stops loading memory.md fallback (would only happen if fs.access on MEMORY.md erroneously succeeds without the file existing)

Risks and Mitigations

Risk: On case-sensitive Linux with both MEMORY.md and memory.md as genuinely different files, only MEMORY.md is now loaded (previously both were loaded).
- Mitigation: Having two memory files differing only in case is an unusual/unsupported pattern with no documented use case; the original intent was always a single memory file with a case-insensitive fallback.

Greptile Summary

Fixes duplicate memory file injection on case-insensitive Docker mounts by replacing collect-then-deduplicate logic with early-exit strategy. The function now tries MEMORY.md first and only falls back to memory.md if absent, preventing the same content from being injected twice when fs.realpath() fails to normalize case through Docker mount layers. This eliminates token waste on macOS Docker setups while maintaining backward compatibility for the lowercase fallback.

Confidence Score: 5/5

This PR is safe to merge with minimal risk
The fix is straightforward and well-tested. The early-exit approach is simpler and more reliable than the previous deduplication logic. All existing tests pass and cover the relevant scenarios. The only behavioral change is for the edge case of having both MEMORY.md and memory.md on case-sensitive systems, which is unsupported and unlikely.
No files require special attention

_{Last reviewed commit: 4adff19}

_{(5/5) You can turn off certain types of comments like style here!}

openclaw-barnacle · 2026-03-03T05:30:15Z

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.

Lanfei · 2026-03-03T06:45:32Z

Rebased

Lanfei · 2026-03-13T07:00:40Z

Hey @jalehman @obviyus — could you take a look when you have a moment? CI is green and the change is small. I currently have several open PRs waiting for review, which is making it hard for me to continue contributing. Any feedback or a quick merge would be much appreciated. Thanks!

…unts On case-insensitive file systems mounted into Docker from macOS, both MEMORY.md and memory.md pass fs.access() even when they are the same underlying file. The previous dedup via fs.realpath() failed in this scenario because realpath does not normalise case through the Docker mount layer, so both paths were treated as distinct entries and the same content was injected into the bootstrap context twice, wasting tokens. Fix by replacing the collect-then-dedup approach with an early-exit: try MEMORY.md first; fall back to memory.md only when MEMORY.md is absent. This makes the function return at most one entry regardless of filesystem case-sensitivity.

@Lanfei

… (thanks @Lanfei)

obviyus · 2026-03-13T09:10:12Z

Landed on main.

Landed source commit: 5ed80a8
Merge commit: a3eed2b

Thanks @Lanfei.

* main: (168 commits) fix: stabilize macos daemon onboarding fix(ui): keep shared auth on insecure control-ui connects (openclaw#45088) docs(plugins): clarify workspace shadowing fix(node-host): harden perl approval binding fix(node-host): harden pnpm approval binding fix(discovery): add missing domain to wideArea Zod config schema (openclaw#35615) chore(gitignore): add docker-compose override (openclaw#42879) feat(ios): add onboarding welcome pager (openclaw#45054) fix(signal): add groups config to Signal channel schema (openclaw#27199) fix: restore web fetch firecrawl config in runtime zod schema (openclaw#42583) fix: polish Android QR scanner onboarding (openclaw#45021) fix(android): use Google Code Scanner for onboarding QR fix(config): add missing params field to agents.list[] validation schema (openclaw#41171) docs(contributing): update Android app ownership fix(agents): rephrase session reset prompt to avoid Azure content filter (openclaw#43403) test(config): cover requiresOpenAiAnthropicToolPayload in compat schema fixture fix(agents): respect explicit user compat overrides for non-native openai-completions (openclaw#44432) Android: fix HttpURLConnection leak in TalkModeVoiceResolver (openclaw#43780) Docker: add OPENCLAW_TZ timezone support (openclaw#34119) fix(agents): avoid injecting memory file twice on case-insensitive mounts (openclaw#26054) ...

HenryLoenwind · 2026-03-14T11:20:25Z

This should have been marked as breaking change, not buried in fixes.

obviyus · 2026-03-14T11:22:38Z

@HenryLoenwind agreed, that's on me. Will update the changelog.

@Lanfei

…unts (openclaw#26054) * fix(agents): avoid injecting memory file twice on case-insensitive mounts On case-insensitive file systems mounted into Docker from macOS, both MEMORY.md and memory.md pass fs.access() even when they are the same underlying file. The previous dedup via fs.realpath() failed in this scenario because realpath does not normalise case through the Docker mount layer, so both paths were treated as distinct entries and the same content was injected into the bootstrap context twice, wasting tokens. Fix by replacing the collect-then-dedup approach with an early-exit: try MEMORY.md first; fall back to memory.md only when MEMORY.md is absent. This makes the function return at most one entry regardless of filesystem case-sensitivity. * docs: clarify singular memory bootstrap fallback * fix: note memory bootstrap fallback docs and changelog (openclaw#26054) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

obviyus · 2026-03-14T11:26:04Z

Updated in 64e6df7.

@Lanfei

…unts (openclaw#26054) * fix(agents): avoid injecting memory file twice on case-insensitive mounts On case-insensitive file systems mounted into Docker from macOS, both MEMORY.md and memory.md pass fs.access() even when they are the same underlying file. The previous dedup via fs.realpath() failed in this scenario because realpath does not normalise case through the Docker mount layer, so both paths were treated as distinct entries and the same content was injected into the bootstrap context twice, wasting tokens. Fix by replacing the collect-then-dedup approach with an early-exit: try MEMORY.md first; fall back to memory.md only when MEMORY.md is absent. This makes the function return at most one entry regardless of filesystem case-sensitivity. * docs: clarify singular memory bootstrap fallback * fix: note memory bootstrap fallback docs and changelog (openclaw#26054) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

@Lanfei

…unts (openclaw#26054) * fix(agents): avoid injecting memory file twice on case-insensitive mounts On case-insensitive file systems mounted into Docker from macOS, both MEMORY.md and memory.md pass fs.access() even when they are the same underlying file. The previous dedup via fs.realpath() failed in this scenario because realpath does not normalise case through the Docker mount layer, so both paths were treated as distinct entries and the same content was injected into the bootstrap context twice, wasting tokens. Fix by replacing the collect-then-dedup approach with an early-exit: try MEMORY.md first; fall back to memory.md only when MEMORY.md is absent. This makes the function return at most one entry regardless of filesystem case-sensitivity. * docs: clarify singular memory bootstrap fallback * fix: note memory bootstrap fallback docs and changelog (openclaw#26054) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]> (cherry picked from commit a3eed2b)

@Lanfei

…unts (openclaw#26054) * fix(agents): avoid injecting memory file twice on case-insensitive mounts On case-insensitive file systems mounted into Docker from macOS, both MEMORY.md and memory.md pass fs.access() even when they are the same underlying file. The previous dedup via fs.realpath() failed in this scenario because realpath does not normalise case through the Docker mount layer, so both paths were treated as distinct entries and the same content was injected into the bootstrap context twice, wasting tokens. Fix by replacing the collect-then-dedup approach with an early-exit: try MEMORY.md first; fall back to memory.md only when MEMORY.md is absent. This makes the function return at most one entry regardless of filesystem case-sensitivity. * docs: clarify singular memory bootstrap fallback * fix: note memory bootstrap fallback docs and changelog (openclaw#26054) (thanks @Lanfei) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

openclaw-barnacle bot added agents Agent runtime and tooling size: XS labels Feb 25, 2026

openclaw-barnacle bot added the stale Marked as stale due to inactivity label Mar 3, 2026

Lanfei force-pushed the fix/memory-bootstrap-dedup branch from 4adff19 to 0fc9a38 Compare March 3, 2026 06:36

openclaw-barnacle bot removed the stale Marked as stale due to inactivity label Mar 4, 2026

obviyus self-assigned this Mar 13, 2026

openclaw-barnacle bot added the docs Improvements or additions to documentation label Mar 13, 2026

Lanfei and others added 3 commits March 13, 2026 14:38

docs: clarify singular memory bootstrap fallback

426f5ab

fix: note memory bootstrap fallback docs and changelog (openclaw#26054)…

5ed80a8

… (thanks @Lanfei)

obviyus force-pushed the fix/memory-bootstrap-dedup branch from 133988e to 5ed80a8 Compare March 13, 2026 09:09

obviyus merged commit a3eed2b into openclaw:main Mar 13, 2026
10 checks passed

github-actions bot mentioned this pull request Mar 13, 2026

📡 Upstream Digest — 2026-03-13 10:28 UTC curtismercier/openclaw-mods#251

Open

Lanfei deleted the fix/memory-bootstrap-dedup branch March 14, 2026 02:19

github-actions bot mentioned this pull request Mar 14, 2026

上游更新: v2026.3.13 — 16 P0 + 29 P1 待合并 jiulingyun/openclaw-cn#510

Open

github-actions bot mentioned this pull request Mar 15, 2026

📢 OpenClaw 新版本发布: v2026.3.13-1 xianyu110/awesome-openclaw-tutorial#32

Closed

5 tasks

MoerAI mentioned this pull request Mar 18, 2026

fix: use file identity (dev:ino) for memory file dedup on case-insensitive FS #43956

Closed

alexey-pelykh mentioned this pull request Mar 23, 2026

Cherry-pick: Documentation updates (4/4) (35 commits) remoteclaw/remoteclaw#1911

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(agents): avoid injecting memory file twice on case-insensitive mounts#26054

fix(agents): avoid injecting memory file twice on case-insensitive mounts#26054
obviyus merged 3 commits intoopenclaw:mainfrom
Lanfei:fix/memory-bootstrap-dedup

Lanfei commented Feb 25, 2026 •

edited by greptile-apps bot

Loading

Uh oh!

openclaw-barnacle bot commented Mar 3, 2026

Uh oh!

Lanfei commented Mar 3, 2026

Uh oh!

Lanfei commented Mar 13, 2026

Uh oh!

Uh oh!

obviyus commented Mar 13, 2026

Uh oh!

HenryLoenwind commented Mar 14, 2026

Uh oh!

obviyus commented Mar 14, 2026

Uh oh!

obviyus commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Lanfei commented Feb 25, 2026 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual (before fix)

Evidence

Human Verification (required)

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Greptile Summary

Confidence Score: 5/5

Uh oh!

openclaw-barnacle bot commented Mar 3, 2026

Uh oh!

Lanfei commented Mar 3, 2026

Uh oh!

Lanfei commented Mar 13, 2026

Uh oh!

Uh oh!

obviyus commented Mar 13, 2026

Uh oh!

HenryLoenwind commented Mar 14, 2026

Uh oh!

obviyus commented Mar 14, 2026

Uh oh!

obviyus commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Lanfei commented Feb 25, 2026 •

edited by greptile-apps bot

Loading