@jacklika/dsh-tool-memory-filesystem 0.1.3-alpha.1 → 0.1.3-alpha.11

package/README.md

@@ -45,27 +45,27 @@ A relative `vaultRoot` resolves against the calling session's workspace.
 | Field | Type | Default | Description |
 |---|---|---|---|
 | `vaultRoot` | `string` | `''` → `<session cwd>/.dsh/memory/` | Vault root. Empty selects the per-workspace memory directory; a relative path resolves against the session workspace. |
-| `extensions` | `string[]` | `['.md']` | File extensions treated as notes. |
+| `extensions` | `string[]` | `['.md']` | File extensions treated as notes. Must list at least one extension; an empty list fails plugin load. |
 | `maxLinkDepth` | `number` | `1` | Maximum `[[link]]` hops `wiki_read` resolves. |
 | `maxSearchResults` | `number` | `20` | Maximum `wiki_search` hits. |
 | `indexHiddenDirs` | `boolean` | `false` | Index directories whose names start with `.` (`.git` and `node_modules` stay excluded). Enable when `vaultRoot` points at the workspace root so `.dsh/memory/` notes are included. |
 
 ### Tools
 
-- `wiki_read(id)` — read one note by vault-relative path and return its frontmatter, body, links, linked notes, and a `version` content fingerprint.
-- `wiki_search(query)` — keyword search across note titles, ids, and bodies; results include backlink counts.
-- `wiki_write(id, content, mode?, baseVersion?)` — create or append to a note. Append mode preserves frontmatter and adds a timestamp header. Passing a `version` from `wiki_read` as `baseVersion` makes the write fail loudly when another writer changed the note in between.
+- `wiki_read(id)` — read one note by vault-relative path and return its frontmatter, body, links, linked notes, a `version` content fingerprint, the file's `mtime` as a `+08:00` timestamp, and a `modifiedExternally` flag that is `true` when the file changed on disk since this plugin last observed it (e.g. an Obsidian edit). The plugin keeps a bounded 256-entry LRU of observed mtimes keyed by absolute path; its own `wiki_write` re-records the mtime so plugin writes never flag. Failures come back as structured errors that name the vault-relative id (`cannot read note "x.md": no such note`) and never embed host paths.
+- `wiki_search(query)` — keyword search across note titles, ids, and bodies; query terms are OR-matched and ranked by field-weighted BM25-style scoring (title/id hits weigh most, rare terms weigh more) plus a verbatim-phrase bonus and a link-graph boost; when `wiki_semantic_search` is mounted the two rankings fuse via reciprocal rank fusion. Returns a `{ hits, total, truncated }` page: each hit carries the note id, title, score, and backlinks; `total` counts every match *before* the `maxSearchResults` cap; `truncated` is `true` when that cap cut the list, so a caller can tell a complete result set from a partial one instead of assuming the vault holds nothing else. Entries that cannot be read (deleted mid-scan, permission denied) are skipped and logged rather than failing the call.
+- `wiki_write(id, content, mode?, baseVersion?)` — create or append to a note. Append mode preserves frontmatter and adds a timestamp header; both write modes normalize `created`/`updated` frontmatter values to `+08:00` second precision (unparseable values pass through). Passing a `version` from `wiki_read` as `baseVersion` makes the write fail loudly when another writer changed the note in between. The result is `{ id, mode, bytes, version }`, where `version` fingerprints the bytes just published — feed it straight back as `baseVersion` on the next write to chain optimistic-concurrency checks without a `wiki_read` round-trip. Writing through an in-vault symlink updates the linked note and keeps the link (a broken link is refused), and atomic replacement carries the note's existing permission bits to the new file.
 
 ### Security
 
-All paths are resolved under the vault root for that call; a path that escapes the vault is rejected. The plugin does not use `ctx.fs`, so the configured filesystem sandbox policy does not apply; vault access is governed by OS permissions and this containment check.
+All paths are resolved under the vault root for that call; a path that escapes the vault is rejected. In-vault symlinks are followed to their real target, which is re-checked for containment, so a symlinked note is appended through rather than replaced; a broken symlink is refused. Error messages stay vault-relative and never embed host paths. The plugin does not use `ctx.fs`, so the configured filesystem sandbox policy does not apply; vault access is governed by OS permissions and this containment check.
 
 -----
 
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
 
-This package is a single Cordis function plugin with no runtime service. It registers three typed tools on `ctx.tools`. The vault root is resolved per tool call: the explicit `vaultRoot` config when set (relative paths anchor at the session workspace), otherwise `<session cwd>/.dsh/memory/` so each workspace owns its notes. Each tool reads Markdown files directly through `node:fs/promises` and stays inside the resolved root via `path.resolve` + prefix checking. YAML frontmatter is parsed with `js-yaml`; `[[link|alias]]` references extract the target before the pipe. Search builds a transient index from the vault contents and sorts hits by backlink count. `wiki_write` publishes atomically: the body is staged in a sibling temp file and `rename`d over the target, so concurrent readers never observe a partially written note.
+This package is a single Cordis function plugin with no runtime service. It registers three typed tools on `ctx.tools`. The vault root is resolved per tool call: the explicit `vaultRoot` config when set (relative paths anchor at the session workspace), otherwise `<session cwd>/.dsh/memory/` so each workspace owns its notes. Each tool reads Markdown files directly through `node:fs/promises` and stays inside the resolved root via `path.resolve` + prefix checking plus a realpath containment re-check. YAML frontmatter is parsed with `js-yaml` (a leading UTF-8 BOM before the opening `---` is tolerated, and duplicate keys resolve last-one-wins instead of dropping the block); `[[link|alias]]` references extract the target before the pipe; `[[...]]` inside inline code spans or fenced code blocks is documentation, not a link, and is ignored. Link targets resolve Obsidian-style against the indexed note ids: an exact vault-relative path first, then a path-suffix match (`[[notes/foo]]` finds `shared/notes/foo.md`), then a basename match anywhere in the vault — each tier tolerates the target carrying or omitting the extension. Ambiguous matches pick the fewest path segments, then the lowest id in code-point order, so resolution is deterministic across platforms. Search builds a transient index from the vault contents and ranks it in layers: OR-matched field-weighted scoring (id/title ×3, backlinks ×1, body ×1, with IDF so rare terms weigh more and BM25 saturation plus length normalization so long notes do not dominate), a verbatim-phrase bonus, and a graph boost for notes linked from strong hits. When `wiki_semantic_search` is registered, its ranking is fused in via reciprocal rank fusion; semantic failures fall back to the lexical ranking. The transient index skips entries that cannot be read (each logged as a warning) so one bad file cannot fail a scan. `wiki_write` publishes atomically: the body is staged in a sibling temp file and `rename`d over the target, so concurrent readers never observe a partially written note; the staged file inherits the target's permission bits and is removed again if staging or rename fails.
 
 -----
 
@@ -76,29 +76,29 @@ This package is a single Cordis function plugin with no runtime service. It regi
 
 #### What the model sees
 
-The model sees the generated [`wiki_read`, `wiki_search`, and `wiki_write` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-memory-filesystem). Their descriptions tell the model that notes are Markdown files with YAML frontmatter and Obsidian-style `[[link]]` references, and that `wiki_read` follows links up to the configured depth.
+The model sees the generated `wiki_read`, `wiki_search`, and `wiki_write` schemas. Their descriptions tell the model that notes are Markdown files with YAML frontmatter and Obsidian-style `[[link]]` references, and that `wiki_read` follows links up to the configured depth.
 
 ##### Verbatim description for `wiki_read`
 
 ```markdown
-Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, and linked notes.
+Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, linked notes, mtime, and a modifiedExternally flag that is true when the file changed on disk since this tool last observed it.
 ```
 
 ##### Verbatim description for `wiki_search`
 
 ```markdown
-Search the wiki vault by note title or body keyword. Returns matching note ids, titles, and backlink counts. Use this before asking the user which note to read.
+Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns { hits, total, truncated }: each hit carries the note id, title, score, and backlinks, total counts every match before the result cap, and truncated is true when that cap cut the list. Use this before asking the user which note to read.
 ```
 
 ##### Verbatim description for `wiki_write`
 
 ```markdown
-Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header.
+Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header. Returns { id, mode, bytes, version }, where version fingerprints the written content and can be passed as baseVersion on the next write without reading the note again.
 ```
 
 #### Token effect
 
