@cachly-dev/mcp-server 0.10.62 → 0.10.64

package/src/tools.ts

@@ -617,6 +617,7 @@ const TOOLS = [
         instance_id: { type: 'string', description: 'UUID of the cache instance' },
         query: { type: 'string', description: 'Natural language query to find relevant cached context' },
         threshold: { type: 'number', description: 'Similarity threshold 0-1 (default: 0.78)' },
+        author: { type: 'string', description: 'Handle of the person doing the recall (optional). Enables team-knowledge-reuse tracking: when you recall a lesson written by a teammate, cachly counts it as cross-author reuse — the value only a shared brain delivers.' },
       },
       required: ['instance_id', 'query'],
     },
@@ -893,6 +894,22 @@ const TOOLS = [
       required: ['instance_id'],
     },
   },
+  {
+    name: 'brain_metrics',
+    description:
+      'Report the three decisive Brain metrics: (1) time-to-first-recall (onboarding friction), ' +
+      '(2) recall-lift vs. raw BM25 (the moat proof, from Cachly-Bench), and ' +
+      '(3) team-knowledge-reuse — what % of proven recalls used a teammate\'s lesson. ' +
+      'Use to track whether the Brain is delivering its core value. ' +
+      'Pass author="handle" to smart_recall so cross-author reuse can be measured.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+      },
+      required: ['instance_id'],
+    },
+  },
   {
     name: 'sync_file_changes',
     description:

package/src/utils.ts

@@ -8,3 +8,83 @@ export function safeJsonParse<T>(raw: string | null | undefined, fallback: T): T
     return fallback;
   }
 }
+
+/**
+ * Runs a promise with a hard timeout. If it doesn't settle within `ms`, resolves
+ * with `fallback` instead of hanging. A memory tool must NEVER block the agent's
+ * turn — a slow Redis scan or unreachable backend degrades gracefully to a fallback.
+ */
+export async function withTimeout<T>(p: Promise<T>, ms: number, fallback: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const guard = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(fallback), ms);
+  });
+  try {
+    return await Promise.race([p, guard]);
+  } catch {
+    return fallback;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// Minimal structural type for the Redis scan API we depend on — avoids importing
+// the full ioredis type into a leaf utility module.
+interface ScanCapable {
+  scanStream(opts: { match: string; count?: number }): {
+    on(event: 'data', cb: (batch: string[]) => void): void;
+    on(event: 'end', cb: () => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+  };
+}
+
+/**
+ * Collects keys matching a pattern with a hard cap and timeout. Prevents a tool
+ * from hanging on a huge keyspace: stops early at `max` keys, and resolves with
+ * whatever was gathered if the scan exceeds `timeoutMs`. Never rejects.
+ */
+export function scanKeys(
+  redis: ScanCapable,
+  pattern: string,
+  opts: { max?: number; count?: number; timeoutMs?: number } = {},
+): Promise<string[]> {
+  const max = opts.max ?? 1000;
+  const timeoutMs = opts.timeoutMs ?? 3000;
+  return new Promise<string[]>((resolve) => {
+    const keys: string[] = [];
+    let done = false;
+    const finish = () => { if (!done) { done = true; resolve(keys); } };
+    const timer = setTimeout(finish, timeoutMs);
+    try {
+      const stream = redis.scanStream({ match: pattern, count: opts.count ?? 200 });
+      stream.on('data', (batch: string[]) => {
+        for (const k of batch) {
+          keys.push(k);
+          if (keys.length >= max) { clearTimeout(timer); finish(); return; }
+        }
+      });
+      stream.on('end', () => { clearTimeout(timer); finish(); });
+      stream.on('error', () => { clearTimeout(timer); finish(); });
+    } catch {
+      clearTimeout(timer);
+      finish();
+    }
+  });
+}
+
+/**
+ * Normalizes a git path that may come from `--name-only` with rename notation,
+ * e.g. `src/{old => new}/file.ts` → `src/new/file.ts`, and `a => b` → `b`.
+ * Returns the post-rename path so file nodes don't fragment on renames.
+ */
+export function normalizeGitPath(raw: string): string {
+  let p = raw.trim();
+  if (!p) return p;
+  // Brace rename: dir/{old => new}/file  →  dir/new/file
+  p = p.replace(/\{[^}]*=>\s*([^}]*)\}/g, (_m, after: string) => after.trim());
+  // Bare rename: old => new  →  new
+  const arrow = p.split('=>');
+  if (arrow.length === 2) p = arrow[1]!.trim();
+  // Collapse any double slashes introduced by an empty rename segment.
+  return p.replace(/\/{2,}/g, '/').replace(/^\/|\/$/g, '');
+}