@malindar/whyline 0.1.0

package/src/memory/saveMemory.ts

@@ -0,0 +1,369 @@
+import crypto from "crypto";
+import type Database from "better-sqlite3";
+import type { CodingMemory } from "./types.js";
+
+export function generateMemoryId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+  return `mem_${timestamp}${random}`;
+}
+
+export function buildEmbeddingText(
+  memory: Pick<
+    CodingMemory,
+    | "intent"
+    | "summary"
+    | "decision"
+    | "why"
+    | "alternativesRejected"
+    | "risks"
+    | "followUps"
+    | "tags"
+    | "files"
+    | "commitSha"
+  >
+): string {
+  return [
+    memory.intent,
+    memory.summary,
+    memory.decision,
+    memory.why,
+    ...memory.alternativesRejected,
+    ...memory.risks,
+    ...memory.followUps,
+    ...memory.tags,
+    ...memory.files,
+    memory.commitSha ?? "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+export function saveMemory(db: Database.Database, memory: CodingMemory): void {
+  const insertMemory = db.prepare(`
+    INSERT INTO memories (
+      id, created_at, updated_at,
+      repo_id, repo_path, repo_name, branch, commit_sha,
+      task, intent, summary, decision, why,
+      source, raw_transcript_path, embedding_text
+    ) VALUES (
+      ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?
+    )
+  `);
+
+  const insertFile = db.prepare(
+    "INSERT OR IGNORE INTO memory_files (memory_id, file_path) VALUES (?, ?)"
+  );
+  const insertTag = db.prepare(
+    "INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)"
+  );
+  const insertAlt = db.prepare(
+    "INSERT OR IGNORE INTO memory_alternatives (memory_id, value) VALUES (?, ?)"
+  );
+  const insertRisk = db.prepare(
+    "INSERT OR IGNORE INTO memory_risks (memory_id, value) VALUES (?, ?)"
+  );
+  const insertFollowup = db.prepare(
+    "INSERT OR IGNORE INTO memory_followups (memory_id, value) VALUES (?, ?)"
+  );
+
+  const run = db.transaction(() => {
+    insertMemory.run(
+      memory.id,
+      memory.createdAt,
+      memory.updatedAt,
+      memory.repoId,
+      memory.repoPath ?? null,
+      memory.repoName ?? null,
+      memory.branch ?? null,
+      memory.commitSha ?? null,
+      memory.task ?? null,
+      memory.intent,
+      memory.summary,
+      memory.decision,
+      memory.why,
+      memory.source,
+      memory.rawTranscriptPath ?? null,
+      memory.embeddingText
+    );
+    for (const f of memory.files) insertFile.run(memory.id, f);
+    for (const t of memory.tags) insertTag.run(memory.id, t);
+    for (const a of memory.alternativesRejected) insertAlt.run(memory.id, a);
+    for (const r of memory.risks) insertRisk.run(memory.id, r);
+    for (const fu of memory.followUps) insertFollowup.run(memory.id, fu);
+  });
+
+  run();
+}
+
+type MemoryRow = {
+  id: string;
+  created_at: string;
+  updated_at: string;
+  repo_id: string;
+  repo_path: string | null;
+  repo_name: string | null;
+  branch: string | null;
+  commit_sha: string | null;
+  task: string | null;
+  intent: string;
+  summary: string;
+  decision: string;
+  why: string;
+  source: string;
+  raw_transcript_path: string | null;
+  embedding_text: string;
+};
+
+function hydrateMemory(db: Database.Database, row: MemoryRow): CodingMemory {
+  const files = db
+    .prepare<[string], { file_path: string }>(
+      "SELECT file_path FROM memory_files WHERE memory_id = ?"
+    )
+    .all(row.id)
+    .map((r) => r.file_path);
+
+  const tags = db
+    .prepare<[string], { tag: string }>("SELECT tag FROM memory_tags WHERE memory_id = ?")
+    .all(row.id)
+    .map((r) => r.tag);
+
+  const alternativesRejected = db
+    .prepare<[string], { value: string }>(
+      "SELECT value FROM memory_alternatives WHERE memory_id = ?"
+    )
+    .all(row.id)
+    .map((r) => r.value);
+
+  const risks = db
+    .prepare<[string], { value: string }>(
+      "SELECT value FROM memory_risks WHERE memory_id = ?"
+    )
+    .all(row.id)
+    .map((r) => r.value);
+
+  const followUps = db
+    .prepare<[string], { value: string }>(
+      "SELECT value FROM memory_followups WHERE memory_id = ?"
+    )
+    .all(row.id)
+    .map((r) => r.value);
+
+  return {
+    id: row.id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    repoId: row.repo_id,
+    repoPath: row.repo_path ?? undefined,
+    repoName: row.repo_name ?? undefined,
+    branch: row.branch ?? undefined,
+    commitSha: row.commit_sha ?? undefined,
+    task: row.task ?? undefined,
+    intent: row.intent,
+    summary: row.summary,
+    decision: row.decision,
+    why: row.why,
+    source: row.source as CodingMemory["source"],
+    rawTranscriptPath: row.raw_transcript_path ?? undefined,
+    embeddingText: row.embedding_text,
+    files,
+    tags,
+    alternativesRejected,
+    risks,
+    followUps,
+  };
+}
+
+export function getMemoryById(db: Database.Database, id: string): CodingMemory | null {
+  const row = db
+    .prepare<[string], MemoryRow>("SELECT * FROM memories WHERE id = ?")
+    .get(id);
+  return row ? hydrateMemory(db, row) : null;
+}
+
+export function getMemoryByCommit(db: Database.Database, commitSha: string): CodingMemory | null {
+  const row = db
+    .prepare<[string], MemoryRow>("SELECT * FROM memories WHERE commit_sha = ? LIMIT 1")
+    .get(commitSha);
+  return row ? hydrateMemory(db, row) : null;
+}
+
+export function getMemoriesByCommit(db: Database.Database, commitSha: string): CodingMemory[] {
+  const rows = db
+    .prepare<[string], MemoryRow>("SELECT * FROM memories WHERE commit_sha = ?")
+    .all(commitSha);
+  return rows.map((r) => hydrateMemory(db, r));
+}
+
+export function getMemoriesByFile(
+  db: Database.Database,
+  repoId: string | null,
+  filePaths: string | string[],
+  limit: number
+): CodingMemory[] {
+  const paths = Array.isArray(filePaths) ? filePaths : [filePaths];
+  const placeholders = paths.map(() => "?").join(", ");
+  let rows: MemoryRow[];
+  if (repoId) {
+    rows = db
+      .prepare<unknown[], MemoryRow>(
+        `SELECT DISTINCT m.* FROM memories m
+         JOIN memory_files f ON f.memory_id = m.id
+         WHERE m.repo_id = ? AND f.file_path IN (${placeholders})
+         ORDER BY m.created_at DESC
+         LIMIT ?`
+      )
+      .all(repoId, ...paths, limit);
+  } else {
+    rows = db
+      .prepare<unknown[], MemoryRow>(
+        `SELECT DISTINCT m.* FROM memories m
+         JOIN memory_files f ON f.memory_id = m.id
+         WHERE f.file_path IN (${placeholders})
+         ORDER BY m.created_at DESC
+         LIMIT ?`
+      )
+      .all(...paths, limit);
+  }
+  return rows.map((r) => hydrateMemory(db, r));
+}
+
+export function getAllMemories(db: Database.Database): CodingMemory[] {
+  const rows = db
+    .prepare<[], MemoryRow>("SELECT * FROM memories ORDER BY created_at DESC")
+    .all();
+  return rows.map((r) => hydrateMemory(db, r));
+}
+
+export function getMemoriesByRepoId(db: Database.Database, repoId: string): CodingMemory[] {
+  const rows = db
+    .prepare<[string], MemoryRow>(
+      "SELECT * FROM memories WHERE repo_id = ? ORDER BY created_at DESC"
+    )
+    .all(repoId);
+  return rows.map((r) => hydrateMemory(db, r));
+}
+
+export function getMemoriesByRepoPath(db: Database.Database, repoPath: string): CodingMemory[] {
+  const rows = db
+    .prepare<[string], MemoryRow>(
+      "SELECT * FROM memories WHERE repo_path LIKE ? ORDER BY created_at DESC"
+    )
+    .all(`%${repoPath}%`);
+  return rows.map((r) => hydrateMemory(db, r));
+}
+
+export function listMemories(
+  db: Database.Database,
+  options: { repoId?: string; limit: number }
+): CodingMemory[] {
+  let rows: MemoryRow[];
+  if (options.repoId) {
+    rows = db
+      .prepare<[string, number], MemoryRow>(
+        "SELECT * FROM memories WHERE repo_id = ? ORDER BY created_at DESC LIMIT ?"
+      )
+      .all(options.repoId, options.limit);
+  } else {
+    rows = db
+      .prepare<[number], MemoryRow>(
+        "SELECT * FROM memories ORDER BY created_at DESC LIMIT ?"
+      )
+      .all(options.limit);
+  }
+  return rows.map((r) => hydrateMemory(db, r));
+}
+
+export function deleteMemory(db: Database.Database, id: string): void {
+  db.prepare<[string]>("DELETE FROM memories WHERE id = ?").run(id);
+}
+
+export type MemoryStats = {
+  total: number;
+  repos: number;
+  oldest: string;
+  newest: string;
+  topFiles: { filePath: string; count: number }[];
+};
+
+export function getStats(db: Database.Database): MemoryStats {
+  const row = db
+    .prepare<[], { total: number; repos: number; oldest: string; newest: string }>(
+      "SELECT COUNT(*) as total, COUNT(DISTINCT repo_id) as repos, MIN(created_at) as oldest, MAX(created_at) as newest FROM memories"
+    )
+    .get();
+
+  const topFiles = db
+    .prepare<[], { file_path: string; count: number }>(
+      "SELECT file_path, COUNT(*) as count FROM memory_files GROUP BY file_path ORDER BY count DESC LIMIT 10"
+    )
+    .all()
+    .map((r) => ({ filePath: r.file_path, count: r.count }));
+
+  return {
+    total: row?.total ?? 0,
+    repos: row?.repos ?? 0,
+    oldest: row?.oldest ? new Date(row.oldest).toLocaleDateString() : "-",
+    newest: row?.newest ? new Date(row.newest).toLocaleDateString() : "-",
+    topFiles,
+  };
+}
+
+export function updateMemory(
+  db: Database.Database,
+  id: string,
+  updates: {
+    intent?: string;
+    summary?: string;
+    decision?: string;
+    why?: string;
+    task?: string;
+    alternativesRejected?: string[];
+    risks?: string[];
+    followUps?: string[];
+    tags?: string[];
+    embeddingText?: string;
+  }
+): void {
+  const now = new Date().toISOString();
+
+  db.prepare(
+    "UPDATE memories SET intent = ?, summary = ?, decision = ?, why = ?, task = ?, embedding_text = ?, updated_at = ? WHERE id = ?"
+  ).run(
+    updates.intent ?? "",
+    updates.summary ?? "",
+    updates.decision ?? "",
+    updates.why ?? "",
+    updates.task ?? null,
+    updates.embeddingText ?? "",
+    now,
+    id
+  );
+
+  if (updates.tags !== undefined) {
+    db.prepare<[string]>("DELETE FROM memory_tags WHERE memory_id = ?").run(id);
+    const ins = db.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag) VALUES (?, ?)");
+    for (const t of updates.tags) ins.run(id, t);
+  }
+
+  if (updates.alternativesRejected !== undefined) {
+    db.prepare<[string]>("DELETE FROM memory_alternatives WHERE memory_id = ?").run(id);
+    const ins = db.prepare("INSERT OR IGNORE INTO memory_alternatives (memory_id, value) VALUES (?, ?)");
+    for (const a of updates.alternativesRejected) ins.run(id, a);
+  }
+
+  if (updates.risks !== undefined) {
+    db.prepare<[string]>("DELETE FROM memory_risks WHERE memory_id = ?").run(id);
+    const ins = db.prepare("INSERT OR IGNORE INTO memory_risks (memory_id, value) VALUES (?, ?)");
+    for (const r of updates.risks) ins.run(id, r);
+  }
+
+  if (updates.followUps !== undefined) {
+    db.prepare<[string]>("DELETE FROM memory_followups WHERE memory_id = ?").run(id);
+    const ins = db.prepare("INSERT OR IGNORE INTO memory_followups (memory_id, value) VALUES (?, ?)");
+    for (const fu of updates.followUps) ins.run(id, fu);
+  }
+}

