@staix/vault-mem 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.2.3] - 2026-10-31
+
+- Graph communities use a deterministic, dependency-free Leiden (modularity, resolution 1.0) instead of label propagation, which collapsed most of a real vault into one community. Every community is connected, ids are numbered by size then smallest member, and `vault-graph.json` and the report Overview record the partitioner, resolution and modularity. The vault graph, the workspace graph and skill mining share it.
+- `vmem graph build <vault> --workspace` and `vmem_graph_build` with `workspace: true` build `reports/workspace-graph.json`: the vault graph plus the work layer (work docs, business-unit hubs, `source:` stubs and `related`, `fm_ref`, `wiki_link`, `bu_member`, `source_ref` and `supersedes` edges), a rule-for-rule port of `build-graph.py --work-root`. It writes only that file and one GRAPH event and returns the work counters and per-relation edge counts. `bun scripts/workspace-parity.ts <vault>` compares it against the Python reference, counts only.
+- `vmem skills mine <vault>` and the MCP tool `vmem_skills_mine` rank new-skill candidates from agent-mem curated entries, agent-mem capture prompts, observations and summaries, and vault notes. They port the skill-mine dictionary matching, masking and scoring, cluster with vmem's deterministic graph communities, report counts by source and write nothing.
+
 ## [0.2.2] - 2026-10-31
 
 - Report operations under `reports/` and `ops/` accept and reread files up to 16 MiB, so graph artifacts above 2 MiB can be rebuilt. Notes keep their 256 KiB write / 2 MiB read limits; CLI body input limits are unchanged.

package/README.md

@@ -171,6 +171,7 @@ The vault set is read once at startup: every tool's `vault` property is an enum
 | `vmem_move` | `from`, `to`, `confirm`, `fingerprint` (two-step) |
 | `vmem_delete` | `path`, `confirm`, `fingerprint` (two-step; the preview lists backlinks) |
 | `vmem_promote` | `path` (in the personal vault), `to` (enum of org vaults), `topics[]`, `again`, `confirm`, `fingerprint` (two-step; never pushes) |
+| `vmem_skills_mine` | `vault`, `days`, `project`, `allProjects`, `vocab`, `skills[]`, `minSize`, `minNovelty` (read-only; see Skill mining) |
 | `vmem_promote_from_amem` | `id`, `project`, `stem`, `type`, `domain`, `topics[]`, `description`, `title`, `body`<=65536, `linkTo`, `confirm`, `fingerprint` (two-step) |
 
 Move and delete without `confirm` write nothing and return the preview and `fingerprint`; `confirm: true` requires the fingerprint recomputed on the current state, otherwise the call is refused with `V09`. `vmem_promote_from_amem` is described under Promotion from agent-mem. `vmem_promote` is described under Org promotion and sync. Graph/lint tools are listed below. Note paths in read results are relative to `notes/`.
@@ -214,7 +215,18 @@ vmem promote-from-amem personal mem:<id> --link-to existing-note  # link an exis
 
 `vmem graph build <vault> [--dry-run]` writes `reports/vault-graph.json`, a dated graph report, graph trend history and GRAPH events through `applyWrite`. Old dated reports are preserved. Trend history appends one row per build, including repeated builds on the same date. Output receipts expose partial report/log failure; these separate writes are not a single transaction. `vmem graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500]` reads a bounded neighborhood. Matching MCP tools are `vmem_lint`, `vmem_graph_build`, and `vmem_graph_neighbors`; MCP report writes require `write=mcp`.
 
