livepilot 1.9.16 → 1.9.18

package/livepilot/skills/livepilot-devices/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: livepilot-devices
+description: This skill should be used when the user asks to "load a device", "add an effect", "find a plugin", "device chain", "rack", "preset", "sound design setup", "load instrument", "find a synth", or wants to browse, load, and configure devices in Ableton Live.
+---
+
+# Device Loading and Configuration
+
+Load instruments, effects, and plugins into Ableton Live tracks. Every device operation follows one discipline: search first, verify after.
+
+## Browser Workflow — The Safe Path
+
+Always use the two-step browser workflow for loading devices:
+
+1. **Search:** `search_browser(path, name_filter)` — returns a list of matching items with exact URIs
+2. **Inspect:** Read the results. Confirm the item name, type, and path match what you need
+3. **Load:** `load_browser_item(uri)` — pass the exact URI string from search results
+
+Common search paths:
+- `path="Instruments"` — synths, samplers, instrument racks
+- `path="Drums"` — drum racks, drum kits, percussion
+- `path="Audio Effects"` — reverb, delay, compressor, EQ, saturator
+- `path="MIDI Effects"` — arpeggiator, chord, scale, random
+- `path="Sounds"` — preset sounds organized by category
+- `path="Samples"` — audio samples, one-shots, loops
+
+Combine path with `name_filter` to narrow results. Example: `search_browser(path="Drums", name_filter="808 Kit")`.
+
+NEVER invent device or preset names. A hallucinated name like "echomorph-hpf" or "Drift Pad Wonk" will crash the load. Always search first, then use the exact URI from results.
+
+## find_and_load_device — The Shortcut
+
+Use `find_and_load_device(name)` ONLY for these simple built-in effects:
+- "Reverb"
+- "Delay"
+- "Compressor"
+- "EQ Eight"
+- "Saturator"
+- "Utility"
+
+For everything else — instruments, racks, presets, AU/VST plugins — use the browser workflow. The shortcut matches greedily and can load a sample file instead of a synth when names overlap (e.g., "Drift" matches "Synth Bass Drift Pad Wonk Bass.wav" before the Drift synthesizer).
+
+## Plugin Health Verification
+
+After loading any device, verify it actually works:
+
+1. Call `get_device_info(track_index, device_index)` on the newly loaded device
+2. Check `parameter_count` — if the device is an AU/VST plugin (`class_name` contains "PluginDevice") and `parameter_count` is 1 or less, the plugin is dead. The shell loaded but the DSP engine crashed.
+3. Check `health_flags` for `opaque_or_failed_plugin` (dead or untweakable AU/VST) or `sample_dependent` (needs source audio)
+4. Check `plugin_host_status` and `mcp_sound_design_ready`
+5. If `mcp_sound_design_ready` is `false`: delete the device with `delete_device`, replace it with a native Ableton alternative, and report the failure to the user
+
+Dead plugin recovery pattern:
+```
+get_device_info → parameter_count <= 1 on PluginDevice?
+  → delete_device(track_index, device_index)
+  → search_browser for native alternative
+  → load_browser_item with replacement URI
+  → report failure and substitution to user
+```
+
+## Rack Introspection
+
+Use `walk_device_tree(track_index)` to see the full nested structure of racks on a track — Instrument Racks, Audio Effect Racks, and Drum Racks with all their chains and sub-devices.
+
+Use `get_rack_chains(track_index, device_index)` to inspect individual rack chain contents. For Drum Racks, this reveals which pads have samples loaded and which chains exist. An empty Drum Rack (zero chains) produces silence.
+
+Set chain volumes with `set_chain_volume(track_index, device_index, chain_index, volume)` to balance rack layers.
+
+## Drum Rack Rule
+
+NEVER load a bare "Drum Rack" — it is an empty container with zero chains and produces silence. Always load a kit preset through the browser:
+
+```
+search_browser(path="Drums", name_filter="Kit")
+```
+
+Pick a real kit from results: "909 Core Kit", "808 Core Kit", "Boom Bap Kit", "Lo-Fi Kit", etc. These come pre-loaded with samples on their pads.
+
+After loading any Drum Rack preset, verify with `get_rack_chains` that chains exist and have named pads like "Bass Drum", "Snare", "Hi-Hat".
+
+## Sample-Dependent Devices
+
+These devices load "successfully" with many parameters but produce zero audio without source material. Since MCP tools cannot load samples into third-party plugin UIs, NEVER use these as standalone instruments:
+
+- **Granular synths:** iDensity, Tardigrain, Koala Sampler, Burns Audio Granular
+- **Bare samplers:** Simpler (empty), Sampler (empty) — always load a preset, never the empty shell
+- **Sample players:** AudioLayer, sEGments
+
+Use self-contained synthesizers instead — these produce sound immediately from MIDI input alone:
+- **Wavetable** — versatile wavetable synthesis
+- **Operator** — FM synthesis, 4 operators
+- **Drift** — analog-modeled, warm and organic
+- **Analog** — subtractive analog modeling
+- **Meld** — MPE-ready, two engines
+- **Collision** — physical modeling, mallet/resonator
+- **Tension** — physical modeling, string/exciter
+
+If granular textures are needed: use Wavetable with aggressive wavetable position modulation, Operator with FM feedback and short envelopes, or load a Simpler/Sampler **preset** (not the bare instrument) from the Sounds browser.
+
+## Simpler Operations
+
+For Simpler devices that already have samples loaded:
+
+- `load_sample_to_simpler(track_index, device_index, file_path)` — load audio into Simpler
+- `replace_simpler_sample(track_index, device_index, file_path)` — swap the current sample. Only works on Simplers that already have a sample loaded.
+- `crop_simpler(track_index, device_index)` — trim sample to current start/end points
+- `reverse_simpler(track_index, device_index)` — reverse the loaded sample
+- `get_simpler_slices(track_index, device_index)` — retrieve auto-detected slice points (Slice mode)
+- `set_simpler_playback_mode(track_index, device_index, mode)` — switch between Classic, One-Shot, and Slice modes
+
+Slice mode workflow: load sample, set playback mode to Slice, call `get_simpler_slices` to see slice points, then program MIDI notes targeting slice indices.
+
+## Effect Chain Best Practices
+
+After loading any effect, verify its key parameters are not at pass-through defaults:
+- **Reverb:** `Dry/Wet` should be > 0 (typically 20-40% for subtle, 60-100% for creative)
+- **Delay:** `Dry/Wet` > 0, `Feedback` set appropriately
+- **Compressor:** `Threshold` below signal level, `Ratio` > 1:1
+- **EQ Eight:** At least one band with non-zero gain
+- **Saturator:** `Drive` > 0 dB
+- **Utility:** `Gain` at target value, `Width` as needed
+
+Use `get_device_parameters` to read current values, then `set_device_parameter` or `batch_set_parameters` to configure. Use `toggle_device` to bypass/enable devices for A/B comparison.
+
+## Device Presets
+
+- `get_device_presets(track_index, device_index)` — list available presets for the loaded device
+- `get_plugin_parameters(track_index, device_index)` — see all AU/VST plugin parameters
+- `get_plugin_presets(track_index, device_index)` — list presets for AU/VST plugins
+- `map_plugin_parameter(track_index, device_index, parameter_index)` — map a plugin parameter for automation
+
+## Device Atlas Reference
+
+Consult `references/device-atlas/` in the livepilot-core skill for the full corpus of 280+ instruments, 139 drum kits, and 350+ impulse responses. The atlas contains real browser URIs, preset names, and sonic descriptions. Use it as your lookup table before loading any device — never guess a name that is not in the atlas or in browser search results.