package/src/memory/searchMemory.ts

@@ -0,0 +1,153 @@
+import type Database from "better-sqlite3";
+import type { CodingMemory, ScoreBreakdown, SearchResult } from "./types.js";
+import {
+  getMemoriesByRepoId,
+  getMemoriesByRepoPath,
+  getAllMemories,
+} from "./saveMemory.js";
+
+export const STALE_THRESHOLD_DAYS = 90;
+
+export function isStale(memory: CodingMemory, thresholdDays = STALE_THRESHOLD_DAYS): boolean {
+  const ageMs = Date.now() - new Date(memory.createdAt).getTime();
+  return ageMs > thresholdDays * 24 * 60 * 60 * 1000;
+}
+
+export type SearchOptions = {
+  query: string;
+  repoId?: string;
+  repoPath?: string;
+  files?: string[];
+  tags?: string[];
+  since?: string;
+  before?: string;
+  limit?: number;
+};
+
+export function scoreMemory(
+  memory: CodingMemory,
+  query: string,
+  contextRepoId: string | null,
+  contextFiles: string[]
+): ScoreBreakdown {
+  const words = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+
+  if (words.length === 0) {
+    const sameRepo = contextRepoId && memory.repoId === contextRepoId ? 10 : 0;
+    const ageMs = Date.now() - new Date(memory.createdAt).getTime();
+    const recency = ageMs < 30 * 24 * 60 * 60 * 1000 ? 1 : 0;
+    return { total: sameRepo + recency, sameRepo, fileOverlap: 0, tagMatch: 0, decisionMatch: 0, whyMatch: 0, summaryMatch: 0, filePathMatch: 0, recency };
+  }
+
+  const hasKeyword = (text: string): boolean =>
+    words.some((w) => text.toLowerCase().includes(w));
+
+  const sameRepo = contextRepoId && memory.repoId === contextRepoId ? 10 : 0;
+  const fileOverlap = contextFiles.some((f) => memory.files.includes(f)) ? 8 : 0;
+  const tagMatch = memory.tags.some(hasKeyword) ? 5 : 0;
+  const decisionMatch = hasKeyword(memory.decision) ? 4 : 0;
+  const whyMatch = hasKeyword(memory.why) ? 3 : 0;
+  const summaryMatch = hasKeyword(memory.summary) ? 2 : 0;
+  const filePathMatch = memory.files.some(hasKeyword) ? 2 : 0;
+
+  const ageMs = Date.now() - new Date(memory.createdAt).getTime();
+  const recency = ageMs < 30 * 24 * 60 * 60 * 1000 ? 1 : 0;
+
+  const total =
+    sameRepo +
+    fileOverlap +
+    tagMatch +
+    decisionMatch +
+    whyMatch +
+    summaryMatch +
+    filePathMatch +
+    recency;
+
+  return {
+    total,
+    sameRepo,
+    fileOverlap,
+    tagMatch,
+    decisionMatch,
+    whyMatch,
+    summaryMatch,
+    filePathMatch,
+    recency,
+  };
+}
+
+export function explainRelevance(scores: ScoreBreakdown): string {
+  const parts: string[] = [];
+  if (scores.sameRepo) parts.push(`same repo (+${scores.sameRepo})`);
+  if (scores.fileOverlap) parts.push(`file overlap (+${scores.fileOverlap})`);
+  if (scores.tagMatch) parts.push(`tag match (+${scores.tagMatch})`);
+  if (scores.decisionMatch) parts.push(`keyword in decision (+${scores.decisionMatch})`);
+  if (scores.whyMatch) parts.push(`keyword in why (+${scores.whyMatch})`);
+  if (scores.summaryMatch) parts.push(`keyword in summary (+${scores.summaryMatch})`);
+  if (scores.filePathMatch) parts.push(`keyword in file path (+${scores.filePathMatch})`);
+  if (scores.recency) parts.push(`recent memory (+${scores.recency})`);
+  return parts.length ? `Matched: ${parts.join(", ")}` : "No specific match factors";
+}
+
+export function searchMemory(db: Database.Database, options: SearchOptions): SearchResult[] {
+  const { query, repoId, repoPath, files = [], tags = [], since, before, limit = 10 } = options;
+
+  let memories: CodingMemory[] = [];
+
+  if (repoId) {
+    memories = getMemoriesByRepoId(db, repoId);
+    if (memories.length === 0 && repoPath) {
+      memories = getMemoriesByRepoPath(db, repoPath);
+    }
+  } else if (repoPath) {
+    memories = getMemoriesByRepoPath(db, repoPath);
+  } else {
+    memories = getAllMemories(db);
+  }
+
+  // Date filters
+  const sinceMs = since ? new Date(since).getTime() : null;
+  const beforeMs = before ? new Date(before).getTime() : null;
+  if (sinceMs !== null || beforeMs !== null) {
+    memories = memories.filter((m) => {
+      const t = new Date(m.createdAt).getTime();
+      if (sinceMs !== null && t < sinceMs) return false;
+      if (beforeMs !== null && t > beforeMs) return false;
+      return true;
+    });
+  }
+
+  // Tag filter — memory must have ALL requested tags
+  if (tags.length > 0) {
+    const lowerTags = tags.map((t) => t.toLowerCase());
+    memories = memories.filter((m) =>
+      lowerTags.every((tag) => m.tags.map((t) => t.toLowerCase()).includes(tag))
+    );
+  }
+
+  const emptyQuery = query.trim() === "";
+
+  const results: SearchResult[] = memories
+    .map((memory) => {
+      const score = scoreMemory(memory, query, repoId ?? null, files);
+      return { memory, score, relevanceReason: explainRelevance(score) };
+    })
+    .filter((r) => {
+      if (emptyQuery) return true;
+      const contentScore =
+        r.score.fileOverlap +
+        r.score.tagMatch +
+        r.score.decisionMatch +
+        r.score.whyMatch +
+        r.score.summaryMatch +
+        r.score.filePathMatch;
+      return contentScore > 0;
+    })
+    .sort((a, b) => b.score.total - a.score.total)
+    .slice(0, limit);
+
+  return results;
+}

