@jacklika/dsh-tool-memory-graph 0.1.0-alpha.5 → 0.1.0-alpha.7

package/README.md

@@ -9,7 +9,7 @@ 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.
+`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 two sources: explicit Obsidian-style `[[link]]` references, and keyword co-occurrence between notes (frontmatter tags/title and body terms). It can therefore expose an implicit association such as "B and C both mention `word1`", and that association automatically disappears when one note is rewritten and the shared term is no longer present — or is replaced by a new shared term such as `word2`. 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
 
@@ -41,17 +41,18 @@ It resolves the same vault root per call as `tool-memory-filesystem`: an explici
 | `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. |
+| `maxEdges` | `number` | `1000` | Maximum edges 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.
+- `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. Edges carry `type` (`link` or `keyword`), `keywords` (for `keyword` edges), and `weight` (combined term frequency). Output is `{ nodes, edges, truncated, edgesTruncated }`: `truncated` reports the `maxNodes` cut and `edgesTruncated` the `maxEdges` cut, kept separate so a complete node set is not misread as a complete graph.
 
 -----
 
 <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`. Targets resolve with the same Obsidian-style tiers as `wiki_read` — exact vault-relative path, then path suffix, then basename anywhere in the vault, with deterministic ambiguity handling. 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. When the node set exceeds `maxNodes`, a whole-vault graph keeps the lowest ids in code-unit order (the ordering `tool-memory-filesystem` tie-breaks with) and a subgraph keeps the notes nearest the center — BFS level first, then id — so which notes survive the cap never depends on directory-listing order and a subgraph never drops its own center. Output is `{ nodes: [{ id, title }], edges: [{ from, to }], truncated: boolean }`.
+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`. Targets resolve with the same Obsidian-style tiers as `wiki_read` — exact vault-relative path, then path suffix, then basename anywhere in the vault, with deterministic ambiguity handling. In addition to explicit links, the tool extracts significant terms from each note (frontmatter `tags` ×3, frontmatter `title` ×2, body terms ×1) and creates `keyword` edges between any two notes that share one or more terms. A breadth-first walk with a visited set (so cyclical link graphs terminate) follows both `link` and `keyword` edges to select the node set first; edges are then collected from every selected node so boundary-node outgoing edges are not dropped. When the node set exceeds `maxNodes`, a whole-vault graph keeps the lowest ids in code-unit order (the ordering `tool-memory-filesystem` tie-breaks with) and a subgraph keeps the notes nearest the center — BFS level first, then id — so which notes survive the cap never depends on directory-listing order and a subgraph never drops its own center. Because `wiki_graph` recomputes from disk on every call, rewriting a note removes stale `keyword` edges and creates new ones for the terms that survive or appear in the new text. Edges are capped at `maxEdges` after node selection: explicit `link` edges first, then `keyword` edges by descending weight, with a deterministic id tie-break, so the surviving set never depends on directory-listing order. Requesting a center id that is not an indexed note fails with `note not found`, and an unreadable note is skipped (logged as a warning) instead of failing the call. Output is `{ nodes: [{ id, title }], edges: [{ from, to, type, keywords?, weight? }], truncated: boolean, edgesTruncated: boolean }`, where `truncated` covers the node cap and `edgesTruncated` the edge cap.
 
 -----
 
@@ -62,12 +63,12 @@ The package is a single Cordis function plugin that registers `wiki_graph` on `c
 
 #### What the model sees
 
-The model sees the generated `wiki_graph` schema. The description states that the graph is read-only and derived from `[[link]]` references.
+The model sees the generated `wiki_graph` schema. The description states that the graph is read-only and derived from `[[link]]` references plus shared keywords.
 
 ##### 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.
+Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. 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. Nodes are capped at maxNodes (`truncated`) and edges at maxEdges (`edgesTruncated`).
 ```
 
 #### Token effect
@@ -83,7 +84,7 @@ Independent. The plugin only supplies tool results; it does not change the reque
 <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.
-- **Edges are scoped to selected nodes** — only links whose source and target both survive the `maxNodes` cap are returned, so boundary links outside the selected set are omitted.
+- **Edges are scoped to selected nodes** — only links whose source and target both survive the `maxNodes` cap are returned, so boundary links outside the selected set are omitted. A dense vault can then also hit the `maxEdges` cap; `edgesTruncated` reports when the returned edges are only a deterministic slice.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-tool-memory-graph` 让 agent 对 [`dsh-tool-memory-filesystem`](../tool-memory-filesystem/README.zh.md) 使用的 Markdown 仓库做只读图查询。模型可见一个工具 `wiki_graph`，返回由 Obsidian 风格 `[[link]]` 引用推导的笔记节点和有向边——可以是全仓库图，也可以是以某条笔记为中心的可达子图。该包复用 filesystem 插件的仓库根解析与解析辅助函数，路径约束、frontmatter 处理和 `indexHiddenDirs` 策略完全一致，不引入第二套解析器。
+`dsh-tool-memory-graph` 让 agent 对 [`dsh-tool-memory-filesystem`](../tool-memory-filesystem/README.zh.md) 使用的 Markdown 仓库做只读图查询。模型可见一个工具 `wiki_graph`，返回两类来源推导的笔记节点和有向边：显式 Obsidian 风格 `[[link]]` 引用，以及笔记之间的关键词共现（frontmatter tags/title 与正文中的显著词）。因此它能暴露类似“B 与 C 都提到 `word1`”的隐式关联，且当某条笔记被重写、共同词消失时该关联自动消失；若重写后双方出现新的共词（如 `word2`），则自动建立以 `word2` 为标签的新关联。该包复用 filesystem 插件的仓库根解析与解析辅助函数，路径约束、frontmatter 处理和 `indexHiddenDirs` 策略完全一致，不引入第二套解析器。
 
 ## 目录
 
@@ -41,17 +41,18 @@ kind: "package-reference"
 | `indexHiddenDirs` | `boolean` | `false` | 是否索引以 `.` 开头的目录（`.git` 与 `node_modules` 始终排除）。当 `vaultRoot` 指向工作区根时开启，以纳入 `.dsh/memory/`。 |
 | `maxDepth` | `number` | `1` | 指定中心笔记时 BFS 的最大深度。 |
 | `maxNodes` | `number` | `200` | 单次图查询返回的最大节点数。 |
+| `maxEdges` | `number` | `1000` | 单次图查询返回的最大边数。 |
 
 ### 工具
 
-- `wiki_graph(id?, depth?)` —— 不传 `id` 时返回全仓库的节点与有向边；传 `id` 时返回 `depth` 跳内的可达子图，两个端点都被选中时边界节点的出边也会包含。
+- `wiki_graph(id?, depth?)` —— 不传 `id` 时返回全仓库的节点与有向边；传 `id` 时返回 `depth` 跳内的可达子图，两个端点都被选中时边界节点的出边也会包含。边携带 `type`（`link` 或 `keyword`）、`keywords`（仅 `keyword` 边）和 `weight`（合并词频）。输出为 `{ nodes, edges, truncated, edgesTruncated }`：`truncated` 对应 `maxNodes` 截断，`edgesTruncated` 对应 `maxEdges` 截断，两者分开报告，节点完整不会被误读为整图完整。
 
 -----
 
 <a id="understand-the-implementation"></a>
 ## 实现说明
 
