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

skill_id, version, last_updated, type, code_dependencies, requires_skills

skill_id	version	last_updated	type	code_dependencies	requires_skills
SKILL_MODULE_LAC	1.0	2025-12-11	module	knowledge_base/lac.py	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:

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:

# 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:

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:

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:

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

---

CLI Commands

# 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:

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:

insights = lac.get_relevant_insights(error_message, categories=["failure", "workaround"])

Study Creation (OP_01)

Query similar past studies for configuration hints:

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