| name | memory-management |
| description | Two-tier memory that decodes shorthand, acronyms, nicknames, and internal language so the assistant understands requests like a colleague would. Activate when the user introduces a person, project, or term ("remember that", "X means Y", "who is Todd"), during /assistant:update or "/assistant:update memory", or when another skill surfaces a durable fact to save. AGENTS.md for working memory (CLAUDE.md → @AGENTS.md shim), memory/ for the full knowledge base. |
| user-invocable | false |
Memory management
Memory makes the assistant your workplace collaborator — someone who speaks your internal language.
The goal
Transform shorthand into understanding:
User: "ask todd to do the PSR for oracle"
↓ decode
"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, the assistant knows:
- todd → Todd Martinez, Finance lead, prefers Slack
- PSR → Pipeline Status Report (weekly sales doc)
- oracle → Oracle Systems deal, not the company
Three layers — don't mix them up
| Layer | File | What lives here |
|---|
| Profile | ~/MyAssistant/config/profile.md | Identity, voice, working rules, autonomy — written by /assistant:setup |
| Policies | ~/MyAssistant/policies/*.policy.md | VIP tiers, email/calendar rules — written by /assistant:setup |
| Working memory | AGENTS.md in the working folder | Hot cache: top people, terms, active projects (~50–80 lines) |
| Deep memory | memory/ in the working folder | Full glossary, people profiles, project detail, company context |
Read the profile first for who the user is and how they write. Use AGENTS.md + memory/ to decode shorthand and store workplace context. Never duplicate voice, VIP tiers, or full identity prose into AGENTS.md — link to config/profile.md instead.
In Cowork, the profile may live in a workspace folder the user has open; check there too.
Architecture
profile.md ← Who you are, how you write, your rules (/assistant:setup)
policies/ ← VIP tiers, email and calendar rules (/assistant:setup)
AGENTS.md ← Hot cache (~30 people, common terms)
CLAUDE.md ← @AGENTS.md shim (Claude Code / Cowork auto-load)
memory/
glossary.md ← Full decoder ring (everything)
people/ ← Complete profiles
projects/ ← Project details
context/ ← Company, teams, tools
AGENTS.md (hot cache):
- Top ~30 people you interact with most
- ~30 most common acronyms/terms
- Active projects (5–15)
- Work preferences not already in the profile
- 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 todd about the PSR for phoenix"
1. Check AGENTS.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 AGENTS.md lean (~100 lines) while supporting unlimited scale in memory/.
File locations
All memory files live in the working folder — the directory where TASKS.md, briefs, and drafts also live. Create memory/ and AGENTS.md (+ CLAUDE.md shim) if missing.
- Working memory:
AGENTS.md in the working folder
- Compat shim:
CLAUDE.md containing @AGENTS.md for Claude hosts
- Deep memory:
memory/ subdirectory
Visual editor: {assistantPath}/dashboard.html (copied at setup) or skills/dashboard.html in the plugin — Memory tab opens the working folder to browse and edit AGENTS.md and memory/ files.
Per rules/file-safety.md: the assistant may write to memory/ and AGENTS.md without asking; tell the user what was added or changed.
Working memory format (AGENTS.md)
Use tables for compactness. Target ~50–80 lines total. Do not repeat profile content (name, voice, VIP list).
# Memory
## People
| Who | Role |
|-----|------|
| **Todd** | Todd Martinez, Finance lead |
| **Sarah** | Sarah Chen, Engineering (Platform) |
| **Greg** | Greg Wilson, Sales |
→ Full list: memory/glossary.md, profiles: memory/people/
## Terms
| Term | Meaning |
|------|---------|
| PSR | Pipeline Status Report |
| P0 | Drop everything priority |
| standup | Daily 9am sync |
→ Full glossary: memory/glossary.md
## Projects
| Name | What |
|------|------|
| **Phoenix** | DB migration, Q2 launch |
| **Horizon** | Mobile app redesign |
→ Details: memory/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
| 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 |
|------|---------|
| standup | Daily 9am sync in #engineering |
| 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 |
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
| Tool | Used for | Internal name |
|------|----------|---------------|
| Slack | Communication | - |
| Asana | Engineering tasks | - |
| Salesforce | CRM | "SF" or "the CRM" |
| Notion | Docs/wiki | - |
## Teams
| Team | What they do | Key people |
|------|--------------|------------|
| Platform | Infrastructure | Sarah (lead) |
| Finance | Money stuff | Todd (lead) |
| Sales | Revenue | Greg |
## Processes
| Process | What it means |
|---------|---------------|
| Weekly sync | Monday 10am all-hands |
| Ship review | Thursday deploy approval |
How to interact
Decoding user input (tiered lookup)
Always decode shorthand before acting on requests:
1. profile.md + policies/ → Identity, VIP tiers (for prioritisation)
2. AGENTS.md (hot cache) → Check first, covers 90% of cases
3. memory/glossary.md → Full glossary if not in hot cache
4. memory/people/, projects/ → Rich detail when needed
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)
memory/glossary.md lookup:
"oracle" → Oracle Systems deal ($2.3M) ✓
Now the assistant can act with full context.
Adding memory
When the user says "remember this", "X means Y", or introduces a person/project:
-
Glossary items (acronyms, terms, shorthand):
- Add to
memory/glossary.md
- If frequently used, add to
AGENTS.md Terms table
-
People:
- Create/update
memory/people/{name}.md
- Add to
AGENTS.md People table if important
- Capture nicknames — critical for decoding
- If they're a VIP or key person, propose a profile update (show diff, ask first)
-
Projects:
- Create/update
memory/projects/{name}.md
- Add to
AGENTS.md Projects table if current
- Capture codenames — "Phoenix", "the migration", etc.
-
Work preferences: add to AGENTS.md Preferences (not the profile unless it's a durable policy change)
Tell the user what was saved. Never store passwords, PINs, 2FA codes, or full account numbers.
Recalling memory
When the user asks "who is X" or "what does X mean":
- Check
AGENTS.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
AGENTS.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
AGENTS.md tells you Todd = Todd Martinez, PSR = Pipeline Status Reportmemory/people/todd-martinez.md tells you he prefers Slack, is direct
Decode checklist (update / review)
When decoding tasks during /assistant:update, /assistant:tasks review, or bootstrap, show per-task entity resolution:
Task: "Send PSR to Todd re: Phoenix blockers"
Decode:
- PSR → ✓ Pipeline Status Report (glossary)
- Todd → ✓ Todd Martinez (people/)
- Phoenix → ? Not in memory
Track what's fully decoded vs. gaps. Present unknowns grouped:
I found terms in your tasks I don't have context for:
1. "Phoenix" (from: "Send PSR to Todd re: Phoenix blockers")
→ What's Phoenix?
2. "Maya" (from: "sync with Maya on API design")
→ Who is Maya?
Add confirmed answers to AGENTS.md, memory/glossary.md, and memory/people/ or memory/projects/ as appropriate.
Task enrichment
Tasks often contain richer context than memory. During /assistant:update (default) and /assistant:tasks review, extract and propose updates:
- Links from tasks → add to project/people files
- Status changes ("launch done", moved to Done) → update project status; demote from
AGENTS.md Projects if complete
- Relationships ("Todd's sign-off on Maya's proposal") → cross-reference people files
- Deadlines → add to project files
Never auto-write enrichment — confirm each change with the user.
Confidence-tiered proposals
When bootstrap or --all scans surface new people, projects, or terms, group by confidence:
| Tier | Action |
|---|
| Ready to add | High confidence (3+ mentions, clear role/context) — offer to add directly |
| Needs clarification | Seen but ambiguous — ask the user |
| Low frequency / unclear | 1–2 mentions, thin context — note for later |
Use this format for comprehensive scans:
## New people (not in memory)
| Name | Frequency | Context |
|------|-----------|---------|
| Maya Rodriguez | 12 mentions | design, UI reviews |
## New projects / topics
| Name | Frequency | Context |
|------|-----------|---------|
| Starlight | 15 mentions | planning docs, product |
## Suggested cleanup
- **Horizon project** — No mentions in 30 days. Mark completed?
Integration with other skills
| Skill / command | How memory fits |
|---|
| meeting-prep | Decode attendees; offer to save new facts after prep |
| meeting-follow-up | Resolve names in notes; offer to save people/projects/decisions |
| inbox-triage / email-drafting | Decode thread shorthand; match senders to memory/people/ |
| task-management | Decode task entities ("PSR for oracle" → real names) |
| weekly-review | Prune stale or contradictory entries with user confirmation |
/assistant:update (default) | Decode task entities against memory; surface gaps; save confirmed entries inline |
/assistant:update memory | Memory-only — gaps, explicit capture, prune stale hot-cache entries |
/assistant:update --all | Deep-scan connectors for missed todos and new people/projects — present each for confirmation, never auto-add |
/assistant:update memory --all | Connector scan for new people/projects not yet in memory |
| Chat ("remember that …") | Explicit capture of people, projects, or terms — no slash command required |
When another skill surfaces a durable fact, offer to save it — don't add silently.
Bootstrapping
- Fast path:
/assistant:start — scaffold files, bootstrap memory from the user's todo list.
- No profile yet? Offer
/assistant:setup — captures identity, voice, and key people into the profile.
- Empty memory? Run
/assistant:start, /assistant:setup, or seed AGENTS.md and memory/glossary.md from conversation. Setup promotes profile key people automatically.
- Fill gaps from activity:
/assistant:update decodes existing tasks against memory, runs enrichment, and asks about unknowns. Add --all to scan connected sources for people and projects worth remembering. Run /assistant:update memory for a memory-only pass including prune.
No connectors? Memory still works from conversation, pasted threads, and meeting notes.
Conventions
- Bold terms in
AGENTS.md for scannability
- Keep
AGENTS.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
AGENTS.md
- When something goes stale, demote it to
memory/ only
What goes where
| Type | profile.md | policies/ | AGENTS.md (hot cache) | memory/ (full storage) |
|---|
| Your identity & voice | ✓ | ✗ | ✗ | ✗ |
| VIP tiers & email policy | ✗ | ✓ | ✗ | ✗ |
| Person | Key people only | ✗ | Top ~30 frequent contacts | glossary.md + people/{name}.md |
| Acronym/term | ✗ | ✗ | ~30 most common | glossary.md (complete list) |
| Project | Goals/deadlines | ✗ | Active projects only | glossary.md + projects/{name}.md |
| Nickname | ✗ | ✗ | In People if top 30 | glossary.md (all nicknames) |
| Company context | ✗ | ✗ | Quick reference only | context/company.md |
| Work preferences | Policy-level | ✓ | Day-to-day prefs | — |
| Historical/stale | ✗ | ✗ | ✗ Remove | ✓ Keep in memory/ |
Promotion / demotion
Promote to AGENTS.md when:
- You use a term/person frequently
- It's part of active work
Demote to memory/ only when:
- Project completed
- Person no longer a frequent contact
- Term rarely used
Propose a profile update when:
- Someone becomes a VIP or key person
- A durable policy preference emerges (not just a shorthand term)
This keeps AGENTS.md fresh and relevant without bloating the profile.
Rules
- Decode before acting — never guess what shorthand means.
- Tell the user after every write to
memory/ or AGENTS.md.
- Don't delete or overwrite memory entries without confirmation.
- Don't invent biographies — if someone isn't in memory, say so and offer to learn.
- Profile changes always need a diff and approval (except during setup).
Approval frame
Follow rules/approval-frame.md when proposing memory or profile changes.
Queue types:
memory-suggestion — proposed AGENTS.md or memory/ writes use source_path under pending-memory/*.mdprofile-diff — profile changes use source_path under pending-profile/*.diff or inline diff in the item body
Append the observability footer when queue items are written. Never write profile or memory files without user confirmation.
