From 42a02b9c0f33f6c8faf3a8d2e44aa3bc37636877 Mon Sep 17 00:00:00 2001
From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com>
Date: Sun, 21 Jun 2026 09:32:24 +0200
Subject: [PATCH] Add architecture rule: shared project memory must be in repo

---
 .../shared-project-memory-must-be-in-repo.md  | 76 +++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 custom/knowledge/architecture/shared-project-memory-must-be-in-repo.md

diff --git a/custom/knowledge/architecture/shared-project-memory-must-be-in-repo.md b/custom/knowledge/architecture/shared-project-memory-must-be-in-repo.md
new file mode 100644
index 0000000..da5b939
--- /dev/null
+++ b/custom/knowledge/architecture/shared-project-memory-must-be-in-repo.md
@@ -0,0 +1,76 @@
+---
+name: shared-project-memory-must-be-in-repo
+description: >
+  Project-level memory (business rules, architectural decisions, scope boundaries)
+  must be stored in a version-controlled projectmemory/ folder, not in a user's
+  local Claude memory store, so all team members benefit from shared knowledge.
+layer: 2
+category: architecture
+---
+
+# Shared Project Memory Must Be in the Repository
+
+## Description
+
+When Claude learns something relevant to the project — a business rule, an architectural
+decision, a known limitation, a scope boundary — that knowledge must be written to the
+repository's `projectmemory/` folder, not to the local user memory store
+(`~/.claude/projects/.../memory/`).
+
+Local memory is invisible to other team members and disappears when someone works on
+a different machine. Version-controlled memory is shared, attributed, and persistent.
+
+## Anti Pattern
+
+```
+# Stored only on Michael's laptop — Tod and SJG never see this
+~/.claude/projects/d--MyProject/memory/project-pricing-vat-scope.md
+```
+
+A rule observed by one developer stays siloed. The next session on another machine —
+or by another team member — starts from zero.
+
+## Best Practice
+
+```
+# In the git repository — committed, shared, visible to all
+projectmemory/
+  memoryupdates_mid.md   ← Michael's observations
+  memoryupdates_tod.md   ← Tod's observations
+  memoryupdates_sjg.md   ← SJG's observations
+```
+
+Each file is named after the user who triggered the observation. All files are read
+by every team member's Claude session at start, via an instruction in `CLAUDE.md`:
+
+```markdown
+## Shared project memory
+
+At session start, read **all files** in `projectmemory/` — they contain shared
+project observations from all team members and are version-controlled in git.
+
+When you learn something project-relevant, write it to
+`projectmemory/memoryupdates_<username>.md` for the active user.
+
+User-specific preferences (tone, workflow habits) stay in the local
+`~/.claude/projects/.../memory/` folder as before.
+```
+
+## What belongs in projectmemory vs local memory
+
+| projectmemory/ (shared, in git) | local memory (personal, not shared) |
+|---|---|
+| Business rules ("B2B only, no VAT") | User's preferred communication language |
+| Architectural decisions and rationale | Workflow habits and preferences |
+| Scope boundaries ("IC via ChangeCompany only") | Personal shortcuts or shortcuts |
+| Known technical debt and migration status | Role and seniority (already known by the team) |
+| Test coverage scope | |
+| Company/entity structure | |
+
+## Implementation checklist
+
+- [ ] Create `projectmemory/` folder in repo root
+- [ ] Add `projectmemory/**` to `cspell.json` ignorePaths (notes are often in the team's native language)
+- [ ] Add the read-at-session-start instruction to `CLAUDE.md`
+- [ ] When learning something project-relevant, write to `projectmemory/memoryupdates_<username>.md`
+- [ ] Commit and push — knowledge is only shared once it is in git