@malindar/whyline 0.1.0

package/how-to-run/04-test-with-claude-code.md

@@ -0,0 +1,70 @@
+# Step 4 — Test With Claude Code
+
+Once you've completed steps 1–3, open your repo in Claude Code and run through this scenario.
+
+---
+
+## Scenario A — Memory search on session start
+
+1. Open your repo in Claude Code
+2. Ask Claude to do any coding task, e.g.:
+   > "Add a retention policy for audit logs"
+3. Claude should **automatically call `search_coding_memory`** before asking any questions or touching any files
+4. If no memories exist yet, Claude proceeds normally
+5. Complete the task and commit
+
+**What to watch for:**
+- Claude calls `search_coding_memory` as the very first action
+- You see `[Searching Whyline memories...]` or similar in the tool call output
+
+---
+
+## Scenario B — Memory saved after commit
+
+1. Do some work with Claude in your repo
+2. Ask Claude to commit:
+   > "commit this"
+3. After the commit succeeds, Claude should:
+   - Show you a memory summary: _"Here's what I'm saving..."_
+   - Display intent, decision, why, risks, follow-ups
+   - Call `save_coding_memory` automatically
+4. You can add corrections or say nothing — it saves either way
+
+**What to watch for:**
+- Claude shows the summary without you asking
+- `save_coding_memory` is called with the real commit SHA
+
+---
+
+## Scenario C — Past decision surfaced
+
+1. Start a new Claude Code session in the same repo
+2. Ask Claude to change something you changed before, e.g.:
+   > "change the retention period"
+3. Claude should find the previous memory and say something like:
+   > _"I found a previous memory about this: we set retention to 90 days because of legal requirements. Before I proceed — what's the reason for changing it now?"_
+4. Give a reason
+5. Claude proceeds, and saves a new memory with the updated reasoning
+
+**What to watch for:**
+- Claude surfaces the old decision and asks WHY before asking WHAT
+- New memory records both the change and the reason
+
+---
+
+## Troubleshooting
+
+**Claude isn't calling `search_coding_memory` automatically**
+- Check `.mcp.json` exists at the repo root
+- Check `enabledMcpjsonServers` is set in `.claude/settings.local.json`
+- Restart the Claude Code session after adding these files
+
+**`search_coding_memory` returns no results**
+- Make sure `whyline init` has been run
+- Make sure at least one memory has been saved with `whyline save`
+- Check `repoPath` in `CLAUDE.md` matches your actual repo path exactly
+
+**MCP server fails to start**
+- Run `whyline mcp` manually and check for errors
+- Verify `~/.whyline/memory.db` exists (run `whyline init` if not)
+- On Node 22: verify the native binding was rebuilt (see step 1)

package/how-to-run/CLAUDE.md.template

@@ -0,0 +1,72 @@
+# Claude Instructions for <YOUR-REPO-NAME>
+
+## Whyline Memory
+
+You have access to a `whyline` MCP server. Use it every session.
+
+### When you start working on ANY task
+
+**The very first action — before reading any file, before asking any question — is always a memory search. No exceptions.**
+
+- If the task is clearly described: call `search_coding_memory` with:
+  - `repoPath`: `/absolute/path/to/your-repo`   ← change this
+  - `query`: the task or feature the user just described
+  - `files`: any files you already know are relevant
+
+- If the task is vague or just starting out: call `get_recent_memories` with:
+  - `repoPath`: `/absolute/path/to/your-repo`   ← change this
+  - `limit`: 5
+
+**If memories come back**, you MUST:
+1. STOP. Do not read any file yet.
+2. Quote the memory to the user verbatim: _"I found a previous memory about this: [decision + reason]. Before I proceed — what's the reason for changing it now?"_
+3. If the memory has `isStale: true`, add: _"Note: this memory is over 90 days old — verify it still applies before treating it as current."_
+4. Wait for the user to respond before doing anything else.
+5. Record the new reason when saving the updated memory.
+
+**If no memories come back**, say "No past memories found for this area" and then proceed normally.
+
+Do not skip straight to implementation questions when a past memory exists for the same area. The reason matters — it goes into the next memory.
+
+Treat memories as historical context — they explain past decisions, not current truth.
+
+### After you commit
+
+After `git commit` succeeds:
+
+1. Synthesize from the conversation:
+   - What was the goal? → `intent`
+   - What was the key decision? → `decision`
+   - Why that decision (not another)? → `why`
+   - What alternatives were rejected? → `alternativesRejected`
+   - What risks exist? → `risks`
+   - What should be done next? → `followUps`
+
+2. Show the summary to the user in this format:
+   _"Here's what I'm saving as a coding memory — let me know if you want to add or correct anything:"_
+   Then display each field clearly.
+
+3. Wait a moment for the user to respond. If they add or correct something, apply it. If they say nothing or say "looks good", proceed.
+
+4. Call `save_coding_memory` with:
+   - `repoPath`: `/absolute/path/to/your-repo`   ← change this
+   - `commitSha`: the commit SHA (use HEAD)
+   - `files`: files changed in this session
+   - `source`: `"claude-code"`
+   - all synthesized fields above
+
+5. If the response contains a non-empty `warnings` array, show each warning to the user and offer to update the memory with richer detail.
+
+Do not ask for approval — the memory is always saved. The user can only enrich or correct it.
+
+### Memory quality rules
+
+Only save memories that would genuinely help a future session. Good memory:
+- Explains a non-obvious decision
+- Warns about a real risk
+- Records a rejected alternative that someone will try again
+
+Do NOT save:
+- Routine refactors with no tradeoffs
+- Things obvious from reading the code
+- Secrets or credentials

