Memory architecture

Memory Architecture

Worclaude projects use five distinct memory layers. Each has a different scope, owner, and lifecycle. Routing a fact to the correct layer is a load-bearing decision — the wrong layer means the fact is invisible when needed, or noisy when not.

The Five Layers

Layer	Scope	Owner	Lifecycle
CLAUDE.md	Team	Manual (humans + Claude via /update-claude-md)	Stable, lean (target ~200 lines)
.claude/rules/	Team	Manual, topic-organized	Stable; optionally path-scoped (deferred — see BACKLOG)
.claude/learnings/	Team	Hook-captured (learn-capture.cjs)	Append-only; transient inputs to promotion
CLAUDE.local.md	Personal	Manual; gitignored	Per-machine sandbox; never shared
Claude Code auto memory	Personal	Autonomous (Claude)	Active, self-pruning

The line between team and personal is the most important boundary. Team layers are committed and shared with collaborators; personal layers stay on the local machine.

Routing Contract

When a fact, rule, or pattern surfaces during a session, route it like this:

Source	Destination
A team-relevant rule the user wants enforced — typed [LEARN] block or /learn invocation	.claude/learnings/<category>.md (via hook)
A personal preference (workflow, tone, naming whim)	Claude Code auto memory (Claude does this autonomously when noticed)
A machine-local sandbox value (paths, secrets, dev URLs)	CLAUDE.local.md (manual; gitignored)
A topic that has accreted multiple learnings AND is stable	Promote to CLAUDE.md via /update-claude-md

Default rule: if you cannot point to a specific reason a fact belongs in a different layer, it does not belong in CLAUDE.md. CLAUDE.md is the last layer to grow, not the first.

Layer Interactions

• CLAUDE.md is the read-on-every-session layer. It is loaded into context at session start and after every /compact. Long files waste context on every interaction. Stay under ~200 lines of actual content.
• .claude/learnings/ is the staging area. Hooks write here on every [LEARN] block. Same category = same file = appended block, so a file that grows multiple **Rule:** entries signals recurrence. The index.json created field is updated to the latest capture date — use it as a "last touched" timestamp, not a fixed creation date.
• Auto memory runs in parallel. Claude Code maintains ~/.claude/projects/<project-slug>/memory/ autonomously. It is per-machine and personal. Worclaude does not write to it and does not read from it during /update-claude-md promotion (deliberate scope boundary — see BACKLOG for the discussion).
• CLAUDE.local.md overrides CLAUDE.md for the local machine. Use it for facts that are genuinely user-specific within an otherwise shared project. Do not commit it.
• .claude/rules/ is reserved. Claude Code's official docs recommend it for topic-organized, optionally path-scoped team rules. Worclaude defers scaffolding it until a usage signal exists; users can still create the folder manually. Do not duplicate CLAUDE.md content into .claude/rules/ ad-hoc.

Promotion Path: Learnings → CLAUDE.md

Promotion is the bridge from .claude/learnings/ to CLAUDE.md. It is deliberately gated by /update-claude-md rather than automatic — promotion is a content decision, not a mechanical one.

A learning is a promotion candidate when at least one of these holds:

1. Recurrence: the learning's file in .claude/learnings/ has 3 or more **Rule:** blocks (i.e., the same category was captured at least three times). Counted by scanning the file, not the index.
2. Recency cluster: the index entry's created date is within the last 14 days AND the same theme has shown up in another recent learning. Recent + repeated > recent alone.
3. Drift: the learning's content is structurally relevant to an existing CLAUDE.md section (e.g., a new "always do X" pattern that would naturally live in ## Critical Rules or ## Gotchas) but the pattern is missing from the file.

Even when a candidate qualifies, /update-claude-md confirms each proposed addition with the user via AskUserQuestion. No silent writes.

Don't / Do

• Don't edit .claude/learnings/ files by hand to "fix" them. They are the raw capture surface. If a learning is wrong, fix the rule in CLAUDE.md or remove the learning file.
• Don't scaffold .claude/rules/ content from old CLAUDE.md sections "to make CLAUDE.md smaller." Splitting into sub-files just fragments the single source of truth without saving context.
• Don't mix personal preferences into team layers. If something applies only to your local workflow, it belongs in CLAUDE.local.md or Claude Code's auto memory — not in CLAUDE.md.
• Do delete stale learnings. If a category was captured once eight months ago and never recurred, it is noise.
• Do prune CLAUDE.md when it crosses 200 lines. worclaude doctor warns at 150 and errors at 200. Pruning is part of maintenance.
• Do read the file before recommending an update. Memory across sessions is not authoritative — current file content is.

Cross-References

• /learn — captures a [LEARN] block to .claude/learnings/.
• /update-claude-md — proposes promotions from learnings to CLAUDE.md, with size + dedup gates.
• claude-md-maintenance skill — what belongs in CLAUDE.md, format discipline, the 200-line target.
• worclaude doctor — surfaces drift between CLAUDE.md claims and package.json reality (see Phase 3 T3.8).