@cachly-dev/mcp-server 0.5.1 → 0.5.3

package/dist/index.js

@@ -3291,62 +3291,144 @@ async function handleTool(name, args) {
             // 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`;
-            const copilotInstructions = `# cachly AI Memory — ${project_description}
+                ? `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 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.
 
-${smartRecallNote}
-   - \`smart_recall("how does authentication work")\` → returns cached auth notes
+### 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>,
+)
+\`\`\`
 
-4. If nothing is found, proceed normally — then save (see below)
+> \`session_end\` **automatically extracts and stores lessons** from the summary text — no manual calls needed.
 
-## AFTER every non-trivial task — save to memory
+### 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
 
-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")\`
+---
 
-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")\`
+## Task-type trigger table
+
+| 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:...")\` |
+
+---
+
+## 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 = [
                 `🧠 **cachly AI Memory Setup Complete**`,
@@ -3524,8 +3606,74 @@ async function handleBulkLockStream(name, args) {
 // ── Server setup ──────────────────────────────────────────────────────────────
 const server = new Server({ name: 'cachly-mcp', version: '0.4.0' }, { capabilities: { tools: {} } });
 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 = null;
+let _autoSessionStarted = false;
+let _autoSessionToolCount = 0;
+async function autoStartSession(instanceId) {
+    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() {
+    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?.instance_id;
+        if (instanceId) {
+            await autoStartSession(instanceId).catch(() => undefined);
+        }
+    }
+    if (!sessionTools.has(name))
+        _autoSessionToolCount++;
     try {
         const text = await handleTool(name, (args ?? {}));
         return { content: [{ type: 'text', text }] };
@@ -3536,8 +3684,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new McpError(ErrorCode.InternalError, err.message);
     }
 });
-// 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);