- name
- memory-architect
- description
- Restructure flat MEMORY.md files into a tiered memory system with an entity graph. Use when: (1) MEMORY.md is growing unwieldy or exceeds 150 lines, (2) user asks to organize/restructure/tier memory, (3) context compaction is losing important details, (4) you need structured entity lookup (people, projects, properties, contacts) instead of scanning markdown. Triggers on organize my memory, memory is too big, restructure memory, tier my memory, make memory more efficient.
Memory Architect
Split a monolithic MEMORY.md into three tiers plus a structured entity graph.
Architecture
MEMORY.md → Router (30 lines max). Points to tiers.
memory/protocols.md → HOT: Stable workflows, shortcuts, procedures. Read on session start.
memory/active.md → WARM: Current projects, waiting-on, live context. Check before acting.
memory/archive.md → COLD: Completed work, historical reference. Search when needed.
memory/ontology/graph.jsonl → Structured entities + relations (JSONL append-only)Process
1. Analyze the existing MEMORY.md
Read the full file. Classify each section:
| Content type | Tier | Examples |
|---|---|---|
| Stable workflow / procedure | protocols | Emoji shortcuts, deploy steps, tool usage rules |
| Active project / waiting-on | active | Current builds, pending replies, live URLs |
| Completed work / reference data | archive | Done tasks, contact lists, account tables, old decisions |
| Named entity with properties | ontology | People, orgs, projects, properties, locations |
2. Create the tier files
Write each tier file with a header comment explaining its purpose and update frequency.
protocols.md rules:
- Only procedures that rarely change
- Include the exact commands (copy-pasteable)
- No project-specific state
active.md rules:
- Only things with a next action or pending status
- Include "Waiting On" section at bottom
- Prune completed items to archive on each update
archive.md rules:
- Completed work grouped by date or category
- Reference data (contacts, accounts, chat IDs)
- Keep searchable — use headers and tables
3. Extract entities to ontology
For each named person, organization, project, property, or location, create a JSONL entry:
{"op":"create","entity":{"id":"p_alice","type":"Person","properties":{"name":"Alice","email":"alice@example.com","role":"Engineer"}},"timestamp":"2026-01-01T00:00:00Z"}
{"op":"relate","from":"p_alice","rel":"member_of","to":"org_acme","timestamp":"2026-01-01T00:00:00Z"}ID conventions:
- People:
p_shortname - Organizations:
grp_nameororg_name - Projects:
proj_name - Properties/locations:
prop_nameorloc_name
Relation types: member_of, owns, collaborates_on, interested_in, guides, uses, listed_by, located_at
4. Rewrite MEMORY.md as router
Replace MEMORY.md with a ~25-line index that:
- Lists the three tiers with one-line descriptions
- Notes the ontology location
- Preserves any system directives (NO_REPLY rules, heartbeat instructions)
- Contains zero project-specific content
5. Verify
wc -l MEMORY.md memory/protocols.md memory/active.md memory/archive.md memory/ontology/graph.jsonlTargets: MEMORY.md under 30, protocols under 100, active under 80, graph = 1 line per entity/relation.
Maintenance
On each session
- Read
memory/protocols.md(always) - Scan
memory/active.md(always) memory/archive.md— only onmemory_searchor explicit request
When adding new information
- New procedure → protocols.md
- New project/active item → active.md
- Completed item → move active → archive
- New person/org/project → append to graph.jsonl
Entity queries
grep "p_forrest" memory/ontology/graph.jsonl
grep '"type":"Project"' memory/ontology/graph.jsonl
cat memory/ontology/graph.jsonl | jq -r 'select(.entity?.type=="Person") | .entity.properties.name'