@cachly-dev/mcp-server 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "MCP server – manage cachly.dev instances from any AI assistant (Copilot, Claude, Cursor, Windsurf)",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "main": "./dist/index.js",
   "scripts": {
     "build": "tsc",
+    "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "vitest run",

package/scripts/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Shown once after: npm install @cachly-dev/mcp-server
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  violet: "\x1b[35m",
+  green: "\x1b[32m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+const line = `${c.dim}─────────────────────────────────────────────────────${c.reset}`;
+
+console.log(`
+${line}
+  ${c.bold}${c.violet}🧠 Cachly Brain MCP Server${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
+
+  ${c.bold}Give your AI assistant persistent memory in 30 seconds:${c.reset}
+
+  ${c.cyan}1.${c.reset} Get a free Brain instance at ${c.bold}cachly.dev/setup-ai${c.reset}
+  ${c.cyan}2.${c.reset} Add to Claude Code / Cursor / Copilot:
+     ${c.dim}npx @cachly-dev/mcp-server --key cky_live_... --instance <uuid>${c.reset}
+
+  ${c.green}✅ Free tier · GDPR · German servers · No credit card${c.reset}
+
+${line}`);

package/src/index.ts

@@ -3782,65 +3782,148 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       // Generate copilot-instructions.md content
       const tier = inst.tier.toUpperCase();
       const smartRecallNote = hasVector
-        ? '3. Call `smart_recall` with keywords for semantic context search'
-        : '3. Call `recall_context` with relevant key patterns like "arch:*" or "file:*"';
+        ? '- `smart_recall("natural language query")` — semantic search (finds by meaning)'
+        : '- `recall_context("arch:*")` — exact/glob key lookup (upgrade to Speed/Business for smart_recall)';
       const layerNote = hasVector
-        ? `Layer 3 (Semantic): smart_recall uses pgvector HNSW on your ${tier} instance for meaning-based search`
-        : `Layer 3 (Autopilot): This file — upgrade to Speed/Business tier to unlock smart_recall`;
+        ? `Layer 3 (Semantic): smart_recall uses pgvector HNSW on your ${tier} instance`
+        : `Layer 3 (Autopilot): this file — upgrade to Speed/Business tier to unlock smart_recall`;
 
-      const copilotInstructions = `# cachly AI Memory — ${project_description}
+      const copilotInstructions = `# cachly AI Brain — ${project_description}
 
-## 3-Layer AI Memory System
+> AI memory system powered by [cachly.dev](https://cachly.dev). Works with GitHub Copilot, Claude Code, Cursor, Windsurf, Continue.dev, and any MCP-compatible editor.
 
-- **Layer 1 — Storage:** cachly instance \`${inst.name}\` (${tier}) — persistent Valkey brain, survives restarts
-- **Layer 2 — Tools:** learn_from_attempts · recall_best_solution · smart_recall — the memory API
-- **Layer 3 — Autopilot (this file):** instructs the AI to run memory tools automatically
+---
 
-## BEFORE every task — check memory first
+## 🔴 MANDATORY RULES — Always enforced, no exceptions
 
-1. Call \`recall_best_solution\` with the task topic to get known solutions
-   - \`recall_best_solution("deploy:web")\` → returns working deploy command
-   - \`recall_best_solution("debug:redis-tls")\` → returns root cause + fix
-   - If a solution exists, use it — do NOT re-discover from scratch
+### Rule 1 — Session Start (FIRST thing in every window)
+Call \`session_start\` **before reading any source files or making any changes**:
 
-2. Call \`recall_context\` with the area you're working in
-   - \`recall_context("arch:*")\` → cached architecture decisions
-   - \`recall_context("file:src/auth*")\` → cached file summaries
+\`\`\`
+session_start(
+  instance_id = "${instance_id}",
+  focus       = "<what you plan to work on today>",
+)
+\`\`\`
+
+Returns: last session summary, handoff from previous window, recent lessons, open failures, brain health.
+
+**If \`session_start\` is unavailable**, fall back:
+1. \`smart_recall("recent lessons <topic>")\`
+2. \`recall_best_solution("<topic>")\`
+
+### Rule 2 — Learn After Every Fix/Deploy/Discovery (AUTOMATIC — no prompting needed)
+After **every** bug fix, deployment, failed attempt, or discovery — call \`learn_from_attempts\` immediately:
+
+\`\`\`
+learn_from_attempts(
+  instance_id = "${instance_id}",
+  topic       = "category:keyword",   # deploy:web | fix:auth | debug:db | infra:docker
+  outcome     = "success" | "failure" | "partial",
+  what_worked = "exact approach or command that worked",
+  what_failed = "what did NOT work (prevents future wasted time)",
+  severity    = "critical" | "major" | "minor",
+  commands    = ["exact command that worked"],
+  file_paths  = ["path/to/changed/file"],
+)
+\`\`\`
+
+**These events MUST automatically trigger \`learn_from_attempts\`:**
+- ✅ Successfully deployed → \`topic="deploy:<component>", outcome="success"\`
+- ✅ Fixed a bug → \`topic="fix:<description>", outcome="success"\`
+- ✅ Discovered root cause → \`topic="debug:<area>", outcome="partial"\`
+- ✅ Tried something that failed → \`topic="<area>", outcome="failure", what_failed="..."\`
+- ✅ Found a config quirk → \`topic="infra:<topic>", outcome="success"\`
+- ✅ Ran a working command → store it in \`commands=[...]\`
+
+### Rule 3 — Session Handoff (when closing window or task list > 3 items)
+\`\`\`
+session_handoff(
+  instance_id     = "${instance_id}",
+  completed_tasks = ["what was done"],
+  remaining_tasks = ["what is still to do"],
+  files_changed   = [{"path": "src/...", "status": "modified", "description": "what changed"}],
+  instructions    = "IMPORTANT: what the next window MUST know to not break things",
+  context_summary = "current state of the system",
+)
+\`\`\`
+
+The next \`session_start\` automatically includes this handoff. The new window sees exactly what's done, what remains, and what NOT to break.
+
+### Rule 4 — Session End (LAST thing before closing)
+\`\`\`
+session_end(
+  instance_id     = "${instance_id}",
+  summary         = "What was accomplished (2-3 sentences with specifics)",
+  files_changed   = ["list", "of", "changed", "files"],
+  lessons_learned = <number of learn_from_attempts calls made>,
+)
+\`\`\`
+
+> \`session_end\` **automatically extracts and stores lessons** from the summary text — no manual calls needed.
 
-${smartRecallNote}
-   - \`smart_recall("how does authentication work")\` → returns cached auth notes
+### Rule 5 — Code Index Invalidation (AUTOMATIC)
+- \`index_project\` tracks MD5 hashes per file — **skips unchanged files automatically**
+- After code changes: next \`index_project\` run re-indexes only modified files
+- After delete/rename: run \`index_project\` again to sync
+- No manual invalidation needed
 
-4. If nothing is found, proceed normally — then save (see below)
+---
 
-## AFTER every non-trivial task — save to memory
+## Task-type trigger table
 
-1. Call \`learn_from_attempts\` for deploy/debug/fix tasks:
-   - Always set outcome = "success" | "failure" | "partial"
-   - Always include what_failed — it prevents future wasted time
-   - Example: \`learn_from_attempts(topic="deploy:api", outcome="success", what_worked="nohup docker compose up -d --build", what_failed="direct docker compose hangs on SSH timeout")\`
+| You're about to... | Call BEFORE | Call AFTER |
+|---|---|---|
+| Deploy anything | \`recall_best_solution("deploy:<component>")\` | \`learn_from_attempts(topic="deploy:...")\` |
+| Fix a bug | \`recall_best_solution("fix:<area>")\` | \`learn_from_attempts(topic="fix:...")\` |
+| Add a feature | \`session_start(focus="feat:<area>")\` | \`learn_from_attempts(topic="feat:...")\` |
+| Infra/server work | \`recall_best_solution("infra:<topic>")\` | \`learn_from_attempts(topic="infra:...")\` |
+| Debug an issue | \`smart_recall("<error message or symptom>")\` | \`learn_from_attempts(topic="debug:...")\` |
 
-2. Call \`remember_context\` for code/architecture findings:
-   - \`remember_context("arch:auth", "Uses Keycloak with JWT...", category="architecture")\`
-   - \`remember_context("file:src/index.ts", "Entry point, registers routes...", category="file_summary")\`
+---
+
+## Available Brain Tools
+
+| Tool | When to use |
+|------|-------------|
+| \`session_start\` | **FIRST** — mandatory at start of every session |
+| \`session_end\` | **LAST** — mandatory at end, auto-learns from summary |
+| \`session_handoff\` | When closing window with remaining tasks |
+| \`learn_from_attempts\` | **AUTOMATIC** after every fix/deploy/discovery |
+| \`recall_best_solution\` | Before any non-trivial task |
+| \`remember_context\` | After analyzing code — save findings for future sessions |
+${smartRecallNote ? `| \`smart_recall\` | Search brain by meaning/keywords |\n` : ''}\
+| \`recall_context\` | Get exact key (supports glob: \`arch:*\`, \`file:*\`) |
+| \`brain_search\` | BM25+ full-text search over all brain data |
+| \`auto_learn_session\` | Batch-learn from a list of observations (optional) |
+| \`index_project\` | Index source files (smart hash, skips unchanged files) |
+| \`list_remembered\` | See what's cached in the brain |
+| \`forget_context\` | Remove stale context |
+
+---
 
 ## Instance Details
 
-- Instance ID: \`${instance_id}\`
-- Instance name: ${inst.name}
-- Tier: ${tier}
-- ${layerNote}
-- Embedding provider: ${providerArg}
+- **Instance ID:** \`${instance_id}\`
+- **Instance name:** ${inst.name}
+- **Tier:** ${tier}
+- **${layerNote}**
+- **Embedding provider:** ${providerArg}
+
+---
 
-## Quick reference
+## How the 3-layer system works
 
 \`\`\`
-recall_best_solution("topic")        # before task
-smart_recall("natural language")     # find by meaning
-learn_from_attempts(...)             # after task
-remember_context("key", "content")   # save analysis
+Layer 1 — Storage:  Your cachly Valkey instance (${inst.name}) — persists forever
+Layer 2 — Tools:    learn_from_attempts · recall_best_solution · brain_search · session_start/end
+Layer 3 — Autopilot: This file — AI reads it and runs tools automatically every session
 \`\`\`
+
+Result: Your AI **never solves the same problem twice** and always picks up exactly where it left off. 🚀
 `;
 
+
       const lines: string[] = [
         `🧠 **cachly AI Memory Setup Complete**`,
         ``,
@@ -4031,8 +4114,75 @@ const server = new Server(
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
+// ── Auto-session management ───────────────────────────────────────────────────
+// Transparently starts a Brain session on the first tool call of a process
+// and saves a session_end summary on SIGTERM/exit so users never have to call
+// session_start/session_end manually.
+
+let _autoSessionInstanceId: string | null = null;
+let _autoSessionStarted = false;
+let _autoSessionToolCount = 0;
+
+async function autoStartSession(instanceId: string): Promise<void> {
+  if (_autoSessionStarted) return;
+  _autoSessionStarted = true;
+  _autoSessionInstanceId = instanceId;
+  try {
+    await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)' });
+  } catch { /* non-fatal — session tracking is a best-effort feature */ }
+
+  // Auto-index the project if it hasn't been indexed in the last 24h.
+  // This is the main lever for growing token savings: more indexed code →
+  // more semantic cache hits → fewer LLM calls for repeated questions.
+  if (process.env.CACHLY_AUTO_INDEX !== 'false') {
+    try {
+      const redis = await getConnection(instanceId);
+      const lastIndexed = await redis.get(`cachly:index:last_indexed:${instanceId}`);
+      const staleMs = 24 * 60 * 60 * 1000;
+      const isStale = !lastIndexed || (Date.now() - parseInt(lastIndexed, 10)) > staleMs;
+      if (isStale) {
+        // Mark as indexing now to prevent concurrent re-runs.
+        await redis.set(`cachly:index:last_indexed:${instanceId}`, String(Date.now()), 'EX', 90000);
+        // Run in background — don't block the first tool call.
+        handleTool('index_project', {
+          instance_id: instanceId,
+          dir: process.cwd(),
+          max_files: 150,
+          ttl: 86400 * 7, // cache for 7 days
+          namespace: 'cachly:sem:code',
+        }).catch(() => undefined);
+      }
+    } catch { /* never block the session on indexing errors */ }
+  }
+}
+
+async function autoEndSession(): Promise<void> {
+  if (!_autoSessionStarted || !_autoSessionInstanceId) return;
+  _autoSessionStarted = false;
+  try {
+    await handleTool('session_end', {
+      instance_id: _autoSessionInstanceId,
+      summary: `Auto-ended after ${_autoSessionToolCount} tool call(s). Session was started automatically.`,
+      files_changed: [],
+      lessons_learned: 0,
+    });
+  } catch { /* non-fatal */ }
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
+
+  // Auto-start brain session on first tool call that has an instance_id.
+  // Skip session management tools to avoid recursion.
+  const sessionTools = new Set(['session_start', 'session_end', 'auto_learn_session']);
+  if (!sessionTools.has(name) && !_autoSessionStarted) {
+    const instanceId = (args as Record<string, unknown>)?.instance_id as string | undefined;
+    if (instanceId) {
+      await autoStartSession(instanceId).catch(() => undefined);
+    }
+  }
+  if (!sessionTools.has(name)) _autoSessionToolCount++;
+
   try {
     const text = await handleTool(name, (args ?? {}) as Record<string, unknown>);
     return { content: [{ type: 'text', text }] };
@@ -4042,8 +4192,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
-// Graceful shutdown – close all Redis connections
+// Graceful shutdown – close all Redis connections + auto-end brain session
 process.on('SIGTERM', async () => {
+  await autoEndSession().catch(() => undefined);
+  for (const [, client] of pool) await client.quit().catch(() => undefined);
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  await autoEndSession().catch(() => undefined);
   for (const [, client] of pool) await client.quit().catch(() => undefined);
   process.exit(0);
 });