@staix/vault-mem 0.5.1 → 0.6.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.
Files changed (47) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +138 -23
  3. package/package.json +5 -4
  4. package/src/amem/seam.ts +15 -6
  5. package/src/analysis-commands.ts +1 -1
  6. package/src/analysis-input.ts +24 -3
  7. package/src/analysis-reports.ts +1 -1
  8. package/src/analysis-types.ts +13 -1
  9. package/src/canon-tables.ts +190 -0
  10. package/src/cli-output.ts +15 -1
  11. package/src/cli.ts +1 -1
  12. package/src/commands-table.ts +6 -2
  13. package/src/config.ts +31 -3
  14. package/src/frontmatter.ts +10 -3
  15. package/src/links.ts +13 -1
  16. package/src/mcp-spec.ts +19 -11
  17. package/src/mcp-vault.ts +14 -9
  18. package/src/mcp.ts +4 -2
  19. package/src/org-promote.ts +29 -12
  20. package/src/promote.ts +24 -12
  21. package/src/read-commands.ts +1 -2
  22. package/src/read-output.ts +7 -5
  23. package/src/registry.ts +1 -0
  24. package/src/skills-mine.ts +5 -4
  25. package/src/spec-command-table.ts +10 -1
  26. package/src/spec-commands.ts +7 -3
  27. package/src/spec-gitlinks.ts +106 -0
  28. package/src/spec-output.ts +30 -0
  29. package/src/spec-source.ts +9 -3
  30. package/src/spec-validate.ts +6 -3
  31. package/src/spec-write.ts +469 -0
  32. package/src/ui/inbox.ts +28 -10
  33. package/src/ui/panel.js +26 -5
  34. package/src/ui/plugin.ts +38 -12
  35. package/src/ui/snapshot-cache.ts +123 -0
  36. package/src/vault-index.ts +109 -19
  37. package/src/vault-lint.ts +53 -5
  38. package/src/vault-log.ts +3 -2
  39. package/src/vault-stats.ts +110 -5
  40. package/src/write-commands.ts +4 -3
  41. package/src/write-files.ts +63 -0
  42. package/src/write-operations.ts +175 -25
  43. package/src/write-output.ts +20 -9
  44. package/src/write-types.ts +8 -1
  45. package/src/write-validation.ts +46 -17
  46. package/src/writer.ts +137 -41
  47. package/src/yaml-quoted.ts +12 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,66 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.6.0] - 2026-11-11