-`wiki_read` returns the full body of the requested note plus every linked note reachable within `maxLinkDepth`. Long notes or dense link graphs can add many tokens to the next request. `wiki_search` returns a bounded list of result metadata only.
+`wiki_read` returns the full body of the requested note plus every linked note reachable within `maxLinkDepth`. Long notes or dense link graphs can add many tokens to the next request. `wiki_search` returns a bounded list of result metadata only; its `total` reports matches beyond the cap without returning them.
 
 #### KV Cache effect
 
@@ -112,6 +112,7 @@ Independent. The plugin only supplies tool results; it does not change the reque
 - **No vector search** — search is keyword-only. A separate `tool-memory-vector` package could add embedding-based retrieval without changing this package.
 - **No embedded image or binary support** — notes are treated as UTF-8 text. Attachments should remain in the attachment seam.
 - **No built-in write coordination** — writes are atomic (temp file + `rename`), so readers never see partial files, but simultaneous `wiki_write` calls to the same note can still lose updates. Cooperative callers can pass `baseVersion` to turn a lost update into a loud conflict; mount `@jacklika/dsh-memory-queue` for in-process serialization, optionally with a heartbeat-refreshed cross-process lock.
+- **Unreadable entries are skipped, not surfaced as data** — a note or directory the process cannot read is omitted from read, search, and linked-note results and reported only through a logger warning; the tool result itself does not list what was skipped.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -45,27 +45,27 @@ kind: "package-reference"
 | 字段 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
 | `vaultRoot` | `string` | `''` → `<session cwd>/.dsh/memory/` | 仓库根目录。留空表示使用按工作区隔离的记忆目录；相对路径相对于会话工作区解析。 |
-| `extensions` | `string[]` | `['.md']` | 视为笔记的文件扩展名。 |
+| `extensions` | `string[]` | `['.md']` | 视为笔记的文件扩展名。至少需列出一个扩展名；空列表会导致插件加载失败。 |
 | `maxLinkDepth` | `number` | `1` | `wiki_read` 解析 `[[link]]` 的最大深度。 |
 | `maxSearchResults` | `number` | `20` | `wiki_search` 返回的最大结果数。 |
 | `indexHiddenDirs` | `boolean` | `false` | 是否索引以 `.` 开头的目录（`.git` 与 `node_modules` 始终排除）。当 `vaultRoot` 指向工作区根时开启，以纳入 `.dsh/memory/` 中的笔记。 |
 
 ### 工具
 
-- `wiki_read(id)` — 按仓库相对路径读取笔记，返回 frontmatter、正文、链接、已解析的链接笔记，以及内容指纹 `version`。
-- `wiki_search(query)` — 按标题、id、正文关键词搜索；结果包含反向链接数量。
-- `wiki_write(id, content, mode?, baseVersion?)` — 创建或追加笔记。追加模式保留 frontmatter 并添加时间戳标题。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。
+- `wiki_read(id)` — 按仓库相对路径读取笔记，返回 frontmatter、正文、链接、已解析的链接笔记、内容指纹 `version`、`+08:00` 格式的文件 `mtime`，以及 `modifiedExternally` 标志（文件自本插件上次观察以来在磁盘上被改动时为 `true`，例如 Obsidian 编辑）。插件按绝对路径维护一个 256 条上限的 LRU mtime 表；自身的 `wiki_write` 会刷新记录，因此插件写入永不误报。失败会以结构化错误返回，错误信息只含仓库相对 id（如 `cannot read note "x.md": no such note`），绝不嵌入宿主绝对路径。
+- `wiki_search(query)` — 按标题、id、正文关键词搜索；查询词采用 OR 匹配，并按字段加权的 BM25 式评分排序（标题/id 命中权重最高，稀有词权重更高），另有整段短语加分与被强命中笔记链接的图增强；挂载 `wiki_semantic_search` 时两路排序经 RRF 融合。返回 `{ hits, total, truncated }` 分页结构：每条命中含笔记 id、标题、分数与反向链接；`total` 是 `maxSearchResults` 截断**之前**的全部命中数；`truncated` 为 `true` 表示结果被该上限截断，调用方因此能区分“结果完整”与“还有更多”，而不会误以为仓库里只有这些。无法读取的条目（扫描途中被删除、权限不足）会被跳过并记入日志，而不是让整次调用失败。
+- `wiki_write(id, content, mode?, baseVersion?)` — 创建或追加笔记。追加模式保留 frontmatter 并添加时间戳标题；两种写入模式都会把 `created`/`updated` frontmatter 值归一化为 `+08:00` 秒级精度（不可解析的值原样保留）。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。返回值为 `{ id, mode, bytes, version }`，其中 `version` 就是刚发布内容的指纹——可直接作为下一次写入的 `baseVersion`，无需再 `wiki_read` 一次即可串联乐观并发校验。通过仓库内 symlink 写入会更新链接指向的笔记并保留链接本身（损坏的链接会被拒绝）；原子替换会把笔记原有的权限位带到新文件。
 
 ### 安全
 
-所有路径都必须在该次调用解析出的仓库根目录下；越界路径会被拒绝。该插件不通过 `ctx.fs` 访问文件，因此不继承文件沙箱策略；访问权限由 OS 文件权限和本插件的越界检查共同控制。
+所有路径都必须在该次调用解析出的仓库根目录下；越界路径会被拒绝。仓库内的 symlink 会先解析到真实目标并重新做包含校验，因此追加写入落在链接目标上而非替换链接；损坏的 symlink 会被拒绝。错误信息保持仓库相对路径，不嵌入宿主绝对路径。该插件不通过 `ctx.fs` 访问文件，因此不继承文件沙箱策略；访问权限由 OS 文件权限和本插件的越界检查共同控制。
 
 -----
 
 <a id="understand-the-implementation"></a>
 ## 实现说明
 
-本包是一个没有运行时服务的 Cordis 函数插件，只在 `ctx.tools` 上注册三个类型化工具。仓库根目录在每次工具调用时解析：优先使用显式 `vaultRoot`（相对路径锚定会话工作区），否则使用 `<session cwd>/.dsh/memory/`，使每个工作区拥有自己的笔记。每个工具都通过 `node:fs/promises` 直接读取 Markdown 文件，并借助 `path.resolve` + 前缀检查保持在解析出的根目录内。YAML frontmatter 使用 `js-yaml` 解析；`[[link|alias]]` 形式的引用会提取管道符前的目标。搜索时从仓库内容构建临时索引，并按反向链接数量排序。`wiki_write` 以原子方式发布：正文先写入同级临时文件，再 `rename` 覆盖目标，因此并发读者永远不会读到写了一半的笔记。
+本包是一个没有运行时服务的 Cordis 函数插件，只在 `ctx.tools` 上注册三个类型化工具。仓库根目录在每次工具调用时解析：优先使用显式 `vaultRoot`（相对路径锚定会话工作区），否则使用 `<session cwd>/.dsh/memory/`，使每个工作区拥有自己的笔记。每个工具都通过 `node:fs/promises` 直接读取 Markdown 文件，并借助 `path.resolve` 词法前缀检查加 realpath 包含复检保持在解析出的根目录内。YAML frontmatter 使用 `js-yaml` 解析（开头 `---` 前带 UTF-8 BOM 亦可识别；frontmatter 出现重复键时按“后者胜出”处理，而不是丢弃整个块）；`[[link|alias]]` 形式的引用会提取管道符前的目标；出现在行内代码或围栏代码块中的 `[[...]]` 是语法示例而非链接，会被忽略。链接目标按 Obsidian 语义对已索引的笔记 id 解析：先精确匹配仓库相对路径，再做路径后缀匹配（`[[notes/foo]]` 可命中 `shared/notes/foo.md`），最后匹配仓库内任意位置的 basename——每一级都容忍目标带或不带扩展名。多重命中时优先路径段最少者，仍并列则取码点序最小的 id，因此解析结果跨平台确定。搜索时从仓库内容构建临时索引（无法读取的条目会被跳过并记入日志，单个坏文件不会使整次扫描失败）并分层排序：OR 匹配的字段加权评分（id/标题 ×3、反向链接 ×1、正文 ×1，含 IDF 使稀有词权重更高、BM25 饱和与长度归一化避免长笔记占优）、整段短语加分，以及被强命中笔记链接的图增强。挂载 `wiki_semantic_search` 时其排序经倒数排名融合并入；语义检索失败时回退到纯词法排序。`wiki_write` 以原子方式发布：正文先写入同级临时文件，再 `rename` 覆盖目标，因此并发读者永远不会读到写了一半的笔记；临时文件继承目标笔记的权限位，且写入或 rename 失败时会被清理。
 
 -----
 
@@ -76,29 +76,29 @@ kind: "package-reference"
 
 #### 模型看到的内容
 
