Memory Compact

Optimize MEMORY.md into a directory-based structure to reduce token consumption in new conversations.

Why This Matters

New conversations load the entire MEMORY.md by default. By splitting into a lightweight index + detailed files, tokens are saved and queries become more efficient. Daily memories (YYYY-MM-DD.md) remain unchanged.

New Structure

{workspace}/
├── MEMORY.md                    # Directory index (lightweight, only links)
├── memory/
│   ├── details/                 # Detailed memory files (one per topic)
│   ├── _import/Start_Memory.md  # Essential startup info (must load first)
│   └── YYYY-MM-DD.md            # Daily memories (unchanged mechanism)

Execution Steps

1. Backup original:

   cp {workspace}/MEMORY.md {workspace}/MEMORY.md.backup

   Always backup before modification.
2. Create directories:

   mkdir -p {workspace}/memory/details
   mkdir -p {workspace}/memory/_import

3. Parse and split MEMORY.md:
   • Read original MEMORY.md
   • Split by section headers (## level)
   • Group related content by theme
   • Generate short titles (≤10 characters, Chinese preferred)
4. Generate detail files:
   • Save each section to memory/details/{title}.md
   • Preserve original content format
   • Use relative paths for cross-references if needed
5. Generate new MEMORY.md:
   • Create directory index following docs/MEMORY.md format
   • Group memories by topic (environment, team, tools, etc.)
   • Use relative paths: ./details/{title}.md
   • Include reference to Start_Memory.md
6. Generate Start_Memory.md:
   • Create essential startup info following docs/Start_Memory.md format
   • CRITICAL: Must include three mandatory sections (see docs/Start_Memory.md for details):
     1. 强制规则 - Memory_Search usage规范（先检索后读取）
     2. 重要约束：记忆存储结构规范 - MEMORY.md/details/Start_Memory/YYYY-MM-DD 的职责划分
     3. 记忆查询流程 - 新优化记忆结构下的查询流程
   • Save to memory/_import/Start_Memory.md
7. Update BOOTSTRAP.md:
   • Add conversation notice from docs/BOOTSTRAP_ADD.md
   • Place where Agent reads at startup
   • Instruct to read Start_Memory.md on first conversation
8. Update AGENTS.md:
   • Replace old Memory section with new structure description
   • Document memory query flow and Memory_Search usage
9. Verify and test:
   • Check directory structure is correct
   • Verify MEMORY.md format and links work
   • Ensure detail files are complete
   • Test Memory_Search can find and retrieve details
   • Confirm Start_Memory.md is properly referenced
10. Report results:
    • List created directories and files
    • Count migrated memory sections
    • Report validation status
    • Note any issues or warnings

Learnings Compatibility

When the workspace also uses a self-improvement / .learnings/ workflow:

• Treat .learnings/ as a staging area for raw corrections, failures, and feature requests
• Promote durable user preferences, environment facts, team rules, and other stable context into memory/details/*.md
• Keep MEMORY.md index-only even when promoting learnings; do not paste detailed learnings directly into it
• Continue to route behavioral patterns to SOUL.md, workflow rules to AGENTS.md, and tool gotchas to TOOLS.md
• Use memory/YYYY-MM-DD.md for daily capture first when information is still fresh or uncurated

Key Rules

• Preserve daily memories: Do not modify memory/YYYY-MM-DD.md files
• Backup first: Always copy MEMORY.md before changes
• Short titles: Detail file names ≤10 characters, clear and descriptive
• Relative paths: Use ./ paths for portability across workspaces
• Complete migration: Ensure all important info is moved, nothing lost
• Test thoroughly: Verify Memory_Search works with new structure
• Memory storage rule: All future memories MUST follow the details-based storage method - MEMORY.md stores only directory index (title + path), memory/details/ stores detailed content, memory/_import/Start_Memory.md stores essential startup info, memory/YYYY-MM-DD.md stores daily logs (unchanged)

Examples

Refer to docs/ directory for format templates:

• docs/MEMORY.md - Directory index with topic groups and relative paths
• docs/Start_Memory.md - Essential startup info with query flow and rules
  • NOTE: Simplified to remove redundancy. Must include three mandatory sections:
    1. 强制规则 (Memory_Search usage)
    2. 重要约束：记忆存储结构规范 (details storage method)
    3. 记忆查询流程 (query flow for optimized structure)
• docs/BOOTSTRAP_ADD.md - Notice to add to BOOTSTRAP.md for first-time reading

Query Flow After Optimization

1. New conversation starts: Read BOOTSTRAP.md → Read Start_Memory.md → Greet user
2. User gives command: Use Memory_Search to find relevant memories
3. If found: Read detailed document at referenced path
4. If not found: Proceed normally without reading memory files