sverklo 0.16.0 → 0.17.2

package/README.md

@@ -2,13 +2,18 @@
   <img src="./docs/logo.svg" alt="sverklo" width="280" height="79"/>
 </p>
 
-> **Stop your AI from making things up about your codebase.**
+> **The only code-intel MCP with a published benchmark and reproducible eval harness.**
 > Local-first MCP server that gives Claude Code, Cursor, Windsurf, and Zed a real symbol graph, a blast-radius lens, and a git-pinned memory — so the agent stops guessing. MIT. Zero config. Your code never leaves the machine.
+>
+> [Paper (Zenodo, CC BY 4.0)](https://doi.org/10.5281/zenodo.19802051) · [bench:primitives](./benchmark/) — sverklo cuts agent context by **65 % vs grep** (255 vs 731 tokens per task, n=60) · [bench:swe](https://sverklo.com/blog/bench-swe-first-results/) — 38/65 perfect recall on 5 OSS repos, including the runs we lose.
 
 [![npm version](https://img.shields.io/npm/v/sverklo.svg?color=E85A2A)](https://www.npmjs.com/package/sverklo)
 [![npm downloads](https://img.shields.io/npm/dw/sverklo.svg?color=E85A2A)](https://www.npmjs.com/package/sverklo)
 [![License: MIT](https://img.shields.io/badge/license-MIT-E85A2A.svg)](LICENSE)
 [![Audited repos](https://img.shields.io/badge/audited_repos-47-E85A2A)](https://sverklo.com/report)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19802051.svg)](https://doi.org/10.5281/zenodo.19802051)
+
+![Sverklo cuts agent context by 65 % vs grep — bench:primitives, 60 retrieval tasks, peer-reviewable](./docs/hero-token-comparison.png)
 
 ![Sverklo demo — audit and badge](./docs/demo.gif)
 
@@ -39,6 +44,18 @@ That's it. `sverklo init` auto-detects your installed AI coding agent (Claude Co
 
 ---
 
+## What's new in 0.17
+
+- **`npm run bench:swe`** — third-party-reproducible cross-repo eval. Clones 5 OSS repos (express, nestjs, vite, prisma, fastapi), runs 65 grounded questions, prints aggregated recall. PRs that add questions are welcome.
+- **Tree-sitter parser opt-in.** `sverklo grammars install` (~3.5 MB across 6 languages) + `SVERKLO_PARSER=tree-sitter` and the indexer routes through real ASTs for TypeScript/TSX/JavaScript/Python/Go/Rust. Silent regex fallback when grammars aren't installed. v0.18 plan to flip the default lives in [docs/parser-parity.md](./docs/parser-parity.md).
+- **Workspace shared memory.** `sverklo workspace memory <name> add/list/search` plus `sverklo_remember scope:"workspace"` from the agent — write a decision once, query it from every other repo in the workspace. `sverklo_recall` blends workspace results under project ones with a `[ws]` badge.
+- **`sverklo memory export`** — markdown / Notion / JSON. Migrate your team's decision log to wherever it actually lives.
+- **PR-bot inline review.** `sverklo review --format github-review-json` + the action's new `inline-comments: true` default posts per-line review comments via `pulls.createReview`, alongside the existing sticky summary.
+- **VS Code extension scaffold** at [`extensions/vscode/`](./extensions/vscode/) with a pre-built `sverklo-vscode-0.1.0.vsix`. Inline caller-count decorations on every function header (`⟵ 47 callers`). Marketplace publish workflow ships dormant; install with `code --install-extension extensions/vscode/sverklo-vscode-0.1.0.vsix` today.
+- **`sverklo digest [--since 7d]`** — 5-line summary of audit-grade trend, new vs stale memories, and high-PageRank files touched. Wire into a shell-hook on `cd` for a daily sverklo check-in.
+
+---
+
 ## Grep vs Sverklo — the same question, side by side
 
 Every one of these is a query a real engineer asked a real AI assistant last week. Grep gives you lines. Sverklo gives you a ranked answer.
@@ -349,6 +366,26 @@ The open-core line: **Pro adds new things, never gates current things.** Anythin
 - [Issues](https://github.com/sverklo/sverklo/issues)
 - [First Run Guide](FIRST_RUN.md)
 - [Benchmarks](BENCHMARKS.md)
+- [Paper (Zenodo, CC BY 4.0)](https://doi.org/10.5281/zenodo.19802051)
+
+## Citing Sverklo
+
+If you use Sverklo or its benchmarks (`bench:primitives`, `bench:swe`) in research, please cite:
+
+> Groshin, N. (2026). *Sverklo: A Local-First Code Intelligence MCP Server and a Cross-Repository Software Engineering Benchmark*. Zenodo. https://doi.org/10.5281/zenodo.19802051
+
+BibTeX:
+
+```bibtex
+@misc{groshin2026sverklo,
+  author    = {Groshin, Nikita},
+  title     = {{Sverklo}: A Local-First Code Intelligence {MCP} Server and a Cross-Repository Software Engineering Benchmark},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.19802051},
+  url       = {https://doi.org/10.5281/zenodo.19802051}
+}
+```
 
 ## License
 

package/dist/bin/sverklo.js

@@ -51,6 +51,8 @@ if (command && command !== "--help" && command !== "-h") {
             dashboard: "Alias for `sverklo ui`.",
             wakeup: "Print compressed project context (for system-prompt injection in non-MCP clients).",
             digest: "5-line summary of what changed in this project. Flags: --since 7d, --format markdown|plain.",
+            memory: "Manage the memory store. Subcommands: show, edit, export.",
+            grammars: "Manage tree-sitter grammars for the SVERKLO_PARSER=tree-sitter opt-in path. Subcommands: install.",
             "audit-prompt": "Print a ready-to-paste codebase-audit prompt (hybrid agent workflow).",
             "review-prompt": "Print a ready-to-paste PR/MR-review prompt (hybrid agent workflow).",
             bench: "Run reproducible benchmarks on gin/nestjs/react.",
@@ -64,7 +66,7 @@ if (command && command !== "--help" && command !== "-h") {
             prune: "", // prune already prints its own --help inside the block
         };
         // Pass-throughs: subcommands that handle --help themselves.
-        const SELF_HANDLES_HELP = new Set(["prune"]);
+        const SELF_HANDLES_HELP = new Set(["prune", "memory"]);
         if (!SELF_HANDLES_HELP.has(command)) {
             const blurb = HELP_BLURBS[command];
             if (blurb) {
@@ -327,6 +329,88 @@ if (command === "workspace") {
             console.log(`  · ${r.alias || ""} ${r.path}`);
         process.exit(0);
     }
+    if (sub === "memory") {
+        // sverklo workspace memory <name> <list|add|search|forget> [...]
+        //
+        // Per-workspace shared memory store at
+        // ~/.sverklo/workspaces/<name>/memories.db. CLI ships in v0.17;
+        // sverklo_remember scope:workspace is the v0.18 follow-up.
+        const name = args[2];
+        const op = args[3];
+        if (!name || !op) {
+            console.error("Usage: sverklo workspace memory <name> <list|add|search|forget> [args]");
+            process.exit(1);
+        }
+        const { openWorkspaceMemory, addWorkspaceMemory, searchWorkspaceMemory, workspaceMemoryExists, } = await import("../src/workspace/memory.js");
+        if (op === "add") {
+            const content = args.slice(4).join(" ");
+            if (!content) {
+                console.error('Usage: sverklo workspace memory <name> add "memory text"');
+                process.exit(1);
+            }
+            const ws = openWorkspaceMemory(name);
+            const id = addWorkspaceMemory(ws, { content });
+            console.log(`Saved workspace memory #${id} → ${ws.dbPath}`);
+            ws.close();
+            process.exit(0);
+        }
+        if (op === "list") {
+            if (!workspaceMemoryExists(name)) {
+                console.log(`No memories yet for workspace "${name}". Add one with:`);
+                console.log(`  sverklo workspace memory ${name} add "your decision here"`);
+                process.exit(0);
+            }
+            const ws = openWorkspaceMemory(name);
+            const rows = ws.memoryStore.getAll(50);
+            console.log(`\nWorkspace "${name}" memories (${rows.length}):\n`);
+            for (const m of rows) {
+                const age = new Date(m.created_at).toISOString().slice(0, 10);
+                console.log(`  #${m.id} [${m.category}/${m.kind}] ${age}`);
+                console.log(`    ${m.content.replace(/\n/g, " ").slice(0, 100)}${m.content.length > 100 ? "…" : ""}`);
+            }
+            ws.close();
+            process.exit(0);
+        }
+        if (op === "search") {
+            const query = args.slice(4).join(" ");
+            if (!query) {
+                console.error('Usage: sverklo workspace memory <name> search "query"');
+                process.exit(1);
+            }
+            if (!workspaceMemoryExists(name)) {
+                console.log(`No memories for workspace "${name}".`);
+                process.exit(0);
+            }
+            const ws = openWorkspaceMemory(name);
+            const rows = searchWorkspaceMemory(ws, query, 20);
+            console.log(`\n${rows.length} match${rows.length === 1 ? "" : "es"}:\n`);
+            for (const m of rows) {
+                console.log(`  #${m.id} [${m.category}/${m.kind}]`);
+                console.log(`    ${m.content.replace(/\n/g, " ").slice(0, 200)}${m.content.length > 200 ? "…" : ""}`);
+            }
+            ws.close();
+            process.exit(0);
+        }
+        if (op === "forget") {
+            const idStr = args[4];
+            if (!idStr) {
+                console.error("Usage: sverklo workspace memory <name> forget <id>");
+                process.exit(1);
+            }
+            const id = parseInt(idStr, 10);
+            if (!Number.isFinite(id)) {
+                console.error(`✗ "${idStr}" is not a valid id`);
+                process.exit(2);
+            }
+            const ws = openWorkspaceMemory(name);
+            const ok = ws.memoryStore.delete(id);
+            ws.close();
+            console.log(ok ? `Forgot memory #${id}.` : `Memory #${id} not found.`);
+            process.exit(ok ? 0 : 1);
+        }
+        console.error(`Unknown workspace memory op: ${op}`);
+        process.exit(1);
+    }
     console.log(`
 sverklo workspace — manage multi-repo workspaces
 
@@ -621,7 +705,20 @@ if (command === "review") {
         (process.env.GITHUB_BASE_REF
             ? `origin/${process.env.GITHUB_BASE_REF}..HEAD`
             : "main..HEAD");
-    const projectPath = await resolveProjectPath(flags);
+    // Strip value-taking flags so `--format github-review-json` doesn't
+    // leave "github-review-json" looking like a positional path.
+    const valueFlags = new Set(["--ref", "--format", "--max-files", "--fail-on"]);
+    const cleanFlags = [];
+    for (let i = 0; i < flags.length; i++) {
+        if (valueFlags.has(flags[i])) {
+            i++;
+            continue;
+        }
+        if (Array.from(valueFlags).some((f) => flags[i].startsWith(`${f}=`)))
+            continue;
+        cleanFlags.push(flags[i]);
+    }
+    const projectPath = await resolveProjectPath(cleanFlags);
     // Ensure model is available
     const { existsSync: modelExists } = await import("node:fs");
     const { join: joinPath } = await import("node:path");
@@ -636,17 +733,34 @@ if (command === "review") {
     const { getProjectConfig } = await import("../src/utils/config.js");
     const { Indexer } = await import("../src/indexer/indexer.js");
     const { handleReviewDiff } = await import("../src/server/tools/review-diff.js");
+    const { buildReviewJson } = await import("../src/server/tools/review-format.js");
     const config = getProjectConfig(projectPath);
     const indexer = new Indexer(config);
     await indexer.index();
-    const markdown = handleReviewDiff(indexer, {
+    const reviewArgs = {
         ref: effectiveRef,
         max_files: maxFiles,
         token_budget: 8000,
-    });
+    };
+    // Run early so we can both decide the threshold AND emit the format.
+    // For github-review-json we want the structured payload; for the
+    // other two formats we just need the markdown.
+    let markdown = "";
+    let structured = null;
+    if (format === "github-review-json") {
+        structured = buildReviewJson(indexer, reviewArgs);
+        if ("error" in structured) {
+            process.stderr.write(`✗ ${structured.error}\n`);
+            indexer.close();
+            process.exit(2);
+        }
+        markdown = structured.summary;
+    }
+    else {
+        markdown = handleReviewDiff(indexer, reviewArgs);
+    }
     indexer.close();
     if (format === "json") {
-        // Wrap the markdown in a JSON envelope with parsed risk level
         const riskLevels = ["low", "medium", "high", "critical"];
         let maxRisk = "low";
         for (const level of riskLevels) {
@@ -660,6 +774,9 @@ if (command === "review") {
         };
         process.stdout.write(JSON.stringify(output, null, 2) + "\n");
     }
+    else if (format === "github-review-json") {
+        process.stdout.write(JSON.stringify(structured, null, 2) + "\n");
+    }
     else {
         process.stdout.write(markdown + "\n");
     }
@@ -1221,6 +1338,320 @@ if (command === "concept-index") {
     indexer.close();
     process.exit(r.failed > 0 && r.labeled === 0 ? 1 : 0);
 }
+if (command === "grammars") {
+    // Installs / refreshes the WASM grammars used by SVERKLO_PARSER=tree-sitter
+    // into ~/.sverklo/grammars/. v0.17 opt-in path; the regex parser
+    // works without grammars, so this is purely additive.
+    const sub = args[1];
+    if (sub !== "install" && sub !== "list") {
+        console.log(`\nsverklo grammars — manage tree-sitter grammars for the SVERKLO_PARSER=tree-sitter opt-in parser\n\n` +
+            `Usage:\n` +
+            `  sverklo grammars install [--lang typescript,python,go] [--force]\n` +
+            `  sverklo grammars list\n\n` +
+            `Languages supported: typescript, tsx, javascript, python, go, rust\n` +
+            `Grammars land in ~/.sverklo/grammars/. Total ~6 MB across all six.\n`);
+        process.exit(0);
+    }
+    const flags = args.slice(2);
+    const langArg = flags.find((f, i) => flags[i - 1] === "--lang") ?? "";
+    const langs = langArg
+        ? langArg.split(",").map((s) => s.trim())
+        : undefined;
+    const force = flags.includes("--force");
+    const { installGrammars, grammarsDir, GRAMMARS } = await import("../src/indexer/grammars-install.js");
+    if (sub === "list") {
+        console.log(`\nGrammars dir: ${grammarsDir()}\n`);
+        const { existsSync, statSync } = await import("node:fs");
+        const { join: jp } = await import("node:path");
+        for (const g of GRAMMARS) {
+            const p = jp(grammarsDir(), g.wasm);
+            if (existsSync(p)) {
+                console.log(`  ✓ ${g.lang.padEnd(12)}${(statSync(p).size / 1024).toFixed(0)} KB`);
+            }
+            else {
+                console.log(`  ✗ ${g.lang.padEnd(12)}not installed`);
+            }
+        }
+        console.log(`\nRun \`sverklo grammars install\` to fetch missing grammars.\n`);
+        process.exit(0);
+    }
+    console.log(`\nInstalling tree-sitter grammars into ${grammarsDir()}\n`);
+    const results = await installGrammars({
+        langs,
+        force,
+        onProgress: (m) => console.log(m),
+    });
+    const fresh = results.filter((r) => r.status === "fresh").length;
+    const cached = results.filter((r) => r.status === "cached").length;
+    const errors = results.filter((r) => r.status === "error");
+    console.log(`\nDone: ${fresh} downloaded, ${cached} cached, ${errors.length} failed.`);
+    if (errors.length > 0) {
+        for (const e of errors)
+            console.log(`  ✗ ${e.lang}: ${e.error}`);
+        console.log(`\nRetry with \`sverklo grammars install --force\` after checking your network.\n`);
+    }
+    else {
+        console.log(`\nNext: SVERKLO_PARSER=tree-sitter sverklo audit . to use them.\n`);
+    }
+    process.exit(errors.length > 0 ? 1 : 0);
+}
+if (command === "memory") {
+    // `sverklo memory` subcommands:
+    //   export  — push memory rows to markdown/Notion/JSON files
+    //   show    — print memory rows as markdown to stdout
+    //   edit    — open memory rows in $EDITOR; round-trip content edits back
+    //             to SQLite. Never deletes by omission.
+    const sub = args[1];
+    if (sub !== "export" && sub !== "show" && sub !== "edit") {
+        console.log(`\nsverklo memory — read, edit, and export the memory store\n\n` +
+            `Subcommands:\n` +
+            `  show     print all memories as markdown to stdout\n` +
+            `  edit     open memories in $EDITOR; round-trip text edits back\n` +
+            `  export   write per-category .md files / JSON / push to Notion\n\n` +
+            `Usage:\n` +
+            `  sverklo memory show [--include-invalidated]\n` +
+            `  sverklo memory edit [--editor PATH]\n` +
+            `  sverklo memory export --format markdown|notion|json --to PATH [flags]\n\n` +
+            `Run \`sverklo memory <subcommand> --help\` for the full flag list.\n`);
+        process.exit(0);
+    }
+    if (sub === "show") {
+        // Render every active memory as markdown to stdout. AI Edge's
+        // "open Memory.md and read it" workflow, but driven by SQLite —
+        // bi-temporal history, git provenance, no manual upkeep.
+        const flags = args.slice(2);
+        if (flags.includes("--help") || flags.includes("-h")) {
+            console.log(`\nsverklo memory show — print memories as markdown to stdout\n\n` +
+                `Flags:\n` +
+                `  --include-invalidated  include superseded rows (full bi-temporal timeline)\n` +
+                `  --kind episodic|semantic|procedural   filter by cognitive axis\n`);
+            process.exit(0);
+        }
+        const includeInvalidated = flags.includes("--include-invalidated");
+        const kindFlag = (() => {
+            const idx = flags.indexOf("--kind");
+            if (idx !== -1 && flags[idx + 1])
+                return flags[idx + 1];
+            const prefixed = flags.find((f) => f.startsWith("--kind="));
+            return prefixed ? prefixed.slice("--kind=".length) : undefined;
+        })();
+        if (kindFlag && !["episodic", "semantic", "procedural"].includes(kindFlag)) {
+            console.error(`✗ --kind must be episodic|semantic|procedural, got "${kindFlag}"`);
+            process.exit(2);
+        }
+        const valueFlags = new Set(["--kind"]);
+        const cleanFlags = [];
+        for (let i = 0; i < flags.length; i++) {
+            if (valueFlags.has(flags[i])) {
+                i++;
+                continue;
+            }
+            if (Array.from(valueFlags).some((f) => flags[i].startsWith(`${f}=`)))
+                continue;
+            cleanFlags.push(flags[i]);
+        }
+        const projectPath = await resolveProjectPath(cleanFlags);
+        const { getProjectConfig } = await import("../src/utils/config.js");
+        const { Indexer } = await import("../src/indexer/indexer.js");
+        const { renderMarkdownCombined } = await import("../src/memory/export.js");
+        const config = getProjectConfig(projectPath);
+        const indexer = new Indexer(config);
+        await indexer.index();
+        const rows = includeInvalidated
+            ? indexer.memoryStore.getTimeline(10_000)
+            : indexer.memoryStore.getAll(10_000);
+        const filtered = kindFlag ? rows.filter((m) => m.kind === kindFlag) : rows;
+        process.stdout.write(renderMarkdownCombined(filtered));
+        indexer.close();
+        process.exit(0);
+    }
+    if (sub === "edit") {
+        // Render memories to a temp markdown file, open in $EDITOR, parse
+        // changed content back into SQLite. Strict safety policy: omission
+        // never deletes (use `sverklo memory demote` for that); a parse
+        // error aborts without writing.
+        const flags = args.slice(2);
+        if (flags.includes("--help") || flags.includes("-h")) {
+            console.log(`\nsverklo memory edit — open memories in $EDITOR; round-trip text edits\n\n` +
+                `Flags:\n` +
+                `  --editor PATH    editor to invoke (default: $EDITOR or vi)\n\n` +
+                `Safety:\n` +
+                `  - Removing a memory's heading from the file does NOT delete it.\n` +
+                `    Use \`sverklo memory demote <id>\` (planned) or \`sverklo_demote\`\n` +
+                `    from MCP for explicit deletion.\n` +
+                `  - Adding a new memory by hand is not supported here. Use\n` +
+                `    \`sverklo_remember\` from MCP or call the API directly.\n` +
+                `  - If the parser can't make sense of your edits, the change\n` +
+                `    is rejected and your SQLite store is left untouched.\n`);
+            process.exit(0);
+        }
+        const editorOverride = (() => {
+            const idx = flags.indexOf("--editor");
+            if (idx !== -1 && flags[idx + 1])
+                return flags[idx + 1];
+            const prefixed = flags.find((f) => f.startsWith("--editor="));
+            return prefixed ? prefixed.slice("--editor=".length) : undefined;
+        })();
+        const editor = editorOverride ?? process.env.EDITOR ?? "vi";
+        const valueFlags = new Set(["--editor"]);
+        const cleanFlags = [];
+        for (let i = 0; i < flags.length; i++) {
+            if (valueFlags.has(flags[i])) {
+                i++;
+                continue;
+            }
+            if (Array.from(valueFlags).some((f) => flags[i].startsWith(`${f}=`)))
+                continue;
+            cleanFlags.push(flags[i]);
+        }
+        const projectPath = await resolveProjectPath(cleanFlags);
+        const { getProjectConfig } = await import("../src/utils/config.js");
+        const { Indexer } = await import("../src/indexer/indexer.js");
+        const { renderMarkdownCombined, parseMarkdownEdits } = await import("../src/memory/export.js");
+        const { writeFileSync, readFileSync, mkdtempSync } = await import("node:fs");
+        const { tmpdir } = await import("node:os");
+        const { join: joinPath } = await import("node:path");
+        const { spawnSync: spawn } = await import("node:child_process");
+        const config = getProjectConfig(projectPath);
+        const indexer = new Indexer(config);
+        await indexer.index();
+        const rows = indexer.memoryStore.getAll(10_000);
+        if (rows.length === 0) {
+            console.log("(no memories to edit)");
+            indexer.close();
+            process.exit(0);
+        }
+        const dir = mkdtempSync(joinPath(tmpdir(), "sverklo-memory-edit-"));
+        const filePath = joinPath(dir, "memory.md");
+        const original = renderMarkdownCombined(rows);
+        writeFileSync(filePath, original, "utf-8");
+        console.log(`Opening ${filePath} in ${editor}...`);
+        const result = spawn(editor, [filePath], { stdio: "inherit" });
+        if (result.status !== 0) {
+            console.error(`✗ editor exited with status ${result.status}; no changes applied`);
+            indexer.close();
+            process.exit(1);
+        }
+        const after = readFileSync(filePath, "utf-8");
+        if (after === original) {
+            console.log("(no edits — exiting)");
+            indexer.close();
+            process.exit(0);
+        }
+        const parsed = parseMarkdownEdits(after);
+        if (parsed === null) {
+            console.error("✗ couldn't parse the edited file (heading structure broken). No changes applied.");
+            console.error(`  Your edits are preserved at ${filePath} in case you want to recover them.`);
+            indexer.close();
+            process.exit(1);
+        }
+        // Compute the diff: ids whose content changed.
+        const byId = new Map(rows.map((r) => [r.id, r]));
+        const updates = [];
+        for (const edit of parsed) {
+            const original = byId.get(edit.id);
+            if (!original)
+                continue; // edit references an unknown id — skip silently
+            if (original.content === edit.content)
+                continue;
+            updates.push({ id: edit.id, content: edit.content, before: original.content });
+        }
+        if (updates.length === 0) {
+            console.log("(content unchanged — only metadata or formatting edits, ignoring)");
+            indexer.close();
+            process.exit(0);
+        }
+        for (const u of updates) {
+            indexer.memoryStore.update(u.id, u.content);
+        }
+        console.log(`✓ updated ${updates.length} memor${updates.length === 1 ? "y" : "ies"}:`);
+        for (const u of updates) {
+            const beforeSnip = u.before.slice(0, 60).replace(/\n/g, " ");
+            const afterSnip = u.content.slice(0, 60).replace(/\n/g, " ");
+            console.log(`  #${u.id}: "${beforeSnip}${u.before.length > 60 ? "..." : ""}"`);
+            console.log(`       → "${afterSnip}${u.content.length > 60 ? "..." : ""}"`);
+        }
+        console.log(`\nNote: omitted memories are preserved. Use \`sverklo_demote <id>\` from MCP\n` +
+            `to explicitly archive a memory.`);
+        indexer.close();
+        process.exit(0);
+    }
+    const flags = args.slice(2);
+    if (flags.includes("--help") || flags.includes("-h")) {
+        console.log(`\nsverklo memory export — push memory rows to markdown / Notion / JSON\n\n` +
+            `Required: --format markdown|notion|json --to PATH\n` +
+            `See \`sverklo memory\` for the full flag list.\n`);
+        process.exit(0);
+    }
+    const flagVal = (name) => {
+        const idx = flags.indexOf(name);
+        if (idx !== -1 && flags[idx + 1])
+            return flags[idx + 1];
+        const prefixed = flags.find((f) => f.startsWith(`${name}=`));
+        return prefixed ? prefixed.slice(name.length + 1) : undefined;
+    };
+    const format = flagVal("--format");
+    if (!format || !["markdown", "notion", "json"].includes(format)) {
+        console.error("✗ --format markdown|notion|json is required");
+        process.exit(2);
+    }
+    const to = flagVal("--to");
+    if (!to) {
+        console.error("✗ --to PATH is required");
+        process.exit(2);
+    }
+    const kindRaw = flagVal("--kind");
+    if (kindRaw && !["episodic", "semantic", "procedural"].includes(kindRaw)) {
+        console.error(`✗ --kind must be episodic|semantic|procedural, got "${kindRaw}"`);
+        process.exit(2);
+    }
+    const includeInvalidated = flags.includes("--include-invalidated");
+    const notionDatabase = flagVal("--notion-database");
+    if (format === "notion" && !notionDatabase) {
+        console.error("✗ --notion-database ID is required for --format notion");
+        process.exit(2);
+    }
+    // Strip value-taking flags before resolving the project path
+    const valueFlags = new Set(["--format", "--to", "--kind", "--notion-database"]);
+    const cleanFlags = [];
+    for (let i = 0; i < flags.length; i++) {
+        if (valueFlags.has(flags[i])) {
+            i++;
+            continue;
+        }
+        if (Array.from(valueFlags).some((f) => flags[i].startsWith(`${f}=`)))
+            continue;
+        cleanFlags.push(flags[i]);
+    }
+    const projectPath = await resolveProjectPath(cleanFlags);
+    const { resolve: resolvePath } = await import("node:path");
+    const outPath = resolvePath(to);
+    const { getProjectConfig } = await import("../src/utils/config.js");
+    const { Indexer } = await import("../src/indexer/indexer.js");
+    const { runMemoryExport } = await import("../src/memory/export.js");
+    const config = getProjectConfig(projectPath);
+    const indexer = new Indexer(config);
+    await indexer.index();
+    try {
+        const report = runMemoryExport(indexer, {
+            format,
+            to: outPath,
+            kind: kindRaw,
+            includeInvalidated,
+            notionDatabase,
+        });
+        console.log(`\nExported ${report.rowsExported} memories (${format}):\n` +
+            report.written.map((p) => `  ${p}`).join("\n") +
+            `\n\nBy category: ${Object.entries(report.byCategory).map(([k, v]) => `${k}=${v}`).join(", ") || "(none)"}\n`);
+    }
+    catch (err) {
+        const e = err;
+        console.error(`✗ export failed: ${e.message ?? String(err)}`);
+        process.exit(1);
+    }
+    indexer.close();
+    process.exit(0);
+}
 if (command === "digest") {
     // Habit-loop scaffold: 5-line summary of what changed in this project
     // since the user last paid attention. Designed to be cheap to render
@@ -1395,6 +1826,8 @@ Memory + offline maintenance:
   sverklo wakeup             Print compressed project context (for system-prompt injection)
   sverklo wiki               Generate a markdown wiki from the indexed codebase
   sverklo digest             5-line summary of what changed in this project (--since 7d)
+  sverklo memory export      Export memories to markdown / Notion / JSON
+  sverklo grammars install   Install tree-sitter grammars for the v0.17 opt-in parser
   sverklo prune              Decay stale memories + consolidate similar episodic ones
   sverklo concept-index      Label clusters with an LLM (requires Ollama)
   sverklo enrich-symbols     Add LLM-generated purpose to top-PageRank symbols (requires Ollama)