auto-build/plugin/commands/memory-save.md

description: Save session insights to memory argument-hint: [category] - Optional: patterns, gotchas, or auto-detect

Save Session Insights to Memory

Persist learned insights from the current session for future use. This builds up a knowledge base that improves subsequent builds.

Memory Categories

Category	File	Purpose
patterns	patterns.json	Reusable code patterns discovered
gotchas	gotchas.json	Issues encountered and their solutions
codebase	codebase-map.json	Structural insights about the project

Workflow

1. Gather Session Context

• Review the current conversation/session
• Identify what was learned:
  • New patterns discovered
  • Problems encountered and solved
  • Insights about code structure
  • Effective approaches that worked

2. Ask User for Input

What insights should be saved from this session?

Categories:
1. [P] Pattern - A reusable code approach
2. [G] Gotcha - A problem and its solution
3. [C] Codebase - Insight about project structure

Enter category and description, or 'auto' to auto-detect:
>

3. Generate Memory Entry

For patterns:

{
  "id": "pat_20250115_143000",
  "timestamp": "2025-01-15T14:30:00Z",
  "title": "API Error Handling Pattern",
  "description": "All API calls should be wrapped in try-catch with consistent error response format",
  "context": "Discovered while implementing user dashboard API",
  "example": {
    "file": "src/api/users.ts",
    "lines": "45-52",
    "snippet": "try { ... } catch (e) { return errorResponse(e) }"
  },
  "tags": ["error-handling", "api", "patterns"],
  "feature": "user-dashboard",
  "usageCount": 0
}

For gotchas:

{
  "id": "got_20250115_143000",
  "timestamp": "2025-01-15T14:30:00Z",
  "title": "Oracle Pool Connection Timeout",
  "problem": "Connections timeout after 30s if pool is exhausted",
  "solution": "Increase POOL_MAX in .env or optimize query execution",
  "context": "Encountered during load testing",
  "tags": ["database", "oracle", "performance"],
  "feature": "user-dashboard"
}

For codebase:

{
  "id": "cb_20250115_143000",
  "timestamp": "2025-01-15T14:30:00Z",
  "path": "src/services/",
  "insight": "All services follow singleton pattern with lazy initialization",
  "examples": ["UserService", "AuthService", "ReportService"],
  "tags": ["architecture", "services"]
}

4. Merge with Existing Memory

1. Load existing memory file (e.g., patterns.json)
2. Check for duplicates by:
   • Matching titles
   • Overlapping tags
   • Similar descriptions
3. If duplicate found: Ask "Update existing or add as new?"
4. Append new entry or update existing
5. Update updated timestamp

5. Create Session Record

Save comprehensive session record: .auto-build/memory/sessions/{timestamp}-{feature}.json

{
  "session_id": "ses_20250115_143000",
  "timestamp": "2025-01-15T14:30:00Z",
  "feature": "user-dashboard",
  "duration": "2h 30m",
  "insights_saved": [
    {"type": "pattern", "id": "pat_20250115_143000"},
    {"type": "gotcha", "id": "got_20250115_143000"}
  ],
  "files_modified": ["src/api/users.ts", "src/types/user.ts"],
  "summary": "Implemented user dashboard with stats API"
}

6. Sync to .claude/rules/ (AUTO-LOADING)

After saving to JSON files, convert and sync to CLAUDE.md-compatible format:

1. Load memory files:

   • Read .auto-build/memory/patterns.json
   • Read .auto-build/memory/gotchas.json

2. Convert to Markdown:

   ---
   paths: **/*
   ---
   
   # Auto-Build Learned Patterns
   
   Last updated: {TIMESTAMP}
   
   ## Patterns
   
   ### {Pattern Title}
   **Discovered**: {date} (feature: {feature-name})
   **Description**: {description}
   
   **Example** (`{file}:{lines}`):
   \```{language}
   {code snippet}
   \```
   
   **Tags**: {tag1}, {tag2}
   
   ---
   
   ## Gotchas
   
   ### {Gotcha Title}
   **Discovered**: {date} (feature: {feature-name})
   **Problem**: {problem description}
   **Solution**: {solution}
   
   **Tags**: {tag1}, {tag2}
   

3. Write to .claude/rules/auto-build-memory.md:

   • Overwrites entire file
   • This file is auto-loaded by Claude Code
   • Patterns become part of project context automatically

7. Confirmation

Saved to memory:

[PATTERN] API Error Handling Pattern
  File: patterns.json (searchable)
  File: .claude/rules/auto-build-memory.md (auto-loaded)

[GOTCHA] Oracle Pool Connection Timeout
  File: gotchas.json (searchable)
  File: .claude/rules/auto-build-memory.md (auto-loaded)

Session recorded: sessions/20250115-143000-user-dashboard.json

Memory stats:
- Total patterns: 15
- Total gotchas: 8
- Sessions recorded: 23
- Auto-loaded in CLAUDE.md: ✅

Auto-Detection

If user enters 'auto' or runs without arguments after a build:

1. Analyze modified files from status.json
2. Look for:
   • New patterns introduced
   • Error handling approaches
   • Code structure decisions
3. Suggest entries for each category
4. Ask user to confirm/edit before saving

Memory File Limits

• Keep max 100 patterns (remove oldest unused)
• Keep max 50 gotchas (remove oldest)
• Keep all session records (for history)
• Update usageCount when pattern is referenced in /ab:memory-search