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

package/README.md

@@ -0,0 +1,124 @@
+---
+description: "Model-facing wiki/memory tools over a local Markdown vault with Obsidian-style links and YAML frontmatter."
+kind: "package-reference"
+---
+
+# @jacklika/dsh-tool-memory-filesystem
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-tool-memory-filesystem` gives agents read, search, and append access to a local Markdown vault. Notes are ordinary `.md` files with optional YAML frontmatter and Obsidian-style `[[link]]` references. A deployment mounts this package as a Cordis plugin; by default each session reads and writes notes under its own workspace at `<session cwd>/.dsh/memory/`, so every project keeps a private memory store. An explicit `vaultRoot` can pin one shared vault instead. The model sees `wiki_read`, `wiki_search`, and `wiki_write` tools. No vector database is required — the MVP uses filename and keyword search, with link following for contextual completeness.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the plugin in a profile or patch file:
+
+```yaml
+- name: '@jacklika/dsh-tool-memory-filesystem'
+```
+
+Each session then uses `<session cwd>/.dsh/memory/` as its vault. To share one vault across sessions, set an explicit root:
+
+```yaml
+- name: '@jacklika/dsh-tool-memory-filesystem'
+  config:
+    vaultRoot: /path/to/obsidian-vault
+```
+
+A relative `vaultRoot` resolves against the calling session's workspace.
+
+### Configure the vault
+
+| 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. |
+| `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.
+
+### 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.
+
+-----
+
+<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.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema
+
+#### 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.
+
+##### 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.
+```
+
+##### 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.
+```
+
+##### 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.
+```
+
+#### 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.
+
+#### KV Cache effect
+
+Independent. The plugin only supplies tool results; it does not change the request header, system prompt, or tool list.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **No sandbox policy integration** — the plugin reads files directly, so it bypasses the `ctx.fs` sandbox and approval gates. A future provider could delegate reads to `ctx.fs` to inherit policy.
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,124 @@
+---
+description: "基于本地 Markdown 仓库的面向模型的 wiki/记忆工具，支持 Obsidian 风格双向链接和 YAML frontmatter。"
+kind: "package-reference"
+---
+
+# @jacklika/dsh-tool-memory-filesystem
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-tool-memory-filesystem` 让 agent 可以读取、搜索和追加本地 Markdown 仓库中的笔记。笔记是普通的 `.md` 文件，可包含 YAML frontmatter 和 Obsidian 风格 `[[link]]` 链接。部署时以 Cordis 插件形式挂载即可；默认情况下每个会话使用自己工作区下的 `<session cwd>/.dsh/memory/` 作为仓库，因此每个项目拥有独立的记忆库。需要共享仓库时可显式配置 `vaultRoot`。模型会看到 `wiki_read`、`wiki_search` 和 `wiki_write` 三个工具。MVP 不需要向量数据库，只使用文件名和关键词搜索，并通过链接跟随保证上下文完整。
+
+## 目录
+
+- [使用](#use-this-package)
+- [实现说明](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与待办](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用
+
+在 profile 或 patch 文件中挂载插件：
+
+```yaml
+- name: '@jacklika/dsh-tool-memory-filesystem'
+```
+
+此后每个会话使用 `<session cwd>/.dsh/memory/` 作为自己的仓库。需要跨会话共享一个仓库时，显式指定根目录：
+
+```yaml
+- name: '@jacklika/dsh-tool-memory-filesystem'
+  config:
+    vaultRoot: /path/to/obsidian-vault
+```
+
+相对路径的 `vaultRoot` 会相对于调用会话的工作区解析。
+
+### 配置仓库
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `vaultRoot` | `string` | `''` → `<session cwd>/.dsh/memory/` | 仓库根目录。留空表示使用按工作区隔离的记忆目录；相对路径相对于会话工作区解析。 |
+| `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` 传入时，若笔记在读取后被其他写入方改动，写入会显式失败。
+
+### 安全
+
+所有路径都必须在该次调用解析出的仓库根目录下；越界路径会被拒绝。该插件不通过 `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` 覆盖目标，因此并发读者永远不会读到写了一半的笔记。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### Tool schema
+
+#### 模型看到的内容
+
+模型看到的是生成的 [`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` 的完整描述
+
+```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.
+```
+
+##### `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.
+```
+
+##### `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.
+```
+
+#### Token 影响
+
+`wiki_read` 返回请求笔记的完整正文，以及 `maxLinkDepth` 范围内所有可达链接笔记的正文。长笔记或密集链接图可能显著增加下次请求的 token 数。`wiki_search` 只返回有限的结果元数据。
+
+#### KV Cache 影响
+
+独立。该插件仅提供工具结果，不改变请求头、系统提示或工具列表。
+
+## 已知限制与待办
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **未接入沙箱策略** — 插件直接读取文件，绕过 `ctx.fs` 沙箱与审批机制。未来可以提供委托给 `ctx.fs` 的 provider 以继承策略。
+- **无向量搜索** — 仅支持关键词搜索。未来可新增 `tool-memory-vector` 包提供基于 embedding 的检索，而无需修改本包。
+- **不支持图片或二进制附件** — 笔记按 UTF-8 文本处理。附件应继续使用 attachment 体系。
+- **无内置写协调** —— 写入是原子的（临时文件 + `rename`），读者不会看到半写文件，但对同一笔记的并发 `wiki_write` 仍可能丢更新。协作调用方可传 `baseVersion` 把丢更新变成显式冲突；挂载 `@jacklika/dsh-memory-queue` 可获得进程内串行化，并可选用心跳刷新的跨进程锁。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,484 @@
+/**
+ * Model-facing wiki/memory tools over a local Markdown vault. The package
+ * provides `wiki_read`, `wiki_search`, and `wiki_write` so an agent can treat a
+ * directory of Markdown notes as long-term memory. Notes are plain files with
+ * YAML frontmatter and Obsidian-style `[[link]]` references; the agent reads,
+ * searches, and appends notes through the tool registry without touching core
+ * packages.
+ * @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 { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import yaml from 'js-yaml';
+/**
+ * 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.
+ */
+export function vaultRelativeId(root, absolutePath) {
+    return relative(root, absolutePath).replace(/\\/g, '/');
+}
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'tool-memory-filesystem';
+/** Services required by the wiki/memory tool suite. */
+export const inject = ['tools'];
+/** Schemastery configuration for the filesystem memory tool consumer. */
+export const Config = z.object({
+    vaultRoot: z.string().default(''),
+    extensions: z.array(z.string()).default(['.md']),
+    maxLinkDepth: z.number().default(1),
+    maxSearchResults: z.number().default(20),
+    indexHiddenDirs: z.boolean().default(false),
+});
+/**
+ * Compute the vault root for one tool call: an explicit `vaultRoot` wins,
+ * resolved relative to the session workspace; otherwise the call gets
+ * `<session cwd>/.dsh/memory/` so each workspace owns its notes.
+ * @param vaultRoot - the configured root (`''` selects the per-workspace default).
+ * @param exec - the current tool execution carrying the agent session.
+ * @returns absolute vault root for this call.
+ */
+export function resolveMemoryVaultRoot(vaultRoot, exec) {
+    const sessionCwd = exec.agent?.session.header.cwd ?? process.cwd();
+    if (vaultRoot === undefined || vaultRoot === '') {
+        return join(sessionCwd, '.dsh', 'memory');
+    }
+    return isAbsolute(vaultRoot) ? vaultRoot : resolve(sessionCwd, vaultRoot);
+}
+/**
+ * Reject paths that escape the vault root. The check resolves the candidate,
+ * normalizes `..`, and requires the result to start with the root path followed
+ * by a path separator (or equal the root itself).
+ * @param root - absolute vault root.
+ * @param candidate - a relative or absolute path.
+ * @returns the absolute, contained path.
+ */
+export function containedPath(root, candidate) {
+    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}`);
+    }
+    return absolute;
+}
+/**
+ * Resolve a vault path and reject an existing symlink or junction component
+ * whose real target leaves the vault. The nearest existing ancestor protects
+ * paths whose final file or directories do not exist yet.
+ * @param root - vault root; it must exist.
+ * @param candidate - vault-relative path.
+ * @returns the absolute lexical path after realpath containment succeeds.
+ */
+export async function containedPathReal(root, candidate) {
+    const absolute = containedPath(root, candidate);
+    const canonicalRoot = await realpath(resolve(root));
+    let ancestor = absolute;
+    for (;;) {
+        try {
+            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}`);
+            }
+            return absolute;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const parent = dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            ancestor = parent;
+        }
+    }
+}
+/**
+ * Extract YAML frontmatter and body from Markdown text. Only the leading
+ * `---\n...\n---\n` form is recognized.
+ * @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);
+    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,
+        };
+    }
+    catch {
+        return { frontmatter: {}, body: text };
+    }
+}
+/**
+ * Fingerprint one note's raw file contents. The value lets `wiki_write`
+ * detect that another writer changed the note since it was read.
+ * @param text - raw file contents.
+ * @returns content hash stable across processes.
+ */
+export function noteVersion(text) {
+    return createHash('sha1').update(text, 'utf8').digest('hex');
+}
+/**
+ * Find all Obsidian-style `[[link]]` references in note text. Aliases of the
+ * form `[[link|alias]]` return the link target only.
+ * @param text - note body.
+ * @returns array of link targets.
+ */
+export function extractLinks(text) {
+    const links = [];
+    const pattern = /\[\[([^|\]\r\n]+)(?:\|[^\]]*)?\]\]/g;
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+        if (match[1] !== undefined)
+            links.push(match[1].trim());
+    }
+    return [...new Set(links)];
+}
+/**
+ * Normalize a configured file extension to a dot-prefixed form.
+ * @param ext - extension string.
+ * @returns `.md` form.
+ */
+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.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @param target - link target from `[[...]]`.
+ * @returns the resolved absolute path, or `undefined` if no file exists.
+ */
+export async function resolveLinkTarget(root, extensions, target) {
+    const candidates = extensions.map(ext => `${target}${dottedExtension(ext)}`);
+    candidates.push(target);
+    for (const candidate of candidates) {
+        try {
+            const path = await containedPathReal(root, candidate);
+            const info = await stat(path);
+            if (info.isFile())
+                return path;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return undefined;
+}
+/**
+ * Recursively discover note files under the vault root. `.git`, `.obsidian`,
+ * and `node_modules` are always excluded; other dot-directories are skipped
+ * unless `indexHiddenDirs` is enabled.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @param indexHiddenDirs - descend into remaining dot-directories.
+ * @returns absolute paths of every note file.
+ */
+export async function listNotePaths(root, extensions, indexHiddenDirs = false) {
+    const results = [];
+    const exclude = new Set(['.git', 'node_modules', '.obsidian']);
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!indexHiddenDirs && entry.name.startsWith('.') && entry.name !== '.')
+                continue;
+            if (exclude.has(entry.name))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && extensions.some(ext => entry.name.endsWith(dottedExtension(ext)))) {
+                results.push(full);
+            }
+        }
+    }
+    await walk(root);
+    return results;
+}
+/**
+ * Read and parse one Markdown note, following configured link depth.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @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.
+ * @returns the parsed note with linked notes attached.
+ */
+export async function readNote(root, extensions, maxLinkDepth, absolutePath, visited = new Set()) {
+    if (visited.has(absolutePath)) {
+        return {
+            path: absolutePath,
+            id: vaultRelativeId(root, absolutePath),
+            frontmatter: {},
+            body: '',
+            links: [],
+            version: '',
+            linkedNotes: [],
+        };
+    }
+    const nextVisited = new Set(visited);
+    nextVisited.add(absolutePath);
+    const text = await readFile(absolutePath, 'utf8');
+    const { frontmatter, body } = splitFrontmatter(text);
+    const links = extractLinks(text);
+    const linkedNotes = [];
+    if (maxLinkDepth > 0) {
+        for (const link of links) {
+            const target = await resolveLinkTarget(root, extensions, link);
+            if (target !== undefined) {
+                const child = await readNote(root, extensions, maxLinkDepth - 1, target, nextVisited);
+                linkedNotes.push(child);
+            }
+        }
+    }
+    return {
+        path: absolutePath,
+        id: vaultRelativeId(root, absolutePath),
+        frontmatter,
+        body,
+        links,
+        version: noteVersion(text),
+        linkedNotes,
+    };
+}
+/**
+ * Build a search index of note titles, bodies, and backlinks. The title is the
+ * first Markdown `# heading` or the basename without extension; the body keeps
+ * keyword search honest about the documented "titles and bodies" contract.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @param indexHiddenDirs - descend into dot-directories besides the fixed exclusions.
+ * @returns a map from note id to search result.
+ */
+export async function buildIndex(root, extensions, indexHiddenDirs = false) {
+    const paths = await listNotePaths(root, extensions, indexHiddenDirs);
+    const notes = [];
+    for (const path of paths) {
+        const text = await readFile(path, 'utf8');
+        const { frontmatter, body } = splitFrontmatter(text);
+        notes.push({
+            path,
+            id: vaultRelativeId(root, path),
+            frontmatter,
+            body,
+            links: extractLinks(text),
+            version: noteVersion(text),
+        });
+    }
+    const index = new Map();
+    for (const note of notes) {
+        const headingMatch = /^#\s+(.+)$/m.exec(note.body);
+        const title = headingMatch !== null && headingMatch[1] !== undefined
+            ? headingMatch[1].trim()
+            : note.id.replace(/\.[^.]+$/, '');
+        index.set(note.id, { id: note.id, title, backlinks: [], body: note.body });
+    }
+    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;
+            });
+            if (targetId !== undefined) {
+                const entry = index.get(targetId);
+                if (entry !== undefined && !entry.backlinks.includes(note.id)) {
+                    entry.backlinks.push(note.id);
+                }
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Write `contents` to `absolutePath` atomically: stage into a sibling temp
+ * file, then `rename` over the target so concurrent readers never observe a
+ * partially written note.
+ * @param absolutePath - final note path inside the vault.
+ * @param contents - complete file body to publish.
+ */
+async function writeAtomic(absolutePath, contents) {
+    const tmpPath = `${absolutePath}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        await writeFile(tmpPath, contents, 'utf8');
+        await rename(tmpPath, absolutePath);
+    }
+    catch (error) {
+        await rm(tmpPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** Validate a positive-integer config bound. */
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`tool-memory-filesystem: ${name} must be a positive integer`);
+    }
+}
+/**
+ * Register the `wiki_read`, `wiki_search`, and `wiki_write` tools on
+ * `ctx.tools`.
+ * @param ctx - registrant context carrying the tool registry.
+ * @param config - deployment's explicit vault configuration.
+ */
+export function apply(ctx, config) {
+    const tools = ctx.get('tools');
+    if (typeof tools?.register !== 'function') {
+        ctx.logger?.warn('tool-memory-filesystem: ctx.tools.register unavailable; wiki tools will not register.');
+        return;
+    }
+    const resolved = config;
+    assertPositiveInteger('maxLinkDepth', resolved.maxLinkDepth);
+    assertPositiveInteger('maxSearchResults', resolved.maxSearchResults);
+    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.',
+        parameters: {
+            id: {
+                type: 'string',
+                required: true,
+                description: 'Vault-relative path of the note to read (e.g. "concepts/RAG.md" or "daily/2026-09-23").',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        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;
+        },
+    })));
+    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.',
+        parameters: {
+            query: {
+                type: 'string',
+                required: true,
+                description: 'Keyword or phrase to match against note titles and bodies.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        id: { type: 'string' },
+                        title: { type: 'string' },
+                        backlinks: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+            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 });
+                }
+            }
+            hits.sort((a, b) => b.backlinks.length - a.backlinks.length);
+            return hits.slice(0, resolved.maxSearchResults);
+        },
+    })));
+    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.',
+        parameters: {
+            id: {
+                type: 'string',
+                required: true,
+                description: 'Vault-relative path of the note (e.g. "meetings/2026-09-23.md").',
+            },
+            content: {
+                type: 'string',
+                required: true,
+                description: 'Markdown content to write or append.',
+            },
+            mode: {
+                type: 'string',
+                description: 'Either "append" (default) or "overwrite".',
+                enum: ['append', 'overwrite'],
+            },
+            baseVersion: {
+                type: 'string',
+                description: 'Optional version returned by wiki_read. When provided, the write fails if the note changed since that read.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string' },
+                    mode: { type: 'string' },
+                    bytes: { type: 'integer' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+            const vaultRoot = vaultRootFor(exec);
+            const mode = args.mode ?? 'append';
+            await mkdir(vaultRoot, { recursive: true });
+            const absolutePath = await containedPathReal(vaultRoot, args.id);
+            const hasExtension = resolved.extensions.some(ext => args.id.endsWith(dottedExtension(ext)));
+            if (!hasExtension) {
+                throw new Error(`tool-memory-filesystem: note id must end with one of ${resolved.extensions.join(', ')}`);
+            }
+            await mkdir(dirname(absolutePath), { recursive: true });
+            await containedPathReal(vaultRoot, args.id);
+            exec.signal.throwIfAborted();
+            let existing;
+            try {
+                existing = await readFile(absolutePath, 'utf8');
+            }
+            catch {
+                // file does not exist yet
+            }
+            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;
+            if (mode === 'overwrite') {
+                finalBody = args.content;
+            }
+            else {
+                const { frontmatter, body } = splitFrontmatter(existing ?? '');
+                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`;
+            }
+            exec.signal.throwIfAborted();
+            await writeAtomic(absolutePath, finalBody);
+            return { id: vaultRelativeId(vaultRoot, absolutePath), mode, bytes: Buffer.byteLength(finalBody, 'utf8') };
+        },
+    })));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Model-facing wiki/memory tools over a local Markdown vault. The package
+ * provides `wiki_read`, `wiki_search`, and `wiki_write` so an agent can treat a
+ * directory of Markdown notes as long-term memory. Notes are plain files with
+ * YAML frontmatter and Obsidian-style `[[link]]` references; the agent reads,
+ * searches, and appends notes through the tool registry without touching core
+ * packages.
+ * @module @jacklika/dsh-tool-memory-filesystem
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { IndexedNote, Note } from './types.ts';
+export type * from './types.ts';
+/**
+ * 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.
+ */
+export declare function vaultRelativeId(root: string, absolutePath: string): string;
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "tool-memory-filesystem";
+/** Services required by the wiki/memory tool suite. */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * Explicit vault root. When omitted, each tool call resolves the memory
+     * directory under the calling session's workspace (`<cwd>/.dsh/memory/`).
+     * A relative path is resolved against the session workspace.
+     */
+    vaultRoot?: string;
+    /** File extensions to treat as notes. */
+    extensions?: string[];
+    /** Maximum depth to follow `[[link]]` references when reading a note. */
+    maxLinkDepth?: number;
+    /** Maximum number of search hits to return. */
+    maxSearchResults?: number;
+    /**
+     * Descend into dot-directories while indexing. `.git`, `.obsidian`, and
+     * `node_modules` are always excluded. Enable this when `vaultRoot` points at
+     * a directory whose notes live under a hidden path such as `.dsh/memory/`.
+     */
+    indexHiddenDirs?: boolean;
+}
+/** Schemastery configuration for the filesystem memory tool consumer. */
+export declare const Config: z<Config>;
+/**
+ * Compute the vault root for one tool call: an explicit `vaultRoot` wins,
+ * resolved relative to the session workspace; otherwise the call gets
+ * `<session cwd>/.dsh/memory/` so each workspace owns its notes.
+ * @param vaultRoot - the configured root (`''` selects the per-workspace default).
+ * @param exec - the current tool execution carrying the agent session.
+ * @returns absolute vault root for this call.
+ */
+export declare function resolveMemoryVaultRoot(vaultRoot: string | undefined, exec: Pick<ToolRunContext, 'agent'>): string;
+/**
+ * Reject paths that escape the vault root. The check resolves the candidate,
+ * normalizes `..`, and requires the result to start with the root path followed
+ * by a path separator (or equal the root itself).
+ * @param root - absolute vault root.
+ * @param candidate - a relative or absolute path.
+ * @returns the absolute, contained path.
+ */
+export declare function containedPath(root: string, candidate: string): string;
+/**
+ * Resolve a vault path and reject an existing symlink or junction component
+ * whose real target leaves the vault. The nearest existing ancestor protects
+ * paths whose final file or directories do not exist yet.
+ * @param root - vault root; it must exist.
+ * @param candidate - vault-relative path.
+ * @returns the absolute lexical path after realpath containment succeeds.
+ */
+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.
+ * @param text - raw file contents.
+ * @returns frontmatter map and body.
+ */
+export declare function splitFrontmatter(text: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/**
+ * Fingerprint one note's raw file contents. The value lets `wiki_write`
+ * detect that another writer changed the note since it was read.
+ * @param text - raw file contents.
+ * @returns content hash stable across processes.
+ */
+export declare function noteVersion(text: string): string;
+/**
+ * Find all Obsidian-style `[[link]]` references in note text. Aliases of the
+ * form `[[link|alias]]` return the link target only.
+ * @param text - note body.
+ * @returns array of link targets.
+ */
+export declare function extractLinks(text: string): string[];
+/**
+ * Normalize a configured file extension to a dot-prefixed form.
+ * @param ext - extension string.
+ * @returns `.md` form.
+ */
+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.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @param target - link target from `[[...]]`.
+ * @returns the resolved absolute path, or `undefined` if no file exists.
+ */
+export declare function resolveLinkTarget(root: string, extensions: string[], target: string): Promise<string | undefined>;
+/**
+ * Recursively discover note files under the vault root. `.git`, `.obsidian`,
+ * and `node_modules` are always excluded; other dot-directories are skipped
+ * unless `indexHiddenDirs` is enabled.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @param indexHiddenDirs - descend into remaining dot-directories.
+ * @returns absolute paths of every note file.
+ */
+export declare function listNotePaths(root: string, extensions: string[], indexHiddenDirs?: boolean): Promise<string[]>;
+/** Wire view of one linked note, truncated to avoid deep recursion types. */
+export interface LinkedNote {
+    id: string;
+    path: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+    links: string[];
+    version: string;
+    linkedNotes: LinkedNote[];
+}
+/**
+ * Read and parse one Markdown note, following configured link depth.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @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.
+ * @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 & {
+    linkedNotes: LinkedNote[];
+}>;
+/**
+ * Build a search index of note titles, bodies, and backlinks. The title is the
+ * first Markdown `# heading` or the basename without extension; the body keeps
+ * keyword search honest about the documented "titles and bodies" contract.
+ * @param root - vault root.
+ * @param extensions - note extensions.
+ * @param indexHiddenDirs - descend into dot-directories besides the fixed exclusions.
+ * @returns a map from note id to search result.
+ */
+export declare function buildIndex(root: string, extensions: string[], indexHiddenDirs?: boolean): Promise<Map<string, IndexedNote>>;
+/**
+ * Register the `wiki_read`, `wiki_search`, and `wiki_write` tools on
+ * `ctx.tools`.
+ * @param ctx - registrant context carrying the tool registry.
+ * @param config - deployment's explicit vault configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared types for filesystem-backed wiki/memory notes.
+ * @module @jacklika/dsh-tool-memory-filesystem/types
+ */
+/** Parsed frontmatter and body of one Markdown note. */
+export interface Note {
+    /** Absolute path to the source file. */
+    path: string;
+    /** Relative path inside the vault, used as a stable note id. */
+    id: string;
+    /** YAML frontmatter key/value map. */
+    frontmatter: Record<string, unknown>;
+    /** Note body after frontmatter. */
+    body: string;
+    /** Obsidian-style `[[target]]` links found in the body. */
+    links: string[];
+    /**
+     * Content fingerprint of the raw file at read time. Pass it back as
+     * `baseVersion` in `wiki_write` to fail when another writer changed the
+     * note in between.
+     */
+    version: string;
+}
+/** Result of a search across the vault. */
+export interface SearchResult {
+    /** Note id (relative path). */
+    id: string;
+    /** Note title: first heading, or the basename without extension. */
+    title: string;
+    /** Paths of notes that link to this note. */
+    backlinks: string[];
+}
+/**
+ * In-memory index entry: the public hit plus the note body kept as keyword
+ * haystack. `wiki_search` matches against the body but never emits it, so the
+ * tool output stays a bounded metadata list.
+ */
+export interface IndexedNote extends SearchResult {
+    /** Note body text used for keyword matching only. */
+    body: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared types for filesystem-backed wiki/memory notes.
+ * @module @jacklika/dsh-tool-memory-filesystem/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "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",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JackLiKa/jacklika-agent-plugins-repo.git",
+    "directory": "packages/tool-memory-filesystem"
+  },
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "README.md",
+    "README.zh.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.4",
+    "js-yaml": "^4.2.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"
+  }
+}