-Analysis consumes note sources from the derived SQLite index, including invalid-frontmatter rows retained separately from searchable notes. Normal scans also retain note sources in `analysis_notes`, roughly doubling cached source storage outside the vault; the cache remains derived and can be rebuilt. Read-only analysis and dry runs clone any existing derived cache through a readonly connection, then refresh changed notes in memory. A missing cache is built in memory. They create no cache, locks, reports or events. Auxiliary log, registry and report inputs use bounded plain-file reads. Snapshot limits are 10,000 notes / 64 MiB source, 1,000 reports / 16 MiB per file and combined, and 32 MiB log; oversized inputs fail explicitly. Graph limits are 100,000 edges and 32 deterministic label-propagation rounds. MOCs are excluded from clustering; ties sort by node id. Graph extraction intentionally retains the reference's body-only legacy wiki-link semantics, distinct from the richer navigation resolver.
+**Communities** come from a deterministic, dependency-free Leiden (Traag, Waltman and van Eck 2019) optimizing modularity with resolution γ = 1.0: fast local moving with a node queue, refinement that merges only well-connected nodes inside each community (the greedy variant, so no random step), and aggregation on the refined partition initialized from the unrefined one, repeated while modularity improves. Nodes are processed in code-point id order and gain ties go to the lowest community id, so the same graph gives byte-identical output whatever the input order. Every community induces a connected subgraph. MOC (and, in the workspace graph, `bu`) nodes are excluded and get `community: null`; an isolated note is its own community. Community ids are numbered by size (descending), then by smallest member id; they are build-local, so cite a member, not the id. `vault-graph.json` records `graph.partitioner: "leiden"`, `resolution`, the achieved `modularity` and the number of levels, and the report Overview prints the partitioner, resolution and modularity. Modularity has a resolution limit: communities smaller than a size that grows with the whole graph cannot be separated, so a very small cluster may merge into a neighbor. There is no resolution setting yet. Skill mining (`vmem skills mine`) and the workspace graph use the same function. `bun scripts/leiden-live.ts <vault-id>` prints counts only: modularity, community count, largest share, connectivity, clustering time and NMI against the Python reference's Leiden partition.
+
+`vmem graph build <vault> --workspace [--dry-run]` (MCP: `vmem_graph_build` with `workspace: true`) builds the workspace graph: the vault graph exactly as above plus the work layer under the vault's work root (the parent of its `registry`; a vault without `registry` is refused). It writes only `reports/workspace-graph.json` through `applyWrite` (no dated report, no trend row) and one GRAPH event, and returns the work counters (`work_docs`, `yaml_fail`, `template_skip`, `related_*`, `source_*`, `collisions`, `dup_edges`) and edge counts per relation. It ports `extract_work` from `build-graph.py --work-root` rule for rule:
+
+- **Walk.** `.md` files under the work root, never following symlinks, pruning `.git node_modules .venv .sync-conflicts temp .maru .pnpm-store .conductor .dotfiles .omx .omc .gstack .frontend-slides .claude .archive archive vault inbox sites dev shared _templates templates` and the scratchpad memos/temp roots (`workspace.config.yaml` `paths.scratchpad`, `scratchpad.memos_subdir`, `scratchpad.temp_subdir`; default `scratchpad/memos`, `scratchpad/temp`). `denyPaths` are honored. Only a file whose first bytes open frontmatter (`---` and whitespace) is read; the rest are probed and skipped.
+- **Nodes.** A work doc qualifies with `document_type`, a non-empty `projects project vault_note topics attendees relatedMeetings relatedTasks`, or `related`; frontmatter containing `{{` is a template (`template_skip`) and unparseable frontmatter is `yaml_fail`. Ids are `work:<relpath>`; business-unit hubs `bu:<slug>` come from `bu_id` in `bu-config.yaml` files named by a doc's `business_unit`; a vault `source:` that names an existing work file outside the qualifying set becomes a `type: file` stub.
+- **Edges.** `related` (work to work, by unique stem or relative `.md` path, `rel` kept), `fm_ref` (work field wiki-link to a vault stem, `field` kept), `wiki_link` (work body to a vault stem), `bu_member`, `source_ref` (vault `source:` to a work node) and `supersedes` (`supersedes`/`superseded_by`, `field` kept). Edges to unknown nodes and self-loops are dropped; one edge per pair survives by priority `wiki_link < fm_ref < bu_member < source_ref < related < supersedes`, and a work-layer edge replaces a vault-layer edge on the same pair. Communities exclude `moc` and `bu` nodes.
+- **Bounds.** 50,000 probed files (each counted once, whether or not it is then read), 2 MiB per read work doc, 128 MiB read in total and 2,000,000 directory entries per walk; exceeding one fails explicitly. Every probed file is stamped, so a file that changes during the build (including a plain file that gains frontmatter) refuses the write. The output is within the 16 MiB report bound.
+
+`bun scripts/workspace-parity.ts <vault-id>` runs the unchanged Python `build-graph.py --work-root` into a private temp directory and the in-memory vmem build on the same tree, and prints only counts: node-id, edge-pair, relation, attribute and counter differences (`--python`, `--reference` select the interpreter and script). Communities are not compared.
+
+Analysis consumes note sources from the derived SQLite index, including invalid-frontmatter rows retained separately from searchable notes. Normal scans also retain note sources in `analysis_notes`, roughly doubling cached source storage outside the vault; the cache remains derived and can be rebuilt. Read-only analysis and dry runs clone any existing derived cache through a readonly connection, then refresh changed notes in memory. A missing cache is built in memory. They create no cache, locks, reports or events. Auxiliary log, registry and report inputs use bounded plain-file reads. Snapshot limits are 10,000 notes / 64 MiB source, 1,000 reports / 16 MiB per file and combined, and 32 MiB log; oversized inputs fail explicitly. Graph limits are 100,000 edges. MOCs are excluded from clustering; ties sort by node id. Graph extraction intentionally retains the reference's body-only legacy wiki-link semantics, distinct from the richer navigation resolver.
 
 `bun scripts/lint-parity.ts` and `bun scripts/graph-parity.ts` compare the synthetic corpus against frozen Python reference oracles. Use `--reference /absolute/path/to/lint.py` or `--reference /absolute/path/to/build-graph.py` to run the unchanged Python tools directly (`PYTHON` selects an interpreter with PyYAML/networkx). Keep those references until a separate retirement decision after two consecutive zero-diff runs. Fixture parity does not establish private-corpus parity or authorize a live vault cutover. Private corpus evidence stays private; no note bodies belong in public fixtures.
 
