Architecture Decision Record · 0006

Agent Memory: geteilt im Repo, nicht in den User-Pfad symlinken

TL;DR — Team-relevante Agent-Memos werden unter .claude/memory/ git-getrackt; der User-Pfad (~/.claude/projects/…/memory/) bleibt isoliert. Synchronisation ist manuell und gerichtet — Reibung ist der Review-Punkt.

Kontext

Claude Code unterhält ein file-basiertes Memory-System mit User-, Feedback-, Project- und Reference-Memos. Memory persistiert zwischen Sessions in einem deterministischen Pfad pro User und Repo: ~/.claude/projects/<encoded-cwd>/memory/. Pfad-Encoding tauscht Slashes durch Dashes — für /Users/x/Sites/solcom ergibt sich ~/.claude/projects/-Users-x-Sites-solcom/memory/.

Inhaltlich enthält Memory in diesem Repo zwei Klassen von Memos:

Team-relevant: Architektur-Patterns, Code-Konventionen aus PR-Reviews, Domain-Wissen über das SOLCOM-Theme und seine Stakeholder, Scope-Reduktionen wie der Card-Familie-Slim-Down.
Persönlich: Workflow-Präferenzen einzelner Entwickler:innen, IDE-spezifische Memos, situatives Korrektiv-Feedback an die jeweilige Session.

Ohne weitere Maßnahmen divergieren beide Klassen pro User-Maschine — neue Devs im Team starten ohne Zugriff auf die Team-relevanten Memos. Drei Constraints:

Claude-Code-Pfad ist hardcoded und macht keine Repo-relative Resolution.
Memos der „persönlichen" Klasse dürfen nicht ins Repo wandern.
Setup-Friktion für neue Devs muss niedrig bleiben.

Entscheidung

Team-Memory wird im Repo unter .claude/memory/ git-tracked. Der globale Claude-Code-Memory-Pfad pro User bleibt eigenständig, ohne Symlink-Kopplung zum Repo. Konkret:

.claude/memory/ ist tracked und enthält Team-relevante Memos: Architektur-Patterns, Konventionen aus Reviews, Scope-Entscheidungen, Onboarding-Hilfen.
~/.claude/projects/<encoded-cwd>/memory/ bleibt pro User isoliert — dort schreibt Claude Code seine Live-Memos zur jeweiligen Session, dort landen auch persönliche Memos.
Synchronisation zwischen beiden Orten ist manuell und gerichtet: Wenn ein Memo team-relevant wird, übernimmt der Author die Datei bewusst in .claude/memory/ und reviewt sie dabei. Repo-Memo entsteht erst durch explizite Kuration.
.gitignore ignoriert spezifische Anthropic-Tooling-State-Files (/.claude/scheduled_tasks.lock), damit nur die kuratierten Memo-Files im .claude/memory/-Tree und die geteilten Subagent-Definitionen in .claude/agents/ ins Repo wandern.
docs/agents/memory.md dokumentiert den Workflow für Entwickler:innen.

★

Onboarding: git clone + übliches Drupal-Setup — keine Symlink-Operation, keine zusätzliche Pfad-Konfiguration. Team-Memory ist sofort verfügbar über .claude/memory/.

Rejected alternatives

Symlink: globaler User-Pfad → <repo>/.claude/memory/ rejected

Technisch der einzige Weg, Repo-Memory live an Claude Code zu hängen. Verworfen, weil das die Persönlich/Team-Trennung kollabiert: persönliche Korrektiv-Memos einer Session würden ins Repo geschrieben, ohne dass der User sie reviewen kann. Außerdem unnötige Pro-Maschine-Setup-Reibung.

Repo-only Memory (kein User-Pfad, alle Memos ins Repo) rejected

Würde die zwei Klassen vermischen — persönliche Korrekturen aus Session-Verläufen wären sofort im git-Diff sichtbar. Außerdem inkompatibel mit dem Claude-Code-System, das hardcoded den User-Pfad nutzt.