package/livepilot/skills/livepilot-evaluation/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: livepilot-evaluation
+description: This skill should be used when the user asks to "evaluate a change", "was that good", "keep or undo", "A/B compare", "rate my change", "check if that helped", or wants to use the universal evaluation loop to judge production moves.
+---
+
+# Evaluation Engine — Universal Move Judgment
+
+The evaluation engine is the shared decision layer used by all other engines (mix, sound design, composition, performance). It determines whether a change improved the session, and whether to keep it, undo it, or learn from it.
+
+## The Universal Evaluation Loop
+
+Every production move follows this loop regardless of which engine initiated it.
+
+### Step 1 — Compile Goal Vector
+
+Call `compile_goal_vector(goal, mode)` to establish what you are trying to achieve.
+
+**Goal**: a plain-text description of the intended improvement (e.g., "reduce masking between bass and kick in 100-200 Hz range").
+
+**Modes** control how aggressively you act:
+
+- `observe` — read-only analysis, no changes. Use for diagnostics and status checks.
+- `improve` — targeted fixes for specific issues. The default mode. Make the smallest change that addresses the problem.
+- `explore` — creative experimentation. Wider parameter ranges, more tolerance for unexpected results. Use when the user says "try something", "experiment", or "surprise me".
+- `finish` — polish and finalize. Conservative moves only, protect what already works. Use when the user says "almost done", "final touches", or "wrap it up".
+- `diagnose` — identify problems without fixing them. Like observe but with critic analysis. Use when the user says "what's wrong" without asking for fixes.
+
+### Step 2 — Build World Model
+
+Call `build_world_model` to snapshot the current session state and available capabilities:
+
+- Session info: tracks, clips, devices, tempo, time signature
+- Capability state: analyzer connected, M4L bridge active, FluCoMa available
+- Recent actions: last moves taken and their outcomes
+- Active constraints: performance mode safety limits, user anti-preferences
+
+The world model determines what tools are available and what measurements are possible.
+
+### Step 3 — Get Turn Budget
+
+Call `get_turn_budget(mode)` to determine how many moves you should make this turn:
+
+- `observe` / `diagnose`: 0 moves (read-only)
+- `improve`: 1-3 moves per turn, evaluate after each
+- `explore`: 1-5 moves per turn, wider tolerance
+- `finish`: 1 move per turn, strict evaluation
+
+Do not exceed the turn budget. If more work is needed, complete the current turn, report progress, and start a new turn.
+
+### Step 4 — Capture Before
+
+Take measurements appropriate to the engine context:
+
+- **Mix engine**: `get_master_spectrum` + `get_master_rms`
+- **Sound design**: `get_device_parameters` + `get_master_spectrum`
+- **Composition**: `get_notes` or `get_arrangement_notes` + `get_section_graph`
+- **Universal**: `get_mix_snapshot` for full session state
+
+Always capture before executing. Without a before snapshot, evaluation is meaningless.
+
+### Step 5 — Execute Intervention
+
+Apply the planned change using the appropriate tool. Execute exactly one move, then proceed to evaluation.
+
+### Step 6 — Capture After
+
+Repeat the same measurements from Step 4. Use identical tool calls to ensure comparable data.
+
+### Step 7 — Evaluate
+
+Call the appropriate evaluator:
+
+- `evaluate_move(before_snapshot, after_snapshot, goal)` — universal evaluator, works for any engine
+- `evaluate_mix_move(before_snapshot, after_snapshot, targets, protect)` — mix-specific with protection constraints
+- `evaluate_composition_move(before_snapshot, after_snapshot, goal)` — composition-specific
+- `evaluate_with_fabric(before_snapshot, after_snapshot, goal)` — uses memory fabric for taste-aware judgment
+
+### Step 8 — Read the Verdict
+
+Every evaluator returns:
+
+- `keep_change` (bool): whether the change should stay
+- `score` (0.0-1.0): magnitude of improvement (0.5 = neutral, >0.5 = better, <0.5 = worse)
+- `goal_progress` (0.0-1.0): how much closer to the stated goal
+- `collateral_damage` (list): things that got worse as a side effect
+- `explanation` (string): human-readable judgment summary
+
+### Step 9 — Keep or Undo
+
+If `keep_change` is `false`:
+1. Call `undo()` immediately
+2. Report to the user: what was tried, why it was undone, citing `collateral_damage`
+3. Consider an alternative approach for the same goal
+
+If `keep_change` is `true`:
+1. Report the improvement with score and explanation
+2. If `score > 0.7`, this is a memory promotion candidate (see below)
+
+### Step 10 — Repeat or Stop
+
+Check turn budget remaining. If budget allows and goal_progress < 1.0, return to Step 4 for the next move. Otherwise, summarize progress and stop.
+
+## Capability Modes
+
+The world model includes a capability state that affects what measurements are available. Call `get_capability_state` to check.
+
+### normal
+Full measured evaluation. M4L analyzer connected, all spectral/RMS/key tools available. Critics use real data. This is the best mode.
+
+### measured_degraded
+Analyzer data is stale (older than 5 seconds) or intermittent. Measurements may not reflect current state. Re-trigger analysis before trusting cached values. Inform the user that data freshness is limited.
+
+### judgment_only
+No analyzer connected. Evaluation relies on device parameter changes, track structure, and role-based heuristics. Critics cannot use spectral evidence. Inform the user: "Evaluation is based on parameter analysis only — spectral verification unavailable."
+
+### read_only
+Session disconnected or in an error state. No tools can modify the session. Only read operations from cached data. Inform the user and suggest reconnecting.
+
+## Action Ledger
+
+Every move is recorded in the action ledger for accountability and learning.
+
+- `get_action_ledger_summary` — summary of all actions taken this session with scores
+- `get_recent_actions` — last N actions with full detail
+- `get_last_move` — the most recent action and its evaluation result
+
+Use the ledger to avoid repeating failed approaches. If a move type has been undone twice for the same issue, try a different strategy.
+
+## Memory Promotion
+
+Successful moves can be promoted to persistent memory for future sessions.
+
+- `get_promotion_candidates` — list moves from this session that scored > 0.7 and are eligible for saving
+- `memory_learn(type, data)` — save a technique to memory (mix_template, sound_design, composition, etc.)
+- `record_anti_preference(description)` — record something the user explicitly rejected, so it is never suggested again
+
+### Promotion Rules
+
+1. Only promote moves the user confirmed satisfaction with — a high score alone is not enough
+2. Anti-preferences are permanent until explicitly deleted
+3. Check `get_anti_preferences` before suggesting any move to avoid repeating rejected ideas
+4. Promotion is optional — never force it. Suggest when appropriate: "That scored 0.85 — want me to save this technique for future sessions?"
+
+## A/B Comparison
+
+When the user asks "was that good?" or "A/B compare":
+
+1. The before snapshot is A, the after snapshot is B
+2. Call the evaluator to get the score
+3. Present the comparison: "Before: [metrics]. After: [metrics]. Score: [score]. [explanation]"
+4. If the user prefers A, call `undo()` to revert to it
+5. If the user prefers B, keep the current state