@@ -244,6 +256,16 @@ vmem sync team --confirm --fingerprint <sha>
 - **Git hardening.** Git runs through agent-mem's hardened argv: hooks, fsmonitor, external diff, pager, credential helper and askpass are disabled, `GIT_TERMINAL_PROMPT=0` is set, and repository-redirecting `GIT_*` variables are removed. So sync uses ssh keys or a deploy key and never prompts.
 - **Not decided by the tool.** Which org, visibility, remote and deploy key a vault uses are deployment decisions, and whether an agent may push a given org vault is the workspace's external-sending rule.
 
+## Skill mining
+
+`vmem skills mine <vault> [--days N] [--project KEY|--all-projects] [--vocab DIR] [--skills DIR ...] [--min-size N] [--min-novelty X] [--json]` ranks repeated work patterns as new-skill candidates. It replaces the Python `skill-mine` pipeline and reads memory instead of raw session logs. `vmem_skills_mine` takes the same inputs over MCP.
+
+- **Records** (within `--days`, default 30; exact duplicate texts kept once). agent-mem curated entries of kind `decision`, `finding`, `contract` or `fail` (title and text), screened by agent-mem's standalone policy plus the vault config's `piiPatterns`. agent-mem capture rows with event `UserPromptSubmit`, `observation` or `summary` (the excerpt), opened read-only; tool events are skipped. Vault notes of every type except `person`, `moc` and `reference` (title, description and body), dated by frontmatter `created`/`date`, else the file mtime. All active agent-mem projects are read by default; `--project` narrows to one.
+- **Matching and graph.** The `materialize.py` rules: action and object vocabularies from `--vocab DIR` (`actions.yaml`, `objects.yaml`; the skill ships them), plus project keywords, acronyms, people and orgs from the vault's `registry`; every contained surface matches (ASCII case-insensitively, Hangul exactly), giving nodes `action--<canon>`, `object--<canon>` and `entity--<kind>--<slug>`. A person node id is a digest, never the name. Records and vocabulary nodes form one graph clustered by the same deterministic Leiden as `vmem graph build`.
+- **Scoring.** The `analyze.py` rules: a community with at least `--min-size` records (default 3) and novelty at least `--min-novelty` (default 0.3) is a candidate, labelled `{top action}-{top object}`, with up to 8 triggers. Cohesion is the community's edge density; novelty is 1 minus the highest Jaccard similarity against the `SKILL.md` name and description tokens under each `--skills` directory; rank is `log2(size) × (unique days / day span) × max(0.1, cohesion) × max(0.1, novelty)`. The report keeps the god nodes, candidates, surprising connections and rejected sections and adds per-candidate counts by source (curated, capture, vault).
+- **Privacy boundary.** The command writes nothing: no vault file, lock, cache, report or log event, nothing under the vmem home and no content under the agent-mem home (it opens no store that does not exist). Reading a SQLite database may create an empty `-wal` file and a `-shm` WAL index (no row content) next to it in the agent-mem home, and nothing else. A record matching vmem's secret screen is dropped and counted. Returned samples from all three sources are masked the same way: registry people become `[PERSON]` (ASCII names case-insensitively, as matching does), emails `[EMAIL]`, absolute paths `[PATH]` and matches of the vault config's `piiPatterns` `[PII]`. Over MCP a vault re-registered after server startup is refused. The JSON result and the markdown report are the only output, and the calling skill decides where to save it.
+- **Bounds.** At most 20,000 records, 64 KiB per record (larger records are dropped and counted) and 64 MiB in total; exceeding the record or total bound fails with an explicit error. Capture reads keep the newest 20,000 rows per machine and count a truncated shard.
+
 
 
 ## Release readiness