-本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。目标按与 `wiki_read` 相同的 Obsidian 语义解析——先精确仓库相对路径，再路径后缀，最后全仓库 basename 匹配，多重命中按确定性规则选择。先用广度优先遍历确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。节点集合超过 `maxNodes` 时，全仓库图保留码点序最小的若干 id（与 `tool-memory-filesystem` 的并列排序规则一致），子图则保留离中心最近的笔记——先按 BFS 层级、再按 id——因此保留哪些笔记不依赖目录列举顺序，子图也不会丢掉自己的中心节点。输出为 `{ nodes: [{ id, title }], edges: [{ from, to }], truncated: boolean }`。
+本包是单个 Cordis 函数插件，在 `ctx.tools` 上注册 `wiki_graph`。每次调用通过共享的 `resolveMemoryVaultRoot` 解析仓库根，用 `listNotePaths` 遍历笔记，用 `extractLinks`/`resolveLinkTarget` 提取 `[[link]]` 目标。目标按与 `wiki_read` 相同的 Obsidian 语义解析——先精确仓库相对路径，再路径后缀，最后全仓库 basename 匹配，多重命中按确定性规则选择。除显式链接外，工具还会从每条笔记提取显著词（frontmatter `tags` ×3、frontmatter `title` ×2、正文词 ×1），并为任意两篇共享一个或多个词的笔记创建 `keyword` 边。广度优先遍历带 visited 集合（循环链接图因此可终止），同时跟随 `link` 边与 `keyword` 边以确定节点集合，再从所有已选节点收集边，因此边界节点的出边不会丢失。节点集合超过 `maxNodes` 时，全仓库图保留码点序最小的若干 id（与 `tool-memory-filesystem` 的并列排序规则一致），子图则保留离中心最近的笔记——先按 BFS 层级、再按 id——因此保留哪些笔记不依赖目录列举顺序，子图也不会丢掉自己的中心节点。由于 `wiki_graph` 每次调用都会从磁盘重新计算，重写一条笔记会移除旧的 `keyword` 边，并为新正文中保留下来的或新出现的词建立新边。边在节点集合确定后按 `maxEdges` 截断：显式 `link` 边优先，其后是 `keyword` 边按 `weight` 降序，并以 id 作确定性并列裁决——保留哪些边同样不依赖目录列举顺序。以非已索引笔记作为中心 id 会以 `note not found` 失败；无法读取的笔记会被跳过（记入 logger 警告），不会让整次调用失败。输出为 `{ nodes: [{ id, title }], edges: [{ from, to, type, keywords?, weight? }], truncated: boolean, edgesTruncated: boolean }`，其中 `truncated` 对应节点上限、`edgesTruncated` 对应边上限。
 
 -----
 
@@ -62,12 +63,12 @@ kind: "package-reference"
 
 #### 模型可见内容
 
-模型看到生成的 `wiki_graph` schema。描述声明该图是只读的，由 `[[link]]` 引用推导。
+模型看到生成的 `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.
+Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. 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. Nodes are capped at maxNodes (`truncated`) and edges at maxEdges (`edgesTruncated`).
 ```
 
 #### Token 影响
@@ -83,7 +84,7 @@ Return the Obsidian-style [[link]] graph of the wiki vault: note ids, titles, an
 <a id="known-limitations-and-deferred-work"></a>
 
 - **无可视化** —— 工具返回 JSON 节点与边；渲染（Obsidian 图谱、Mermaid）由消费方负责。
-- **边限于已选节点** —— 只有两端都在 `maxNodes` 截断后保留下来的节点之间的链接才会出现，子图边界外的出边被省略。
+- **边限于已选节点** —— 只有两端都在 `maxNodes` 截断后保留下来的节点之间的链接才会出现，子图边界外的出边被省略；密集仓库随后可能触及 `maxEdges` 上限，`edgesTruncated` 会表明返回的边只是确定性切片。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -3,6 +3,12 @@
  * 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.
+ *
+ * In addition to explicit Obsidian-style `[[link]]` edges, `wiki_graph` now
+ * derives keyword edges: two notes share a directed keyword edge for every
+ * significant term that appears in both. Rewriting a note therefore
+ * automatically removes stale keyword edges and creates new ones for the terms
+ * that survive or appear in the new text.
  * @module @jacklika/dsh-tool-memory-graph
  */
 import { readFile } from 'node:fs/promises';
@@ -19,6 +25,7 @@ export const Config = z.object({
     extensions: z.array(z.string()).default(['.md']),
     maxDepth: z.number().default(1),
     maxNodes: z.number().default(200),
+    maxEdges: z.number().default(1000),
     indexHiddenDirs: z.boolean().default(false),
 });
 function assertPositiveInteger(name, value) {
@@ -26,8 +33,85 @@ function assertPositiveInteger(name, value) {
         throw new Error(`tool-memory-graph: ${name} must be a positive integer`);
     }
 }