package/src/memory/types.ts

@@ -0,0 +1,57 @@
+export type CodingMemory = {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+
+  repoId: string;
+  repoPath?: string;
+  repoName?: string;
+  branch?: string;
+  commitSha?: string;
+
+  files: string[];
+  tags: string[];
+
+  task?: string;
+  intent: string;
+  summary: string;
+  decision: string;
+  why: string;
+
+  alternativesRejected: string[];
+  risks: string[];
+  followUps: string[];
+
+  source: "manual" | "claude-code" | "cli" | "hook";
+  rawTranscriptPath?: string;
+
+  embeddingText: string;
+};
+
+export type ScoreBreakdown = {
+  total: number;
+  sameRepo: number;
+  fileOverlap: number;
+  tagMatch: number;
+  decisionMatch: number;
+  whyMatch: number;
+  summaryMatch: number;
+  filePathMatch: number;
+  recency: number;
+};
+
+export type SearchResult = {
+  memory: CodingMemory;
+  score: ScoreBreakdown;
+  relevanceReason: string;
+};
+
+export type RepoContext = {
+  repoRoot: string;
+  repoId: string;
+  repoPath: string;
+  repoName: string;
+  branch: string | null;
+  commitSha: string;
+  changedFiles: string[];
+};

package/src/output/format.ts

@@ -0,0 +1,44 @@
+import type { CodingMemory, SearchResult } from "../memory/types.js";
+import { isStale } from "../memory/searchMemory.js";
+
+export function formatMemory(memory: CodingMemory, verbose = false): string {
+  const staleNote = isStale(memory) ? "  [STALE — older than 90 days, verify still applies]" : "";
+  const lines: string[] = [memory.id + staleNote];
+
+  if (memory.commitSha) lines.push(`Commit: ${memory.commitSha.slice(0, 8)}`);
+  if (memory.repoName) lines.push(`Repo: ${memory.repoName}`);
+  if (memory.files.length) lines.push(`Files: ${memory.files.join(", ")}`);
+
+  lines.push("", "Intent:", `  ${memory.intent}`);
+  lines.push("", "Decision:", `  ${memory.decision}`);
+  lines.push("", "Why:", `  ${memory.why}`);
+
+  if (memory.risks.length) {
+    lines.push("", "Risks:");
+    for (const r of memory.risks) lines.push(`  - ${r}`);
+  }
+
+  if (verbose) {
+    if (memory.alternativesRejected.length) {
+      lines.push("", "Alternatives rejected:");
+      for (const a of memory.alternativesRejected) lines.push(`  - ${a}`);
+    }
+    if (memory.followUps.length) {
+      lines.push("", "Follow-ups:");
+      for (const fu of memory.followUps) lines.push(`  - ${fu}`);
+    }
+    if (memory.tags.length) {
+      lines.push("", `Tags: ${memory.tags.join(", ")}`);
+    }
+    if (memory.task) {
+      lines.push("", `Task: ${memory.task}`);
+    }
+    lines.push("", `Summary: ${memory.summary}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function formatSearchResult(result: SearchResult): string {
+  return `${formatMemory(result.memory)}\n\n  [${result.relevanceReason}]`;
+}