livepilot 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.4.0] — 2026-03-18
+
+### Added
+- **Technique Memory System** — 8 new MCP tools (`memory_learn`, `memory_recall`, `memory_get`, `memory_replay`, `memory_list`, `memory_favorite`, `memory_update`, `memory_delete`) for persistent technique storage with agent-written stylistic qualities
+- Memory guide reference (`references/memory-guide.md`) with qualities template and examples
+- `/memory` command for browsing the technique library
+- Producer agent now consults memory by default before creative decisions (override with "fresh" / "ignore history")
+- Three memory modes: Informed (default), Fresh (override), Explicit Recall
+
+### Changed
+- Tool count: 96 → 104 (10 domains, was 9)
+- Commands: 4 → 5 (added /memory)
+
+## 1.3.0 — 2026-03-17
+
+### Enhancements
+- **Device tools now support return tracks and master track** — use negative `track_index` for return tracks (-1=A, -2=B) and -1000 for master track. Works with all 12 device tools: `get_device_info`, `get_device_parameters`, `set_device_parameter`, `batch_set_parameters`, `toggle_device`, `delete_device`, `load_device_by_uri`, `find_and_load_device`, `get_rack_chains`, `set_simpler_playback_mode`, `set_chain_volume`, `get_device_presets`
+- **Mixing tools now support return tracks** — `set_track_volume`, `set_track_pan`, `get_track_routing`, `set_track_routing` accept negative indices for return tracks
+- Fixed `quantize_clip` grid parameter documentation — was incorrectly documented as float beats, now correctly documented as integer enum (0-8)
+- Fixed tempo range typo in SKILL.md (was 20-969, corrected to 20-999)
+
 ## 1.2.1 — 2026-03-17
 
 ### Fixes

package/README.md

