@malindar/whyline 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,326 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { resolveConfig } from "../config.js";
+import { openDb } from "../db/connection.js";
+import { searchMemory, isStale } from "../memory/searchMemory.js";
+import {
+  saveMemory,
+  generateMemoryId,
+  buildEmbeddingText,
+  getMemoriesByCommit,
+  getMemoriesByFile,
+  listMemories,
+} from "../memory/saveMemory.js";
+import { getRepoId } from "../git/repoId.js";
+import { getFileRenameHistory } from "../git/diff.js";
+import { redactSecrets } from "../memory/redactSecrets.js";
+import { checkQuality, checkDuplicates } from "../memory/qualityCheck.js";
+import {
+  SearchMemoryInput,
+  SaveMemoryInput,
+  GetCommitMemoryInput,
+  GetFileMemoriesInput,
+  GetRecentMemoriesInput,
+} from "./tools.js";
+import type { CodingMemory } from "../memory/types.js";
+
+function resolveRepoId(repoPath?: string, repoId?: string): string | undefined {
+  if (repoId) return repoId;
+  if (repoPath) {
+    try {
+      return getRepoId(repoPath);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+export async function createMcpServer(): Promise<void> {
+  const server = new Server(
+    { name: "whyline", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "search_coding_memory",
+        description:
+          "Search stored coding memories by keyword. Returns relevant memories with reasoning about why and tradeoffs made.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search query" },
+            repoPath: { type: "string", description: "Absolute path to the git repository" },
+            repoId: { type: "string", description: "Repository ID (hash)" },
+            files: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter by file paths",
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Filter by tags (memory must have all listed tags)",
+            },
+            since: { type: "string", description: "ISO date — only memories created after this (e.g. 2025-01-01)" },
+            before: { type: "string", description: "ISO date — only memories created before this (e.g. 2025-12-31)" },
+            limit: { type: "number", description: "Max results (default 10)" },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "save_coding_memory",
+        description: "Save a new coding memory with reasoning, decisions, and context. Returns warnings if fields are too short, contain filler text, or a similar memory already exists — surface these warnings to the user so they can enrich the memory.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            repoPath: { type: "string" },
+            commitSha: { type: "string" },
+            files: { type: "array", items: { type: "string" } },
+            task: { type: "string" },
+            intent: { type: "string" },
+            summary: { type: "string" },
+            decision: { type: "string" },
+            why: { type: "string" },
+            alternativesRejected: { type: "array", items: { type: "string" } },
+            risks: { type: "array", items: { type: "string" } },
+            followUps: { type: "array", items: { type: "string" } },
+            tags: { type: "array", items: { type: "string" } },
+            source: {
+              type: "string",
+              enum: ["manual", "claude-code", "cli", "hook"],
+            },
+          },
+          required: ["files", "intent", "summary", "decision", "why"],
+        },
+      },
+      {
+        name: "get_commit_memory",
+        description: "Get coding memories associated with a specific git commit.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            commitSha: { type: "string" },
+            repoPath: { type: "string" },
+            repoId: { type: "string" },
+          },
+          required: ["commitSha"],
+        },
+      },
+      {
+        name: "get_file_memories",
+        description: "Get coding memories that touch a specific file path.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            filePath: { type: "string" },
+            repoPath: { type: "string" },
+            repoId: { type: "string" },
+            limit: { type: "number" },
+          },
+          required: ["filePath"],
+        },
+      },
+      {
+        name: "get_recent_memories",
+        description: "Get the most recent coding memories for a repo without requiring a search query. Use this at session start when the task is not yet defined, to surface relevant recent context.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            repoPath: { type: "string", description: "Absolute path to the git repository" },
+            repoId: { type: "string", description: "Repository ID (hash)" },
+            limit: { type: "number", description: "Max results (default 5)" },
+          },
+          required: [],
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const db = openDb(resolveConfig().storage.dbPath);
+    try {
+      switch (request.params.name) {
+        case "search_coding_memory": {
+          const input = SearchMemoryInput.parse(request.params.arguments);
+          const resolvedRepoId = resolveRepoId(input.repoPath, input.repoId);
+          const results = searchMemory(db, {
+            query: input.query,
+            repoId: resolvedRepoId,
+            repoPath: input.repoPath,
+            files: input.files,
+            tags: input.tags,
+            since: input.since,
+            before: input.before,
+            limit: input.limit,
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  memories: results.map((r) => ({
+                    id: r.memory.id,
+                    commitSha: r.memory.commitSha,
+                    createdAt: r.memory.createdAt,
+                    files: r.memory.files,
+                    intent: r.memory.intent,
+                    summary: r.memory.summary,
+                    decision: r.memory.decision,
+                    why: r.memory.why,
+                    alternativesRejected: r.memory.alternativesRejected,
+                    risks: r.memory.risks,
+                    followUps: r.memory.followUps,
+                    tags: r.memory.tags,
+                    relevanceReason: r.relevanceReason,
+                    isStale: isStale(r.memory),
+                  })),
+                }),
+              },
+            ],
+          };
+        }
+
+        case "save_coding_memory": {
+          const input = SaveMemoryInput.parse(request.params.arguments);
+          const resolvedRepoId = resolveRepoId(input.repoPath, undefined);
+          const now = new Date().toISOString();
+          const id = generateMemoryId();
+
+          const memory: CodingMemory = {
+            id,
+            createdAt: now,
+            updatedAt: now,
+            repoId: resolvedRepoId ?? "unknown",
+            repoPath: input.repoPath,
+            commitSha: input.commitSha,
+            files: input.files,
+            tags: input.tags.map(redactSecrets),
+            task: input.task ? redactSecrets(input.task) : undefined,
+            intent: redactSecrets(input.intent),
+            summary: redactSecrets(input.summary),
+            decision: redactSecrets(input.decision),
+            why: redactSecrets(input.why),
+            alternativesRejected: input.alternativesRejected.map(redactSecrets),
+            risks: input.risks.map(redactSecrets),
+            followUps: input.followUps.map(redactSecrets),
+            source: input.source,
+            embeddingText: "",
+          };
+          memory.embeddingText = buildEmbeddingText(memory);
+
+          const qualityWarnings = checkQuality(memory);
+          const duplicateWarnings = checkDuplicates(db, memory);
+
+          saveMemory(db, memory);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                id,
+                saved: true,
+                warnings: [
+                  ...qualityWarnings.map((w) => w.message),
+                  ...duplicateWarnings.map((w) => w.message),
+                ],
+              }),
+            }],
+          };
+        }
+
+        case "get_commit_memory": {
+          const input = GetCommitMemoryInput.parse(request.params.arguments);
+          const memories = getMemoriesByCommit(db, input.commitSha);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  memories: memories.map((m) => ({
+                    id: m.id,
+                    intent: m.intent,
+                    decision: m.decision,
+                    why: m.why,
+                    files: m.files,
+                    risks: m.risks,
+                    followUps: m.followUps,
+                  })),
+                }),
+              },
+            ],
+          };
+        }
+
+        case "get_file_memories": {
+          const input = GetFileMemoriesInput.parse(request.params.arguments);
+          const resolvedRepoId = resolveRepoId(input.repoPath, input.repoId) ?? null;
+          const filePaths = input.repoPath
+            ? getFileRenameHistory(input.repoPath, input.filePath)
+            : [input.filePath];
+          const memories = getMemoriesByFile(db, resolvedRepoId, filePaths, input.limit);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  memories: memories.map((m) => ({
+                    id: m.id,
+                    commitSha: m.commitSha,
+                    intent: m.intent,
+                    decision: m.decision,
+                    why: m.why,
+                    risks: m.risks,
+                    followUps: m.followUps,
+                  })),
+                }),
+              },
+            ],
+          };
+        }
+
+        case "get_recent_memories": {
+          const input = GetRecentMemoriesInput.parse(request.params.arguments);
+          const resolvedRepoId = resolveRepoId(input.repoPath, input.repoId);
+          const memories = listMemories(db, { repoId: resolvedRepoId, limit: input.limit });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  memories: memories.map((m) => ({
+                    id: m.id,
+                    commitSha: m.commitSha,
+                    createdAt: m.createdAt,
+                    files: m.files,
+                    intent: m.intent,
+                    decision: m.decision,
+                    why: m.why,
+                    risks: m.risks,
+                    followUps: m.followUps,
+                    tags: m.tags,
+                    isStale: isStale(m),
+                  })),
+                }),
+              },
+            ],
+          };
+        }
+
+        default:
+          throw new Error(`Unknown tool: ${request.params.name}`);
+      }
+    } finally {
+      db.close();
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+export const SearchMemoryInput = z.object({
+  repoPath: z.string().optional(),
+  repoId: z.string().optional(),
+  query: z.string(),
+  files: z.array(z.string()).optional(),
+  tags: z.array(z.string()).optional(),
+  since: z.string().optional(),
+  before: z.string().optional(),
+  limit: z.number().int().positive().default(10),
+});
+
+export const SaveMemoryInput = z.object({
+  repoPath: z.string().optional(),
+  commitSha: z.string().optional(),
+  files: z.array(z.string()),
+  task: z.string().optional(),
+  intent: z.string(),
+  summary: z.string(),
+  decision: z.string(),
+  why: z.string(),
+  alternativesRejected: z.array(z.string()).default([]),
+  risks: z.array(z.string()).default([]),
+  followUps: z.array(z.string()).default([]),
+  tags: z.array(z.string()).default([]),
+  source: z.enum(["manual", "claude-code", "cli", "hook"]).default("claude-code"),
+});
+
+export const GetCommitMemoryInput = z.object({
+  repoPath: z.string().optional(),
+  repoId: z.string().optional(),
+  commitSha: z.string(),
+});
+
+export const GetFileMemoriesInput = z.object({
+  repoPath: z.string().optional(),
+  repoId: z.string().optional(),
+  filePath: z.string(),
+  limit: z.number().int().positive().default(10),
+});
+
+export const GetRecentMemoriesInput = z.object({
+  repoPath: z.string().optional(),
+  repoId: z.string().optional(),
+  limit: z.number().int().positive().default(5),
+});
+
+export type SearchMemoryInputType = z.infer<typeof SearchMemoryInput>;
+export type SaveMemoryInputType = z.infer<typeof SaveMemoryInput>;
+export type GetCommitMemoryInputType = z.infer<typeof GetCommitMemoryInput>;
+export type GetFileMemoriesInputType = z.infer<typeof GetFileMemoriesInput>;
+export type GetRecentMemoriesInputType = z.infer<typeof GetRecentMemoriesInput>;

package/src/memory/parseSummary.ts

@@ -0,0 +1,72 @@
+export type ParsedSummary = {
+  task?: string;
+  intent: string;
+  summary: string;
+  decision: string;
+  why: string;
+  alternativesRejected: string[];
+  risks: string[];
+  followUps: string[];
+  tags: string[];
+};
+
+const HEADING_REGEX = /^([A-Za-z][A-Za-z\- ]+):\s*$/m;
+
+function extractSections(text: string): Record<string, string> {
+  const lines = text.split("\n");
+  const sections: Record<string, string> = {};
+  let currentHeading: string | null = null;
+  const buffer: string[] = [];
+
+  const flush = () => {
+    if (currentHeading !== null) {
+      sections[currentHeading] = buffer.join("\n").trim();
+      buffer.length = 0;
+    }
+  };
+
+  for (const line of lines) {
+    const match = line.match(/^([A-Za-z][A-Za-z\- ]+):\s*$/);
+    if (match) {
+      flush();
+      currentHeading = match[1].toLowerCase();
+    } else {
+      if (currentHeading !== null) {
+        buffer.push(line);
+      }
+    }
+  }
+  flush();
+
+  return sections;
+}
+
+function parseBullets(text: string): string[] {
+  return text
+    .split("\n")
+    .map((l) => l.replace(/^[-*]\s*/, "").trim())
+    .filter(Boolean);
+}
+
+export function parseSummary(markdown: string): ParsedSummary {
+  // Remove markdown h1 title lines before parsing sections
+  const text = markdown.replace(/^#[^#].*$/m, "").trim();
+  const sections = extractSections(text);
+
+  const get = (key: string): string | undefined => sections[key];
+
+  return {
+    task: get("task")?.trim() || undefined,
+    intent: get("intent")?.trim() || "Unspecified intent",
+    summary: get("summary")?.trim() || markdown.trim(),
+    decision: get("decision")?.trim() || "Unspecified decision",
+    why: get("why")?.trim() || "Unspecified rationale",
+    alternativesRejected: parseBullets(get("alternatives rejected") ?? ""),
+    risks: parseBullets(get("risks") ?? ""),
+    followUps: parseBullets(get("follow-ups") ?? get("follow ups") ?? ""),
+    tags: parseBullets(get("tags") ?? ""),
+  };
+}
+
+// Keep HEADING_REGEX exported for potential reuse
+export { HEADING_REGEX };

package/src/memory/qualityCheck.ts

@@ -0,0 +1,102 @@
+import type Database from "better-sqlite3";
+import type { CodingMemory } from "./types.js";
+import { getMemoriesByRepoId } from "./saveMemory.js";
+
+const FILLER_PHRASES = [
+  "done", "fixed", "fixed it", "updated", "changed", "refactored",
+  "wip", "misc", "test", "testing", "cleanup", "fix", "update",
+  "unspecified intent", "unspecified decision", "unspecified rationale",
+];
+
+const MIN_FIELD_LENGTH = 20;
+
+export type QualityWarning = {
+  field: string;
+  message: string;
+};
+
+export type DuplicateWarning = {
+  type: "same-commit" | "similar-intent";
+  existingId: string;
+  message: string;
+};
+
+export function checkQuality(memory: Pick<CodingMemory, "intent" | "decision" | "why">): QualityWarning[] {
+  const warnings: QualityWarning[] = [];
+
+  const checks: Array<{ field: string; value: string }> = [
+    { field: "intent", value: memory.intent },
+    { field: "decision", value: memory.decision },
+    { field: "why", value: memory.why },
+  ];
+
+  for (const { field, value } of checks) {
+    const trimmed = value.trim().toLowerCase();
+
+    if (trimmed.length < MIN_FIELD_LENGTH) {
+      warnings.push({
+        field,
+        message: `"${field}" is very short (${trimmed.length} chars) — future searches may not find this memory`,
+      });
+      continue;
+    }
+
+    if (FILLER_PHRASES.some((phrase) => trimmed === phrase || trimmed.startsWith(phrase + " "))) {
+      warnings.push({
+        field,
+        message: `"${field}" looks like filler text ("${value.trim()}") — consider adding more detail`,
+      });
+    }
+  }
+
+  return warnings;
+}
+
+function jaccardSimilarity(a: string, b: string): number {
+  const setA = new Set(a.toLowerCase().split(/\s+/).filter((w) => w.length > 2));
+  const setB = new Set(b.toLowerCase().split(/\s+/).filter((w) => w.length > 2));
+  if (setA.size === 0 && setB.size === 0) return 1;
+  if (setA.size === 0 || setB.size === 0) return 0;
+  const intersection = [...setA].filter((w) => setB.has(w)).length;
+  const union = new Set([...setA, ...setB]).size;
+  return intersection / union;
+}
+
+export function checkDuplicates(
+  db: Database.Database,
+  memory: Pick<CodingMemory, "repoId" | "commitSha" | "files" | "intent">
+): DuplicateWarning[] {
+  const warnings: DuplicateWarning[] = [];
+  const existing = getMemoriesByRepoId(db, memory.repoId);
+
+  // Same commit SHA
+  if (memory.commitSha) {
+    const sameCommit = existing.find((m) => m.commitSha === memory.commitSha);
+    if (sameCommit) {
+      warnings.push({
+        type: "same-commit",
+        existingId: sameCommit.id,
+        message: `A memory already exists for commit ${memory.commitSha.slice(0, 8)} (${sameCommit.id}) — saving anyway but you may want to delete the old one`,
+      });
+    }
+  }
+
+  // Similar intent + overlapping files
+  const fileSet = new Set(memory.files);
+  for (const m of existing) {
+    if (memory.commitSha && m.commitSha === memory.commitSha) continue; // already caught above
+    const fileOverlap = m.files.filter((f) => fileSet.has(f)).length;
+    if (fileOverlap === 0) continue;
+    const similarity = jaccardSimilarity(memory.intent, m.intent);
+    if (similarity >= 0.4) {
+      warnings.push({
+        type: "similar-intent",
+        existingId: m.id,
+        message: `A similar memory exists (${m.id}) with ${Math.round(similarity * 100)}% intent similarity on the same files — consider editing it instead`,
+      });
+      break;
+    }
+  }
+
+  return warnings;
+}

package/src/memory/redactSecrets.ts

@@ -0,0 +1,32 @@
+type SecretPattern = { name: string; pattern: RegExp };
+
+export const SECRET_PATTERNS: SecretPattern[] = [
+  { name: "github_token", pattern: /ghp_[A-Za-z0-9]{36}/g },
+  { name: "github_oauth", pattern: /gho_[A-Za-z0-9]{36}/g },
+  { name: "github_app_token", pattern: /ghs_[A-Za-z0-9]{36}/g },
+  { name: "npm_token", pattern: /npm_[A-Za-z0-9]{36}/g },
+  { name: "aws_access_key", pattern: /AKIA[0-9A-Z]{16}/g },
+  {
+    name: "bearer_token",
+    pattern: /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+  },
+  {
+    name: "dotenv_secret",
+    pattern:
+      /(?:API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY|ACCESS_KEY|AUTH_KEY)\s*=\s*\S+/gi,
+  },
+  {
+    name: "private_key_block",
+    pattern: /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+PRIVATE KEY-----/g,
+  },
+];
+
+export function redactSecrets(input: string): string {
+  let output = input;
+  for (const { pattern } of SECRET_PATTERNS) {
+    // Reset lastIndex for global regexes to avoid stateful bugs
+    pattern.lastIndex = 0;
+    output = output.replace(pattern, "[REDACTED_SECRET]");
+  }
+  return output;
+}

package/src/memory/repoContext.ts

@@ -0,0 +1,25 @@
+import { getRepoRoot, getCurrentBranch, resolveCommit } from "../git/git.js";
+import { getRepoId, getRepoName } from "../git/repoId.js";
+import { getChangedFilesForCommit } from "../git/diff.js";
+import type { RepoContext } from "./types.js";
+
+export function getRepoContext(cwd: string, commitRef: string): RepoContext {
+  const repoRoot = getRepoRoot(cwd);
+  if (!repoRoot) throw new Error("Not inside a git repository");
+
+  const commitSha = resolveCommit(repoRoot, commitRef);
+  const repoId = getRepoId(repoRoot);
+  const repoName = getRepoName(repoRoot);
+  const branch = getCurrentBranch(repoRoot);
+  const changedFiles = getChangedFilesForCommit(repoRoot, commitSha);
+
+  return {
+    repoRoot,
+    repoId,
+    repoPath: repoRoot,
+    repoName,
+    branch,
+    commitSha,
+    changedFiles,
+  };
+}