memory-management
Two-tier memory that makes the agent a true workplace collaborator. Decodes shorthand, acronyms, nicknames, and internal language so the agent understands requests like a colleague would. A small pers
SKILL.mdpackages/core-backend/starter-packs/general/Plugins/general-starter/skills/memory-management/SKILL.md
GitHubMemory Management
Memory makes your agent a workplace collaborator - someone who speaks your internal language.
The Goal
Transform shorthand into understanding:
User: "ask todd to do the PSR for oracle"
↓ the agent 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, the agent 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, personal (~30 people, common terms, your preferences)
Knowledge base (Hexis, shared with your team)
Glossary.md ← Full decoder ring (everything)
People/ ← Work profiles of colleagues
Projects/ ← Project details
How we work.md ← Teams, tools, processes
CLAUDE.md (Hot Cache): the file your agent reads at the start of every conversation, in its own working directory. Claude reads CLAUDE.md; other agents read their own file (often AGENTS.md). Use whichever your agent reads. It is NOT the AGENTS.md at the root of the knowledge base, which the platform maintains.
- 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
Glossary (Full Glossary): the Glossary page in the knowledge base.
- Complete decoder ring - everyone, every term
- Searched when something isn't in CLAUDE.md
- Shared: the whole team benefits from every term anyone adds
People/, Projects/, How we work:
- Rich detail when needed for execution
- Full profiles, history, context
The knowledge base lives in the knowledge folder (KnowledgeBase/ unless your workspace renamed it). Search it with the Hexis tools (grep, list_files, read_file) and write to it with write_file or edit_file. If the team already keeps these pages under other names, use theirs.
Shared vs personal
The knowledge base is read by your whole team. Before anything goes there:
- Work facts only. Roles, responsibilities, how to reach someone for work, project facts, terms. Nothing private or personal about a colleague (no health, family, opinions of them, or hobbies they have not shared at work). Write each profile as if its subject will read it, because they may.
- Your preferences stay personal. "No meetings Friday afternoons" goes in CLAUDE.md, not the knowledge base.
- Ask before writing. Show what you will add and where. If the person cannot write to a page, the change goes in as a proposed change for the page's owner to approve; say so.
- Check before adding. Search the knowledge base first and update an existing page instead of creating a duplicate.
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 the knowledge base (Glossary first)
→ The 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 the knowledge base grows with the team.
File Locations
- Working memory:
CLAUDE.md(or your agent's equivalent) in the agent's working directory - Deep memory: pages in the Hexis knowledge base
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
| Who | Role |
|-----|------|
| **Todd** | Todd Martinez, Finance lead |
| **Sarah** | Sarah Chen, Engineering (Platform) |
| **Greg** | Greg Wilson, Sales |
→ Full list: knowledge base Glossary, profiles: People/
## Terms
| Term | Meaning |
|------|---------|
| PSR | Pipeline Status Report |
| P0 | Drop everything priority |
| standup | Daily 9am sync |
→ Full glossary: knowledge base Glossary
## Projects
| Name | What |
|------|------|
| **Phoenix** | DB migration, Q2 launch |
| **Horizon** | Mobile app redesign |
→ Details: knowledge base Projects/
## Preferences
- 25-min meetings with buffers
- Async-first, Slack over email
- No meetings Friday afternoons
Deep Memory Format (knowledge base)
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 |
People/{Name}.md:
# Todd Martinez
**Also known as:** Todd, T
**Role:** Finance Lead
**Team:** Finance
**Reports to:** CFO (Michael Chen)
## Working with Todd
- 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
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.
How we work.md:
# How we work
## 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. CLAUDE.md (hot cache) → Check first, covers 90% of cases
2. Glossary (knowledge base) → Full glossary if not in hot cache
3. 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)
Glossary lookup:
"oracle" → Oracle Systems deal ($2.3M) ✓
Now the agent can act with full context.
Adding Memory
When user says "remember this" or "X means Y":
Glossary items (acronyms, terms, shorthand):
- Add to the Glossary page (after asking - it is shared)
- If frequently used, add to CLAUDE.md Terms
People:
- Create/update People/{Name}.md (work facts only)
- Add to CLAUDE.md People if important
- Capture nicknames - critical for decoding
Projects:
- Create/update Projects/{Name}.md
- Add to CLAUDE.md Projects if current
- Capture codenames - "Phoenix", "the migration", etc.
Preferences: Add to CLAUDE.md Preferences section (personal, never the knowledge base)
Recalling Memory
When user asks "who is X" or "what does X mean":
- Check CLAUDE.md first
- Search the knowledge base 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
- Read knowledge base pages 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
- 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)
- Page names: readable, the way the team would look them up (
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, drop it from CLAUDE.md; the knowledge base keeps it
What Goes Where
| Type | CLAUDE.md (Hot Cache) | Knowledge base (shared) |
|---|---|---|
| Person | Top ~30 frequent contacts | Glossary + People/{Name}.md |
| Acronym/term | ~30 most common | Glossary (complete list) |
| Project | Active projects only | Glossary + Projects/{Name}.md |
| Nickname | In People if top 30 | Glossary (all nicknames) |
| Company context | Quick reference only | How we work |
| Preferences | All preferences | - |
| Historical/stale | ✗ Remove | ✓ Keep, marked as finished |
Promotion / Demotion
Promote to CLAUDE.md when:
- You use a term/person frequently
- It's part of active work
Drop from CLAUDE.md (the knowledge base keeps it) when:
- Project completed
- Person no longer frequent contact
- Term rarely used
This keeps CLAUDE.md fresh and relevant.