@stitchdb/cli 0.5.0 → 0.6.0

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();
@@ -469,42 +441,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 +506,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 +599,238 @@ 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 for an AI coding assistant.
+
+Read the conversation below (between a developer and an AI). Extract ONLY
+durable, project-specific facts the developer explicitly stated or decisions
+they explicitly made. Do not invent. Do not extrapolate from implications.
+Skip anything that's tentative, exploratory, or not directly stated.
+
+Output a JSON array. Each entry:
+  {
+    "kind": "fact" | "decision" | "snippet" | "preference",
+    "content": "<self-contained, single-paragraph statement>",
+    "tags": ["<short-keyword>", ...]
+  }
+
+Rules:
+- "fact"        : stable knowledge about this project (architecture, services, schema)
+- "decision"    : explicit choice with rationale (e.g. "we use X because Y")
+- "snippet"     : a reusable code/config/command pattern the user wants kept
+- "preference"  : how the developer wants the AI to behave on this project
+- Each entry must stand alone — readable months later without context.
+- Tags should be 1–3 short keywords.
+- If nothing durable was said, output exactly: []
+- Output ONLY the JSON array. No prose, no code fences, no commentary.
+
+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 result = await run(claudeBin, ['-p', DISTILL_PROMPT + conversation], { cwd: process.cwd() });
+    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) {
+        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 sometimes wraps in markdown fences or adds a "Here are the memories:" preamble.
+    // Strip everything outside the first balanced [..] array.
+    const text = stdout.trim();
+    const start = text.indexOf('[');
+    const end = text.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start)
+        return [];
+    const json = text.slice(start, end + 1);
+    try {
+        const parsed = JSON.parse(json);
+        if (!Array.isArray(parsed))
+            return [];
+        return 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));
+    }
+    catch {
+        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,
@@ -1178,6 +1409,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 +1474,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.0",
   "description": "Stitch CLI — manage memory + run agents from your terminal",
   "type": "module",
   "bin": {