@jacklika/dsh-tool-memory-graph 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,96 @@
+---
+description: "Model-facing wiki_graph tool exposing the [[link]] graph of a Markdown vault."
+kind: "package-reference"
+---
+
+# @jacklika/dsh-tool-memory-graph
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-tool-memory-graph` gives agents read-only graph queries over the Markdown vault used by [`dsh-tool-memory-filesystem`](../tool-memory-filesystem/README.md). The model sees one tool, `wiki_graph`, which returns note nodes and directed edges derived from Obsidian-style `[[link]]` references — either the whole vault or the reachable subgraph around one note. The package reuses the filesystem plugin's vault resolution and parsing helpers, so path containment, frontmatter handling, and the `indexHiddenDirs` policy match without a second parser.
+
+## 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-graph'
+```
+
+It resolves the same vault root per call as `tool-memory-filesystem`: an explicit `vaultRoot` (relative paths anchor at the session workspace), otherwise `<session cwd>/.dsh/memory/`.
+
+### Configure the graph
+
+| 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. |
+| `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. |
+| `maxDepth` | `number` | `1` | Maximum BFS depth when a center id is given. |
+| `maxNodes` | `number` | `200` | Maximum nodes returned in one graph. |
+
+### Tools
+
+- `wiki_graph(id?, depth?)` — without `id`, return every note and directed edge in the vault. With `id`, return the reachable subgraph within `depth` hops; edges from boundary nodes are included when both endpoints are selected.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+The package is a single Cordis function plugin that registers `wiki_graph` on `ctx.tools`. Per call it resolves the vault root through the shared `resolveMemoryVaultRoot` helper, lists notes through the shared `listNotePaths` walker, and extracts `[[link]]` targets through `extractLinks`/`resolveLinkTarget`. A breadth-first walk selects the node set first; edges are then collected from every selected node so boundary-node outgoing edges are not dropped. Output is `{ nodes: [{ id, title, backlinks }], edges: [{ from, to }] }`.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated `wiki_graph` schema in the [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-memory-graph). The description states that the graph is read-only and derived from `[[link]]` references.
+
+##### Verbatim description for `wiki_graph`
+
+```markdown
+Return the Obsidian-style [[link]] graph of the wiki vault: note ids, titles, and directed edges. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth.
+```
+
+#### Token effect
+
+A whole-vault call returns every note and edge; large vaults can add many tokens. Center-id subgraph calls bound output by `depth`.
+
+#### 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 visualization** — the tool returns JSON nodes and edges; rendering (Obsidian graph view, Mermaid) is left to consumers.
+- **Backlinks reflect the whole vault** — node `backlinks` counts are computed over all notes, not just the selected subgraph.
+
+<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,96 @@
+---
+description: "面向模型的 wiki_graph 工具，输出 Markdown 仓库的 [[link]] 链接图。"
+kind: "package-reference"
+---
+
+# @jacklika/dsh-tool-memory-graph
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-tool-memory-graph` 让 agent 对 [`dsh-tool-memory-filesystem`](../tool-memory-filesystem/README.zh.md) 使用的 Markdown 仓库做只读图查询。模型可见一个工具 `wiki_graph`，返回由 Obsidian 风格 `[[link]]` 引用推导的笔记节点和有向边——可以是全仓库图，也可以是以某条笔记为中心的可达子图。该包复用 filesystem 插件的仓库根解析与解析辅助函数，路径约束、frontmatter 处理和 `indexHiddenDirs` 策略完全一致，不引入第二套解析器。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [实现说明](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用
+
+在 profile 或 patch 文件中挂载插件：
+
+```yaml
+- name: '@jacklika/dsh-tool-memory-graph'
+```
+
+仓库根与 `tool-memory-filesystem` 一致，每次调用时解析：显式 `vaultRoot`（相对路径锚定会话工作区），否则使用 `<session cwd>/.dsh/memory/`。
+
+### 配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `vaultRoot` | `string` | `''` → `<session cwd>/.dsh/memory/` | 仓库根。留空时使用按工作区隔离的记忆目录；相对路径相对于会话工作区解析。 |
+| `extensions` | `string[]` | `['.md']` | 视为笔记的文件扩展名。 |
+| `indexHiddenDirs` | `boolean` | `false` | 是否索引以 `.` 开头的目录（`.git` 与 `node_modules` 始终排除）。当 `vaultRoot` 指向工作区根时开启，以纳入 `.dsh/memory/`。 |
+| `maxDepth` | `number` | `1` | 指定中心笔记时 BFS 的最大深度。 |
+| `maxNodes` | `number` | `200` | 单次图查询返回的最大节点数。 |
+
+### 工具
+
+- `wiki_graph(id?, depth?)` —— 不传 `id` 时返回全仓库的节点与有向边；传 `id` 时返回 `depth` 跳内的可达子图，两个端点都被选中时边界节点的出边也会包含。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 实现说明
+
+本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。先用广度优先遍历确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。输出为 `{ nodes: [{ id, title, backlinks }], edges: [{ from, to }] }`。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema
+
+#### 模型可见内容
+
+模型在[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-memory-graph)中看到生成的 `wiki_graph` schema。描述声明该图是只读的，由 `[[link]]` 引用推导。
+
+##### `wiki_graph` 的原文描述
+
+```markdown
+Return the Obsidian-style [[link]] graph of the wiki vault: note ids, titles, and directed edges. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth.
+```
+
+#### Token 影响
+
+全仓库调用返回所有节点与边，大仓库可能产生较多 token。指定中心 id 的子图调用通过 `depth` 限制输出规模。
+
+#### KV Cache 影响
+
+独立。插件只提供工具结果，不改变请求头、system prompt 或工具列表。
+
+## 已知限制与待办
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **无可视化** —— 工具返回 JSON 节点与边；渲染（Obsidian 图谱、Mermaid）由消费方负责。
+- **backlinks 基于全仓库统计** —— 节点的 `backlinks` 计数覆盖全部笔记，而非仅选中子图。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 —— 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,157 @@
+/**
+ * Model-facing link-graph tool over a Markdown memory vault. The package
+ * registers `wiki_graph`, which returns the vault's note/link graph or the
+ * subgraph reachable from one note, so an agent can reason about how memory
+ * notes connect before reading them.
+ * @module @jacklika/dsh-tool-memory-graph
+ */
+import { readFile } from 'node:fs/promises';
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { containedPathReal, extractLinks, listNotePaths, resolveLinkTarget, resolveMemoryVaultRoot, splitFrontmatter, vaultRelativeId, } from '@jacklika/dsh-tool-memory-filesystem';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'tool-memory-graph';
+/** Services required by the wiki graph tool. */
+export const inject = ['tools'];
+/** Schemastery configuration for the memory graph tool consumer. */
+export const Config = z.object({
+    vaultRoot: z.string().default(''),
+    extensions: z.array(z.string()).default(['.md']),
+    maxDepth: z.number().default(1),
+    maxNodes: z.number().default(200),
+    indexHiddenDirs: z.boolean().default(false),
+});
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`tool-memory-graph: ${name} must be a positive integer`);
+    }
+}
+async function noteTitle(absolutePath, id) {
+    const text = await readFile(absolutePath, 'utf8');
+    const { body } = splitFrontmatter(text);
+    const heading = /^#\s+(.+)$/m.exec(body);
+    return heading?.[1]?.trim() ?? id.replace(/\.[^.]+$/, '');
+}
+/**
+ * Build the vault-wide link graph: every note is a node; every `[[link]]`
+ * that resolves to an existing note is an edge.
+ * @param root - vault root.
+ * @param resolved - applied plugin configuration.
+ * @returns the full graph, node-capped.
+ */
+async function buildGraph(root, resolved) {
+    const paths = await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs);
+    const entries = paths.map(path => [vaultRelativeId(root, path), path]);
+    const truncated = entries.length > resolved.maxNodes;
+    const capped = entries.slice(0, resolved.maxNodes);
+    const nodes = [];
+    for (const [id, path] of capped)
+        nodes.push({ id, title: await noteTitle(path, id) });
+    const idSet = new Set(capped.map(([id]) => id));
+    const edges = [];
+    for (const [id, path] of capped) {
+        const text = await readFile(path, 'utf8');
+        for (const link of extractLinks(text)) {
+            const targetPath = await resolveLinkTarget(root, resolved.extensions, link);
+            if (targetPath === undefined)
+                continue;
+            const targetId = vaultRelativeId(root, targetPath);
+            if (idSet.has(targetId))
+                edges.push({ from: id, to: targetId });
+        }
+    }
+    return { nodes, edges, truncated };
+}
+/**
+ * Collect the subgraph reachable from one note by following `[[link]]`
+ * references breadth-first up to `depth`.
+ * @param root - vault root.
+ * @param resolved - applied plugin configuration.
+ * @param startId - vault-relative id of the center note.
+ * @param depth - maximum link hops from the center.
+ * @returns the neighborhood graph, node-capped.
+ */
+async function buildSubgraph(root, resolved, startId, depth) {
+    const startPath = await containedPathReal(root, startId);
+    const visited = new Map([[vaultRelativeId(root, startPath), startPath]]);
+    let frontier = [startPath];
+    for (let level = 0; level < depth && frontier.length > 0; level += 1) {
+        const next = [];
+        for (const path of frontier) {
+            const text = await readFile(path, 'utf8');
+            for (const link of extractLinks(text)) {
+                const targetPath = await resolveLinkTarget(root, resolved.extensions, link);
+                if (targetPath === undefined)
+                    continue;
+                const toId = vaultRelativeId(root, targetPath);
+                if (!visited.has(toId)) {
+                    visited.set(toId, targetPath);
+                    next.push(targetPath);
+                }
+            }
+        }
+        frontier = next;
+    }
+    const truncated = visited.size > resolved.maxNodes;
+    const ids = [...visited.keys()].slice(0, resolved.maxNodes);
+    const idSet = new Set(ids);
+    const edges = [];
+    const nodes = [];
+    for (const id of ids) {
+        const path = await containedPathReal(root, id);
+        nodes.push({ id, title: await noteTitle(path, id) });
+        const text = await readFile(path, 'utf8');
+        for (const link of extractLinks(text)) {
+            const targetPath = await resolveLinkTarget(root, resolved.extensions, link);
+            if (targetPath === undefined)
+                continue;
+            const toId = vaultRelativeId(root, targetPath);
+            if (idSet.has(toId))
+                edges.push({ from: id, to: toId });
+        }
+    }
+    return { nodes, edges, truncated };
+}
+/**
+ * Register the `wiki_graph` tool 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-graph: ctx.tools.register unavailable; wiki_graph tool will not register.');
+        return;
+    }
+    const resolved = config;
+    assertPositiveInteger('maxDepth', resolved.maxDepth);
+    assertPositiveInteger('maxNodes', resolved.maxNodes);
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'wiki_graph',
+        description: 'Return the Obsidian-style [[link]] graph of the wiki vault: note ids, titles, and directed edges. Without an id it returns the whole vault graph (node-capped); with an id it returns the subgraph reachable from that note within the given depth.',
+        parameters: {
+            id: {
+                type: 'string',
+                description: 'Optional vault-relative note id to center the subgraph on (e.g. "concepts/RAG.md").',
+            },
+            depth: {
+                type: 'integer',
+                description: 'Maximum [[link]] hops from the center note; defaults to the configured maxDepth.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+            const vaultRoot = resolveMemoryVaultRoot(resolved.vaultRoot, exec);
+            const depth = args.depth ?? resolved.maxDepth;
+            assertPositiveInteger('depth', depth);
+            const graph = args.id === undefined
+                ? await buildGraph(vaultRoot, resolved)
+                : await buildSubgraph(vaultRoot, resolved, args.id, depth);
+            return graph;
+        },
+    })));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Model-facing link-graph tool over a Markdown memory vault. The package
+ * registers `wiki_graph`, which returns the vault's note/link graph or the
+ * subgraph reachable from one note, so an agent can reason about how memory
+ * notes connect before reading them.
+ * @module @jacklika/dsh-tool-memory-graph
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "tool-memory-graph";
+/** Services required by the wiki graph tool. */
+export declare const inject: string[];
+/** Plugin configuration, mirroring the filesystem memory vault settings. */
+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[];
+    /** Default traversal depth when the call omits `depth`. */
+    maxDepth?: number;
+    /** Maximum nodes returned in one graph. */
+    maxNodes?: number;
+    /** Descend into dot-directories besides the fixed exclusions while indexing. */
+    indexHiddenDirs?: boolean;
+}
+/** Schemastery configuration for the memory graph tool consumer. */
+export declare const Config: z<Config>;
+/**
+ * Register the `wiki_graph` tool 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/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jacklika/dsh-tool-memory-graph",
+  "description": "Model-facing link-graph tool over a Markdown memory vault: returns note nodes and [[link]] edges, or the subgraph reachable from one note.",
+  "version": "0.1.0-alpha.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JackLiKa/jacklika-agent-plugins-repo.git",
+    "directory": "packages/tool-memory-graph"
+  },
+  "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",
+    "@jacklika/dsh-tool-memory-filesystem": "0.1.3-alpha.1"
+  },
+  "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"
+  }
+}