memory-architect

# 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: ```jsonl {"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_name` or `org_name` - Projects: `proj_name` - Properties/locations: `prop_name` or `loc_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 ```bash wc -l MEMORY.md memory/protocols.md memory/active.md memory/archive.md memory/ontology/graph.jsonl ``` Targets: 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 on `memory_search` or 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 ```bash 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' ```