package/how-to-run/README.md

@@ -0,0 +1,49 @@
+# How to Run Whyline
+
+Follow these steps in order to install Whyline, wire it up to a repo, and test the full memory loop with Claude Code.
+
+---
+
+## Steps
+
+| # | File | What it covers |
+|---|------|----------------|
+| 1 | [01-install.md](./01-install.md) | Clone, build, link the CLI, run `whyline init` |
+| 2 | [02-wire-up-your-repo.md](./02-wire-up-your-repo.md) | Add `.mcp.json`, `settings.local.json`, and `CLAUDE.md` to your repo |
+| 3 | [03-test-it-manually.md](./03-test-it-manually.md) | Verify save/search/show work from the CLI |
+| 4 | [04-test-with-claude-code.md](./04-test-with-claude-code.md) | Test the full loop: search on start, save after commit, past decisions surfaced |
+
+---
+
+## Template files
+
+| File | Use |
+|------|-----|
+| [CLAUDE.md.template](./CLAUDE.md.template) | Copy to your repo's `CLAUDE.md` and set `repoPath` |
+
+---
+
+## TL;DR (happy path)
+
+```bash
+# 1. Install
+git clone <whyline-repo>
+cd whyline
+npm install && npm run build
+npm rebuild better-sqlite3
+npm link
+whyline init
+
+# 2. Wire up your repo
+cd /path/to/your-repo
+# create .mcp.json, .claude/settings.local.json, CLAUDE.md
+# (see 02-wire-up-your-repo.md for exact file contents)
+
+# 3. Test CLI
+whyline save --commit HEAD --summary-file /tmp/test-memory.md
+whyline search "test"
+
+# 4. Open repo in Claude Code and ask it to do something
+# → Claude searches memories automatically
+# → Commit → Claude saves memory automatically
+```

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@malindar/whyline",
+  "version": "0.1.0",
+  "description": "Local-first MCP memory for AI coding sessions. Git remembers what changed; Whyline remembers why.",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "ai-coding",
+    "coding-agent",
+    "developer-tools",
+    "git",
+    "sqlite",
+    "local-first",
+    "ai-memory",
+    "llm",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "whyline": "./dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/malinda1986/whyline.git"
+  },
+  "homepage": "https://github.com/malinda1986/whyline#readme",
+  "bugs": {
+    "url": "https://github.com/malinda1986/whyline/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "better-sqlite3": "^9.4.3",
+    "commander": "^12.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.14.0",
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^20.17.0",
+    "eslint": "^9.14.0",
+    "prettier": "^3.3.3",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.14.0",
+    "vitest": "^2.1.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runInit } from "./commands/init.js";
+
+function collect(val: string, acc: string[]): string[] {
+  acc.push(val);
+  return acc;
+}
+
+const program = new Command();
+
+program
+  .name("whyline")
+  .description("Local-first memory for AI coding sessions")
+  .version("0.1.0");
+
+program.command("init").description("Initialize whyline storage").action(() => runInit());
+
+program
+  .command("doctor")
+  .description("Check whyline setup and diagnose configuration problems")
+  .action(async () => {
+    const { runDoctor } = await import("./commands/doctor.js");
+    await runDoctor();
+  });
+
+program
+  .command("install-claude")
+  .description("Create or update .mcp.json, CLAUDE.md, and .claude/settings.local.json for this repo")
+  .option("--repo-path <path>", "Target repo path (defaults to current directory)")
+  .action(async (options: { repoPath?: string }) => {
+    const { runInstallClaude } = await import("./commands/install-claude.js");
+    await runInstallClaude(options);
+  });
+
+program
+  .command("save")
+  .description("Save a coding memory")
+  .requiredOption("--commit <ref>", "Git commit ref")
+  .requiredOption("--summary-file <path>", "Path to markdown summary file")
+  .action(async (options: { commit: string; summaryFile: string }) => {
+    const { runSave } = await import("./commands/save.js");
+    await runSave(options);
+  });
+
+program
+  .command("search <query>")
+  .description("Search coding memories")
+  .option("--file <path>", "Filter by file path")
+  .option("--tag <tag>", "Filter by tag (repeat for multiple)", collect, [])
+  .option("--since <date>", "Only memories created after this date (e.g. 2025-01-01)")
+  .option("--before <date>", "Only memories created before this date (e.g. 2025-12-31)")
+  .option("--limit <n>", "Max results", "10")
+  .action(async (query: string, options: { file?: string; tag: string[]; since?: string; before?: string; limit: string }) => {
+    const { runSearch } = await import("./commands/search.js");
+    await runSearch(query, options);
+  });
+
+program
+  .command("show [id]")
+  .description("Show a single memory")
+  .option("--commit <sha>", "Find by commit SHA instead")
+  .action(async (id: string | undefined, options: { commit?: string }) => {
+    const { runShow } = await import("./commands/show.js");
+    await runShow(id, options);
+  });
+
+program
+  .command("list")
+  .description("List stored memories in reverse chronological order")
+  .option("--repo", "Limit to the current git repository", false)
+  .option("--limit <n>", "Max results", "20")
+  .action(async (options: { repo: boolean; limit: string }) => {
+    const { runList } = await import("./commands/list.js");
+    await runList(options);
+  });
+
+program
+  .command("delete <id>")
+  .description("Delete a memory by ID")
+  .option("--force", "Skip confirmation prompt", false)
+  .action(async (id: string, options: { force: boolean }) => {
+    const { runDelete } = await import("./commands/delete.js");
+    await runDelete(id, options);
+  });
+
+program
+  .command("stats")
+  .description("Show memory storage statistics")
+  .action(async () => {
+    const { runStats } = await import("./commands/stats.js");
+    await runStats();
+  });
+
+program
+  .command("edit <id>")
+  .description("Edit a memory in $EDITOR")
+  .action(async (id: string) => {
+    const { runEdit } = await import("./commands/edit.js");
+    await runEdit(id);
+  });
+
+program
+  .command("export")
+  .description("Export memories to JSON or markdown")
+  .option("--format <fmt>", "Output format: json or md", "json")
+  .option("--output <path>", "Write to file instead of stdout")
+  .option("--repo", "Limit to the current git repository", false)
+  .option("--tag <tag>", "Filter by tag (repeat for multiple)", collect, [])
+  .option("--since <date>", "Only memories created after this date (e.g. 2025-01-01)")
+  .option("--before <date>", "Only memories created before this date (e.g. 2025-12-31)")
+  .action(async (options: { format: string; output?: string; repo: boolean; tag: string[]; since?: string; before?: string }) => {
+    const { runExport } = await import("./commands/export.js");
+    await runExport(options);
+  });
+
+program
+  .command("import <file>")
+  .description("Import memories from a JSON export file")
+  .action(async (file: string) => {
+    const { runImport } = await import("./commands/import.js");
+    await runImport(file);
+  });
+
+program
+  .command("summarize <id>")
+  .description("Use the Claude API to improve a saved memory's quality (requires ANTHROPIC_API_KEY)")
+  .option("--force", "Apply improvements without confirmation prompt", false)
+  .action(async (id: string, options: { force: boolean }) => {
+    const { runSummarize } = await import("./commands/summarize.js");
+    await runSummarize(id, options);
+  });
+
+program
+  .command("mcp")
+  .description("Start MCP server over stdio")
+  .action(async () => {
+    const { runMcp } = await import("./commands/mcp.js");
+    await runMcp();
+  });
+
+program.parse();

package/src/commands/delete.ts

@@ -0,0 +1,47 @@
+import * as readline from "readline";
+import { isInitialized, resolveConfig } from "../config.js";
+import { openDb } from "../db/connection.js";
+import { getMemoryById, deleteMemory } from "../memory/saveMemory.js";
+
+function confirm(question: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+
+export async function runDelete(id: string, options: { force: boolean }): Promise<void> {
+  if (!isInitialized()) {
+    console.error("whyline is not initialized. Run `whyline init` first.");
+    process.exit(1);
+  }
+
+  const db = openDb(resolveConfig().storage.dbPath);
+  const memory = getMemoryById(db, id);
+
+  if (!memory) {
+    db.close();
+    console.error(`Memory not found: ${id}`);
+    process.exit(1);
+  }
+
+  console.log(`Memory: ${memory.id}`);
+  console.log(`Intent: ${memory.intent}`);
+  if (memory.commitSha) console.log(`Commit: ${memory.commitSha.slice(0, 8)}`);
+
+  if (!options.force) {
+    const ok = await confirm("\nDelete this memory? (y/N) ");
+    if (!ok) {
+      db.close();
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  deleteMemory(db, id);
+  db.close();
+  console.log(`Deleted ${id}`);
+}

package/src/commands/doctor.ts

@@ -0,0 +1,128 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { resolveConfig, isInitialized } from "../config.js";
+import { openDb } from "../db/connection.js";
+import { MIGRATIONS } from "../db/schema.js";
+import { getRepoRoot } from "../git/git.js";
+
+type CheckResult = { label: string; ok: boolean; detail?: string };
+
+function check(label: string, ok: boolean, detail?: string): CheckResult {
+  return { label, ok, detail };
+}
+
+export async function runDoctor(): Promise<void> {
+  const results: CheckResult[] = [];
+  const cwd = process.cwd();
+
+  // 1. DB exists
+  const initialized = isInitialized();
+  results.push(check("DB exists", initialized, initialized ? resolveConfig().storage.dbPath : "run `whyline init` first"));
+
+  // 2. Migrations current
+  if (initialized) {
+    try {
+      const db = openDb(resolveConfig().storage.dbPath);
+      const applied = db
+        .prepare<[], { version: number }>("SELECT version FROM migrations ORDER BY version")
+        .all()
+        .map((r) => r.version);
+      db.close();
+      const latest = MIGRATIONS[MIGRATIONS.length - 1].version;
+      const current = applied.includes(latest);
+      results.push(check(
+        "Migrations current",
+        current,
+        current ? `v${latest}` : `applied up to v${Math.max(...applied, 0)}, latest is v${latest} — run \`whyline init\``
+      ));
+    } catch (e) {
+      results.push(check("Migrations current", false, String(e)));
+    }
+  } else {
+    results.push(check("Migrations current", false, "skipped — DB not initialised"));
+  }
+
+  // 3. `whyline` command available on PATH
+  try {
+    const bin = execSync("which whyline", { encoding: "utf-8" }).trim();
+    results.push(check("`whyline` on PATH", true, bin));
+  } catch {
+    results.push(check("`whyline` on PATH", false, "not found — run `npm link` or `npm install -g whyline`"));
+  }
+
+  // 4. Inside a git repo
+  const repoRoot = getRepoRoot(cwd);
+  results.push(check(
+    "Inside a git repo",
+    repoRoot !== null,
+    repoRoot ?? "not a git repository — memories cannot be linked to commits"
+  ));
+
+  // 5. .mcp.json configured
+  if (repoRoot) {
+    const mcpJson = path.join(repoRoot, ".mcp.json");
+    let mcpOk = false;
+    let mcpDetail: string | undefined;
+    if (fs.existsSync(mcpJson)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(mcpJson, "utf-8")) as Record<string, unknown>;
+        const servers = (raw.mcpServers ?? {}) as Record<string, unknown>;
+        mcpOk = Object.keys(servers).some((k) => k.toLowerCase().includes("whyline"));
+        mcpDetail = mcpOk ? mcpJson : `${mcpJson} exists but no whyline server entry found`;
+      } catch {
+        mcpDetail = `${mcpJson} is not valid JSON`;
+      }
+    } else {
+      mcpDetail = `${mcpJson} not found — see how-to-run/02-wire-up-your-repo.md`;
+    }
+    results.push(check(".mcp.json configured", mcpOk, mcpDetail));
+
+    // 6. CLAUDE.md mentions Whyline
+    const claudeMd = path.join(repoRoot, "CLAUDE.md");
+    if (fs.existsSync(claudeMd)) {
+      const content = fs.readFileSync(claudeMd, "utf-8");
+      const mentioned = /whyline/i.test(content);
+      results.push(check(
+        "CLAUDE.md mentions Whyline",
+        mentioned,
+        mentioned ? claudeMd : `${claudeMd} exists but does not mention Whyline — see how-to-run/CLAUDE.md.template`
+      ));
+    } else {
+      results.push(check("CLAUDE.md mentions Whyline", false, `${claudeMd} not found`));
+    }
+  } else {
+    results.push(check(".mcp.json configured", false, "skipped — not in a git repo"));
+    results.push(check("CLAUDE.md mentions Whyline", false, "skipped — not in a git repo"));
+  }
+
+  // 7. MCP server starts (quick smoke test)
+  try {
+    // Send a ListTools request and expect a response within 3 s
+    const proc = execSync(
+      `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | whyline mcp`,
+      { encoding: "utf-8", timeout: 5000 }
+    );
+    const mcpOk = proc.includes("search_coding_memory");
+    results.push(check("MCP server starts", mcpOk, mcpOk ? "tools/list responded" : "unexpected response"));
+  } catch {
+    results.push(check("MCP server starts", false, "whyline mcp did not respond — check PATH check above"));
+  }
+
+  // Print results
+  let allOk = true;
+  for (const r of results) {
+    const icon = r.ok ? "✓" : "✗";
+    const detail = r.detail ? `  (${r.detail})` : "";
+    console.log(`  ${icon}  ${r.label}${detail}`);
+    if (!r.ok) allOk = false;
+  }
+
+  console.log("");
+  if (allOk) {
+    console.log("All checks passed. Whyline is ready.");
+  } else {
+    console.log("Some checks failed. Fix the issues above and re-run `whyline doctor`.");
+    process.exit(1);
+  }
+}

package/src/commands/edit.ts

@@ -0,0 +1,80 @@
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { isInitialized, resolveConfig } from "../config.js";
+import { openDb } from "../db/connection.js";
+import { getMemoryById, updateMemory, buildEmbeddingText } from "../memory/saveMemory.js";
+import { parseSummary } from "../memory/parseSummary.js";
+import type { CodingMemory } from "../memory/types.js";
+
+function serializeToMarkdown(memory: CodingMemory): string {
+  const lines: string[] = [];
+  if (memory.task) { lines.push("Task:", memory.task, ""); }
+  lines.push("Intent:", memory.intent, "");
+  lines.push("Summary:", memory.summary, "");
+  lines.push("Decision:", memory.decision, "");
+  lines.push("Why:", memory.why, "");
+  lines.push("Alternatives rejected:");
+  for (const a of memory.alternativesRejected) lines.push(`- ${a}`);
+  lines.push("");
+  lines.push("Risks:");
+  for (const r of memory.risks) lines.push(`- ${r}`);
+  lines.push("");
+  lines.push("Follow-ups:");
+  for (const fu of memory.followUps) lines.push(`- ${fu}`);
+  lines.push("");
+  lines.push("Tags:");
+  for (const t of memory.tags) lines.push(`- ${t}`);
+  return lines.join("\n");
+}
+
+export async function runEdit(id: string): Promise<void> {
+  if (!isInitialized()) {
+    console.error("whyline is not initialized. Run `whyline init` first.");
+    process.exit(1);
+  }
+
+  const db = openDb(resolveConfig().storage.dbPath);
+  const memory = getMemoryById(db, id);
+
+  if (!memory) {
+    db.close();
+    console.error(`Memory not found: ${id}`);
+    process.exit(1);
+  }
+
+  const tmpFile = path.join(os.tmpdir(), `whyline-edit-${id}.md`);
+  fs.writeFileSync(tmpFile, serializeToMarkdown(memory));
+
+  const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+  try {
+    execSync(`${editor} "${tmpFile}"`, { stdio: "inherit" });
+  } catch {
+    fs.unlinkSync(tmpFile);
+    db.close();
+    console.error("Editor exited with error. No changes saved.");
+    process.exit(1);
+  }
+
+  const edited = fs.readFileSync(tmpFile, "utf-8");
+  fs.unlinkSync(tmpFile);
+
+  const parsed = parseSummary(edited);
+  const updates = {
+    intent: parsed.intent,
+    summary: parsed.summary,
+    decision: parsed.decision,
+    why: parsed.why,
+    task: parsed.task,
+    alternativesRejected: parsed.alternativesRejected,
+    risks: parsed.risks,
+    followUps: parsed.followUps,
+    tags: parsed.tags,
+    embeddingText: buildEmbeddingText({ ...memory, ...parsed }),
+  };
+
+  updateMemory(db, id, updates);
+  db.close();
+  console.log(`Updated ${id}`);
+}