@stitchdb/cli 0.5.0 → 0.6.1

package/dist/cli.js

@@ -339,36 +339,8 @@ async function cmdAgent(args) {
 }
 // ── Threads — append / recall / current ───────────────────────────────────
 function inferThread() {
-    // Reasonable default: <git-repo-name>/<branch> if we're in a git repo,
-    // else the cwd's basename. Hooks call this to get a stable thread per project.
-    try {
-        const dir = process.cwd();
-        let cur = dir;
-        for (let i = 0; i < 8; i++) {
-            if (fs.existsSync(path.join(cur, '.git'))) {
-                const parent = path.dirname(cur);
-                const repoName = path.basename(cur);
-                let branch = 'main';
-                try {
-                    const head = fs.readFileSync(path.join(cur, '.git', 'HEAD'), 'utf8').trim();
-                    const m = head.match(/^ref:\s+refs\/heads\/(.+)$/);
-                    if (m)
-                        branch = m[1];
-                }
-                catch { /* detached */ }
-                return `${repoName}/${branch}`;
-                void parent;
-            }
-            const next = path.dirname(cur);
-            if (next === cur)
-                break;
-            cur = next;
-        }
-        return path.basename(dir);
-    }
-    catch {
-        return 'default';
-    }
+    // Single source of truth: `.stitch/project.json` if present, else cwd basename.
+    return inferThreadFor(process.cwd());
 }
 async function cmdThread(args) {
     const cfg = loadConfig();
@@ -448,6 +420,11 @@ async function cmdHook(args) {
     const cfg = loadConfig();
     if (!cfg.apiKey)
         return; // not logged in, silently skip
+    // When the Stitch CLI spawns its own `claude -p` (e.g. for distillation),
+    // we don't want THAT inner conversation logged as a user/assistant turn —
+    // it would pollute the project thread with the distill prompt and JSON.
+    if (process.env.STITCH_HOOKS_DISABLED === '1')
+        return;
     let raw = '';
     try {
         raw = await readStdinAll();
@@ -469,42 +446,43 @@ async function cmdHook(args) {
     // (which is the directory `claude` was launched from).
     const cwd = event?.cwd || process.cwd();
     const threadName = inferThreadFor(cwd) || 'default';
-    // ── SessionStart: inject prior context as additional context ──────────
+    // ── SessionStart: inject prior context (token-efficient) ─────────────
+    // Strategy: prefer distilled memories (dense facts) over raw turns. Only
+    // include raw turns for the last 5 to give the agent immediate continuation.
     if (eventName === 'SessionStart') {
         try {
             const stitch = client(cfg);
-            const projectTag = path.basename(cwd || process.cwd());
-            // Pull both: recent dialogue from the per-repo thread + relevant
-            // durable memories tagged with the project.
+            const projectTag = (threadName.split('/')[0] || threadName).toLowerCase();
             const [thread, memHits] = await Promise.all([
-                stitch.thread(threadName).recall({ last: 20 }).catch(() => ({ thread_id: '', recent: [], semantic: [] })),
-                stitch.recall(projectTag, { k: 5 }).catch(() => []),
+                stitch.thread(threadName).recall({ last: 5 }).catch(() => ({ thread_id: '', recent: [], semantic: [] })),
+                stitch.recall(projectTag, { k: 8 }).catch(() => []),
             ]);
             const lines = [];
-            lines.push('## Stitch — prior memory for this project');
-            lines.push('');
-            lines.push(`Thread: \`${threadName}\` · Workspace recall available via the \`stitch\` MCP server.`);
+            lines.push('<stitch-context>');
+            lines.push(`Project: ${threadName} · Stitch MCP server is available with tools: recall, remember, thread_recall, thread_append.`);
             lines.push('');
-            if (thread.recent && thread.recent.length > 0) {
-                lines.push('### Recent conversation (continue from here)');
-                for (const t of thread.recent.slice(-12)) {
-                    const txt = String(t.content || '').replace(/\n+/g, ' ').slice(0, 400);
-                    lines.push(`- **${t.role}**: ${txt}`);
+            if (Array.isArray(memHits) && memHits.length > 0) {
+                // Prefer distilled (auto-tagged) facts and decisions; fall back to anything else
+                const sortedMems = [...memHits].sort((a, b) => Number(b.score ?? 0) - Number(a.score ?? 0)).slice(0, 8);
+                lines.push('### Durable memories for this project');
+                for (const m of sortedMems) {
+                    const isAuto = Array.isArray(m.tags) && m.tags.includes('auto');
+                    const txt = String(m.content || '').replace(/\n+/g, ' ').slice(0, 350);
+                    lines.push(`- **[${m.kind}${isAuto ? '·auto' : ''}]** ${txt}`);
                 }
                 lines.push('');
             }
-            if (Array.isArray(memHits) && memHits.length > 0) {
-                lines.push('### Durable memories');
-                for (const m of memHits) {
-                    const txt = String(m.content || '').replace(/\n+/g, ' ').slice(0, 320);
-                    lines.push(`- **[${m.kind}]** ${txt}`);
+            if (thread.recent && thread.recent.length > 0) {
+                lines.push('### Most recent turns (continue from here)');
+                for (const t of thread.recent.slice(-5)) {
+                    const txt = String(t.content || '').replace(/\n+/g, ' ').slice(0, 300);
+                    lines.push(`- **${t.role}**: ${txt}`);
                 }
                 lines.push('');
             }
-            if (lines.length > 4) {
-                // Plain stdout is auto-injected as additionalContext for SessionStart.
-                process.stdout.write(lines.join('\n'));
-            }
+            lines.push('Call `recall` for deeper search or `thread_recall` for older turns when needed.');
+            lines.push('</stitch-context>');
+            process.stdout.write(lines.join('\n'));
         }
         catch { /* silent — never break a session start */ }
         return;
@@ -533,29 +511,55 @@ async function cmdHook(args) {
     catch {
         /* silent */
     }
+    // After Stop, opportunistically kick off a distillation pass in the
+    // background (fire-and-forget). Won't block the session; debouncing
+    // (cooldown + min-new-turns) is enforced inside maybeAutoDistill.
+    if (eventName === 'Stop') {
+        maybeAutoDistill(threadName).catch(() => { });
+    }
 }
+/**
+ * Derive a thread name for the project at `cwd`. Strategy:
+ *
+ *   1. Walk up looking for a `.stitch/project.json` containing { "thread": "x" }
+ *      — this is the authoritative cross-machine pin. Stays exactly the same
+ *      on every machine that has the file. Created by `stitch link`.
+ *   2. Fall back to the folder basename (which already works fine if the user
+ *      keeps the same folder name across their machines).
+ *
+ * Deliberately does NOT require git — works for any project structure.
+ */
 function inferThreadFor(cwd) {
     const dir = cwd && fs.existsSync(cwd) ? cwd : process.cwd();
     let cur = dir;
     for (let i = 0; i < 8; i++) {
-        if (fs.existsSync(path.join(cur, '.git'))) {
-            const repoName = path.basename(cur);
-            let branch = 'main';
+        const projectFile = path.join(cur, '.stitch', 'project.json');
+        if (fs.existsSync(projectFile)) {
             try {
-                const head = fs.readFileSync(path.join(cur, '.git', 'HEAD'), 'utf8').trim();
-                const m = head.match(/^ref:\s+refs\/heads\/(.+)$/);
-                if (m)
-                    branch = m[1];
+                const cfg = JSON.parse(fs.readFileSync(projectFile, 'utf8'));
+                if (cfg.thread && typeof cfg.thread === 'string')
+                    return cfg.thread;
             }
-            catch { /* detached */ }
-            return `${repoName}/${branch}`;
+            catch { /* malformed — fall through */ }
         }
         const next = path.dirname(cur);
         if (next === cur)
             break;
         cur = next;
     }
-    return path.basename(dir);
+    return path.basename(dir) || 'default';
+}
+function findProjectRoot(cwd) {
+    let cur = cwd;
+    for (let i = 0; i < 8; i++) {
+        if (fs.existsSync(path.join(cur, '.stitch', 'project.json')))
+            return cur;
+        const next = path.dirname(cur);
+        if (next === cur)
+            break;
+        cur = next;
+    }
+    return null;
 }
 function lastAssistantTextFromTranscript(transcriptPath) {
     if (!transcriptPath || !fs.existsSync(transcriptPath))
@@ -600,6 +604,310 @@ function lastAssistantTextFromTranscript(transcriptPath) {
     catch { /* ignore */ }
     return text;
 }
+// ── stitch link — pin a project's thread name so it's the same on every machine
+async function cmdLink(args) {
+    const positionals = positional(args);
+    const explicit = positionals[0];
+    const name = (explicit || path.basename(process.cwd()) || 'default').trim();
+    const dir = path.join(process.cwd(), '.stitch');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'project.json');
+    let cfg = {};
+    try {
+        cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch { }
+    cfg.thread = name;
+    cfg.linked_at = new Date().toISOString();
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
+    console.log(`Project pinned to thread "${name}"`);
+    console.log(`  → ${file}`);
+    console.log();
+    console.log('Commit `.stitch/project.json` to your repo (or sync the file across');
+    console.log('machines) so every machine pinning this project uses the same thread.');
+}
+// ── stitch distill — extract durable facts from recent conversation ─────────
+//
+// Uses the user's own `claude -p` to run a strict-JSON extraction prompt over
+// the last N turns of the project's thread. Each extracted fact becomes a
+// Stitch memory tagged `auto:true` so the user can review or wipe them later.
+//
+// Triggered manually (`stitch distill`), and automatically by the Stop hook
+// when conditions are met (cooldown + new-turn threshold).
+const DISTILL_STATE_FILE = path.join(CONFIG_DIR, 'distill-state.json');
+const DISTILL_COOLDOWN_MS = 30 * 60 * 1000; // don't distill more than once per 30 min
+const DISTILL_MIN_NEW_TURNS = 10; // need 10 new turns before bothering
+const DISTILL_BATCH_SIZE = 30; // turns per distillation pass
+function loadDistillState() {
+    try {
+        return JSON.parse(fs.readFileSync(DISTILL_STATE_FILE, 'utf8'));
+    }
+    catch {
+        return { threads: {} };
+    }
+}
+function saveDistillState(s) {
+    if (!fs.existsSync(CONFIG_DIR))
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(DISTILL_STATE_FILE, JSON.stringify(s, null, 2));
+}
+const DISTILL_PROMPT = `You are a memory distiller. Output ONLY a JSON array of memory objects. Be GENEROUS — capture every concrete fact about the project that future sessions will care about. Aim for 10–30 memories on a substantial conversation.
+
+Each memory is one atomic, self-contained statement (1–4 sentences) that someone reading it months later — without the conversation around it — will fully understand.
+
+Format:
+  [{"kind":"fact|decision|snippet|preference","content":"...","tags":["short","keywords"]}, ...]
+
+Capture:
+- fact        — anything concrete: file paths, endpoint URLs, commands, version
+                numbers, architecture, deployed services, schemas, dependencies,
+                bugs found, fixes shipped.
+- decision    — choices with rationale.
+- snippet     — reusable commands/config/code/CLI flags/env var names.
+- preference  — how the developer wants the AI to behave on this project.
+
+Skip pleasantries and questions still being explored. One atomic idea per
+memory — don't bundle. If truly nothing durable was discussed, output: [].
+Output the JSON array and nothing else — no prose, no markdown fences.
+
+Conversation:
+`;
+async function cmdDistill(args) {
+    if (hasFlag(args, ['--review']))
+        return distillReview(args);
+    if (hasFlag(args, ['--clear']))
+        return distillClear(args);
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const explicitThread = parseFlag(args, ['--thread', '-t']);
+    const thread = explicitThread || inferThread();
+    const dryRun = hasFlag(args, ['--dry-run']);
+    const batchSize = Number(parseFlag(args, ['--n']) || String(DISTILL_BATCH_SIZE));
+    console.log(`Distilling last ${batchSize} turns of "${thread}"…`);
+    // Pull recent turns from the thread.
+    const recall = await stitch.thread(thread).recall({ last: batchSize });
+    if (!recall.thread_id || recall.recent.length === 0) {
+        console.log('No turns to distill yet.');
+        return;
+    }
+    // Format conversation as plain text for the prompt.
+    const conversation = recall.recent
+        .map((t) => `[${t.role}] ${String(t.content || '').trim()}`)
+        .join('\n\n');
+    if (dryRun) {
+        console.log(`Would distill ${recall.recent.length} turns. Sample (first 200 chars):`);
+        console.log(conversation.slice(0, 200));
+        return;
+    }
+    const claudeBin = process.env.STITCH_CLAUDE_BIN || 'claude';
+    process.stdout.write(`  → asking ${claudeBin} -p to extract facts… `);
+    const fullPrompt = DISTILL_PROMPT + conversation;
+    // Pipe the prompt via stdin: long conversations blow past ARG_MAX when
+    // passed as `-p <prompt>`, and stdin avoids claude interpreting any
+    // prompt-internal characters as flags. `claude -p` with no value reads
+    // from stdin. STITCH_HOOKS_DISABLED stops our own _hook command from
+    // logging this nested distill conversation as project thread turns.
+    const result = await runWithStdin(claudeBin, ['-p'], fullPrompt, {
+        cwd: process.cwd(),
+        env: { STITCH_HOOKS_DISABLED: '1' },
+    });
+    // Debug capture: STITCH_DEBUG_DISTILL=1 writes raw stdout/stderr/prompt
+    // to /tmp so we can see exactly what claude actually returned.
+    if (process.env.STITCH_DEBUG_DISTILL === '1') {
+        const ts = Date.now();
+        const dbgDir = '/tmp';
+        try {
+            fs.writeFileSync(path.join(dbgDir, `stitch-distill-${ts}.prompt.txt`), fullPrompt);
+            fs.writeFileSync(path.join(dbgDir, `stitch-distill-${ts}.stdout.txt`), result.stdout);
+            fs.writeFileSync(path.join(dbgDir, `stitch-distill-${ts}.stderr.txt`), result.stderr);
+            console.log(`\n  [debug] wrote /tmp/stitch-distill-${ts}.{prompt,stdout,stderr}.txt`);
+        }
+        catch { /* ignore */ }
+    }
+    if (result.exit_code !== 0) {
+        console.log('failed');
+        console.error(result.stderr.trim().slice(0, 400));
+        process.exit(1);
+    }
+    const memories = parseDistillationOutput(result.stdout);
+    console.log(`extracted ${memories.length} memories`);
+    if (memories.length === 0) {
+        if (process.env.STITCH_DEBUG_DISTILL === '1') {
+            console.error('  [debug] claude stdout (first 600 chars):');
+            console.error('  ' + result.stdout.slice(0, 600).replace(/\n/g, '\n  '));
+        }
+        bumpDistillCooldown(thread);
+        return;
+    }
+    // Push each to Stitch as a memory with auto:true tag.
+    const projectTag = thread.split('/')[0] || thread;
+    let saved = 0;
+    for (const m of memories) {
+        try {
+            const tags = ['auto', 'auto:distill', `thread:${thread}`, `project:${projectTag}`, ...(m.tags || [])];
+            await stitch.remember(m.content, { kind: m.kind, tags });
+            saved++;
+        }
+        catch (e) {
+            console.error('  ! failed to save:', e.message);
+        }
+    }
+    console.log(`  saved ${saved}/${memories.length} to Stitch`);
+    bumpDistillCooldown(thread);
+}
+function bumpDistillCooldown(thread) {
+    const state = loadDistillState();
+    state.threads[thread] = {
+        lastDistilledAt: Date.now(),
+        lastTurnAt: Date.now(),
+        lastTurnCount: state.threads[thread]?.lastTurnCount ?? 0,
+    };
+    saveDistillState(state);
+}
+function parseDistillationOutput(stdout) {
+    // claude -p often wraps the array in markdown fences, prepends prose like
+    // "Here are the extracted memories:", or follows it with a sign-off line.
+    // Strategy: try several extraction modes from most-precise to most-lenient,
+    // returning the first one that parses to a non-empty valid array.
+    const text = stdout.trim();
+    if (!text)
+        return [];
+    const candidates = [];
+    // 1. Fenced ```json block
+    const fenced = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/i);
+    if (fenced)
+        candidates.push(fenced[1].trim());
+    // 2. The first `[ {` … last `} ]` window (skips prose-level stray brackets).
+    const objStart = text.indexOf('[');
+    const objEnd = text.lastIndexOf(']');
+    if (objStart !== -1 && objEnd > objStart) {
+        candidates.push(text.slice(objStart, objEnd + 1));
+    }
+    // 3. Largest `[\n{ ... }\n]` block via balanced scan from each `[`
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== '[')
+            continue;
+        let depth = 0;
+        let inStr = false;
+        let esc = false;
+        for (let j = i; j < text.length; j++) {
+            const ch = text[j];
+            if (esc) {
+                esc = false;
+                continue;
+            }
+            if (ch === '\\' && inStr) {
+                esc = true;
+                continue;
+            }
+            if (ch === '"') {
+                inStr = !inStr;
+                continue;
+            }
+            if (inStr)
+                continue;
+            if (ch === '[')
+                depth++;
+            else if (ch === ']') {
+                depth--;
+                if (depth === 0) {
+                    candidates.push(text.slice(i, j + 1));
+                    break;
+                }
+            }
+        }
+    }
+    const seen = new Set();
+    for (const cand of candidates) {
+        if (seen.has(cand))
+            continue;
+        seen.add(cand);
+        try {
+            const parsed = JSON.parse(cand);
+            if (!Array.isArray(parsed))
+                continue;
+            const valid = parsed.filter((m) => m && typeof m === 'object'
+                && typeof m.content === 'string' && m.content.length > 0
+                && typeof m.kind === 'string' && ['fact', 'decision', 'snippet', 'preference', 'note'].includes(m.kind));
+            if (valid.length > 0)
+                return valid;
+        }
+        catch { /* try next candidate */ }
+    }
+    return [];
+}
+async function distillReview(args) {
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const limit = Number(parseFlag(args, ['--limit']) || '20');
+    const all = await stitch.list({ limit: 200 });
+    const autos = all.filter((m) => m.tags.includes('auto'));
+    console.log(`${autos.length} auto-distilled memories (showing first ${limit}):\n`);
+    for (const m of autos.slice(0, limit)) {
+        const date = new Date(m.created_at).toISOString().slice(0, 19).replace('T', ' ');
+        console.log(`  ${m.id}  ${date}  [${m.kind}]`);
+        console.log(`    ${m.content.split('\n')[0].slice(0, 200)}`);
+        if (m.content.length > 200 || m.content.includes('\n'))
+            console.log(`    ...`);
+        console.log();
+    }
+    if (autos.length > limit)
+        console.log(`(${autos.length - limit} more — use --limit to see)`);
+}
+async function distillClear(args) {
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    const all = await stitch.list({ limit: 500 });
+    const autos = all.filter((m) => m.tags.includes('auto'));
+    if (autos.length === 0) {
+        console.log('No auto-distilled memories to clear.');
+        return;
+    }
+    if (!hasFlag(args, ['--yes', '-y'])) {
+        console.log(`Will soft-delete ${autos.length} auto-distilled memories. Re-run with --yes to confirm.`);
+        return;
+    }
+    let deleted = 0;
+    for (const m of autos) {
+        if (await stitch.forget(m.id))
+            deleted++;
+    }
+    console.log(`Cleared ${deleted} memories.`);
+}
+// Triggered from the Stop hook (fire-and-forget, never blocks the user).
+async function maybeAutoDistill(thread) {
+    const state = loadDistillState();
+    const meta = state.threads[thread] || { lastDistilledAt: 0, lastTurnAt: 0, lastTurnCount: 0 };
+    // Cool-down: don't distill more than once per 30 min per thread.
+    if (Date.now() - meta.lastDistilledAt < DISTILL_COOLDOWN_MS)
+        return;
+    // Need at least N new turns since last pass.
+    const cfg = loadConfig();
+    const stitch = client(cfg);
+    let recallSize = 0;
+    try {
+        const r = await stitch.thread(thread).recall({ last: 200 });
+        recallSize = r.recent.length;
+    }
+    catch {
+        return;
+    }
+    if (recallSize - meta.lastTurnCount < DISTILL_MIN_NEW_TURNS)
+        return;
+    // Mark BEFORE running so we don't double-fire on overlapping Stop events.
+    state.threads[thread] = { lastDistilledAt: Date.now(), lastTurnAt: Date.now(), lastTurnCount: recallSize };
+    saveDistillState(state);
+    // Detach: spawn a background process so the Stop hook returns immediately.
+    // The detached child runs `stitch distill` for this thread.
+    try {
+        const child = spawn(process.argv[0], [process.argv[1] || (await import('node:url')).fileURLToPath(import.meta.url), 'distill', '--thread', thread, '--n', String(DISTILL_BATCH_SIZE)], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch { /* ignore */ }
+}
 // ── Sync Claude's local memory dir into Stitch ────────────────────────────
 // Claude Code keeps per-project memory at ~/.claude/projects/<encoded>/memory/
 // Each file is a markdown memory with optional YAML frontmatter (name,
@@ -1156,6 +1464,22 @@ function run(cmd, args, opts = {}) {
         child.on('close', (code) => resolve({ stdout, stderr, exit_code: code ?? 0 }));
     });
 }
+function runWithStdin(cmd, args, stdinData, opts = {}) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd || process.cwd(),
+            env: { ...process.env, ...(opts.env || {}) },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => stdout += d.toString());
+        child.stderr.on('data', (d) => stderr += d.toString());
+        child.on('error', (err) => resolve({ stdout, stderr: stderr + '\n[spawn error] ' + err.message, exit_code: 127 }));
+        child.on('close', (code) => resolve({ stdout, stderr, exit_code: code ?? 0 }));
+        child.stdin.end(stdinData);
+    });
+}
 function readLine() {
     return new Promise((resolve) => {
         const onData = (d) => { process.stdin.off('data', onData); resolve(d.toString().trim()); };
@@ -1178,6 +1502,24 @@ function help() {
   stitch whoami                               Show the configured key.
   stitch logout
 
+  stitch link [name]                          Pin this project to a canonical
+                                              thread name. Writes
+                                              .stitch/project.json — commit it
+                                              (or sync the file across machines)
+                                              so every machine that pins this
+                                              project shares the same memory.
+
+  stitch distill [--thread <t>] [--n 30] [--dry-run]
+                                              Read the last N turns of a thread
+                                              and have your local Claude Code
+                                              extract durable facts/decisions
+                                              into Stitch memories. Tagged
+                                              auto so they can be reviewed.
+  stitch distill --review [--limit 20]        Show recent auto-distilled
+                                              memories for inspection.
+  stitch distill --clear --yes                Soft-delete every auto-distilled
+                                              memory (recoverable 30 days).
+
   stitch sync [--watch] [--dry-run]           Mirror ~/.claude/projects/*/memory/
                                               files into Stitch as memories.
                                               --watch keeps running; otherwise it's
@@ -1225,6 +1567,8 @@ async function main(argv) {
             case 'thread': return cmdThread(rest);
             case 'install': return cmdInstall(rest);
             case 'sync': return cmdSync(rest);
+            case 'link': return cmdLink(rest);
+            case 'distill': return cmdDistill(rest);
             case '_hook': return cmdHook(rest);
             case 'update':
             case 'upgrade': return cmdUpdate(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stitchdb/cli",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {