claude-code - 💡(How to fix) Fix 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.

2. 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.

3. 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.

4. 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/
    [email protected]/         # keyed by git user.email (or a hash of it)
      MEMORY.md
      feedback_*.md
      project_*.md
      ...
    [email protected]/
      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.

2. /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.

3. 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)