Skip to content

feat: MEMORY.md index file for memory discovery #717

@kokevidaurre

Description

@kokevidaurre

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 blockers

Reading behavior

  1. If MEMORY.md exists, inject it into context (cheap: ~200 tokens for 10 pointers)
  2. Agent decides which files to Read based on task relevance
  3. If MEMORY.md doesn't exist, fall back to state.md (backwards compat)

Writing behavior

  1. Agents write topic files, then update MEMORY.md index
  2. SYSTEM.md instructions teach agents the two-step save pattern
  3. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions