decision-memory 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,174 @@
+# decision-memory
+
+[![npm](https://img.shields.io/npm/v/decision-memory)](https://www.npmjs.com/package/decision-memory)
+
+**Automatic decision logging for Claude Code.** Every architectural choice your AI assistant makes gets stored in a compact, token-efficient [TOON](https://github.com/toon-format/toon) file — and retrieved automatically when context is lost.
+
+```
+decisions[3]{id,ts,topic,decision,rationale,impact,tags}:
+D001,2026-02-10T14:32Z,auth,"Use JWT RS256","HS256 needs shared secret across services",high,auth|security|jwt
+D002,2026-02-11T09:15Z,database,"Use Postgres","Need concurrent writes; SQLite WAL insufficient",high,database|postgres
+D003,2026-02-12T16:44Z,testing,"Use Vitest","ESM-native project; Jest ESM support is experimental",low,testing|vitest
+```
+
+## Why decision-memory?
+
+- **Context loss is real.** Long sessions and session restarts mean Claude forgets why `JWT RS256` was chosen over `HS256` three days ago.
+- **Re-discussing decided things wastes time.** Every re-debate costs tokens and slows development.
+- **Decisions deserve a home.** Like `CHANGELOG.md` for architecture.
+
+## How it works
+
+1. **Auto-trigger**: A Claude Code hook fires after every `Write`/`Edit` operation, nudging Claude to log decisions automatically.
+2. **Session start**: Claude calls `get_context_summary` to orient itself (~200 tokens).
+3. **Before deciding**: Claude calls `search_decisions` to check prior decisions (~50-80 tokens/result).
+4. **After deciding**: Claude calls `log_decision` to record the choice.
+
+No manual intervention needed.
+
+## Quickstart (Claude Code)
+
+### 1. Copy integration files to your project
+
+```bash
+npx degit baadir/decisionmemo/integrations/claude-code . --force
+```
+
+This pulls `.mcp.json`, `CLAUDE.md` and `.claude/` directly into your project root — no cloning, no manual copying.
+
+### 2. Initialize DECISIONS.toon
+
+```bash
+npx decision-memory init
+```
+
+### 3. Start Claude Code
+
+Claude will automatically:
+- Call `get_context_summary` at session start
+- Be nudged to call `log_decision` after file modifications
+- Call `search_decisions` before making architectural choices
+
+## MCP Server
+
+The MCP server is the primary integration method. It exposes 4 tools:
+
+| Tool | Description |
+|---|---|
+| `log_decision` | Log an architectural decision |
+| `search_decisions` | Search past decisions by keyword/tag |
+| `get_context_summary` | Get compact session-start summary |
+| `update_decision` | Mark a prior decision as superseded |
+
+## CLI
+
+```bash
+# Initialize
+npx decision-memory init
+
+# Log a decision
+npx decision-memory log \
+  --topic auth \
+  --decision "Use JWT RS256" \
+  --rationale "HS256 requires shared secret across services" \
+  --impact high \
+  --tags auth,security,jwt
+
+# Search
+npx decision-memory search --keywords jwt
+npx decision-memory search --tags auth,security
+npx decision-memory search --impact high
+
+# Summary
+npx decision-memory summary
+```
+
+## Why TOON format?
+
+TOON (Token-Oriented Object Notation) uses **39% fewer tokens than JSON** for the same structured data. For a project with 50 decisions:
+
+- JSON: ~4,250 tokens
+- TOON: ~2,600 tokens
+- Savings: **1,650 tokens per search** that's not consumed
+
+## DECISIONS.toon schema
+
+```
+# decision-memory v1
+project: <name>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+
+decisions[N]{id,ts,topic,decision,rationale,impact,tags}:
+D001,YYYY-MM-DDTHH:MMZ,topic,"Decision text","Rationale text",impact,tag1|tag2
+
+summary{total,high_impact,last_updated,top_topics}:
+N,N,YYYY-MM-DD,topic1|topic2
+```
+
+**Fields:**
+- `impact`: `low` | `medium` | `high` | `critical`
+- `tags`: pipe-delimited (`auth|jwt|security`)
+- Fields with commas are quoted: `"Use JWT, not sessions"`
+
+## File location
+
+Priority order:
+1. `DECISION_MEMORY_FILE` environment variable
+2. `./DECISIONS.toon` in current working directory ← **recommended**
+3. `~/.decision-memory/global.toon` (fallback)
+
+Commit `DECISIONS.toon` to git — it's a project artifact like `README.md`.
+
+## Package
+
+Single npm package — CLI and MCP server in one:
+
+```bash
+npm install -g decision-memory   # CLI
+npx decision-memory init         # run without installing
+```
+
+The MCP server binary (`decision-memory-mcp`) is included in the same package and started automatically via `.mcp.json`.
+
+## How does this compare to Claude Code's MEMORY.md?
+
+Claude Code has three places where context lives. They don't overlap — they complement each other:
+
+| | `MEMORY.md` | `CLAUDE.md` | `DECISIONS.toon` |
+|---|---|---|---|
+| **Written by** | Claude (auto-generated) | You (human) | Claude (via MCP tool) |
+| **Contains** | Discoveries, patterns, debugging notes | Behavioral rules & instructions | Architectural decisions with rationale |
+| **Searchable** | No | No | Yes — keyword + tag search |
+| **Location** | `~/.claude/projects/.../memory/` | Project root | Project root |
+| **Format** | Markdown | Markdown | TOON (39% fewer tokens) |
+
+**In plain terms:**
+- MEMORY.md is Claude's personal notebook ("I noticed this codebase uses X pattern")
+- CLAUDE.md is your instruction manual for Claude ("always call get_context_summary at start")
+- DECISIONS.toon is the project's architecture log ("we chose Postgres over SQLite because...")
+
+All three can be active at once. decision-memory adds the one thing neither MEMORY.md nor CLAUDE.md provides: **searchable, structured, rationale-rich decision history**.
+
+## Compatibility
+
+decision-memory is compatible with any other MCP server or Claude Code tool. It only reads and writes `DECISIONS.toon` — it does not interfere with other tools.
+
+**Execution order when Claude Code starts:**
+1. `.mcp.json` is read → all MCP servers start (including decision-memory)
+2. `CLAUDE.md` is added to the system prompt
+3. Session begins — Claude calls `get_context_summary` per instructions
+
+Other MCP tools (context-mode, etc.) run in parallel with decision-memory. There is no conflict because each MCP server handles its own tools independently.
+
+## Roadmap
+
+- [x] Claude Code (MCP + hooks)
+- [ ] Cursor (`.cursor/mcp.json`)
+- [ ] VS Code + Cline (`.vscode/mcp.json`)
+- [ ] Opencode (`opencode.json`)
+- [ ] Semantic search (embeddings, opt-in)
+
+## License
+
+MIT

package/dist/chunk-5VFZ3YOK.js

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// packages/core/src/parser.ts
+function splitCsvRow(line) {
+  const fields = [];
+  let current = "";
+  let inQuote = false;
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (inQuote) {
+      if (ch === "\\") {
+        const next = line[i + 1];
+        if (next === '"') {
+          current += '"';
+          i += 2;
+          continue;
+        } else if (next === "n") {
+          current += "\n";
+          i += 2;
+          continue;
+        } else if (next === "\\") {
+          current += "\\";
+          i += 2;
+          continue;
+        }
+        current += ch;
+      } else if (ch === '"') {
+        inQuote = false;
+      } else {
+        current += ch;
+      }
+    } else {
+      if (ch === '"') {
+        inQuote = true;
+      } else if (ch === ",") {
+        fields.push(current);
+        current = "";
+      } else {
+        current += ch;
+      }
+    }
+    i++;
+  }
+  fields.push(current);
+  return fields;
+}
+function parseTableHeader(line) {
+  const match = line.match(/^decisions\[(\d+)\]\{([^}]+)\}:$/);
+  if (!match) return null;
+  return {
+    count: parseInt(match[1], 10),
+    fields: match[2].split(",")
+  };
+}
+function isSummaryLine(line) {
+  return line.startsWith("summary{");
+}
+function parseDecisionRow(fields, values) {
+  const get = (name) => {
+    const idx = fields.indexOf(name);
+    return idx >= 0 ? values[idx] ?? "" : "";
+  };
+  const impactRaw = get("impact");
+  const validImpacts = ["low", "medium", "high", "critical"];
+  const impact = validImpacts.includes(impactRaw) ? impactRaw : "medium";
+  const tagsRaw = get("tags");
+  const tags = tagsRaw ? tagsRaw.split("|").filter(Boolean) : [];
+  return {
+    id: get("id"),
+    ts: get("ts"),
+    topic: get("topic"),
+    decision: get("decision"),
+    rationale: get("rationale"),
+    impact,
+    tags
+  };
+}
+function parseDecisionFile(content) {
+  const lines = content.split("\n");
+  const meta = {
+    project: "unknown",
+    version: "1",
+    created: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+  const decisions = [];
+  let tableFields = [];
+  let inTable = false;
+  let inSummary = false;
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+    if (!line || line.startsWith("#")) continue;
+    if (isSummaryLine(line)) {
+      inTable = false;
+      inSummary = true;
+      continue;
+    }
+    if (inSummary) continue;
+    const tableHeader = parseTableHeader(line);
+    if (tableHeader) {
+      tableFields = tableHeader.fields;
+      inTable = true;
+      continue;
+    }
+    if (inTable && tableFields.length > 0) {
+      const values = splitCsvRow(line);
+      if (values.length >= tableFields.length) {
+        decisions.push(parseDecisionRow(tableFields, values));
+      }
+      continue;
+    }
+    const colonIdx = line.indexOf(":");
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      if (key === "project") meta.project = value;
+      else if (key === "version") meta.version = value;
+      else if (key === "created") meta.created = value;
+      else if (key === "updated") meta.updated = value;
+    }
+  }
+  return { meta, decisions };
+}
+function serializeDecisionRow(d) {
+  const escapeField = (s) => {
+    if (s.includes(",") || s.includes('"') || s.includes("\n")) {
+      return '"' + s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n") + '"';
+    }
+    return s;
+  };
+  const tags = d.tags.join("|");
+  return [
+    d.id,
+    d.ts,
+    d.topic,
+    escapeField(d.decision),
+    escapeField(d.rationale),
+    d.impact,
+    tags
+  ].join(",");
+}
+
+// packages/core/src/searcher.ts
+var IMPACT_WEIGHT = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1
+};
+function computeMatchedFields(d, keywords, tags) {
+  const matched = [];
+  const kws = keywords.map((k) => k.toLowerCase());
+  if (tags.length > 0 && tags.some((t) => d.tags.map((dt) => dt.toLowerCase()).includes(t))) {
+    matched.push("tags");
+  }
+  if (kws.some((k) => d.topic.toLowerCase().includes(k))) matched.push("topic");
+  if (kws.some((k) => d.decision.toLowerCase().includes(k))) matched.push("decision");
+  if (kws.some((k) => d.rationale.toLowerCase().includes(k))) matched.push("rationale");
+  return matched;
+}
+function searchDecisions(file, query) {
+  const keywords = (query.keywords ?? []).map((k) => k.toLowerCase());
+  const tags = (query.tags ?? []).map((t) => t.toLowerCase());
+  const impactFilter = query.impact;
+  const limit = query.limit ?? 5;
+  if (keywords.length === 0 && tags.length === 0 && !impactFilter) {
+    return file.decisions.slice(-limit).reverse().map((d) => ({ decision: d, matchedFields: [] }));
+  }
+  const results = [];
+  for (const d of file.decisions) {
+    if (impactFilter && d.impact !== impactFilter) continue;
+    const decisionLower = d.decision.toLowerCase();
+    const rationaleLower = d.rationale.toLowerCase();
+    const topicLower = d.topic.toLowerCase();
+    const tagsLower = d.tags.map((t) => t.toLowerCase());
+    const matchesTag = tags.length === 0 || tags.some((t) => tagsLower.includes(t));
+    const matchesKeyword = keywords.length === 0 || keywords.some(
+      (k) => topicLower.includes(k) || decisionLower.includes(k) || rationaleLower.includes(k) || tagsLower.some((t) => t.includes(k))
+    );
+    if (matchesTag && matchesKeyword) {
+      results.push({
+        decision: d,
+        matchedFields: computeMatchedFields(d, keywords, tags)
+      });
+    }
+  }
+  results.sort((a, b) => {
+    const weightDiff = IMPACT_WEIGHT[b.decision.impact] - IMPACT_WEIGHT[a.decision.impact];
+    if (weightDiff !== 0) return weightDiff;
+    return b.decision.ts.localeCompare(a.decision.ts);
+  });
+  return results.slice(0, limit);
+}
+
+// packages/core/src/summary.ts
+var HIGH_IMPACT = ["high", "critical"];
+function topTopics(decisions, n = 5) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const d of decisions) {
+    counts.set(d.topic, (counts.get(d.topic) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, n).map(([topic]) => topic);
+}
+function buildContextSummary(file, options = {}) {
+  const { includeRecent = true } = options;
+  const { decisions } = file;
+  const highImpactCount = decisions.filter(
+    (d) => HIGH_IMPACT.includes(d.impact)
+  ).length;
+  const lastUpdated = decisions.length > 0 ? decisions[decisions.length - 1].ts.slice(0, 10) : file.meta.updated;
+  const recentDecisions = includeRecent ? decisions.filter((d) => HIGH_IMPACT.includes(d.impact)).slice(-5).reverse() : [];
+  return {
+    total: decisions.length,
+    highImpactCount,
+    lastUpdated,
+    topTopics: topTopics(decisions),
+    recentDecisions
+  };
+}
+function buildSummaryBlock(file) {
+  const summary = buildContextSummary(file, { includeRecent: false });
+  const topics = summary.topTopics.join("|");
+  return `summary{total,high_impact,last_updated,top_topics}:
+${summary.total},${summary.highImpactCount},${summary.lastUpdated},${topics}`;
+}
+function formatContextSummaryAsToon(file, includeRecent = true) {
+  const summary = buildContextSummary(file, { includeRecent });
+  const topics = summary.topTopics.join("|");
+  let output = `summary{total,high_impact,last_updated,top_topics}:
+`;
+  output += `${summary.total},${summary.highImpactCount},${summary.lastUpdated},${topics}`;
+  if (includeRecent && summary.recentDecisions.length > 0) {
+    output += `
+
+recent_high_impact[${summary.recentDecisions.length}]{id,ts,topic,decision,impact}:
+`;
+    for (const d of summary.recentDecisions) {
+      const decisionField = d.decision.includes(",") ? `"${d.decision}"` : d.decision;
+      output += `${d.id},${d.ts},${d.topic},${decisionField},${d.impact}
+`;
+    }
+  }
+  return output.trimEnd();
+}
+
+// packages/core/src/writer.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+// packages/core/src/idgen.ts
+var ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function encodeBase36(n) {
+  if (n === 0) return "0";
+  let result = "";
+  while (n > 0) {
+    result = ALPHABET[n % 36] + result;
+    n = Math.floor(n / 36);
+  }
+  return result;
+}
+function generateNextId(currentCount) {
+  const next = currentCount + 1;
+  if (next <= 999) {
+    return `D${String(next).padStart(3, "0")}`;
+  }
+  const encoded = encodeBase36(next).padStart(4, "0");
+  return `D${encoded}`;
+}
+
+// packages/core/src/writer.ts
+function initDecisionFile(filePath, projectName) {
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Dosya zaten var: ${filePath}`);
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const content = `# decision-memory v1
+project: ${projectName}
+version: 1
+created: ${today}
+updated: ${today}
+
+decisions[0]{id,ts,topic,decision,rationale,impact,tags}:
+
+summary{total,high_impact,last_updated,top_topics}:
+0,0,${today},
+`;
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+function updateDecisionCount(filePath, newCount) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const updated = content.replace(
+    /^decisions\[(\d+)\]\{/m,
+    `decisions[${newCount}]{`
+  );
+  const tmpPath = filePath + ".tmp";
+  fs.writeFileSync(tmpPath, updated, "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+function updateSummaryBlock(filePath) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const file = parseDecisionFile(content);
+  const summaryBlock = buildSummaryBlock(file);
+  const summaryStart = content.indexOf("\nsummary{");
+  let base;
+  if (summaryStart >= 0) {
+    base = content.slice(0, summaryStart);
+  } else {
+    base = content.trimEnd();
+  }
+  const newContent = base + "\n" + summaryBlock + "\n";
+  const tmpPath = filePath + ".tmp";
+  fs.writeFileSync(tmpPath, newContent, "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+function appendDecision(filePath, input) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`DECISIONS.toon dosyas\u0131 bulunamad\u0131: ${filePath}
+\xD6nce 'decision-memory init' komutunu \xE7al\u0131\u015Ft\u0131r\u0131n.`);
+  }
+  const content = fs.readFileSync(filePath, "utf-8");
+  const countMatch = content.match(/^decisions\[(\d+)\]/m);
+  const currentCount = countMatch ? parseInt(countMatch[1], 10) : 0;
+  const id = generateNextId(currentCount);
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z").replace(/:\d{2}Z$/, "Z");
+  const decision = {
+    id,
+    ts,
+    topic: input.topic,
+    decision: input.decision,
+    rationale: input.rationale,
+    impact: input.impact,
+    tags: input.tags
+  };
+  const row = serializeDecisionRow(decision);
+  const lines = content.split("\n");
+  let tableEnd = -1;
+  let inTable = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^decisions\[\d+\]\{/.test(lines[i])) {
+      inTable = true;
+      tableEnd = i;
+      continue;
+    }
+    if (inTable) {
+      if (lines[i].startsWith("summary{") || lines[i] === "" && tableEnd >= 0) {
+        if (lines[i].startsWith("summary{")) {
+          tableEnd = i - 1;
+        } else {
+          tableEnd = i - 1;
+        }
+        break;
+      }
+      if (lines[i] !== "") {
+        tableEnd = i;
+      }
+    }
+  }
+  lines.splice(tableEnd + 1, 0, row);
+  const newContent = lines.join("\n");
+  const tmpPath = filePath + ".tmp";
+  fs.writeFileSync(tmpPath, newContent, "utf-8");
+  fs.renameSync(tmpPath, filePath);
+  updateDecisionCount(filePath, currentCount + 1);
+  updateSummaryBlock(filePath);
+  return decision;
+}
+function resolveDecisionFilePath(cwd) {
+  if (process.env.DECISION_MEMORY_FILE) {
+    return process.env.DECISION_MEMORY_FILE;
+  }
+  const dir = cwd ?? process.cwd();
+  const local = path.join(dir, "DECISIONS.toon");
+  if (fs.existsSync(local)) return local;
+  const globalDir = path.join(os.homedir(), ".decision-memory");
+  fs.mkdirSync(globalDir, { recursive: true });
+  return path.join(globalDir, "global.toon");
+}
+
+export {
+  __require,
+  __commonJS,
+  __export,
+  __toESM,
+  parseDecisionFile,
+  serializeDecisionRow,
+  searchDecisions,
+  formatContextSummaryAsToon,
+  initDecisionFile,
+  appendDecision,
+  resolveDecisionFilePath
+};