package/livepilot/skills/livepilot-evaluation/references/capability-modes.md

@@ -0,0 +1,118 @@
+# Capability Modes Reference
+
+The evaluation engine adapts its behavior based on what measurement capabilities are available. Call `get_capability_state` to determine the current mode.
+
+## Mode: normal
+
+Full measurement capabilities available.
+
+**Requirements:**
+- Ableton Live connected via TCP port 9878
+- M4L analyzer bridge running on master track
+- UDP 9880 (M4L -> Server) and OSC 9881 (Server -> M4L) active
+- SpectralCache receiving fresh data (age < 5 seconds)
+
+**Available measurements:**
+- `get_master_spectrum` — 8-band spectral analysis, real-time
+- `get_master_rms` — RMS and peak levels
+- `get_detected_key` — key detection from audio
+- `get_mel_spectrum` — mel-scaled spectral representation
+- `get_chroma` — chromagram for harmonic analysis
+- `get_onsets` — transient detection
+- `get_momentary_loudness` — short-term loudness
+- `get_spectral_shape` — centroid, spread, skewness, kurtosis
+- All device parameter reads and session state tools
+
+**Evaluation quality:** Highest. Critics use measured spectral evidence. Before/after comparisons are numerically precise.
+
+## Mode: measured_degraded
+
+Analyzer data is present but stale or intermittent.
+
+**Indicators:**
+- SpectralCache age > 5 seconds
+- Intermittent UDP packet loss from M4L device
+- M4L bridge loaded but analyzer section not receiving audio
+
+**Available measurements:**
+- All session state tools (tracks, clips, devices, parameters)
+- Cached spectral data (may not reflect current audio)
+- Device parameter reads (always fresh)
+
+**Evaluation quality:** Moderate. Spectral comparisons may be inaccurate if data is stale. Always check cache age before trusting spectrum values.
+
+**User notification:** "Analyzer data may be stale. For accurate spectral evaluation, play audio through the master bus and wait 2-3 seconds for the cache to refresh."
+
+## Mode: judgment_only
+
+No M4L analyzer connected. The evaluation engine operates on structural and parametric data only.
+
+**Indicators:**
+- M4L bridge not loaded on master track
+- UDP 9880 not receiving data
+- `get_master_spectrum` returns error or empty data
+
+**Available measurements:**
+- All session state tools
+- Device parameter reads
+- Track structure (names, types, device chains)
+- Note and clip data
+- Role-based heuristics (bass tracks should have low content, etc.)
+
+**Evaluation quality:** Limited. No spectral evidence for masking, balance, or loudness judgments. Critics infer from:
+- Track names and roles (a track named "Bass" should have low-frequency content)
+- Device chains (a track with EQ Eight + Compressor is likely processed)
+- Parameter values (filter cutoff position, compressor threshold)
+- Volume/pan/send positions
+
+**User notification:** "M4L analyzer is not connected. Evaluation is based on track structure and parameter analysis only. For spectral verification, load the LivePilot Bridge device on the master track."
+
+## Mode: read_only
+
+Session disconnected or in an error state.
+
+**Indicators:**
+- TCP connection to port 9878 failed or timed out
+- Remote Script not responding
+- Ableton Live not running or crashed
+
+**Available measurements:**
+- Cached session data from last successful connection
+- Memory system (technique recall, preferences)
+- No live reads from the session
+
+**Evaluation quality:** None for current state. Can only reference cached data and memory.
+
+**User notification:** "Session disconnected. Cannot evaluate current state. Reconnect to Ableton Live to resume."
+
+## Capability Fallback Chain
+
+When a measurement fails, fall back gracefully:
+
+1. Try the primary measurement tool
+2. If it fails, check if degraded data is available in cache
+3. If no cache, use parametric/structural heuristics
+4. If no session connection, report inability and suggest reconnection
+
+Never silently skip evaluation. Always inform the user which capability mode is active and how it affects the quality of judgment.
+
+## Checking Capability State
+
+Call `get_capability_state` at the start of any evaluation session. The response includes:
+
+```json
+{
+  "mode": "normal",
+  "analyzer_connected": true,
+  "bridge_version": "1.9.18",
+  "spectral_cache_age_ms": 1200,
+  "flucoma_available": false,
+  "session_connected": true
+}
+```
+
+- `mode`: one of "normal", "measured_degraded", "judgment_only", "read_only"
+- `analyzer_connected`: whether M4L bridge is active
+- `spectral_cache_age_ms`: milliseconds since last spectral update
+- `flucoma_available`: whether FluCoMa analysis tools are installed
+- `session_connected`: whether TCP connection to Ableton is active

