@cachly-dev/mcp-server 0.10.100 → 0.10.102

package/README.md

@@ -496,9 +496,14 @@ keep talking to your backend on every editor launch. All data stays in your infr
 
 ## 🛠️ Ecosystem & Docs
 
+**One brain, wherever you work.** Start with the MCP server, or drop the same memory
+straight into your editor — your lessons follow you across all of them.
+
 | Package | What it does |
 |---------|-------------|
-| **[`@cachly-dev/mcp-server`](https://www.npmjs.com/package/@cachly-dev/mcp-server)** | ← you are here |
+| **[`@cachly-dev/mcp-server`](https://www.npmjs.com/package/@cachly-dev/mcp-server)** | ← you are here · works with Claude, Cursor, Copilot, Windsurf, Cline, Zed |
+| **[Cachly Brain for VS Code](https://marketplace.visualstudio.com/items?itemName=cachly-dev.cachly-brain)** | One-click memory in the editor — status bar, lessons view, ambient learning. No terminal needed. |
+| **[Cachly Brain for JetBrains](https://plugins.jetbrains.com/plugin/32059-cachly-brain)** | Same brain for IntelliJ / PyCharm / GoLand / WebStorm / Rider — status bar, brain health, lessons view. |
 | **[`@cachly-dev/openclaw`](https://www.npmjs.com/package/@cachly-dev/openclaw)** | Cut LLM costs 60–90% in JS/TS apps |
 
 - 🌐 [cachly.dev](https://cachly.dev) — Dashboard & free signup

package/dist/src/cls-hook.d.ts

@@ -0,0 +1,15 @@
+/** Bumped whenever the hook script changes so installers can upgrade old hooks. */
+export declare const CLS_HOOK_VERSION = "v2";
+export type ClsHookResult = 'written' | 'upgraded' | 'appended' | 'unchanged' | 'skipped-no-git';
+/**
+ * Idempotently install/upgrade the CLS post-commit hook in `projectDir`.
+ * Never throws — returns a status the caller can log. Shared by `init`, `setup`
+ * and `autopilot` so all paths stay in lock-step.
+ */
+export declare function installClsPostCommitHook(projectDir: string, instanceId: string, apiKey?: string): Promise<ClsHookResult>;
+/**
+ * Build the `.git/hooks/post-commit` shell script.
+ * @param instanceId  Cachly Brain instance to ingest into.
+ * @param apiKey      Optional cky_… key embedded for authentication.
+ */
+export declare function buildClsPostCommitHook(instanceId: string, apiKey?: string): string;

package/dist/src/cls-hook.js

@@ -0,0 +1,94 @@
+// Shared builder for the CLS (Continuous Learning Stream) git post-commit hook.
+//
+// History / why this is centralised:
+// The previous inline versions interpolated the commit message directly into a
+// `node -e "... message:'$MSG' ..."` JS string. Any commit message containing an
+// apostrophe (e.g. "don't crash") produced invalid JavaScript, so the hook
+// silently ingested nothing — and a crafted message could inject shell/JS.
+//
+// This version is robust:
+//   • Commit message / sha / files are passed to node via ENVIRONMENT VARIABLES,
+//     never interpolated into JS source — no quoting or injection breakage.
+//   • The JSON payload is handed to the CLI via execFileSync (no shell), so the
+//     shell never re-parses quotes, `$`, or backticks from the message.
+//   • CACHLY_JWT is embedded only when provided so the `cls-ingest` CLI command
+//     can authenticate; absent it, that command exits 0 silently.
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, chmod, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Bumped whenever the hook script changes so installers can upgrade old hooks. */
+export const CLS_HOOK_VERSION = 'v2';
+/**
+ * Matches any previously-installed cachly CLS block (from its marker comment
+ * down to the trailing `exit 0`), optionally including an immediately-preceding
+ * standalone shebang. Used to upgrade old hooks in place rather than skipping
+ * them (the v1 block was a silent no-op).
+ */
+const CLS_BLOCK_RE = /(?:#!\/bin\/sh\n)?# cachly CLS[\s\S]*?\nexit 0\n?/;
+/**
+ * Idempotently install/upgrade the CLS post-commit hook in `projectDir`.
+ * Never throws — returns a status the caller can log. Shared by `init`, `setup`
+ * and `autopilot` so all paths stay in lock-step.
+ */
+export async function installClsPostCommitHook(projectDir, instanceId, apiKey) {
+    if (!existsSync(resolve(projectDir, '.git')))
+        return 'skipped-no-git';
+    const hookDir = resolve(projectDir, '.git', 'hooks');
+    const hookPath = resolve(hookDir, 'post-commit');
+    await mkdir(hookDir, { recursive: true });
+    const script = buildClsPostCommitHook(instanceId, apiKey);
+    let existing = '';
+    try {
+        existing = await readFile(hookPath, 'utf-8');
+    }
+    catch { /* no existing hook */ }
+    if (!existing) {
+        await writeFile(hookPath, script + '\n', 'utf-8');
+        await chmod(hookPath, 0o755).catch(() => { });
+        return 'written';
+    }
+    if (existing.includes(`cachly CLS — Continuous Learning Stream ${CLS_HOOK_VERSION}`)) {
+        return 'unchanged';
+    }
+    if (CLS_BLOCK_RE.test(existing)) {
+        // Upgrade an older cachly block in place, preserving any surrounding hook.
+        const replaced = existing.replace(CLS_BLOCK_RE, script);
+        await writeFile(hookPath, replaced.endsWith('\n') ? replaced : replaced + '\n', 'utf-8');
+        await chmod(hookPath, 0o755).catch(() => { });
+        return 'upgraded';
+    }
+    // Foreign hook with no cachly block → append ours.
+    await writeFile(hookPath, existing.trimEnd() + '\n\n' + script + '\n', 'utf-8');
+    await chmod(hookPath, 0o755).catch(() => { });
+    return 'appended';
+}
+/** The node `-e` program — reads commit data from env, ingests via the CLI. */
+const CLS_NODE_PROGRAM = "try{" +
+    "var p={instance_id:process.env.CACHLY_BRAIN_INSTANCE_ID,source:'git_commit'," +
+    "payload:{message:process.env.CLS_MSG||'',sha:process.env.CLS_SHA||''," +
+    "files:(process.env.CLS_FILES||'').split(',').filter(Boolean)}};" +
+    "require('child_process').execFileSync('npx',['@cachly-dev/mcp-server@latest','cls-ingest',JSON.stringify(p)]," +
+    "{stdio:'ignore',timeout:8000});" +
+    "}catch(e){}";
+/**
+ * Build the `.git/hooks/post-commit` shell script.
+ * @param instanceId  Cachly Brain instance to ingest into.
+ * @param apiKey      Optional cky_… key embedded for authentication.
+ */
+export function buildClsPostCommitHook(instanceId, apiKey) {
+    return [
+        `#!/bin/sh`,
+        `# cachly CLS — Continuous Learning Stream ${CLS_HOOK_VERSION}`,
+        `# Runs silently on every commit to keep your brain up to date.`,
+        `export CACHLY_BRAIN_INSTANCE_ID="${instanceId}"`,
+        ...(apiKey ? [`export CACHLY_JWT="${apiKey}"`] : []),
+        `CLS_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")`,
+        // No `tr`/quote-mangling — the message is passed verbatim via env.
+        `CLS_MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 | cut -c1-200)`,
+        `CLS_FILES=$(git diff-tree --no-commit-id -r --name-only HEAD 2>/dev/null | tr '\\n' ',' | sed 's/,$//')`,
+        `export CLS_SHA CLS_MSG CLS_FILES`,
+        `node -e "${CLS_NODE_PROGRAM}" 2>/dev/null &`,
+        `exit 0`,
+    ].join('\n');
+}
+//# sourceMappingURL=cls-hook.js.map

package/dist/src/cls-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cls-hook.js","sourceRoot":"","sources":["../../src/cls-hook.ts"],"names":[],"mappings":"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"}

package/dist/src/handlers/brain.js

@@ -301,6 +301,33 @@ export const BRAIN_TOOL_NAMES = new Set([
     'skill_gaps', 'brain_coverage', 'brain_metrics', 'brain_service_map',
     'brain_collab_pairs', 'brain_portability',
 ]);
+// ── Free-tier Teaser-Gate ──────────────────────────────────────────────────
+// When a Free-tier Brain crosses its recall limit, smart_recall still delivers
+// the top hits — the magic moment is sacred — but withholds the long tail
+// behind an upgrade teaser ("🔒 N more relevant lessons available"). This is a
+// DEPTH gate (hide the tail), never an access wall: the #1 result is always
+// returned. Usage/limit come from the same authoritative numbers as the Brain
+// Health bar (GET /instances/:id/memory), cached briefly to avoid per-call latency.
+const FREE_TIER_VISIBLE_RECALLS = 3;
+const UPGRADE_URL = 'https://cachly.dev/billing';
+const _recallGateCache = new Map();
+async function getRecallGate(instanceId, apiFetch) {
+    const cached = _recallGateCache.get(instanceId);
+    if (cached && cached.expiresAt > Date.now())
+        return cached.gate;
+    try {
+        const mem = await apiFetch(`/api/v1/instances/${instanceId}/memory`);
+        const limit = mem?.recall_limit ?? -1;
+        const used = mem?.total_recall_count ?? 0;
+        const gate = { reached: limit > 0 && used >= limit, limit, used };
+        _recallGateCache.set(instanceId, { gate, expiresAt: Date.now() + 60_000 });
+        return gate;
+    }
+    catch {
+        // Stats unavailable → never gate (fail open: value delivery beats monetization).
+        return { reached: false, limit: -1, used: 0 };
+    }
+}
 export async function handleBrainTool(name, args, getConnection, apiFetch) {
     switch (name) {
         case 'learn_from_attempts': {
@@ -838,9 +865,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 redis.set(`cachly:stats:first_recall_at:${instance_id}`, new Date().toISOString(), 'EX', 365 * 86400, 'NX').catch(() => { });
             }
             // ── Layer 2: Semantic search (parallel, optional) ────────────────────────
+            // Semantic recall is a Premium depth layer: free tier keeps full keyword +
+            // CKG recall (the magic moment), paid tiers add embedding-based retrieval.
             const inst = await apiFetch(`/api/v1/instances/${instance_id}`).catch(() => null);
+            const tierIsFree = !inst?.tier || inst.tier.toLowerCase() === 'free';
             const semHits = [];
-            if (inst?.vector_token && hasEmbedProvider()) {
+            if (!tierIsFree && inst?.vector_token && hasEmbedProvider()) {
                 try {
                     const embedding = await computeEmbedding(query);
                     const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
@@ -980,6 +1010,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 return true;
             })
                 .sort((a, b) => b.hybridScore - a.hybridScore);
+            // ── Teaser-Gate: free tier over its recall limit hides the long tail ──────
+            const recallGate = await getRecallGate(instance_id, apiFetch);
+            const gateActive = recallGate.reached && hybridResults.length > FREE_TIER_VISIBLE_RECALLS;
+            const visibleCount = gateActive ? FREE_TIER_VISIBLE_RECALLS : 8;
             // ── Build output ──────────────────────────────────────────────────────────
             const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
             // "Brain saved you here" banner — surfaces value inline for proven recalled lessons
@@ -1029,7 +1063,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 // Group by sub-query for multi-topic queries
                 if (subQueries.length > 1) {
                     const grouped = new Map();
-                    for (const r of hybridResults.slice(0, 12)) {
+                    for (const r of hybridResults.slice(0, gateActive ? FREE_TIER_VISIBLE_RECALLS : 12)) {
                         const sq = r.subQuery ?? query;
                         if (!grouped.has(sq))
                             grouped.set(sq, []);
@@ -1060,7 +1094,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     }
                 }
                 else {
-                    for (const r of hybridResults.slice(0, 8)) {
+                    for (const r of hybridResults.slice(0, visibleCount)) {
                         const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
                         let authorBadge = '';
                         if (r.key.startsWith('cachly:lesson:best:')) {
@@ -1079,6 +1113,13 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
                     }
                 }
+                // ── Teaser-Gate footer: sell the withheld tail at the moment of need ──
+                if (gateActive) {
+                    const withheld = Math.max(0, hybridResults.length - visibleCount);
+                    if (withheld > 0) {
+                        lines.push(`🔒 **${withheld} more relevant lesson${withheld !== 1 ? 's' : ''} available** — you've reached your Free recall limit (${recallGate.used}/${recallGate.limit}). Unlock your full Brain → ${UPGRADE_URL}\n`);
+                    }
+                }
             }
             else {
                 lines.push(`⚠️ No matches found for: "${query}"`);