@cachly-dev/mcp-server 0.9.11 → 0.9.13

package/dist/index.js

@@ -2434,7 +2434,11 @@ const TOOLS = [
     {
         name: 'cache_get',
         description: 'Get a value from a running cache instance by key. ' +
-            'Returns the value (string or JSON) or null if the key does not exist.',
+            'Returns the stored value (string or deserialized JSON object) or null if the key does not exist or has expired. ' +
+            'Read-only — no side effects. ' +
+            'Use cache_mget when you need multiple keys in one round-trip. ' +
+            'Use cache_exists to check existence without retrieving the value. ' +
+            'Use semantic_search when you need fuzzy/vector search across stored values.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2503,12 +2507,15 @@ const TOOLS = [
     },
     {
         name: 'cache_ttl',
-        description: 'Get the remaining time-to-live (TTL) of a key in seconds. Returns -1 if no TTL, -2 if the key does not exist.',
+        description: 'Get the remaining time-to-live (TTL) of a key in seconds. ' +
+            'Returns -1 if the key exists but has no expiry, -2 if the key does not exist. ' +
+            'Read-only — no side effects. ' +
+            'Use cache_set with a ttl parameter to set or update the expiry.',
         inputSchema: {
             type: 'object',
             properties: {
-                instance_id: { type: 'string' },
-                key: { type: 'string' },
+                instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
+                key: { type: 'string', description: 'Cache key to inspect' },
             },
             required: ['instance_id', 'key'],
         },
@@ -2688,7 +2695,11 @@ const TOOLS = [
         name: 'cache_mset',
         description: 'Set multiple key-value pairs in a single pipeline round-trip. ' +
             'Supports per-key TTL – unlike native MSET. ' +
-            'Uses one TCP round-trip for N keys via Redis pipeline.',
+            'Uses one TCP round-trip for N keys via Redis pipeline. ' +
+            'Each item overwrites any existing value for that key. ' +
+            'On partial failure the successfully pipelined keys are committed; a per-key error list is returned for any that failed. ' +
+            'Returns a summary: { set: N, errors: [...] }. ' +
+            'Use cache_set for a single key; use cache_stream_set for large streaming payloads.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2771,8 +2782,11 @@ const TOOLS = [
             'Perfect for caching: codebase overviews, file summaries, project structure, ' +
             'frequently-accessed data, or "thinking" results like dependency analysis. ' +
             'The AI assistant can use this to avoid re-reading the entire codebase every time. ' +
+            'Overwrites any existing value stored under the same key. ' +
+            'Returns { key, stored_at, ttl } confirming the saved context. ' +
             'Example: remember_context("project overview", "This is a Next.js app with...") ' +
-            'then later: recall_context("project overview")',
+            'then later: recall_context("project overview"). ' +
+            'Use recall_context to retrieve; use list_remembered to see all stored keys.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -3347,7 +3361,11 @@ const TOOLS = [
         name: 'publish_lesson',
         description: 'Publish a lesson to the Cachly Public Brain (anonymized community knowledge base). ' +
             'Published lessons can be imported by other developers via import_public_brain. ' +
-            'PII is stripped automatically. Visible under the framework/category tag.',
+            'PII is stripped automatically. Visible under the framework/category tag. ' +
+            'Returns { lesson_id, topic, framework, published_at } confirming the publish. ' +
+            'Irreversible — once published to the public brain, lessons cannot be deleted via the MCP interface. ' +
+            'Use learn_from_attempts or global_learn for private lessons; ' +
+            'use syndicate for anonymized global sharing without framework tagging.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -3644,7 +3662,10 @@ const TOOLS = [
             'This is how individual knowledge becomes collective intelligence. ' +
             'Call this AFTER every learn_from_attempts that is worth sharing universally ' +
             '(critical bugs, deployment gotchas, architecture discoveries). ' +
-            'Use scope="org" to keep the lesson private to your organisation.',
+            'If a lesson with the same topic already exists in the commons, it is updated in place (idempotent). ' +
+            'Returns { key, confirm_count, scope } confirming the stored lesson. ' +
+            'Use scope="org" to keep the lesson private to your organisation. ' +
+            'Do NOT use for secrets or PII — content is stored in a shared knowledge base.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -4904,6 +4925,8 @@ async function handleTool(name, args) {
             }
             catch { /* non-critical */ }
             // ── Layer 1+2: CKG update (Causal Knowledge Graph + Belief Update Engine) ──
+            // BUE: Bayesian confidence, contradiction detection, second-degree propagation, decay
+            let beliefConflict = null;
             try {
                 const conceptId = ckgSlug(topic);
                 const domain = topic.split(':')[0] ?? 'unknown';
@@ -4941,6 +4964,71 @@ async function handleTool(name, args) {
                         await ckgUpdateEdge(redis, conceptId, 'causes', causeId, false);
                     }
                 }
+                // ── BUE: Contradiction detection ──────────────────────────────────────
+                // If this topic previously had a confirmed 'fixes' edge (confidence > 0.7)
+                // and now outcome=failure → flag belief_conflict
+                if (outcome === 'failure') {
+                    const existingEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
+                    for (const ek of existingEdgeKeys) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const existEdge = JSON.parse(er);
+                        if (existEdge.edgeType === 'fixes' && existEdge.confidence > 0.7 && existEdge.trials >= 3) {
+                            beliefConflict = `⚠️ **belief_conflict** on \`${topic}\`: previously confirmed fix (confidence ${existEdge.confidence.toFixed(2)}, n=${existEdge.trials}) now reports failure. Both beliefs retained as \`contested\`. Use \`ckg_inspect(concept="${conceptId}")\` to review.`;
+                            // Store conflict marker
+                            const conflictKey = `cachly:ckg:conflict:${conceptId}`;
+                            await redis.set(conflictKey, JSON.stringify({ topic, detected_at: new Date().toISOString(), fix_confidence: existEdge.confidence, fix_trials: existEdge.trials, failure_outcome: outcome }), 'EX', 60 * 60 * 24 * 90);
+                        }
+                    }
+                }
+                // ── BUE: Second-degree propagation ────────────────────────────────────
+                // When a 'fixes' edge gets stronger, boost co-occurring second-degree edges slightly
+                if (outcome === 'success' && (domain === 'fix' || domain === 'debug')) {
+                    const fromEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
+                    for (const ek of fromEdgeKeys.slice(0, 10)) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const e2 = JSON.parse(er);
+                        if (e2.edgeType !== 'fixes')
+                            continue;
+                        // Boost second-degree: edges from e2.to get a small fractional success
+                        const secondKeys = await redis.smembers(`cachly:ckg:idx:from:${e2.to}`);
+                        for (const sk of secondKeys.slice(0, 5)) {
+                            const sr = await redis.get(sk);
+                            if (!sr)
+                                continue;
+                            const se = JSON.parse(sr);
+                            if (se.edgeType !== 'co-occurs')
+                                continue;
+                            // Add 0.1 fractional success (second-degree signal)
+                            se.successes = (se.successes || 0) + 0.1;
+                            se.trials = (se.trials || 0) + 0.1;
+                            se.confidence = (se.successes + 1) / (se.trials + 2);
+                            se.last_updated = new Date().toISOString();
+                            await redis.set(sk, JSON.stringify(se));
+                        }
+                    }
+                }
+                // ── BUE: Stale edge decay ─────────────────────────────────────────────
+                // Edges older than 90 days with < 3 trials decay by 10% confidence.
+                // Only run probabilistically (1% of calls) to avoid per-call overhead.
+                if (Math.random() < 0.01) {
+                    const decayCutoff = Date.now() - 90 * 24 * 60 * 60 * 1000;
+                    const fromEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
+                    for (const ek of fromEdgeKeys) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const de = JSON.parse(er);
+                        if (de.trials < 3 && de.last_updated && new Date(de.last_updated).getTime() < decayCutoff) {
+                            de.confidence = de.confidence * 0.9;
+                            de.last_updated = new Date().toISOString();
+                            await redis.set(ek, JSON.stringify(de));
+                        }
+                    }
+                }
             }
             catch { /* CKG updates are non-critical */ }
             const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
