-
Notifications
You must be signed in to change notification settings - Fork 2
feat: MEMORY.md index file for memory discovery #717
Copy link
Copy link
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
Context
Claude Code uses MEMORY.md as a lightweight pointer file that's always loaded into the system prompt. It contains only links to memory files with brief descriptions — never memory content itself. This enables discovery without loading everything.
From Claude Code Source
- MEMORY.md: 200-line cap, 25KB cap, always in system prompt
- Contains only:
- [Title](file.md) — one-line description - No frontmatter, no content, no dates
- Truncated with warning if caps exceeded
- Separate from the topic memory files it points to
Current State
We have no discovery layer. run-context.ts reads state.md directly and injects it into the prompt. There's no way for an agent to know what memories exist without reading them all.
Proposed Changes
Add MEMORY.md at .agents/memory/{squad}/{agent}/MEMORY.md:
- [api-migration](api-migration.md) — Alembic pipeline state, rev 37 deployed
- [auth-rewrite](auth-rewrite.md) — OAuth2 rewrite for compliance
- [deploy-blockers](deploy-blockers.md) — Current deployment blockersReading behavior
- If MEMORY.md exists, inject it into context (cheap: ~200 tokens for 10 pointers)
- Agent decides which files to Read based on task relevance
- If MEMORY.md doesn't exist, fall back to state.md (backwards compat)
Writing behavior
- Agents write topic files, then update MEMORY.md index
- SYSTEM.md instructions teach agents the two-step save pattern
- Max 200 lines enforced by rotate script
Files to change
- src/lib/run-context.ts — load MEMORY.md instead of (or alongside) state.md
- .agents/SYSTEM.md — document MEMORY.md as index pattern
- scripts/rotate-states.sh — maintain MEMORY.md line cap
Expected impact
- ~200 tokens for index vs ~2000 tokens for full state.md
- Agent reads only relevant topic files on demand
- Enables per-turn relevance selection (test(workflow): fix child_process mock, add spawn export #710)
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request