livepilot 1.4.1 → 1.4.4

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "livepilot": {
+      "command": "node",
+      "args": ["bin/livepilot.js"],
+      "cwd": "/Users/visansilviugeorge/Desktop/LivePilot"
+    }
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [1.4.4] — 2026-03-18
+
+### Fixes
+- **`find_and_load_device` breadth-first search** — Pass 0 instant top-level check finds raw devices like "Operator", "Auto Filter", "Limiter" in O(50) instead of O(thousands). Falls back to breadth-first recursive search for nested items
+- **Better "no devices" error message** — `get_device_parameters` on an empty track now says "Track 'BASS' has no devices — load an instrument or effect first" instead of the confusing "Device index 0 out of range (0..-1)"
+
+## [1.4.3] — 2026-03-18
+
+### Fixes
+- **`find_and_load_device` now finds raw instruments** — two-pass search: exact name match first (finds "Operator" before "Hello Operator.adg"), then partial match for M4L devices (e.g., "Kickster" matches "trnr.Kickster")
+- **Browser now searches plugins and Max for Live categories** — added `browser.plugins` and `browser.max_for_live` to all browser operations. AU/VST/AUv3 plugins (Moog, Drambo, BYOD, etc.) are now discoverable and loadable via `find_and_load_device` and `search_browser("plugins")`
+- **`load_browser_item` handles Sounds FileId URIs** — URIs containing internal FileId references (e.g., `query:Sounds#Pad:FileId_6343`) now trigger a deep URI search instead of failing with "not found"
+- **`load_browser_item` URI category prioritization** — parses category hint from URI (e.g., `query:Drums#...` searches drums first), reducing search time from 10K+ iterations to under 1K for most loads
+- **Iteration limit increased** — `load_browser_item` and `load_device_by_uri` now search up to 50K iterations (was 10K), preventing timeouts on large browser categories
+- **Case-insensitive parameter matching** — `set_device_parameter` and `batch_set_parameters` now try exact match first, then case-insensitive fallback. Error messages list available parameter names for debugging
+- **Track index validation relaxed** — `_validate_track_index` in arrangement, browser, clips, notes, and tracks MCP tools now allows negative indices for return tracks (-1=A, -2=B) and -1000 for master, consistent with the remote script's `get_track()` behavior
+
+### Added
+- `search_browser("plugins")` — browse all installed AU/VST/AUv3 plugins
+- `search_browser("max_for_live")` — browse all M4L devices directly
+- `search_browser("clips")` and `search_browser("current_project")` — additional browser categories
+
+## [1.4.2] — 2026-03-18
+
+### Fixes
+- `memory_recall` multi-word search now works — queries are split into words and matched across name, tags, and qualities (was treating entire query as single substring)
+- `set_session_loop` returns correct loop state — echoes requested value instead of reading stale LOM property
+- `jump_to_time` returns correct position — echoes requested beat_time instead of reading stale `current_song_time`
+
 ## [1.4.1] — 2026-03-18
 
 ### Fixes

package/README.md

@@ -19,33 +19,41 @@ Every command goes through Ableton's official Live Object Model API. No hacks, n
 
 ---
 
-## Train Your Own AI Producer
+## Agent & Technique Memory
 
-LivePilot ships with 104 tools and a deep reference corpus — genre-specific drum patterns, chord voicings, sound design recipes, mixing templates, song structures. Day one, it already knows how music works. But the tools are just the starting point.
+LivePilot is stateless by default — 104 tools, deterministic execution, no hidden context. The agent layer adds **persistent state** on top: a technique memory system that stores production decisions as typed, searchable, replayable data structures with structured metadata.
 
-**The real product is the agent you build on top of them.**
+### How it works
 
-Every producer has a sonic identity — the swing amounts they reach for, the drum kits that feel right, the FX chains they keep coming back to, the way they EQ a vocal bus. Most AI tools ignore all of this. Every session starts blank. LivePilot is different: it has a technique memory system that turns your production decisions into a persistent, searchable stylistic palette the agent learns from over time.
+The memory system stores five technique types: `beat_pattern`, `device_chain`, `mix_template`, `preference`, and `browser_pin`. Each technique consists of three layers:
 
-Here's how you train it:
+| Layer | Contents | Purpose |
+|-------|----------|---------|
+| **Identity** | UUID, name, type, tags, timestamps, rating, replay count | Indexing, filtering, sorting |
+| **Qualities** | Structured analysis — summary, mood, genre tags, rhythm feel, harmonic character, sonic texture, production notes, reference points | Search ranking, agent context at decision time |
+| **Payload** | Raw data — MIDI notes, device params, tempo, kit URIs, send levels | Exact replay or adaptation |
 