-async function noteTitle(absolutePath, id) {
-    const text = await readFile(absolutePath, 'utf8');
+/**
+ * Minimal English stopwords. The list is intentionally short; the model-facing
+ * graph is most useful for distinctive project terms, not for hiding grammar.
+ */
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'shall', 'should', 'may', 'might',
+    'can', 'could', 'of', 'in', 'on', 'at', 'to', 'for', 'with', 'by', 'from', 'as', 'it', 'its',
+    'this', 'that', 'these', 'those', 'i', 'me', 'my', 'you', 'your', 'we', 'us', 'our', 'he', 'him',
+    'his', 'she', 'her', 'they', 'them', 'their', 'not', 'no', 'if', 'then', 'than', 'so', 'very',
+    'just', 'only', 'also', 'about', 'into', 'through', 'during', 'before', 'after', 'above', 'below',
+    'up', 'down', 'out', 'off', 'over', 'under', 'again', 'further', 'once', 'here', 'there', 'when',
+    'where', 'why', 'how', 'all', 'any', 'both', 'each', 'few', 'more', 'most', 'other', 'some',
+    'such', 'what', 'which', 'who', 'whom', 'whose', 'see', 'one', 'two', 'three', 'four', 'five',
+    'get', 'got', 'go', 'went', 'come', 'came', 'take', 'took', 'make', 'made', 'know', 'knew',
+    'think', 'thought', 'say', 'said', 'look', 'use', 'used', 'find', 'found', 'give', 'gave',
+    'tell', 'told', 'ask', 'asked', 'work', 'worked', 'seem', 'seemed', 'feel', 'felt', 'try',
+    'tried', 'leave', 'left', 'call', 'called', 'keep', 'kept', 'let', 'put', 'bring', 'brought',
+    'begin', 'began', 'help', 'helped', 'show', 'showed', 'hear', 'heard', 'play', 'played', 'run',
+    'ran', 'move', 'moved', 'live', 'lived', 'believe', 'believed', 'hold', 'held', 'must', 'need',
+    'needed', 'able', 'due', 'while', 'whereas', 'nevertheless', 'however', 'therefore', 'moreover',
+    'furthermore', 'nonetheless', 'otherwise', 'meanwhile', 'besides', 'thus', 'hence', 'accordingly',
+    'consequently', 'now', 'later', 'soon', 'early', 'late', 'long', 'much', 'many', 'little', 'less',
+    'least', 'well', 'better', 'best', 'bad', 'worse', 'worst', 'good', 'great', 'new', 'old',
+    'first', 'last', 'next', 'previous', 'same', 'different', 'own', 'another', 'none', 'either',
+    'neither', 'whether', 'nor', 'even', 'still', 'yet', 'already', 'always', 'never', 'often',
+    'sometimes', 'usually', 'rarely', 'seldom', 'back', 'already', 'quite', 'rather', 'really',
+    'actually', 'certainly', 'definitely', 'probably', 'possibly', 'perhaps', 'maybe', 'likely',
+    'sure', 'course', 'absolutely', 'completely', 'entirely', 'totally', 'almost', 'nearly',
+    'hardly', 'barely', 'scarcely', 'enough',
+]);
+/** Token pattern: starts with a letter, then letters or digits. Unicode-aware. */
+const TOKEN_RE = /[\p{L}][\p{L}\p{N}]*/gu;
+/**
+ * Extract normalised significant terms from Markdown text.
+ * - Frontmatter `tags` count 3x (they are explicit metadata).
+ * - Frontmatter `title` counts 2x.
+ * - Body terms count 1x.
+ * - Numbers-only tokens and short/stop tokens are dropped.
+ */
+function extractTerms(text) {
+    const { frontmatter, body } = splitFrontmatter(text);
+    const terms = new Map();
+    const addToken = (raw, multiplier = 1) => {
+        const normalized = raw.normalize('NFC').toLowerCase();
+        if (normalized.length < 2)
+            return;
+        if (/^\d+$/.test(normalized))
+            return;
+        if (STOPWORDS.has(normalized))
+            return;
+        terms.set(normalized, (terms.get(normalized) ?? 0) + multiplier);
+    };
+    const tokenize = (source) => {
+        const re = new RegExp(TOKEN_RE.source, TOKEN_RE.flags);
+        return source.match(re) ?? [];
+    };
+    if (Array.isArray(frontmatter.tags)) {
+        for (const tag of frontmatter.tags) {
+            if (typeof tag === 'string') {
+                for (const token of tokenize(tag))
+                    addToken(token, 3);
+            }
+        }
+    }
+    if (typeof frontmatter.title === 'string') {
+        for (const token of tokenize(frontmatter.title))
+            addToken(token, 2);
+    }
+    // Strip Obsidian `[[link]]` syntax so explicit links do not also create
+    // redundant keyword edges; keep markdown link text, not the URL.
+    const bodyForTerms = body
+        .replace(/\[\[[^\]]*\]\]/g, ' ')
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+    for (const token of tokenize(bodyForTerms))
+        addToken(token, 1);
+    return terms;
+}
+function noteTitleFromText(text, id) {
     const { frontmatter, body } = splitFrontmatter(text);
     const explicitTitle = typeof frontmatter.title === 'string' ? frontmatter.title.trim() : '';
     if (explicitTitle !== '')
@@ -35,88 +119,213 @@ async function noteTitle(absolutePath, id) {
     const heading = /^#\s+(.+)$/m.exec(body);
     return heading?.[1]?.trim() ?? id.replace(/\.[^.]+$/, '');
 }
+/**
+ * Build undirected keyword edges for a set of notes. Each pair of notes that
+ * share one or more terms receives two directed edges (A→B and B→A) carrying
+ * the sorted shared keywords and a combined weight.
+ */
+function buildKeywordEdges(noteTerms) {
+    const inverted = new Map();
+    for (const [id, terms] of noteTerms) {
+        for (const term of terms.keys()) {
+            const list = inverted.get(term) ?? [];
+            list.push(id);
+            inverted.set(term, list);
+        }
+    }
+    const pairData = new Map();
+    for (const [term, ids] of inverted) {
+        if (ids.length < 2)
+            continue;
+        for (let i = 0; i < ids.length; i += 1) {
+            for (let j = i + 1; j < ids.length; j += 1) {
+                const a = ids[i];
+                const b = ids[j];
+                const [first, second] = codeUnitCompare(a, b) <= 0 ? [a, b] : [b, a];
+                const weight = (noteTerms.get(a)?.get(term) ?? 0) + (noteTerms.get(b)?.get(term) ?? 0);
+                const key = `${first}\x00${second}`;
+                const entry = pairData.get(key) ?? { keywords: [], weight: 0 };
+                entry.keywords.push(term);
+                entry.weight += weight;
+                pairData.set(key, entry);
+            }
+        }
+    }
+    const edges = [];
+    for (const [key, { keywords, weight }] of pairData) {
+        const parts = key.split('\x00');
+        const from = parts[0];
+        const to = parts[1];
+        const sortedKeywords = [...keywords].sort(codeUnitCompare);
+        edges.push({ from, to, type: 'keyword', keywords: sortedKeywords, weight });
+        edges.push({ from: to, to: from, type: 'keyword', keywords: sortedKeywords, weight });
+    }
+    return edges;
+}
+async function loadVaultNotes(root, resolved, onSkip) {
+    const paths = await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs, onSkip);
+    const ids = paths.map(path => vaultRelativeId(root, path));
+    const linkResolver = createLinkResolver(ids);
+    const parsed = [];
+    const parsedById = new Map();
+    const skipped = new Map();
+    for (const path of paths) {
+        const id = vaultRelativeId(root, path);
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch (error) {
+            // One unreadable note must not fail the graph for the whole vault; the
+            // note is omitted and the loader logs the degradation.
+            skipped.set(id, error);
+            onSkip?.(path, error);
+            continue;
+        }
+        const note = { id, path, text, terms: extractTerms(text) };
+        parsed.push(note);
+        parsedById.set(id, note);
+    }
+    return { parsed, parsedById, linkResolver, skipped };
+}
+/** Build the skip callback that reports unreadable entries to the Loader logger. */
+function skipLogger(ctx, root) {
+    return (path, error) => {
+        const code = error.code ?? 'unknown';
+        ctx.logger?.warn(`tool-memory-graph: skipped unreadable entry ${vaultRelativeId(root, path)} (${code})`);
+    };
+}
+/** Validate that at least one note extension is configured. */
+function assertExtensions(extensions) {
+    if (extensions.length === 0) {
+        throw new Error('tool-memory-graph: extensions must list at least one file extension');
+    }
+}
+/**
+ * Apply the edge budget deterministically: explicit `link` edges are kept
+ * first, then `keyword` edges by descending weight and id order, so the same
+ * vault returns the same subset regardless of directory-listing order. Below
+ * the budget the edge list is returned untouched.
+ */
+function capEdges(edges, maxEdges) {
+    if (edges.length <= maxEdges)
+        return { edges, truncated: false };
+    const ordered = [...edges].sort((a, b) => {
+        const linkFirst = (a.type === 'keyword' ? 1 : 0) - (b.type === 'keyword' ? 1 : 0);
+        if (linkFirst !== 0)
+            return linkFirst;
+        const weightOrder = (b.weight ?? 0) - (a.weight ?? 0);
+        if (weightOrder !== 0)
+            return weightOrder;
+        return codeUnitCompare(a.from, b.from) || codeUnitCompare(a.to, b.to);
+    });
+    return { edges: ordered.slice(0, maxEdges), truncated: true };
+}
 /**
  * Build the vault-wide link graph: every note is a node; every `[[link]]`
- * that resolves to an existing note is an edge.
+ * that resolves to an existing note is an edge; every shared significant term
+ * between two nodes becomes a directed `keyword` edge in both directions.
  * @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 linkResolver = createLinkResolver(entries.map(([id]) => id));
-    const truncated = entries.length > resolved.maxNodes;
-    // `listNotePaths` follows readdir order, so the node cap would otherwise keep
-    // a filesystem-dependent subset of the vault.
-    const capped = [...entries].sort((a, b) => codeUnitCompare(a[0], b[0])).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));
+async function buildGraph(root, resolved, onSkip) {
+    const { parsed, linkResolver } = await loadVaultNotes(root, resolved, onSkip);
+    const truncated = parsed.length > resolved.maxNodes;
+    const capped = [...parsed].sort((a, b) => codeUnitCompare(a.id, b.id)).slice(0, resolved.maxNodes);
+    const idSet = new Set(capped.map(p => p.id));
+    const nodes = capped.map(p => ({ id: p.id, title: noteTitleFromText(p.text, p.id) }));
     const edges = [];
-    for (const [id, path] of capped) {
-        const text = await readFile(path, 'utf8');
-        for (const link of extractLinks(text)) {
+    for (const p of capped) {
+        for (const link of extractLinks(p.text)) {
             const targetPath = await resolveLinkTarget(root, resolved.extensions, link, linkResolver);
             if (targetPath === undefined)
                 continue;
             const targetId = vaultRelativeId(root, targetPath);
             if (idSet.has(targetId))
-                edges.push({ from: id, to: targetId });
+                edges.push({ from: p.id, to: targetId });
         }
     }
-    return { nodes, edges, truncated };
+    const noteTerms = new Map(capped.map(p => [p.id, p.terms]));
+    edges.push(...buildKeywordEdges(noteTerms));
+    // Safety: every edge endpoint must be in the returned node set.
+    const safeEdges = edges.filter(e => idSet.has(e.from) && idSet.has(e.to));
+    const budgeted = capEdges(safeEdges, resolved.maxEdges);
+    return { nodes, edges: budgeted.edges, truncated, edgesTruncated: budgeted.truncated };
 }
 /**
  * Collect the subgraph reachable from one note by following `[[link]]`
- * references breadth-first up to `depth`.
+ * references and shared-keyword edges 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.
+ * @param depth - maximum link/keyword hops from the center.
  * @returns the neighborhood graph, node-capped.
  */
