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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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`

```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**:
   ```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`