@@ -4948,6 +5036,7 @@ async function handleTool(name, args) {
             const action = isUpdate ? 'updated' : 'stored';
             return [
                 `${emoji} **Lesson ${action}:** \`${topic}\` (${outcome}) ${sevEmoji} ${severity}`,
+                beliefConflict ?? '',
                 ``,
                 `**What worked:** ${what_worked}`,
                 what_failed ? `**What failed:** ${what_failed}` : '',
@@ -5449,6 +5538,24 @@ async function handleTool(name, args) {
                     lines.push('');
                 }
             }
+            // ── Layer 7 MCM: Active belief conflicts ─────────────────────────────────
+            try {
+                const conflictKeys = [];
+                const cfStream = redis.scanStream({ match: 'cachly:ckg:conflict:*', count: 50 });
+                await new Promise((res, rej) => { cfStream.on('data', (b) => conflictKeys.push(...b)); cfStream.on('end', res); cfStream.on('error', rej); });
+                if (conflictKeys.length > 0) {
+                    lines.push(`⚡ **Active belief conflicts (${conflictKeys.length}):**`);
+                    for (const ck of conflictKeys.slice(0, 3)) {
+                        const cr = await redis.get(ck);
+                        if (!cr)
+                            continue;
+                        const cf = JSON.parse(cr);
+                        lines.push(`  ⚠️ \`${cf.topic}\` — previously confirmed fix (${(cf.fix_confidence * 100).toFixed(0)}%, n=${cf.fix_trials}) now contradicted. Use \`ckg_inspect(concept="${ckgSlug(cf.topic)}")\``);
+                    }
+                    lines.push('');
+                }
+            }
+            catch { /* non-critical */ }
             if (focusLessons.length > 0) {
                 lines.push(`🎯 **Relevant for "${focus}":**`);
                 for (const l of focusLessons.slice(0, 4)) {
@@ -8737,107 +8844,114 @@ smart_recall(
             const { resolve } = await import('node:path');
             const repoDir = resolve(repo_path);
             const maxCommits = Math.min(Number(limit) || 100, 500);
-            // Verify it's a git repo
-            try {
-                execSync('git rev-parse --git-dir', { cwd: repoDir, stdio: 'pipe' });
-            }
-            catch {
-                return `❌ Not a git repository: \`${repoDir}\`. Pass \`repo_path\` pointing to a git checkout.`;
-            }
-            // Build git log command
-            const sinceFlag = since ? `--since="${since}"` : '';
-            const logCmd = `git log ${branch} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
-            let logOutput = '';
+            // Semaphore: max 10 concurrent git subprocesses per MCP process
+            await _gitSemAcquire();
             try {
-                logOutput = execSync(logCmd, { cwd: repoDir, encoding: 'utf-8', stdio: 'pipe' });
-            }
-            catch (e) {
-                return `❌ git log failed: ${e.message}. Check \`repo_path\` and \`branch\`.`;
-            }
-            const commits = logOutput.trim().split('\n').filter(Boolean).map(line => {
-                const [sha, subject, date, author] = line.split('|||');
-                return { sha: (sha ?? '').trim(), subject: (subject ?? '').trim(), date: (date ?? '').trim(), author: (author ?? '').trim() };
-            });
-            if (commits.length === 0) {
-                return `⚠️ No commits found in \`${repoDir}\` on branch \`${branch}\`${since ? ` since ${since}` : ''}.`;
-            }
-            // Pattern classifiers
-            const classifyCommit = (subject) => {
-                const s = subject.toLowerCase();
-                if (/\b(fix|fixed|fixes|bug|hotfix|patch|revert|resolve|closes? #\d+)\b/.test(s)) {
-                    const sev = /\b(critical|crash|security|auth|data loss|outage|prod|production)\b/.test(s) ? 'critical' : /\b(major|breaking|regression|hotfix)\b/.test(s) ? 'major' : 'minor';
-                    return { category: 'fix', outcome: 'success', severity: sev };
-                }
-                if (/\b(feat|feature|add|added|implement|new|introduce)\b/.test(s))
-                    return { category: 'feat', outcome: 'success', severity: 'minor' };
-                if (/\b(refactor|clean|cleanup|improve|simplify|extract|rename)\b/.test(s))
-                    return { category: 'refactor', outcome: 'success', severity: 'minor' };
-                if (/\b(perf|optimize|speed|cache|latency|memory|performance)\b/.test(s))
-                    return { category: 'perf', outcome: 'success', severity: 'major' };
-                if (/\b(security|cve|auth|csrf|xss|sql|injection|sanitize|escape|encrypt)\b/.test(s))
-                    return { category: 'security', outcome: 'success', severity: 'critical' };
-                if (/\b(deploy|ci|cd|build|docker|k8s|helm|infra|devops)\b/.test(s))
-                    return { category: 'deploy', outcome: 'success', severity: 'major' };
-                if (/\b(test|spec|coverage|assert|mock|unit|integration)\b/.test(s))
-                    return { category: 'test', outcome: 'success', severity: 'minor' };
-                return { category: 'chore', outcome: 'success', severity: 'minor' };
-            };
-            // Extract domain keywords from commit subject
-            const extractDomain = (subject) => {
-                const s = subject.toLowerCase();
-                const tokens = s.replace(/[^a-z0-9\s\-_]/g, ' ').split(/\s+/).filter(t => t.length > 3 && !['that', 'this', 'with', 'from', 'when', 'into', 'also', 'some', 'were'].includes(t));
-                return tokens.slice(0, 3).join('-') || 'general';
-            };
-            const ts = new Date().toISOString();
-            let ingested = 0;
-            let skipped = 0;
-            const categoryCount = new Map();
-            for (const commit of commits) {
-                if (!commit.subject) {
-                    skipped++;
-                    continue;
+                // Verify it's a git repo
+                try {
+                    execSync('git rev-parse --git-dir', { cwd: repoDir, stdio: 'pipe' });
                 }
-                const { category, outcome, severity } = classifyCommit(commit.subject);
-                const domain = extractDomain(commit.subject);
-                const topic = `${category}:${domain}`;
-                categoryCount.set(category, (categoryCount.get(category) ?? 0) + 1);
-                const lessonObj = {
-                    topic, outcome, severity,
-                    what_worked: commit.subject.slice(0, 200),
-                    what_failed: '',
-                    context: `git:${commit.sha.slice(0, 8)} by ${commit.author} on ${commit.date}`,
-                    file_paths: [], commands: [`git show ${commit.sha.slice(0, 8)}`],
-                    tags: ['brain_from_git', category, 'git-history'],
-                    depends_on: [], recall_count: 0, ts, verified_at: ts,
-                    confidence: 0.55, // lower confidence for auto-inferred lessons
-                    audit_trail: [{ ts, action: 'brain_from_git', sha: commit.sha.slice(0, 8) }],
-                    version: 3,
-                };
-                // Only store if no existing lesson for this topic (avoid overwriting higher-confidence lessons)
-                const existing = await redis.get(`cachly:lesson:best:${topic}`);
-                if (!existing) {
-                    await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lessonObj));
-                    await redis.rpush(`cachly:lessons:${topic}`, JSON.stringify(lessonObj));
+                catch {
+                    return `❌ Not a git repository: \`${repoDir}\`. Pass \`repo_path\` pointing to a git checkout.`;
                 }
-                await redis.rpush('cachly:lessons:brain_from_git:all', JSON.stringify({ topic, sha: commit.sha.slice(0, 8), subject: commit.subject.slice(0, 60) }));
-                await redis.ltrim('cachly:lessons:brain_from_git:all', -500, -1);
-                // Update CKG
-                const conceptId = ckgSlug(topic);
-                await ckgUpsertNode(redis, conceptId, category, 'git-derived');
-                ingested++;
+                // Build git log command
+                const sinceFlag = since ? `--since="${since}"` : '';
+                const logCmd = `git log ${branch} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
+                let logOutput = '';
+                try {
+                    logOutput = execSync(logCmd, { cwd: repoDir, encoding: 'utf-8', stdio: 'pipe' });
+                }
+                catch (e) {
+                    return `❌ git log failed: ${e.message}. Check \`repo_path\` and \`branch\`.`;
+                }
+                const commits = logOutput.trim().split('\n').filter(Boolean).map(line => {
+                    const [sha, subject, date, author] = line.split('|||');
+                    return { sha: (sha ?? '').trim(), subject: (subject ?? '').trim(), date: (date ?? '').trim(), author: (author ?? '').trim() };
+                });
+                if (commits.length === 0) {
+                    return `⚠️ No commits found in \`${repoDir}\` on branch \`${branch}\`${since ? ` since ${since}` : ''}.`;
+                }
+                // Pattern classifiers
+                const classifyCommit = (subject) => {
+                    const s = subject.toLowerCase();
+                    if (/\b(fix|fixed|fixes|bug|hotfix|patch|revert|resolve|closes? #\d+)\b/.test(s)) {
+                        const sev = /\b(critical|crash|security|auth|data loss|outage|prod|production)\b/.test(s) ? 'critical' : /\b(major|breaking|regression|hotfix)\b/.test(s) ? 'major' : 'minor';
+                        return { category: 'fix', outcome: 'success', severity: sev };
+                    }
+                    if (/\b(feat|feature|add|added|implement|new|introduce)\b/.test(s))
+                        return { category: 'feat', outcome: 'success', severity: 'minor' };
+                    if (/\b(refactor|clean|cleanup|improve|simplify|extract|rename)\b/.test(s))
+                        return { category: 'refactor', outcome: 'success', severity: 'minor' };
+                    if (/\b(perf|optimize|speed|cache|latency|memory|performance)\b/.test(s))
+                        return { category: 'perf', outcome: 'success', severity: 'major' };
+                    if (/\b(security|cve|auth|csrf|xss|sql|injection|sanitize|escape|encrypt)\b/.test(s))
+                        return { category: 'security', outcome: 'success', severity: 'critical' };
+                    if (/\b(deploy|ci|cd|build|docker|k8s|helm|infra|devops)\b/.test(s))
+                        return { category: 'deploy', outcome: 'success', severity: 'major' };
+                    if (/\b(test|spec|coverage|assert|mock|unit|integration)\b/.test(s))
+                        return { category: 'test', outcome: 'success', severity: 'minor' };
+                    return { category: 'chore', outcome: 'success', severity: 'minor' };
+                };
+                // Extract domain keywords from commit subject
+                const extractDomain = (subject) => {
+                    const s = subject.toLowerCase();
+                    const tokens = s.replace(/[^a-z0-9\s\-_]/g, ' ').split(/\s+/).filter(t => t.length > 3 && !['that', 'this', 'with', 'from', 'when', 'into', 'also', 'some', 'were'].includes(t));
+                    return tokens.slice(0, 3).join('-') || 'general';
+                };
+                const ts = new Date().toISOString();
+                let ingested = 0;
+                let skipped = 0;
+                const categoryCount = new Map();
+                for (const commit of commits) {
+                    if (!commit.subject) {
+                        skipped++;
+                        continue;
+                    }
+                    const { category, outcome, severity } = classifyCommit(commit.subject);
+                    const domain = extractDomain(commit.subject);
+                    const topic = `${category}:${domain}`;
+                    categoryCount.set(category, (categoryCount.get(category) ?? 0) + 1);
+                    const lessonObj = {
+                        topic, outcome, severity,
+                        what_worked: commit.subject.slice(0, 200),
+                        what_failed: '',
+                        context: `git:${commit.sha.slice(0, 8)} by ${commit.author} on ${commit.date}`,
+                        file_paths: [], commands: [`git show ${commit.sha.slice(0, 8)}`],
+                        tags: ['brain_from_git', category, 'git-history'],
+                        depends_on: [], recall_count: 0, ts, verified_at: ts,
+                        confidence: 0.55, // lower confidence for auto-inferred lessons
+                        audit_trail: [{ ts, action: 'brain_from_git', sha: commit.sha.slice(0, 8) }],
+                        version: 3,
+                    };
+                    // Only store if no existing lesson for this topic (avoid overwriting higher-confidence lessons)
+                    const existing = await redis.get(`cachly:lesson:best:${topic}`);
+                    if (!existing) {
+                        await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lessonObj));
+                        await redis.rpush(`cachly:lessons:${topic}`, JSON.stringify(lessonObj));
+                    }
+                    await redis.rpush('cachly:lessons:brain_from_git:all', JSON.stringify({ topic, sha: commit.sha.slice(0, 8), subject: commit.subject.slice(0, 60) }));
+                    await redis.ltrim('cachly:lessons:brain_from_git:all', -500, -1);
+                    // Update CKG
+                    const conceptId = ckgSlug(topic);
+                    await ckgUpsertNode(redis, conceptId, category, 'git-derived');
+                    ingested++;
+                }
+                const categoryBreakdown = [...categoryCount.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `  • **${k}** (${v})`).join('\n');
+                return [
+                    `🔁 **brain_from_git: ${repoDir}**`, '',
+                    `📂 Branch: \`${branch}\`  |  Processed: **${commits.length}** commits  |  Ingested: **${ingested}** lessons  |  Skipped: ${skipped}`,
+                    ``,
+                    `**Breakdown by category:**`,
+                    categoryBreakdown,
+                    ``,
+                    `💡 New lessons are stored with confidence 0.55 (auto-inferred).`,
+                    `💡 As you confirm them via \`learn_from_attempts\`, confidence rises automatically.`,
+                    `🔍 Explore: \`brain_search(query="fix")\`  |  \`ckg_inspect(concept="deploy")\``,
+                ].join('\n');
+            }
+            finally {
+                _gitSemRelease();
             }
-            const categoryBreakdown = [...categoryCount.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `  • **${k}** (${v})`).join('\n');
-            return [
-                `🔁 **brain_from_git: ${repoDir}**`, '',
-                `📂 Branch: \`${branch}\`  |  Processed: **${commits.length}** commits  |  Ingested: **${ingested}** lessons  |  Skipped: ${skipped}`,
-                ``,
-                `**Breakdown by category:**`,
-                categoryBreakdown,
-                ``,
-                `💡 New lessons are stored with confidence 0.55 (auto-inferred).`,
-                `💡 As you confirm them via \`learn_from_attempts\`, confidence rises automatically.`,
-                `🔍 Explore: \`brain_search(query="fix")\`  |  \`ckg_inspect(concept="deploy")\``,
-            ].join('\n');
         }
         // ── brain_predict_failures ─────────────────────────────────────────────────
         case 'brain_predict_failures': {
@@ -8978,6 +9092,28 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 let _autoSessionInstanceId = null;
 let _autoSessionStarted = false;
 let _autoSessionToolCount = 0;
+// ── brain_from_git concurrency limiter ────────────────────────────────────────
+// Spawning many `git log` subprocesses in parallel can fork-bomb the host.
+// This simple semaphore caps concurrent brain_from_git calls to 10 per process.
+let _gitSemCount = 0;
+const _GIT_SEM_MAX = 10;
+const _gitSemQueue = [];
+function _gitSemAcquire() {
+    if (_gitSemCount < _GIT_SEM_MAX) {
+        _gitSemCount++;
+        return Promise.resolve();
+    }
+    return new Promise(resolve => _gitSemQueue.push(resolve));
+}
+function _gitSemRelease() {
+    const next = _gitSemQueue.shift();
+    if (next) {
+        next();
+    }
+    else {
+        _gitSemCount--;
+    }
+}
 async function autoStartSession(instanceId) {
     if (_autoSessionStarted)
         return;
@@ -9214,6 +9350,47 @@ if (process.argv[2] === 'init') {
     const result = await writeClaudeMd(projectDir, instanceId);
     const action = result === 'updated' ? '✅ Updated' : result === 'appended' ? '✅ Appended to' : '✅ Written';
     console.log(`${action}: CLAUDE.md`);
+    // ── CLS Phase 4: Auto-install git post-commit hook ─────────────────────────
+    try {
+        const { existsSync } = await import('node:fs');
+        const gitHookDir = resolve(projectDir, '.git', 'hooks');
+        const hookPath = resolve(gitHookDir, 'post-commit');
+        if (existsSync(resolve(projectDir, '.git'))) {
+            await mkdir(gitHookDir, { recursive: true });
+            const hookScript = [
+                `#!/bin/sh`,
+                `# cachly CLS — Continuous Learning Stream (installed by cachly init)`,
+                `# Runs silently on every commit to keep your brain up to date.`,
+                `CACHLY_INSTANCE="${instanceId}"`,
+                `SHA=$(git rev-parse HEAD 2>/dev/null || echo "")`,
+                `MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 | tr '"' "'" | cut -c1-200)`,
+                `FILES=$(git diff-tree --no-commit-id -r --name-only HEAD 2>/dev/null | tr '\\n' ',' | sed 's/,$//')`,
+                `node -e "try{require('child_process').execSync('npx @cachly-dev/mcp-server@latest cls-ingest \\''+ JSON.stringify({instance_id:'$CACHLY_INSTANCE',source:'git_commit',payload:{message:'$MSG',sha:'$SHA',files:'$FILES'.split(',').filter(Boolean)}})+'\\'' ,{stdio:'ignore',timeout:5000})}catch(e){}" 2>/dev/null &`,
+                `exit 0`,
+            ].join('\n');
+            let existing = '';
+            try {
+                const { readFile } = await import('node:fs/promises');
+                existing = await readFile(hookPath, 'utf-8');
+            }
+            catch { /* no existing hook */ }
+            if (existing && !existing.includes('cachly CLS')) {
+                // Append to existing hook
+                await writeFile(hookPath, existing.trimEnd() + '\n\n' + hookScript + '\n', 'utf-8');
+                console.log(`✅ Appended: .git/hooks/post-commit (CLS hook)`);
+            }
+            else if (!existing) {
+                await writeFile(hookPath, hookScript + '\n', 'utf-8');
+                const { chmod } = await import('node:fs/promises');
+                await chmod(hookPath, 0o755);
+                console.log(`✅ Written: .git/hooks/post-commit (CLS hook)`);
+            }
+            else {
+                console.log(`✓  CLS hook already present in .git/hooks/post-commit`);
+            }
+        }
+    }
+    catch { /* non-critical — git hook is a best-effort feature */ }
     console.log(`\n🧠 Cachly AI Brain configured for ${editor === 'claude' ? 'Claude Code' : editor}!`);
     console.log(`   Restart your editor — the \`cachly\` MCP tools will appear.\n`);
     process.exit(0);
@@ -9541,6 +9718,43 @@ if (process.argv[2] === 'setup') {
             catch { /* fire and forget */ }
         }
     }
+    // ── CLS Phase 4: Auto-install git post-commit hook in setup flow ─────────
+    try {
+        const { existsSync } = await import('node:fs');
+        const { writeFile: wf2, mkdir: mk2, chmod: ch2, readFile: rf2 } = await import('node:fs/promises');
+        const { resolve: res2 } = await import('node:path');
+        const setupProjectDir = process.cwd();
+        const gitHookDir2 = res2(setupProjectDir, '.git', 'hooks');
+        const hookPath2 = res2(gitHookDir2, 'post-commit');
+        if (existsSync(res2(setupProjectDir, '.git'))) {
+            await mk2(gitHookDir2, { recursive: true });
+            const hs2 = [
+                `#!/bin/sh`,
+                `# cachly CLS — Continuous Learning Stream (installed by cachly setup)`,
+                `CACHLY_INSTANCE="${instance.id}"`,
+                `SHA=$(git rev-parse HEAD 2>/dev/null || echo "")`,
+                `MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 | tr '"' "'" | cut -c1-200)`,
+                `FILES=$(git diff-tree --no-commit-id -r --name-only HEAD 2>/dev/null | tr '\\n' ',' | sed 's/,$//')`,
+                `node -e "try{require('child_process').execSync('npx @cachly-dev/mcp-server@latest cls-ingest \\''+ JSON.stringify({instance_id:'$CACHLY_INSTANCE',source:'git_commit',payload:{message:'$MSG',sha:'$SHA',files:'$FILES'.split(',').filter(Boolean)}})+'\\'' ,{stdio:'ignore',timeout:5000})}catch(e){}" 2>/dev/null &`,
+                `exit 0`,
+            ].join('\n');
+            let ex2 = '';
+            try {
+                ex2 = await rf2(hookPath2, 'utf-8');
+            }
+            catch { /* no existing */ }
+            if (!ex2) {
+                await wf2(hookPath2, hs2 + '\n', 'utf-8');
+                await ch2(hookPath2, 0o755);
+                console.log(`\n✅  CLS git hook installed — your brain will learn from every commit.`);
+            }
+            else if (!ex2.includes('cachly CLS')) {
+                await wf2(hookPath2, ex2.trimEnd() + '\n\n' + hs2 + '\n', 'utf-8');
+                console.log(`\n✅  CLS git hook appended to existing post-commit.`);
+            }
+        }
+    }
+    catch { /* non-critical */ }
     rl.close();
     process.exit(0);
 }