Atomizer/.claude/skills/modules/learning-atomizer-core.md

---
skill_id: SKILL_MODULE_LAC
version: 1.0
last_updated: 2025-12-11
type: module
code_dependencies:
  - knowledge_base/lac.py
requires_skills:
  - SKILL_000
---

# Learning Atomizer Core (LAC) Integration

**Version**: 1.0
**Updated**: 2025-12-11
**Purpose**: Enable Claude to learn from every session and improve over time.

---

## Overview

LAC is Atomizer's persistent memory system. It stores:
- **Optimization outcomes** - What methods worked for what problems
- **Session insights** - Learnings, failures, and workarounds
- **Skill evolution** - Suggested protocol improvements

---

## Directory Structure

```
knowledge_base/lac/
├── optimization_memory/     # What worked for what geometry
│   ├── bracket.jsonl
│   ├── beam.jsonl
│   └── mirror.jsonl
├── session_insights/        # Learnings from sessions
│   ├── failure.jsonl
│   ├── success_pattern.jsonl
│   ├── user_preference.jsonl
│   └── protocol_clarification.jsonl
└── skill_evolution/         # Protocol improvements
    └── suggested_updates.jsonl
```

---

## When to Use LAC

### At Session Start
Query LAC for relevant prior knowledge:

```python
from knowledge_base.lac import get_lac

lac = get_lac()

# Before starting a bracket optimization
similar = lac.query_similar_optimizations(
    geometry_type="bracket",
    objectives=["mass"],
    converged_only=True
)

# Get method recommendation
rec = lac.get_best_method_for("bracket", n_objectives=1)
if rec:
    print(f"Recommended: {rec['method']} (success rate: {rec['success_rate']:.0%})")

# Get relevant insights
insights = lac.get_relevant_insights("bracket mass optimization")
```

### During Session
Record learnings as they occur:

```python
# Record a failure and its solution
lac.record_insight(
    category="failure",
    context="Modal analysis with CMA-ES sampler",
    insight="CMA-ES struggles with discrete frequency targets. TPE works better.",
    confidence=0.8,
    tags=["cma-es", "modal", "frequency"]
)

# Record a success pattern
lac.record_insight(
    category="success_pattern",
    context="Bracket optimization with 5+ design variables",
    insight="20 startup trials before TPE improves convergence by 30%",
    confidence=0.85,
    tags=["tpe", "startup_trials", "bracket"]
)

# Record user preference
lac.record_insight(
    category="user_preference",
    context="Report generation",
    insight="User prefers Pareto plots with actual values instead of normalized",
    confidence=0.9,
    tags=["plotting", "pareto", "reporting"]
)
```

### At Session End
Record optimization outcomes:

```python
lac.record_optimization_outcome(
    study_name="bracket_v3",
    geometry_type="bracket",
    method="TPE",
    objectives=["mass"],
    design_vars=4,
    trials=100,
    converged=True,
    convergence_trial=67,
    best_value=2.34,
    notes="Good convergence with 20 startup trials"
)
```

---

## Insight Categories

| Category | Use When | Example |
|----------|----------|---------|
| `failure` | Something failed and you found the cause | "CMA-ES fails on discrete targets" |
| `success_pattern` | An approach worked particularly well | "TPE with n_startup=20 converges faster" |
| `user_preference` | User expressed a preference | "User prefers minimal output" |
| `protocol_clarification` | A protocol needed interpretation | "SYS_12 unclear on Zernike subcase numbering" |
| `performance` | Performance-related observation | "GNN inference 100x faster than FEA" |
| `workaround` | Found a workaround for a known issue | "Load _i.prt before UpdateFemodel()" |

---

## Protocol Update Suggestions

When you discover a protocol could be improved:

```python
lac.suggest_protocol_update(
    protocol="SYS_15_METHOD_SELECTOR.md",
    section="Modal Optimization",
    current_text="Use TPE or CMA-ES for frequency optimization",
    suggested_text="Use TPE for frequency optimization. CMA-ES struggles with discrete frequency targets.",
    reason="Discovered during bracket_modal study - CMA-ES failed to converge"
)
```

Review pending updates:
```python
pending = lac.get_pending_updates()
for p in pending:
    print(f"- {p['protocol']}: {p['reason']}")
```

---

## CLI Commands

```bash
# View LAC statistics
python knowledge_base/lac.py stats

# Generate full report
python knowledge_base/lac.py report

# View pending protocol updates
python knowledge_base/lac.py pending

# Query insights for a context
python knowledge_base/lac.py insights "bracket mass optimization"
```

---

## Integration with Protocols

### Method Selection (SYS_15)
Before recommending a method, check LAC:
```python
rec = lac.get_best_method_for(geometry_type, n_objectives)
# Use recommendation if available, else fall back to protocol defaults
```

### Troubleshooting (OP_06)
Check if this error has been seen before:
```python
insights = lac.get_relevant_insights(error_message, categories=["failure", "workaround"])
```

### Study Creation (OP_01)
Query similar past studies for configuration hints:
```python
similar = lac.query_similar_optimizations(geometry_type, objectives)
```

---

## Best Practices

1. **Record failures immediately** - Don't wait until session end
2. **Be specific** - Include enough context to be useful later
3. **Tag appropriately** - Tags enable better retrieval
4. **Set confidence** - Low (0.5) for hunches, high (0.9) for verified patterns
5. **Suggest protocol updates** - Don't just note issues, propose fixes

---

## Example Session Flow

```
SESSION START
│
├── Query LAC for similar optimizations
├── Query LAC for relevant insights
├── Note any pending protocol updates
│
├── [User requests work]
│
├── During work:
│   ├── Encounter issue? → Record to failure.jsonl
│   ├── Find workaround? → Record to workaround.jsonl
│   ├── User states preference? → Record to user_preference.jsonl
│   └── Protocol unclear? → Record to protocol_clarification.jsonl
│
└── SESSION END
    ├── Record optimization outcome (if optimization ran)
    ├── Suggest any protocol updates discovered
    └── Summarize learnings for user
```