engramx 0.1.0 → 0.2.0

package/README.md

@@ -7,6 +7,7 @@
   <a href="#usage"><strong>Usage</strong></a> ·
   <a href="#mcp-server"><strong>MCP Server</strong></a> ·
   <a href="#how-it-works"><strong>How It Works</strong></a> ·
+  <a href="docs/INTEGRATION.md"><strong>Integration Guide</strong></a> ·
   <a href="#contributing"><strong>Contributing</strong></a>
 </p>
 
@@ -14,7 +15,7 @@
   <a href="https://github.com/NickCirv/engram/actions"><img src="https://github.com/NickCirv/engram/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
-  <img src="https://img.shields.io/badge/tests-63%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-132%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/LLM%20cost-$0-green" alt="Zero LLM cost">
   <img src="https://img.shields.io/badge/native%20deps-zero-green" alt="Zero native deps">
 </p>
@@ -46,22 +47,24 @@ npx engram init
 
 Every AI coding session starts from zero. Claude Code re-reads your files. Cursor reindexes. Copilot has no memory. CLAUDE.md is a sticky note you write by hand.
 
-engram fixes this with three things no other tool combines:
+engram fixes this with five things no other tool combines:
 
 1. **Persistent knowledge graph** — survives across sessions, stored in `.engram/graph.db`
 2. **Learns from every session** — decisions, patterns, mistakes are extracted and remembered
 3. **Universal protocol** — MCP server + CLI + auto-generates CLAUDE.md, .cursorrules, AGENTS.md
+4. **Skill-aware** (v0.2) — indexes your `~/.claude/skills/` directory into the graph so queries return code *and* the skill to apply
+5. **Regret buffer** (v0.2) — surfaces past mistakes at the top of query results so your AI stops re-making the same wrong turns
 
 ## Install
 
 ```bash
-npx engram-ai init
+npx engramx init
 ```
 
 Or install globally:
 
 ```bash
-npm install -g engram-ai
+npm install -g engramx
 engram init
 ```
 
@@ -71,6 +74,7 @@ Requires Node.js 20+. Zero native dependencies. No build tools needed.
 
 ```bash
 engram init [path]              # Scan codebase, build knowledge graph
+engram init --with-skills       # Also index ~/.claude/skills/ (v0.2)
 engram query "how does auth"    # Query the graph (BFS, token-budgeted)
 engram query "auth" --dfs       # DFS traversal (trace specific paths)
 engram gods                     # Show most connected entities
@@ -78,7 +82,9 @@ engram stats                    # Node/edge counts, token savings
 engram bench                    # Token reduction benchmark
 engram path "auth" "database"   # Shortest path between concepts
 engram learn "chose JWT..."     # Teach a decision or pattern
+engram mistakes                 # List known mistakes (v0.2)
 engram gen                      # Generate CLAUDE.md section from graph
+engram gen --task bug-fix       # Task-aware view (v0.2: general|bug-fix|feature|refactor)
 engram hooks install            # Auto-rebuild on git commit
 ```
 
@@ -103,7 +109,7 @@ Connect engram to Claude Code, Windsurf, or any MCP client:
   "mcpServers": {
     "engram": {
       "command": "npx",
-      "args": ["-y", "engram-ai", "serve", "/path/to/your/project"]
+      "args": ["-y", "engramx", "serve", "/path/to/your/project"]
     }
   }
 }
@@ -122,12 +128,24 @@ Or if installed globally:
 }
 ```
 
-**MCP Tools:**
+**MCP Tools** (6 total):
 - `query_graph` — Search the knowledge graph with natural language
 - `god_nodes` — Core abstractions (most connected entities)
 - `graph_stats` — Node/edge counts, confidence breakdown
 - `shortest_path` — Trace connections between two concepts
 - `benchmark` — Token reduction measurement
+- `list_mistakes` — Known failure modes from past sessions (v0.2)
+
+### Shell Wrapper (for Bash-based agents)
+
+If your agent stack runs shell commands instead of JSON-RPC MCP, use the reference wrapper at [`scripts/mcp-engram`](scripts/mcp-engram). One command handles all projects via `-p <path>` — no per-project MCP server needed.
+
+```bash
+cp scripts/mcp-engram ~/bin/mcp-engram && chmod +x ~/bin/mcp-engram
+mcp-engram query "how does auth work" -p ~/myrepo
+```
+
+See [`docs/INTEGRATION.md`](docs/INTEGRATION.md) for multi-machine setups, rule-file integration, and gotchas.
 
 ## Auto-Generated AI Instructions
 
@@ -142,6 +160,19 @@ engram gen --target agents    # Write to AGENTS.md
 
 This writes a structured codebase summary — god nodes, file structure, key dependencies, decisions — so your AI assistant navigates by structure instead of grepping.
 
+### Task-Aware Views (v0.2)
+
+`engram gen --task <name>` emits different content based on what you're about to do. The four preset views are defined in `src/autogen.ts` as a data table — no branching logic — so you can add your own task modes without touching the renderer.
+
+```bash
+engram gen --task general     # default — balanced mix of sections
+engram gen --task bug-fix     # emphasizes hot files + past mistakes
+engram gen --task feature     # emphasizes architecture + decisions
+engram gen --task refactor    # emphasizes god nodes + dependency graph
+```
+
+Each view picks a different set of sections with different limits. For example, `bug-fix` omits `## Decisions` and `## Key dependencies` entirely (they'd just be noise when you're chasing a regression) and leads with `🔥 Hot files` and `⚠️ Past mistakes`.
+
 ## How engram Compares
 
 | | engram | Mem0 | Graphify | aider repo-map | CLAUDE.md |
@@ -234,7 +265,26 @@ src/
 
 TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, Ruby, PHP.
 
-Tree-sitter WASM integration (20+ languages with full call-graph precision) is planned for v0.2.
+## Roadmap
+
+### v0.2 (current) — **shipped April 2026**
+- ✅ Skills miner — index `~/.claude/skills/` into the graph
+- ✅ Adaptive gen — task-aware views (`--task general|bug-fix|feature|refactor`)
+- ✅ Regret buffer — surface past mistakes at the top of query results
+- ✅ `list_mistakes` MCP tool
+- ✅ Atomic init lockfile
+- ✅ Marker-safe `writeToFile` + surrogate-safe truncation
+
+### v0.3
+- Tree-sitter WASM (20+ languages with full call-graph precision)
+- Cross-project graph (query patterns across *all* your projects)
+- Temporal graph (commit-snapshot deltas — "what changed in auth this week?")
+- Token enforcement PreToolUse hook for Claude Code
+
+### v0.4+
+- LLM-free semantic search (locality-sensitive hashing over n-grams)
+- Graph-as-IR experimental spike
+- Team memory sync (paid tier)
 
 ## Privacy
 

package/dist/{chunk-44GN6IRQ.js → chunk-D53DRZZL.js}

@@ -1,6 +1,7 @@
 // src/core.ts
-import { join as join3, resolve as resolve2 } from "path";
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4 } from "fs";
+import { join as join4, resolve as resolve2 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync2, unlinkSync } from "fs";
+import { homedir } from "os";
 
 // src/graph/store.ts
 import initSqlJs from "sql.js";
@@ -164,7 +165,7 @@ var GraphStore = class _GraphStore {
       `SELECT n.*, COUNT(*) as degree
        FROM nodes n
        JOIN edges e ON e.source = n.id OR e.target = n.id
-       WHERE n.kind NOT IN ('file', 'import', 'module')
+       WHERE n.kind NOT IN ('file', 'import', 'module', 'concept')
        GROUP BY n.id
        ORDER BY degree DESC
        LIMIT ?`
@@ -293,7 +294,28 @@ var GraphStore = class _GraphStore {
   }
 };
 
