[RFC] Optional memory discovery policy (frontmatter + settings) to unify traversal/local issues

Preflight Checklist

• [x] I have searched existing issues and this is a single RFC-style proposal
• [x] This proposal is intended to unify multiple existing memory/discovery issues

RFC: Deterministic memory discovery policy (frontmatter + settings)

This RFC proposes an optional, repo-versioned memory discovery policy for Claude Code.

Goal: unify the recurring conflicts across:

• #16600 (worktree/git-boundary traversal concerns)
• #20880 (exclude parent CLAUDE.md / monorepo context pollution)
• #2950 (imports vs CLAUDE.local.md determinism)
• #22652 (nested CLAUDE.local.md discovery)

Current documented behavior (baseline)

The current docs already define important behavior clearly:

• CLAUDE.local.md is documented as Local instructions and a normal source in the scope table:

https://code.claude.com/docs/en/memory#choose-where-to-put-claude-md-files

• The memory docs say CLAUDE.local.md is automatically loaded and added to .gitignore:

https://code.claude.com/docs/en/memory#import-additional-files

• Ancestor traversal is documented in "How CLAUDE.md files load" (walk up directory tree):

https://code.claude.com/docs/en/memory#how-claude-md-files-load

• Settings scope interaction / precedence is documented in settings docs:

https://code.claude.com/docs/en/settings#how-scopes-interact

• Existing mitigation (claudeMdExcludes) is documented:

https://code.claude.com/docs/en/memory#exclude-specific-claude-md-files

As of March 1, 2026, I could not find an official doc that deprecates CLAUDE.local.md.

Problem statement

Even with the current documented behavior, teams still hit a policy gap:

• Some repos need ancestor inheritance by default.
• Some repos need strict repo boundary behavior.
• Some repos need fully manual inclusion.
• claudeMdExcludes helps but does not provide one portable, repo-owned policy switch that travels with git history.

This is why similar issues keep reappearing with different workarounds.

Proposal

Add an optional memory policy block in CLAUDE.md frontmatter (or equivalent setting) to control discovery mode per repository.

Illustrative schema:

---
memory:
  discovery_mode: filesystem   # filesystem | repo_boundary | manual
  load_local_file: true        # keeps CLAUDE.local.md first-class
  allow_parent_traversal: true # false in repo_boundary/manual
---

Equivalent settings override (for local experimentation) can remain in settings files.

Design principles

1. Preserve current behavior by default (backward compatible).
2. Keep CLAUDE.local.md first-class unless explicitly disabled by policy.
3. Do not redefine or replace existing settings precedence docs; this RFC is about memory discovery policy, not scope precedence.
4. Make active behavior inspectable in /memory (resolved sources + policy mode).

Why this helps across the 4 issues

• #16600 / #20880: repo_boundary provides deterministic isolation without relying only on excludes.
• #2950 / #22652: keeps local-file use case explicit and deterministic while still allowing imports.
• Teams get a repo-versioned switch that can differ by project without forcing one global behavior.

Backward compatibility

• If no policy is set, behavior remains unchanged.
• Policy can be opt-in first.

If maintainers feel this belongs under existing issue(s), I’m happy to consolidate there; this issue is intended as a unifying RFC for policy-level behavior rather than a single bug report.