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

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:

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