Per-User-Branch im Repo (z. B. agent-memory/marc) rejected

Würde Personal-Memos versionieren, die das nicht brauchen, und blast-radius-mäßig den Repo mit User-Branches überfluten. Zusätzlich Git-Reibung (Branch-Pflege, Merge-Konflikte beim Update von MEMORY.md-Index).

Setup-Skript bin/setup-claude-memory.sh mit Symlink-Logik plus Backup rejected

Reduziert die Setup-Reibung gegenüber dem Symlink-Snippet, ändert aber nichts am fundamentalen Problem: Persönlich/Team verschmelzen, sobald der Symlink steht.

Drupal-Modul oder Hook, das Memory-Files aus dem Repo in den User-Pfad kopiert rejected

Bringt Drupal als Synchronisations-Mechanismus in einen Tooling-Kontext, der nichts mit Drupal zu tun hat — Coupling-Smell. Außerdem kein Zwei-Wege-Sync.

In CLAUDE.md anweisen, alle Schreibaktionen ins Repo statt in den User-Pfad zu lenken rejected

Scheitert: (a) Claude-Code-Behaviors-Pfad ist nicht durch CLAUDE.md änderbar; (b) selbst wenn es ginge, würde es den persönlichen Memo-Schutz aushebeln.

Consequences

Team-Wissen wird redundant gepflegt. Wenn ein Memo team-relevant ist, schreibt der Author es in beide Orte (sein User-Pfad für die Live-Session, plus Repo für das Team) oder schreibt es nur ins Repo und referenziert es manuell. Das ist Reibung, aber bewusst — die Reibung ist der Review-Punkt.
Onboarding für neue Devs ist niedrig-friktion. git clone plus übliches Drupal-Setup — keine Symlink-Operation, keine zusätzliche Pfad-Konfiguration. Wer regelmäßig im Repo arbeitet, kann optional sein User-Memory mit relevanten Files seeden — das ist eine Per-Dev-Entscheidung.
Memos im Repo veralten ohne Live-Update. Da kein Symlink besteht, schreibt Claude beim Live-Workflow nur ins User-Memory. Mitigation: Memos referenzieren explizit den Code-Pfad, auf den sie sich beziehen, damit beim nächsten Code-Touch der Memo-Drift sichtbar wird.
Personal-Memo-Drift ist akzeptiert. Persönliche Memos können widersprüchlich zu Team-Repo-Memos sein — das ist ein Feature, kein Bug. Wenn der Widerspruch produktiv ist, zieht der Author den neuen Stand bewusst ins Repo nach.
.gitignore-Pflege bei neuen Anthropic-Tooling-State-Files. Aktuell ist /.claude/scheduled_tasks.lock ignoriert. Wenn Claude Code in zukünftigen Versionen weitere State-Files in .claude/ ablegt, müssen die einzeln in die .gitignore aufgenommen werden.
Sensitive-Content-Risiko bei Repo-Memos. Memos können versehentlich personenbezogene Inhalte enthalten, wenn der Author die Trennung übersieht. PR-Review ist die Defense — Memos landen genauso im Diff wie Code.
Customer-Lens-Reviewer-Trigger gilt nicht für Memos. Memo-Strukturentscheidungen sind Tooling-State, keine Komponenten-/Architekturentscheidung im Theme. ADR-0006 ist die kanonische Stelle für die Memo-Architektur.

FAQ

Wie kommt ein neuer Dev an die Team-Memos?: git clone genügt — .claude/memory/ ist im Repo. Kein zusätzliches Setup-Skript, kein Symlink nötig. Wer die Memos auch im Live-Memory-Pfad haben möchte, kopiert sie manuell nach ~/.claude/projects/-Users-<name>-Sites-solcom/memory/.
Was passiert, wenn Claude Code im Live-Workflow ein Memo überschreibt?: Nur der User-Pfad wird überschrieben — .claude/memory/ im Repo bleibt unberührt bis zu einem expliziten Commit. Kein automatischer Durchgriff in die andere Richtung.