@staix/vault-mem 0.3.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,30 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [0.4.0] - 2026-11-04
6
+
7
+ - Search, `vmem_search`, spec grep and writer duplicate hints match a Hangul or other CJK term of 2+ characters inside particle and compound forms (`사업단` finds `사업단은`, `사업단장`, `해외사업단`) through a side FTS5 bigram table. Latin terms keep token matching and their ranking; standalone-word and title/description hits rank before substring-only body hits. The index file name gains a schema version (`-links2-schema2.sqlite`), so the first run builds a new index once and older vmem versions keep their own file (#59).
8
+
9
+ - `vmem_patch` takes `edits` (1 to 32 `{oldString, newString}` pairs) as an alternative to the single pair, and `vmem patch --edits file|-` takes the same JSON array. Each `oldString` must match exactly once in the original note, edits must not overlap or start in frontmatter, and all apply or none do, with one receipt, one log event and the 256 KiB bound checked on the combined result. Several rows of one note no longer need one SHA round trip per edit (#63).
10
+
11
+ - Every MCP write tool takes the optional `log` event: `vmem_patch`, `vmem_append`, `vmem_set_frontmatter`, `vmem_move` and `vmem_delete` join `vmem_create`, `vmem_link` and `vmem_supersede` (move and delete use it on the confirm call). CLI writers keep `--log JSON` as the one form, now shown in each command's usage and checked against the same closed schema as the MCP field. A given event is validated and screened like `log append` before any note changes, so an invalid event (bad JSON, unknown key, bad type, unknown project, screened secret) refuses the whole write instead of saving the note and logging nothing; the event is no longer part of the move/delete fingerprint (#60).
12
+
13
+ - `vmem_list` takes a `cursor` and returns the filtered `total`, a per-row `mtime` from the index and `nextCursor`, so a full vault can be paged in stable path order. New read-only `vmem stats <vault>` and `vmem_stats` count notes by type, domain and status, notes modified in the last 7 and 30 days, and log events by type over a bounded window (default 30 days), without writing or locking the vault or its log. `vmem status` and `vmem doctor` no longer print the obsolete `stage: "foundation"` field; scripts that read it should drop that check (#62).
14
+
15
+ - `vmem manifest --json` lists read-only MCP tools as `{name, readOnly: true}` (taken from each tool's `readOnlyHint`), so installers can approve new read tools without a hard-coded list; other tools stay plain names. The release workflow states N-1 per minor line; patch releases carry no N-1 line (#106).
16
+
17
+ - Add MCP `vmem_read_file` and `vmem_list_files`, bounded read-only access to `ops/`, `reports/`, `self/`, `templates/`, `AGENTS.md` and `README.md` with `vmem_read` paging and limits; `notes/`, `log`, dot paths, symlinked components, non-UTF-8 and over-limit files are refused with the tool to use instead. Add `vmem_report`, the MCP form of `vmem report` with the same receipt and log event (#61).
18
+
19
+ - N-1: 0.3.3 runs beside this release. The derived index moves to `<sha>-links2-schema2.sqlite` (spec caches likewise), so 0.3.3 keeps its own `-links2.sqlite` and the first 0.4.0 run builds its index once. The config format, note format and log line format are unchanged, so each version reads what the other writes. MCP and CLI changes are additive for 0.3.3 clients: new tools (`vmem_read_file`, `vmem_list_files`, `vmem_report`, `vmem_stats`), optional `log` and `edits` arguments, and `vmem_list` adds `total`, `nextCursor` and per-row `mtime` beside `notes`. Two behaviors differ: `vmem status` no longer prints `stage`, and a write with an invalid log event is refused instead of saved without its event.
20
+
21
+ ## [0.3.3] - 2026-11-02
22
+
23
+ - Polish the spec read surface: scope fish parent completions to the first subcommand, preserve positional help tokens after `--`, document spec MCP tools and startup source registration, clarify shared field/error guidance, reuse body section helpers, and keep literal snippets on code-point boundaries (#103).
24
+
25
+ - Add read-only spec MCP tools and CLI get/graph/grep/validate commands from a shared bounded schema table, registry-free `spec validate --repo` CI mode, worktree-aware source selection, body/search pagination and metadata/path-scope filters. Spec snapshot filtering precedes FTS pagination; new read tools appear in the manifest. Spec content write tools remain deferred (#91 T5).
26
+
27
+ - Add spec validation reports, complete-tree introduced-error comparison, computed path-scoped freshness, tracked-file coversPath matching and registry-free validation library (#91 T3/T6), with a portable synthetic schema fixture. Candidate, link-list/path-list and supersession rules follow the confirmed schema. Discovery ignores inherited Git pathspec modes, skips oversized/non-UTF8 non-candidates with diagnostics, and performs Git inspection outside cache writer transactions. CLI/MCP wiring remains T5 and spec content writes remain deferred.
28
+
5
29
  ## [0.3.2] - 2026-11-02
6
30
 
7
31
  - Add library-only spec discovery, repository/worktree identity checks, typed id-based graphs and bounded directional slices (#91 T2). `SpecIndex` reuses the vault scan/metadata/hash/BM25 engine with a separate `spec-` cache per canonical worktree; vault cache names remain unchanged. Spec searches exclude shared-cache rows absent from the instance snapshot or replaced since its scan, and discovery errors name the relative file. Filesystem normalization/case aliases are accepted with root-identity and physical-containment checks, skipped listed paths have diagnostics, and error advice preserves the original cause and names `.gitignore` for discovery bounds. No CLI/MCP read surface or spec content write tools are added.
package/README.md CHANGED
@@ -87,9 +87,9 @@ bun bin/vmem.js links personal "Note or alias" --limit 50 --json
87
87
 
88
88
  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.
89
89
 
90
- The cache is `$VMEM_HOME/indexes/<canonical-vault-path-sha256>-links<N>.sqlite` using the resolved home, not necessarily the environment variable. `N` is the link-resolution version (currently 2), so two installed vmem versions that resolve links differently keep separate caches instead of rebuilding each other's links; 0.2.4 and older use the unversioned `<sha256>.sqlite`, and a first run after upgrading builds the new file once. 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.
90
+ 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.
91
91
 
92
- 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. `--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.
92
+ 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.
93
93
 
94
94
  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. 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.
95
95
 
@@ -104,6 +104,7 @@ All mutations use `applyWrite(home, request)`: per-vault `mutation.lock`, curren
104
104
  vmem new personal example-finding --type insight --domain research --topics research --description "A distinct supporting observation."
105
105
  vmem new personal another-finding --type insight --domain research --topics research --description "An independently sourced result." --body body.md
106
106
  vmem patch personal example-finding --old "This note argues that" --new "This finding states that" --expected-sha <sha256>
107
+ vmem patch personal example-finding --edits edits.json --expected-sha <sha256> # [{"oldString": "...", "newString": "..."}, ...]
107
108
  vmem append personal example-finding --section Evidence --markdown "Additional evidence."
108
109
  vmem frontmatter personal example-finding --set '{"confidence":"likely"}'
109
110
  vmem link personal example-finding another-finding --relation supports
@@ -117,11 +118,11 @@ vmem tidy personal --connections
117
118
  vmem tidy personal --all --json # migration sanitize preview (see Migration tidy)
118
119
  ```
119
120
 
120
- 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). 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 `-`.
121
+ 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 `-`.
121
122
 
122
123
  `--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.
123
124
 
124
- Validation returns named issues with severity and no matched secret text: V01 schema/enums/description; V02 existing MOC topics; V03 newly unresolved links; V04 flat ASCII note paths (maximum 200 bytes) and safe report paths; V05 final Topics placement/content (error when the write introduces a placement or content problem the note did not already have, or on create; warning when every problem was already present), with explicit append-to-Topics refusal; V06 pinned agent-mem secret regex parity and denied sources/input/snapshot paths; V07 email/phone/configured PII patterns when denied; V08 create duplicates (stem/NFKC H1); V09 256 KiB prospective note size / 16 MiB report size, exact patch and expected-SHA/drift; V10 supersession target integrity. Unchanged pre-existing broken links warn, including after a move. `possibleDuplicates` lists candidate paths for warnings from a disposable in-memory FTS5 query of title terms, with BM25 <= -0.000001, up to three paths; no disk cache is written for that check. `LOCKED`, `IO`, `ROLLBACK`, `INDEX` and `CLEANUP` identify operational failures. CLI returns exit 1 when `ok` is false.
125
+ Validation returns named issues with severity and no matched secret text: V01 schema/enums/description; V02 existing MOC topics; V03 newly unresolved links; V04 flat ASCII note paths (maximum 200 bytes) and safe report paths; V05 final Topics placement/content (error when the write introduces a placement or content problem the note did not already have, or on create; warning when every problem was already present), with explicit append-to-Topics refusal; V06 pinned agent-mem secret regex parity and denied sources/input/snapshot paths; V07 email/phone/configured PII patterns when denied; V08 create duplicates (stem/NFKC H1); V09 256 KiB prospective note size / 16 MiB report size, exact patch and expected-SHA/drift; V10 supersession target integrity. Unchanged pre-existing broken links warn, including after a move. `possibleDuplicates` lists candidate paths for warnings from a disposable in-memory FTS5 query of title terms, matched like search terms (CJK substrings included), with BM25 <= -0.000001, up to three paths; no disk cache is written for that check. `LOCKED`, `IO`, `ROLLBACK`, `INDEX` and `CLEANUP` identify operational failures. CLI returns exit 1 when `ok` is false.
125
126
 
126
127
  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.
127
128
 
@@ -132,6 +133,7 @@ A successful receipt reports `applied`, planned path/hash/byte changes, issues a
132
133
  vmem log append personal EXTRACT - synthetic:source "A synthetic event" --dest notes/example.md
133
134
  vmem log tail personal --limit 50 --json
134
135
  vmem log grep personal "EXTRACT|CONNECT" --type EXTRACT --limit 20
136
+ vmem patch personal example-finding --old "argues" --new "states" --log '{"type":"EXTRACT","project":"-","source":"synthetic:source","note":"Reworded claim"}'
135
137
  ```
136
138
 
137
139
  Events keep the canonical local-time format `YYYY-MM-DD HH:MM TYPE project source → dest — note` (two spaces between fields, one LF at the end). Destination is optional. Allowed new types: `INGEST ROUTE EXTRACT CONNECT DIGEST LEARN LINT TASK GRAPH SYNC RETHINK SOURCE`. Project must be `-` or a lowercase alphanumeric/hyphen id; when `registry` is configured, ids must exist in its bounded YAML `projects`/nested `sub_projects` arrays. Registry files are limited to 1 MiB, eight nesting levels and 10000 unique ids; invalid or unavailable configuration fails closed. Invalid types/fields/projects use L09 issues, the 1000-byte line bound uses V09, and secret/PII refusals use V06/V07. Fields cannot inject pipes, control characters or two-space/column separators. Validation and screening run before a file or lock is created. The 1000 UTF-8-byte bound includes the LF and attribution.
@@ -140,42 +142,63 @@ Every MCP log append and CLI call with a nonempty `AGENTHUB_PEER_ID`, `CLAUDECOD
140
142
 
141
143
  `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.
142
144
 
143
- 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; CLI writers accept `--log JSON` for overrides. 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. An override is validated at append time, not during a note-only dry run.
145
+ 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.
144
146
 
145
147
  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.
146
148
 
149
+ # Vault statistics
150
+
151
+ ```sh
152
+ vmem stats personal --json # log window: last 30 days
153
+ vmem stats personal --days 7 --json
154
+ ```
155
+
156
+ `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.
157
+
158
+ `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.
159
+
147
160
  # MCP server
148
161
 
149
162
  `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.
150
163
 
151
- 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`. 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.
164
+ 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.
152
165
 
153
166
  | tool | arguments (caps) |
154
167
  |---|---|
168
+ | `vmem_spec_get` | `id`, optional `source`, absolute `worktree`, `body`, `maxBytes`<=65536, `section`, `offset`<=2097152; metadata, relations, hash, freshness and optional body pages |
169
+ | `vmem_spec_graph` | `id`, optional `source`, `worktree`, `direction` subtree/ancestors/neighbors, `edge`, `depth`<=3, `limit`<=500 |
170
+ | `vmem_spec_grep` | optional `source`, `worktree`, `query`<=1024 UTF-8 bytes, `literal`, `type`, `status`, `tag`, `parent`, `dependsOn`, `coversPath`, `offset`<=10000, `limit`<=500; continuation after filters |
171
+ | `vmem_spec_validate` | optional `source`, `worktree`, `requireFresh`, `limit`<=500; bounded report; stale is fatal only with `requireFresh` |
155
172
  | `vmem_status` | none; vaults with health, write policy, effective pii and `piiPolicy` (read-only) |
156
173
  | `vmem_search` | `query`<=1000, `vault`, `limit`<=50, `type`, `domain` |
157
174
  | `vmem_read` | `path` (stem, alias or `notes/` path), `vault`, `maxBytes`<=65536; returns `{path, frontmatter, body, sha256, truncated}` |
158
175
  | `vmem_read_many` | `paths`<=20 (8 KiB each), `vault` |
159
- | `vmem_list` | `vault`, `prefix`, `limit`<=500 |
176
+ | `vmem_list` | `vault`, `prefix`, `limit`<=500, `cursor`; rows in path order with `mtime`, the filtered `total` and `nextCursor` while more remain |
160
177
  | `vmem_links` | `path`, `vault`, `direction` out/in/both, `limit`<=200; returns `{out, dead, in}` |
161
178
  | `vmem_mocs` | `vault`; MOC notes with incoming link counts |
162
179
  | `vmem_check` | `vault`, `path`, `text`<=256 KiB; validation only |
163
180
  | `vmem_log_tail` | `vault`, `n`<=200, `type`, `grep`<=256 |
164
181
  | `vmem_create` | `stem`, `type`, `domain`, `description`, `topics[]`<=32, `title`, `body`<=65536, `source`, `confidence`, `status`, `extra`, `log` |
165
- | `vmem_patch` | `path`, `oldString`<=8192, `newString`<=8192, `expectedSha` |
166
- | `vmem_append` | `path`, `section`<=120, `markdown`<=16384, `expectedSha` |
167
- | `vmem_set_frontmatter` | `path`, `set`, `unset[]`, `expectedSha` |
182
+ | `vmem_patch` | `path`, `oldString`<=8192 and `newString`<=8192, or `edits[]` 1..32 of `{oldString, newString}` (all-or-nothing), `expectedSha`, `log` |
183
+ | `vmem_append` | `path`, `section`<=120, `markdown`<=16384, `expectedSha`, `log` |
184
+ | `vmem_set_frontmatter` | `path`, `set`, `unset[]`, `expectedSha`, `log` |
168
185
  | `vmem_link` | `from`, `to`, `relation`, `context`, `bidirectional` (default true), `log` |
169
186
  | `vmem_supersede` | `old`, `next`, `log` |
170
187
  | `vmem_log_append` | `type`, `project`, `source`, `dest`, `note`<=500 |
171
- | `vmem_move` | `from`, `to`, `confirm`, `fingerprint` (two-step) |
172
- | `vmem_delete` | `path`, `confirm`, `fingerprint` (two-step; the preview lists backlinks) |
188
+ | `vmem_move` | `from`, `to`, `confirm`, `fingerprint` (two-step), `log` (on confirm) |
189
+ | `vmem_delete` | `path`, `confirm`, `fingerprint` (two-step; the preview lists backlinks), `log` (on confirm) |
173
190
  | `vmem_promote` | `path` (in the personal vault), `to` (enum of org vaults), `topics[]`, `again`, `confirm`, `fingerprint` (two-step; never pushes) |
174
191
  | `vmem_skills_mine` | `vault`, `days`, `project`, `allProjects`, `vocab`, `skills[]`, `minSize`, `minNovelty` (read-only; see Skill mining) |
192
+ | `vmem_stats` | `vault`, `days`<=3650 (default 30); read-only counts, see Vault statistics |
175
193
  | `vmem_promote_from_amem` | `id`, `project`, `stem`, `type`, `domain`, `topics[]`, `description`, `title`, `body`<=65536, `linkTo`, `confirm`, `fingerprint` (two-step) |
194
+ | `vmem_read_file` | `path`, `vault`, `maxBytes`<=65536, `offset`<=2097152; returns `{path, sha256, truncated, body, offset?, nextOffset?}` (read-only; allowed roots below the table) |
195
+ | `vmem_list_files` | `dir`, `vault`; one level, <=500 entries `{name, path, type, bytes?}` (read-only) |
196
+ | `vmem_report` | `path` under `reports/` or `ops/`, `body`<=65536, `dryRun`, `log`; the receipt of `vmem report` |
176
197
 
177
198
  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/`.
178
199
 
200
+ 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.
201
+
179
202
  # Host setup
180
203
 
181
204
  ```sh
@@ -192,7 +215,7 @@ Apply is idempotent and touches only the `vmem` entry: other servers and setting
192
215
 
193
216
  `vmem completion bash|zsh|fish` prints a completion script generated from the same command table as `--help`.
194
217
 
195
- `vmem manifest --json` prints `{name, version, configVersion, mcp: {server, tools}, commands}`: the package version, the config format it writes, the MCP tool names and the CLI command names from the same table, for tools that would otherwise hard-code them.
218
+ `vmem manifest --json` prints `{name, version, configVersion, mcp: {server, tools}, commands}`: the package version, the config format it writes, the MCP tools and the CLI command names from the same table, for tools that would otherwise hard-code them. A read-only tool (its `readOnlyHint` annotation) is listed as `{name, readOnly: true}`, every other tool as its plain name.
196
219
 
197
220
  # Promotion from agent-mem
198
221
 
@@ -287,7 +310,7 @@ vmem sync team --confirm --fingerprint <sha>
287
310
 
288
311
  - `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.
289
312
  - `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.
290
- - `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, 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.
313
+ - `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.
291
314
  - [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.
292
315
 
293
316
 
@@ -343,4 +366,33 @@ The config `specs` array holds `id`, canonical git working-tree root `path`, `wr
343
366
 
344
367
  Config writes containing `specs` use format 2; a config without `specs` 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 and `vaults list` keep their output shape.
345
368
 
346
- The registry and a library-only read engine 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. `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. Spec validation, freshness, path filters, MCP tools and CLI graph/search commands are not yet implemented. Spec create/update/delete tools remain deferred; `write` stores a policy for later capabilities. Commands do not edit repository content or run git commit, branch or push.
369
+ 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.
370
+
371
+ 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.
372
+
373
+ ```sh
374
+ vmem spec get goal --source project-specs --body --max-bytes 16384 --json
375
+ vmem spec graph goal --direction subtree --depth 3 --limit 100 --json
376
+ vmem spec grep implementation --type module --tag storage --limit 20 --offset 0 --json
377
+ vmem spec grep --covers-path src/index.ts --json
378
+ vmem spec validate --source project-specs --require-fresh --json
379
+ vmem spec validate --repo /absolute/checkout --require-fresh --json
380
+ ```
381
+
382
+ `get` returns frontmatter, resolved outgoing links, backlinks, children, path, SHA-256 and computed freshness. Body reads are optional (`--body`, or body paging/section options) and use byte offsets with bounded UTF-8 pages. `graph` accepts subtree, ancestors or neighbors and an optional edge kind. `grep` searches FTS terms by default or a literal substring with `--literal`; filters are type, status, tag, parent, depends-on and covers-path. Use `--` before a positional id/query beginning with a hyphen, for example `vmem spec grep --literal -- "- [ ]"`. Results carry a continuation `nextOffset` when more matching hits exist. Snapshot path/hash filtering occurs before search limit/offset, so another scanner's cache rows cannot shorten pages. Rerun a command to refresh its snapshot. Large responses refuse with guidance or mark bounded collections as truncated.
383
+
384
+ `validate` exits 1 on validation errors; stale scopes become errors only with `--require-fresh`. `--repo` validates a checkout without consulting a home/config file or creating a registry/cache, and cannot be combined with `--source` or `--worktree`. The four read tools are listed by `vmem manifest --json` as `{name, readOnly: true}`; hosts that approve from a frozen allow-list instead of the manifest need to add their names separately.
385
+
386
+ # Spec validation and freshness library
387
+
388
+ `validateSpecs(snapshot, { requireFresh?, limit?, env?, git? })` returns full error/warning counts and count/byte-bounded `items`, source `diagnostics` and computed `freshness`. Types are `goal`, `architecture`, `module`, `submodule`, with increasing parent/child ranks and skipped levels allowed; status is optional or `draft|active|deprecated`. A deprecated spec may name one replacement; dangling, self or non-deprecated replacement links error, while missing or already-deprecated replacements warn. Metadata link values accept plain ids or wiki links with labels/headings. List link fields and `paths` require lists; malformed scalars remain visible to validation. `covers` and `tags` require lists of nonempty strings; scalar, non-string or empty items error. Empty lists are allowed. Only valid `covers` lists contribute duplicate claims.
389
+
390
+ 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.
391
+
392
+ `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.
393
+
394
+ `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`.
395
+
396
+ `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.
397
+
398
+ 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@staix/vault-mem",
3
- "version": "0.3.2",
3
+ "version": "0.4.0",
4
4
  "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/src/cli.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { runSpecCommand, specTools } from "./mcp-spec.ts";
1
2
  import { tidyVault, TIDY_RULES } from "./tidy.ts";
2
3
  import { originCheck } from "./sync.ts";
3
4
  import { registryIds } from "./vault-log.ts";
@@ -8,12 +9,13 @@ import { isWriteCommand, runWriteCommand } from "./write-commands.ts";
8
9
  import { isReadCommand, runReadCommand } from "./read-commands.ts";
9
10
  import { version } from "../package.json";
10
11
  import { COMMANDS, completionScript, help } from "./commands-table.ts";
11
- import { VMEM_TOOL_NAMES } from "./mcp-vault.ts";
12
+ import { VMEM_TOOL_NAMES, vaultTools } from "./mcp-vault.ts";
12
13
  import { CONFIG_VERSION } from "./config.ts";
13
14
  import { runSetup, type SetupMode } from "./setup.ts";
14
15
  import { resolveHome } from "./home.ts";
15
16
  import { addVault, addSpec, removeSpec, specStatus, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault, setVaultPii } from "./registry.ts";
16
17
  import { piiPolicy } from "./pii.ts";
18
+ import { vaultStats } from "./vault-stats.ts";
17
19
  function parse(args: string[], allowed: string[], values: string[]) {
18
20
  const flags: Record<string, string | boolean> = {}, positional: string[] = [];
19
21
  for (let i = 0; i < args.length; i++) {
@@ -29,6 +31,7 @@ function parse(args: string[], allowed: string[], values: string[]) {
29
31
  return { flags, positional };
30
32
  }
31
33
  function commandHelp(args: string[]): string | undefined {
34
+ if (args.includes("--")) return undefined;
32
35
  if (!["--help", "-h"].includes(args.at(-1) ?? "")) return undefined;
33
36
  const name = args.slice(0, -1).join(" ");
34
37
  if (!name) return undefined;
@@ -43,7 +46,10 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
43
46
  if (args[0] === "manifest") {
44
47
  const { flags, positional } = parse(args.slice(1), ["--json"], []);
45
48
  if (positional.length) throw new Error("manifest: unexpected arguments");
46
- const manifest = { name: "@staix/vault-mem", version, configVersion: CONFIG_VERSION, mcp: { server: "vmem", tools: [...VMEM_TOOL_NAMES] }, commands: COMMANDS.map(c => c.name) };
49
+ // Read-only tools are published as { name, readOnly: true } so installers can approve them without a hard-coded list.
50
+ const readOnly = new Set([...vaultTools([]), ...specTools()].filter(t => t.annotations.readOnlyHint).map(t => t.name));
51
+ const tools = VMEM_TOOL_NAMES.map(name => readOnly.has(name) ? { name, readOnly: true } : name);
52
+ const manifest = { name: "@staix/vault-mem", version, configVersion: CONFIG_VERSION, mcp: { server: "vmem", tools }, commands: COMMANDS.map(c => c.name) };
47
53
  return { text: JSON.stringify(manifest, null, flags["--json"] ? undefined : 2), code: 0 };
48
54
  }
49
55
  if (args[0] === "setup") {
@@ -57,6 +63,7 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
57
63
  if (args.length !== 2) throw new Error("completion: requires bash, zsh or fish");
58
64
  return { text: completionScript(args[1]!).trimEnd(), code: 0 };
59
65
  }
66
+ if (args[0] === "spec") return runSpecCommand(args.slice(1), env);
60
67
  if (args[0] === "lint" || args[0] === "graph") return runAnalysisCommand(args[0],args.slice(1),resolveHome(env).home,env);
61
68
  if (args[0] === "promote" || args[0] === "sync") return runOrgCommand(args[0], args.slice(1), resolveHome(env).home, env);
62
69
  if (args[0] === "log") return runLogCommand(args.slice(1), resolveHome(env).home, env);
@@ -65,7 +72,7 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
65
72
  const group = args[0] === "vaults" || args[0] === "specs";
66
73
  const command = group ? `${args[0]} ${args[1] ?? ""}` : args[0];
67
74
  const tail = args.slice(group ? 2 : 1);
68
- const options = command === "vaults add" ? ["--kind", "--write", "--pii", "--remote", "--registry"] : command === "vaults pii" ? ["--set"] : command === "specs add" ? ["--write", "--pii"] : [];
75
+ const options = command === "vaults add" ? ["--kind", "--write", "--pii", "--remote", "--registry"] : command === "vaults pii" ? ["--set"] : command === "specs add" ? ["--write", "--pii"] : command === "stats" ? ["--days"] : [];
69
76
  const { flags, positional } = parse(tail, ["--json", ...options, ...(command === "vaults remove" || command === "specs remove" || command === "vaults pii" || command === "recover" ? ["--confirm"] : [])], options);
70
77
  const home = resolveHome(env);
71
78
  let result: unknown, code = 0;
@@ -102,10 +109,19 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
102
109
  });
103
110
  const sources = command === "doctor" && config.specs !== undefined ? specStatus(home.home, env) : undefined;
104
111
  const healthy = vaults.every(v => v.healthy && (!v.checks || Object.values(v.checks).every(check => check.ok))) && (!sources || sources.every(source => source.healthy));
105
- result = { ...home, version, stage: "foundation", healthy, vaults, ...(config.specs !== undefined ? { specs: sources ?? config.specs } : {}) };
112
+ result = { ...home, version, healthy, vaults, ...(config.specs !== undefined ? { specs: sources ?? config.specs } : {}) };
106
113
  if (command === "doctor" && !healthy) code = 1;
107
114
  break;
108
115
  }
116
+ case "stats": {
117
+ if (positional.length !== 1) throw new Error("stats: requires one vault id; use vmem stats <vault> [--days 1..3650]");
118
+ const days = flags["--days"];
119
+ if (days !== undefined && !/^[0-9]+$/.test(String(days))) throw new Error("stats: --days expects an integer 1..3650; omit it for the 30-day default");
120
+ const stats = vaultStats(home.home, positional[0]!, days === undefined ? {} : { days: Number(days) });
121
+ result = stats;
122
+ if (stats.log.issues.length) code = 1;
123
+ break;
124
+ }
109
125
  case "recover":
110
126
  if (positional.length) throw new Error("recover: unexpected arguments");
111
127
  result = recoverRegistry(home.home, flags["--confirm"] === true);
@@ -1,4 +1,6 @@
1
+ import { SPEC_COMMANDS } from "./spec-command-table.ts";
1
2
  export const COMMANDS = [
3
+ ...SPEC_COMMANDS.map(item => ({ name: `spec ${item.command}`, usage: item.usage, mutates: false })),
2
4
  { name: "lint", usage: "lint <vault> [--note PATH] [--write] [--dry-run] [--json]", mutates: "write" },
3
5
  { name: "graph build", usage: "graph build <vault> [--workspace] [--dry-run] [--json]", mutates: true },
4
6
  { name: "graph neighbors", usage: "graph neighbors <vault> <stem> [--hops 1..2] [--limit 1..500] [--json]", mutates: false },
@@ -17,16 +19,16 @@ export const COMMANDS = [
17
19
  { name: "specs list", usage: "specs list [--json]", mutates: false },
18
20
  { name: "specs add", usage: "specs add <id> <absolute-path> [--write mcp|cli|none] [--pii allow|deny] [--json]", mutates: true },
19
21
  { name: "specs remove", usage: "specs remove <id> [--confirm] [--json]", mutates: "confirm" },
20
- { name: "new", usage: "new <vault> <stem> --type TYPE --domain DOMAIN --topics a,b --description TEXT [--title TEXT] [--source TEXT|JSON] [--confidence TEXT] [--status TEXT] [--body file|-] [--extra JSON] [--dry-run] [--json]", mutates: true },
21
- { name: "patch", usage: "patch <vault> <note> --old TEXT --new TEXT [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
22
- { name: "append", usage: "append <vault> <note> --section SECTION --markdown TEXT [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
23
- { name: "frontmatter", usage: "frontmatter <vault> <note> [--set JSON] [--unset key,key] [--expected-sha SHA] [--dry-run] [--json]", mutates: true },
24
- { name: "link", usage: "link <vault> <from> <to> --relation R [--context TEXT] [--one-way] [--dry-run] [--json]", mutates: true },
25
- { name: "supersede", usage: "supersede <vault> <old> <next> [--dry-run] [--json]", mutates: true },
26
- { name: "move", usage: "move <vault> <from> <to> [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm" },
27
- { name: "delete", usage: "delete <vault> <note> [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm" },
22
+ { name: "new", usage: "new <vault> <stem> --type TYPE --domain DOMAIN --topics a,b --description TEXT [--title TEXT] [--source TEXT|JSON] [--confidence TEXT] [--status TEXT] [--body file|-] [--extra JSON] [--log JSON] [--dry-run] [--json]", mutates: true },
23
+ { name: "patch", usage: "patch <vault> <note> [--old TEXT --new TEXT] [--edits file|-] [--expected-sha SHA] [--log JSON] [--dry-run] [--json]", mutates: true },
24
+ { name: "append", usage: "append <vault> <note> --section SECTION --markdown TEXT [--expected-sha SHA] [--log JSON] [--dry-run] [--json]", mutates: true },
25
+ { name: "frontmatter", usage: "frontmatter <vault> <note> [--set JSON] [--unset key,key] [--expected-sha SHA] [--log JSON] [--dry-run] [--json]", mutates: true },
26
+ { name: "link", usage: "link <vault> <from> <to> --relation R [--context TEXT] [--one-way] [--log JSON] [--dry-run] [--json]", mutates: true },
27
+ { name: "supersede", usage: "supersede <vault> <old> <next> [--log JSON] [--dry-run] [--json]", mutates: true },
28
+ { name: "move", usage: "move <vault> <from> <to> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm" },
29
+ { name: "delete", usage: "delete <vault> <note> [--confirm --fingerprint SHA] [--log JSON] [--dry-run] [--json]", mutates: "confirm" },
28
30
  { name: "tidy", usage: "tidy <vault> [--connections] [--escapes] [--enums] [--keys] [--sources] [--topics] [--secrets] [--log] [--all] [--map file] [--confirm --fingerprint SHA] [--dry-run] [--json]", mutates: "confirm" },
29
- { name: "report", usage: "report <vault> <reports/path|ops/path> --body file|- [--dry-run] [--json]", mutates: true },
31
+ { name: "report", usage: "report <vault> <reports/path|ops/path> --body file|- [--log JSON] [--dry-run] [--json]", mutates: true },
30
32
  { name: "check", usage: "check <vault> <file|-> [--path stem] [--json]", mutates: false },
31
33
  { name: "log tail", usage: "log tail <vault> [--limit 1..200] [--type TYPE] [--json]", mutates: false },
32
34
  { name: "log grep", usage: "log grep <vault> <pattern> [--limit 1..200] [--type TYPE] [--json]", mutates: false },
@@ -38,6 +40,7 @@ export const COMMANDS = [
38
40
  { name: "setup", usage: "setup <claude|codex|kimi|pi|qwen|jcode|agy|all> [--root PATH] [--apply|--undo] [--json]", mutates: "apply" },
39
41
  { name: "manifest", usage: "manifest [--json]", mutates: false },
40
42
  { name: "completion", usage: "completion <bash|zsh|fish>", mutates: false },
43
+ { name: "stats", usage: "stats <vault> [--days 1..3650] [--json]", mutates: false },
41
44
  ] as const;
42
45
  const RELATIONS = ["supports", "contradicts", "extends", "applies-to", "context-for"] as const;
43
46
  const LOG_EVENT_TYPES = ["INGEST", "ROUTE", "EXTRACT", "CONNECT", "DIGEST", "LEARN", "LINT", "TASK", "GRAPH", "SYNC", "RETHINK", "SOURCE"] as const;
@@ -69,10 +72,10 @@ export function completionScript(shell: string): string {
69
72
  if (shell === "fish") {
70
73
  const lines = [`complete -c vmem -f`, `complete -c vmem -n '__fish_use_subcommand' -a ${quote(top.join(" "))}`];
71
74
  for (const d of defs) {
72
- const cond = d.path.length === 1 ? `__fish_seen_subcommand_from ${d.path[0]}` : `__fish_seen_subcommand_from ${d.path[1]}`;
75
+ const cond = d.path.length === 1 ? `__fish_seen_subcommand_from ${d.path[0]}` : `__fish_seen_subcommand_from ${d.path[0]}; and __fish_seen_subcommand_from ${d.path[1]}`;
73
76
  for (const flag of Object.keys(d.options)) lines.push(`complete -c vmem -n ${quote(cond)} -l ${flag.slice(2)}`);
74
77
  }
75
- for (const parent of ["vaults", "specs", "log", "graph", "skills"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
78
+ for (const parent of ["vaults", "specs", "spec", "log", "graph", "skills"]) lines.push(`complete -c vmem -n '__fish_seen_subcommand_from ${parent}; and test (commandline -opc)[2] = ${parent}' -a ${quote(defs.filter(d => d.path[0] === parent).map(d => d.path[1]).join(" "))}`);
76
79
  return lines.join("\n") + "\n";
77
80
  }
78
81
  const cases = defs.map(d => ` ${quote(d.path.join(" "))}) words=${quote(Object.keys(d.options).join(" "))} ;;`);
@@ -81,7 +84,7 @@ export function completionScript(shell: string): string {
81
84
  cur="\${COMP_WORDS[COMP_CWORD]}"
82
85
  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W ${quote(top.join(" "))} -- "$cur")); return; fi
83
86
  key="\${COMP_WORDS[1]}"
84
- case "$key" in graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
87
+ case "$key" in spec) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W '${SPEC_COMMANDS.map(item => item.command).join(" ")}' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; graph) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'build neighbors' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; skills) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'mine' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; specs) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W 'list add remove' -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; vaults|log) if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=($(compgen -W "$( [ "$key" = vaults ] && echo 'list add remove' || echo 'tail grep append')" -- "$cur")); return; fi; key="$key \${COMP_WORDS[2]}" ;; esac
85
88
  case "$key" in
86
89
  ${cases.join("\n")}
87
90
  *) words='' ;;
package/src/index.ts CHANGED
@@ -44,6 +44,11 @@ export { tidyVault, parseTidyMap, TIDY_RULES } from "./tidy.ts";
44
44
  export type { TidyRequest, TidyResult, TidyRule, TidyMap } from "./tidy.ts";
45
45
 
46
46
  export { resolveSpecWorktree, discoverSpecs, SpecIndex } from "./spec-source.ts";
47
- export type { SpecDocument, SpecDiagnostic, SpecSnapshot, SpecSourceOptions, SpecIndexOptions, SpecSearchResult } from "./spec-source.ts";
47
+ export type { SpecCandidate, SpecDocument, SpecDiagnostic, SpecSnapshot, SpecSourceOptions, SpecIndexOptions, SpecSearchResult } from "./spec-source.ts";
48
48
  export { buildSpecGraph, specSlice, SPEC_EDGE_KINDS, MAX_SPEC_INPUTS, MAX_SPEC_EDGES } from "./spec-graph.ts";
49
49
  export type { SpecNode, SpecEdge, SpecEdgeKind, SpecGraph, SpecSliceOptions, SpecSlice } from "./spec-graph.ts";
50
+
51
+ export { validateSpecs, introducedSpecErrors, validateSpecRepo } from "./spec-validate.ts";
52
+ export type { SpecValidationIssue, SpecValidationOptions, SpecValidationReport, SpecRepoValidationOptions, SpecRepoValidation } from "./spec-validate.ts";
53
+ export { specFreshness, specsCoveringPath } from "./spec-freshness.ts";
54
+ export type { SpecFreshnessEntry, SpecFreshnessReport, SpecFreshnessOptions } from "./spec-freshness.ts";
package/src/log-format.ts CHANGED
@@ -7,6 +7,9 @@ import type { LogContext, LogEvent } from "./log-types.ts";
7
7
  import type { WriteIssue } from "./write-types.ts";
8
8
 
9
9
  export const LOG_TYPES = ["INGEST", "ROUTE", "EXTRACT", "CONNECT", "DIGEST", "LEARN", "LINT", "TASK", "GRAPH", "SYNC", "RETHINK", "SOURCE"] as const;
10
+ const bounded = (maxLength: number) => ({ type: "string", minLength: 1, maxLength });
11
+ /** Closed schema of a write's log event, shared by the MCP write tools and CLI `--log JSON`. */
12
+ export const LOG_EVENT_SCHEMA = { type: "object", properties: { type: { type: "string", enum: [...LOG_TYPES] }, project: bounded(64), source: bounded(512), dest: bounded(512), note: bounded(500) }, required: ["type", "project", "source", "note"], additionalProperties: false };
10
13
  export const AGENT_MARKERS = ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID"] as const;
11
14
  const EVENT_KEYS = new Set(["type", "project", "source", "dest", "note"]);
12
15
  const CONTEXT_KEYS = new Set(["vault", "config", "channel", "env", "now", "projectIds"]);
package/src/log-types.ts CHANGED
@@ -4,7 +4,11 @@ export interface LogEvent { type: string; project: string; source: string; dest?
4
4
  export interface LogRequest { vault: string; event: LogEvent; channel?: "cli" | "mcp" }
5
5
  export interface LogContext { vault: VaultSpec; config: VmemConfig; channel?: "cli" | "mcp"; env?: NodeJS.ProcessEnv; now?: Date; projectIds?: ReadonlySet<string> }
6
6
  export interface LogReceipt { ok: boolean; appended: boolean | null; synced: boolean; bytesWritten: number | null; issues: WriteIssue[]; rolledBack?: boolean }
7
- export interface LogReadOptions { vault: string; limit?: number; grep?: string; type?: string }
7
+ export interface LogReadOptions {
8
+ vault: string; limit?: number; grep?: string; type?: string;
9
+ /** In-process callers only (never CLI/MCP input): called with every complete data line, before the type and grep filters. */
10
+ visit?: (line: string) => void;
11
+ }
8
12
  export interface LogReadResult { ok: boolean; lines: string[]; dataLines: number | null; warnings: string[]; issues: WriteIssue[] }
9
13
 
10
14
  export interface LogBinding { vault: VaultSpec; denyPaths: string[]; piiPatterns: string[]; dev: number; ino: number }
@@ -0,0 +1,68 @@
1
+ import { argumentError, type McpHandler, type McpTool } from "./mcp.ts";
2
+ import { SPEC_COMMANDS } from "./spec-command-table.ts";
3
+ import { executeSpecCommand } from "./spec-commands.ts";
4
+ import { validateSpecRepo } from "./spec-validate.ts";
5
+ import { resolveHome } from "./home.ts";
6
+ import { loadRegistry } from "./registry.ts";
7
+
8
+ /** Spec tool definitions; every spec tool is read-only. */
9
+ export const specTools = (): McpTool[] => SPEC_COMMANDS.map(item => ({ name: item.name, description: item.description, inputSchema: item.inputSchema,
10
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }));
11
+
12
+ export function createSpecMcp(home: string, env: NodeJS.ProcessEnv = process.env): { tools: McpTool[]; handlers: Record<string, McpHandler> } {
13
+ const registered = loadRegistry(home).specs ?? [];
14
+ const tools = specTools();
15
+ const handlers: Record<string, McpHandler> = {};
16
+ for (const item of SPEC_COMMANDS) handlers[item.name] = args => {
17
+ const invalid = argumentError(args, item.inputSchema);
18
+ if (invalid) throw new Error(invalid);
19
+ const selected = registered.find(source => source.id === (args.source ?? registered[0]?.id));
20
+ if (!selected) throw new Error("spec source: no matching source in the server's startup registry; pass the source argument with a registered id, or register with vmem specs add and restart the MCP server");
21
+ const current = loadRegistry(home).specs?.find(source => source.id === selected.id);
22
+ if (!current || JSON.stringify(current) !== JSON.stringify(selected)) throw new Error("spec source: registry changed since server startup; restart the MCP server before reading");
23
+ return executeSpecCommand(home, item.command, { ...args, source: selected.id }, env);
24
+ };
25
+ return { tools, handlers };
26
+ }
27
+
28
+ /** Parse with the same bounded field schemas as MCP. --repo deliberately bypasses home resolution. */
29
+ export function runSpecCommand(args: string[], env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
30
+ const item = SPEC_COMMANDS.find(entry => entry.command === args[0]);
31
+ if (!item) throw new Error("spec: unknown command; use vmem spec --help");
32
+ const values: Record<string, unknown> = {}, positional: string[] = [];
33
+ const properties = item.inputSchema.properties as Record<string, { type: string }>;
34
+ const flags = new Map(Object.keys(properties).filter(key => key !== "id" && key !== "query").map(key => ["--" + key.replace(/[A-Z]/g, value => "-" + value.toLowerCase()), key]));
35
+ const seen = new Set<string>(); let json = false, repo: string | undefined, positionalOnly = false;
36
+ for (let i = 1; i < args.length; i++) {
37
+ const flag = args[i]!;
38
+ if (positionalOnly || !flag.startsWith("-")) { positional.push(flag); continue; }
39
+ if (flag === "--") { positionalOnly = true; continue; }
40
+ if (seen.has(flag)) throw new Error(`spec ${item.command}: repeated option ${flag}; supply it once (vmem spec ${item.command} --help)`);
41
+ seen.add(flag);
42
+ if (flag === "--json") { json = true; continue; }
43
+ const key = flags.get(flag);
44
+ if (!key && !(flag === "--repo" && item.command === "validate")) throw new Error(`spec ${item.command}: unknown option ${flag}; see vmem spec ${item.command} --help`);
45
+ if (key && properties[key]!.type === "boolean") { values[key] = true; continue; }
46
+ const value = args[++i];
47
+ if (value === undefined || value.startsWith("--")) throw new Error(`${flag}: value required; see vmem spec ${item.command} --help`);
48
+ if (flag === "--repo") {
49
+ const invalidPath = argumentError(value, { type: "string", minLength: 1, maxLength: 4096 }, "repo");
50
+ if (invalidPath) throw new Error(`${invalidPath}; supply a checkout path with vmem spec validate --repo PATH`);
51
+ repo = value; continue;
52
+ }
53
+ if (properties[key!]!.type === "integer") {
54
+ if (!/^[0-9]+$/.test(value)) throw new Error(`${flag}: expected integer; see vmem spec ${item.command} --help for its bounds`);
55
+ values[key!] = Number(value);
56
+ } else values[key!] = value;
57
+ }
58
+ const takesId = item.command === "get" || item.command === "graph";
59
+ if (positional.length > (item.command === "validate" ? 0 : 1) || (takesId && positional.length !== 1)) throw new Error(`spec ${item.command}: unexpected targets; use vmem ${item.usage}`);
60
+ if (positional[0] !== undefined) values[takesId ? "id" : "query"] = positional[0];
61
+ const invalid = argumentError(values, item.inputSchema);
62
+ if (invalid) throw new Error(`${invalid}; see vmem spec ${item.command} --help to correct the arguments`);
63
+ if (repo !== undefined && (values.source !== undefined || values.worktree !== undefined)) throw new Error("--repo cannot be combined with --source or --worktree; choose registry-free or registered validation");
64
+ const result = repo !== undefined
65
+ ? validateSpecRepo(repo, { requireFresh: values.requireFresh as boolean | undefined, limit: values.limit as number | undefined, env }).report
66
+ : executeSpecCommand(resolveHome(env).home, item.command, values, env);
67
+ return { text: JSON.stringify(result, null, json ? undefined : 2), code: item.command === "validate" && !(result as { ok: boolean }).ok ? 1 : 0 };
68
+ }