-async function buildSubgraph(root, resolved, startId, depth) {
+async function buildSubgraph(root, resolved, startId, depth, onSkip) {
+    const { parsed, parsedById, linkResolver, skipped } = await loadVaultNotes(root, resolved, onSkip);
     const startPath = await containedPathReal(root, startId);
-    const linkResolver = createLinkResolver((await listNotePaths(root, resolved.extensions, resolved.indexHiddenDirs))
-        .map(path => vaultRelativeId(root, path)));
-    const visited = new Map([[vaultRelativeId(root, startPath), startPath]]);
-    const levels = new Map([[vaultRelativeId(root, startPath), 0]]);
-    let frontier = [startPath];
+    const startNoteId = vaultRelativeId(root, startPath);
+    // A missing path, a directory, or a file outside the configured extensions
+    // resolves fine but has no indexed note; seeding the BFS with it would crash
+    // on the first `parsedById.get(id)!` lookup.
+    if (!parsedById.has(startNoteId)) {
+        const skipError = skipped.get(startNoteId);
+        if (skipError !== undefined) {
+            const code = skipError.code ?? 'unknown error';
+            throw new Error(`tool-memory-graph: cannot read note ${JSON.stringify(startNoteId)}: ${code}`);
+        }
+        throw new Error(`tool-memory-graph: note not found: ${startNoteId}`);
+    }
+    const idSetAll = new Set(parsed.map(p => p.id));
+    const adjacency = new Map();
+    for (const p of parsed) {
+        const neighbors = [];
+        for (const link of extractLinks(p.text)) {
+            const targetPath = await resolveLinkTarget(root, resolved.extensions, link, linkResolver);
+            if (targetPath === undefined)
+                continue;
+            const targetId = vaultRelativeId(root, targetPath);
+            if (idSetAll.has(targetId) && !neighbors.includes(targetId))
+                neighbors.push(targetId);
+        }
+        adjacency.set(p.id, neighbors);
+    }
+    const noteTerms = new Map(parsed.map(p => [p.id, p.terms]));
+    const keywordEdges = buildKeywordEdges(noteTerms);
+    for (const { from, to } of keywordEdges) {
+        const list = adjacency.get(from) ?? [];
+        if (!list.includes(to))
+            list.push(to);
+        adjacency.set(from, list);
+    }
+    const visited = new Map([[startNoteId, 0]]);
+    let frontier = [startNoteId];
     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, linkResolver);
-                if (targetPath === undefined)
-                    continue;
-                const toId = vaultRelativeId(root, targetPath);
-                if (!visited.has(toId)) {
-                    visited.set(toId, targetPath);
-                    levels.set(toId, level + 1);
-                    next.push(targetPath);
+        for (const id of frontier) {
+            for (const neighbor of adjacency.get(id) ?? []) {
+                if (!visited.has(neighbor)) {
+                    visited.set(neighbor, level + 1);
+                    next.push(neighbor);
                 }
             }
         }
         frontier = next;
     }
     const truncated = visited.size > resolved.maxNodes;
-    // Truncate by distance from the center, then by id: the neighborhood closest
-    // to the requested note survives the cap, and which notes those are does not
-    // depend on readdir or link order.
     const ids = [...visited.keys()]
-        .sort((a, b) => (levels.get(a) ?? 0) - (levels.get(b) ?? 0) || codeUnitCompare(a, b))
+        .sort((a, b) => (visited.get(a) ?? 0) - (visited.get(b) ?? 0) || codeUnitCompare(a, b))
         .slice(0, resolved.maxNodes);
     const idSet = new Set(ids);
+    const nodes = ids.map(id => {
+        const p = parsedById.get(id);
+        return { id, title: noteTitleFromText(p.text, id) };
+    });
     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 p = parsedById.get(id);
+        for (const link of extractLinks(p.text)) {
             const targetPath = await resolveLinkTarget(root, resolved.extensions, link, linkResolver);
             if (targetPath === undefined)
                 continue;
@@ -125,12 +334,15 @@ async function buildSubgraph(root, resolved, startId, depth) {
                 edges.push({ from: id, to: toId });
         }
     }
-    return { nodes, edges, truncated };
+    const filteredKeywordEdges = keywordEdges.filter(e => idSet.has(e.from) && idSet.has(e.to));
+    edges.push(...filteredKeywordEdges);
+    const budgeted = capEdges(edges, resolved.maxEdges);
+    return { nodes, edges: budgeted.edges, truncated, edgesTruncated: budgeted.truncated };
 }
 /**
  * Register the `wiki_graph` tool on `ctx.tools`.
  * @param ctx - registrant context carrying the tool registry.
- * @param config - deployment's explicit vault configuration.
+ * @param config - plugin configuration.
  */
 export function apply(ctx, config) {
     const tools = ctx.get('tools');
@@ -141,9 +353,11 @@ export function apply(ctx, config) {
     const resolved = config;
     assertPositiveInteger('maxDepth', resolved.maxDepth);
     assertPositiveInteger('maxNodes', resolved.maxNodes);
+    assertPositiveInteger('maxEdges', resolved.maxEdges);
+    assertExtensions(resolved.extensions);
     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.',
+        description: 'Return the link and keyword graph of the wiki vault: note ids, titles, and directed edges. Explicit `[[link]]` edges are type `link`; edges derived from shared significant terms are type `keyword` with `keywords` and `weight`. 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. Nodes are capped at maxNodes (`truncated`) and edges at maxEdges (`edgesTruncated`).',
         parameters: {
             id: {
                 type: 'string',
@@ -151,7 +365,7 @@ export function apply(ctx, config) {
             },
             depth: {
                 type: 'integer',
-                description: 'Maximum [[link]] hops from the center note; defaults to the configured maxDepth.',
+                description: 'Maximum link or keyword hops from the center note; defaults to the configured maxDepth.',
             },
         },
         output: {
@@ -162,9 +376,10 @@ export function apply(ctx, config) {
             const vaultRoot = resolveMemoryVaultRoot(resolved.vaultRoot, exec);
             const depth = args.depth ?? resolved.maxDepth;
             assertPositiveInteger('depth', depth);
+            const onSkip = skipLogger(ctx, vaultRoot);
             const graph = args.id === undefined
-                ? await buildGraph(vaultRoot, resolved)
-                : await buildSubgraph(vaultRoot, resolved, args.id, depth);
+                ? await buildGraph(vaultRoot, resolved, onSkip)
+                : await buildSubgraph(vaultRoot, resolved, args.id, depth, onSkip);
             return graph;
         },
     })));

package/lib/types/index.d.ts

@@ -3,6 +3,12 @@
  * 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.
+ *
+ * In addition to explicit Obsidian-style `[[link]]` edges, `wiki_graph` now
+ * derives keyword edges: two notes share a directed keyword edge for every
+ * significant term that appears in both. Rewriting a note therefore
+ * automatically removes stale keyword edges and creates new ones for the terms
+ * that survive or appear in the new text.
  * @module @jacklika/dsh-tool-memory-graph
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -25,6 +31,8 @@ export interface Config {
     maxDepth?: number;
     /** Maximum nodes returned in one graph. */
     maxNodes?: number;
+    /** Maximum edges returned in one graph. */
+    maxEdges?: number;
     /** Descend into dot-directories besides the fixed exclusions while indexing. */
     indexHiddenDirs?: boolean;
 }
@@ -33,7 +41,7 @@ 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.
+ * @param config - plugin configuration.
  */
 export declare function apply(ctx: Context, config: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.5",
+  "version": "0.1.0-alpha.7",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.4",
-    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.9"
+    "@jacklika/dsh-tool-memory-filesystem": "^0.1.3-alpha.10"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.4",