+// src/graph/render-utils.ts
+function sliceGraphemeSafe(s, max) {
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  let cut = max;
+  const code = s.charCodeAt(cut - 1);
+  if (code >= 55296 && code <= 56319) cut--;
+  return s.slice(0, cut);
+}
+function truncateGraphemeSafe(s, max) {
+  if (max <= 0) return "";
+  if (s.length <= max) return s;
+  let cut = max - 1;
+  if (cut <= 0) return "";
+  const code = s.charCodeAt(cut - 1);
+  if (code >= 55296 && code <= 56319) cut--;
+  return s.slice(0, cut) + "\u2026";
+}
+
 // src/graph/query.ts
+var MISTAKE_SCORE_BOOST = 2.5;
+var MAX_MISTAKE_LABEL_CHARS = 500;
 var CHARS_PER_TOKEN = 4;
 function scoreNodes(store, terms) {
   const allNodes = store.getAllNodes();
@@ -306,7 +328,10 @@ function scoreNodes(store, terms) {
       if (label.includes(t)) score += 2;
       if (file.includes(t)) score += 1;
     }
-    if (score > 0) scored.push({ score, node });
+    if (score > 0) {
+      if (node.kind === "mistake") score *= MISTAKE_SCORE_BOOST;
+      scored.push({ score, node });
+    }
   }
   return scored.sort((a, b) => b.score - a.score);
 }