-模型看到的是生成的 [`wiki_read`、`wiki_search` 和 `wiki_write` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-memory-filesystem)。工具描述会告知模型：笔记是带 YAML frontmatter 和 Obsidian 风格 `[[link]]` 链接的 Markdown 文件，`wiki_read` 会按配置深度跟随链接。
+模型看到的是生成的 `wiki_read`、`wiki_search` 和 `wiki_write` schema。工具描述会告知模型：笔记是带 YAML frontmatter 和 Obsidian 风格 `[[link]]` 链接的 Markdown 文件，`wiki_read` 会按配置深度跟随链接。
 
 ##### `wiki_read` 的完整描述
 
 ```markdown
-Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, and linked notes.
+Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, linked notes, mtime, and a modifiedExternally flag that is true when the file changed on disk since this tool last observed it.
 ```
 
 ##### `wiki_search` 的完整描述
 
 ```markdown
-Search the wiki vault by note title or body keyword. Returns matching note ids, titles, and backlink counts. Use this before asking the user which note to read.
+Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns { hits, total, truncated }: each hit carries the note id, title, score, and backlinks, total counts every match before the result cap, and truncated is true when that cap cut the list. Use this before asking the user which note to read.
 ```
 
 ##### `wiki_write` 的完整描述
 
 ```markdown
-Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header.
+Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header. Returns { id, mode, bytes, version }, where version fingerprints the written content and can be passed as baseVersion on the next write without reading the note again.
 ```
 
 #### Token 影响
 
-`wiki_read` 返回请求笔记的完整正文，以及 `maxLinkDepth` 范围内所有可达链接笔记的正文。长笔记或密集链接图可能显著增加下次请求的 token 数。`wiki_search` 只返回有限的结果元数据。
+`wiki_read` 返回请求笔记的完整正文，以及 `maxLinkDepth` 范围内所有可达链接笔记的正文。长笔记或密集链接图可能显著增加下次请求的 token 数。`wiki_search` 只返回有限的结果元数据；其 `total` 会告知被上限截断而未返回的命中数量。
 
 #### KV Cache 影响
 
@@ -112,6 +112,7 @@ Create a new note or append to an existing note in the wiki vault. The path is r
 - **无向量搜索** — 仅支持关键词搜索。未来可新增 `tool-memory-vector` 包提供基于 embedding 的检索，而无需修改本包。
 - **不支持图片或二进制附件** — 笔记按 UTF-8 文本处理。附件应继续使用 attachment 体系。
 - **无内置写协调** —— 写入是原子的（临时文件 + `rename`），读者不会看到半写文件，但对同一笔记的并发 `wiki_write` 仍可能丢更新。协作调用方可传 `baseVersion` 把丢更新变成显式冲突；挂载 `@jacklika/dsh-memory-queue` 可获得进程内串行化，并可选用心跳刷新的跨进程锁。
+- **无法读取的条目被跳过而非作为数据暴露** —— 进程读不到的笔记或目录会从读取、搜索与链接解析结果中消失，仅通过 logger 警告报告；工具返回值本身不会列出被跳过的条目。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -8,11 +8,19 @@
  * @module @jacklika/dsh-tool-memory-filesystem
  */
 import { createHash, randomUUID } from 'node:crypto';
-import { readdir, readFile, realpath, rename, rm, stat, writeFile, mkdir } from 'node:fs/promises';
+import { chmod, lstat, mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { formatBeijingTime } from '@jacklika/dsh-memory-time';
 import yaml from 'js-yaml';
+import { codeUnitCompare, fuseRankings, rankNotes } from "./search.js";
+/**
+ * Locale-independent note-id ordering, re-exported so sibling packages that
+ * truncate or tie-break id lists sort by the same rule instead of a copy that
+ * can drift.
+ */
+export { codeUnitCompare };
 /**
  * Compute a vault-relative note id from an absolute path. The result always
  * uses POSIX separators so note ids are stable across Windows, macOS, and Linux.
@@ -56,11 +64,14 @@ export function resolveMemoryVaultRoot(vaultRoot, exec) {
  * @returns the absolute, contained path.
  */
 export function containedPath(root, candidate) {
+    if (candidate.includes('\0')) {
+        throw new Error('tool-memory-filesystem: note id must not contain a NUL byte');
+    }
     const absoluteRoot = resolve(root);
     const absolute = resolve(absoluteRoot, candidate);
     const remainder = relative(absoluteRoot, absolute);
     if (remainder === '..' || remainder.startsWith(`..${sep}`) || isAbsolute(remainder)) {
-        throw new Error(`tool-memory-filesystem: path ${candidate} is outside vault root ${root}`);
+        throw new Error(`tool-memory-filesystem: path ${JSON.stringify(candidate)} is outside the vault root`);
     }
     return absolute;
 }
@@ -81,7 +92,7 @@ export async function containedPathReal(root, candidate) {
             const canonicalAncestor = await realpath(ancestor);
             const remainder = relative(canonicalRoot, canonicalAncestor);
             if (remainder === '..' || remainder.startsWith(`..${sep}`) || isAbsolute(remainder)) {
-                throw new Error(`tool-memory-filesystem: path ${candidate} resolves outside vault root ${root}`);
+                throw new Error(`tool-memory-filesystem: path ${JSON.stringify(candidate)} resolves outside the vault root`);
             }
             return absolute;
         }
@@ -97,25 +108,35 @@ export async function containedPathReal(root, candidate) {
 }
 /**
  * Extract YAML frontmatter and body from Markdown text. Only the leading
- * `---\n...\n---\n` form is recognized.
+ * `---\n...\n---\n` form is recognized, optionally behind a UTF-8 BOM.
+ * Duplicate keys resolve last-one-wins rather than dropping the block.
  * @param text - raw file contents.
  * @returns frontmatter map and body.
  */
 export function splitFrontmatter(text) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(text);
+    // A UTF-8 BOM is invisible but pushes the opening fence off the start of the
+    // string, which would silently drop the whole frontmatter block.
+    const source = text.startsWith('\uFEFF') ? text.slice(1) : text;
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
     if (match === null) {
         return { frontmatter: {}, body: text };
     }
     const frontmatterText = match[1] ?? '';
     const bodyText = match[2] ?? '';
     try {
-        const parsed = yaml.load(frontmatterText);
-        return {
-            frontmatter: parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
-                ? parsed
-                : {},
-            body: bodyText,
-        };
+        // `json: true` makes duplicate keys last-one-wins instead of throwing;
+        // throwing falls into the catch below and drops every field.
+        const parsed = yaml.load(frontmatterText, { json: true });
+        const frontmatter = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+        // js-yaml coerces unquoted timestamps to Date; vault convention stores them
+        // as Asia/Shanghai +08:00 strings, so convert back before they reach callers.
+        for (const [key, value] of Object.entries(frontmatter)) {
+            if (value instanceof Date)
+                frontmatter[key] = formatBeijingTime(value);
+        }
+        return { frontmatter, body: bodyText };
     }
     catch {
         return { frontmatter: {}, body: text };
@@ -130,6 +151,68 @@ export function splitFrontmatter(text) {
 export function noteVersion(text) {
     return createHash('sha1').update(text, 'utf8').digest('hex');
 }
+/**
+ * Last `mtimeMs` observed per note path, keyed by absolute path so identical
+ * note ids in different vaults never collide. Bounded at 256 entries with
+ * LRU eviction: an unbounded map would grow with every note ever read in a
+ * long-running process, while a fixed cap keeps the newest observations —
+ * the only ones a `modifiedExternally` comparison can still act on.
+ */
+const observedMtimes = new Map();
+const OBSERVED_MTIME_LIMIT = 256;
+/**
+ * Record the freshest observed `mtimeMs` for a path, evicting the oldest
+ * entry when the cap is reached.
+ */
+function recordMtime(path, mtimeMs) {
+    observedMtimes.delete(path);
+    observedMtimes.set(path, mtimeMs);
+    if (observedMtimes.size > OBSERVED_MTIME_LIMIT) {
+        const oldest = observedMtimes.keys().next().value;
+        if (oldest !== undefined)
+            observedMtimes.delete(oldest);
+    }
+}
+/**
+ * Whether the note changed on disk since this plugin last observed it.
+ * The first observation records and reports `false`; a successful
+ * `wiki_write` re-records so the plugin's own writes never flag.
+ */
+function detectExternalChange(path, mtimeMs) {
+    const seen = observedMtimes.get(path);
+    recordMtime(path, mtimeMs);
+    return seen !== undefined && seen !== mtimeMs;
+}
+/**
+ * Normalize `created`/`updated` frontmatter timestamps to the vault's
+ * `+08:00` second-precision convention. Parseable values in any other form
+ * (`Z`, `+00:00`, millisecond precision) are rewritten; unparseable values
+ * pass through untouched so a non-date string is never corrupted.
+ */
+export function normalizeNoteTimestamps(frontmatter) {
+    for (const key of ['created', 'updated']) {
+        const value = frontmatter[key];
+        if (typeof value !== 'string')
+            continue;
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime()))
+            continue;
+        const normalized = formatBeijingTime(parsed);
+        if (normalized !== value)
+            frontmatter[key] = normalized;
+    }
+}
+/**
+ * Normalize timestamps inside a complete note text. Returns the text
+ * unchanged when there is no frontmatter to rewrite.
+ */
+function normalizeTextTimestamps(text) {
+    const { frontmatter, body } = splitFrontmatter(text);
+    if (Object.keys(frontmatter).length === 0)
+        return text;
+    normalizeNoteTimestamps(frontmatter);
+    return `---\n${yaml.dump(frontmatter).trim()}\n---\n${body}`;
+}
 /**
  * Find all Obsidian-style `[[link]]` references in note text. Aliases of the
  * form `[[link|alias]]` return the link target only.
@@ -140,12 +223,66 @@ export function extractLinks(text) {
     const links = [];
     const pattern = /\[\[([^|\]\r\n]+)(?:\|[^\]]*)?\]\]/g;
     let match;
-    while ((match = pattern.exec(text)) !== null) {
+    while ((match = pattern.exec(stripCode(text))) !== null) {
         if (match[1] !== undefined)
             links.push(match[1].trim());
     }
     return [...new Set(links)];
 }
+/**
+ * Remove fenced code blocks and inline code spans so literal `[[...]]` inside
+ * them is not treated as a link. Fences follow CommonMark: a closing fence
+ * must use the same marker character and be at least as long as the opener —
+ * a rule a regex backreference cannot express, so fences are scanned line by
+ * line. Inline spans treat backtick runs as maximal units: a run closes only
+ * at a later run of exactly equal length; an unmatched run is literal text.
+ * @param text - note body.
+ * @returns the text with all code sections dropped.
+ */
+function stripCode(text) {
+    const kept = [];
+    let fenceChar = '';
+    let fenceLen = 0;
+    for (const line of text.split('\n')) {
+        if (fenceChar === '') {
+            const open = /^( {0,3})(`{3,}|~{3,})/.exec(line);
+            if (open?.[2] !== undefined) {
+                fenceChar = open[2][0] ?? '';
+                fenceLen = open[2].length;
+                continue;
+            }
+            kept.push(line);
+        }
+        else if (new RegExp(`^ {0,3}${fenceChar === '`' ? '`' : '~'}{${fenceLen},}[ \t]*$`).test(line)) {
+            fenceChar = '';
+        }
+    }
+    const body = kept.join('\n');
+    let out = '';
+    let i = 0;
+    while (i < body.length) {
+        if (body[i] !== '`') {
+            out += body[i];
+            i++;
+            continue;
+        }
+        let j = i;
+        while (body[j] === '`')
+            j++;
+        const run = body.slice(i, j);
+        let close = body.indexOf(run, j);
+        while (close !== -1 && (body[close - 1] === '`' || body[close + run.length] === '`')) {
+            close = body.indexOf(run, close + 1);
+        }
+        if (close === -1) {
+            out += run;
+            i = j;
+            continue;
+        }
+        i = close + run.length;
+    }
+    return out;
+}
 /**
  * Normalize a configured file extension to a dot-prefixed form.
  * @param ext - extension string.
@@ -155,17 +292,86 @@ export function dottedExtension(ext) {
     return ext.startsWith('.') ? ext : `.${ext}`;
 }
 /**
- * Resolve a link target to an existing note file inside the vault. The target
- * may omit the extension; extensions are tried in config order.
+ * Build a resolver over the known note ids, matching Obsidian semantics: an
+ * exact vault-relative path first, then a path-suffix match, then a bare
+ * basename match — each tier tolerates the target carrying or omitting the
+ * extension. Ambiguity within a tier resolves to the id with the fewest path
+ * segments, ties by code-unit order, so results are identical across hosts.
+ * @param ids - vault-relative note ids (e.g. `shared/notes/foo.md`).
+ * @returns resolver function for `[[...]]` targets.
+ */
+export function createLinkResolver(ids) {
+    const entries = ids.map(id => {
+        const stem = id.replace(/\.[^./]+$/, '');
+        return {
+            id,
+            stem,
+            basenameId: id.slice(id.lastIndexOf('/') + 1),
+            basenameStem: stem.slice(stem.lastIndexOf('/') + 1),
+            segments: id.split('/').length,
+        };
+    });
+    // O(1) lookup tables keyed by every segment-boundary suffix of each id and
+    // stem: an exact hit is the full-string key, a path-suffix hit is a proper
+    // suffix, and a basename hit is the last segment.
+    const exact = new Map();
+    const suffix = new Map();
+    const basename = new Map();
+    const add = (table, key, entry) => {
+        const list = table.get(key);
+        if (list === undefined)
+            table.set(key, [entry]);
+        else
+            list.push(entry);
+    };
+    for (const entry of entries) {
+        add(basename, entry.basenameId, entry);
+        add(basename, entry.basenameStem, entry);
+        for (const s of [entry.id, entry.stem]) {
+            let boundary = -1;
+            while ((boundary = s.indexOf('/', boundary + 1)) !== -1) {
+                add(suffix, s.slice(boundary + 1), entry);
+            }
+            add(exact, s, entry);
+        }
+    }
+    const pick = (matches) => {
+        if (matches === undefined || matches.length === 0)
+            return undefined;
+        matches.sort((a, b) => a.segments - b.segments || codeUnitCompare(a.id, b.id));
+        return matches[0]?.id;
+    };
+    return (target) => {
+        const t = target.replace(/\\/g, '/');
+        const hit = pick(exact.get(t)) ?? pick(suffix.get(t)) ?? pick(basename.get(t));
+        return hit;
+    };
+}
+/**
+ * Resolve a link target to an existing note file inside the vault. When
+ * `resolve` is provided the target is first looked up in the note-id set with
+ * Obsidian semantics (exact path, then path suffix, then basename); otherwise
+ * the target is probed as a vault-relative path and extensions are tried in
+ * config order. Every result still passes the realpath containment check.
  * @param root - vault root.
  * @param extensions - note extensions.
  * @param target - link target from `[[...]]`.
+ * @param resolve - optional resolver built by {@link createLinkResolver}.
  * @returns the resolved absolute path, or `undefined` if no file exists.
  */
-export async function resolveLinkTarget(root, extensions, target) {
+export async function resolveLinkTarget(root, extensions, target, resolve) {
+    if (resolve !== undefined) {
+        const id = resolve(target);
+        if (id !== undefined)
+            return containedPathReal(root, id);
+    }
     const candidates = extensions.map(ext => `${target}${dottedExtension(ext)}`);
     candidates.push(target);
     for (const candidate of candidates) {
+        // A NUL byte can never name a real note; skip it instead of aborting the
+        // whole read over one malformed link.
+        if (candidate.includes('\0'))
+            continue;
         try {
             const path = await containedPathReal(root, candidate);
             const info = await stat(path);
@@ -186,13 +392,32 @@ export async function resolveLinkTarget(root, extensions, target) {
  * @param root - vault root.
  * @param extensions - note extensions.
  * @param indexHiddenDirs - descend into remaining dot-directories.
+ * @param onSkip - optional callback for entries skipped because they could not
+ *   be read; one unreadable directory must not fail the whole vault scan.
  * @returns absolute paths of every note file.
  */
-export async function listNotePaths(root, extensions, indexHiddenDirs = false) {
+export async function listNotePaths(root, extensions, indexHiddenDirs = false, onSkip) {
     const results = [];
     const exclude = new Set(['.git', 'node_modules', '.obsidian']);
+    try {
+        if (!(await stat(root)).isDirectory())
+            return results;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return results;
+        throw err;
+    }
     async function walk(dir) {
-        const entries = await readdir(dir, { withFileTypes: true });
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            // An unreadable directory hides only its own subtree.
+            onSkip?.(dir, error);
+            return;
+        }
         for (const entry of entries) {
             if (!indexHiddenDirs && entry.name.startsWith('.') && entry.name !== '.')
                 continue;
@@ -217,9 +442,11 @@ export async function listNotePaths(root, extensions, indexHiddenDirs = false) {
  * @param maxLinkDepth - how many link hops to resolve.
  * @param absolutePath - absolute path of the note.
  * @param visited - set of already-visited absolute paths to prevent cycles.
+ * @param linkResolver - resolver over the vault's note ids; built once per
+ *   call tree so bare `[[filename]]` links resolve without rescanning.
  * @returns the parsed note with linked notes attached.
  */
-export async function readNote(root, extensions, maxLinkDepth, absolutePath, visited = new Set()) {
+export async function readNote(root, extensions, maxLinkDepth, absolutePath, visited = new Set(), linkResolver) {
     if (visited.has(absolutePath)) {
         return {
             path: absolutePath,
@@ -239,9 +466,9 @@ export async function readNote(root, extensions, maxLinkDepth, absolutePath, vis
     const linkedNotes = [];
     if (maxLinkDepth > 0) {
         for (const link of links) {
-            const target = await resolveLinkTarget(root, extensions, link);
+            const target = await resolveLinkTarget(root, extensions, link, linkResolver);
             if (target !== undefined) {
-                const child = await readNote(root, extensions, maxLinkDepth - 1, target, nextVisited);
+                const child = await readNote(root, extensions, maxLinkDepth - 1, target, nextVisited, linkResolver);
                 linkedNotes.push(child);
             }
         }
@@ -263,13 +490,22 @@ export async function readNote(root, extensions, maxLinkDepth, absolutePath, vis
  * @param root - vault root.
  * @param extensions - note extensions.
  * @param indexHiddenDirs - descend into dot-directories besides the fixed exclusions.
+ * @param onSkip - optional callback for notes skipped because they could not
+ *   be read; one unreadable note must not fail search for the whole vault.
  * @returns a map from note id to search result.
  */
-export async function buildIndex(root, extensions, indexHiddenDirs = false) {
-    const paths = await listNotePaths(root, extensions, indexHiddenDirs);
+export async function buildIndex(root, extensions, indexHiddenDirs = false, onSkip) {
+    const paths = await listNotePaths(root, extensions, indexHiddenDirs, onSkip);
     const notes = [];
     for (const path of paths) {
-        const text = await readFile(path, 'utf8');
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            onSkip?.(path, error);
+            continue;
+        }
         const { frontmatter, body } = splitFrontmatter(text);
         notes.push({
             path,
@@ -282,18 +518,19 @@ export async function buildIndex(root, extensions, indexHiddenDirs = false) {
     }
     const index = new Map();
     for (const note of notes) {
+        const explicitTitle = typeof note.frontmatter.title === 'string' ? note.frontmatter.title.trim() : '';
         const headingMatch = /^#\s+(.+)$/m.exec(note.body);
-        const title = headingMatch !== null && headingMatch[1] !== undefined
-            ? headingMatch[1].trim()
-            : note.id.replace(/\.[^.]+$/, '');
+        const title = explicitTitle !== ''
+            ? explicitTitle
+            : (headingMatch !== null && headingMatch[1] !== undefined
+                ? headingMatch[1].trim()
+                : note.id.replace(/\.[^.]+$/, ''));
         index.set(note.id, { id: note.id, title, backlinks: [], body: note.body });
     }
+    const linkResolver = createLinkResolver([...index.keys()]);
     for (const note of notes) {
         for (const link of note.links) {
-            const targetId = [...index.keys()].find((id) => {
-                const base = id.replace(/\.[^.]+$/, '');
-                return base === link || id === link;
-            });
+            const targetId = linkResolver(link);
             if (targetId !== undefined) {
                 const entry = index.get(targetId);
                 if (entry !== undefined && !entry.backlinks.includes(note.id)) {
@@ -313,8 +550,19 @@ export async function buildIndex(root, extensions, indexHiddenDirs = false) {
  */
 async function writeAtomic(absolutePath, contents) {
     const tmpPath = `${absolutePath}.tmp-${process.pid}-${randomUUID()}`;
+    // rename replaces the inode, so carry an existing target's permission bits
+    // onto the staged file; otherwise a read-only note silently becomes writable.
+    let mode;
     try {
-        await writeFile(tmpPath, contents, 'utf8');
+        mode = (await stat(absolutePath)).mode & 0o7777;
+    }
+    catch {
+        // New note: keep the default creation mode.
+    }
+    try {
+        await writeFile(tmpPath, contents, { encoding: 'utf8', ...(mode === undefined ? {} : { mode }) });
+        if (mode !== undefined)
+            await chmod(tmpPath, mode);
         await rename(tmpPath, absolutePath);
     }
     catch (error) {
@@ -322,6 +570,66 @@ async function writeAtomic(absolutePath, contents) {
         throw error;
     }
 }
+/**
+ * Turn a filesystem failure into a structured, vault-relative tool error. Raw
+ * Node errors carry absolute host paths and no plugin context; callers see
+ * `tool-memory-filesystem: cannot read note "x.md": permission denied` instead.
+ */
+function noteIoError(action, id, error) {
+    return new Error(`tool-memory-filesystem: cannot ${action} note ${JSON.stringify(id)}: ${describeIoError(error)}`);
+}
+/** Short, host-path-free description of one filesystem error. */
+function describeIoError(error) {
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return 'no such note';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'permission denied';
+    if (code === 'EISDIR')
+        return 'path is a directory';
+    if (typeof code === 'string' && code !== '')
+        return code;
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Follow a symlink at the final path component so a write publishes through
+ * the link instead of replacing it: the sibling-temp + rename sequence targets
+ * the directory entry itself, which would otherwise turn an alias note into a
+ * regular file and leave the linked note untouched.
+ */
+async function resolveSymlinkWriteTarget(root, absolutePath, id) {
+    const info = await lstat(absolutePath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw noteIoError('write', id, error);
+    });
+    if (info === undefined || !info.isSymbolicLink())
+        return absolutePath;
+    const canonical = await realpath(absolutePath).catch(() => {
+        // A broken link cannot be written through; replacing it would silently
+        // discard the alias, so refuse instead.
+        throw new Error(`tool-memory-filesystem: cannot write through broken symbolic link ${JSON.stringify(id)}`);
+    });
+    const canonicalRoot = await realpath(resolve(root));
+    const remainder = relative(canonicalRoot, canonical);
+    if (remainder === '..' || remainder.startsWith(`..${sep}`) || isAbsolute(remainder)) {
+        throw new Error(`tool-memory-filesystem: path ${JSON.stringify(id)} resolves outside the vault root`);
+    }
+    return canonical;
+}
+/** Build the skip callback that reports unreadable entries to the Loader logger. */
+function skipLogger(ctx, root) {
+    return (path, error) => {
+        const code = error.code ?? 'unknown';
+        ctx.logger?.warn(`tool-memory-filesystem: skipped unreadable entry ${vaultRelativeId(root, path)} (${code})`);
+    };
+}
+/** Validate that at least one note extension is configured. */
+function assertExtensions(extensions) {
+    if (extensions.length === 0) {
+        throw new Error('tool-memory-filesystem: extensions must list at least one file extension');
+    }
+}
 /** Validate a positive-integer config bound. */
 function assertPositiveInteger(name, value) {
     if (!Number.isInteger(value) || value < 1) {
@@ -343,10 +651,11 @@ export function apply(ctx, config) {
     const resolved = config;
     assertPositiveInteger('maxLinkDepth', resolved.maxLinkDepth);
     assertPositiveInteger('maxSearchResults', resolved.maxSearchResults);
+    assertExtensions(resolved.extensions);
     const vaultRootFor = (exec) => resolveMemoryVaultRoot(resolved.vaultRoot, exec);
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_read',
-        description: 'Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, and linked notes.',
+        description: 'Read one Markdown note from the wiki vault, optionally following Obsidian-style [[link]] references up to the configured depth. Returns the note id, frontmatter, body, linked notes, mtime, and a modifiedExternally flag that is true when the file changed on disk since this tool last observed it.',
         parameters: {
             id: {
                 type: 'string',
@@ -361,13 +670,21 @@ export function apply(ctx, config) {
         async execute(args, exec) {
             const vaultRoot = vaultRootFor(exec);
             const absolutePath = await containedPathReal(vaultRoot, args.id);
-            const note = await readNote(vaultRoot, resolved.extensions, resolved.maxLinkDepth, absolutePath);
-            return note;
+            const linkResolver = createLinkResolver((await listNotePaths(vaultRoot, resolved.extensions, resolved.indexHiddenDirs, skipLogger(ctx, vaultRoot)))
+                .map(path => vaultRelativeId(vaultRoot, path)));
+            const note = await readNote(vaultRoot, resolved.extensions, resolved.maxLinkDepth, absolutePath, new Set(), linkResolver)
+                .catch(error => { throw noteIoError('read', args.id, error); });
+            const info = await stat(absolutePath).catch(error => { throw noteIoError('read', args.id, error); });
+            return {
+                ...note,
+                mtime: formatBeijingTime(info.mtime),
+                modifiedExternally: detectExternalChange(absolutePath, info.mtimeMs),
+            };
         },
     })));
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_search',
-        description: 'Search the wiki vault by note title or body keyword. Returns matching note ids, titles, and backlink counts. Use this before asking the user which note to read.',
+        description: 'Search the wiki vault by note title or body keyword. Terms are OR-matched; results are ranked by field-weighted relevance (title/id hits outrank body hits, rare terms weigh more, notes linked from strong hits get a boost, and results may be fused with semantic search when available). Returns { hits, total, truncated }: each hit carries the note id, title, score, and backlinks, total counts every match before the result cap, and truncated is true when that cap cut the list. Use this before asking the user which note to read.',
         parameters: {
             query: {
                 type: 'string',
@@ -377,37 +694,73 @@ export function apply(ctx, config) {
         },
         output: {
             schema: {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    additionalProperties: false,
-                    properties: {
-                        id: { type: 'string' },
-                        title: { type: 'string' },
-                        backlinks: { type: 'array', items: { type: 'string' } },
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    hits: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                id: { type: 'string' },
+                                title: { type: 'string' },
+                                score: { type: 'number' },
+                                backlinks: { type: 'array', items: { type: 'string' } },
+                            },
+                        },
                     },
+                    total: { type: 'integer' },
+                    truncated: { type: 'boolean' },
                 },
             },
             render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
         },
         async execute(args, exec) {
             const vaultRoot = vaultRootFor(exec);
-            const index = await buildIndex(vaultRoot, resolved.extensions, resolved.indexHiddenDirs);
-            const terms = args.query.toLowerCase().split(/\s+/).filter(Boolean);
-            const hits = [];
-            for (const result of index.values()) {
-                const haystack = `${result.id} ${result.title} ${result.backlinks.join(' ')} ${result.body}`.toLowerCase();
-                if (terms.every(term => haystack.includes(term))) {
-                    hits.push({ id: result.id, title: result.title, backlinks: result.backlinks });
+            const index = await buildIndex(vaultRoot, resolved.extensions, resolved.indexHiddenDirs, skipLogger(ctx, vaultRoot));
+            let hits = rankNotes(index, args.query);
+            // Optional semantic layer: when `wiki_semantic_search` is mounted, fuse
+            // both rankings via reciprocal rank fusion. Only the dispatch is
+            // fail-soft — an unavailable or erroring semantic layer degrades to the
+            // lexical ranking; parse/fusion errors propagate so real bugs surface
+            // instead of silently weakening results.
+            if (ctx.tools.get('wiki_semantic_search') !== undefined) {
+                let semantic;
+                try {
+                    semantic = await ctx.tools.execute({
+                        callId: `${exec.callId}:wiki_semantic_search:${randomUUID()}`,
+                        rootCallId: exec.rootCallId,
+                        name: 'wiki_semantic_search',
+                        arguments: { query: args.query },
+                        parent: exec.token,
+                        signal: exec.signal,
+                        ...(exec.agent !== undefined ? { agent: exec.agent } : {}),
+                    });
+                }
+                catch (error) {
+                    ctx.logger?.warn('tool-memory-filesystem: semantic fusion skipped: ' + String(error));
+                }
+                if (semantic !== undefined && !semantic.isError) {
+                    const semanticHits = JSON.parse(semantic.content
+                        .map(block => {
+                        const maybe = block;
+                        return maybe.type === 'text' && typeof maybe.text === 'string' ? maybe.text : '';
+                    })
+                        .join('') || '[]');
+                    hits = fuseRankings(hits, semanticHits.map(hit => hit.id), index);
+                }
+                else if (semantic !== undefined) {
+                    ctx.logger?.warn('tool-memory-filesystem: semantic fusion skipped: wiki_semantic_search returned an error');
                 }
             }
-            hits.sort((a, b) => b.backlinks.length - a.backlinks.length);
-            return hits.slice(0, resolved.maxSearchResults);
+            const capped = hits.slice(0, resolved.maxSearchResults);
+            return { hits: capped, total: hits.length, truncated: capped.length < hits.length };
         },
     })));
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'wiki_write',
-        description: 'Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header.',
+        description: 'Create a new note or append to an existing note in the wiki vault. The path is relative to the vault root. When appending, the new content is inserted at the end of the body after a timestamp header. Returns { id, mode, bytes, version }, where version fingerprints the written content and can be passed as baseVersion on the next write without reading the note again.',
         parameters: {
             id: {
                 type: 'string',
@@ -426,7 +779,7 @@ export function apply(ctx, config) {
             },
             baseVersion: {
                 type: 'string',
-                description: 'Optional version returned by wiki_read. When provided, the write fails if the note changed since that read.',
+                description: 'Optional version returned by wiki_read or by an earlier wiki_write. When provided, the write fails if the note changed since that version.',
             },
         },
         output: {
@@ -437,6 +790,10 @@ export function apply(ctx, config) {
                     id: { type: 'string' },
                     mode: { type: 'string' },
                     bytes: { type: 'integer' },
+                    version: { type: 'string' },
+                    created: { type: 'string' },
+                    updated: { type: 'string' },
+                    committed: { type: 'boolean' },
                 },
             },
             render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
@@ -450,34 +807,76 @@ export function apply(ctx, config) {
             if (!hasExtension) {
                 throw new Error(`tool-memory-filesystem: note id must end with one of ${resolved.extensions.join(', ')}`);
             }
-            await mkdir(dirname(absolutePath), { recursive: true });
+            const writeTarget = await resolveSymlinkWriteTarget(vaultRoot, absolutePath, args.id);
+            try {
+                await mkdir(dirname(writeTarget), { recursive: true });
+            }
+            catch (error) {
+                throw noteIoError('write', args.id, error);
+            }
             await containedPathReal(vaultRoot, args.id);
             exec.signal.throwIfAborted();
             let existing;
             try {
-                existing = await readFile(absolutePath, 'utf8');
+                existing = await readFile(writeTarget, 'utf8');
             }
-            catch {
-                // file does not exist yet
+            catch (error) {
+                // Only a missing file means a first write; any other failure (a
+                // directory in the way, an unreadable note) must not silently fall
+                // back to treating the note as new and replacing it.
+                if (error.code !== 'ENOENT')
+                    throw noteIoError('write', args.id, error);
             }
             if (args.baseVersion !== undefined && noteVersion(existing ?? '') !== args.baseVersion) {
                 throw new Error(`tool-memory-filesystem: note ${args.id} changed since it was read; re-read it before writing`);
             }
             let finalBody;
+            let frontmatter = {};
             if (mode === 'overwrite') {
-                finalBody = args.content;
+                finalBody = normalizeTextTimestamps(args.content);
+                frontmatter = splitFrontmatter(finalBody).frontmatter;
             }
             else {
-                const { frontmatter, body } = splitFrontmatter(existing ?? '');
+                const split = splitFrontmatter(existing ?? '');
+                frontmatter = split.frontmatter;
+                const body = split.body;
+                normalizeNoteTimestamps(frontmatter);
+                const timestamp = formatBeijingTime(new Date());
+                // Track note lifetime the way memory_capture does: `created` on the
+                // first write, `updated` on every append thereafter.
+                if (existing === undefined) {
+                    frontmatter.created ??= timestamp;
+                }
+                else {
+                    frontmatter.updated = timestamp;
+                }
                 const frontmatterText = Object.keys(frontmatter).length > 0
                     ? `---\n${yaml.dump(frontmatter).trim()}\n---\n\n`
                     : '';
-                const timestamp = new Date().toISOString();
-                finalBody = `${frontmatterText}${body}\n\n## ${timestamp}\n\n${args.content}\n`;
+                // Content that opens with its own heading supplies the section
+                // header, so a bare `## <time>` above it would duplicate it.
+                const header = args.content.trimStart().startsWith('#') ? '' : `## ${timestamp}\n\n`;
+                const base = `${frontmatterText}${body}`.replace(/\s+$/, '');
+                finalBody = base === '' ? `${header}${args.content}\n` : `${base}\n\n${header}${args.content}\n`;
             }
             exec.signal.throwIfAborted();
-            await writeAtomic(absolutePath, finalBody);
-            return { id: vaultRelativeId(vaultRoot, absolutePath), mode, bytes: Buffer.byteLength(finalBody, 'utf8') };
+            await writeAtomic(writeTarget, finalBody)
+                .catch(error => { throw noteIoError('write', args.id, error); });
+            const info = await stat(writeTarget);
+            recordMtime(absolutePath, info.mtimeMs);
+            const result = {
+                id: vaultRelativeId(vaultRoot, absolutePath),
+                mode,
+                bytes: Buffer.byteLength(finalBody, 'utf8'),
+                // `writeAtomic` publishes `finalBody` verbatim, so this is the same
+                // fingerprint `wiki_read` would report — without a second read.
+                version: noteVersion(finalBody),
+            };
+            if (typeof frontmatter.created === 'string' && frontmatter.created !== '')
+                result.created = frontmatter.created;
+            if (typeof frontmatter.updated === 'string' && frontmatter.updated !== '')
+                result.updated = frontmatter.updated;
+            return result;
         },
     })));
 }

package/lib/search.js

@@ -0,0 +1,150 @@
+/**
+ * Multi-layer lexical ranking for `wiki_search`: field-weighted BM25-style
+ * scoring over note id/title/backlinks/body, a verbatim-phrase bonus, and a
+ * link-graph boost for notes referenced by strong lexical hits. Substring
+ * matching (not tokenization) keeps CJK text working without a segmenter.
+ * @module @jacklika/dsh-tool-memory-filesystem/search
+ */
+const K1 = 1.2;
+const B = 0.75;
+const TITLE_WEIGHT = 3;
+const BODY_WEIGHT = 1;
+const BACKLINK_WEIGHT = 1;
+const GRAPH_BOOST = 0.15;
+const RRF_K = 60;
+function countOccurrences(haystack, needle) {
+    if (needle === '')
+        return 0;
+    let count = 0;
+    let from = 0;
+    while ((from = haystack.indexOf(needle, from)) !== -1) {
+        count += 1;
+        from += needle.length;
+    }
+    return count;
+}
+function toHit(note, score) {
+    return {
+        id: note.id,
+        title: note.title,
+        score: Math.round(score * 10000) / 10000,
+        backlinks: note.backlinks,
+    };
+}
+/**
+ * Rank every note in `index` against `query`. Any note containing at least one
+ * query term (OR semantics) is a candidate; scores follow BM25 saturation with
+ * field weights (`id`/`title` ×3, backlinks ×1, body ×1), a phrase bonus for a
+ * verbatim multi-term match, and a graph boost for notes linked from a scored
+ * hit.
+ * @param index - note index built by {@link buildIndex}.
+ * @param query - raw query text.
+ * @returns hits sorted by descending score.
+ */
+export function rankNotes(index, query) {
+    const lowered = query.toLowerCase();
+    const terms = [...new Set(lowered.split(/\s+/).filter(Boolean))];
+    if (terms.length === 0)
+        return [];
+    const prepared = [...index.values()].map(note => ({
+        note,
+        titleField: `${note.id} ${note.title}`.toLowerCase(),
+        backlinkField: note.backlinks.join(' ').toLowerCase(),
+        bodyField: note.body.toLowerCase(),
+        docLen: Math.max(1, note.body.length),
+    }));
+    const docCount = prepared.length;
+    const avgdl = prepared.reduce((sum, p) => sum + p.docLen, 0) / Math.max(1, docCount);
+    const idf = new Map();
+    for (const term of terms) {
+        const df = prepared.filter(p => p.titleField.includes(term) || p.backlinkField.includes(term) || p.bodyField.includes(term)).length;
+        idf.set(term, Math.log(1 + (docCount - df + 0.5) / (df + 0.5)));
+    }
+    const sumIdf = [...idf.values()].reduce((a, b) => a + b, 0);
+    const scores = new Map();
+    const phrase = lowered.trim();
+    for (const p of prepared) {
+        let score = 0;
+        for (const term of terms) {
+            const tf = TITLE_WEIGHT * countOccurrences(p.titleField, term) +
+                BACKLINK_WEIGHT * countOccurrences(p.backlinkField, term) +
+                BODY_WEIGHT * countOccurrences(p.bodyField, term);
+            if (tf === 0)
+                continue;
+            const termIdf = idf.get(term) ?? 0;
+            score += termIdf * (tf * (K1 + 1)) / (tf + K1 * (1 - B + (B * p.docLen) / avgdl));
+        }
+        if (terms.length > 1) {
+            if (p.titleField.includes(phrase))
+                score += sumIdf;
+            else if (p.bodyField.includes(phrase))
+                score += 0.5 * sumIdf;
+        }
+        if (score > 0)
+            scores.set(p.note.id, score);
+    }
+    // Graph boost: a note linked from a scored hit gains a fraction of that
+    // hit's score (the strongest link wins). `backlinks` lists the sources, so
+    // hit H links to T exactly when H.id ∈ T.backlinks.
+    const linkedBoost = new Map();
+    for (const p of prepared) {
+        for (const sourceId of p.note.backlinks) {
+            const sourceScore = scores.get(sourceId);
+            if (sourceScore !== undefined) {
+                linkedBoost.set(p.note.id, Math.max(linkedBoost.get(p.note.id) ?? 0, GRAPH_BOOST * sourceScore));
+            }
+        }
+    }
+    const hits = [];
+    for (const p of prepared) {
+        const score = (scores.get(p.note.id) ?? 0) + (linkedBoost.get(p.note.id) ?? 0);
+        if (score > 0)
+            hits.push(toHit(p.note, score));
+    }
+    hits.sort((a, b) => b.score - a.score || codeUnitCompare(a.id, b.id));
+    return hits;
+}
+/**
+ * Locale-independent code-unit ordering — `localeCompare` without a locale
+ * follows the host runtime locale, which makes tied-score ordering differ
+ * across machines.
+ */
+export function codeUnitCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Fuse the lexical ranking with a semantic-search ranking using reciprocal
+ * rank fusion (k = 60). Semantic-only notes are surfaced with their index
+ * metadata so the output shape stays uniform.
+ * @param lexical - hits from {@link rankNotes}.
+ * @param semanticIds - note ids ordered by descending semantic similarity.
+ * @param index - the note index for metadata lookup.
+ * @returns fused hits sorted by descending RRF score.
+ */
+export function fuseRankings(lexical, semanticIds, index) {
+    const fused = new Map();
+    const contribute = (id, rank) => {
+        const existing = fused.get(id);
+        if (existing !== undefined) {
+            existing.score += 1 / (RRF_K + rank + 1);
+            return;
+        }
+        const note = index.get(id);
+        if (note === undefined)
+            return; // never fabricate a hit for an id outside the vault index
+        fused.set(id, {
+            id,
+            title: note.title,
+            score: 1 / (RRF_K + rank + 1),
+            backlinks: note.backlinks,
+        });
+    };
+    lexical.forEach((hit, rank) => contribute(hit.id, rank));
+    semanticIds.forEach((id, rank) => contribute(id, rank));
+    const hits = [...fused.values()];
+    for (const hit of hits)
+        hit.score = Math.round(hit.score * 10000) / 10000;
+    hits.sort((a, b) => b.score - a.score || codeUnitCompare(a.id, b.id));
+    return hits;
+}
+//# sourceMappingURL=search.js.map

package/lib/types/index.d.ts

@@ -10,8 +10,15 @@
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type ToolRunContext } from '@deepseek-ai/dsh-tools';
+import { codeUnitCompare } from './search.ts';
 import type { IndexedNote, Note } from './types.ts';
 export type * from './types.ts';
+/**
+ * Locale-independent note-id ordering, re-exported so sibling packages that
+ * truncate or tie-break id lists sort by the same rule instead of a copy that
+ * can drift.
+ */
+export { codeUnitCompare };
 /**
  * Compute a vault-relative note id from an absolute path. The result always
  * uses POSIX separators so note ids are stable across Windows, macOS, and Linux.
@@ -73,7 +80,8 @@ export declare function containedPath(root: string, candidate: string): string;
 export declare function containedPathReal(root: string, candidate: string): Promise<string>;
 /**
  * Extract YAML frontmatter and body from Markdown text. Only the leading
- * `---\n...\n---\n` form is recognized.
+ * `---\n...\n---\n` form is recognized, optionally behind a UTF-8 BOM.
+ * Duplicate keys resolve last-one-wins rather than dropping the block.
  * @param text - raw file contents.
  * @returns frontmatter map and body.
  */
@@ -88,6 +96,13 @@ export declare function splitFrontmatter(text: string): {
  * @returns content hash stable across processes.
  */
 export declare function noteVersion(text: string): string;
+/**
+ * Normalize `created`/`updated` frontmatter timestamps to the vault's
+ * `+08:00` second-precision convention. Parseable values in any other form
+ * (`Z`, `+00:00`, millisecond precision) are rewritten; unparseable values
+ * pass through untouched so a non-date string is never corrupted.
+ */
+export declare function normalizeNoteTimestamps(frontmatter: Record<string, unknown>): void;
 /**
  * Find all Obsidian-style `[[link]]` references in note text. Aliases of the
  * form `[[link|alias]]` return the link target only.
@@ -102,14 +117,33 @@ export declare function extractLinks(text: string): string[];
  */
 export declare function dottedExtension(ext: string): string;
 /**
- * Resolve a link target to an existing note file inside the vault. The target
- * may omit the extension; extensions are tried in config order.
+ * A link resolver maps an Obsidian `[[target]]` to a vault-relative note id,
+ * or `undefined` when nothing matches.
+ */
+export type LinkResolver = (target: string) => string | undefined;
+/**
+ * Build a resolver over the known note ids, matching Obsidian semantics: an
+ * exact vault-relative path first, then a path-suffix match, then a bare
+ * basename match — each tier tolerates the target carrying or omitting the
+ * extension. Ambiguity within a tier resolves to the id with the fewest path
+ * segments, ties by code-unit order, so results are identical across hosts.
+ * @param ids - vault-relative note ids (e.g. `shared/notes/foo.md`).
+ * @returns resolver function for `[[...]]` targets.
+ */
+export declare function createLinkResolver(ids: string[]): LinkResolver;
+/**
+ * Resolve a link target to an existing note file inside the vault. When
+ * `resolve` is provided the target is first looked up in the note-id set with
+ * Obsidian semantics (exact path, then path suffix, then basename); otherwise
+ * the target is probed as a vault-relative path and extensions are tried in
+ * config order. Every result still passes the realpath containment check.
  * @param root - vault root.
  * @param extensions - note extensions.
  * @param target - link target from `[[...]]`.
+ * @param resolve - optional resolver built by {@link createLinkResolver}.
  * @returns the resolved absolute path, or `undefined` if no file exists.
  */
-export declare function resolveLinkTarget(root: string, extensions: string[], target: string): Promise<string | undefined>;
+export declare function resolveLinkTarget(root: string, extensions: string[], target: string, resolve?: LinkResolver): Promise<string | undefined>;
 /**
  * Recursively discover note files under the vault root. `.git`, `.obsidian`,
  * and `node_modules` are always excluded; other dot-directories are skipped
@@ -117,9 +151,11 @@ export declare function resolveLinkTarget(root: string, extensions: string[], ta
  * @param root - vault root.
  * @param extensions - note extensions.
  * @param indexHiddenDirs - descend into remaining dot-directories.
+ * @param onSkip - optional callback for entries skipped because they could not
+ *   be read; one unreadable directory must not fail the whole vault scan.
  * @returns absolute paths of every note file.
  */
-export declare function listNotePaths(root: string, extensions: string[], indexHiddenDirs?: boolean): Promise<string[]>;
+export declare function listNotePaths(root: string, extensions: string[], indexHiddenDirs?: boolean, onSkip?: (path: string, error: unknown) => void): Promise<string[]>;
 /** Wire view of one linked note, truncated to avoid deep recursion types. */
 export interface LinkedNote {
     id: string;
@@ -137,9 +173,11 @@ export interface LinkedNote {
  * @param maxLinkDepth - how many link hops to resolve.
  * @param absolutePath - absolute path of the note.
  * @param visited - set of already-visited absolute paths to prevent cycles.
+ * @param linkResolver - resolver over the vault's note ids; built once per
+ *   call tree so bare `[[filename]]` links resolve without rescanning.
  * @returns the parsed note with linked notes attached.
  */
-export declare function readNote(root: string, extensions: string[], maxLinkDepth: number, absolutePath: string, visited?: ReadonlySet<string>): Promise<Note & {
+export declare function readNote(root: string, extensions: string[], maxLinkDepth: number, absolutePath: string, visited?: ReadonlySet<string>, linkResolver?: LinkResolver): Promise<Note & {
     linkedNotes: LinkedNote[];
 }>;
 /**
@@ -149,9 +187,11 @@ export declare function readNote(root: string, extensions: string[], maxLinkDept
  * @param root - vault root.
  * @param extensions - note extensions.
  * @param indexHiddenDirs - descend into dot-directories besides the fixed exclusions.
+ * @param onSkip - optional callback for notes skipped because they could not
+ *   be read; one unreadable note must not fail search for the whole vault.
  * @returns a map from note id to search result.
  */
-export declare function buildIndex(root: string, extensions: string[], indexHiddenDirs?: boolean): Promise<Map<string, IndexedNote>>;
+export declare function buildIndex(root: string, extensions: string[], indexHiddenDirs?: boolean, onSkip?: (path: string, error: unknown) => void): Promise<Map<string, IndexedNote>>;
 /**
  * Register the `wiki_read`, `wiki_search`, and `wiki_write` tools on
  * `ctx.tools`.

package/lib/types/search.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Multi-layer lexical ranking for `wiki_search`: field-weighted BM25-style
+ * scoring over note id/title/backlinks/body, a verbatim-phrase bonus, and a
+ * link-graph boost for notes referenced by strong lexical hits. Substring
+ * matching (not tokenization) keeps CJK text working without a segmenter.
+ * @module @jacklika/dsh-tool-memory-filesystem/search
+ */
+import type { IndexedNote, SearchResult } from './types.ts';
+/** A search hit carrying its fused relevance score. */
+export interface RankedHit extends SearchResult {
+    /** Relevance score: BM25 sum (+phrase/graph bonuses), or an RRF score when semantic fusion ran. */
+    score: number;
+}
+/**
+ * Rank every note in `index` against `query`. Any note containing at least one
+ * query term (OR semantics) is a candidate; scores follow BM25 saturation with
+ * field weights (`id`/`title` ×3, backlinks ×1, body ×1), a phrase bonus for a
+ * verbatim multi-term match, and a graph boost for notes linked from a scored
+ * hit.
+ * @param index - note index built by {@link buildIndex}.
+ * @param query - raw query text.
+ * @returns hits sorted by descending score.
+ */
+export declare function rankNotes(index: Map<string, IndexedNote>, query: string): RankedHit[];
+/**
+ * Locale-independent code-unit ordering — `localeCompare` without a locale
+ * follows the host runtime locale, which makes tied-score ordering differ
+ * across machines.
+ */
+export declare function codeUnitCompare(a: string, b: string): number;
+/**
+ * Fuse the lexical ranking with a semantic-search ranking using reciprocal
+ * rank fusion (k = 60). Semantic-only notes are surfaced with their index
+ * metadata so the output shape stays uniform.
+ * @param lexical - hits from {@link rankNotes}.
+ * @param semanticIds - note ids ordered by descending semantic similarity.
+ * @param index - the note index for metadata lookup.
+ * @returns fused hits sorted by descending RRF score.
+ */
+export declare function fuseRankings(lexical: RankedHit[], semanticIds: string[], index: Map<string, IndexedNote>): RankedHit[];
+//# sourceMappingURL=search.d.ts.map

package/lib/types/types.d.ts

@@ -20,6 +20,17 @@ export interface Note {
      * note in between.
      */
     version: string;
+    /**
+     * File modification time rendered as a `+08:00` timestamp. Only set on the
+     * top-level note returned by `wiki_read`.
+     */
+    mtime?: string;
+    /**
+     * True when the file's `mtime` changed since this plugin last observed it —
+     * evidence that an external writer (e.g. Obsidian) touched the note. Only
+     * set on the top-level note returned by `wiki_read`.
+     */
+    modifiedExternally?: boolean;
 }
 /** Result of a search across the vault. */
 export interface SearchResult {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jacklika/dsh-tool-memory-filesystem",
   "description": "Model-facing wiki/memory tools over a local Markdown vault: read, search, and write notes with Obsidian-style links and YAML frontmatter.",
-  "version": "0.1.3-alpha.1",
+  "version": "0.1.3-alpha.11",
   "publishConfig": {
     "access": "public"
   },
@@ -32,11 +32,12 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.4",
-    "js-yaml": "^4.2.0"
+    "js-yaml": "^4.2.0",
+    "@jacklika/dsh-memory-time": "^0.1.0-alpha.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0",
-    "@deepseek-ai/dsh-util-values": ">=0.1.7-rc.1 <0.3.0"
+    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0",
+    "@deepseek-ai/dsh-util-values": ">=0.1.7-rc.1 <0.3.0-0 || >=0.2.0-rc.1 <0.3.0-0"
   }
 }