memory-management

Files (2)

• SKILL.md
• templates.md · references/

SKILL.md (first lines)

# Memory Management

Memory makes Codex your household collaborator - someone who speaks your family's internal language.

## The Goal

Transform shorthand into understanding:

```
User: "check on the reno permits for maple"
              ↓ Codex decodes
"Check on building permits for the Maple Street property renovation
 (123 Maple St, contractor: Davis & Sons, target completion Q3)"
```

Without memory, that request is meaningless. With memory, Codex knows:
- **reno** → the renovation project
- **maple** → 123 Maple Street property
- **permits** → building permits submitted in January

## Architecture

```
AGENTS.md          ← Hot cache (~30 people/entities, common terms)
memory/
  glossary.md      ← Full decoder ring (everything)
  people/          ← Complete profiles
  projects/        ← Project details
  context/         ← Household, services, tools
```

**AGENTS.md (Hot Cache):**
- Top ~30 people you interact with most (family, advisors, vendors, service providers)
- ~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 AGENTS.md
- Can grow indefinitely

**memory/people/, projects/, context/:**
- Rich detail when needed for execution
- Full profiles, history, context

## Lookup Flow

```
User: "ask nita about the enrollment for greenwood"

1. Check AGENTS.md (hot cache)
   → Nita? ✓ Nita Patel, education consultant
   → enrollment? ✓ School enrollment process
   → Greenwood? ✓ Greenwood Academy application

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 AGENTS.md lean (~100 lines) while supporting unlimited scale in memory/.

## File Locations

- **Working memory:** `AGENTS.md` in current working directory
- **Deep memory:** `memory/` subdirectory

## Memory Format Templates

Use tables for compactness in AGENTS.md. Target ~50-80 lines for the hot cache.

For full templates with examples for each file type (AGENTS.md, glossary.md, people profiles, project profiles, household context), see [references/templates.md](references/templates.md).

Key file structure:
- **AGENTS.md**: Sections for Me, People (table), Terms (table), Projects (table), Preferences (bullets)
- **memory/glossary.md**: Acronyms, internal terms, nicknames, project codenames — all as tables
- **memory/people/{name}.md**: Also-known-as, role, communication prefs, context, notes
- **memory/projects/{name}.md**: Codename, status, description, key people, context
- **memory/context/household.md**: Tools/systems, service providers, recurring processes

## How to Interact

### Decoding User Input (Tiered Lookup)

**Always** decode shorthand before acting on requests:

```
1. AGENTS.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 jim about the trust amendment for maple"

AGENTS.md lookup:
  "jim" → Jim Davis, estate attorney ✓
  "trust amendment" → (not in hot cache)
  "maple" → Maple Street property ✓

memory/glossary.md lookup:
  "trust amendment" → property trust restructuring doc ✓

Now Codex can act with full context.
```

### Adding Memory

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

1. **Glossary items** (acronyms, terms, shorthand):
   - Add to memory/glossary.md
   - If frequently used, add to AGENTS.md Quick Glossary

From hvkshetry/StewardOS, MIT.

More from hvkshetry/StewardOS