@staix/vault-mem 0.11.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +17 -2
- package/bin/vmem.js +5 -1
- package/package.json +2 -1
- package/skills/_shared/vault-adapter.md +131 -0
- package/skills/skill-mine/SKILL.md +52 -0
- package/skills/skill-mine/vocab/actions.yaml +110 -0
- package/skills/skill-mine/vocab/objects.yaml +123 -0
- package/skills/vault-connect/SKILL.md +75 -0
- package/skills/vault-extract/README.md +20 -0
- package/skills/vault-extract/SKILL.md +139 -0
- package/skills/vault-graph/SKILL.md +120 -0
- package/skills/vault-learn/SKILL.md +111 -0
- package/skills/vault-lint/README.md +32 -0
- package/skills/vault-lint/SKILL.md +137 -0
- package/skills/vault-lint/references/lint-output.md +97 -0
- package/skills/vault-lint/references/vault-scope-rules.md +26 -0
- package/skills/vault-lint/references/work-scope-checks.md +71 -0
- package/skills/vault-refactor/SKILL.md +112 -0
- package/skills/vault-remember/SKILL.md +38 -0
- package/skills/vault-rethink/README.md +15 -0
- package/skills/vault-rethink/SKILL.md +58 -0
- package/skills/vault-stats/SKILL.md +49 -0
- package/skills/vault-sync/README.md +15 -0
- package/skills/vault-sync/SKILL.md +195 -0
- package/skills/vault-sync/references/r4-method-evidence.md +12 -0
- package/skills/vault-update/SKILL.md +68 -0
- package/skills/vmem-status/SKILL.md +30 -0
- package/src/amem/host-api.ts +5 -1
- package/src/analysis-input.ts +15 -0
- package/src/analysis-types.ts +3 -1
- package/src/assertion-policy.ts +4 -2
- package/src/assertions.ts +48 -8
- package/src/cli-output.ts +10 -3
- package/src/cli.ts +29 -3
- package/src/commands-table.ts +3 -1
- package/src/config.ts +21 -7
- package/src/enrichment-query.ts +65 -0
- package/src/enrichment-search.ts +69 -0
- package/src/enrichment-store.ts +197 -0
- package/src/enrichment.ts +245 -0
- package/src/graph-evidence.ts +2 -2
- package/src/index.ts +9 -0
- package/src/mcp-vault.ts +46 -8
- package/src/proposal-provider.ts +3 -2
- package/src/proposals.ts +10 -4
- package/src/read-output.ts +1 -1
- package/src/registry.ts +57 -2
- package/src/setup.ts +12 -3
- package/src/skills-install.ts +216 -0
- package/src/ui/panel-types.ts +55 -0
- package/src/ui/panel.js +76 -0
- package/src/ui/plugin.ts +95 -5
- package/src/vault-graph.ts +15 -7
- package/src/vault-index.ts +17 -0
- package/src/vault-lint.ts +12 -4
- package/src/write-operations.ts +38 -1
- package/src/write-types.ts +1 -0
- package/src/write-validation.ts +2 -1
- package/src/writer.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.12.0] - 2026-11-22
|
|
6
|
+
|
|
7
|
+
- N-1: 0.11.0 shares the note and spec index files; 0.11.0 supports config format 4; format 5 adds default vault and graph options, and format 6 adds per-vault enrichment. Older readers preserve but ignore new keys in newer formats. The older CLI lacks settings and enrichment options; its MCP server lacks the enrichment tools and vector arguments. Older readers ignore local sidecars, may treat inferred links as extracted and do not expose assertion origin metadata; older writers refuse newly introduced `inferred_links` metadata and the `infer-link` proposal operation. Bundled skills and their setup and export commands are new in 0.12.0; 0.11.0 leaves those installed skill directories alone.
|
|
8
|
+
|
|
9
|
+
- Ship the 13 vmem skills and install or undo them with `vmem setup` for Claude, Codex, Kimi and Qwen. `vmem skills export` prepares self-contained directories for other hosts; ownership markers protect locally modified and foreign skills.
|
|
10
|
+
|
|
11
|
+
- Add opt-in, hash-bound offline enrichment intake, work and read tools, local Float32 embedding sidecars (128 MiB, 50,000 records), similar-note and hybrid search, and enabled-only vector lint. Inferred links are reviewed as proposals and tagged using unverified `inferred_links` frontmatter declarations; facts retain unverified producer metadata in the assertion journal. Sidecars are local to the home and excluded from vault Git sync; new embeddings, summaries and community labels replace older hashes for the same note.
|
|
12
|
+
|
|
13
|
+
- Preserve stacks for unexpected CLI load failures while keeping host API refusals concise.
|
|
14
|
+
- Add settings snapshots and fingerprint-bound settings changes for default vault, write mode, PII patterns and graph community resolution, through the console and CLI. Config format 5 preserves these keys when 0.10.x or 0.11.x reads and writes it; older versions ignore the new default and graph options. If an older version unregisters the default vault, the newer version falls back to its first personal vault (or first vault). The note index is unchanged, older CLI versions do not have `settings`, and MCP tool names and arguments are unchanged. Restart running MCP and console sessions after changing default vault or write mode.
|
|
15
|
+
- Console provider: Proposals (list, show, apply, reject), Assertions and History (note history and changes between two commits) panels, reusing the proposal provider, assertion reader and Git snapshot history through the MCP handlers. Apply and reject keep the preview, fingerprint and confirm flow. `@staix/vault-mem/ui-plugin` exports the `ProposalsSnapshot`, `AssertionsSnapshot` and `HistorySnapshot` types. Only the console provider gains panels and actions; a host loading an older plugin simply lacks them, and the acon plugin manifest must be re-registered with `vmem setup` after upgrading, as for any release.
|
|
16
|
+
|
|
5
17
|
## [0.11.0] - 2026-11-21
|
|
6
18
|
|
|
7
19
|
- N-1: 0.10.x pins agent-mem 0.32.0 while 0.11.0 accepts `>=0.33.0 <1.0.0` when its host API includes version 1. Both share the same vault index, configuration, CLI and MCP contracts; 0.11.0 status and doctor additionally report the loaded agent-mem version and host API. Neither release raises agent-mem format floors or changes placement writer attestation.
|
package/README.md
CHANGED
|
@@ -56,6 +56,18 @@ Output: every command prints text for people by default, following agent-hub's C
|
|
|
56
56
|
|
|
57
57
|
`vmem help <command>` prints one command's syntax; `vmem manifest --json` lists the commands and MCP tools for scripts. [docs/README.md](docs/README.md) says which document to open for which task.
|
|
58
58
|
|
|
59
|
+
`vmem settings <vault>` reads effective settings; `--set JSON` previews changes and `--confirm --fingerprint SHA` applies them. The console Settings panel uses the same preview and confirmation. Graph community resolution defaults to 1.
|
|
60
|
+
|
|
61
|
+
Enrichment is opt-in per vault through `vmem settings` or the Settings panel. A skill computes results outside vmem and uses `vmem_enrichment_work`, `vmem_enrichment_intake` and `vmem_enrichment_get` over MCP. An uncertain fact or link intake blocks replay until the journal or proposal is inspected and `vmem_enrichment_reconcile` confirms whether it was published. Results bind a source path and content hash to unverified producer metadata. Embeddings, summaries and community labels stay in a local sidecar under the vmem home; they are not synced. Embeddings are rounded to little-endian Float32. The sidecar is capped at 128 MiB and 50,000 records; 10,000 vectors of 1,536 dimensions fit with bounded metadata when the remaining capacity is not occupied by other records. Updating a record rewrites the sidecar, so large bulk intakes can be slow. Inferred links enter the existing proposal flow and the `inferred_links` frontmatter list is an unverified declaration. L19 warns when a listed target has no visible body link. Facts enter the assertion journal. `vmem_similar` uses stored vectors, and `vmem_search` accepts an optional model and vector for hybrid ranking; without stored vectors it keeps lexical ordering and scores while excluding currently denied paths. Only enabled vaults report missing or stale embeddings in lint.
|
|
62
|
+
|
|
63
|
+
## Skills
|
|
64
|
+
|
|
65
|
+
The package includes `vault-connect`, `vault-extract`, `vault-graph`, `vault-learn`, `vault-lint`, `vault-refactor`, `vault-remember`, `vault-rethink`, `vault-stats`, `vault-sync`, `vault-update`, `vmem-status` and `skill-mine`. They run with vmem alone; workspace-specific steps are optional.
|
|
66
|
+
|
|
67
|
+
`vmem setup claude|codex|kimi|qwen --apply` installs the skills alongside the MCP entry. `--undo` removes only unmodified vmem-owned skills. Pi, jcode and agy do not have an automatic skill root; use `vmem skills export <dir>` to prepare self-contained directories for another host.
|
|
68
|
+
|
|
69
|
+
Each installed directory has a `.vmem-skill.json` ownership marker with its package version and SHA-256 over its files, excluding the marker. Unexpected empty directories are treated as modifications. An absent skill is installed; an owned, unchanged skill can be replaced. Locally modified skills and foreign directories or symlinks are reported and left untouched. An existing export directory with unrelated entries is refused. Setup reports each result; a conflict does not prevent other requested changes.
|
|
70
|
+
|
|
59
71
|
## Not implemented
|
|
60
72
|
|
|
61
73
|
- Live cutover of an existing vault writer: outside this repository (see Status).
|
|
@@ -64,13 +76,12 @@ Output: every command prints text for people by default, following agent-hub's C
|
|
|
64
76
|
- Evidence verification of sources outside the same vault's `notes/` (other files, other vaults, URLs, memory ids): those entries are stored and reported `unverified_external` or `unsupported`, never fetched.
|
|
65
77
|
- Scheduled or automatic sync and push.
|
|
66
78
|
- Rewriting assertion bytes out of Git history, other clones or remotes: `vmem assertions purge` removes a payload from the journal in the working tree, and complete erasure needs a history rewrite outside vmem.
|
|
67
|
-
- A resolution setting for graph communities.
|
|
68
79
|
- An event-filtered capture read for skill mining.
|
|
69
80
|
- A console bin: vault-mem ships only the plugin module for the `acon` console of [agent-console](https://github.com/STAIxBWLB/agent-console).
|
|
70
81
|
|
|
71
82
|
## Library
|
|
72
83
|
|
|
73
|
-
The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
|
|
84
|
+
The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@staix/agent-mem@>=0.33.0 <1.0.0`<!-- /facts:amem-pin -->; host API 1 is checked at load before any agent-mem store opens. Registry commands do not load the agent-mem root. New compatible minors are resolved on installation or update; an existing installation keeps its resolved version. Public library exports (`@staix/vault-mem`, from `src/index.ts`) cover configuration and home resolution, registry operations, frontmatter, link resolution and the derived index, validated writes, the append-only log, the MCP server and its vault tools, host setup, the CLI command table and completion, promotion from agent-mem and to org vaults, lint and graph analysis, sync, source references, migration tidy, the temporal assertion journal and its evaluation, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry, with panels for proposals (list, show, apply, reject), assertions and note history and changes, and their snapshot types (see [Console plugin](docs/reference/mcp-and-setup.md#console-plugin)). No console bin is shipped. Exported functions and constants by module:
|
|
74
85
|
<!-- facts:exports -->
|
|
75
86
|
|
|
76
87
|
- `src/assertion-read.ts`: `readAssertions`, `ASSERTIONS_PAGE_LIMIT`
|
|
@@ -106,6 +117,10 @@ The only runtime dependency is the first-party range <!-- facts:amem-pin -->`@st
|
|
|
106
117
|
- `src/spec-graph.ts`: `buildSpecGraph`, `specSlice`, `SPEC_EDGE_KINDS`, `MAX_SPEC_INPUTS`, `MAX_SPEC_EDGES`
|
|
107
118
|
- `src/spec-validate.ts`: `validateSpecs`, `introducedSpecErrors`, `validateSpecRepo`
|
|
108
119
|
- `src/spec-freshness.ts`: `specFreshness`, `specsCoveringPath`
|
|
120
|
+
- `src/registry.ts`: `settingsSnapshot`, `changeSettings`
|
|
121
|
+
- `src/ui/plugin.ts`: `plugin as consolePlugin`
|
|
122
|
+
- `src/enrichment.ts`: `listEnrichmentWork`, `intakeEnrichment`, `readEnrichment`, `reconcileEnrichment`
|
|
123
|
+
- `src/enrichment-query.ts`: `hybridSearch`, `similarNotes`
|
|
109
124
|
|
|
110
125
|
<!-- /facts:exports -->
|
|
111
126
|
|
package/bin/vmem.js
CHANGED
|
@@ -6,7 +6,11 @@ if (!version || Number(version[1]) < 1 || (Number(version[1]) === 1 && (Number(v
|
|
|
6
6
|
}
|
|
7
7
|
let cli;
|
|
8
8
|
try { cli = await import("../src/cli.ts"); }
|
|
9
|
-
catch (error) {
|
|
9
|
+
catch (error) {
|
|
10
|
+
if (error instanceof Error && error.code === "VMEM_HOST_API_INCOMPATIBLE") console.error(`vmem: ${error.message}`);
|
|
11
|
+
else console.error(error);
|
|
12
|
+
process.exit(1);
|
|
13
|
+
}
|
|
10
14
|
const { main, mainAsync, reportError, runMcp } = cli;
|
|
11
15
|
const { resolveColor, takeColorFlag } = await import("../src/text-output.ts");
|
|
12
16
|
const argv = process.argv.slice(2);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@staix/vault-mem",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Validated Obsidian-compatible knowledge vaults for agents and people",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -29,6 +29,7 @@
|
|
|
29
29
|
"files": [
|
|
30
30
|
"src/",
|
|
31
31
|
"bin/",
|
|
32
|
+
"skills/",
|
|
32
33
|
"README.md",
|
|
33
34
|
"CHANGELOG.md",
|
|
34
35
|
"LICENSE"
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault_adapter
|
|
3
|
+
description: Vault access rules for public vault-facing skills. Shared runtime, vault access, logging and schema guidance for vmem skills.
|
|
4
|
+
type: spec
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Vault Adapter Rules
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
This spec is the shared access contract for vault-facing skills. It is a policy document, not a Python module.
|
|
12
|
+
|
|
13
|
+
## Runtime Discovery
|
|
14
|
+
|
|
15
|
+
At the start of a vault-facing workflow:
|
|
16
|
+
|
|
17
|
+
1. Prefer connected vmem MCP tools. If they are unavailable but the CLI is installed, use documented CLI equivalents where available; for MCP tools without a CLI equivalent start `vmem mcp` as a stdio subprocess. Use newline-delimited JSON-RPC: send `initialize` with `protocolVersion: "2025-06-18"`, `capabilities: {}` and `clientInfo: {name: "skill-client", version: "1"}`; read its response, send `notifications/initialized`, then use `tools/list` and `tools/call` with `params: {name, arguments}`. Read each response and its full tool receipt before continuing; close the subprocess when done. Stdout is protocol only, stderr is diagnostic. Respect the registered vault's write policy; a refusal is not permission to bypass it.
|
|
18
|
+
2. Discover registered vaults using `vmem_status` when MCP is available, or `vmem vaults list --json` using the CLI. If a workspace config is present, discover it by walking up from the current directory and match its `vault.path` to the canonical registered path. Otherwise use the user's explicitly selected vault, or the sole registered vault. If selection is ambiguous or no vault matches, ask the user; never rely on an implicit first-vault fallback.
|
|
19
|
+
3. Pass the selected id as `vault` on every vmem tool call and as `<vault>` on CLI calls. When workspace configuration exists, read the relevant `vault.log_file` and `ssot.*` keys only for workspace-dependent steps. If a required workspace or key is absent, skip that step and report it; do not invent a path.
|
|
20
|
+
4. When a skill states a minimum version, check `vmem --version` if the CLI is available, or the MCP initialize response's `serverInfo.version` if exposed by the host. If an available version is below the minimum, stop and report the required upgrade. If the MCP host does not expose the version, report it as unknown and use the tool availability and receipts; do not require a CLI solely for the version check.
|
|
21
|
+
|
|
22
|
+
## Access Rules
|
|
23
|
+
|
|
24
|
+
### Vault Markdown
|
|
25
|
+
|
|
26
|
+
All vault writes go through vmem, which validates before it saves (schema, enums, MOC topics, links, secrets, PII):
|
|
27
|
+
|
|
28
|
+
- `notes/*.md`: the vmem write tools below, using the selected transport.
|
|
29
|
+
- `ops/` and `reports/` files: `vmem_report(path, body)`, the MCP form of the CLI `vmem report <vault> <ops/...|reports/...> --body -` (same path rules, screening, receipt and default `EXTRACT` line).
|
|
30
|
+
- Root docs (`AGENTS.md` and similar) are not agent-writable; change them only on the user's explicit maintenance instruction.
|
|
31
|
+
|
|
32
|
+
Reads: `notes/` through `vmem_read` / `vmem_read_many` / `vmem_search` / `vmem_list`. `ops/`, `reports/`, `self/`, `templates/` and root docs through `vmem_read_file` / `vmem_list_files` (bounded, paged like `vmem_read`); read-only filesystem access also works. Do not use filesystem write/edit, shell redirection or another MCP server for any vault file.
|
|
33
|
+
|
|
34
|
+
### Write results
|
|
35
|
+
|
|
36
|
+
Read the whole receipt, never one field. `ok: true` with `applied: true` saved its changes. A write that persisted changes and then failed returns `ok: false` with `applied: true` — that is the one partial-write signal, for direct note writes since vmem 0.6.0 and for `vmem_promote` / `vmem_promote_from_amem` since 0.7.0. In that case stop, report the receipt, reconcile the note and log, and never retry blindly. `ok: false` with `applied: false` wrote nothing, so its issues are the whole result. Always check `changes` and `logged` too: a saved note whose log line failed is `applied: true, logged: false`, which is a warning, not a rollback.
|
|
37
|
+
|
|
38
|
+
Skills link to this section (§Write results) instead of restating the rule.
|
|
39
|
+
|
|
40
|
+
Declared exceptions (machine I/O, not agent writes):
|
|
41
|
+
|
|
42
|
+
| Path | Writer / reader | Why |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| `ops/sessions/last-sync-timestamp` | fs read/write by vault-sync | plain file, not a note |
|
|
45
|
+
|
|
46
|
+
Typical mappings:
|
|
47
|
+
|
|
48
|
+
| Operation | vmem tool |
|
|
49
|
+
|---|---|
|
|
50
|
+
| Read note / several notes | `vmem_read` (frontmatter, body, sha256), `vmem_read_many` (<=20) |
|
|
51
|
+
| Search / list | `vmem_search`, `vmem_list` (page with the returned `nextCursor` as `cursor`) |
|
|
52
|
+
| Read / list non-note files | `vmem_read_file`, `vmem_list_files` |
|
|
53
|
+
| Links / neighbourhood | `vmem_links` (out, in or both, each dead link with at most one `suggested` target), `vmem_graph_neighbors` (`hops` 1–2, `limit` 1–500, `relation`; each node carries `community` and `degree`), `vmem_graph_path` (`from`/`to` stems, `maxHops` 1–6 default 6, `relation`, `viaHubs`; `found: false` when no route within `maxHops`). Neighbour, path or community questions never read `reports/vault-graph.json` or the graph report |
|
|
54
|
+
| Create note | `vmem_create` |
|
|
55
|
+
| Edit body | `vmem_patch` (exact old/new text, or `edits` for up to 32 at once), `vmem_append` (into an H2 section) |
|
|
56
|
+
| Edit frontmatter or tags | `vmem_set_frontmatter` |
|
|
57
|
+
| Typed relation link | `vmem_link` |
|
|
58
|
+
| Supersede | `vmem_supersede` |
|
|
59
|
+
| Merge two notes | `vmem_merge`: call once for the merged body, source/topic unions, inbound rewrites and `fingerprint`, then again with `confirm: true`, that fingerprint and `log` |
|
|
60
|
+
| Intent-scoped pointers | `vmem_brief` (`intent` <=1024 bytes, optional `paths` as extra basename word hints — not a citation filter — and `bytes` 256–4096; screened pointer lines without bodies, one-hop rows marked `[neighbor]`) |
|
|
61
|
+
| Promote an agent-mem entry | `vmem_promote_from_amem`: two-step like `vmem_move`; its confirm logs `LEARN` itself and takes no `log` |
|
|
62
|
+
| Recent log events | `vmem_log_tail` (read-only) |
|
|
63
|
+
| Move / delete | `vmem_move`, `vmem_delete`: call once for `{preview, fingerprint}`, then again with `confirm: true` and that fingerprint |
|
|
64
|
+
| MOCs / stats | `vmem_mocs`, `vmem_stats` (counts by type, domain and status, `size` bytes and words by type and domain, note-to-source `ratio`, recent edits, log events), `vmem_status` |
|
|
65
|
+
| `ops/` / `reports/` file | `vmem_report` |
|
|
66
|
+
| Lint / graph reports | `vmem_lint` (`write: true` saves `reports/lint-report-YYMMDD.md`; it takes no note argument), `vmem_graph_build` |
|
|
67
|
+
| Dry validation | `vmem_check` (prospective note text, no write; run it before `vmem_create` so a refusal costs no write) |
|
|
68
|
+
|
|
69
|
+
Pass `expectedSha` (from `vmem_read`) on edits that must not race another writer. Every successful write changes the note's sha256, so re-read before the next `expectedSha` edit of the same note.
|
|
70
|
+
|
|
71
|
+
### Workspace SSOT
|
|
72
|
+
|
|
73
|
+
Workspace-local operational files are not vault markdown. They may be read or edited through normal filesystem tools:
|
|
74
|
+
|
|
75
|
+
- `workspace.config.yaml`
|
|
76
|
+
- `project-registry.yaml`
|
|
77
|
+
- files under the workspace rules directory
|
|
78
|
+
- skill source files in this repo
|
|
79
|
+
|
|
80
|
+
## Log Append
|
|
81
|
+
|
|
82
|
+
vmem owns the vault log (`vault.log_file`). Every vmem write appends one attributed line itself:
|
|
83
|
+
|
|
84
|
+
- Every write tool (`vmem_create`, `vmem_patch`, `vmem_append`, `vmem_set_frontmatter`, `vmem_link`, `vmem_supersede`, `vmem_merge`, `vmem_report`, and `vmem_move` / `vmem_delete` on the confirm call) accepts an optional `log` argument (`{type, project, source, dest?, note}`) that sets that line's TYPE, project and note. vmem refuses the whole write when the event is invalid. `vmem_promote_from_amem` is the exception: its confirm logs `LEARN` itself and takes no `log`.
|
|
85
|
+
- Without `log`, a write records vmem's default for that operation: `vmem_link` records `CONNECT`, `vmem_move` records `ROUTE`, `vmem_merge` / `vmem_supersede` record `RETHINK`, every other write records `EXTRACT` (`… - vmem:<op> → path`); `vmem_lint(write: true)` and `vmem_graph_build` record `LINT` / `GRAPH`.
|
|
86
|
+
- When a workflow's contract needs a TYPE (for example a LEARN line for an update), pass it as `log` on that write. Use `vmem_log_append` only for an event with no write (a failure, a batch summary, a promoted TASK).
|
|
87
|
+
|
|
88
|
+
Do not append to the log with `>>` or any other filesystem write.
|
|
89
|
+
|
|
90
|
+
### Log failure handling
|
|
91
|
+
|
|
92
|
+
Read the whole receipt per §Write results. The one rule this section adds: on `ok: false, applied: false`, record a `failed: <reason or issue codes>` line with `vmem_log_append` under the workflow's TYPE and report the issues.
|
|
93
|
+
|
|
94
|
+
```text
|
|
95
|
+
YYYY-MM-DD HH:MM TYPE project source → dest — note
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Each field is two spaces apart; `project` is a registry id or `-` when unclassified, and `dest` uses `notes/<x>.md`. For `source`, use the real workspace-relative source path when available, otherwise a valid source URL or `mem:` id; if none is available use `-` and report missing provenance. Do not invent a workspace path. The log field must be nonempty, at most 512 characters, without control characters, `|`, double spaces, ` → ` or ` — `; vmem also screens it and limits the whole line to 1000 UTF-8 bytes. If the real reference cannot satisfy those rules, report the refusal and ask for a valid reference rather than silently changing it.
|
|
99
|
+
|
|
100
|
+
When available, consult the workspace `ssot.ingest_chain` normalization table. `TYPE` is validated by vmem: the canonical set is `INGEST ROUTE EXTRACT CONNECT DIGEST LEARN LINT TASK GRAPH SYNC RETHINK SOURCE`; historical non-standard TYPEs are interpreted via that rule's normalization table and must not be written anew (a split or MOC refactor logs as `EXTRACT`, while vmem records a rename as `ROUTE` and a merge as `RETHINK` on its own). vmem refuses a TYPE outside the set.
|
|
101
|
+
|
|
102
|
+
## Summary To Vault Fields
|
|
103
|
+
|
|
104
|
+
When promoting a source summary into a vault note, copy source-derived fields instead of regenerating them:
|
|
105
|
+
|
|
106
|
+
| Vault note field | Source summary field | Rule |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `description` | `description` | Required, non-empty, concise |
|
|
109
|
+
| `domain` | `domain` | Required, workspace-defined domain enum |
|
|
110
|
+
| `topics` | `topics` | Required, at least one wiki link, **and every `[[target]]` must already exist as a MOC note in vault** (MOC = note where `type: moc` or a domain hub like `projects.md`, `research.md`, `operations.md`, `teaching.md`, `people.md`, `ai-practice.md`). |
|
|
111
|
+
| `source` | `source` | Preserve source identity |
|
|
112
|
+
| `project` | `project` | Map via project registry when available |
|
|
113
|
+
|
|
114
|
+
If required fields are missing, fail before writing. Do not synthesize blank or guessed values. expect: vmem refuses a missing `description`, `type` or `domain`, an enum value outside the vocabulary, and a `topics` entry that is not an existing MOC.
|
|
115
|
+
|
|
116
|
+
**MOC enforcement on `topics`**: `topics` carries hub navigation only. Concept/keyword tags (e.g., `credit-recognition`, `partnership-mapping`, `duty-model`) belong in body text, not in `topics`. vmem refuses a `topics` entry that does not resolve to an existing MOC. If a needed MOC does not exist, ABORT: a MOC is created separately with a `vmem_create type: moc` call on the user's instruction, never implicitly by an extract. Never silently copy unknown wiki-links from summary.md into vault notes.
|
|
117
|
+
|
|
118
|
+
## Project Registry Pattern
|
|
119
|
+
|
|
120
|
+
1. When a workspace and its registry are available, load `ssot.project_registry` from `workspace.config.yaml`. Otherwise skip registry classification, report the skipped step, and use content-based domain analysis or an unclassified project (`-`); ask if the result remains ambiguous.
|
|
121
|
+
2. Consider `status: active` entries only. Extract signals from the source (people, acronyms, keywords, orgs, tags).
|
|
122
|
+
3. Score with the workspace weights; the default is people +3, acronyms +2, keywords +2, orgs +1, tags +1, with a match threshold of 3. A workspace scoring rule under `ssot.registry_scoring` overrides these defaults.
|
|
123
|
+
4. A single top score at or above the threshold is the match: use its `path` to validate the source. Resolve its `vault_note` in the bound vault. Add it to `topics` only if `vmem_mocs` confirms it is a MOC; for an ordinary note, keep it as a project/body link and use its validated MOC topics or a relevant existing domain MOC. Apply §Summary To Vault Fields before writing; a missing MOC is unresolved, never auto-created.
|
|
124
|
+
5. Tie or ambiguity: use the registry disambiguation fields, then ask the user.
|
|
125
|
+
6. Below the threshold (registry fallback): fall back to content-based domain analysis; if still ambiguous, ask the user, or record the source as unclassified (`project: -`) when the calling workflow allows it.
|
|
126
|
+
|
|
127
|
+
## Boundary
|
|
128
|
+
|
|
129
|
+
- Work files: filesystem tools.
|
|
130
|
+
- Vault markdown: vmem tools or documented CLI equivalents only; never write directly to the filesystem.
|
|
131
|
+
- Cloud mirrors or synced copies: do not edit directly from vault skills.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: skill-mine
|
|
3
|
+
description: >
|
|
4
|
+
여러 세션에 걸쳐 반복되는 업무를 찾아 새 스킬 후보로 뽑을 때
|
|
5
|
+
(스킬 채굴, skill mine, 반복 패턴 감지, /skill-mine): amem 기억(curated·capture)과
|
|
6
|
+
vault 노트를 `vmem skills mine`으로 사전 매칭·Leiden 커뮤니티·novelty 점수로 묶어
|
|
7
|
+
순위를 매긴 스킬 후보 마크다운 리포트를 만든다. LLM·API 호출 없이 로컬·결정론적으로 동작.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# skill-mine: 기억 기반 스킬 후보 채굴 (LLM-free)
|
|
11
|
+
|
|
12
|
+
> Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as the `<vault>` argument of the `vmem` CLI command (or `vault` on `vmem_skills_mine`).
|
|
13
|
+
>
|
|
14
|
+
> This skill requires vmem >= 0.8.0. Check the version as described in the adapter; if the MCP host does not expose it, report it as unknown and check tool availability.
|
|
15
|
+
|
|
16
|
+
## 언제 사용
|
|
17
|
+
|
|
18
|
+
- "자주 반복되는 업무를 스킬로 뽑아달라", "스킬 채굴", "반복 패턴 감지" 요청
|
|
19
|
+
- 주기 점검(주 1회 권장)으로 누락된 스킬 후보를 찾을 때
|
|
20
|
+
- 대상은 세션 1건이 아니라 여러 세션·프로젝트에 걸친 반복 패턴
|
|
21
|
+
|
|
22
|
+
## 실행
|
|
23
|
+
|
|
24
|
+
설치된 skill 디렉토리의 `vocab/`와 비교할 호스트 skill 디렉토리를 사용한다:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
vmem skills mine <vault> --days 30 \
|
|
28
|
+
--vocab <installed skill directory>/vocab \
|
|
29
|
+
--skills <host skill directory>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- MCP만 있으면 `vmem_skills_mine`에 `vault`, `days`, `vocab`, `skills`를 전달한다. amem 데이터가 없으면 이용 가능한 vault 노트로 실행하고 누락된 입력을 보고한다.
|
|
33
|
+
- 입력: amem curated(decision·finding·contract·fail), amem capture(사용자 프롬프트·observation·summary), vault 노트(person·moc·reference 제외). 기간은 `--days`(기본 30), 프로젝트는 기본 전체이고 `--project <key>`로 좁힌다.
|
|
34
|
+
- 표준출력이 리포트 본문(markdown)이다. `--json`은 후보·점수·출처별 건수를 구조화해 돌려준다. MCP에서는 `vmem_skills_mine`.
|
|
35
|
+
- workspace가 있으면 리포트를 `<workspace-root>/_meta/reports/skill-candidates-YYMMDD.md`로 저장한다. 없으면 사용자에게 결과를 보여주고 workspace 저장을 건너뛰었다고 보고한다. 같은 날 재실행은 덮어쓴다.
|
|
36
|
+
- `--skills`는 novelty 비교용 기존 스킬 카탈로그다. 사용 가능한 호스트 스킬 설치 디렉토리를 반복해서 넘긴다.
|
|
37
|
+
- 임계치 조정: `--min-size N`(기본 3), `--min-novelty X`(기본 0.3).
|
|
38
|
+
- expect: vmem refuses an unknown option, a missing `--vocab` file and, through MCP, a vault re-registered after the server started. 명령은 vault·vmem home·amem home에 아무것도 쓰지 않는다.
|
|
39
|
+
|
|
40
|
+
## 결과 해석
|
|
41
|
+
|
|
42
|
+
- **Candidates**: 커뮤니티 하나 = 한 업무 패턴. `rank`가 높을수록 재사용 가치가 크다. `novelty > 0.7`이면 신규 스킬 후보, `0.3~0.7`이면 기존 스킬 확장 여지(overlap 목록 확인), `cohesion > 0.3`이면 패턴이 뚜렷하다. `sources`는 curated·capture·vault 출처별 건수다.
|
|
43
|
+
- **God nodes**: 전체에서 가장 많이 연결된 어휘. 최근 업무의 공통 어휘를 보여준다.
|
|
44
|
+
- **Surprising connections**: 커뮤니티 경계를 넘는 어휘 쌍. 교차 영역 스킬 아이디어의 단서.
|
|
45
|
+
- **Rejected**: 크기·novelty 미달 클러스터(관찰용).
|
|
46
|
+
- samples는 마스킹되어 있다(registry 인물 `[PERSON]`, 이메일 `[EMAIL]`, 절대경로 `[PATH]`, vault `piiPatterns` `[PII]`). 리포트를 외부로 내보내기 전에 한 번 더 확인한다.
|
|
47
|
+
|
|
48
|
+
## 후속 작업
|
|
49
|
+
|
|
50
|
+
1. **승격**: 적합한 후보 1건을 골라 SKILL.md를 쓰고 스킬 소스 repo에 issue·PR로 추가한다(런타임 설치본 직접 수정 금지).
|
|
51
|
+
2. **확장**: 기존 스킬과 overlap이 높으면 그 스킬의 description·트리거에 새 표현을 더한다.
|
|
52
|
+
3. **사전 보강**: god nodes에 기대한 어휘가 없으면 `vocab/actions.yaml`·`vocab/objects.yaml`에 표제어를 추가한다.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Action vocabulary — Korean + English verb surface forms mapped to canonical action keys.
|
|
2
|
+
# Used by materialize.py to create [[action:<canon>]] wiki-links when a prompt mentions any surface form.
|
|
3
|
+
#
|
|
4
|
+
# Schema:
|
|
5
|
+
# actions:
|
|
6
|
+
# - canon: <canonical_action_id> # kebab-case English
|
|
7
|
+
# surface: [<ko1>, <ko2>, <en1>, ...] # literal tokens to match (case-insensitive for en, exact for ko)
|
|
8
|
+
|
|
9
|
+
actions:
|
|
10
|
+
- canon: organize
|
|
11
|
+
surface: [정리, 정리하라, 정리해, 정리해줘, 정돈, organize, cleanup, tidy]
|
|
12
|
+
|
|
13
|
+
- canon: extract
|
|
14
|
+
surface: [추출, 추출하라, 뽑아, 뽑아라, 뽑아줘, extract, pull, scrape]
|
|
15
|
+
|
|
16
|
+
- canon: classify
|
|
17
|
+
surface: [분류, 분류하라, 분류해, 라우팅, categorize, classify, route]
|
|
18
|
+
|
|
19
|
+
- canon: sync
|
|
20
|
+
surface: [동기화, 싱크, 동기, sync, synchronize]
|
|
21
|
+
|
|
22
|
+
- canon: summarize
|
|
23
|
+
surface: [요약, 요약하라, 요약해, 요약해줘, summarize, summarise, summary]
|
|
24
|
+
|
|
25
|
+
- canon: create
|
|
26
|
+
surface: [생성, 생성하라, 작성, 작성하라, 만들어, 만들어라, 만들라, create, generate, write, draft]
|
|
27
|
+
|
|
28
|
+
- canon: send
|
|
29
|
+
surface: [전송, 발송, 보내, 보내라, 보내줘, send, dispatch]
|
|
30
|
+
|
|
31
|
+
- canon: search
|
|
32
|
+
surface: [검색, 검색하라, 찾아, 찾아라, 찾아줘, search, find, lookup]
|
|
33
|
+
|
|
34
|
+
- canon: edit
|
|
35
|
+
surface: [편집, 수정, 수정하라, 변경, 바꿔, 바꿔라, edit, modify, update, change, rewrite]
|
|
36
|
+
|
|
37
|
+
- canon: delete
|
|
38
|
+
surface: [삭제, 삭제하라, 제거, 지워, 지워라, remove, delete, drop]
|
|
39
|
+
|
|
40
|
+
- canon: execute
|
|
41
|
+
surface: [실행, 실행하라, 돌려, 돌려라, 돌려줘, run, execute, invoke]
|
|
42
|
+
|
|
43
|
+
- canon: verify
|
|
44
|
+
surface: [확인, 확인하라, 검증, 검증하라, 점검, verify, check, validate]
|
|
45
|
+
|
|
46
|
+
- canon: explain
|
|
47
|
+
surface: [설명, 설명하라, 설명해, 설명해줘, explain, describe]
|
|
48
|
+
|
|
49
|
+
- canon: review
|
|
50
|
+
surface: [리뷰, 검토, 검토하라, review, audit]
|
|
51
|
+
|
|
52
|
+
- canon: commit
|
|
53
|
+
surface: [커밋, commit, git-commit]
|
|
54
|
+
|
|
55
|
+
- canon: push
|
|
56
|
+
surface: [푸시, push]
|
|
57
|
+
|
|
58
|
+
- canon: pull
|
|
59
|
+
surface: [풀, pull, fetch]
|
|
60
|
+
|
|
61
|
+
- canon: merge
|
|
62
|
+
surface: [병합, 머지, merge]
|
|
63
|
+
|
|
64
|
+
- canon: install
|
|
65
|
+
surface: [설치, 설치하라, install, setup]
|
|
66
|
+
|
|
67
|
+
- canon: migrate
|
|
68
|
+
surface: [이관, 마이그레이션, migrate, migration]
|
|
69
|
+
|
|
70
|
+
- canon: rename
|
|
71
|
+
surface: [이름변경, 이름 바꿔, 리네임, rename]
|
|
72
|
+
|
|
73
|
+
- canon: move
|
|
74
|
+
surface: [이동, 옮겨, 옮겨라, move, relocate]
|
|
75
|
+
|
|
76
|
+
- canon: copy
|
|
77
|
+
surface: [복사, copy, duplicate]
|
|
78
|
+
|
|
79
|
+
- canon: translate
|
|
80
|
+
surface: [번역, 번역하라, translate]
|
|
81
|
+
|
|
82
|
+
- canon: convert
|
|
83
|
+
surface: [변환, 전환, convert, transform]
|
|
84
|
+
|
|
85
|
+
- canon: register
|
|
86
|
+
surface: [등록, 등록하라, register, enroll]
|
|
87
|
+
|
|
88
|
+
- canon: schedule
|
|
89
|
+
surface: [예약, 예약하라, 스케줄, schedule]
|
|
90
|
+
|
|
91
|
+
- canon: report
|
|
92
|
+
surface: [보고, 보고하라, 리포트, report]
|
|
93
|
+
|
|
94
|
+
- canon: analyze
|
|
95
|
+
surface: [분석, 분석하라, analyze, analyse, inspect]
|
|
96
|
+
|
|
97
|
+
- canon: plan
|
|
98
|
+
surface: [계획, 계획하라, 기획, plan, design]
|
|
99
|
+
|
|
100
|
+
- canon: refactor
|
|
101
|
+
surface: [리팩토링, 리팩터링, refactor, cleanup-code]
|
|
102
|
+
|
|
103
|
+
- canon: test
|
|
104
|
+
surface: [테스트, 테스트하라, test, validate]
|
|
105
|
+
|
|
106
|
+
- canon: deploy
|
|
107
|
+
surface: [배포, deploy, release, ship]
|
|
108
|
+
|
|
109
|
+
- canon: fix
|
|
110
|
+
surface: [수정, 고쳐, 고쳐라, 픽스, fix, patch, repair]
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Object vocabulary — Korean + English noun surface forms mapped to canonical object keys.
|
|
2
|
+
# Used by materialize.py to create [[object:<canon>]] wiki-links.
|
|
3
|
+
|
|
4
|
+
objects:
|
|
5
|
+
- canon: inbox
|
|
6
|
+
surface: [inbox, 수신함, incoming, downloads]
|
|
7
|
+
|
|
8
|
+
- canon: meeting-notes
|
|
9
|
+
surface: [회의록, 미팅노트, meeting, meetings, meeting-notes]
|
|
10
|
+
|
|
11
|
+
- canon: task
|
|
12
|
+
surface: [태스크, 할일, todo, tasks, task]
|
|
13
|
+
|
|
14
|
+
- canon: email
|
|
15
|
+
surface: [이메일, 메일, email, gmail, outlook]
|
|
16
|
+
|
|
17
|
+
- canon: document
|
|
18
|
+
surface: [문서, 보고서, 자료, document, doc, docs, report]
|
|
19
|
+
|
|
20
|
+
- canon: skill
|
|
21
|
+
surface: [스킬, skill, skills, SKILL]
|
|
22
|
+
|
|
23
|
+
- canon: commit
|
|
24
|
+
surface: [커밋, commit, git-commit]
|
|
25
|
+
|
|
26
|
+
- canon: prompt
|
|
27
|
+
surface: [프롬프트, prompt, prompts]
|
|
28
|
+
|
|
29
|
+
- canon: vault
|
|
30
|
+
surface: [vault, 볼트, 노트, note, notes]
|
|
31
|
+
|
|
32
|
+
- canon: schedule
|
|
33
|
+
surface: [일정, 캘린더, calendar, schedule, event]
|
|
34
|
+
|
|
35
|
+
- canon: kakao
|
|
36
|
+
surface: [카톡, 카카오톡, kakao, kakaotalk]
|
|
37
|
+
|
|
38
|
+
- canon: telegram
|
|
39
|
+
surface: [텔레그램, telegram]
|
|
40
|
+
|
|
41
|
+
- canon: slide
|
|
42
|
+
surface: [슬라이드, 발표자료, 프레젠테이션, slide, slides, presentation, pptx]
|
|
43
|
+
|
|
44
|
+
- canon: spreadsheet
|
|
45
|
+
surface: [엑셀, 스프레드시트, excel, xlsx, spreadsheet]
|
|
46
|
+
|
|
47
|
+
- canon: pdf
|
|
48
|
+
surface: [pdf, PDF]
|
|
49
|
+
|
|
50
|
+
- canon: hwp
|
|
51
|
+
surface: [hwp, HWP, hwpx, HWPX, 한글]
|
|
52
|
+
|
|
53
|
+
- canon: word
|
|
54
|
+
surface: [word, docx, DOCX, 워드]
|
|
55
|
+
|
|
56
|
+
- canon: website
|
|
57
|
+
surface: [웹사이트, 홈페이지, website, site, web]
|
|
58
|
+
|
|
59
|
+
- canon: blog-post
|
|
60
|
+
surface: [블로그, blog, post]
|
|
61
|
+
|
|
62
|
+
- canon: linkedin-post
|
|
63
|
+
surface: [linkedin, 링크드인]
|
|
64
|
+
|
|
65
|
+
- canon: proposal
|
|
66
|
+
surface: [제안서, 사업계획서, 사업계획, 지원서, proposal, application]
|
|
67
|
+
|
|
68
|
+
- canon: plan
|
|
69
|
+
surface: [계획서, 기획서, plan]
|
|
70
|
+
|
|
71
|
+
- canon: course
|
|
72
|
+
surface: [수업, 강의, 강의자료, course, lesson, class]
|
|
73
|
+
|
|
74
|
+
- canon: student
|
|
75
|
+
surface: [학생, 수강생, student, students, cohort]
|
|
76
|
+
|
|
77
|
+
- canon: cv
|
|
78
|
+
surface: [cv, CV, 이력서, 약력, bio, resume]
|
|
79
|
+
|
|
80
|
+
- canon: repo
|
|
81
|
+
surface: [레포, repo, repository, 저장소]
|
|
82
|
+
|
|
83
|
+
- canon: branch
|
|
84
|
+
surface: [브랜치, branch]
|
|
85
|
+
|
|
86
|
+
- canon: submodule
|
|
87
|
+
surface: [서브모듈, submodule]
|
|
88
|
+
|
|
89
|
+
- canon: config
|
|
90
|
+
surface: [설정, config, settings, configuration]
|
|
91
|
+
|
|
92
|
+
- canon: script
|
|
93
|
+
surface: [스크립트, script]
|
|
94
|
+
|
|
95
|
+
- canon: hook
|
|
96
|
+
surface: [훅, hook, hooks]
|
|
97
|
+
|
|
98
|
+
- canon: log
|
|
99
|
+
surface: [로그, log, logs]
|
|
100
|
+
|
|
101
|
+
- canon: chart
|
|
102
|
+
surface: [차트, 그래프, chart, graph, plot]
|
|
103
|
+
|
|
104
|
+
- canon: diagram
|
|
105
|
+
surface: [다이어그램, diagram]
|
|
106
|
+
|
|
107
|
+
- canon: seo
|
|
108
|
+
surface: [seo, SEO]
|
|
109
|
+
|
|
110
|
+
- canon: test
|
|
111
|
+
surface: [테스트, 시험, test, exam]
|
|
112
|
+
|
|
113
|
+
- canon: dataset
|
|
114
|
+
surface: [데이터셋, 데이터, dataset, data]
|
|
115
|
+
|
|
116
|
+
- canon: image
|
|
117
|
+
surface: [이미지, 사진, image, img, photo]
|
|
118
|
+
|
|
119
|
+
- canon: audio
|
|
120
|
+
surface: [오디오, 음성, audio, voice]
|
|
121
|
+
|
|
122
|
+
- canon: video
|
|
123
|
+
surface: [비디오, 영상, video]
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vault-connect
|
|
3
|
+
trigger: /vault-connect
|
|
4
|
+
description: Find and create wiki link connections between vault notes
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# /vault-connect [note]
|
|
8
|
+
|
|
9
|
+
> Before the first vmem call, read `references/vault-adapter.md` §Runtime Discovery and select and bind the vmem vault id; pass it as `vault` on every vmem tool call and as the `<vault>` argument of every `vmem` CLI command.
|
|
10
|
+
|
|
11
|
+
Find relationships between a note and existing vault notes, create wiki links.
|
|
12
|
+
|
|
13
|
+
## Input
|
|
14
|
+
- note: filename or path of a note in vault/notes/
|
|
15
|
+
- entities_hint (optional): list of 인물/기관 names from source summary.md — used as wiki-link candidate seeds in step 2 first pass
|
|
16
|
+
|
|
17
|
+
## Process
|
|
18
|
+
|
|
19
|
+
0. **Candidate pre-fetch through vmem** (never a graph-report or `vault-graph.json` read):
|
|
20
|
+
a. `vmem_brief(intent: "<target note title> <description>", bytes: 2048)` returns screened pointer lines `notes/<path> | title | type | description` — no note bodies — with one-hop rows marked `[neighbor]`, so this is the cheap first pass.
|
|
21
|
+
b. `vmem_graph_neighbors(path: "<stem>", hops: 1)` returns the note's community and its one-hop neighbours (each node carries `community` and `degree`, so rank by degree); widen with `hops: 2` or narrow with `relation` (`wiki_link` or one typed relation). expect: vmem refuses `hops` outside 1–2, a `limit` outside 1–500, an unknown `relation` and an unknown note.
|
|
22
|
+
c. Obsidian Smart Connections 플러그인이 활성 상태면 대상 노트의 semantic neighbors 상위 5개를 추가 연결 후보로 포함 (키워드 매칭으로 놓치는 cross-domain 연결 보완)
|
|
23
|
+
d. 위 후보를 Step 2의 검색 결과와 병합 (중복 제거)
|
|
24
|
+
1. Read the target note completely (`vmem_read`); `vmem_links(path, direction: "in", limit: 200)` lists its in-links, and each in-link that lacks a back-link is a link candidate for step 3. A full page of 200 may be cut off: then report this page's back-link check as incomplete.
|
|
25
|
+
2. Search vault/notes/ for related notes by:
|
|
26
|
+
- **entities_hint first pass** (if provided): for each entity name, run `vmem_brief(intent: "<entity>", bytes: 1024)` and confirm a hit with `vmem_search`; its pointers already cover `glossary`, `people` and note titles, so no manual grep of those notes. These are highest-priority link candidates since they're pre-identified by summaries or source metadata.
|
|
27
|
+
- **Backref seeds** (if present in target frontmatter): `relatedMeetings`, `relatedTasks`, `source_doc` / `meetingSourcePath` are pre-identified origins — treat their resolved `[[targets]]` as high-priority bidirectional link candidates.
|
|
28
|
+
- Title keyword matching
|
|
29
|
+
- Description similarity
|
|
30
|
+
- Shared topics/MOCs
|
|
31
|
+
- Same domain or cross-domain relevance
|
|
32
|
+
- Project affinity via registry: if source is from work/, classify it per `references/vault-adapter.md` §Project Registry Pattern (scoring and fallback), then prioritize sibling notes sharing the same `vault_note` topic as connection candidates
|
|
33
|
+
3. For each discovered relationship:
|
|
34
|
+
- Determine relationship type (supports, contradicts, extends, applies-to, context-for)
|
|
35
|
+
- **Existing short path**: when the proposed link joins two notes that already sit close together, read `vmem_graph_path(from: "<x>", to: "<y>", maxHops: 3)` and show the hops beside the proposal (`x -[supports]-> m -[context-for]-> y`, 2 hops), in the same step and with no extra approval gate. `found: false` means no short route to show (raise `maxHops` to 6, or set `viaHubs` for a route through a MOC).
|
|
36
|
+
- `vmem_link(from, to, relation, context, log: {type: "CONNECT", project, source: "notes/<x>.md", dest: "notes/<y>.md", note: "linked [[y]] (<relation>)"})` adds the typed link to both notes (bidirectional by default) and skips a side that already links the target; `from` is always a note this run owns or stands in for (vmem_link always writes `from`); when `to` is a page another writer owns, pass `bidirectional: false` and let its owner add the back-link, per `/vault-extract` §Extraction Fidelity and Concurrent Writers rule 3
|
|
37
|
+
- expect: vmem refuses a relation outside `supports | contradicts | extends | applies-to | context-for` and an unknown or ambiguous note; an already-linked pair returns `unchanged: true`
|
|
38
|
+
4. Update relevant MOCs if new connections span topics (`vmem_append` into the MOC's list section)
|
|
39
|
+
5. **CONNECT events in vault/log** come from each `vmem_link` call (ingest chain audit trail)
|
|
40
|
+
6. Report connections made and any cross-domain patterns discovered
|
|
41
|
+
|
|
42
|
+
## Log Append (Step 5 — REQUIRED)
|
|
43
|
+
|
|
44
|
+
Every wiki link /vault-connect creates produces one `log` line, written by `vmem_link` itself; set its content with the `log` argument. `vmem_link` links one `from` to one `to`, so one call writes one line naming that one target: a note that gains three links takes three calls and three lines. Never append to the log file directly.
|
|
45
|
+
|
|
46
|
+
**Format** (`references/vault-adapter.md` §Log Append):
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
YYYY-MM-DD HH:MM CONNECT <project> <vault/notes/x.md> — linked `[[a]]`
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
- `<project>`: project id from the target note's source registry classification, or `-` if unclassified
|
|
53
|
+
- `<vault/notes/x.md>`: the `from` note this call linked from (vmem uses it as the line's source even when the link is bidirectional)
|
|
54
|
+
- `[[a]]`: the one target this call linked
|
|
55
|
+
|
|
56
|
+
**No connections made**: no line is written (an `unchanged: true` link writes nothing). Report zero-connection runs in chat output instead.
|
|
57
|
+
|
|
58
|
+
**Bidirectional links**: a bidirectional `vmem_link` call updates both notes, and a `bidirectional: false` call updates only `from`; each call writes one line.
|
|
59
|
+
|
|
60
|
+
**Failure**: `references/vault-adapter.md` §Log failure handling, per link; keep the links that succeeded.
|
|
61
|
+
|
|
62
|
+
**Vault access**: use vmem through the transport in the adapter; no direct vault writes.
|
|
63
|
+
|
|
64
|
+
## Quality Gates
|
|
65
|
+
|
|
66
|
+
- Every connection must have stated reasoning
|
|
67
|
+
- Bidirectional: if A links to B, B should link to A, except a link this run wrote with `bidirectional: false` (step 3)
|
|
68
|
+
- Don't force connections — quality over quantity
|
|
69
|
+
- **CONNECT event appended to log for every run with ≥1 link created**
|
|
70
|
+
|
|
71
|
+
## Output
|
|
72
|
+
- List of connections made with reasoning
|
|
73
|
+
- Cross-domain patterns noted (if any)
|
|
74
|
+
- Updated MOCs (if any)
|
|
75
|
+
- log append status
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
SKILL.md is the instruction source for this skill. This file is background for maintainers; it holds no directives.
|
|
2
|
+
|
|
3
|
+
# vault-extract background
|
|
4
|
+
|
|
5
|
+
## Why the preconditions are strict
|
|
6
|
+
|
|
7
|
+
- An L02 incident: two notes created by an automated EXTRACT run lacked the required frontmatter fields and were caught only by a later `/vault-lint`.
|
|
8
|
+
- An L01 incident: about twenty notes accumulated dead `topics` wiki-links because `topics` was copied verbatim from summary frontmatter without a MOC existence check. The MOC check in the preconditions prevents a recurrence at the write site, and vmem now refuses the same entry (V02).
|
|
9
|
+
|
|
10
|
+
## Sibling meeting merge rule
|
|
11
|
+
|
|
12
|
+
The merge-or-split rule for sibling meetings was added after two complementary meeting sources on one initiative were extracted as fragmented notes.
|
|
13
|
+
|
|
14
|
+
## Change history
|
|
15
|
+
|
|
16
|
+
- 2026-11-15: Issue #150 aligned meeting frontmatter and extraction handoffs.
|
|
17
|
+
The template lacked extraction-required fields, registry project notes were
|
|
18
|
+
mistaken for MOC topics, and workspace links could be treated as vault links.
|
|
19
|
+
The updated contract separates those namespaces and exposes unresolved
|
|
20
|
+
metadata during review before an extraction proposal is offered.
|