@jacklika/dsh-tool-memory-filesystem 0.1.3-alpha.4 → 0.1.3-alpha.5

package/README.md

@@ -53,7 +53,7 @@ A relative `vaultRoot` resolves against the calling session's workspace.
 ### 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_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. Results include the score and 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.
 
 ### Security
@@ -65,7 +65,7 @@ All paths are resolved under the vault root for that call; a path that escapes t
 <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. YAML frontmatter is parsed with `js-yaml`; `[[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. `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.
 
 -----
 
@@ -76,7 +76,7 @@ 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`
 
@@ -87,7 +87,7 @@ Read one Markdown note from the wiki vault, optionally following Obsidian-style
 ##### 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 matching note ids, titles, scores, and backlink counts. Use this before asking the user which note to read.
 ```
 
 ##### Verbatim description for `wiki_write`

package/README.zh.md

@@ -53,7 +53,7 @@ kind: "package-reference"
 ### 工具
 
 - `wiki_read(id)` — 按仓库相对路径读取笔记，返回 frontmatter、正文、链接、已解析的链接笔记，以及内容指纹 `version`。
-- `wiki_search(query)` — 按标题、id、正文关键词搜索；结果包含反向链接数量。
+- `wiki_search(query)` — 按标题、id、正文关键词搜索；查询词采用 OR 匹配，并按字段加权的 BM25 式评分排序（标题/id 命中权重最高，稀有词权重更高），另有整段短语加分与被强命中笔记链接的图增强；挂载 `wiki_semantic_search` 时两路排序经 RRF 融合。结果包含分数与反向链接数量。
 - `wiki_write(id, content, mode?, baseVersion?)` — 创建或追加笔记。追加模式保留 frontmatter 并添加时间戳标题。把 `wiki_read` 返回的 `version` 作为 `baseVersion` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。
 
 ### 安全
@@ -65,7 +65,7 @@ kind: "package-reference"
 <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` + 前缀检查保持在解析出的根目录内。YAML frontmatter 使用 `js-yaml` 解析；`[[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` 覆盖目标，因此并发读者永远不会读到写了一半的笔记。
 
 -----
 
@@ -76,7 +76,7 @@ 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` 的完整描述
 
@@ -87,7 +87,7 @@ Read one Markdown note from the wiki vault, optionally following Obsidian-style
 ##### `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 matching note ids, titles, scores, and backlink counts. Use this before asking the user which note to read.
 ```
 
 ##### `wiki_write` 的完整描述

package/lib/index.js

@@ -14,6 +14,7 @@ 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";
 /**
  * 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.
@@ -111,12 +112,16 @@ export function splitFrontmatter(text) {
     const bodyText = match[2] ?? '';
     try {
         const parsed = yaml.load(frontmatterText);
-        return {
-            frontmatter: parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
-                ? parsed
-                : {},
-            body: bodyText,
-        };
+        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 };
@@ -141,12 +146,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.
@@ -156,14 +215,79 @@ 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) {
@@ -227,9 +351,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,
@@ -249,9 +375,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);
             }
         }
@@ -298,12 +424,10 @@ export async function buildIndex(root, extensions, indexHiddenDirs = false) {
             : 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)) {
@@ -371,13 +495,15 @@ 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);
+            const linkResolver = createLinkResolver((await listNotePaths(vaultRoot, resolved.extensions, resolved.indexHiddenDirs))
+                .map(path => vaultRelativeId(vaultRoot, path)));
+            const note = await readNote(vaultRoot, resolved.extensions, resolved.maxLinkDepth, absolutePath, new Set(), linkResolver);
             return note;
         },
     })));
     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 matching note ids, titles, scores, and backlink counts. Use this before asking the user which note to read.',
         parameters: {
             query: {
                 type: 'string',
@@ -394,6 +520,7 @@ export function apply(ctx, config) {
                     properties: {
                         id: { type: 'string' },
                         title: { type: 'string' },
+                        score: { type: 'number' },
                         backlinks: { type: 'array', items: { type: 'string' } },
                     },
                 },
@@ -403,15 +530,41 @@ export function apply(ctx, config) {
         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 });
+            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);
         },
     })));

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

@@ -102,14 +102,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
@@ -137,9 +156,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[];
 }>;
 /**

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/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.4",
+  "version": "0.1.3-alpha.5",
   "publishConfig": {
     "access": "public"
   },