package/livepilot/skills/livepilot-evaluation/references/evaluation-contracts.md

@@ -0,0 +1,121 @@
+# Evaluation Contracts Reference
+
+Every evaluator returns the same base contract. Engine-specific evaluators extend it with additional fields.
+
+## Base Evaluation Contract
+
+Returned by `evaluate_move`:
+
+```json
+{
+  "keep_change": true,
+  "score": 0.72,
+  "goal_progress": 0.6,
+  "collateral_damage": [],
+  "explanation": "Filter cut at 250 Hz reduced masking by 4 dB without affecting bass body.",
+  "before_metrics": {
+    "master_rms_db": -12.4,
+    "master_peak_db": -3.2,
+    "spectrum": [...]
+  },
+  "after_metrics": {
+    "master_rms_db": -12.8,
+    "master_peak_db": -3.5,
+    "spectrum": [...]
+  }
+}
+```
+
+### Field Definitions
+
+- **keep_change** (bool): `true` if the change improved the target without unacceptable regression. `false` if the change should be undone.
+- **score** (float 0.0-1.0): 0.0 = catastrophic regression, 0.5 = neutral (no change), 1.0 = perfect improvement. Scores below 0.4 trigger automatic undo recommendation.
+- **goal_progress** (float 0.0-1.0): how much of the stated goal has been achieved. 1.0 means the goal is fully met. Use this to decide whether to continue iterating.
+- **collateral_damage** (list of strings): side effects that got worse. Empty list means no regressions detected. Examples: "bass lost 2 dB of body", "stereo width narrowed by 15%".
+- **explanation** (string): one-sentence human-readable summary of the judgment. Always report this to the user.
+
+## Mix Evaluation Contract
+
+Returned by `evaluate_mix_move`, extends base with:
+
+```json
+{
+  "targets": {
+    "reduce_masking": { "before": 0.72, "after": 0.35, "improved": true },
+    "maintain_headroom": { "before": -3.2, "after": -3.5, "ok": true }
+  },
+  "protect": {
+    "bass_body": { "before": -14.2, "after": -14.8, "ok": true },
+    "vocal_presence": { "before": -8.1, "after": -8.0, "ok": true }
+  },
+  "spectral_delta_db": {
+    "sub": 0.1, "low": -0.3, "low_mid": -2.1,
+    "mid": 0.2, "high_mid": 0.1, "high": 0.0
+  }
+}
+```
+
+- **targets**: what the move aimed to improve, with before/after measurements
+- **protect**: what must not get worse, with tolerance checking
+- **spectral_delta_db**: per-band change in spectral energy
+
+## Composition Evaluation Contract
+
+Returned by `evaluate_composition_move`, extends base with:
+
+```json
+{
+  "structural_coherence": 0.85,
+  "thematic_continuity": 0.78,
+  "energy_delta": 0.15,
+  "transition_smoothness": 0.82,
+  "note_count_delta": 12
+}
+```
+
+- **structural_coherence**: how well the change fits the overall form
+- **thematic_continuity**: whether existing motifs are maintained or developed (not broken)
+- **energy_delta**: change in section energy level
+- **transition_smoothness**: quality of section boundaries after the change
+
+## Fabric Evaluation Contract
+
+Returned by `evaluate_with_fabric`, extends base with:
+
+```json
+{
+  "taste_alignment": 0.88,
+  "anti_preference_violations": [],
+  "similar_past_moves": [
+    { "memory_id": "mix_001", "similarity": 0.91, "past_score": 0.85 }
+  ],
+  "novelty_score": 0.3
+}
+```
+
+- **taste_alignment**: how well the move matches the user's saved taste profile
+- **anti_preference_violations**: list of anti-preferences this move conflicts with (should be empty)
+- **similar_past_moves**: techniques from memory that resemble this move, with their past scores
+- **novelty_score**: how different this move is from past approaches (high = novel, low = familiar)
+
+## Scoring Thresholds
+
+| Score Range | Interpretation | Action |
+|------------|---------------|--------|
+| 0.0 - 0.3 | Significant regression | Auto-undo, explain damage |
+| 0.3 - 0.45 | Mild regression | Undo recommended, ask user |
+| 0.45 - 0.55 | Neutral / no effect | Keep but note it had no impact |
+| 0.55 - 0.7 | Mild improvement | Keep, continue iterating |
+| 0.7 - 0.85 | Clear improvement | Keep, suggest memory promotion |
+| 0.85 - 1.0 | Excellent improvement | Keep, strongly suggest promotion |
+
+## Collateral Damage Categories
+
+Common side effects to check for:
+
+- **bass_body_loss**: EQ cuts in the low-mid range reduced bass warmth
+- **stereo_narrowing**: mono compatibility fix reduced perceived width
+- **headroom_reduction**: boost increased master peak level
+- **transient_loss**: compression removed punch from drums
+- **vocal_masking**: frequency boost created new masking with vocal track
+- **phase_issue**: stereo manipulation introduced phase cancellation