-1. **Produce something you like** — a beat, a device chain, a mixing setup, a synth patch
-2. **Tell the agent to save it** — "remember this groove" / "save this reverb chain"
-3. **The agent writes a stylistic analysis** — not just raw MIDI data, but *what makes it work*: the rhythmic feel, the sonic texture, the mood, what it pairs with, what artists it evokes
-4. **Your library grows** — rate and favorite the best techniques, tag them by genre or mood, build categories
-5. **The agent develops taste** — next time you say "make me a beat", it checks your library, reads your tendencies, and creates something new that sounds like you
+When you save a technique, the agent collects raw data from Ableton using existing tools (`get_notes`, `get_device_parameters`, etc.) and writes a structured qualities analysis. The qualities are what make search useful — `memory_recall(query="dark heavy 808")` matches against mood, genre tags, sonic texture, and summary fields, not just names.
 
-This isn't a preset recall system. The agent doesn't copy stored patterns — it understands the *qualities* across your saved techniques (the swing you prefer, the harmonic language you gravitate toward, the density of your arrangements) and uses that understanding to inform new creative decisions.
+### Three operating modes
 
-**Three modes, always under your control:**
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| **Informed** (default) | Any creative task | Agent calls `memory_recall`, reads top results' qualities, lets them influence decisions (kit selection, parameter ranges, rhythmic density) without copying |
+| **Fresh** | "ignore my history" / "something new" | Agent skips memory entirely — uses only the shipped reference corpus and its own knowledge |
+| **Explicit recall** | "use that boom bap beat" / "load my reverb chain" | Direct retrieval via `memory_get` → `memory_replay` with `adapt=false` (exact) or `adapt=true` (variation) |
 
-- **Informed** (default) — the agent consults your memory and lets it influence creative choices naturally
-- **Fresh** — "ignore my history" / "something completely new" — blank slate, pure musical knowledge, zero influence from saved techniques
-- **Explicit recall** — "use that boom bap beat I saved" — direct retrieval and replay
+The agent consults memory by default but never constrains itself to it. Override is always one sentence away.
 
-The memory is both a drawer and a personality. You put things in, you take things out, and the agent develops taste from what you've collected — but you can always tell it to forget everything and start fresh.
+### Replay architecture
 
-**You're not configuring software. You're building a creative partner that gets better the more you use it.**
+`memory_replay` does not execute Ableton commands directly. It returns a structured plan — an ordered list of tool calls (`search_browser`, `load_browser_item`, `create_clip`, `add_notes`, etc.) that the agent then executes through the existing MCP tools. This keeps the memory system decoupled from the Ableton connection and makes replay logic testable without a running DAW.
+
+### Building the corpus over time
+
+The shipped plugin includes a reference corpus (~2,700 lines): genre-specific drum patterns, chord voicings, sound design recipes, mixing templates, and workflow patterns. This is the baseline — the agent is competent from the first session.
+
+The technique memory extends this with user-specific data. As you save techniques, rate them, and tag them, the library becomes a structured representation of your production preferences. The agent reads across saved qualities at decision time — not to copy stored patterns, but to understand tendencies: swing ranges, kit preferences, harmonic language, arrangement density. New output is always generated; the memory informs the generation.
 
 ---
 
@@ -269,7 +277,7 @@ npx -y github:dreamrec/LivePilot --status
 
 ## Claude Code Plugin
 