package/bin/vmem.js

@@ -8,5 +8,5 @@ const { main, mainAsync, runMcp } = await import("../src/cli.ts");
 if (process.argv.length === 3 && process.argv[2] === "mcp") {
   try { await runMcp(); }
   catch (error) { console.error(`vmem mcp: ${error instanceof Error ? error.message : "failed"}`); process.exitCode = 1; }
-} else if (process.argv[2] === "promote-from-amem") process.exitCode = await mainAsync(process.argv.slice(2));
+} else if (process.argv[2] === "promote-from-amem" || process.argv[2] === "skills") process.exitCode = await mainAsync(process.argv.slice(2));
 else process.exitCode = main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/vault-mem",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
   "license": "MIT",
   "type": "module",

package/src/amem/seam.ts

@@ -47,6 +47,62 @@ export async function openAmem(options: AmemOptions = {}): Promise<AmemSeam> {
     close() { store.close(); },
   };
 }
+export interface MineAmemRecord { source: "curated" | "capture"; kind: string; at: string; text: string; project: string }
+export interface MineAmemRead { records: MineAmemRecord[]; projects: string[]; screened: number; truncatedCapture: number; unreadable: number }
+const MINE_KINDS = new Set(["decision", "finding", "contract", "fail"]);
+const MINE_EVENTS = new Set(["UserPromptSubmit", "observation", "summary"]);
+/**
+ * Skill mining input, read-only: curated entries (screened by amem's standalone policy plus the vault's piiPatterns) and
+ * capture rows (events UserPromptSubmit/observation/summary) of every active project, or one. Opens nothing that does not
+ * exist: an absent home, a capture-only shard or an unsplit home without curated logs yields no rows, never a new store.
+ */
+export async function readAmemForMining(options: { env?: NodeJS.ProcessEnv; project?: string; since: string; piiPatterns?: string[]; maxCaptureRows?: number }): Promise<MineAmemRead> {
+  const amem = await import("@staix/agent-mem");
+  const { existsSync } = await import("node:fs"), { basename, join } = await import("node:path");
+  const base = amem.memoryHome(options.env ?? process.env), maxRows = options.maxCaptureRows ?? 20000;
+  const out: MineAmemRead = { records: [], projects: [], screened: 0, truncatedCapture: 0, unreadable: 0 };
+  if (!existsSync(base)) return out;
+  const policy = amem.createStandalonePolicy({ ...(options.piiPatterns?.length ? { piiPatterns: [...options.piiPatterns] } : {}) });
+  const state = amem.lifecycleResolver(base);
+  const sharded = existsSync(join(base, "shards.json"));
+  const unsplitCurated = !sharded && ["log", "local", "generations"].some(name => existsSync(join(base, name)));
+  const shared: MemoryStore | undefined = unsplitCurated ? new amem.MemoryStore({ memoryDir: base, deferPromotions: true }) : undefined;
+  try {
+    // A split home lists its projects as shards; an unsplit home keeps curated projects in the one shared store.
+    const machineDirs = new Map(amem.walkShards(base).map(shard => [shard.key, shard.machineDirs]));
+    for (const view of shared?.list({ limit: 1_000_000, includeSuperseded: true }) ?? []) if (!machineDirs.has(view.project)) machineDirs.set(view.project, []);
+    const shards = [...machineDirs].map(([key, dirs]) => ({ key, machineDirs: dirs }))
+      .filter(shard => state(shard.key) === "active" && (options.project === undefined || shard.key === options.project))
+      .sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+    if (options.project !== undefined && !shards.length) throw new Error(`amem: no active project shard for ${options.project}`);
+    for (const shard of shards) {
+      out.projects.push(shard.key);
+      const store: MemoryStore | undefined = shared ?? (sharded && existsSync(join(amem.shardDir(base, shard.key), "generation.json"))
+        ? amem.openShardStore({ memoryDir: base, project: shard.key, deferPromotions: true, lifecycle: "ignore" }) : undefined);
+      try {
+        for (const { view } of store?.vaultEntries(shard.key) ?? []) {
+          if (!MINE_KINDS.has(view.kind) || view.supersededBy || view.at < options.since) continue;
+          if (!await policy.screen(view)) { out.screened++; continue; }
+          out.records.push({ source: "curated", kind: view.kind, at: view.at, text: [view.title, view.text].filter(Boolean).join("\n"), project: shard.key });
+        }
+      } catch { out.unreadable++; }
+      finally { if (store && store !== shared) store.close(); }
+      for (const dir of shard.machineDirs) {
+        let capture: InstanceType<typeof amem.CaptureStore> | undefined;
+        try {
+          capture = new amem.CaptureStore({ memoryDir: base, project: shard.key, machine: basename(dir), readOnly: true, recentReadRows: true, maxReadRows: maxRows });
+          if (capture.recentReadTruncated) out.truncatedCapture++;
+          for (const row of capture.rows({ limit: maxRows })) {
+            if (!MINE_EVENTS.has(row.event) || row.at < options.since || !row.excerpt.trim()) continue;
+            out.records.push({ source: "capture", kind: row.event, at: row.at, text: row.excerpt, project: shard.key });
+          }
+        } catch { out.unreadable++; }
+        finally { capture?.close(); }
+      }
+    }
+  } finally { shared?.close(); }
+  return out;
+}
 /** Cross-project candidate table from amem's own selection, read-only. */
 export async function allProjectCandidates(options: { env?: NodeJS.ProcessEnv; limit?: number; piiPatterns?: string[] }): Promise<{ project: string; candidates: AmemCandidate[] }[]> {
   const amem = await import("@staix/agent-mem");

package/src/analysis-commands.ts

@@ -9,12 +9,12 @@ export function runAnalysisCommand(command: string, args: string[], home: string
     const word = args[i]!;
     if (!word.startsWith("-")) { positional.push(word); continue; }
     if (word in values || flags.has(word)) throw new Error("analysis: repeated option");
-    if (["--json","--dry-run","--write"].includes(word)) flags.add(word);
+    if (["--json","--dry-run","--write","--workspace"].includes(word)) flags.add(word);
     else if (["--note","--hops","--limit"].includes(word)) { const value = args[++i]; if (!value || value.startsWith("--")) throw new Error(`${word}: requires value`); values[word]=value; }
     else throw new Error(`analysis: unknown option ${word}`);
   }
   if (command === "lint") {
-    if (positional.length !== 1 || values["--hops"] || values["--limit"]) throw new Error("lint: requires one vault id");
+    if (positional.length !== 1 || values["--hops"] || values["--limit"] || flags.has("--workspace")) throw new Error("lint: requires one vault id");
     if (flags.has("--write")) { const result = writeAnalysisReports(home,{vault:positional[0]!,kind:"lint",note:values["--note"],dryRun:flags.has("--dry-run")},env); return {text:JSON.stringify(result),code:result.ok && (result.summary as {errors?:number}).errors === 0 ? 0 : 1}; }
     const {snapshot} = analysisInput(home,positional[0]!);
     const report = lintVault(snapshot,values["--note"]);
@@ -24,10 +24,10 @@ export function runAnalysisCommand(command: string, args: string[], home: string
   if (values["--note"] || flags.has("--write")) throw new Error("graph: unsupported option");
   if (action === "build") {
     if (positional.length !== 1 || values["--hops"] || values["--limit"]) throw new Error("graph build: requires one vault id");
-    const result = writeAnalysisReports(home,{vault:positional[0]!,kind:"graph",dryRun:flags.has("--dry-run")},env);
+    const result = writeAnalysisReports(home,{vault:positional[0]!,kind:"graph",workspace:flags.has("--workspace"),dryRun:flags.has("--dry-run")},env);
     return {text:JSON.stringify(result),code:result.ok ? 0 : 1};
   }
-  if (action !== "neighbors" || positional.length !== 2) throw new Error("graph: use build <vault> or neighbors <vault> <stem>");
+  if (action !== "neighbors" || positional.length !== 2 || flags.has("--workspace")) throw new Error("graph: use build <vault> or neighbors <vault> <stem>");
   const hops = Number(values["--hops"] ?? 1), limit = Number(values["--limit"] ?? 50);
   if ((hops !== 1 && hops !== 2) || !Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error("graph neighbors: hops 1..2, limit 1..500");
   const {snapshot} = analysisInput(home,positional[0]!);

package/src/analysis-reports.ts

@@ -1,3 +1,5 @@
+import { workspaceInput } from "./workspace-input.ts";
+import { buildWorkspaceGraph } from "./workspace-graph.ts";
 import { MAX_REPORT_BYTES } from "./write-validation.ts";
 import type { VaultSpec } from "./config.ts";
 import { lstatSync } from "node:fs";
@@ -12,7 +14,7 @@ import { analysisInput } from "./analysis-input.ts";
 import { lintVault } from "./vault-lint.ts";
 import { buildGraph, graphReport } from "./vault-graph.ts";
 
-export interface AnalysisRequest { vault: string; kind: "lint" | "graph"; dryRun?: boolean; channel?: "cli" | "mcp"; today?: string; note?: string; expectedVault?: VaultSpec }
+export interface AnalysisRequest { vault: string; kind: "lint" | "graph"; workspace?: boolean; dryRun?: boolean; channel?: "cli" | "mcp"; today?: string; note?: string; expectedVault?: VaultSpec }
 function trend(snapshot: AnalysisSnapshot, nodes: number, edges: number, communities: number, top: string): string {
   const seed = "---\ntype: report\nkind: graph-trend\n---\n\n# Graph Trend (vault layer)\n\n| 빌드 | Nodes | Edges | Communities | Density | Top hub (degree 1위) |\n|---|---|---|---|---|---|\n";
   const source = snapshot.reports["graph-trend.md"] ?? seed;
@@ -27,8 +29,11 @@ function trend(snapshot: AnalysisSnapshot, nodes: number, edges: number, communi
 }
 export function writeAnalysisReports(home: string, request: AnalysisRequest, env: NodeJS.ProcessEnv = process.env) {
   const {snapshot,vault,config,identity} = analysisInput(home,request.vault,{today:request.today,expectedVault:request.expectedVault});
+  if (request.workspace && request.kind !== "graph") throw new Error("workspace is only supported for graph build");
+  const work = request.workspace ? workspaceInput(snapshot,vault,config) : undefined;
   const binding = {vault,denyPaths:config.denyPaths ?? [],piiPatterns:config.piiPatterns ?? [],dev:Number(identity.dev),ino:Number(identity.ino)};
   const unchanged = () => {
+    work?.assertUnchanged?.();
     const current = loadRegistry(home), stat = lstatSync(vault.path);
     if (JSON.stringify(current) !== JSON.stringify(config) || stat.dev !== identity.dev || stat.ino !== identity.ino || stat.isSymbolicLink()) throw new Error("analysis: vault or policy changed during build");
   };
@@ -37,6 +42,10 @@ export function writeAnalysisReports(home: string, request: AnalysisRequest, env
   if (request.kind === "lint") {
     const lint = lintVault(snapshot,request.note); summary = {findings:lint.findings,errors:lint.errors,warnings:lint.warnings,summary:lint.summary};
     outputs.push({path:`reports/lint-report-${snapshot.today.slice(2).replaceAll("-","")}.md`,text:lint.markdown+"\n"+lint.summary+"\n"});
+  } else if (work) {
+    const result = buildWorkspaceGraph(snapshot,work);
+    summary = { nodes: result.graph.nodes.length, edges: result.graph.edges.length, ...result.counters, relations: result.relations };
+    outputs.push({path:"reports/workspace-graph.json",text:JSON.stringify(result.graph,null,2)+"\n"});
   } else {
     const graph = buildGraph(snapshot), communities = new Set(graph.nodes.flatMap(n => n.community === null ? [] : [n.community])).size;
     summary = {nodes:graph.nodes.length,edges:graph.edges.length,communities};
@@ -47,7 +56,7 @@ export function writeAnalysisReports(home: string, request: AnalysisRequest, env
   }
   const originals = new Map(outputs.map(out => {
     const name = out.path.slice("reports/".length);
-    return [out.path, request.kind === "graph" ? snapshot.reports[name] ?? null : analysisRead(join(vault.path,out.path), MAX_REPORT_BYTES)] as const;
+    return [out.path, request.kind === "graph" && !request.workspace ? snapshot.reports[name] ?? null : analysisRead(join(vault.path,out.path), MAX_REPORT_BYTES)] as const;
   }));
   unchanged();
   for (const out of outputs) if (analysisRead(join(vault.path,out.path), MAX_REPORT_BYTES) !== originals.get(out.path)) throw new Error("analysis: report changed during build");
@@ -65,6 +74,6 @@ export function writeAnalysisReports(home: string, request: AnalysisRequest, env
   }
   const complete = receipts.length === outputs.length && receipts.every(r => r.ok);
   unchanged();
-  const log = complete ? appendLog(home,{vault:request.vault,channel:request.channel,event:{type:request.kind === "lint" ? "LINT" : "GRAPH",project:"-",source:"vmem",dest:outputs[0]!.path,note:request.kind === "lint" ? "Vault lint report" : "Vault graph reports"}},{env,binding}) : undefined;
+  const log = complete ? appendLog(home,{vault:request.vault,channel:request.channel,event:{type:request.kind === "lint" ? "LINT" : "GRAPH",project:"-",source:"vmem",dest:outputs[0]!.path,note:request.kind === "lint" ? "Vault lint report" : request.workspace ? "Workspace graph" : "Vault graph reports"}},{env,binding}) : undefined;
   return {ok:complete && log?.ok === true,applied:receipts.some(r => r.applied),summary,paths:outputs.map(o => o.path),receipts,log};
 }

package/src/cli.ts

@@ -113,8 +113,12 @@ export async function runMcp(env: NodeJS.ProcessEnv = process.env): Promise<void
   const server = createVaultMcp(resolveHome(env).home, env);
   await serveMcp({ tools: server.tools, handlers: server.handlers, name: "vmem", version });
 }
-/** Async commands. Only `promote-from-amem` loads the agent-mem seam, and only when it runs. */
+/** Async commands. Only `promote-from-amem` and `skills mine` load the agent-mem seam, and only when they run. */
 export async function runAsync(args: string[], env: NodeJS.ProcessEnv = process.env, io: { stdinIsTTY?: boolean } = {}): Promise<{ text: string; code: number }> {
+  if (args[0] === "skills") {
+    const { runSkillsCommand } = await import("./skills-mine.ts");
+    return runSkillsCommand(args.slice(1), resolveHome(env).home, env);
+  }
   if (args[0] !== "promote-from-amem") return run(args, env);
   const { runPromoteCommand } = await import("./promote-command.ts");
   return runPromoteCommand(args.slice(1), resolveHome(env).home, env, io);

package/src/commands-table.ts

@@ -1,7 +1,8 @@
 export const COMMANDS = [
   { name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write" },
-  { name: "graph build", usage: "graph build <vault> [--dry-run] [--json]", mutates: true },
+  { name: "graph build", usage: "graph build <vault> [--workspace] [--dry-run] [--json]", mutates: true },
   { name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--json]", mutates: false },
+  { name: "skills mine", usage: "skills mine <vault> [--days N] [--project KEY|--all-projects] [--vocab DIR] [--skills DIR] [--min-size N] [--min-novelty X] [--json]", mutates: false },
   { name: "rebuild", usage: "rebuild <vault> [--json]", mutates: "cache" },
   { name: "search", usage: "search <vault> <query> [--type TYPE] [--domain DOMAIN] [--limit 1..500] [--json]", mutates: "cache" },
   { name: "show", usage: "show <vault> <target> [--section TEXT] [--offset 0..2097152] [--max-bytes 1..65536] [--json]", mutates: "cache" },
@@ -67,7 +68,7 @@ export function completionScript(shell: string): string {
       const cond = d.path.length === 1 ? `__fish_seen_subcommand_from ${d.path[0]}` : `__fish_seen_subcommand_from ${d.path[1]}`;
       for (const flag of Object.keys(d.options)) lines.push(`complete -c vmem -n ${quote(cond)} -l ${flag.slice(2)}`);
     }
-    for (const parent of ["vaults", "log", "graph"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
+    for (const parent of ["vaults", "log", "graph", "skills"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
     return lines.join("\n") + "\n";
   }
   const cases = defs.map(d => `    ${quote(d.path.join(" "))}) words=${quote(Object.keys(d.options).join(" "))} ;;`);
@@ -76,7 +77,7 @@ export function completionScript(shell: string): string {
   cur="\${COMP_WORDS[COMP_CWORD]}"
   if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
   key="\${COMP_WORDS[1]}"
-  case "$key" in graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
+  case "$key" in graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
   case "$key" in
 ${cases.join("\n")}
     *) words='' ;;

package/src/mcp-vault.ts

@@ -27,7 +27,7 @@ const scalar = { type: ["string", "number", "boolean", "null", "array"], maxLeng
 
 /** Tool names for the implemented read, write, log, analysis and promotion providers. */
 export const VMEM_TOOL_NAMES = ["vmem_status", "vmem_search", "vmem_read", "vmem_read_many", "vmem_list", "vmem_links", "vmem_mocs", "vmem_check", "vmem_log_tail",
-  "vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote"] as const;
+  "vmem_create", "vmem_patch", "vmem_append", "vmem_set_frontmatter", "vmem_link", "vmem_supersede", "vmem_log_append", "vmem_move", "vmem_delete", "vmem_promote_from_amem", "vmem_lint", "vmem_graph_build", "vmem_graph_neighbors", "vmem_promote", "vmem_skills_mine"] as const;
 
 /** Tool definitions for a fixed vault set: `vault` is an enum of the registered ids. */
 export function vaultTools(ids: readonly string[], orgIds: readonly string[] = []): McpTool[] {
@@ -56,10 +56,12 @@ export function vaultTools(ids: readonly string[], orgIds: readonly string[] = [
     tool("vmem_promote_from_amem", "Two-step promotion of one durable agent-mem entry (id from amem_vault_candidates) into a vault note: without confirm returns the full note text, possible duplicates and fingerprint; confirm=true with that fingerprint creates the note, logs LEARN and records the agent-mem vault link. linkTo links an existing note instead.",
       object({ vault, id: { type: "string", minLength: 32, maxLength: 36 }, stem: string(120), type: string(64), domain: string(64), topics: { type: "array", maxItems: 32, items: string(200) }, description: string(1000), title: string(300), body: string(65536, 0), linkTo: note, project: string(400), ...twoStep }, ["id"]), "confirm"),
     tool("vmem_lint", "Lint a private derived snapshot; write=true writes a screened report.", object({ vault, write: { type: "boolean" }, dryRun: { type: "boolean" } }), "write"),
-    tool("vmem_graph_build", "Build a deterministic graph and screened reports; dryRun changes nothing.", object({ vault, dryRun: { type: "boolean" } }), "write"),
+    tool("vmem_graph_build", "Build a deterministic graph and screened reports; dryRun changes nothing.", object({ vault, dryRun: { type: "boolean" }, workspace: { type: "boolean" } }), "write"),
     tool("vmem_graph_neighbors", "Read a bounded graph neighborhood.", object({ vault, path: note, hops: integer(1,2), limit: integer(1,500) }, ["path"])),
     tool("vmem_promote", "Two-step promotion of a personal note into a local org vault clone (never pushes): without confirm returns the full transformed text, dropped links, screen result and fingerprint; confirm=true with that fingerprint writes the org note, source provenance and SYNC log lines. Publishing is the separate `vmem sync` CLI.",
       object({ path: note, to: orgVault, topics: { type: "array", maxItems: 32, items: string(200) }, again: { type: "boolean" }, ...twoStep }, ["path", "to"]), "confirm"),
+    tool("vmem_skills_mine", "Read-only skill-candidate mining over amem curated entries, amem capture rows and vault notes: dictionary matching, deterministic communities and novelty scoring. Returns counts, masked candidates and a markdown report; writes nothing.",
+      object({ vault, days: integer(1, 3650), project: string(400), allProjects: { type: "boolean" }, vocab: string(4096), skills: { type: "array", maxItems: 16, items: string(4096) }, minSize: integer(1, 10000), minNovelty: { type: "number", minimum: 0, maximum: 1 } })),
   ];
 }
 type Issue = { code: string; severity: "error"; message: string };
@@ -112,8 +114,14 @@ export function createVaultMcp(home: string, env: NodeJS.ProcessEnv = process.en
         ...(Array.isArray(args.topics) ? { topics: args.topics as string[] } : {}) }, { env, ...(str(args.project) ? { project: str(args.project) } : {}) });
       return result.ok ? result : { ...result, refused: true };
     },
+    vmem_skills_mine: async args => {
+      const { mineSkills } = await import("./skills-mine.ts");
+      return mineSkills(home, { vault: pick(args).id, expectedVault: pick(args), env, allProjects: args.allProjects === true, ...(str(args.project) ? { project: str(args.project) } : {}), ...(str(args.vocab) ? { vocab: str(args.vocab) } : {}),
+        ...(Array.isArray(args.skills) ? { skills: args.skills as string[] } : {}), ...(typeof args.days === "number" ? { days: args.days } : {}),
+        ...(typeof args.minSize === "number" ? { minSize: args.minSize } : {}), ...(typeof args.minNovelty === "number" ? { minNovelty: args.minNovelty } : {}) });
+    },
     vmem_lint: args => args.write === true ? writeAnalysisReports(home,{vault:pick(args).id,kind:"lint",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env) : lintVault(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),
-    vmem_graph_build: args => writeAnalysisReports(home,{vault:pick(args).id,kind:"graph",channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env),
+    vmem_graph_build: args => writeAnalysisReports(home,{vault:pick(args).id,kind:"graph",workspace:args.workspace === true,channel:"mcp",expectedVault:pick(args),dryRun:args.dryRun === true},env),
     vmem_graph_neighbors: args => graphNeighbors(buildGraph(analysisInput(home,pick(args).id,{expectedVault:pick(args)}).snapshot),str(args.path)!, (args.hops as 1|2|undefined) ?? 1, (args.limit as number|undefined) ?? 50),
     vmem_status: () => ({ defaultVault: defaultVault ?? null, vaults: registryStatus(home).filter(v => ids.includes(v.id)) }),
     vmem_search: args => read(args, index => ({ hits: index.search(str(args.query)!, { limit: (args.limit as number | undefined) ?? 20, type: str(args.type), domain: str(args.domain) }) })),