Repo-level alternative to per-user `~/.claude/projects/.../memory/` — visibility, portability, debuggability

Summary

Claude Code currently writes "auto memory" entries to
~/.claude/projects/<repo-slug>/memory/MEMORY.md + per-entry .md files.
The system prompt instructs the model to write to this directory liberally
across multiple categories (user, feedback, project, reference). For a
single-developer workflow this functions, but the storage location has
several practical problems:

1. Hidden from the repo. The contents are invisible to anyone who

doesn't have shell access to that machine. Two engineers in the same
repo see different agent behavior with no diff to compare. Onboarding a
new collaborator means the agent loses context the agent itself wrote.

1. Hidden from git. git log / git blame show nothing. When agent

behavior changes, there is no commit to attribute it to. Reviewing or
reverting a memory change is a manual file edit on someone's laptop.

1. Stale-by-design. A memory written six weeks ago can mislead today

and nothing in the project tells you it exists. The model itself flags
memories older than a few days with an inline reminder, but doesn't
re-validate. In my session today, an entry that claimed "the canonical
transactional-repository pattern is super(Entity, cls, schema) +
forFeature — never 2-arg" turned out to be incomplete — the actual
working pattern needed a third leg (don't set target on the
EntitySchema). If that knowledge lived in .claude/guidelines/ it
would have been PR-reviewed, versioned with the code, and corrected via
a normal commit. Instead it sat hidden and steered a planning step
wrong.

1. Cross-machine drift. Same repo on two machines = two memory stores

= two different agents. There is no rsync story, no "promote to repo"
story, no team-shared memory story.

Concrete proposal

Add a setting (memory.location: "repo" | "user" | "both", default
"user" for back-compat). When set to "repo", memory writes go to a
per-user subfolder inside the repo rather than per-machine outside it:

.claude/
  memory/
    user@example.com/         # keyed by git user.email (or a hash of it)
      MEMORY.md
      feedback_*.md
      project_*.md
      ...
    other-collaborator@example.com/
      MEMORY.md
      ...
  guidelines/                 # shared, team-reviewed knowledge
    *.guidelines.md

Properties this gives you that the current per-user-home location doesn't:

• Portable — the user's memory follows the repo, not the machine.

Rebuild your laptop, clone the repo, your agent's context is intact.

• No merge conflicts between users — personal folders are

user-namespaced, so one user's memory writes never collide with
another's. Git treats them as independent paths.

• Visible & debuggable — when two team members see different agent

behavior in the same repo, you can git diff their personal-memory
folders side-by-side and see exactly which entry is driving the drift.
Today there is no way to debug user-specific drift; the state is on
someone's laptop.

• A clear promotion path — when something in

.claude/memory/<user>/ proves out as a team-wide rule, promoting it
to .claude/guidelines/<name>.guidelines.md is an explicit, reviewable
PR (mv + rewrite the frontmatter to the guideline shape). Promotion
becomes a normal code-review event, not a hidden behavior change.

• Auditable history — git log .claude/memory/ shows when the agent

wrote what, and git blame answers "why does Claude think X?" cleanly.

The existing per-user-home location stays the default, so this is purely
additive and back-compat.

Secondary asks

1. Memory writes generate a user-visible signal. When the model

writes a memory entry, surface a one-line confirmation with a "promote
to guideline?" prompt. Today the writes are silent — the user has no
signal that hidden state just changed.

1. /memory UI improvements. A first-class command that lists,

inspects, and edits memory entries with timestamps + age + last-read
indicators, so users can audit drift without cat-ing files in a
hidden directory.

1. Auto-stale detection. Hash referenced file paths or symbols at

write time, re-validate at read time, and refuse to surface entries
whose anchors no longer exist.

Environment

• Claude Code (Opus 4.7)
• macOS 25.4.0
• exploring-claude repo (single-developer experiment, but the proposal

is shaped for multi-user repos)