memory-management

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

<vault> (Obsidian vault — path from Workflow Config)
  memory/
    AGENTS.md                    ← Compiled hot cache (regenerated by update)
    glossary.md                  ← Full decoder ring
    context/
      company.md                 ← Tools, teams, processes
  people/                        ← People profiles
  efforts/                       ← Projects / multi-step initiatives
  decisions/                     ← Architecture Decision Records
  log/
    daily/                       ← Daily notes (## Open / ## Plan / ## Capture)
    cycles/                      ← Linear cycle/sprint notes
  comms/                         ← Meeting notes, draft communications
  +/                             ← Inbox / unorganized notes

memory/AGENTS.md (Hot Cache):

• Compiled summary of the vault, optimized for agent token efficiency
• Top ~30 people you interact with most
• ~30 most common acronyms/terms
• Active efforts (5-15)
• Your preferences and workflow conventions
• Regenerated by workflow skills — never hand-edited
• Goal: Cover 90% of daily decoding needs in a single file read

Obsidian vault — memory/glossary.md (Full Glossary):

• Complete decoder ring - everyone, every term
• Searched when something isn't in AGENTS.md
• Can grow indefinitely

Obsidian vault — people/, efforts/, memory/context/:

• Rich detail when needed for execution
• Full profiles, history, context
• Accessed via the Obsidian MCP (search_notes, read_note, write_note, patch_note)

Lookup Flow

User: "ask todd about the PSR for phoenix"

1. Check memory/AGENTS.md (hot cache — single MCP read)
   → Todd? ✓ Todd Martinez, Finance
   → PSR? ✓ Pipeline Status Report
   → Phoenix? ✓ DB migration project

2. If not found → search Obsidian vault via MCP
   → search_notes for the term
   → read memory/glossary.md for full glossary
   → read people/{name}.md for people detail

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

This tiered approach keeps AGENTS.md lean (~100 lines) while supporting unlimited scale in the vault.

File Locations

Everything lives in the Obsidian vault (accessed via Obsidian MCP):

• Hot cache: memory/AGENTS.md (compiled by workflow skills)
• Glossary: memory/glossary.md
• Company context: memory/context/company.md
• People: people/{name}.md
• Efforts/projects: efforts/{name}.md

Hot Cache Format (memory/AGENTS.md)

Regenerated by workflow skills. Use tables for compactness. Target ~50-100 lines.

# Agent Context

> Auto-generated. Do not edit manually.
> Source of truth: the rest of this Obsidian vault.
> Last updated: YYYY-MM-DD

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

## People
| Who | Role |
|-----|------|
| **Todd** | Todd Martinez, Finance lead |
| **Sarah** | Sarah Chen, Engineering (Platform) |
| **Greg** | Greg Wilson, Sales |
→ Full list: people/ and memory/glossary.md

## Terms
| Term | Meaning |
|------|---------|
| PSR | Pipeline Status Report |
| P0 | Drop everything priority |
→ Full glossary: memory/glossary.md

## Active Efforts
| Name | What |
|------|------|
| **Phoenix** | DB migration, Q2 launch |
| **Horizon** | Mobile app redesign |
→ Details: efforts/

## Preferences
- Personal notes in Obsidian vault (path from Workflow Config)
- Efforts, daily notes, cycle notes all go there
- "Effort" = a multi-step task/initiative tracked in efforts/
- Daily notes use ## Plan (intended work) and ## Capture (incoming tasks)
- Cycle notes track personal notes per Linear sprint in log/cycles/
- Decisions tracked as lightweight ADRs in decisions/

Deep Memory Format (Obsidian vault)

memory/glossary.md - The decoder ring:

# Glossary

Workplace shorthand, acronyms, and internal language.

## Acronyms
| Term | Meaning | Context |
|------|---------|---------|
| PSR | Pipeline Status Report | Weekly sales doc |
| OKR | Objectives & Key Results | Quarterly planning |
| P0/P1/P2 | Priority levels | P0 = drop everything |

## Internal Terms
| Term | Meaning |
|------|---------|
| the migration | Project Phoenix database work |
| ship it | Deploy to production |
| escalate | Loop in leadership |

## Nicknames → Full Names
| Nickname | Person |
|----------|--------|
| Todd | Todd Martinez (Finance) |
| T | Also Todd Martinez |

## Project Codenames
| Codename | Project |
|----------|---------|
| Phoenix | Database migration |
| Horizon | New mobile app |

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

efforts/{name}.md — see task-management skill for effort conventions (datestamp-slug naming, folder refactoring, etc.)

memory/context/company.md:

# Company Context

## Tools & Systems
| Tool | Used for | Internal name |
|------|----------|---------------|
| Slack | Communication | - |
| Linear | Project tracking, engineering tasks, and project docs | - |
| Notion | Long-term documentation, non-project notes, wiki | - |
| Google Docs | Incoming work, external-facing docs | - |
| GitHub | Source control ({github_org}) | - |
| Gmail | Email | - |
| Google Calendar | Calendar | "gcal" |
| Figma | Design | - |

## Teams
| Team | What they do | Key people |
|------|--------------|------------|

## Processes
| Process | What it means |
|---------|---------------|

How to Interact

Decoding User Input (Tiered Lookup)

Always decode shorthand before acting on requests:

1. memory/AGENTS.md (hot cache)      → Single read, covers 90% of cases
2. Obsidian: memory/glossary.md      → Full glossary if not in hot cache
3. Obsidian: people/, efforts/       → Rich detail when needed
4. Obsidian: search_notes            → Broad search across the vault
5. Ask user                          → Unknown term? Learn it.

Example:

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

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

Obsidian lookup (via MCP):
  read_note("memory/glossary") → "oracle" → Oracle Systems deal ($2.3M) ✓

Now Claude can act with full context.

Adding Memory

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

1. Glossary items (acronyms, terms, shorthand):

   • Add to Obsidian memory/glossary.md via patch_note
   • AGENTS.md will pick it up on next update if frequently used

2. People:

   • Create/update Obsidian people/{name}.md via write_note or patch_note
   • Capture nicknames - critical for decoding

3. Efforts/projects:

   • Create/update Obsidian efforts/{name}.md via write_note or patch_note
   • Capture codenames - "Phoenix", "the migration", etc.

4. Preferences: Add to Obsidian memory/context/company.md or relevant file

5. Notes, efforts, daily/cycle logs:

   • These live in the Obsidian vault
   • Efforts: efforts/, Daily: log/daily/, Cycles: log/cycles/, Comms: comms/
   • See the task-management skill for the full directory layout and daily note structure

Recalling Memory

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

1. Check memory/AGENTS.md first
2. Search Obsidian vault via MCP (search_notes, then read_note for detail)
3. If not found: "I don't know what X means yet. Can you tell me?"

Progressive Disclosure

1. Load memory/AGENTS.md for quick parsing of any request
2. Dive into Obsidian vault via MCP when you need full context for execution
3. Example: drafting an email to todd about the PSR
   • AGENTS.md tells you Todd = Todd Martinez, PSR = Pipeline Status Report
   • Obsidian people/todd-martinez.md tells you he prefers Slack, is direct

Bootstrapping (First Run)

If memory/AGENTS.md doesn't exist in the vault (or memory/glossary.md is missing), the memory system needs bootstrapping. Direct the user to run /productivity:bootstrap, which does a comprehensive scan of all connected sources (Linear, Slack, Gmail, Calendar, Notion, existing vault content) to build the initial memory.

Conventions

• Bold terms in AGENTS.md for scannability
• Keep AGENTS.md under ~100 lines (the "hot 30" rule)
• Filenames in Obsidian: lowercase, hyphens (todd-martinez.md, project-phoenix.md)
• Always capture nicknames and alternate names
• Glossary tables for easy lookup
• AGENTS.md is regenerated by workflow skills — source of truth is the vault itself

What Goes Where

Type	AGENTS.md (Hot Cache)	Obsidian Vault (Full Storage)
Person	Top ~30 frequent contacts	glossary.md + people/{name}.md
Acronym/term	~30 most common	memory/glossary.md (complete list)
Effort/project	Active efforts only	memory/glossary.md + efforts/{name}.md
Nickname	In People if top 30	memory/glossary.md (all nicknames)
Company context	Quick reference only	memory/context/company.md
Preferences	Key preferences	memory/context/company.md
Historical/stale	Not included	Stays in Obsidian

Promotion / Demotion

AGENTS.md is compiled — promotion and demotion happen automatically when workflow skills regenerate it:

Included in AGENTS.md when:

• Term/person appears frequently in recent daily notes
• Effort has status: active
• Part of current Linear cycle work

Excluded from AGENTS.md when:

• Effort completed or stale
• Person not mentioned recently
• Term rarely used in recent notes

Excluded items remain accessible in the vault. Workflow skills handle this automatically.