Memory routing: get team-applicable gotchas into shared standards

Goal

Ensure that gotchas, preferences, and references Claude learns during sessions end up in shared team knowledge (standards/CLAUDE.md) when they apply to anyone on the codebase — instead of fragmenting across each developer's personal memory file. Today, the same lessons get re-learned independently by each team member, producing inconsistent Claude experiences and wasting aggregate hours.

Current Behavior

The auto-memory system writes to ~/.claude/projects/<repo>/memory/ per developer. Memories are scoped to one machine, one user.

The taxonomy already distinguishes types (user / feedback / project / reference) but doesn't route between personal-only and team-shared. So Claude saves:

• user memories — correctly personal (e.g., "user is a backend engineer")
• feedback memories — sometimes personal ("user prefers terse responses"), sometimes universal ("plugin files must be self-contained at runtime — applies to anyone authoring plugins")
• project memories — sometimes personal ("I'm working on issue #123"), sometimes team-shared ("merge freeze starts 2026-03-05")
• reference memories — usually universal ("ADO bugs tracked in Linear project INGEST")

Universal items end up in personal memory and never propagate.

Real example: my own memory directory

Three feedback entries currently in ~/.claude/projects/C--Users-tzander-Documents-repos-claude/memory/:

Memory file	Content	Where it should live
feedback_tool_preferences.md	Prefer core tools over permission-gated tools	Already in standards/CLAUDE.md — duplicate
feedback_plugin_script_preference.md	Plugin commands should call scripts, not inline markdown logic	In this repo's CLAUDE.md — but only loads in this repo
feedback_plugins_must_be_self_contained.md	Plugin files must not reference this repo's standards	In this repo's CLAUDE.md — same scope problem

All three are universal guidance for anyone authoring Claude plugins, but each new contributor will re-learn them from scratch unless they happen to be in this repo at the time. Two are duplicated between memory and CLAUDE.md (which is its own maintenance problem); one is silently personal-only.

Other examples from recent sessions that should end up shared

• "Running bash setup-env.sh from PowerShell can route to WSL bash and write standards to the wrong filesystem — use setup-env.ps1 instead." (Discovered today; currently in nobody's standards.)
• "ADO MCP requires repo GUID, not name, for PR creation." (Eventually promoted, but only after one developer hit it.)
• "Heredoc with single-quoted 'ENDOFBODY' delimiter avoids permission prompts when piping markdown to gh issue create." (Eventually promoted.)

The pattern: lessons get learned by one developer, sit in personal memory, then get promoted manually weeks or months later — sometimes only after a second developer trips on the same thing.

Proposed Solution

Four options ordered roughly lightest to heaviest. Probably want some combination, not just one.

1. Update auto-memory rules to route by scope (lightest)

Extend the auto-memory section in standards/CLAUDE.md (synced into every developer's ~/.claude/CLAUDE.md) with explicit routing guidance:

• Before saving a feedback or reference memory, ask: would this apply to anyone working on this codebase, or only me?
• If team-applicable: don't save to personal memory — propose adding to standards/CLAUDE.md (or the appropriate project CLAUDE.md) via a PR instead.
• Default route: personal memory for user type and personal feedback; shared standards for universal feedback and reference.

This addresses the root cause (Claude defaults to personal memory) without new tooling.

2. /promote-memory skill

A skill that reviews a developer's personal memory directory, flags entries that look team-applicable under the routing rule from option 1, and drafts a PR adding the relevant entries to standards/CLAUDE.md. Could share an integration point with /self-review (which already surfaces session learnings).

Catches what slips through option 1 — an explicit periodic sweep rather than relying on per-decision routing.

3. Drift-detection scheduled agent

Recurring agent (depends on GH #127) that reads each developer's memory directory across the team and looks for memories appearing independently in multiple developers' files. That overlap is the strongest signal that the same gotcha got re-learned and should be promoted. Surfaces those as PR candidates.

Higher value than option 2 because the signal is empirical (multiple devs already hit it) rather than predictive ("this looks team-applicable").

4. Memory taxonomy expansion (probably not)

Add a new memory type that writes directly to standards/CLAUDE.md via PR instead of personal memory. Tempting but high blast radius — auto-PR-creation from a memory write is the kind of automation that gets you in trouble. Probably not the right answer; mentioned to rule out.

Recommendation: Start with option 1 (rule update). Add option 2 as a follow-up after a few weeks to catch what slips through. Option 3 only if drift continues despite 1+2.

Acceptance Criteria

1. standards/CLAUDE.md includes a routing decision tree for the auto-memory system, concrete enough that two developers in similar situations would route the same way.
2. Existing personal memory entries on at least the issue author's machine are audited under the new rule — duplicates removed, team-applicable ones promoted to standards.
3. The decision tree distinguishes:
   • Repo-scoped team knowledge (goes in this repo's CLAUDE.md)
   • Cross-repo team standards (goes in standards/CLAUDE.md)
   • Truly personal preferences (stays in memory)
4. At least one new team member onboards a Claude session after the change and verifies they receive guidance the issue author had in personal memory before this work.
5. Memories duplicated between personal storage and standards are deduplicated as part of this work.

Open Questions

• Should there be a lightweight "staging area" for memories that aren't ready for full standards promotion yet — e.g., a notes/recent-learnings.md in the repo that's between personal memory and formal standards?
• How do we handle memory decay? Promoting from personal memory to standards centralizes the source but doesn't fix the staleness problem; just makes everyone stale together. Probably orthogonal — file separately if it matters.
• For repos with both internal team members and external contributors, how do we keep contributor-specific memories out of team standards? (Internal only, probably not an issue today.)
• Does this routing rule belong in standards/CLAUDE.md (where every dev's Claude reads it) or in a Claude Code-managed default? The former is reachable today; the latter would need product input from Anthropic.

Related

• self-review skill — already synthesizes session learnings; natural integration point for option 2.
• #127 — scheduling research; option 3 depends on it.
• standards/CLAUDE.md "Auto Memory" section — the destination for the routing rule.

Start with the Auto Memory section in standards/CLAUDE.md, then inspect the issue author's ~/.claude/projects/.../memory/ entries and the self-review skill. Define the routing guidance and determine how the listed memories should be audited and deduplicated. Done means the decision tree covers repo-scoped, cross-repo, and personal knowledge, with the stated onboarding verification completed.