6
+
7
+ - N-1: 0.5.1 runs beside 0.6.0 with separate note/spec index files (`links2-schema3` versus `links2-schema4`); its format-3 reader preserves format-4 `canonTables` without using their promotion hints. The prior CLI/MCP surface remains available in 0.5.1; note merge and spec create/update/delete commands and MCP tools require 0.6.0. Note files remain shared, including automatic date stamps written by 0.6.0.
8
+
9
+ - Cache console Inbox and Promote snapshots by bounded vault-log and registry revisions, return unchanged cursors, and page Promote responses within 32 KiB. Retain page tokens across identical rescans, restore unchanged views on navigation and after failed-scan recovery, and isolate unreadable revision sources. Repeated revision churn retains usable completed pages, and page budgets include worst-case selection escaping (#197).
10
+
11
+ - Throttle console Inbox refreshes to at most one revision-triggered collection per 10 seconds while an applied console write still refreshes on the next poll; keep one Promote error cursor until a scan succeeds instead of rebuilding the error view each poll; hide `First page` on page 0; and unregister the broken revision vault the UI plugin test adds, so later tests open the same registry (#199).
12
+
13
+ - Share note/spec publication and descriptor-owned cleanup helpers, recheck parent identities and target containment after publication, retain replaced cleanup paths, and document the remaining same-user race windows. Direct MCP note writes now omit `refused: true` on applied-with-errors receipts, matching spec mutation semantics. Drift receipts identify applied paths, the drifted target and retained backups; pre-publication guidance and rollback state distinguish unpublished steps from already restored originals. Preserve EEXIST for intervening spec-create targets; cover publication/cleanup interleavings with fault fixtures (#172).
14
+
15
+ - Add two-step `vmem merge` / `vmem_merge`: full deterministic body/source/topic/inbound preview, locked fingerprint confirmation, shared link repointing and supersession, rollback and one log event. Authored endpoints get updated dates while inbound rewrites retain freshness; source/body limits and referenced fragment collisions, including copied fragment-only self-links, refuse before mutation. Heading edits decide title removal before Topics extraction, preserving later H1s, and remove only a leading title H1 and demote ATX outside code/raw HTML; Setext stays byte-unchanged, and fragment collisions use the reader anchor index. Both older-keeper supersession directions refuse with swap guidance (#166).
16
+
17
+ - Note merge checks absorb self-fragment collisions only in the content actually copied into keep, so a link on the removed leading title no longer refuses a valid merge. Surviving copied links still refuse referenced collisions (#190).
18
+
19
+ - Promotion previews optionally match configured canonical Markdown table rows with deterministic whole-token matching, alias handling, bounded indexing and advisory `link-existing` choices. Org previews read only target-vault tables; rows/warnings and `canonTables` stay outside fingerprints. Missing or denied tables warn without blocking. Per-vault `canonTables` uses config format 4; no built-in note names, model calls or automatic row edits (#167).
20
+
21
+ - Canonical table parsing accepts the GFM delimiter row with one or more hyphens per cell and optional alignment colons, so `|-|-|`, `|--|--|` and `| :-: | - |` are recognized tables and contribute rows. A configured note that reads but holds no recognizable table adds one advisory warning naming the path, which stays outside the fingerprint and blocks nothing (#189).
22
+
23
+ - Authored note writes (including link and explicit DOI assignment) stamp `updated` with the local calendar date through one shared writer transform; move backlink rewrites, tidy and sanitize preserve freshness dates; create fills absent `created` while preserving caller values and existing validation. Promotion previews show the same stamped content as confirm, and read-only/no-op operations remain unchanged. Non-JSON flow-header values and date emission that would alter YAML anchor/alias relationships preserve the authored write and return a cause-specific automatic-date warning with a working manual text-editor header repair step. Applied warnings confirm content was saved and never suggest repeating it (#165, part 1).
24
+
25
+ - Automatic note dates never canonicalize an uneditable header or refuse an otherwise valid near-limit authored write: preserve the candidate and return a V01 warning. Document explicit `updated` precedence and reuse validation snapshots across raw/stamped passes (#185).
26
+
27
+ - Spec create refuses a new Markdown input past the discovery cap, and create/update titles reject controls and line separators. Cleanup errors preserve their directory and cause. Delete acknowledgement budgets are preview-invariant, blocked path refusals request a fresh preview, and applied-delete errors direct inspection of the parent directory and lock state instead of re-confirmation (#175, #176).
28
+
29
+ - Spec update/delete ignore ordinary Markdown path-list churn while preserving spec drift checks; create compares only discovery count and target membership. Post-publication create IO/cleanup guidance inspects the created file, parents and lock state without suggesting a retry (#180).
30
+
31
+ - Spec create streams the index once per mutation stage and compares only gitlinks against its own ancestors, preserving missing-workdir, case and mixed Unicode normalization alias refusals without spelling expansion. Actual index-size, record and time bounds name the lookup cause and recovery step (#174).
32
+
33
+ - Lint L01, `vmem links` and `vmem_links` offer at most one suggested existing target for each dead link: the closest indexed title to the link text with its positive title score, above a minimum score, using the existing index and FTS. The report says `suggested` and gives the score, and the link is never rewritten. A text that mixes Hangul and Latin is ranked and thresholded on a CJK run's bigram score and a Latin term's token score added together, so a Hangul phrase most titles share cannot hide the one title carrying the whole text. Hints cover at most 1000 distinct dead link texts per lint run; a text past that bound says `hint not computed (cap 1000)` and the report counts what it left out, instead of reading as a missing match. A hint is looked up for at most 1024 UTF-8 bytes of the raw link text, the bound a reported link target is capped at, read before a control character is read as the separator the index already tokenizes it as and never on the capped target a row displays, so `links`, `vmem_links` and lint name the same hint for the same dead link and an odd or over-long dead link is a miss at worst, never a failed read (#165, part 3).
34
+
35
+ - Lint adds L15: a note with `confidence: proven` and an empty `source` is listed as a warning, never refused, so existing notes stay readable. The MCP server now sends pinned `initialize` `instructions` under 400 bytes: search first with `vmem_search`, read the best match by section with `vmem_read`, and expect validated writes (#165, parts 2 and 4).
36
+
37
+ - Reference notes are searchable by their frontmatter `arxiv_id`, alongside `doi` and `citekey`: the id joins the FTS text without its `vN` version suffix, so `vmem search <vault> 2502.04321 --type reference` finds a note holding `arxiv_id: 2502.04321v2` whose body never mentions it. The index schema moves to 4, so an existing cache rebuilds once on the next scan instead of answering without the id; stored bodies, links and lint input are unchanged (#188).
38
+
39
+ - Add `vmem_spec_delete` and `vmem spec delete`: read-only previews list every backlink kind and child, with a path/SHA/list fingerprint. Confirm recomputes under the shared mutation lock, refuses stale acknowledgements and allows only listed dangling links to the removed id. Other introduced errors remain blocked before result limits. All three spec write tools are implemented (#97, T4c).
40
+
41
+ - Add `vmem_spec_create` and `vmem spec create` with ordered frontmatter, type-specific headings and draft defaults. Creation shares spec write policy, secret/PII screens, actor attribution, mutation locks and the introduced-error gate; unsafe, ignored or existing targets refuse without overwrite (#97, T4b).
42
+
43
+ - Add `vmem_spec_update` and `vmem spec update` from the shared spec command schema: lossless frontmatter set/unset/list edits with an immutable id, per-worktree locks outside the repository, expected-SHA protection, shared secret/PII screens and an in-memory introduced-error gate. Receipts include the actor; no commit, branch, push or source log is created (#97, T4a).
44
+
45
+ - Skill mining parses `Record` capture excerpts through agent-mem 0.23.0, preserving record kinds and using anchors as matching context under the existing screens, masks and bounds. Malformed or partially parsed excerpts are dropped as whole rows and counted in `dropped.malformedRecord`; `Title` and tool rows stay excluded. Truncated capture shards remain reported because the API has no excluded-Record count. Promotion drafting remains separate (#163).
46
+
47
+ - Raise the exact bundled `@staix/agent-mem` pin from 0.17.0 to 0.23.0, bringing reader-floor enforcement and current generation-profile support to the amem seam. Record mining is supported through the updated parser; promotion drafting remains separate, and no home migration or placement activation is performed.
48
+
49
+ - Skill mining includes agent-mem `Recap` and `Compact` capture excerpts with their event kinds, through the existing read-only screening and masking pipeline. The Markdown report now exposes the truncated capture-window shard count already present in JSON and states that rows of any event beyond the window were not read. `Title` and tool events remain excluded; `Record` excerpts are also supported as described above, while promotion drafting remains separate (#163).
50
+
51
+ - Release evidence: a new dgx02 measurement through `remote_dev.py run --cgroup` replaces the synthetic performance report (cgroup `memory.peak` 96.35 MB, sampled peak 137.76 MB, idle 53.39 MB, search p95 25.51 ms) and passes `release:verify`; the 0.5.1 report is kept as `docs/evidence/v0.5.1-synthetic-performance.json` (#156).
52
+
53
+ - Release performance now requires delegated cgroup memory accounting on Linux, runs MCP alone in a fresh child before Bun startup, and records its `memory.peak` as the gate value. The unchanged 200 MB gate requires both this charged-memory peak and the sampled VmRSS/VmHWM maximum to be below the limit. File pages first charged by the harness remain excluded from `memory.peak`, so it is not an upper bound of VmRSS. VmRSS/VmHWM samples and `sampledPeakRss` remain recorded; cgroup-sourced evidence can verify even when VmHWM decreases. Missing delegation refuses with the remote runner command, without fallback. The preserved 0.5.1 VmHWM-only report remains unverified under the newer evidence rule; 0.6.0 includes a fresh cgroup-sourced report (#156).
54
+
55
+ - Docs: README facts (Bun floor, agent-mem pin, index versions, note types, MCP tool list, library exports) are generated by `scripts/readme-facts.ts` and checked in `bun run check`; `docs/verified.json` stamps README and the release docs, `scripts/check-docs.mjs` warns on stale stamps in `bun run check` and refuses them in `release:tag` and tag validation. Stale statements fixed: search example type, library export summary, index schema version, release status and the live-cutover position. The release workflow notifies agent-hub-site after a release (#157).
56
+
57
+ - `release:verify` refuses non-cgroup performance evidence whose sampled VmHWM (`rssSamples` `highWaterBytes`) is missing or decreases, naming the decrease count, first drop and next step. Cgroup-sourced evidence uses the joint charged-memory and sampled-maximum gate described above; `hwmDecreases` remains diagnostic, and no `lowerBound` gate field is emitted (#152).
58
+
59
+ - CI now exposes the `ci-ok` aggregate over the check matrix, requires release tags to be on main with a green main-push Check on the same commit, provides the guarded `release:tag` script, and pins checkout v6 consistently across workflows (#153).
60
+
61
+ - Vault statistics add the note text size in bytes and words, in total and by type and domain, and a note-to-source byte ratio: for notes whose frontmatter `source` names readable workspace files, the note's size over theirs, reported as median and p90 with the notes larger than their sources and the five largest. Each source counts at its own size on disk rather than at the size of its decoded text. Non-file sources, denied or missing paths, files past the 2 MiB read bound, a file that would take the 64 MiB source total past its cap, and anything past the per-call bounds are skipped and counted, and `truncatedNotes` counts the sourced notes the index's 10000-note cap left out. Stats stay read-only (#165 part 5).
62
+
63
+ - The ratio keeps its units apart: `skipped` now counts source references only, and a note whose readable sources total zero bytes is counted in `emptySourceNotes`, with its own line in the text output and its own field in JSON and `vmem_stats`, so an empty file that was read is no longer also reported as a skipped reference (#184).
64
+
5
65
  ## [0.5.1] - 2026-11-05
6
66
 
7
67
  - Console inbox snapshots share a background refresh, keep prior rows through refreshes and source failures, and wait at most 700 ms cold before showing a refreshing row. Payloads are capped at 50 prioritized rows with bounded Unicode-safe title and detail. `moreIsLowerBound` identifies "at least N more" when agent-mem's per-project candidate limit prevents an exact total. Applied writes invalidate freshness without clearing triage; source workers refresh on a 60-second cache and have a 30-second termination budget (#149).
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # vault-mem
2
2
 
3
- An Obsidian-compatible knowledge vault tool for agents and people. Requires Bun >=1.4.2. The full check (`bun run check`) needs Bun, git and tar; it includes a package dry-run and clean installed CLI/MCP smoke. Node/npm are used by the separate release workflow, not required for the ordinary Bun gate. CI runs on Ubuntu and macOS for pull requests and for pushes to `main`.
3
+ An Obsidian-compatible knowledge vault tool for agents and people. Requires <!-- facts:bun-floor -->Bun >=1.4.2<!-- /facts:bun-floor -->. The full check (`bun run check`) needs Bun, git and tar; it includes a package dry-run and clean installed CLI/MCP smoke. Node/npm are used by the separate release workflow, not required for the ordinary Bun gate. CI runs on Ubuntu and macOS for pull requests and for pushes to `main`.
4
4
 
5
- Implemented: configuration, vault registration, lossless frontmatter parsing/emission, wiki-link resolution and derived SQLite FTS5 indexing with bounded read commands. Validated note writes, the append-only log, the `vmem mcp` stdio server, reversible `vmem setup` host registration and promotion from agent-mem (`promote-from-amem`) are also implemented below. Lint/graph analysis, promotion to org vaults (`vmem promote`) and explicit `vmem sync` are implemented below. The vmem plugin for the `acon` console ([agent-console](https://github.com/STAIxBWLB/agent-console)) is described under "Console plugin"; vault-mem ships no console bin. Do not use this increment to replace an existing vault writer.
5
+ Implemented: configuration, vault registration, lossless frontmatter parsing/emission, wiki-link resolution and derived SQLite FTS5 indexing with bounded read commands. Validated note writes, the append-only log, the `vmem mcp` stdio server, reversible `vmem setup` host registration and promotion from agent-mem (`promote-from-amem`) are also implemented below. Lint/graph analysis, promotion to org vaults (`vmem promote`) and explicit `vmem sync` are implemented below. The vmem plugin for the `acon` console ([agent-console](https://github.com/STAIxBWLB/agent-console)) is described under "Console plugin"; vault-mem ships no console bin.
6
+
7
+ Status: released versions are published to npm ([CHANGELOG](CHANGELOG.md), [release readiness](docs/release-readiness.md)). Replacing an existing vault writer is a live cutover: it is the parent plan's operation, outside this repository, and follows the [cutover checklist](docs/cutover-checklist.md). This repository does not record its result, and a release does not authorize it.
6
8
 
7
9
  ```sh
8
10
  bun install
@@ -27,7 +29,7 @@ Home precedence: `VMEM_HOME` (the pointer is not consulted), else a `home` point
27
29
  {"vaults":[{"id":"personal","path":"/absolute/vault","kind":"personal","write":"mcp"}],"denyPaths":[],"piiPatterns":[]}
28
30
  ```
29
31
 
30
- Configuration is limited to 64 KiB both on read and after serialization (a change whose pretty-printed result exceeds the limit is refused and the file is unchanged), rejects unknown keys, and is updated under an exclusive lock using a flushed temporary file and atomic rename. An optional top-level `version` (positive integer, absent means 1) names the config format; this build supports format 3. Registry writes add `version: 3` when a vault declares `domains`, or at least `version: 2` when `specs` is present. Configurations without either keep their existing version field (or its absence). A config whose `version` is newer than this build's format is read tolerantly: unknown keys at the top level, in vaults and in PII policies are kept and written back unchanged by registry commands, while the keys this build knows are still validated. A PII policy with members this build does not know cannot be enforced, so it fails closed: every write on that vault (note writes and `check`, two-step previews and confirms, tidy, `promote-from-amem`, `promote` and log appends) is refused with `PII_POLICY`, naming the members, until the newer vmem that wrote the policy does the write. Reads and `vaults pii` show are unaffected. `vaults pii --set` refuses to replace a policy that carries such members, since the replacement would drop them; change it with the newer vmem. Versions that add a key bump the format. Errors name the config file or vault id and path but never echo config or note contents.
32
+ Configuration is limited to 64 KiB both on read and after serialization (a change whose pretty-printed result exceeds the limit is refused and the file is unchanged), rejects unknown keys, and is updated under an exclusive lock using a flushed temporary file and atomic rename. An optional top-level `version` (positive integer, absent means 1) names the config format; this build supports format 4. Registry writes add `version: 4` when a vault declares `canonTables`, at least `version: 3` for `domains`, or at least `version: 2` for `specs`. Configurations without these fields keep their existing version field (or its absence). A config whose `version` is newer than this build's format is read tolerantly: unknown keys at the top level, in vaults and in PII policies are kept and written back unchanged by registry commands, while the keys this build knows are still validated. A PII policy with members this build does not know cannot be enforced, so it fails closed: every write on that vault (note writes and `check`, two-step previews and confirms, tidy, `promote-from-amem`, `promote` and log appends) is refused with `PII_POLICY`, naming the members, until the newer vmem that wrote the policy does the write. Reads and `vaults pii` show are unaffected. `vaults pii --set` refuses to replace a policy that carries such members, since the replacement would drop them; change it with the newer vmem. Versions that add a key bump the format. Errors name the config file or vault id and path but never echo config or note contents.
31
33
 
32
34
  A vault entry may declare `"domains": ["finance", "health", "household"]` in `vmem.config.json` (or in the object passed to `addVault`). This adds at most 16 ids matching `[a-z][a-z0-9-]{0,31}` to the built-ins `research`, `projects`, `teaching`, `operations`, `people`, `ai-practice`; an empty or omitted array leaves the built-ins available. Duplicate ids count toward the 16-entry declaration bound and appear once in the effective set. `status --json`, MCP `vmem_status` and `vaults list` report the effective set as `domains` (the text list has a DOMAINS column). Reads do not rewrite config. Writers and lint check domain values against the selected vault; missing-domain lint behavior is unchanged. `promote` and `promote-from-amem` check the target vault's set and name an undeclared domain with how to fix it; a personal-only domain is refused by an org vault that does not declare it. The existing per-vault PII policy applies to every domain; note types remain fixed.
33
35
 
@@ -37,7 +39,46 @@ Crash recovery: the lock file records the writer's pid, host and start time. Not
37
39
 
38
40
  Vault fields: `id`, absolute `path` (must contain a real `notes/` directory), `kind` (`personal|org`), `write` (`mcp|cli|none`), optional `pii` (the `allow|deny` shorthand or a policy object, see PII policy below; default `allow` for personal and `deny` for org, and `status`/`vaults list` always report the effective shorthand and `piiPolicy` matrix, including for unhealthy entries), optional `remote` (any nonempty string such as an `https://` or `git@host:path` URL) and optional `registry` (absolute path). For healthy vaults, `doctor` checks locally that the vault is a git repository root with an origin whose fetch and push URLs all match `remote` (URL rewrites are refused), and that `registry` passes the same deny-path, size and project-id validation as log appends. Results appear under each vault's `checks.remote` and `checks.registry`. Doctor also runs the tidy planning pass for writable vaults and reports pending counts and unparsable paths, without per-note writer validation or writes. Planning failures appear as `checks.tidy`; a failed check exits 1. Actual tidy previews validate planned notes and identify skipped notes. These checks use no network and do not test reachability. `status` is unchanged. Policy fields are stored for later note-writing stages, not enforced by the read commands. Writer commands enforce write/channel policy and configured deny/PII screening.
39
41
 
40
- The only runtime dependency is the exact first-party pin `@staix/agent-mem@0.17.0`; it is not loaded by registry commands. Public library exports cover configuration, home resolution, registry operations, frontmatter, link resolution and the derived index. No console bin or UI contract is advertised before its implementation.
42
+ A vault may declare `canonTables` in format 4, with no default note names:
43
+
44
+ ```json
45
+ {"version":4,"vaults":[{"id":"personal","path":"/absolute/vault","kind":"personal","write":"mcp","canonTables":[{"path":"notes/entities.md"},{"path":"notes/roster.md","keyColumn":2}]}]}
46
+ ```
47
+
48
+ Each entry names a literal flat `notes/<name>.md` path in that vault (at most 256 UTF-8 bytes); absolute/traversing/dot paths, backslashes and controls are config errors. Up to 16 entries are allowed, with `keyColumn` defaulting to the first column and otherwise 1..64. Duplicate path/column pairs are refused. Missing, unreadable or denied table notes at preview time contribute no rows and produce an advisory warning with a repair step. They never become a promotion refusal. Other write policy and note validation remain enforced.
49
+
50
+
51
+ The only runtime dependency is the exact first-party pin <!-- facts:amem-pin -->`@staix/agent-mem@0.23.0`<!-- /facts:amem-pin -->; it is not loaded by registry commands. 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, and the spec source registry, graph, validation and freshness. `@staix/vault-mem/ui-plugin` is the console plugin entry (see Console plugin). No console bin is shipped. Exported functions and constants by module:
52
+ <!-- facts:exports -->
53
+
54
+ - `src/home.ts`: `resolveHome`
55
+ - `src/config.ts`: `parseConfig`, `parseVault`, `parseSpec`, `readConfig`, `CONFIG_FILE`, `MAX_CONFIG_BYTES`
56
+ - `src/registry.ts`: `addVault`, `removeVault`, `addSpec`, `removeSpec`, `specStatus`, `loadRegistry`, `registryStatus`, `recoverRegistry`, `effectivePii`, `syncDirectory`, `LOCK_FILE`
57
+ - `src/frontmatter.ts`: `parseFrontmatter`, `emitFrontmatter`
58
+ - `src/links.ts`: `extractLinks`, `resolveLinks`, `normalizeTarget`
59
+ - `src/vault-index.ts`: `VaultIndex`, `MAX_NOTE_BYTES`, `MAX_RESULTS`, `MAX_READ_BYTES`
60
+ - `src/writer.ts`: `applyWrite`, `sha256`, `MUTATION_LOCK`, `MAX_WRITE_BYTES`
61
+ - `src/write-validation.ts`: `validateWrite`, `screenContent`
62
+ - `src/vault-log.ts`: `appendLog`, `readLog`, `LOG_LOCK`, `MAX_LOG_READ_BYTES`, `MAX_LOG_RESULT_BYTES`, `LARGE_LOG_LINES`
63
+ - `src/log-format.ts`: `formatLogEvent`, `LOG_TYPES`, `AGENT_MARKERS`
64
+ - `src/mcp.ts`: `serveMcp`, `validArguments`, `FRAME_BYTES`, `RESULT_BYTES`
65
+ - `src/mcp-vault.ts`: `createVaultMcp`, `vaultTools`, `VMEM_TOOL_NAMES`
66
+ - `src/setup.ts`: `runSetup`, `defaultEntry`, `SETUP_TARGETS`, `SERVER_NAME`
67
+ - `src/commands-table.ts`: `COMMANDS`, `completionDefinitions`, `completionScript`
68
+ - `src/promote.ts`: `promoteFromAmem`, `listPromotionCandidates`, `draftNote`, `stemFor`, `logProjectFor`
69
+ - `src/vault-lint.ts`: `lintVault`
70
+ - `src/vault-graph.ts`: `buildGraph`, `graphNeighbors`, `graphReport`
71
+ - `src/analysis-reports.ts`: `writeAnalysisReports`
72
+ - `src/org-promote.ts`: `promoteToOrg`, `screenForOrg`, `dropUnresolvedLinks`, `lintPromoted`
73
+ - `src/sync.ts`: `syncVault`, `sameRemote`
74
+ - `src/source.ts`: `normalizeSource`, `sourceReferences`
75
+ - `src/tidy.ts`: `tidyVault`, `parseTidyMap`, `TIDY_RULES`
76
+ - `src/spec-source.ts`: `resolveSpecWorktree`, `discoverSpecs`, `SpecIndex`
77
+ - `src/spec-graph.ts`: `buildSpecGraph`, `specSlice`, `SPEC_EDGE_KINDS`, `MAX_SPEC_INPUTS`, `MAX_SPEC_EDGES`
78
+ - `src/spec-validate.ts`: `validateSpecs`, `introducedSpecErrors`, `validateSpecRepo`
79
+ - `src/spec-freshness.ts`: `specFreshness`, `specsCoveringPath`
80
+
81
+ <!-- /facts:exports -->
41
82
 
42
83
  # PII policy
43
84
 
@@ -84,25 +125,29 @@ The policy is changed only through the CLI, under the config lock. MCP clients c
84
125
 
85
126
  ```sh
86
127
  bun bin/vmem.js rebuild personal
87
- bun bin/vmem.js search personal "project discovery" --type concept --domain research --limit 20
128
+ bun bin/vmem.js search personal "project discovery" --type insight --domain research --limit 20
88
129
  bun bin/vmem.js show personal "Note or alias" --max-bytes 16384
89
130
  bun bin/vmem.js links personal "Note or alias" --limit 50 --json
90
131
  ```
91
132
 
133
+ `--type` and `--domain` keep only notes whose frontmatter `type` and `domain` equal the given value. Validated writes accept these note types: <!-- facts:note-types -->`insight`, `decision`, `observation`, `person`, `project`, `method`, `moc`, `reference`<!-- /facts:note-types -->.
134
+
92
135
  All four commands require a registered vault id. They read only flat, regular `notes/*.md` files (case-sensitive `.md` extension), skip subdirectories and symlink files, and refuse a replaced vault/notes directory. Notes are limited to 2 MiB each. They never write note content, registry configuration or `.obsidian/`. `rebuild` rebuilds the derived cache; other commands scan metadata on every invocation and rehash new or metadata-changed files. Content-identical changes only update metadata; deleted/renamed paths leave the index. SQLite transactions make each scan atomic. A concurrently changing note aborts that scan, so retry after its writer finishes. No watcher, model calls or embeddings run.
93
136
 
94
- The cache is `$VMEM_HOME/indexes/<canonical-vault-path-sha256>-links<N>-schema<S>.sqlite` using the resolved home, not necessarily the environment variable. `N` is the link-resolution version (currently 2) and `S` the index schema version (currently 2, which added the CJK bigram table), so two installed vmem versions that resolve links or store the index differently keep separate caches instead of rebuilding each other's; 0.2.4 and older use the unversioned `<sha256>.sqlite`, 0.3.0 through 0.3.3 use `<sha256>-links2.sqlite`, and a first run after upgrading builds the new file once with no manual step. Cache files use mode 0600 on creation. The location must be outside every registered vault, including through symlinks; linked cache directories/files are refused. It contains note text and is disposable private derived state. Removing it while commands are stopped allows the next read to build it again. SQLite uses its own transaction lock and a five-second busy timeout. There is no automatic migration or live vault cutover.
137
+ The cache is `$VMEM_HOME/indexes/<canonical-vault-path-sha256>-links<N>-schema<S>.sqlite` using the resolved home, not necessarily the environment variable. `N` is the link-resolution version (currently <!-- facts:index-links -->2<!-- /facts:index-links -->) and `S` the index schema version (currently <!-- facts:index-schema -->4<!-- /facts:index-schema -->; schema 2 added the CJK bigram table, schema 3 the reference identifiers and schema 4 the arXiv id reference notes are searchable by), so two installed vmem versions that resolve links or store the index differently keep separate caches instead of rebuilding each other's; 0.2.4 and older use the unversioned `<sha256>.sqlite`, 0.3.0 through 0.3.3 use `<sha256>-links2.sqlite`, 0.4.0 uses `<sha256>-links2-schema2.sqlite`, 0.5.0 through 0.5.1 use `<sha256>-links2-schema3.sqlite`, and a first run after upgrading builds the new file once with no manual step. Cache files use mode 0600 on creation. The location must be outside every registered vault, including through symlinks; linked cache directories/files are refused. It contains note text and is disposable private derived state. Removing it while commands are stopped allows the next read to build it again. SQLite uses its own transaction lock and a five-second busy timeout. There is no automatic migration or live vault cutover.
95
138
 
96
139
  Search uses FTS5 `unicode61` over title, description and body with BM25 weights 5:2:1, ascending score and path tie-breaking. Whitespace-separated query terms are literal AND terms, not a raw FTS expression; quote the query as one shell argument. A term whose letters and digits form one run of 2 or more Hangul, Han, Hiragana or Katakana characters (surrounding punctuation is ignored) matches wherever it occurs in the title, description or body, including particle and compound forms: `사업단` finds `사업단은`, `사업단장` and `해외사업단`. That matching uses a side FTS5 table of overlapping character bigrams (Unicode NFC), so a 2-character term is one indexed lookup and a longer term a phrase of consecutive bigrams; it is substring matching, not morphological analysis. Every other term, including Latin words, single CJK characters and terms mixing CJK with Latin letters or digits (`AI교육`), keeps `unicode61` token matching, and a query without CJK terms ranks exactly as before. With a CJK term, notes where every CJK term is a standalone word or occurs in the title or description rank before notes that contain it only inside a longer body word; within each group BM25 over the bigram table (5:2:1) and path break ties, and the snippet is a body window around the first CJK term. `--type` and `--domain` are exact scalar frontmatter filters. Results include a bounded snippet and metadata, not the full body. Search queries and note targets accept at most 1024 UTF-8 bytes. Search/links default to 50 results, with an enforced 1..500 range. Show defaults to 16384 UTF-8 bytes and permits 1..65536, returning `truncated` and the full note SHA-256. `--section "Exact H2"` selects one real H2 through the next H1/H2, including its H3 children; code-fenced headings are ignored and duplicate/missing names refuse. Truncated reads include bounded `headings` (at most 64 names/8KiB metadata; `headingsTruncated` when omitted) and `nextOffset`. `--offset N` is a UTF-8 byte offset within the selected section or whole note; use the returned `nextOffset` to page even a single section larger than 64 KiB, and compare note hashes across pages. Invalid UTF-8 boundaries and zero-progress byte budgets refuse. Link string fields are capped at 1024 bytes in command results. Oversized arguments fail instead of silently raising a bound.
97
140
 
98
- Link resolution uses NFC and case-insensitive filename stems only, as Obsidian and `vmem lint` L01 do. Frontmatter `aliases` (string or string array; legacy `alias` accepted) are not link targets; `show`, `links <target>` and `vmem_read` still find a note by alias. A link that only an alias matches is a missing-note link, so the writer refuses a new one and org promotion drops it to text. An optional `notes/` prefix and `.md` suffix are accepted. `[[target|label]]`, `[[target#heading]]`, `[[target#^block]]`, `![[target]]` and same-note anchors work. ATX/Setext headings and end-of-line block ids are checked; fenced code is skipped. Missing/ambiguous targets and missing anchors remain explicit with a reason. Stems that differ only by case or Unicode normalization are ambiguous. Reported `path` values are the on-disk file names byte for byte, while targets (`show`, `links`, `vmem_read`, wiki-links) are compared after NFC: a note another tool saved under an NFD name is found from an NFC target and reported under its NFD name. Links returns outgoing links in source order, with one-based body-relative `line` values (frontmatter excluded); it does not write backlinks or repair dead links.
141
+ Link resolution uses NFC and case-insensitive filename stems only, as Obsidian and `vmem lint` L01 do. Frontmatter `aliases` (string or string array; legacy `alias` accepted) are not link targets; `show`, `links <target>` and `vmem_read` still find a note by alias. A link that only an alias matches is a missing-note link, so the writer refuses a new one and org promotion drops it to text. An optional `notes/` prefix and `.md` suffix are accepted. `[[target|label]]`, `[[target#heading]]`, `[[target#^block]]`, `![[target]]` and same-note anchors work. ATX/Setext headings and end-of-line block ids are checked; fenced code is skipped. Missing/ambiguous targets and missing anchors remain explicit with a reason. Stems that differ only by case or Unicode normalization are ambiguous. Reported `path` values are the on-disk file names byte for byte, while targets (`show`, `links`, `vmem_read`, wiki-links) are compared after NFC: a note another tool saved under an NFD name is found from an NFC target and reported under its NFD name. Links returns outgoing links in source order, with one-based body-relative `line` values (frontmatter excluded); it does not write backlinks or repair dead links. A dead link is also offered at most one suggested existing target: the closest indexed title to its text, with its positive title score, above a minimum score. `links` returns it as `suggested` on the dead entry, and `vmem lint` L01 names the same one. A text that mixes Hangul and Latin is ranked and thresholded on both parts added together, so a Hangul phrase most titles share cannot hide the one title that carries the whole text. A hint is looked up for at most 1024 UTF-8 bytes of the raw link text, the bound a reported link target is capped at, and the bound is read on the raw text before a control character is read as the separator the index already tokenizes it as, never on the capped target a row displays, so `links`, `vmem_links` and `vmem lint` name the same hint for the same dead link and a longer text gets no suggestion. A text FTS cannot parse is a miss rather than an error. It is a hint only; nothing rewrites the link.
99
142
 
100
143
  `parseFrontmatter` retains source bytes alongside semantic YAML data using Bun's built-in YAML parser. `emitFrontmatter(document, changes)` returns the entire note, preserving omitted and semantically unchanged keys byte-identically (comments, quoting, sequences, one-level mappings, folded/literal/chomped scalars, BOM and line endings). Changed keys use canonical JSON-compatible YAML; `undefined` removes a key. Editing requires a block mapping, while an unchanged flow mapping round-trips. This is a library transformation only, not a note-write command. Synthetic fixtures and create/edit/delete/rename parity tests cover this increment; Linux/macOS CI remains the platform verification gate.
101
144
 
102
145
 
103
146
  # Validated writes
104
147
 
105
- All mutations use `applyWrite(home, request)`: per-vault `mutation.lock`, current-SHA checks, in-memory planning, final-snapshot validation/screening, same-directory flushed temporary files and atomic renames, directory flushes, derived-index refresh and a structured receipt. `write: mcp` allows CLI and MCP writes; `cli` allows CLI only; `none` refuses mutations. `check` is read-only and works with `none`. No command requires a TTY or rejects agent environments. This increment runs on fixtures; it does not authorize a live vault cutover.
148
+ Authored note content writes stamp `updated` with the local calendar date (`YYYY-MM-DD`, using the same clock as vault logs): create, append, patch, frontmatter edits (including explicit DOI assignment), both sides of supersession, promotion and link. Mechanical move rewrites (including backlinks), tidy and sanitize preserve existing dates, as do checks, reports and semantic no-ops. Create also fills `created` when the key is absent; existing and caller-supplied values retain their current validation. Automatic stamping takes precedence over an explicit `updated` set or unset on an authored write; the caller candidate still passes normal validation first. The writer validates the final content too, reusing parsed snapshots across the two passes. Writer and promotion previews account for the dates without writing; their date-bearing fingerprints need a fresh preview after a date change. A header that cannot be edited in place, including flow mappings and merge-key block mappings, is never canonicalized just to add dates: the authored candidate keeps its header bytes and gets a V01 warning. If adding only the automatic dates would push an otherwise valid note over 256 KiB, the candidate is saved unstamped with a V01 warning asking you to shorten the note enough to leave room for later automatic dates. Oversized caller content is still refused. Stamping also reparses its candidate and preserves YAML anchor/alias relationships. If emission would remove or change a reference, alter other metadata, or produce an invalid header, the original authored candidate is kept unstamped. A cause-specific V01 warning directs you to open the note in a text editor and rewrite its header as a block mapping with plain literal values. Replace any aliases with their literal values and remove anchors; later authored writes then stamp `updated` automatically. This is a manual header edit, not a vmem frontmatter operation, which cannot repair every flow header or semantic no-op alias. An applied receipt says the content was saved; the warning never advises repeating that content write. Readonly previews do not claim a save. Unrelated anchors and aliases remain intact and do not prevent stamping.
149
+
150
+ All mutations use `applyWrite(home, request)`: per-vault `mutation.lock`, current-SHA checks, in-memory planning, final-snapshot validation/screening, same-directory flushed temporary files and atomic renames, directory flushes, derived-index refresh and a structured receipt. `write: mcp` allows CLI and MCP writes; `cli` allows CLI only; `none` refuses mutations. `check` is read-only and works with `none`. No command requires a TTY or rejects agent environments. Note and spec publication share a path/cleanup helper. Immediately after rename, link or unlink, it rechecks all captured parent identities and target containment; a mismatch returns an error with recovery steps, retaining `applied`/`changed` when publication already occurred. Note drift receipts annotate planned changes with per-path `applied` state, attribute the drifted target, and list `retainedBackups` by their original relative names. CLI error summaries count only applied changes; a rollback that already restored the original bytes reports a consumed backup rather than claiming it was retained. Backups are not intentionally retained when no change was published. Owned lock/temp descriptors remain open through cleanup; immediately before unlink the helper compares descriptor and named-path identities, retaining and reporting a replacement. A concurrent writer with the same user's access can still edit the target or swap a directory between the last check and publication, or replace a cleanup name after its last identity check. Pure TypeScript cannot atomically close these windows without native relative-directory or inode-checked operations. Stop concurrent writers and inspect the root, target, lock and retained backups before manual recovery; do not automatically retry an applied-with-errors receipt.
106
151
 
107
152
  ```sh
108
153
  vmem new personal example-finding --type insight --domain research --topics research --description "A distinct supporting observation."
@@ -124,7 +169,7 @@ vmem tidy personal --all --json # migration sanitize preview (se
124
169
 
125
170
  Syntax follows indexed reads: the vault id comes first. `new` supports `--title`, `--source`, `--confidence`, `--status`, `--extra JSON` and `--body file|-`; omitted body gets an H1/Relevant Notes/Topics skeleton. Patch accepts nonempty old/new strings up to 8192 bytes and requires exactly one occurrence (including overlapping occurrences). `--edits file|-` (MCP `edits`) instead takes a JSON array of 1 to 32 `{oldString, newString}` pairs with the same bounds: each `oldString` must match exactly once in the original note, edits must not overlap and none may start in frontmatter. They apply all-or-nothing, so any failing edit (or a stale `--expected-sha`) refuses the whole patch; a success gives one receipt and one log event, and the 256 KiB bound applies to the combined result. Use exactly one form per call; both or neither is refused. Append uses an existing section or inserts it before Topics; it refuses targeting or introducing a Topics H2. `frontmatter` supports `--set JSON`, `--unset key,key` and `--expected-sha`; changing `topics` also replaces only the body Topics wiki-list items in the same write, preserving other content and line endings; setting an equal topics value leaves the body unchanged; append also supports `--expected-sha`. Link relations are `supports`, `contradicts`, `extends`, `applies-to`, `context-for`; links are bidirectional unless `--one-way`. Supersede sets `status`/`superseded_by` on the old note and adds a reverse link in the next note. Report permits plain paths below `reports/` or `ops/`, is schema-exempt and still screened. Inputs are bounded to 256 KiB, follow no file symlinks and accept stdin with `-`.
126
171
 
127
- Reference notes may optionally hold `citekey` (`[A-Za-z0-9_:-]{1,64}`, unique vault-wide ignoring ASCII case (stored case is preserved)), `doi` (`10.` plus a 4..9-digit registrant, `/` and a nonempty suffix without whitespace or control characters), `arxiv_id` (`YYMM.NNNN` for YY < 15, `YYMM.NNNNN` for YY >= 15, or `archive/YYMMNNN`, optionally `vN` with N >= 1 and month 01..12), `authors` (1..100 nonempty strings), `year` (integer 1000..2100) and `venue` (1..200 Unicode characters). These keys are refused on other note types. Create and explicit DOI assignments store lowercase; body-only edits preserve legacy metadata. Identifier validation is offline syntax only, with no existence lookup or model call. `vmem search <vault> "10.1234/example" --type reference` (MCP `vmem_search` with `type: "reference"`) searches DOI and citekey as well as title, description and body. The derived cache uses `-links2-schema3.sqlite`, rebuilt once independently of older versions; stored note bodies and lint input stay unchanged.
172
+ Reference notes may optionally hold `citekey` (`[A-Za-z0-9_:-]{1,64}`, unique vault-wide ignoring ASCII case (stored case is preserved)), `doi` (`10.` plus a 4..9-digit registrant, `/` and a nonempty suffix without whitespace or control characters), `arxiv_id` (`YYMM.NNNN` for YY < 15, `YYMM.NNNNN` for YY >= 15, or `archive/YYMMNNN`, optionally `vN` with N >= 1 and month 01..12), `authors` (1..100 nonempty strings), `year` (integer 1000..2100) and `venue` (1..200 Unicode characters). These keys are refused on other note types. Create and explicit DOI assignments store lowercase; body-only edits preserve legacy metadata. Identifier validation is offline syntax only, with no existence lookup or model call. `vmem search <vault> "10.1234/example" --type reference` (MCP `vmem_search` with `type: "reference"`) searches DOI, citekey and arXiv id as well as title, description and body; the arXiv id joins the search text without its `vN` version suffix, so `2502.04321` finds a note holding `arxiv_id: 2502.04321v2`. The derived cache uses `-links2-schema4.sqlite`, rebuilt once independently of older versions, so an index built before arXiv ids were indexed answers from a fresh cache rather than without the id; stored note bodies and lint input stay unchanged.
128
173
 
129
174
  `--dry-run` plans and validates any writer without creating locks, temporary files, directories or caches. `check` always takes this path, even without `--dry-run`. Move, delete and tidy first return a preview with planned path/hash changes and a fingerprint; confirmation requires that fingerprint. It covers canonical operation input, the canonical vault path/identity and policy, expected SHAs, every scanned note and all touched files, so even a new inbound reference after preview forces another preview. Move rewrites visible wiki/heading/block/embed targets and wiki references in frontmatter across the vault, preserving explicit `|label` text, anchors and code. Alias-only links resolve to no note and are left as written. The move source may be an existing note with a legacy file name (lint L13, for example a dot in the stem); the destination must be a valid stem. Tidy folds Connections sections into Relevant Notes. Delete refuses when it would newly break inbound links or MOC topics; fix those references first.
130
175
 
@@ -133,6 +178,20 @@ Validation returns named issues with severity and no matched secret text: V01 sc
133
178
  A successful receipt reports `applied`, planned path/hash/byte changes, issues and `indexUpdated`. Unrelated malformed legacy YAML is skipped by duplicate hints and by writer index refresh, with a V01 warning naming the unchanged note; normal read/rebuild commands retain strict parsing. Move/tidy still require parseable inputs and name the offending path on refusal. Reads allocate each note's stat size plus one growth-probe byte, capped at the 2 MiB read limit plus one. A failed index refresh rolls back the file changes. Rollback first verifies each file still equals this operation's committed result; external edits are preserved. Failed/refused rollback retains the original backup and reports its relative recovery path. All files are staged before replacement and backups permit rollback of caught multi-file failures. Each individual rename is atomic; a machine/process crash between multiple renames can leave a partially completed batch. The retained lock and `.vmem-<uuid>.tmp` files require inspection and manual recovery after confirming the writer stopped. They are never automatically removed by registry recovery. Uncoordinated editors do not honor the lock; the pipeline rechecks SHAs before replacement, but this does not provide a filesystem transaction against concurrent external edits. Existing notes may be read up to the index's 2 MiB limit; prospective notes are limited to 256 KiB; report operations under `reports/` and `ops/` allow up to 16 MiB for both prospective content and existing-file reads (including staging and rollback rechecks), with at most 10000 flat notes per mutation snapshot. File/directory fsync has the platform guarantees described above. Successful changed mutations now append an event as described below; log failure is reported separately from note success.
134
179
 
135
180
 
181
+
182
+ ## Note merge
183
+
184
+ `vmem merge <vault> <keep> <absorb>` and `vmem_merge` preview a lossless merge, then require `confirm` with that preview's fingerprint. Preview creates no lock, cache or vault file. The JSON receipt's `merge` object contains `keep`, `absorb`, the full merged `body`, stable keep-first `source` and `topics` unions, and `inboundLinks` with original path, field, target, replacement, body-relative line and optional fragment. Human output shows the plan and confirm command; `--json` shows the full body.
185
+
186
+ ```sh
187
+ vmem merge personal retained-note duplicate-note --json
188
+ vmem merge personal retained-note duplicate-note --confirm --fingerprint <sha> --json
189
+ ```
190
+
191
+ Keep's H1 and prose remain first. Absorb's leading `# <title>` line is removed only when it is the first non-blank line of the original body, before Topics extraction; its other ATX headings are demoted one level (H6 stays H6), and its content follows `## Merged from [[absorb]]`. No prose is summarized; fenced and inline code, including multiline spans, stay unchanged. Setext headings and ambiguous blocks stay byte-unchanged. Raw HTML blocks are preserved conservatively from a line starting with up to three spaces then `<` through the next blank line. Both plain Topics lists become one final union `## Topics`; unusual prose/code or mismatched lists in Topics refuse with a repair step so nothing is silently dropped. Source union over 32 entries refuses instead of discarding provenance. Notes must have the same type; person and MOC notes, identical endpoints, and content over the 256 KiB write bound refuse.
192
+
193
+ Confirm recomputes the plan under the shared vault lock, writes keep, repoints existing inbound references using move's path-only rewrite (preserving labels/fragments), and marks absorb `status: superseded`, `superseded_by: [[keep]]`. The absorb file stays. The new provenance heading intentionally links to absorb. Fragment collision checks use the same anchor index as the link reader. Referenced heading/block collisions already present in keep refuse with V03, including absorb's fragment-only self-links (`[[#Heading]]`, `[[#^id]]`) whose containing note changes on copy: rename the conflicting anchor before a new preview; unreferenced duplicate anchors are allowed. Normal link/metadata/secret/PII validation still applies, and new broken fragments refuse. If keep is already `superseded_by: [[absorb]]`, or absorb has `supersedes: [[keep]]`, keep is older and V10 asks you to swap the endpoints. A keeper `supersedes: [[absorb]]` relationship is retained as provenance and excluded from repointing. `updated` changes only on keep and absorb; mechanical inbound rewrites retain dates. All note changes use the existing staged writes and rollback, followed by one default RETHINK event (or the existing `log` override). A post-publication log failure keeps `applied: true` and the failing log receipt; notes are not rolled back after an ambiguous append. A stale fingerprint refuses without changing note bytes. An MCP plan exceeding the bounded full acknowledgement is refused before publication with guidance to use CLI preview and confirm or reduce the inputs.
194
+
136
195
  # Append-only events
137
196
 
138
197
  ```sh
@@ -148,7 +207,7 @@ Every MCP log append and CLI call with a nonempty `AGENTHUB_PEER_ID`, `CLAUDECOD
148
207
 
149
208
  `appendLog` validates the registered canonical vault and write/channel policy, acquires a separate `log.lock` (bounded two-second contention wait), then makes one O_APPEND write and fsyncs the log. New log files are mode 0600 and their parent directory is flushed. Linked/nonregular files and an incomplete existing final line are refused. Cooperating appenders share the lock; a short write is truncated back only when the same file still has the expected size, and its tail still equals our exact prefix, then flushed. Error-after-write cases inspect at most one event's bytes. Failed/ambiguous writes or cleanup are explicit; the receipt reports `appended` (possibly null when unknown), `synced`, `bytesWritten` (possibly null) and `rolledBack` when a partial append was removed. Before reporting sync, the current log and vault identities are rechecked; rotation produces LOG_DRIFT and an unknown current-path append state. A synced event can coexist with a cleanup error. No existing event is rewritten. A crash can retain `log.lock`, and failed short-write recovery can retain an incomplete line; inspect the file and stopped writer before manual recovery. There is no automatic cleanup or new TTY requirement.
150
209
 
151
- Successful changed mutations default to EXTRACT, link to CONNECT, move to ROUTE, and supersede/tidy to RETHINK. Default events use project `-`, affected paths and the operation name rather than note text. Library callers can supply `WriteRequest.log` to override the event or `false` to disable it. Every MCP write tool (`vmem_create`, `vmem_patch`, `vmem_append`, `vmem_set_frontmatter`, `vmem_link`, `vmem_supersede`, `vmem_move`, `vmem_delete`) takes the same optional `log` object (`type`, `project`, `source`, `note`, optional `dest`); move and delete use it on the confirm call. The CLI writers `new`, `patch`, `append`, `frontmatter`, `link`, `supersede`, `move`, `delete` and `report` take the same object as `--log JSON`, checked against the same closed schema (unknown keys, a missing field or a bad type are refused); omitting it keeps the default event. `tidy --log` is the unrelated redaction rule. Preview/check/no-op/refused mutations never append. The append is bound to the mutation's resolved vault identity/policy, so re-registration cannot route its event to another vault; the same binding covers the tidy LINT event and both SYNC events of org promotion, which are refused with LOG_DRIFT instead. A bound append compares the registry before any policy or path check, so a re-registration always reads as LOG_DRIFT. Tidy and org promotion also bind every note write to the vaults resolved at the start of the run: if a vault id is re-registered before a write, that write is refused with VAULT_DRIFT and nothing is written to either vault. After a committed mutation, log append is independent: `ok`/`applied` describe the note operation, `log` holds its append receipt, and `logged` is true only when the event was appended and synced. A log error does not roll back a successfully saved note. CLI exits 1 for a log failure even when the note receipt says `ok: true`; inspect the receipt before retrying to avoid duplicate mutations/events. A given event is validated and screened like `log append` (type, registry project id, fields, secret/PII screening, line bound) before any lock or note change, also on dry runs and previews: an invalid event refuses the whole write with its L09/V06/V07/V09 issue and nothing changes. The event is not part of the move/delete fingerprint.
210
+ Successful changed mutations default to EXTRACT, link to CONNECT, move to ROUTE, and supersede/tidy/merge to RETHINK. Default events use project `-`, affected paths and the operation name rather than note text. Library callers can supply `WriteRequest.log` to override the event or `false` to disable it. Every MCP write tool (`vmem_create`, `vmem_patch`, `vmem_append`, `vmem_set_frontmatter`, `vmem_link`, `vmem_supersede`, `vmem_merge`, `vmem_move`, `vmem_delete`) takes the same optional `log` object (`type`, `project`, `source`, `note`, optional `dest`); move, delete and merge use it on the confirm call. The CLI writers `new`, `patch`, `append`, `frontmatter`, `link`, `supersede`, `merge`, `move`, `delete` and `report` take the same object as `--log JSON`, checked against the same closed schema (unknown keys, a missing field or a bad type are refused); omitting it keeps the default event. `tidy --log` is the unrelated redaction rule. Preview/check/no-op/refused mutations never append. The append is bound to the mutation's resolved vault identity/policy, so re-registration cannot route its event to another vault; the same binding covers the tidy LINT event and both SYNC events of org promotion, which are refused with LOG_DRIFT instead. A bound append compares the registry before any policy or path check, so a re-registration always reads as LOG_DRIFT. Tidy and org promotion also bind every note write to the vaults resolved at the start of the run: if a vault id is re-registered before a write, that write is refused with VAULT_DRIFT and nothing is written to either vault. After a committed mutation, log append is independent: `ok`/`applied` describe the note operation, `log` holds its append receipt, and `logged` is true only when the event was appended and synced. A log error does not roll back a successfully saved note. CLI exits 1 for a log failure even when the note receipt says `ok: true`; inspect the receipt before retrying to avoid duplicate mutations/events. A given event is validated and screened like `log append` (type, registry project id, fields, secret/PII screening, line bound) before any lock or note change, also on dry runs and previews: an invalid event refuses the whole write with its L09/V06/V07/V09 issue and nothing changes. The event is not part of the move/delete/merge fingerprint.
152
211
 
153
212
  Readers never create a home, log or lock, and work with `write: none`. They skip blank/comment lines, return the last matching 1..200 records (default 50), accept an optional canonical TYPE and non-backtracking regex subset up to 256 characters (`|`, `^`, `$`, `.`, character classes, `\d`/`\s`/`\w` and their inverses, escaped literals, and atom `*`/`+`/`?`; groups, backreferences and brace quantifiers are refused), and scan a fixed descriptor-size snapshot. Streaming is capped at 32 MiB; individual historical lines over 4096 bytes and incomplete final lines are omitted with warnings, and the serialized line array stays within 128 KiB. Above 20000 data lines, the manual-archival warning is preserved. Read failure returns `dataLines: null` rather than claiming a count. Golden synthetic fixtures and concurrent/fault persistence tests cover the format and actual append state; no live vault log was read or modified for this increment.
154
213
 
@@ -161,13 +220,15 @@ vmem stats personal --days 7 --json
161
220
 
162
221
  `vmem stats <vault>` and `vmem_stats` report note counts (total, by `type`, `domain` and frontmatter `status`; empty values count as `(none)`), notes whose indexed mtime falls in the last 7 and 30 local calendar days (today included), and log event counts by type dated on or after `log.since`, the first local date of the `--days` window (1..3650, default 30). Known types always appear, unknown ones count as `(other)`. The derived index cache is refreshed as by every read command and the log is streamed with the bounded log reader; no vault file or log is written and no vault or log lock is taken. When the log cannot be read, `log.total` and `log.byType` are null, `log.issues` names the cause and the CLI exits 1.
163
222
 
223
+ `size` adds the note text size in bytes and words, as `total` and by `type` and `domain` (`{ notes, bytes, words }` each); words are the whitespace-separated tokens of the stored source, frontmatter included. `ratio` compares each note with the workspace files its frontmatter `source` cites: the note's byte size over the summed size of those files, reported as `median` and `p90` over the notes that qualified (p90 by nearest rank, both null when none did), with `overOne` counting the notes larger than their sources and `largest` listing up to five of them by ratio. `notes` and `sources` are the counts behind those figures. Each source counts at its own byte size on disk, not at the size of its decoded text, so a file that is not UTF-8 contributes its real bytes instead of the three bytes each invalid byte becomes when decoded. `skipped` counts only the source references left out of the ratio, `skippedNonFile` of them memory ids or URLs rather than files; a path is skipped too when it is denied, missing or unreadable, is past the 2 MiB auxiliary read bound or past the bytes the budget has left, or the call reaches its own limits. Those limits bound the reads and not only the counts: 64 MiB of source bytes and 10000 read attempts, failed or not, where each read asks only for the bytes the budget has left, a larger file is refused from its size without being read, and nothing further is opened once the budget is spent. A note whose readable sources total zero bytes has no ratio and is counted in `emptySourceNotes` instead, so a file that was read and found empty is never also reported as a skipped reference. `truncatedNotes` counts the notes that declare a `source` but fall past the index's 10000-note cap, in path order, so the figures describe those notes and not every sourced note. Source paths resolve from the workspace root found by walking up from the vault's registered project registry; a vault with no registered workspace reads nothing and skips every entry. A note without a `source` is not part of the ratio. The pass reuses the bounded auxiliary reader, which follows no link, and writes neither the vault nor the sources.
224
+
164
225
  `vmem_list` pages the whole vault: pass the returned `nextCursor` as `cursor` to get the next page in path order. The cursor is the previous page's last path (exclusive), so a note added or removed between pages does not repeat or skip the others; a cursor outside the `prefix` filter is refused.
165
226
 
166
227
  # MCP server
167
228
 
168
229
  `vmem mcp` serves newline-delimited JSON-RPC 2.0 (MCP tools, protocol 2025-06-18 and earlier) on stdio. stdout carries protocol messages only; it needs no TTY and runs in agent sessions. Requests are limited to 64 KiB per frame and results to 256 KiB (a larger result becomes a structured `LIMIT` refusal). Arguments are validated against each tool's bounded schema (`additionalProperties: false`, string/array/integer caps); invalid arguments or unknown tools return JSON-RPC `-32602`, unknown methods `-32601`, malformed frames `-32700`/`-32600`. At startup it loads every module a tool can run, the `@staix/agent-mem` root included, so a server keeps its own code and tool list when its install is replaced or a newer release is installed beside it; restart the host session to pick up the new release.
169
230
 
170
- The vault set is read once at startup: every tool's `vault` property is an enum of the registered ids and defaults to the first `personal` vault. Restart the host session after `vaults add/remove`. Registered spec sources are also read once when `vmem mcp` starts; restart the MCP server after `specs add` or `specs remove`. Reads go through the same index as the CLI; writes go through `applyWrite`/`appendLog` with channel `mcp`, so they require `write: mcp` and pass the same V01-V10 gates. Every tool returns a JSON result: a receipt, or `{refused: true, issues}` for policy, validation or lookup failures.
231
+ The vault set is read once at startup: every tool's `vault` property is an enum of the registered ids and defaults to the first `personal` vault. Restart the host session after `vaults add/remove`. Registered spec sources are also read once when `vmem mcp` starts; restart the MCP server after `specs add` or `specs remove`. Reads go through the same index as the CLI; writes go through `applyWrite`/`appendLog` with channel `mcp`, so they require `write: mcp` and pass the same V01-V10 gates. Every tool returns a JSON result: a receipt, or `{refused: true, issues}` for policy, validation or lookup failures. Direct note-write tools return an applied-with-errors receipt (`applied: true`, `ok: false`) without `refused: true`; inspect and recover the recorded write instead of retrying it as an unapplied refusal. Spec mutations add `refused: true` only when no change was applied (`ok: false`, `changed: false`); post-publication errors return the applied receipt (`changed: true`, `ok: false`) without that marker.
171
232
 
172
233
  | tool | arguments (caps) |
173
234
  |---|---|
@@ -180,7 +241,7 @@ The vault set is read once at startup: every tool's `vault` property is an enum
180
241
  | `vmem_read` | `path` (stem, alias or `notes/` path), `vault`, `maxBytes`<=65536; returns `{path, frontmatter, body, sha256, truncated}` |
181
242
  | `vmem_read_many` | `paths`<=20 (8 KiB each), `vault` |
182
243
  | `vmem_list` | `vault`, `prefix`, `limit`<=500, `cursor`; rows in path order with `mtime`, the filtered `total` and `nextCursor` while more remain |
183
- | `vmem_links` | `path`, `vault`, `direction` out/in/both, `limit`<=200; returns `{out, dead, in}` |
244
+ | `vmem_links` | `path`, `vault`, `direction` out/in/both, `limit`<=200; returns `{out, dead, in}`, each `dead` entry with `suggested` (the closest title and its score, or null; a hint, never a rewrite) |
184
245
  | `vmem_mocs` | `vault`; MOC notes with incoming link counts |
185
246
  | `vmem_check` | `vault`, `path`, `text`<=256 KiB; validation only |
186
247
  | `vmem_log_tail` | `vault`, `n`<=200, `type`, `grep`<=256 |
@@ -192,19 +253,28 @@ The vault set is read once at startup: every tool's `vault` property is an enum
192
253
  | `vmem_supersede` | `old`, `next`, `log` |
193
254
  | `vmem_log_append` | `type`, `project`, `source`, `dest`, `note`<=500 |
194
255
  | `vmem_move` | `from`, `to`, `confirm`, `fingerprint` (two-step), `log` (on confirm) |
256
+ | `vmem_merge` | `keep`, `absorb`, optional `confirm`, `fingerprint`, `log`; full body/source/topic/inbound preview, then locked merge and supersession |
195
257
  | `vmem_delete` | `path`, `confirm`, `fingerprint` (two-step; the preview lists backlinks), `log` (on confirm) |
196
258
  | `vmem_promote` | `path` (in the personal vault), `to` (enum of org vaults), `topics[]`, `again`, `confirm`, `fingerprint` (two-step; never pushes) |
197
259
  | `vmem_skills_mine` | `vault`, `days`, `project`, `allProjects`, `vocab`, `skills[]`, `minSize`, `minNovelty` (read-only; see Skill mining) |
198
- | `vmem_stats` | `vault`, `days`<=3650 (default 30); read-only counts, see Vault statistics |
260
+ | `vmem_stats` | `vault`, `days`<=3650 (default 30); read-only counts, note size and note-to-source ratio, see Vault statistics |
199
261
  | `vmem_promote_from_amem` | `id`, `project`, `stem`, `type`, `domain`, `topics[]`, `description`, `title`, `body`<=65536, `linkTo`, `confirm`, `fingerprint` (two-step) |
200
262
  | `vmem_read_file` | `path`, `vault`, `maxBytes`<=65536, `offset`<=2097152; returns `{path, sha256, truncated, body, offset?, nextOffset?}` (read-only; allowed roots below the table) |
201
263
  | `vmem_list_files` | `dir`, `vault`; one level, <=500 entries `{name, path, type, bytes?}` (read-only) |
202
264
  | `vmem_report` | `path` under `reports/` or `ops/`, `body`<=65536, `dryRun`, `log`; the receipt of `vmem report` |
203
265
 
266
+ <!-- facts:mcp-tools -->
267
+
268
+ `vmem mcp` lists 36 tools: `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_merge`, `vmem_delete`, `vmem_promote_from_amem`, `vmem_lint`, `vmem_graph_build`, `vmem_graph_neighbors`, `vmem_promote`, `vmem_skills_mine`, `vmem_read_file`, `vmem_list_files`, `vmem_report`, `vmem_stats`, `vmem_spec_get`, `vmem_spec_graph`, `vmem_spec_grep`, `vmem_spec_validate`, `vmem_spec_create`, `vmem_spec_update`, `vmem_spec_delete`.
269
+
270
+ <!-- /facts:mcp-tools -->
271
+
204
272
  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/`.
205
273
 
206
274
  File reads and reports: `vmem_read_file` and `vmem_list_files` read only these roots: `ops/`, `reports/`, `self/`, `templates/`, `AGENTS.md` and `README.md`. They refuse `notes/` (use `vmem_read`), `log` (use `vmem_log_tail`), absolute paths, `.` or `..` segments, dot paths such as `.git`, any symlinked component, denied paths, non-UTF-8 files and files over 2 MiB. Paging, `maxBytes` and `offset` match `vmem_read`; listings leave out dot, linked, special and denied entries. Neither tool takes a lock, touches the index or writes a file. `vmem_report` is `vmem report` over MCP: the same path rules, screening, receipt and default `EXTRACT` event (a `log` override sets another event, for example `LINT` or `GRAPH`), with `write: mcp` required; MCP events always carry the agent attribution.
207
275
 
276
+ The `initialize` result carries short `instructions` (under 400 bytes): the vault is durable, linked knowledge; search first with `vmem_search`, then read the best match with `vmem_read` by section; writes are validated and receipted, and because a failure after publication can leave changes behind, read the receipt and its issues before retrying. The receipt state field differs by tool: `applied` and `changes` for vault writes, `changed` for spec writes.
277
+
208
278
  # Host setup
209
279
 
210
280
  ```sh
@@ -234,20 +304,25 @@ vmem promote-from-amem personal mem:<id> ... --confirm --fingerprint <sha>
234
304
  vmem promote-from-amem personal mem:<id> --link-to existing-note # link an existing note instead of creating one
235
305
  ```
236
306
 
237
- - `src/amem/seam.ts` is the only module that imports the `@staix/agent-mem` root (exact pin 0.17.0, at or above agent-mem's 0.13 floor for agent workflows). Reads, writes and other commands never load it; promotion and mining load it when they run, and `vmem mcp` loads it at startup. The project defaults to agent-mem's key for the current directory (`--project` overrides); `AMEM_HOME` selects the memory home as in agent-mem.
307
+ - `src/amem/seam.ts` is the only module that imports the `@staix/agent-mem` root (exact pin <!-- facts:amem-version -->0.23.0<!-- /facts:amem-version -->, at or above agent-mem's 0.13 floor for agent workflows). Reads, writes and other commands never load it; promotion and mining load it when they run, and `vmem mcp` loads it at startup. The project defaults to agent-mem's key for the current directory (`--project` overrides); `AMEM_HOME` selects the memory home as in agent-mem.
238
308
  - Listing and linking require agent-mem's generation profile; a shared-v1 memory home is refused. Candidate listing applies agent-mem's durable selection and policy (secrets, default PII and the vault config's `piiPatterns`) before ordering and `--limit`; previews screen the requested entry with the same policy.
239
309
  - The preview prefills the H1 and stem from the entry title, the body from its text, `about[]` as Relevant Notes hints, and provenance `promoted_from: mem:<id>` plus `promoted_at`. `--stem --type --domain --topics --description --title` and `--body file|-` override it; none of this needs a TTY. When a note with the same stem or title exists, the preview is refused with V08 and lists `link-existing <path>` choices; `--link-to` takes one. `--edit` opens `$VISUAL`/`$EDITOR` on the draft only when stdin is a terminal (the only TTY check); the edited text is previewed and confirmed with `--body`.
240
310
  - Confirm requires the preview fingerprint, then creates the note through `applyWrite` (V01-V10), appends one `LEARN <project> mem:<id> → notes/<stem>.md <em-dash> promoted: <kind>` event (`--log-project` sets the project field; it defaults to the last segment of the agent-mem project key) and records the vault link last.
241
311
  - If the final link fails, the note stays, the result reports `LINK` and `link-only notes/<stem>.md`, and the entry stays a candidate. A rerun finds the note through `promoted_from` and offers link-only, never a second note or a second LEARN event.
242
312
  - `vmem_promote_from_amem` is the same two steps over MCP and needs a vault with `write: mcp`.
243
313
 
314
+ Configured canonical tables add `canonRowMatches: [{path,line,key,row}]` to promotion results and deduplicated `link-existing <path>` choices. Keys come from the selected Markdown-table column: bold, wiki brackets and inline code are stripped; parentheses, comma and spaced-slash aliases are split; one-character keys are ignored. Matching uses whole-token Unicode boundaries, ignoring case only for Latin characters, including in mixed-script keys. Matches rank by key length, then configured table/row order, with at most five distinct rows and 200 characters of row text. Text output lists "canonical rows" beside possible duplicates. `vmem promote --to <org>` uses only the org target's own tables; personal-vault rows never appear in its preview.
315
+
316
+ Rows and `canonTableWarnings` are advisory, outside the fingerprint: changing `canonTables` leaves a preview valid, while draft and note edits still invalidate it. A table is a header row followed by a delimiter row whose cells each hold one or more hyphens with optional leading and trailing colons, as GFM allows, so `|-|-|`, `|--|--|` and `| :-: | - |` all open a table. A missing/unreadable/denied note produces `canonTables: <path> not read (<cause>)` plus recovery advice, and a note that reads but holds no recognizable table produces `canonTables: <path> has no recognizable Markdown table` with what a table needs, so an empty `canonRowMatches` names its cause instead of staying silent. With no `canonTables` key, JSON and text output retain their previous shape. Reads reuse the open target note index with its 2 MiB per-note limit, an 8 MiB aggregate byte budget and at most 16 attempts; parsing is bounded to 20000 rows, 40000 aliases and 256 KiB of key text. There are no model calls, embeddings, automatic row edits or canonical-row lint rules.
317
+
244
318
  ## Console plugin
245
319
 
246
320
  `vmem setup <target> --apply` also writes `$AGENTHUB_HOME/console/plugins/vmem.json` (default `~/.agenthub`; directory 0700, file 0600) with the absolute path and sha256 of `src/ui/plugin.ts`. `acon ui` then shows a Vault area. The panel needs agent-console 0.1.0 or later, the first release with the `host.ui` panel kit and `ui.button`. An older acon still loads the plugin, but the panel then fails with a TypeError on `host.ui`; upgrade agent-console to fix it. Re-run setup after upgrading vmem: acon refuses a module whose hash changed.
247
321
 
248
322
  - Panels: Overview (vaults, maps, recent log), Search, Note (body, links, actions), Promote (agent-mem candidates), Lint (typed findings linked to notes) and Log (parsed rows).
249
323
  - Inbox: promotion candidates (group `candidate`), lint errors, a stale graph report and org-vault sync pending (group `alert`). Sync pending counts uncommitted paths plus local commits ahead of the upstream tracking ref; without an upstream it counts only uncommitted paths. It reads local Git state only (no fetch or credential prompt) and opens Overview with that vault, with no one-key sync verb. The palette searches notes.
250
- - Inbox snapshots share one background refresh, with one worker source at a time. A cold snapshot waits at most 700 ms and then shows a refreshing status row; `refreshing: true` also marks an active collection. Later snapshots keep serving the last complete rows while refreshing. A source failure retains its last rows; if every source is unavailable at startup, a separate unavailable status row opens Overview and advises checking System. Refreshes are cached for 60 seconds, including failed attempts. Applied writes invalidate freshness without clearing the rows.
324
+ - Inbox snapshots share one background refresh, with one worker source at a time. A cold snapshot waits at most 700 ms and then shows a refreshing status row; `refreshing: true` also marks an active collection. Later snapshots keep serving the last complete rows while refreshing. A source failure retains its last rows; if every source is unavailable at startup, a separate unavailable status row opens Overview and advises checking System. Snapshots are cached by the registered vault logs and registry metadata (inode, size and nanosecond modification/change times), a 256-byte log tail and the size-limited registry contents, without opening Git or scanning notes on a warm poll. Applied console writes invalidate freshness even if their log receipt failed. Revision-triggered refreshes wait at least 10 seconds from the start of the last collection, so sustained vault log appends cannot rerun every source on each poll, while an applied console write still refreshes on the next poll. A matching numeric `after` cursor returns only `{changed:false,cursor}`. An in-flight first collection waits only on its first request, so repeated rail polls return immediately. A 60-second safety refresh retains freshness for new agent-mem candidates, direct edits without a log receipt, and failed-source retries.
325
+ - Promote scans are single-flight and cached by the same revision, with the same 60-second safety refresh. Brief candidate titles are capped at 160 characters; pages include at most 32 KiB of serialized UTF-8 JSON, including their envelope. `nextPage` is passed back as `page`; an actually changed candidate set makes a stale page restart at the first page, or the selected candidate, and the panel hides `First page` when that reply is page 0. Identical rescans keep page tokens and conditional cursors stable. Unreadable revision evidence degrades to a stable error stamp; source collection retains its existing failure isolation and recovers when the file is readable again. A matching `after` cursor returns `{changed:false,cursor}` for that page and selection. Failed scans reuse one error cursor until a scan succeeds, so the panel does not rebuild the same error view on each poll; recovery sends full rows even if candidates are identical. Under continuous revision changes, collection makes at most two scans per request and serves the last completed pages at their old revision; the next request retries freshness. The current console contract pin has no `maxAgeMs` or `inboxMaxAgeMs`; these hints await agent-console#105.
251
326
  - The inbox returns at most 50 rows, errors and alerts first, then newest candidates, with titles capped at 160 Unicode code points and detail at 240. `more` counts omitted rows. Because agent-mem limits candidates per project and exposes no total-count API, vmem fetches 51 per project to detect overflow: when `moreIsLowerBound: true`, read `more` as "at least N more", not an exact total. That lower bound does not decrease when candidates are added to the same population, but may stay flat once a project reaches the fetch limit. A source failure retains its previous count too. Full candidate and lint details are available in their panels. Each source has a 30-second budget to initiate worker termination; shutdown may wait for an active native call, without blocking inbox responses.
252
327
  - Actions: `delete`, `move`, `promote` (to an org vault) and `promote-from-amem` reuse the two-step MCP tools. Each first answers a preview with the planned changes; the write happens only after the console's confirm dialog, and only while the fingerprint still matches.
253
328
  - The provider calls the `vmem mcp` handlers in process, so the console has exactly the MCP rights: writes need a vault with `write: mcp`, and log lines carry the agent attribution.
@@ -255,7 +330,7 @@ vmem promote-from-amem personal mem:<id> --link-to existing-note # link an exis
255
330
 
256
331
  ## Lint and graph analysis
257
332
 
258
- `vmem lint <vault>` checks L01/L02/L03/L09/L10/L11/L12 and L13 (lowercase ASCII kebab-case filenames). `--note notes/example.md` limits note findings. Section names and `SUMMARY errors=N warnings=N` follow the Python reference. `--write` writes a screened lint report and LINT event; `--dry-run` previews without persistence. Findings may identify paths, link targets and malformed log prefixes. Note bodies are never included in analysis results.
333
+ `vmem lint <vault>` checks L01/L02/L03/L09/L10/L11/L12 and L13 (lowercase ASCII kebab-case filenames). An L01 finding for a dead link adds at most one suggested existing target and its title score, dropped when no title scores above the minimum; the hint is reported and the link is never rewritten. Hints are computed for at most 1000 distinct dead link texts per run: a text past that bound is reported as `hint not computed (cap 1000)` with the count left out, never as a missing match. L15 is a warning, not a write error: a note with `confidence: proven` and an empty `source` (absent, empty string or empty list) is listed with what to add, and existing notes are never refused. `--note notes/example.md` limits note findings. Section names and `SUMMARY errors=N warnings=N` follow the Python reference. `--write` writes a screened lint report and LINT event; `--dry-run` previews without persistence. Findings may identify paths, link targets and malformed log prefixes. Note bodies are never included in analysis results.
259
334
 
260
335
  `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. A `- [[x]] (relation)` line written by `vmem link --relation` keeps its relation as `rel` on the `wiki_link` edge (`supports`, `contradicts`, `extends`, `applies-to`, `context-for`); other links carry no `rel`. Edges stay undirected, so `rel` does not say which note supports which, and when a pair carries different relations the first in note path order is kept. `vmem graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--relation REL]` reads a bounded neighborhood; `--relation` (MCP `relation`) follows only edges of that relation, `wiki_link` meaning untyped links, and an unknown relation is refused. Matching MCP tools are `vmem_lint`, `vmem_graph_build`, and `vmem_graph_neighbors`; MCP report writes require `write=mcp`.
261
336
 
@@ -304,11 +379,11 @@ vmem sync team --confirm --fingerprint <sha>
304
379
 
305
380
  `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.
306
381
 
307
- - **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.
382
+ - **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`, `summary`, `Recap` or `Compact` (the excerpt), opened read-only. `Record` excerpts are parsed by agent-mem's `parseRecordLines`: mined kinds are `decision`, `fix`, `fail`, `contract` or `finding`, with parsed anchors appended to the text as matching context. Excerpts with no parsed records, parser drops or an incomplete parse are dropped as whole rows and counted in JSON `dropped.malformedRecord` and the Markdown dropped line; they never enter mining as raw text. `Title` and 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.
308
383
  - **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`.
309
384
  - **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).
310
385
  - **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.
311
- - **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.
386
+ - **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. JSON `dropped.truncatedCapture` and the Markdown report count truncated machine shards; rows of any event beyond `maxReadRows` were not read. This count describes shards, not excluded rows by event. The pinned CaptureStore API cannot count `Record` rows outside the window; an event-filtered upstream API remains a follow-up, without raw database scans or a larger read bound.
312
387
 
313
388
 
314
389
 
@@ -318,8 +393,8 @@ vmem sync team --confirm --fingerprint <sha>
318
393
 
319
394
  - `bun run parity:release` checks same-snapshot frontmatter bytes, incremental notes/FTS/links against clean rebuild, and two consecutive synthetic Python-oracle lint/graph comparisons. External Python reference paths can be supplied with `--lint-reference` and `--graph-reference`; `--output` records aggregate evidence.
320
395
  - `bun run release:verify` enforces committed runtime/method/external-parity evidence freshness and the declared synthetic thresholds at the explicit release gate. Ordinary tests validate evidence shape and internal sample consistency; routine source edits and version bumps do not require fresh benchmark evidence until release validation.
321
- - `bun run bench:release --output <file.json>` measures a generated 5000-note corpus in the authorized Linux dgx02 container. It records actual MCP search round-trip timings (including metadata refresh), kernel RSS high-water, the derived index size after rebuild (`indexBytes`), raw samples and environment; it exits nonzero when a synthetic threshold fails. Synthetic write timings are diagnostic and do not establish representative private-vault acceptance.
322
- - [Readiness evidence](docs/release-readiness.md), [release workflow](docs/release-workflow.md) and [cutover checklist](docs/cutover-checklist.md) distinguish verified results from outstanding private/native/integration/deployment gates. Live cutover remains blocked.
396
+ - `remote_dev.py run --cgroup <worktree> -- 'bun run bench:release --output <file.json>'` measures a generated 5000-note corpus in the authorized Linux container with writable `REMOTE_DEV_CGROUP` memory delegation. It records MCP search round-trip timings (including metadata refresh), cgroup `memory.peak`, sampled VmRSS/VmHWM, the rebuilt index size (`indexBytes`), raw samples and environment. Both peak values must be below 200 MB; charged cgroup memory excludes pages first charged by the harness and is not an RSS upper bound. The command exits nonzero when a synthetic threshold fails. Synthetic write timings are diagnostic and do not establish representative private-vault acceptance.
397
+ - [Readiness evidence](docs/release-readiness.md), [release workflow](docs/release-workflow.md) and [cutover checklist](docs/cutover-checklist.md) distinguish verified results from outstanding private/native/integration/deployment gates. Live cutover is covered by the Status paragraph at the top.
323
398
 
324
399
 
325
400
  ## Core operating compatibility
@@ -372,9 +447,9 @@ vmem specs remove project-specs --confirm
372
447
 
373
448
  The config `specs` array holds `id`, canonical git working-tree root `path`, `write` (`mcp|cli|none`, default `none`) and `pii` (`allow|deny`, default `deny`). IDs are unique across vaults and spec sources. A spec source does not need a `notes/` directory. Registration and removal reuse the vault registry lock and atomic config write. Removal previews first, then `--confirm` unregisters only; repository files remain in place.
374
449
 
375
- Config writes containing `specs` use at least format 2; vault `domains` requires format 3. A config without either keeps its existing serialization and version field. `status` lists spec entries under a separate `specs` key, and `doctor` checks that every registered path is still its canonical git working-tree root. An unavailable or changed root makes doctor exit 1 with a per-source issue. Existing vault entries remain valid; `vaults list` also reports each effective domain set.
450
+ Config writes containing `specs` use at least format 2; vault `domains` requires format 3 and vault `canonTables` requires format 4. Without these fields, the existing serialization and version field are retained. `status` lists spec entries under a separate `specs` key, and `doctor` checks that every registered path is still its canonical git working-tree root. An unavailable or changed root makes doctor exit 1 with a per-source issue. Existing vault entries remain valid; `vaults list` also reports each effective domain set.
376
451
 
377
- The registry, read-only MCP tools and CLI commands are implemented. `resolveSpecWorktree` checks the registered git common directory; `discoverSpecs` discovers nested Markdown specs in memory; `SpecIndex` reuses the vault scanner and BM25 with a separate `spec-` cache prefix per canonical worktree. Call `scan()` to refresh a `SpecIndex`; its `snapshot()` uses the last completed scan and `search()` admits only shared-cache rows matching that snapshot's paths and hashes. Call `scan()` again to see documents another index instance inserted or replaced. A failed scan invalidates the instance snapshot; the next read refreshes it or propagates the original failure. `buildSpecGraph` resolves typed links by frontmatter id, and `specSlice` returns bounded subtree/ancestor/neighbor slices (depth 0..3, at most 500 nodes). Discovery uses Git's tracked/untracked non-ignored Markdown list, reports skipped symlinks/missing/nonregular paths, accepts NFC/NFD and filesystem case aliases, and keeps the first duplicate id in NFC path order with a diagnostic. Root device/inode identity and per-file physical containment remain checked while accepting these spelling aliases. Unknown type/status strings remain readable. To exclude large or vendored untracked Markdown, add it to `.gitignore`; already-tracked ignored files must also be untracked with `git rm --cached`. Discovery/indexing is bounded to 10000 Markdown inputs, 2 MiB each and 64 MiB total; graphs allow 10000 inputs and 100000 unique edges. Graph results omit raw note sources. Library validation (`validateSpecs`), introduced-error comparison (`introducedSpecErrors`), computed freshness (`specFreshness`), tracked-file ownership (`specsCoveringPath`) and registry-free CI logic (`validateSpecRepo`) are implemented. The read tools are `vmem_spec_get`, `vmem_spec_graph`, `vmem_spec_grep` and `vmem_spec_validate`. Spec content tools `vmem_spec_create`, `vmem_spec_update` and `vmem_spec_delete` are not implemented (T4, #97); `write` stores a policy for later capabilities. Commands do not edit repository content or run git commit, branch or push.
452
+ The registry, read-only MCP tools and CLI commands, spec creation, frontmatter-only update and two-step deletion are implemented. `resolveSpecWorktree` checks the registered git common directory; `discoverSpecs` discovers nested Markdown specs in memory; `SpecIndex` reuses the vault scanner and BM25 with a separate `spec-` cache prefix per canonical worktree. Call `scan()` to refresh a `SpecIndex`; its `snapshot()` uses the last completed scan and `search()` admits only shared-cache rows matching that snapshot's paths and hashes. Call `scan()` again to see documents another index instance inserted or replaced. A failed scan invalidates the instance snapshot; the next read refreshes it or propagates the original failure. `buildSpecGraph` resolves typed links by frontmatter id, and `specSlice` returns bounded subtree/ancestor/neighbor slices (depth 0..3, at most 500 nodes). Discovery uses Git's tracked/untracked non-ignored Markdown list, reports skipped symlinks/missing/nonregular paths, accepts NFC/NFD and filesystem case aliases, and keeps the first duplicate id in NFC path order with a diagnostic. Root device/inode identity and per-file physical containment remain checked while accepting these spelling aliases. Unknown type/status strings remain readable. To exclude large or vendored untracked Markdown, add it to `.gitignore`; already-tracked ignored files must also be untracked with `git rm --cached`. Discovery/indexing is bounded to 10000 Markdown inputs, 2 MiB each and 64 MiB total; graphs allow 10000 inputs and 100000 unique edges. Graph results omit raw note sources. Library validation (`validateSpecs`), introduced-error comparison (`introducedSpecErrors`), computed freshness (`specFreshness`), tracked-file ownership (`specsCoveringPath`) and registry-free CI logic (`validateSpecRepo`) are implemented. The read tools are `vmem_spec_get`, `vmem_spec_graph`, `vmem_spec_grep` and `vmem_spec_validate`. `vmem_spec_create` / `vmem spec create`, `vmem_spec_update` / `vmem spec update` and `vmem_spec_delete` / `vmem spec delete` are implemented (#97). No spec command runs git commit, branch or push.
378
453
 
379
454
  Read commands share one bounded schema table with their MCP tools. `source` (CLI `--source`) defaults to the first registered source; `worktree` (`--worktree`) defaults to its registered root and must be an absolute root with the same Git common directory. Reads are allowed with `write: none` and do not edit repository content. Derived search caches stay outside protected sources.
380
455
 
@@ -397,10 +472,50 @@ vmem spec validate --repo /absolute/checkout --require-fresh --json
397
472
 
398
473
  Validation candidates are any `SPEC.md`, plus Markdown with parsed `id` or `type` frontmatter. A bare `SPEC.md` reports missing required keys. If YAML cannot be parsed, only the filename asserts candidacy; ordinary horizontal-rule/title-only READMEs are ignored. Oversized/non-UTF8 non-candidates yield skipped-path diagnostics; candidates retain blocking file errors. A truncated oversized frontmatter header is ambiguous and fails closed; it is never assumed to be a non-candidate. Discovery strips inherited Git pathspec-mode variables. Git binding/discovery subprocesses run outside the cache's IMMEDIATE transaction, while descriptor/path stamp checks remain inside.
399
474
 
400
- `introducedSpecErrors(current, prospective, options)` compares complete internal error identities before applying display limits. Owners are matched across both trees by ids that are unique in both (including file moves), with stable file paths as the fallback for missing/duplicate-id repairs. Old owners are matched one-to-one, so a new spec reusing a moved spec's path cannot inherit its errors. Error identity also includes the repository namespace, code, field and target. Existing errors remain reportable but do not block an unrelated change; new dangling targets, cycles and rank errors are returned. Results contain only introduced errors and are bounded samples; internal resource-budget failures throw instead of returning an empty success. This API is not yet wired to spec writes because T4 is deferred.
475
+ `introducedSpecErrors(current, prospective, options)` compares complete internal error identities before applying display limits. Owners are matched across both trees by ids that are unique in both (including file moves), with stable file paths as the fallback for missing/duplicate-id repairs. Old owners are matched one-to-one, so a new spec reusing a moved spec's path cannot inherit its errors. Error identity also includes the repository namespace, code, field and target. Existing errors remain reportable but do not block an unrelated change; new dangling targets, cycles and rank errors are returned. Results contain only introduced errors and are bounded samples; internal resource-budget failures throw instead of returning an empty success. Spec create, update and delete use this API before publishing the prospective change. Delete allows only the preview-acknowledged dangling links to the removed id; that exception is applied before result limits so unrelated introduced errors cannot be hidden.
401
476
 
402
477
  `specFreshness` checks full commit stamps against a pinned HEAD, counts scoped source commits and reports staged/unstaged/untracked changes touching native Git pathspecs. `paths` must be a nonempty relative pathspec list with no parent traversal and matching tracked files. Freshness is never authored into files. Stale scopes are report-only by default; `requireFresh` makes them errors. A spec without a stamp has no computed freshness entry. `git: false` skips native repository checks while retaining metadata shape/relative-path/full-SHA-format checks, and cannot be combined with `requireFresh`.
403
478
 
404
479
  `specsCoveringPath` matches a tracked relative filename using Git's pathspec engine. `validateSpecRepo(repo, { requireFresh?, limit?, env? })` discovers and validates a checkout without reading or creating a registry, home or disk cache, returning `{ code, report }`; code is 1 for validation errors or required stale scopes. CLI `vmem spec validate --repo` implements this registry-free mode.
405
480
 
406
481
  The portable schema contract is [test/fixtures/spec-graph/README.md](test/fixtures/spec-graph/README.md), with independent small valid/error/warning trees and expected codes. Consumers can copy the fixtures without a runtime dependency. Validation/CI reports omit raw sources; display limits are 1..500 records per collection and 128 KiB total, with errors shown before warnings, with `truncated` when records or oversized optional identifiers are omitted. Fixing errors and rerunning reveals later items.
482
+
483
+ `vmem_spec_create` / `vmem spec create <path> --id ID --type TYPE --title TEXT` share the create schema in `SPEC_COMMANDS`:
484
+
485
+ - The path is a literal filename relative to the selected worktree, ends in `.md`, is not Git-ignored, has no symlink component and does not exist. It must stay in that repository's discovery tree: nested repositories and submodule gitlink ancestors are refused; create the spec through that repository's own source instead. Missing parent directories are created only after validation; a failed write removes only directories it created that are still owned and empty. Create refuses before publication if a new Git-listed Markdown path would exceed the 10000-input discovery cap; ordinary Markdown and skipped tracked paths count too. Remove or ignore Markdown inputs (untrack tracked exclusions) before retrying. Non-empty parents are kept; expected retention after a refused create race is reported as a warning. Other owned-directory cleanup errors name the directory and the errno or ownership cause, with an access/ownership recovery step.
486
+ - Repository, ignore and gitlink checks run once at each create stage: initial read, locked validation and final publication check. Each stage streams the index once, retaining only whether a mode-160000 gitlink matches the target's own ancestors by canonical NFC/lowercase key, including missing workdirs and mixed normalization. There is no spelling-variant expansion. The scan bounds actual index output to 128 MiB, 1000000 records, 64 KiB per record and 10 seconds. Exceeding a bound refuses with the index cause and asks you to inspect, reduce or repair the index before retrying. Filesystem checks still run while creating parents.
487
+ - New file permissions are `0666 & ~umask`; new parent directory permissions are `0777 & ~umask`, matching editor-style creation. Updates retain the existing file mode. After publication, create syncs the immediate file parent, then the parent of each new directory, deepest first. A post-publication sync or cleanup failure returns `changed: true`, `ok: false` and "created with errors". Inspect the created file, its parent directories and the lock state under `VMEM_HOME`; preserve any replacement temporary file, and do not repeat the create.
488
+ - Titles supplied to create or update must contain no line separators or control characters (C0/C1, including NEL and NUL). Rejected inputs leave the file unchanged; the frontmatter emitter is unchanged.
489
+ - Required metadata is `id`, `type` and a single-line `title`. Status defaults to `draft`. Types are `goal|architecture|module|submodule`; statuses are `draft|active|deprecated`. Optional fields are `parent`, `superseded-by`, `depends-on`, `references`, `implements`, `covers`, `tags`, `paths` and `verified-against`. CLI list flags take JSON arrays. There is no body input.
490
+ - Frontmatter uses this field order: `id`, `type`, `title`, `status`, `parent`, `superseded-by`, `depends-on`, `references`, `implements`, `covers`, `tags`, `paths`, `verified-against`. The body starts with `# <title>`, then empty H2 sections: goal has `Scope`, `Decisions`, `Success and evidence`; architecture has `Boundaries`, `Decisions`; module and submodule have `Responsibility`, `Interfaces`, `Decisions`. New files use LF and no BOM.
491
+ - Creation uses the same write policy, raw and decoded metadata screens, worktree lock, introduced-error gate and actor attribution as update. Duplicate-id refusals name the new file even when it sorts before the existing spec. After setting the final mode and fsyncing the staged file, create publishes it atomically with a hard link and removes its temporary name. An intervening destination is preserved and refused with `EEXIST`. Other link failures name the cause and require checking permissions or using a filesystem with hard-link support; create never falls back to rename. Update publishes with rename. Spec create/update/delete use the same publication/cleanup helper as note writes: post-publication parent-identity and containment checks report drift with recovery guidance, while already-published changes retain `changed: true` and are not marked as MCP refusals. Lock/temp descriptors stay open until identity-checked unlink. A concurrent writer with the same user's access can still change the target or replace a parent between the last check and publication, or replace a cleanup name after its final identity check; pure TypeScript has no atomic inode-checked namespace primitive. Stop other writers, inspect the target, original parents, retained temps and VMEM_HOME lock state, and recover any applied change before another mutation.
492
+
493
+ ```sh
494
+ vmem spec create design/module.md --id module-id --type module --title 'Module design' --parent root-id --tags '["new"]' --json
495
+ ```
496
+
497
+ `vmem_spec_update` / `vmem spec update <id>` share the update schema in `SPEC_COMMANDS`:
498
+
499
+ - `set` (`--set JSON`) accepts scalar `title`, `type`, `status`, `parent`, `superseded-by` and `verified-against`. Types are `goal|architecture|module|submodule`; statuses are `draft|active|deprecated`.
500
+ - `unset` (`--unset JSON`) is a list of optional field names. `id` is immutable, and `id`, `type` and `title` cannot be unset. Unknown keys are refused.
501
+ - `add` / `remove` (`--add JSON`, `--remove JSON`) map `depends-on`, `references`, `implements`, `covers`, `tags` or `paths` to string lists. Entries are compared literally; existing entries are not added twice. A field cannot be unset and edited together, and a value cannot be added and removed together.
502
+ - Optional `expectedSha` (`--expected-sha`) takes the SHA-256 from `spec get` and refuses a stale read. The target is re-read under an exclusive per-canonical-worktree mutation lock under `VMEM_HOME`, outside every worktree. Registry/policy and spec-state changes during validation refuse rather than overwrite the new state. Update and delete ignore ordinary Markdown path-list churn in this drift comparison. Create compares the Markdown count and whether its target is listed, preserving the discovery-cap guard while allowing same-count unrelated renames; spec candidates and diagnostics still participate in every operation's drift check.
503
+ - `emitFrontmatter` preserves body bytes, BOM, original line endings, existing field order and unchanged field syntax. A semantic no-op writes nothing and returns `changed: false`. A changed file is staged in a same-directory temporary file and atomically renamed; the result names the path, SHA-256, actor and any refusal rule.
504
+ - The prospective tree is built in memory and checked with `introducedSpecErrors`: new errors refuse the write, while old unrelated errors do not block it. Refusals name the written path, with related paths/targets when needed.
505
+ - `write: mcp` permits CLI and MCP; `write: cli` permits CLI only; `write: none` refuses both. The shared `screenContent` rules always refuse secrets and refuse email/phone under `pii: deny`. The whole written text and decoded frontmatter are screened. Results carry `actor: agent` for MCP or the usual agent environment markers, otherwise `person`; no vault or source log is appended. Body prose is edited with normal file tools. Delete uses the preview-confirm flow described below.
506
+
507
+ ```sh
508
+ vmem spec update module-id --source project-specs --set '{"title":"Reviewed module"}' --unset '["status"]' --add '{"tags":["reviewed"]}' --json
509
+ ```
510
+
511
+ `vmem_spec_delete` / `vmem spec delete <id>` use a two-step acknowledgement:
512
+
513
+ - Without `confirm`, preview returns `preview: true`, the path, SHA-256, every backlink edge kind (body links included), children and a fingerprint. Arrays are sorted; the fingerprint binds the selected worktree, path, file SHA and the complete listed backlinks and children. Preview creates no cache, lock or file. The 224 KiB budget applies to preview-invariant acknowledgement fields, so a payload at the bound passes both preview and confirm. If it exceeds that budget, it refuses instead of omitting relations.
514
+ - Confirm with `confirm: true` and the fingerprint (`--confirm --fingerprint SHA` in CLI). The preview is recomputed under the canonical-worktree mutation lock. A changed file, child or backlink list makes the fingerprint stale and refuses deletion; request and inspect a fresh preview before confirming again.
515
+ - Only dangling frontmatter links to the removed id that the current preview acknowledged are permitted. Other newly introduced validation errors refuse. The caller repairs the listed links afterwards through spec update. Delete does not remove children or rewrite other specs.
516
+ - The same source write policy and actor attribution apply to preview and confirm. Confirm rechecks the shared registry guard immediately before unlink, removes only the selected file and leaves an ordinary Git deletion; it does not stage, commit, branch, push or append a log. Post-unlink sync or cleanup errors retain `changed: true`, `ok: false` and the SHA, with "deleted with errors" and no refusal marker. After an applied delete error, inspect the deleted file's parent directory and the mutation lock state under `VMEM_HOME`; the file is already gone. A blocked delete, including a path refusal before any deletion, directs the caller to request and inspect a fresh preview before confirming again, never to supply an update `expectedSha`.
517
+
518
+ ```sh
519
+ vmem spec delete module-id --source project-specs --json
520
+ vmem spec delete module-id --source project-specs --confirm --fingerprint <preview-fingerprint> --json
521
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@staix/vault-mem",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -12,7 +12,7 @@
12
12
  "bun": ">=1.4.2"
13
13
  },
14
14
  "dependencies": {
15
- "@staix/agent-mem": "0.17.0"
15
+ "@staix/agent-mem": "0.23.0"
16
16
  },
17
17
  "devDependencies": {
18
18
  "@staix/agent-console": "github:STAIxBWLB/agent-console#4c4c1e0",
@@ -34,10 +34,11 @@
34
34
  "LICENSE"
35
35
  ],
36
36
  "scripts": {
37
- "check": "bun x tsc --noEmit && bun scripts/check-boundary.ts && bun test && bun pm pack --dry-run && bun scripts/package-smoke.ts",
37
+ "check": "bun x tsc --noEmit && bun scripts/check-boundary.ts && bun scripts/readme-facts.ts && bun scripts/check-docs.mjs && bun test && bun pm pack --dry-run && bun scripts/package-smoke.ts",
38
38
  "smoke:package": "bun scripts/package-smoke.ts",
39
39
  "bench:release": "bun scripts/release-performance.ts",
40
40
  "parity:release": "bun scripts/release-parity.ts",
41
- "release:verify": "bun scripts/release-evidence.ts"
41
+ "release:verify": "bun scripts/release-evidence.ts",
42
+ "release:tag": "bun scripts/release-tag.ts"
42
43
  }
43
44
  }