@@ -11,18 +11,44 @@
 [![CI](https://github.com/dreamrec/LivePilot/actions/workflows/ci.yml/badge.svg)](https://github.com/dreamrec/LivePilot/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/dreamrec/LivePilot)](https://github.com/dreamrec/LivePilot/stargazers)
 
-**AI copilot for Ableton Live 12** — 96 MCP tools for music production, sound design, and mixing.
+**AI copilot for Ableton Live 12** — 104 MCP tools for music production, sound design, and mixing.
 
-Control your entire Ableton session through natural language. Create tracks, program MIDI, load instruments, tweak parameters, arrange songs, and mix — all without leaving the keyboard.
+Talk to your DAW. Create tracks, program MIDI, load instruments, tweak parameters, arrange songs, and mix — all through natural language. LivePilot connects any MCP-compatible AI client (Claude, Cursor, VS Code Copilot) to Ableton Live and gives it full control over your session.
+
+Every command goes through Ableton's official Live Object Model API. No hacks, no injection — the same interface Ableton's own control surfaces use. Everything is deterministic and reversible with undo.
+
+---
+
+## Build Your Own AI Producer
+
+LivePilot isn't just a tool collection — it's a framework for building **your own personalized AI production partner**.
+
+Out of the box, the agent ships with a deep reference corpus: genre-specific drum patterns, chord voicings, sound design recipes, mixing templates, song structures. It knows how music works. But that's just the starting point.
+
+**The real power is training it to work like you.**
+
+Every time you produce something you like — a beat, a device chain, a mixing setup — you tell the agent to remember it. It doesn't just store raw data. It writes a rich stylistic analysis: *what makes this groove feel the way it does, what the sonic texture is, what it pairs with, what artists it evokes.* Over sessions, your saved techniques become a **stylistic fingerprint** the agent understands and draws from.
+
+Here's how you build your agent's palette:
+
+- **Save beats you like** — "remember this groove" — the agent captures the pattern AND analyzes why it works
+- **Pin your go-to sounds** — "save this reverb chain" — instant recall next time, with context about when to use it
+- **Set preferences** — "I always want Utility on every track" — the agent adapts its workflow to match yours
+- **Curate over time** — rate, favorite, and refine saved techniques — the best ones float to the top
+
+The next time you say "make me a beat", the agent checks your library. It doesn't copy — it reads your tendencies (the swing you like, the kits you reach for, your harmonic language) and creates something **new that sounds like you**. Say "ignore my history" and it starts fresh. Say "use that boom bap groove" and it replays exactly what you saved.
+
+**You're not configuring software. You're building a creative relationship.**
 
 ---
 
 ## What You Can Do
 
 - **Produce** — Create tracks, load instruments, program drum patterns, bass lines, chord progressions, and melodies
-- **Arrange** — Build full song structures in arrangement view with MIDI note editing, cue points, and timeline navigation
-- **Design sounds** — Browse Ableton's library, load presets, tweak device parameters, chain effects
-- **Mix** — Set levels, panning, sends, and routing. Run diagnostics to catch silent tracks and mute leftovers
+- **Arrange** — Build full song structures in arrangement view with MIDI editing, cue points, automation, and timeline navigation
+- **Design sounds** — Browse Ableton's library, load presets, tweak every device parameter, chain effects
+- **Mix** — Set levels, panning, sends, and routing across all track types including return tracks and master. Run diagnostics to catch silent tracks and stale solos
+- **Remember and evolve** — Save techniques, build a personal style library, and let the agent learn your taste over time
 - **Iterate fast** — Transpose, humanize, quantize, duplicate, and reshape patterns through conversation
 
 ---
@@ -70,9 +96,9 @@ claude plugin add github:dreamrec/LivePilot/plugin
 </details>
 
 <details>
-<summary><strong>Claude Desktop</strong></summary>
+<summary><strong>Claude Desktop (macOS)</strong></summary>
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -89,6 +115,32 @@ Restart Claude Desktop after saving.
 
 </details>
 
+<details>
+<summary><strong>Claude Desktop (Windows)</strong></summary>
+
+On Windows, `npx` can cause EBUSY file-locking errors. Install globally instead:
+
+```cmd
+npm install -g github:dreamrec/LivePilot
+livepilot --install
+```
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "LivePilot": {
+      "command": "livepilot"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+</details>
+
 <details>
 <summary><strong>Cursor</strong></summary>
 
@@ -156,7 +208,7 @@ npx -y github:dreamrec/LivePilot --status
 
 ---
 
-## 96 Tools Across 9 Domains
+## 104 Tools Across 10 Domains
 
 | Domain | Tools | What you can do |
 |--------|:-----:|-----------------|
@@ -164,11 +216,12 @@ npx -y github:dreamrec/LivePilot --status
 | **Tracks** | 14 | Create MIDI/audio/return tracks, name, color, mute, solo, arm, group fold, input monitoring |
 | **Clips** | 11 | Create, delete, duplicate, fire, stop, loop settings, launch mode, warp mode |
 | **Notes** | 8 | Add/get/remove/modify MIDI notes, transpose, quantize, duplicate |
-| **Devices** | 12 | Load instruments & effects, tweak parameters, rack chains, presets |
+| **Devices** | 12 | Load instruments & effects, tweak parameters, rack chains, presets — works on regular, return, and master tracks |
 | **Scenes** | 8 | Create, delete, duplicate, fire, rename, color, per-scene tempo |
-| **Mixing** | 8 | Volume, pan, sends, routing, return tracks, master |
+| **Mixing** | 8 | Volume, pan, sends, routing — return tracks and master fully supported |
 | **Browser** | 4 | Search Ableton's library, browse categories, load presets |
 | **Arrangement** | 19 | Create clips, full MIDI note CRUD, cue points, recording, automation |
+| **Memory** | 8 | Save, recall, replay, and manage production techniques |
 
 <details>
 <summary><strong>Full tool list</strong></summary>
@@ -200,13 +253,22 @@ npx -y github:dreamrec/LivePilot --status
 ### Arrangement (19)
 `get_arrangement_clips` · `create_arrangement_clip` · `add_arrangement_notes` · `get_arrangement_notes` · `remove_arrangement_notes` · `remove_arrangement_notes_by_id` · `modify_arrangement_notes` · `duplicate_arrangement_notes` · `transpose_arrangement_notes` · `set_arrangement_clip_name` · `set_arrangement_automation` · `back_to_arranger` · `jump_to_time` · `capture_midi` · `start_recording` · `stop_recording` · `get_cue_points` · `jump_to_cue` · `toggle_cue_point`
 
+### Memory (8)
+`memory_learn` · `memory_recall` · `memory_get` · `memory_replay` · `memory_list` · `memory_favorite` · `memory_update` · `memory_delete`
+
 </details>
 
 ---
 
 ## Claude Code Plugin
 
-The plugin adds production-focused skills, slash commands, and an autonomous producer agent.
+The plugin turns LivePilot from a tool collection into a **production partner that learns your style**.
+
+```bash
+claude plugin add github:dreamrec/LivePilot/plugin
+```
+
+### Commands
 
 | Command | Description |
 |---------|-------------|
@@ -214,8 +276,60 @@ The plugin adds production-focused skills, slash commands, and an autonomous pro
 | `/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.
 
-**Producer Agent** — An autonomous agent that builds tracks from high-level descriptions like *"Make me a 126 BPM rominimal track in D minor with hypnotic percussion"*.
+But the shipped corpus is just the floor. The real value builds over time.
+
+### Technique Memory — Your Evolving Stylistic Palette
+
+Most AI music tools are stateless — every session starts blank. LivePilot remembers.
+
+When you make something you like — a beat, a device chain, a mixing setup, a favorite preset — you tell the agent to save it. But it doesn't just store the raw MIDI data or parameter values. It writes a **stylistic analysis**: what makes this groove feel the way it does, what the sonic character is, what it pairs well with, what artists or styles it evokes. Over time, your saved techniques become a **stylistic fingerprint** — a palette the agent understands.
+
+The next time you say "make me a beat", the agent checks your library first. It doesn't copy a stored pattern — it reads across your saved techniques, understands your tendencies (the swing amounts you like, the kits you reach for, your harmonic language), and creates something **new that sounds like you**. It's the difference between an assistant that follows instructions and one that knows your taste.
+
+Three modes, always under your control:
+
+- **Informed** (default) — the agent consults your memory and lets it influence creative choices
+- **Fresh** — say "ignore my history" and the agent starts with a blank slate, pure musical knowledge
+- **Explicit recall** — say "use that boom bap beat I saved" for direct retrieval and replay
+
+The memory is 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 override it.
+
+### 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.
+
+---
+
+## How It Compares
+
+| Feature | LivePilot | [AbletonMCP](https://github.com/ahujasid/ableton-mcp) | [Ableton MCP Extended](https://github.com/uisato/ableton-mcp-extended) |
+|---------|:---------:|:---------:|:---------:|
+| **Tools** | 104 | ~20 | ~50 |
+| **Arrangement view** | Full (clips, notes, cue points, automation) | No | Partial (automation "not perfect yet") |
+| **MIDI note editing** | Full CRUD with note IDs, probability, velocity deviation | Basic add/get | Add/get/modify |
+| **Device control** | Load, params, batch edit, rack chains, presets, Simpler modes | Load, basic params | Load, params |
+| **Browser search** | Tree navigation, path filtering, URI-based loading | Basic search | Search with categories |
+| **Mixing** | Volume, pan, sends, routing, master, diagnostics | Volume, pan | Volume, pan, sends |
+| **Undo support** | Full (begin/end_undo_step wrapping) | No | Partial |
+| **Session diagnostics** | Built-in health checks (armed tracks, solos, silent tracks) | No | No |
+| **Per-note probability** | Yes (Live 12 API) | No | No |
+| **Plugin/skills** | Claude Code plugin with 5 commands + producer agent | No | No |
+| **Voice generation** | No | No | Yes (ElevenLabs) |
+| **UDP low-latency mode** | No (TCP, reliable) | No | Yes (experimental) |
+| **Protocol** | JSON/TCP, single-client, structured errors | JSON/TCP | JSON/TCP + UDP |
+| **Installation** | Auto-detect CLI (`--install`) | Manual copy | Manual copy |
+| **Live version** | Live 12 (modern note API) | Live 11+ | Live 11+ |
+| **License** | MIT | MIT | MIT |
+
+LivePilot focuses on **comprehensive, deterministic control** with safety nets (undo wrapping, diagnostics, verification patterns). It trades real-time parameter streaming (Extended's UDP mode) and external service integration (Extended's ElevenLabs) for deeper coverage of Ableton's core operations — especially arrangement, device management, and MIDI editing with Live 12's modern note API.
 
 ---
 
@@ -238,7 +352,9 @@ Claude / AI Client
 └─────────────────────┘
 ```
 
-Single-client TCP connection by design — Ableton's Live Object Model is not thread-safe.
+All commands execute on Ableton's main thread via `schedule_message` — the same thread that handles the UI. This guarantees consistency with what you see on screen. Single-client TCP by design, because Ableton's Live Object Model is not thread-safe.
+
+**Structured errors** with codes (`INDEX_ERROR`, `NOT_FOUND`, `INVALID_PARAM`, `STATE_ERROR`, `TIMEOUT`, `INTERNAL`) so the AI can understand what went wrong and recover.
 
 ---
 

package/bin/livepilot.js

@@ -16,9 +16,16 @@ const REQUIREMENTS = path.join(ROOT, "requirements.txt");
 // ---------------------------------------------------------------------------
 
 function findPython() {
-  for (const cmd of ["python3", "python"]) {
+  // On Windows, also try the "py -3" launcher which avoids the
+  // Microsoft Store stub that "python3" resolves to.
+  const candidates = process.platform === "win32"
+    ? ["python", "python3", "py"]
+    : ["python3", "python"];
+
+  for (const cmd of candidates) {
     try {
-      const out = execFileSync(cmd, ["--version"], {
+      const args = cmd === "py" ? ["-3", "--version"] : ["--version"];
+      const out = execFileSync(cmd, args, {
         encoding: "utf-8",
         timeout: 5000,
       }).trim();
@@ -26,8 +33,11 @@ function findPython() {
       if (match) {
         const major = parseInt(match[1], 10);
         const minor = parseInt(match[2], 10);
-        if (major === 3 && minor >= 10) {
-          return { cmd, version: out };
+        if (major === 3 && minor >= 9) {
+          // For "py" launcher, the actual command to use is "py -3"
+          const actualCmd = cmd === "py" ? "py" : cmd;
+          const actualArgs = cmd === "py" ? ["-3"] : [];
+          return { cmd: actualCmd, version: out, prefixArgs: actualArgs };
         }
       }
     } catch {
@@ -53,7 +63,8 @@ function venvPython() {
  * Ensure a local .venv exists with dependencies installed.
  * Returns the path to the venv Python binary.
  */
-function ensureVenv(systemPython) {
+function ensureVenv(systemPython, prefixArgs) {
+  const prefix = prefixArgs || [];
   const venvPy = venvPython();
 
   // Check if venv already exists and has our deps
@@ -67,10 +78,10 @@ function ensureVenv(systemPython) {
       return venvPy; // venv exists and fastmcp is importable
     } catch {
       // venv exists but deps missing — reinstall
-      console.log("LivePilot: reinstalling Python dependencies...");
+      console.error("LivePilot: reinstalling Python dependencies...");
       execFileSync(venvPy, ["-m", "pip", "install", "-q", "-r", REQUIREMENTS], {
         cwd: ROOT,
-        stdio: "inherit",
+        stdio: ["pipe", "pipe", "inherit"],
         timeout: 120000,
       });
       return venvPy;
@@ -78,17 +89,17 @@ function ensureVenv(systemPython) {
   }
 
   // Create venv from scratch
-  console.log("LivePilot: setting up Python environment (first run)...");
-  execFileSync(systemPython, ["-m", "venv", VENV_DIR], {
+  console.error("LivePilot: setting up Python environment (first run)...");
+  execFileSync(systemPython, [...prefix, "-m", "venv", VENV_DIR], {
     cwd: ROOT,
-    stdio: "inherit",
+    stdio: ["pipe", "pipe", "inherit"],
     timeout: 30000,
   });
 
-  console.log("LivePilot: installing dependencies...");
+  console.error("LivePilot: installing dependencies...");
   execFileSync(venvPython(), ["-m", "pip", "install", "-q", "-r", REQUIREMENTS], {
     cwd: ROOT,
-    stdio: "inherit",
+    stdio: ["pipe", "pipe", "inherit"],
     timeout: 120000,
   });
 
@@ -165,8 +176,8 @@ async function doctor() {
   if (pyInfo) {
     console.log("  Python: %s (%s)", pyInfo.version, pyInfo.cmd);
   } else {
-    console.log("  Python: NOT FOUND (need >= 3.10)");
-    console.log("    Fix: install Python 3.10+ and add to PATH");
+    console.log("  Python: NOT FOUND (need >= 3.9)");
+    console.log("    Fix: install Python 3.9+ and add to PATH");
     ok = false;
   }
 
@@ -326,9 +337,9 @@ async function main() {
   // Default: start MCP server
   const pyInfo = findPython();
   if (!pyInfo) {
-    console.error("Error: Python >= 3.10 is required but was not found.");
+    console.error("Error: Python >= 3.9 is required but was not found.");
     console.error("");
-    console.error("Install Python 3.10+ and ensure 'python3' or 'python' is on your PATH.");
+    console.error("Install Python 3.9+ and ensure 'python3' or 'python' is on your PATH.");
     console.error("  macOS:   brew install python@3.12");
     console.error("  Ubuntu:  sudo apt install python3");
     console.error("  Windows: https://www.python.org/downloads/");
@@ -338,7 +349,7 @@ async function main() {
   // Bootstrap venv and install deps automatically
   let pythonBin;
   try {
-    pythonBin = ensureVenv(pyInfo.cmd);
+    pythonBin = ensureVenv(pyInfo.cmd, pyInfo.prefixArgs);
   } catch (err) {
     console.error("Error: failed to set up Python environment.");
     console.error("  %s", err.message);

package/mcp_server/connection.py

@@ -1,11 +1,14 @@
 """TCP client for communicating with Ableton Live's Remote Script."""
 
+from __future__ import annotations
+
 import json
 import os
 import socket
 import time
 import uuid
 from collections import deque
+from typing import Optional
 
 CONNECT_TIMEOUT = 5
 RECV_TIMEOUT = 20
@@ -45,10 +48,10 @@ class AbletonConnection:
 
     MAX_LOG_ENTRIES = 50
 
-    def __init__(self, host: str | None = None, port: int | None = None):
+    def __init__(self, host: Optional[str] = None, port: Optional[int] = None):
         self.host = host or os.environ.get("LIVE_MCP_HOST", "127.0.0.1")
         self.port = port or int(os.environ.get("LIVE_MCP_PORT", "9878"))
-        self._socket: socket.socket | None = None
+        self._socket: Optional[socket.socket] = None
         self._recv_buf: bytes = b""
         self._command_log: deque[dict] = deque(maxlen=self.MAX_LOG_ENTRIES)
 
@@ -103,7 +106,7 @@ class AbletonConnection:
         except Exception:
             return False
 
-    def send_command(self, command_type: str, params: dict | None = None) -> dict:
+    def send_command(self, command_type: str, params: Optional[dict] = None) -> dict:
         """Send a command to Ableton and return the result dict.
 
         Retries once on socket errors with a fresh connection.

package/mcp_server/memory/__init__.py

@@ -0,0 +1,5 @@
+"""LivePilot technique memory — persistent storage for learned patterns."""
+
+from .technique_store import TechniqueStore
+
+__all__ = ["TechniqueStore"]