@@ -420,12 +445,23 @@ function shortestPath(store, sourceTerm, targetTerm, maxHops = 8) {
 function renderSubgraph(nodes, edges, tokenBudget) {
   const charBudget = tokenBudget * CHARS_PER_TOKEN;
   const lines = [];
+  const mistakes2 = nodes.filter((n) => n.kind === "mistake");
+  const nonMistakes = nodes.filter((n) => n.kind !== "mistake");
+  if (mistakes2.length > 0) {
+    lines.push("\u26A0\uFE0F PAST MISTAKES (relevant to your query):");
+    for (const m of mistakes2) {
+      const label = truncateGraphemeSafe(m.label, MAX_MISTAKE_LABEL_CHARS);
+      const confNote = m.confidence === "EXTRACTED" ? "" : ` [confidence ${m.confidenceScore}]`;
+      lines.push(`  - ${label} (from ${m.sourceFile})${confNote}`);
+    }
+    lines.push("");
+  }
   const degreeMap = /* @__PURE__ */ new Map();
   for (const e of edges) {
     degreeMap.set(e.source, (degreeMap.get(e.source) ?? 0) + 1);
     degreeMap.set(e.target, (degreeMap.get(e.target) ?? 0) + 1);
   }
-  const sorted = [...nodes].sort(
+  const sorted = [...nonMistakes].sort(
     (a, b) => (degreeMap.get(b.id) ?? 0) - (degreeMap.get(a.id) ?? 0)
   );
   for (const n of sorted) {
@@ -445,7 +481,7 @@ function renderSubgraph(nodes, edges, tokenBudget) {
   }
   let output = lines.join("\n");
   if (output.length > charBudget) {
-    output = output.slice(0, charBudget) + `
+    output = sliceGraphemeSafe(output, charBudget) + `
 ... (truncated to ~${tokenBudget} token budget)`;
   }
   return output;
@@ -1031,34 +1067,358 @@ function learnFromSession(text, sourceLabel = "session") {
   return mineText(text, sourceLabel);
 }
 
+// src/miners/skills-miner.ts
+import {
+  existsSync as existsSync4,
+  readFileSync as readFileSync4,
+  readdirSync as readdirSync3,
+  realpathSync as realpathSync2,
+  statSync
+} from "fs";
+import { basename as basename3, dirname as dirname2, join as join3 } from "path";
+function makeId4(...parts) {
+  return parts.filter(Boolean).join("_").replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_|_$/g, "").toLowerCase().slice(0, 120);
+}
+function parseFrontmatter(content) {
+  if (!content.startsWith("---")) {
+    return { data: {}, body: content, parseOk: false };
+  }
+  const closeMatch = content.slice(3).match(/\n---\s*(\n|$)/);
+  if (!closeMatch || closeMatch.index === void 0) {
+    return { data: {}, body: content, parseOk: false };
+  }
+  const yamlBlock = content.slice(3, 3 + closeMatch.index).trim();
+  const bodyStart = 3 + closeMatch.index + closeMatch[0].length;
+  const body = content.slice(bodyStart);
+  try {
+    const data = parseYaml(yamlBlock);
+    return { data, body, parseOk: true };
+  } catch {
+    return { data: {}, body, parseOk: false };
+  }
+}
+function parseYaml(block) {
+  const data = {};
+  const lines = block.split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith("#")) {
+      i++;
+      continue;
+    }
+    const topMatch = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!topMatch) {
+      throw new Error(`YAML parse: unexpected line ${i}: ${line}`);
+    }
+    const [, key, rest] = topMatch;
+    if (rest === ">" || rest === "|") {
+      const style = rest;
+      const collected = [];
+      i++;
+      while (i < lines.length) {
+        const next = lines[i];
+        if (next === "" || /^\s/.test(next)) {
+          collected.push(next.replace(/^ {2}/, "").replace(/^\t/, ""));
+          i++;
+        } else {
+          break;
+        }
+      }
+      data[key] = style === ">" ? collected.filter((l) => l.trim()).join(" ").trim() : collected.join("\n").trim();
+    } else if (rest === "") {
+      const nested = {};
+      i++;
+      while (i < lines.length && /^\s+\S/.test(lines[i])) {
+        const childMatch = lines[i].match(
+          /^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/
+        );
+        if (childMatch) {
+          nested[childMatch[1]] = stripQuotes(childMatch[2]);
+        }
+        i++;
+      }
+      data[key] = nested;
+    } else {
+      data[key] = stripQuotes(rest);
+      i++;
+    }
+  }
+  return data;
+}
+function stripQuotes(s) {
+  const trimmed = s.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if (first === '"' && last === '"') {
+    return trimmed.slice(1, -1).replace(
+      /\\u([0-9a-fA-F]{4})/g,
+      (_, hex) => String.fromCharCode(parseInt(hex, 16))
+    ).replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\\\/g, "\\");
+  }
+  if (first === "'" && last === "'") {
+    return trimmed.slice(1, -1).replace(/''/g, "'");
+  }
+  return trimmed;
+}
+var QUOTED_PHRASE_RE = /[\u0022\u0027\u201C\u201D\u2018\u2019]([^\u0022\u0027\u201C\u201D\u2018\u2019\n]{4,100}?)[\u0022\u0027\u201C\u201D\u2018\u2019]/g;
+var USE_WHEN_RE = /\bUse when\s+(.+?)(?=\.\s+[A-Z]|[\n\r]|$)/g;
+function extractTriggers(text) {
+  const triggers = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(QUOTED_PHRASE_RE)) {
+    const t = m[1]?.trim();
+    if (t && t.length >= 4) triggers.add(t);
+  }
+  for (const m of text.matchAll(USE_WHEN_RE)) {
+    const t = m[1]?.trim().replace(/[.,;]+$/, "");
+    if (t && t.length > 0 && t.length < 120) triggers.add(t);
+  }
+  return [...triggers];
+}
+function extractRelatedSkills(body) {
+  const sectionMatch = body.match(
+    /##\s*Related Skills\s*\r?\n([\s\S]*?)(?=\r?\n##|\r?\n#[^#]|$)/i
+  );
+  if (!sectionMatch) return [];
+  const section = sectionMatch[1];
+  const names = [];
+  for (const line of section.split(/\r?\n/)) {
+    const m = line.match(/^[\s]*[-*+]\s+`?([a-z][a-z0-9-]*)`?/i);
+    if (m) names.push(m[1].toLowerCase());
+  }
+  return [...new Set(names)];
+}
+function discoverSkillFiles(skillsDir) {
+  if (!existsSync4(skillsDir)) return [];
+  let entries;
+  try {
+    entries = readdirSync3(skillsDir, {
+      withFileTypes: true,
+      encoding: "utf-8"
+    });
+  } catch {
+    return [];
+  }
+  const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  const results = [];
+  for (const entry of sorted) {
+    if (entry.name.startsWith(".")) continue;
+    let isDir = entry.isDirectory();
+    if (entry.isSymbolicLink()) {
+      try {
+        const resolved = realpathSync2(join3(skillsDir, entry.name));
+        isDir = statSync(resolved).isDirectory();
+      } catch {
+        continue;
+      }
+    }
+    if (!isDir) continue;
+    const skillMdPath = join3(skillsDir, entry.name, "SKILL.md");
+    if (existsSync4(skillMdPath)) {
+      results.push(skillMdPath);
+    }
+  }
+  return results;
+}
+function mineSkills(skillsDir) {
+  const result = {
+    nodes: [],
+    edges: [],
+    skillCount: 0,
+    anomalies: []
+  };
+  const skillFiles = discoverSkillFiles(skillsDir);
+  if (skillFiles.length === 0) return result;
+  const now = Date.now();
+  const keywordIds = /* @__PURE__ */ new Set();
+  const skillIdByDirName = /* @__PURE__ */ new Map();
+  const pendingRelated = [];
+  for (const skillPath of skillFiles) {
+    let content;
+    try {
+      content = readFileSync4(skillPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const skillDirName = basename3(dirname2(skillPath));
+    const { data, body, parseOk } = parseFrontmatter(content);
+    const hasFrontmatter = parseOk && Object.keys(data).length > 0;
+    let name;
+    let description;
+    let version;
+    if (hasFrontmatter) {
+      name = String(data.name ?? skillDirName);
+      description = String(data.description ?? "");
+      const meta = data.metadata;
+      if (meta && typeof meta === "object" && "version" in meta) {
+        version = String(meta.version);
+      }
+    } else {
+      result.anomalies.push(skillPath);
+      const headingMatch = content.match(/^#\s+(.+)$/m);
+      name = headingMatch?.[1]?.trim() ?? skillDirName;
+      const paragraphs = content.split(/\r?\n\s*\r?\n/).map((p) => p.trim()).filter((p) => p && !p.startsWith("#"));
+      description = paragraphs[0] ?? "";
+    }
+    const skillId = makeId4("skill", skillDirName);
+    skillIdByDirName.set(skillDirName.toLowerCase(), skillId);
+    const sourceFileRel = `${skillDirName}/SKILL.md`;
+    const sizeLines = content.split("\n").length;
+    result.nodes.push({
+      id: skillId,
+      label: name,
+      kind: "concept",
+      sourceFile: sourceFileRel,
+      sourceLocation: skillPath,
+      confidence: "EXTRACTED",
+      confidenceScore: 1,
+      lastVerified: now,
+      queryCount: 0,
+      metadata: {
+        miner: "skills",
+        subkind: "skill",
+        description: truncateGraphemeSafe(description, 500),
+        sizeLines,
+        hasFrontmatter,
+        version,
+        skillDir: skillDirName
+      }
+    });
+    result.skillCount++;
+    const triggers = extractTriggers(description + "\n\n" + body);
+    for (const trigger of triggers) {
+      const normalized = trigger.toLowerCase().trim();
+      if (normalized.length === 0 || normalized.length > 120) continue;
+      const keywordId = makeId4("keyword", normalized);
+      if (!keywordIds.has(keywordId)) {
+        result.nodes.push({
+          id: keywordId,
+          label: trigger,
+          kind: "concept",
+          sourceFile: sourceFileRel,
+          sourceLocation: null,
+          confidence: "EXTRACTED",
+          confidenceScore: 1,
+          lastVerified: now,
+          queryCount: 0,
+          metadata: { miner: "skills", subkind: "keyword" }
+        });
+        keywordIds.add(keywordId);
+      }
+      result.edges.push({
+        source: keywordId,
+        target: skillId,
+        relation: "triggered_by",
+        confidence: "EXTRACTED",
+        confidenceScore: 1,
+        sourceFile: sourceFileRel,
+        sourceLocation: skillPath,
+        lastVerified: now,
+        metadata: { miner: "skills" }
+      });
+    }
+    if (hasFrontmatter || body.length > 0) {
+      const relatedNames = extractRelatedSkills(body);
+      for (const relatedName of relatedNames) {
+        pendingRelated.push({ fromId: skillId, toName: relatedName });
+      }
+    }
+  }
+  for (const { fromId, toName } of pendingRelated) {
+    const toId = skillIdByDirName.get(toName.toLowerCase());
+    if (toId && toId !== fromId) {
+      result.edges.push({
+        source: fromId,
+        target: toId,
+        relation: "similar_to",
+        confidence: "INFERRED",
+        confidenceScore: 0.8,
+        sourceFile: "SKILL.md",
+        sourceLocation: null,
+        lastVerified: Date.now(),
+        metadata: { miner: "skills", via: "related_skills_section" }
+      });
+    }
+  }
+  return result;
+}
+
 // src/core.ts
 var ENGRAM_DIR = ".engram";
 var DB_FILE = "graph.db";
+var LOCK_FILE = "init.lock";
+var DEFAULT_SKILLS_DIR = join4(homedir(), ".claude", "skills");
 function getDbPath(projectRoot) {
-  return join3(projectRoot, ENGRAM_DIR, DB_FILE);
+  return join4(projectRoot, ENGRAM_DIR, DB_FILE);
 }
 async function getStore(projectRoot) {
   return GraphStore.open(getDbPath(projectRoot));
 }
-async function init(projectRoot) {
+async function init(projectRoot, options = {}) {
   const root = resolve2(projectRoot);
   const start = Date.now();
-  mkdirSync2(join3(root, ENGRAM_DIR), { recursive: true });
-  const { nodes, edges, fileCount, totalLines } = extractDirectory(root);
-  const gitResult = mineGitHistory(root);
-  const sessionResult = mineSessionHistory(root);
-  const allNodes = [...nodes, ...gitResult.nodes, ...sessionResult.nodes];
-  const allEdges = [...edges, ...gitResult.edges, ...sessionResult.edges];
-  const store = await getStore(root);
+  mkdirSync2(join4(root, ENGRAM_DIR), { recursive: true });
+  const lockPath = join4(root, ENGRAM_DIR, LOCK_FILE);
   try {
-    store.clearAll();
-    store.bulkUpsert(allNodes, allEdges);
-    store.setStat("last_mined", String(Date.now()));
-    store.setStat("project_root", root);
+    writeFileSync2(lockPath, String(process.pid), { flag: "wx" });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      throw new Error(
+        `engram: another init is running on ${root} (lock: ${lockPath}). If no other process is active, delete the lock file manually.`
+      );
+    }
+    throw err;
+  }
+  try {
+    const { nodes, edges, fileCount, totalLines } = extractDirectory(root);
+    const gitResult = mineGitHistory(root);
+    const sessionResult = mineSessionHistory(root);
+    let skillCount = 0;
+    let skillNodes = [];
+    let skillEdges = [];
+    if (options.withSkills) {
+      const skillsDir = typeof options.withSkills === "string" ? options.withSkills : DEFAULT_SKILLS_DIR;
+      const skillsResult = mineSkills(skillsDir);
+      skillCount = skillsResult.skillCount;
+      skillNodes = skillsResult.nodes;
+      skillEdges = skillsResult.edges;
+    }
+    const allNodes = [
+      ...nodes,
+      ...gitResult.nodes,
+      ...sessionResult.nodes,
+      ...skillNodes
+    ];
+    const allEdges = [
+      ...edges,
+      ...gitResult.edges,
+      ...sessionResult.edges,
+      ...skillEdges
+    ];
+    const store = await getStore(root);
+    try {
+      store.clearAll();
+      store.bulkUpsert(allNodes, allEdges);
+      store.setStat("last_mined", String(Date.now()));
+      store.setStat("project_root", root);
+    } finally {
+      store.close();
+    }
+    return {
+      nodes: allNodes.length,
+      edges: allEdges.length,
+      fileCount,
+      totalLines,
+      timeMs: Date.now() - start,
+      skillCount
+    };
   } finally {
-    store.close();
+    try {
+      unlinkSync(lockPath);
+    } catch {
+    }
   }
-  return { nodes: allNodes.length, edges: allEdges.length, fileCount, totalLines, timeMs: Date.now() - start };
 }
 async function query(projectRoot, question, options = {}) {
   const store = await getStore(projectRoot);
@@ -1110,6 +1470,28 @@ async function learn(projectRoot, text, sourceLabel = "manual") {
   }
   return { nodesAdded: nodes.length };
 }
+async function mistakes(projectRoot, options = {}) {
+  const store = await getStore(projectRoot);
+  try {
+    let items = store.getAllNodes().filter((n) => n.kind === "mistake");
+    if (options.sinceDays !== void 0) {
+      const cutoff = Date.now() - options.sinceDays * 24 * 60 * 60 * 1e3;
+      items = items.filter((m) => m.lastVerified >= cutoff);
+    }
+    items.sort((a, b) => b.lastVerified - a.lastVerified);
+    const limit = options.limit ?? 20;
+    return items.slice(0, limit).map((m) => ({
+      id: m.id,
+      label: m.label,
+      confidence: m.confidence,
+      confidenceScore: m.confidenceScore,
+      sourceFile: m.sourceFile,
+      lastVerified: m.lastVerified
+    }));
+  } finally {
+    store.close();
+  }
+}
 async function benchmark(projectRoot, questions) {
   const root = resolve2(projectRoot);
   const store = await getStore(root);
@@ -1121,8 +1503,8 @@ async function benchmark(projectRoot, questions) {
       if (node.sourceFile && !seenFiles.has(node.sourceFile)) {
         seenFiles.add(node.sourceFile);
         try {
-          const fullPath = join3(root, node.sourceFile);
-          if (existsSync4(fullPath)) fullCorpusChars += readFileSync4(fullPath, "utf-8").length;
+          const fullPath = join4(root, node.sourceFile);
+          if (existsSync5(fullPath)) fullCorpusChars += readFileSync5(fullPath, "utf-8").length;
         } catch {
         }
       }
@@ -1143,8 +1525,8 @@ async function benchmark(projectRoot, questions) {
         let relevantChars = 0;
         for (const f of matchedFiles) {
           try {
-            const fullPath = join3(root, f);
-            if (existsSync4(fullPath)) relevantChars += readFileSync4(fullPath, "utf-8").length;
+            const fullPath = join4(root, f);
+            if (existsSync5(fullPath)) relevantChars += readFileSync5(fullPath, "utf-8").length;
           } catch {
           }
         }
@@ -1174,11 +1556,15 @@ async function benchmark(projectRoot, questions) {
 
 export {
   GraphStore,
+  sliceGraphemeSafe,
+  truncateGraphemeSafe,
+  MAX_MISTAKE_LABEL_CHARS,
   queryGraph,
   shortestPath,
   SUPPORTED_EXTENSIONS,
   extractFile,
   extractDirectory,
+  mineSkills,
   getDbPath,
   getStore,
   init,
@@ -1187,5 +1573,6 @@ export {
   godNodes,
   stats,
   learn,
+  mistakes,
   benchmark
 };