Memory Management

Memory makes Claude your workplace collaborator - someone who speaks your internal language.

The Goal

Transform shorthand into understanding:

User: "ask todd to do the PSR for oracle" ↓ Claude decodes "Ask Todd Martinez (Finance lead) to prepare the Pipeline Status Report for the Oracle Systems deal ($2.3M, closing Q2)"

Without memory, that request is meaningless. With memory, Claude knows:

• todd → Todd Martinez, Finance lead, prefers Slack

• PSR → Pipeline Status Report (weekly sales doc)

• oracle → Oracle Systems deal, not the company

Architecture

CLAUDE.md ← Hot cache (~30 people, common terms) memory/ glossary.md ← Full decoder ring (everything) people/ ← Complete profiles projects/ ← Project details context/ ← Company, teams, tools

CLAUDE.md (Hot Cache):

• Top ~30 people you interact with most

• ~30 most common acronyms/terms

• Active projects (5-15)

• Your preferences

• Goal: Cover 90% of daily decoding needs

memory/glossary.md (Full Glossary):

• Complete decoder ring - everyone, every term

• Searched when something isn't in CLAUDE.md

• Can grow indefinitely

memory/people/, projects/, context/:

• Rich detail when needed for execution

• Full profiles, history, context

Lookup Flow

User: "ask todd about the PSR for phoenix"

1. Check CLAUDE.md (hot cache) → Todd? ✓ Todd Martinez, Finance → PSR? ✓ Pipeline Status Report → Phoenix? ✓ DB migration project

2. If not found → search memory/glossary.md → Full glossary has everyone/everything

3. If still not found → ask user → "What does X mean? I'll remember it."

This tiered approach keeps CLAUDE.md lean (~100 lines) while supporting unlimited scale in memory/.

File Locations

• Working memory: CLAUDE.md in current working directory

• Deep memory: memory/ subdirectory

Working Memory Format (CLAUDE.md)

Use tables for compactness. Target ~50-80 lines total.

Memory

Me

[Name], [Role] on [Team]. [One sentence about what I do.]

People

Terms

Projects

Preferences

• 25-min meetings with buffers
• Async-first, Slack over email
• No meetings Friday afternoons

Deep Memory Format (memory/)

memory/glossary.md - The decoder ring:

Glossary

Workplace shorthand, acronyms, and internal language.

Acronyms

Internal Terms

Nicknames → Full Names

Project Codenames

memory/people/{name}.md:

Todd Martinez

Also known as: Todd, T Role: Finance Lead Team: Finance Reports to: CFO (Michael Chen)

Communication

• Prefers Slack DM
• Quick responses, very direct
• Best time: mornings

Context

• Handles all PSRs and financial reporting
• Key contact for deal approvals over $500k
• Works closely with Sales on forecasting

Notes

• Cubs fan, likes talking baseball

memory/projects/{name}.md:

Project Phoenix

Codename: Phoenix Also called: "the migration" Status: Active, launching Q2

What It Is

Database migration from legacy Oracle to PostgreSQL.

Key People

• Sarah - tech lead
• Todd - budget owner
• Greg - stakeholder (sales impact)

Context

$1.2M budget, 6-month timeline. Critical path for Horizon project.

memory/context/company.md:

Company Context

Tools & Systems

Teams

Processes

How to Interact

Decoding User Input (Tiered Lookup)

Always decode shorthand before acting on requests:

1. CLAUDE.md (hot cache) → Check first, covers 90% of cases
2. memory/glossary.md → Full glossary if not in hot cache
3. memory/people/, projects/ → Rich detail when needed
4. Ask user → Unknown term? Learn it.

Example:

User: "ask todd to do the PSR for oracle"

CLAUDE.md lookup: "todd" → Todd Martinez, Finance ✓ "PSR" → Pipeline Status Report ✓ "oracle" → (not in hot cache)

memory/glossary.md lookup: "oracle" → Oracle Systems deal ($2.3M) ✓

Now Claude can act with full context.

Adding Memory

When user says "remember this" or "X means Y":

Glossary items (acronyms, terms, shorthand):

• Add to memory/glossary.md

• If frequently used, add to CLAUDE.md Quick Glossary

People:

• Create/update memory/people/{name}.md

• Add to CLAUDE.md Key People if important

• Capture nicknames - critical for decoding

Projects:

• Create/update memory/projects/{name}.md

• Add to CLAUDE.md Active Projects if current

• Capture codenames - "Phoenix", "the migration", etc.

Preferences: Add to CLAUDE.md Preferences section

Recalling Memory

When user asks "who is X" or "what does X mean":

• Check CLAUDE.md first

• Check memory/ for full detail

• If not found: "I don't know what X means yet. Can you tell me?"

Progressive Disclosure

• Load CLAUDE.md for quick parsing of any request

• Dive into memory/ when you need full context for execution

• Example: drafting an email to todd about the PSR

• CLAUDE.md tells you Todd = Todd Martinez, PSR = Pipeline Status Report

• memory/people/todd-martinez.md tells you he prefers Slack, is direct

Bootstrapping

Use /productivity:start to initialize by scanning your chat, calendar, email, and documents. Extracts people, projects, and starts building the glossary.

Conventions

• Bold terms in CLAUDE.md for scannability

• Keep CLAUDE.md under ~100 lines (the "hot 30" rule)

• Filenames: lowercase, hyphens (todd-martinez.md , project-phoenix.md )

• Always capture nicknames and alternate names

• Glossary tables for easy lookup

• When something's used frequently, promote it to CLAUDE.md

• When something goes stale, demote it to memory/ only

What Goes Where

Type CLAUDE.md (Hot Cache) memory/ (Full Storage)

Person Top ~30 frequent contacts glossary.md + people/{name}.md

Acronym/term ~30 most common glossary.md (complete list)

Project Active projects only glossary.md + projects/{name}.md

Nickname In Key People if top 30 glossary.md (all nicknames)

Company context Quick reference only context/company.md

Preferences All preferences

Historical/stale ✗ Remove ✓ Keep in memory/

Promotion / Demotion

Promote to CLAUDE.md when:

• You use a term/person frequently

• It's part of active work

Demote to memory/ only when:

• Project completed

• Person no longer frequent contact

• Term rarely used

This keeps CLAUDE.md fresh and relevant.