-The plugin turns LivePilot from a tool collection into a **production partner that learns your style**.
+The plugin adds a skill, an autonomous agent, and 5 slash commands on top of the MCP tools.
 
 ```bash
 claude plugin add github:dreamrec/LivePilot/plugin
@@ -283,23 +291,17 @@ claude plugin add github:dreamrec/LivePilot/plugin
 | `/beat` | Guided beat creation — genre, tempo, instrumentation |
 | `/mix` | Mixing assistant — levels, panning, sends |
 | `/sounddesign` | Sound design workflow — instruments, effects, presets |
-| `/memory` | Browse, search, and manage your saved technique library |
-
-### The Producer Agent
-
-The heart of the plugin. An autonomous agent that builds tracks from high-level descriptions like *"Make me a 126 BPM rominimal track in D minor with hypnotic percussion"*. It handles the full pipeline: planning the arrangement, creating tracks, loading instruments, programming patterns, adding effects, and mixing — with mandatory health checks to make sure every track actually produces sound.
-
-What makes it different from a generic AI with tools is **what it knows**. The agent ships with a deep reference corpus — genre-specific drum patterns, chord voicings, sound design recipes, mixing templates, song structures — so it doesn't start from zero every time. It knows that a boom bap kick lands on beat 1 and the "and" of 2, that a Drum Rack needs a kit preset (not an empty shell), that a Saturator with Drive at 0 is a pass-through doing nothing.
+| `/memory` | Browse, search, and manage your technique library |
 
-But the shipped corpus is just the floor. The real value builds over time.
+### Producer Agent
 
-### Technique Memory
+Autonomous agent that executes multi-step production tasks from high-level descriptions. Handles the full pipeline: session planning, track creation, instrument loading, MIDI programming, effect configuration, and mixing — with mandatory health checks between each stage to verify every track produces audible output.
 
-8 tools for saving, searching, and replaying production techniques. Every saved technique includes a rich stylistic analysis written by the agent — not just raw data, but *what makes it work* and when to use it. See "Train Your Own AI Producer" above for how this shapes the agent over time.
+The agent ships with a 2,700-line reference corpus covering genre-specific drum patterns, chord voicings, sound design parameter recipes, mixing templates, and song structures. It consults the technique memory by default (see above), and can be overridden to work from a clean slate.
 
 ### Core Skill
 
-The `livepilot-core` skill teaches the AI how to work with Ableton properly: read session state before changing anything, verify after every write, check that instruments actually loaded, never invent device names. It's the difference between an AI that fumbles through the API and one that works like an experienced assistant.
+`livepilot-core` encodes operational discipline for the 104 tools: read state before writing, verify after every mutation, validate instrument loading (empty Drum Racks produce silence), never hallucinate device names (always `search_browser` first), use negative track indices for return tracks. Without it, an LLM with access to the tools will produce silent tracks and load wrong devices.
 
 ---
 

package/mcp_server/memory/technique_store.py

@@ -124,19 +124,13 @@ class TechniqueStore:
             tag_set = set(tags)
             results = [t for t in results if tag_set & set(t.get("tags", []))]
 
-        # text search
+        # text search — all query words must appear somewhere in the technique
         if query:
-            q = query.lower()
+            words = query.lower().split()
             filtered = []
             for t in results:
-                if q in t["name"].lower():
-                    filtered.append(t)
-                    continue
-                if any(q in tag.lower() for tag in t.get("tags", [])):
-                    filtered.append(t)
-                    continue
-                # search all qualities fields
-                if self._matches_qualities(t.get("qualities", {}), q):
+                searchable = self._searchable_text(t)
+                if all(w in searchable for w in words):
                     filtered.append(t)
             results = filtered
 
@@ -255,15 +249,16 @@ class TechniqueStore:
         raise ValueError(f"NOT_FOUND: technique '{technique_id}' does not exist")
 
     @staticmethod
-    def _matches_qualities(qualities: dict, query: str) -> bool:
-        for v in qualities.values():
-            if isinstance(v, str) and query in v.lower():
-                return True
-            if isinstance(v, list):
-                for item in v:
-                    if isinstance(item, str) and query in item.lower():
-                        return True
-        return False
+    def _searchable_text(t: dict) -> str:
+        """Build a single lowercase string from all searchable fields."""
+        parts = [t.get("name", "")]
+        parts.extend(t.get("tags", []))
+        for v in t.get("qualities", {}).values():
+            if isinstance(v, str):
+                parts.append(v)
+            elif isinstance(v, list):
+                parts.extend(str(item) for item in v)
+        return " ".join(parts).lower()
 
     @staticmethod
     def _multi_sort(results: list[dict]) -> list[dict]:

package/mcp_server/tools/arrangement.py

@@ -19,6 +19,7 @@ def _get_ableton(ctx: Context):
 
 
 def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
     if track_index < 0:
         raise ValueError("track_index must be >= 0")
 

package/mcp_server/tools/browser.py

@@ -18,6 +18,7 @@ def _get_ableton(ctx: Context):
 
 
 def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
     if track_index < 0:
         raise ValueError("track_index must be >= 0")
 
@@ -49,6 +50,9 @@ def search_browser(
 ) -> dict:
     """Search the browser tree under a path, optionally filtering by name.
 
+    path:        top-level category to search under. Valid categories:
+                 instruments, audio_effects, midi_effects, sounds, drums,
+                 samples, packs, user_library, plugins, max_for_live, clips
     max_depth:   how deep to recurse into subfolders (default 8)
     max_results: maximum number of results to return (default 100)
     """

package/mcp_server/tools/clips.py

@@ -18,6 +18,7 @@ def _get_ableton(ctx: Context):
 
 
 def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
     if track_index < 0:
         raise ValueError("track_index must be >= 0")
 

package/mcp_server/tools/notes.py

@@ -26,6 +26,7 @@ def _ensure_list(value: Any) -> list:
 
 
 def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
     if track_index < 0:
         raise ValueError("track_index must be >= 0")
 

package/mcp_server/tools/tracks.py

@@ -18,6 +18,7 @@ def _get_ableton(ctx: Context):
 
 
 def _validate_track_index(track_index: int):
+    """Validate track index. Must be >= 0 for regular tracks."""
     if track_index < 0:
         raise ValueError("track_index must be >= 0")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.4.1",
+  "version": "1.4.4",
   "mcpName": "io.github.dreamrec/livepilot",
   "description": "AI copilot for Ableton Live 12 — 104 MCP tools for music production, sound design, and mixing",
   "author": "Pilot Studio",

package/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.4.1",
+  "version": "1.4.4",
   "description": "AI copilot for Ableton Live 12 — 104 MCP tools for music production, sound design, and mixing",
   "author": "Pilot Studio",
   "skills": [

package/plugin/skills/livepilot-core/references/device-atlas/00-index.md

@@ -0,0 +1,110 @@
+# Device Atlas — Master Index
+
+> Last updated: 2026-03-18 | 10,600+ lines | 330+ devices | 139 drum kits | 350+ IRs | 1,850+ presets mapped
+
+## How to Use This Atlas
+
+**Agent loading strategy:**
+1. Read this index first to understand what's available
+2. Based on the user's request, load only the relevant 1-2 category files
+3. For compound requests ("add compression and reverb"), load both relevant files
+4. For vibe-based requests ("make it darker"), load `presets-by-vibe.md`
+5. Always verify device existence via `search_browser` before loading — the atlas tells you WHAT and WHY, the browser confirms it EXISTS
+
+## Atlas Files
+
+### Sound Processing
+
+| File | Scope | Devices | Lines |
+|------|-------|---------|-------|
+| [dynamics-and-punch.md](dynamics-and-punch.md) | Compressors, limiters, gates, transient shapers | 21 (6 native + 15 M4L) | 525 |
+| [distortion-and-character.md](distortion-and-character.md) | Saturators, fuzz, amp sims, tape, IRs | 17 + 350 IRs | 687 |
+| [space-and-depth.md](space-and-depth.md) | Reverbs, delays, diffusion, spatial | 19 (12 native + 7 M4L) | 571 |
+| [movement-and-modulation.md](movement-and-modulation.md) | Chorus, phaser, LFOs, tremolo, auto-pan | 21 (5 native + 16 M4L) | 874 |
+| [spectral-and-weird.md](spectral-and-weird.md) | Granular, glitch, spectral, experimental | 40 (5 native + 35 M4L) | 714 |
+| [eq-and-filtering.md](eq-and-filtering.md) | EQs, filters, resonators, vocoder | 13 (8 native + 5 M4L) | 402 |
+
+### Sound Generation
+
+| File | Scope | Devices | Lines |
+|------|-------|---------|-------|
+| [synths-native.md](synths-native.md) | All 11 Ableton instruments in depth | 11 native | 953 |
+| [synths-m4l.md](synths-m4l.md) | Fors, Mutable Instruments, Sonus Dept, Spektro, etc. | 34 M4L | 730 |
+| [plugins-synths.md](plugins-synths.md) | AU/VST plugin synths, samplers, drum machines, effects, MIDI tools | 49 entries (85+ plugins) | 1,300+ |
+| [drums-and-percussion.md](drums-and-percussion.md) | Drum Rack, DS synths, kits by genre, M4L drum tools | 18 + 139 kits | 753 |
+
+### MIDI & Composition
+
+| File | Scope | Devices | Lines |
+|------|-------|---------|-------|
+| [midi-tools.md](midi-tools.md) | Arpeggiators, chord tools, sequencers, generative | 45 (13 native + 32 M4L) | 963 |
+
+### Workflow & Utility
+
+| File | Scope | Devices | Lines |
+|------|-------|---------|-------|
+| [utility-and-workflow.md](utility-and-workflow.md) | Meters, mapping, routing, QOL tools | 42 (3 native + 39 M4L) | 843 |
+
+### Cross-References
+
+| File | Scope | Lines |
+|------|-------|-------|
+| [samples-and-irs.md](samples-and-irs.md) | 3,889 samples + Encoder Audio Mojo IR guide | 597 |
+| [presets-by-vibe.md](presets-by-vibe.md) | 14 vibe categories mapping natural language → devices/presets | 727 |
+
+## Quick Routing Guide
+
+**User says something about...** → **Load this file:**
+
+| Request Pattern | Primary File | Secondary File |
+|----------------|-------------|----------------|
+| "make it punchier / harder / tighter" | dynamics-and-punch | distortion-and-character |
+| "add warmth / grit / saturation / fuzz" | distortion-and-character | dynamics-and-punch |
+| "more space / depth / reverb / delay / echo" | space-and-depth | — |
+| "add movement / modulation / wobble / pulse" | movement-and-modulation | — |
+| "glitch / granular / freeze / spectral / weird" | spectral-and-weird | — |
+| "EQ / filter / tone / brighten / darken" | eq-and-filtering | — |
+| "I need a synth / bass / pad / lead" | synths-native | synths-m4l, plugins-synths |
+| "Moog / Drambo / granular / modular / DX7 / sampler plugin" | plugins-synths | — |
+| "drums / beats / kick / snare / hat" | drums-and-percussion | — |
+| "arpeggio / chord / sequence / generative / random" | midi-tools | — |
+| "meter / gain / routing / utility / organize" | utility-and-workflow | — |
+| "dark / ethereal / aggressive / lo-fi / cinematic" | presets-by-vibe | (then load the relevant device file) |
+| "sample / one-shot / loop / IR / convolution" | samples-and-irs | — |
+| "what M4L devices do I have for X" | (search relevant category) | utility-and-workflow |
+
+## Scope Notes
+
+- **[universal]** files: synths-native, eq-and-filtering (native sections), dynamics-and-punch (native sections), space-and-depth (native sections), movement-and-modulation (native sections)
+- **[user-library]** files: All M4L device entries, drums-and-percussion (kit guide), samples-and-irs, presets-by-vibe, utility-and-workflow (M4L sections), synths-m4l, spectral-and-weird (M4L sections)
+- Always `search_browser` to verify M4L device availability before attempting to load
+- The atlas is a strong hint system, not a guarantee — when in doubt, discover via `get_device_parameters`
+
+## M4L Collection Mapping
+
+| Collection | Location in User Library | Atlas Coverage |
+|-----------|------------------------|----------------|
+| CLX_01 (QOL GUI) | MAX MONTY/_CLX_01 | utility-and-workflow |
+| CLX_02 (FX) | MAX MONTY/_CLX_02 | dynamics, distortion, space, eq, movement |
+| CLX_03 (MIDI) | MAX MONTY/_CLX_03 | midi-tools |
+| CLX_04 (GEN) | MAX MONTY/_CLX_04 | spectral-and-weird, synths-m4l |
+| CLX_05 (MOD) | MAX MONTY/_CLX_05 | movement-and-modulation |
+| Fors | MAX MONTY/M4L_fors | synths-m4l, space-and-depth |
+| Mutable Instruments | MAX MONTY/M4L_Mutable Instruments | synths-m4l, midi-tools |
+| Sonus Dept | MAX MONTY/M4L_Sonus Dept | synths-m4l, spectral-and-weird |
+| Confetti | MAX MONTY/M4L_Confetti | spectral-and-weird |
+| J74 | MAX MONTY/M4L_J74 | midi-tools |
+| Isotonik | MAX MONTY/M4L_Isotonik Studios | spectral-and-weird |
+| Altar of Wisdom | MAX MONTY/M4L_Altar of Wisdom | spectral-and-weird |
+| Oscilloscopemusic | MAX MONTY/M4L_Oscilloscopemusic | spectral-and-weird |
+| Soundmanufacture | MAX MONTY/M4L_Soundmanufacture | midi-tools |
+| Robert Henke | MAX MONTY/Robert Henke | utility-and-workflow, spectral-and-weird |
+| Suzuki Kentaro | MAX MONTY/M4L_Suzuki Kentaro | utility-and-workflow |
+| trnr | MAX MONTY/m4l_2024/_CLX_02/trnr | drums-and-percussion, distortion-and-character |
+| pATCHES | MAX MONTY/M4L_pATCHES | utility-and-workflow |
+| S8JFOU | MAX MONTY/M4L_S8JFOU | utility-and-workflow |
+| alexkid | MAX MONTY/M4L_alexkid | utility-and-workflow |
+| Slink | MAX MONTY/M4L_Slink Devices | movement-and-modulation |
+| Iris | MAX MONTY/rem4llives | movement-and-modulation |
+| All MIDI Tools | MAX MONTY/2024_august | midi-tools |
+| Encoder Audio Mojo | MAX MONTY/_CLX_02/Encoder Audio Mojo | distortion-and-character, samples-and-irs |