package/livepilot/skills/livepilot-evaluation/references/memory-promotion.md

@@ -0,0 +1,110 @@
+# Memory Promotion Reference
+
+Memory promotion saves successful production moves to persistent storage for recall in future sessions.
+
+## Promotion Flow
+
+1. A move scores > 0.7 in evaluation
+2. Call `get_promotion_candidates` to list all eligible moves from this session
+3. Present the candidate to the user with score and description
+4. If the user confirms, call `memory_learn(type, data)` to save
+5. The technique is now available via `memory_recall` in future sessions
+
+## Promotion Candidates
+
+`get_promotion_candidates` returns moves that meet all criteria:
+
+- Evaluation score > 0.7
+- `keep_change` was `true`
+- The move has not already been promoted
+- The move does not conflict with any anti-preference
+
+Response format:
+```json
+{
+  "candidates": [
+    {
+      "action_id": "act_001",
+      "move_type": "eq_cut",
+      "score": 0.85,
+      "goal": "reduce masking between bass and kick",
+      "parameters": {
+        "track": "Bass",
+        "device": "EQ Eight",
+        "band": 3,
+        "frequency": 250,
+        "gain_db": -4.5,
+        "q": 2.0
+      },
+      "explanation": "4.5 dB cut at 250 Hz on bass cleared kick presence without losing bass warmth"
+    }
+  ]
+}
+```
+
+## Memory Types
+
+When calling `memory_learn`, specify the type:
+
+- `mix_template` — mixing techniques (EQ curves, compression settings, gain staging recipes)
+- `sound_design` — patch design moves (modulation settings, filter configurations, oscillator tuning)
+- `composition` — structural techniques (transition patterns, arrangement gestures, motif transformations)
+- `automation` — automation curves and recipes
+- `performance` — live performance patterns (scene orderings, safe macro ranges)
+
+## Anti-Preferences
+
+Anti-preferences are the inverse of promotion — they record moves the user explicitly rejected.
+
+### Recording
+
+Call `record_anti_preference(description)` when:
+- The user says "I hate that", "never do that again", "that's wrong"
+- A move is undone and the user expresses displeasure (not just neutral undo)
+- The user explicitly states a preference against a technique
+
+### Checking
+
+Call `get_anti_preferences` before suggesting any move. The response lists all recorded anti-preferences with descriptions and creation dates.
+
+### Format
+```json
+{
+  "anti_preferences": [
+    {
+      "id": "ap_001",
+      "description": "Never boost above 10 kHz on vocals — user finds it harsh",
+      "created": "2026-04-08T14:30:00Z"
+    },
+    {
+      "id": "ap_002",
+      "description": "No sidechain compression on pads — user prefers volume automation for ducking",
+      "created": "2026-04-09T09:15:00Z"
+    }
+  ]
+}
+```
+
+### Rules
+
+1. Always check anti-preferences before planning any move
+2. If a planned move matches an anti-preference, skip it and choose an alternative
+3. Anti-preferences are permanent until the user explicitly asks to remove one
+4. When skipping a move due to anti-preference, tell the user: "Skipping [move] because you previously indicated [anti-preference]."
+
+## Promotion Best Practices
+
+1. **Do not auto-promote.** Always ask: "That scored [score] — want me to save this technique?"
+2. **Include context in the saved data.** A raw parameter value without context (genre, source material, goal) is less useful on recall.
+3. **Group related moves.** If three EQ cuts together solved a masking problem, save them as one technique, not three.
+4. **Tag with genre and role.** A bass EQ technique for house music may not apply to jazz. Include tags for future filtering.
+5. **Review periodically.** Suggest `memory_list` to the user occasionally to prune outdated techniques.
+
+## Recall Integration
+
+When starting a new production task:
+
+1. Call `memory_recall(type, query)` to find relevant past techniques
+2. Present matches with their past scores: "I found a similar technique from a past session (scored 0.85). Want me to try it here?"
+3. If the user agrees, apply the recalled technique and evaluate as normal
+4. If the recalled technique scores lower in the new context, note this — context sensitivity means not all techniques transfer