@gmickel/gno 0.11.0 → 0.13.0

package/README.md

@@ -27,6 +27,25 @@ GNO is a local knowledge engine for privacy-conscious developers and AI agents.
 
 ---
 
+## What's New in v0.13
+
+- **Knowledge Graph**: Interactive force-directed visualization of document connections
+- **Graph with Similarity**: See semantic similarity as golden edges (not just wiki/markdown links)
+- **CLI**: `gno graph` command with collection filtering and similarity options
+- **Web UI**: `/graph` page with zoom, pan, collection filter, similarity toggle
+- **MCP**: `gno_graph` tool for AI agents to explore document relationships
+- **REST API**: `/api/graph` endpoint with full query parameters
+
+### v0.12
+
+- **Note Linking**: Wiki-style `[[links]]`, backlinks, and AI-powered related notes
+- **Tag System**: Filter searches by frontmatter tags with `--tags-any`/`--tags-all`
+- **Web UI**: Outgoing links panel, backlinks panel, related notes sidebar
+- **CLI**: `gno links`, `gno backlinks`, `gno similar` commands
+- **MCP**: `gno_links`, `gno_backlinks`, `gno_similar` tools
+
+---
+
 ## Quick Start
 
 ```bash
@@ -144,16 +163,20 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 6 tools via [Model Context Protocol](https://modelcontextprotocol.io):
-
-| Tool            | Description                 |
-| :-------------- | :-------------------------- |
-| `gno_search`    | BM25 keyword search         |
-| `gno_vsearch`   | Vector semantic search      |
-| `gno_query`     | Hybrid search (recommended) |
-| `gno_get`       | Retrieve document by ID     |
-| `gno_multi_get` | Batch document retrieval    |
-| `gno_status`    | Index health check          |
+GNO exposes tools via [Model Context Protocol](https://modelcontextprotocol.io):
+
+| Tool            | Description                           |
+| :-------------- | :------------------------------------ |
+| `gno_search`    | BM25 keyword search                   |
+| `gno_vsearch`   | Vector semantic search                |
+| `gno_query`     | Hybrid search (recommended)           |
+| `gno_get`       | Retrieve document by ID               |
+| `gno_multi_get` | Batch document retrieval              |
+| `gno_links`     | Get outgoing links from document      |
+| `gno_backlinks` | Get documents linking TO document     |
+| `gno_similar`   | Find semantically similar documents   |
+| `gno_graph`     | Get knowledge graph (nodes and edges) |
+| `gno_status`    | Index health check                    |
 
 **Design**: MCP tools are retrieval-only. Your AI assistant (Claude, GPT-4) synthesizes answers from retrieved context. Best retrieval (GNO) + best reasoning (your LLM).
 
@@ -201,6 +224,18 @@ Full-featured markdown editor with:
 | **Keyboard Shortcuts**  | ⌘S save, ⌘B bold, ⌘I italic, ⌘K link |
 | **Quick Capture**       | ⌘N creates new note from anywhere    |
 
+### Document Viewer
+
+![GNO Document Viewer](./assets/screenshots/webui-doc-view.jpg)
+
+View documents with full context: outgoing links, backlinks, and AI-powered related notes sidebar.
+
+### Knowledge Graph
+
+![GNO Knowledge Graph](./assets/screenshots/webui-graph.jpg)
+
+Interactive visualization of document connections. Wiki links, markdown links, and optional similarity edges rendered as a navigable constellation.
+
 ### Collections Management
 
 ![GNO Collections](./assets/screenshots/webui-collections.jpg)
@@ -315,6 +350,7 @@ graph TD
 | **MCP Server**      | Works with Claude Desktop, Cursor, Zed, + 8 more                               |
 | **Collections**     | Organize sources with patterns, excludes, contexts                             |
 | **Tag Filtering**   | Frontmatter tags with hierarchical paths, filter via `--tags-any`/`--tags-all` |
+| **Note Linking**    | Wiki links, backlinks, related notes, cross-collection navigation              |
 | **Multilingual**    | 30+ languages, auto-detection, cross-lingual search                            |
 | **Incremental**     | SHA-256 tracking, only changed files re-indexed                                |
 | **Keyboard First**  | ⌘N capture, ⌘K search, ⌘/ shortcuts, ⌘S save                                   |

package/assets/skill/SKILL.md

@@ -20,6 +20,8 @@ Fast local semantic search. Index once, search instantly. No cloud, no API keys.
 - User wants a **web UI** to browse/search documents
 - User asks to **get AI answers** from their documents
 - User wants to **tag, categorize, or filter** documents
+- User asks about **backlinks, wiki links, or related notes**
+- User wants to **visualize document connections** or see a **knowledge graph**
 
 ## Quick Start
 
@@ -32,18 +34,19 @@ gno search "your query"               # BM25 keyword search
 
 ## Command Overview
 
-| Category     | Commands                                                         | Description                                            |
-| ------------ | ---------------------------------------------------------------- | ------------------------------------------------------ |
-| **Search**   | `search`, `vsearch`, `query`, `ask`                              | Find documents by keywords, meaning, or get AI answers |
-| **Retrieve** | `get`, `multi-get`, `ls`                                         | Fetch document content by URI or ID                    |
-| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index                     |
-| **Tags**     | `tags`, `tags add`, `tags rm`                                    | Organize and filter documents                          |
-| **Context**  | `context add/list/rm/check`                                      | Add hints to improve search relevance                  |
-| **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                 |
-| **Serve**    | `serve`                                                          | Web UI for browsing and searching                      |
-| **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                               |
-| **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                            |
-| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `completion`             | Maintenance and diagnostics                            |
+| Category     | Commands                                                         | Description                                               |
+| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |
+| **Search**   | `search`, `vsearch`, `query`, `ask`                              | Find documents by keywords, meaning, or get AI answers    |
+| **Links**    | `links`, `backlinks`, `similar`, `graph`                         | Navigate document relationships and visualize connections |
+| **Retrieve** | `get`, `multi-get`, `ls`                                         | Fetch document content by URI or ID                       |
+| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index                        |
+| **Tags**     | `tags`, `tags add`, `tags rm`                                    | Organize and filter documents                             |
+| **Context**  | `context add/list/rm/check`                                      | Add hints to improve search relevance                     |
+| **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                    |
+| **Serve**    | `serve`                                                          | Web UI for browsing and searching                         |
+| **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                                  |
+| **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                               |
+| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`      | Maintenance and diagnostics                               |
 
 ## Search Modes
 

package/assets/skill/cli-reference.md

@@ -234,6 +234,76 @@ Validate context configuration.
 gno context check [--json]
 ```
 
+## Note Linking
+
+### gno links
+
+List outgoing links from a document.
+
+```bash
+gno links <ref> [options]
+```
+
+| Option       | Description                          |
+| ------------ | ------------------------------------ |
+| `--type`     | Filter: `wiki`, `markdown`, or `all` |
+| `--resolved` | Only show resolved links             |
+| `--broken`   | Only show broken links               |
+| `--json`     | JSON output                          |
+
+### gno backlinks
+
+Find documents linking TO a target.
+
+```bash
+gno backlinks <ref> [options]
+```
+
+| Option   | Description               |
+| -------- | ------------------------- |
+| `-n`     | Max results (default: 20) |
+| `--json` | JSON output               |
+
+### gno similar
+
+Find semantically similar documents.
+
+```bash
+gno similar <ref> [options]
+```
+
+| Option               | Description                   |
+| -------------------- | ----------------------------- |
+| `-n`                 | Max results (default: 5)      |
+| `--threshold`        | Min similarity (0-1)          |
+| `--cross-collection` | Search across all collections |
+| `--json`             | JSON output                   |
+
+**Requirements**: Embeddings must exist for source and target documents.
+
+### gno graph
+
+Generate knowledge graph of document connections.
+
+```bash
+gno graph [options]
+```
+
+| Option             | Default | Description                    |
+| ------------------ | ------- | ------------------------------ |
+| `-c, --collection` | all     | Filter to single collection    |
+| `--limit`          | 2000    | Max nodes                      |
+| `--edge-limit`     | 10000   | Max edges                      |
+| `--similar`        | false   | Include similarity edges       |
+| `--threshold`      | 0.7     | Similarity threshold (0-1)     |
+| `--linked-only`    | true    | Exclude isolated nodes         |
+| `--similar-top-k`  | 5       | Similar docs per node (max 20) |
+| `--json`           | -       | JSON output                    |
+
+**Edge types**: `wiki` (wiki links), `markdown` (md links), `similar` (vector similarity).
+
+**Web UI**: Access interactive graph at `http://localhost:3000/graph` via `gno serve`.
+
 ## Tags
 
 ### gno tags
@@ -324,6 +394,19 @@ gno doctor [--json|--md]
 gno cleanup
 ```
 
+### gno vec
+
+Vector index maintenance. Use when `gno similar` returns empty despite embeddings.
+
+```bash
+gno vec sync      # Fast incremental sync
+gno vec rebuild   # Full rebuild
+```
+
+| Option   | Description |
+| -------- | ----------- |
+| `--json` | JSON output |
+
 ## MCP Server
 
 ### gno mcp

package/assets/skill/examples.md

@@ -206,6 +206,54 @@ gno models use quality
 gno models pull
 ```
 
+## Note Linking
+
+### View outgoing links
+
+```bash
+# List all links from a document
+gno links gno://notes/readme.md
+
+# Filter by type
+gno links gno://notes/readme.md --type wiki
+gno links gno://notes/readme.md --type markdown
+
+# Show only broken links
+gno links gno://notes/readme.md --broken
+```
+
+### Find backlinks
+
+```bash
+# Find all documents linking TO this one
+gno backlinks gno://notes/api-design.md
+
+# More results
+gno backlinks gno://notes/api-design.md -n 50
+```
+
+### Find related notes
+
+```bash
+# Find semantically similar documents
+gno similar gno://notes/auth.md
+
+# Stricter threshold (default: 0.7)
+gno similar gno://notes/auth.md --threshold 0.85
+
+# Search across all collections
+gno similar gno://notes/auth.md --cross-collection
+```
+
+### Wiki link syntax
+
+```markdown
+# In your documents:
+See [[API Design]] for details.
+Check [[work:Project Plan]] for cross-collection link.
+Read [[Security#OAuth]] for specific section.
+```
+
 ## Tagging
 
 ### List and manage tags

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -101,6 +101,7 @@
     "picocolors": "^1.1.1",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
+    "react-force-graph-2d": "^1.29.0",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",

package/src/cli/commands/embed.ts

@@ -372,6 +372,26 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       return { success: false, error: result.error };
     }
 
+    // Sync vec index if any vec0 writes failed (matches embedBacklog behavior)
+    if (vectorIndex.vecDirty) {
+      const syncResult = await vectorIndex.syncVecIndex();
+      if (syncResult.ok) {
+        const { added, removed } = syncResult.value;
+        if (added > 0 || removed > 0) {
+          if (!options.json) {
+            process.stdout.write(
+              `\n[vec] Synced index: +${added} -${removed}\n`
+            );
+          }
+        }
+        vectorIndex.vecDirty = false;
+      } else if (!options.json) {
+        process.stdout.write(
+          `\n[vec] Sync failed: ${syncResult.error.message}\n`
+        );
+      }
+    }
+
     return {
       success: true,
       embedded: result.embedded,

package/src/cli/commands/graph.ts

@@ -0,0 +1,187 @@
+/**
+ * gno graph command implementation.
+ * Outputs knowledge graph of document links.
+ *
+ * @module src/cli/commands/graph
+ */
+
+import type { GetGraphOptions, GraphResult } from "../../store/types";
+
+import { initStore } from "./shared";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GraphOptions {
+  /** Override config path */
+  configPath?: string;
+  /** Filter by collection */
+  collection?: string;
+  /** Max nodes (default 2000) */
+  limitNodes?: number;
+  /** Max edges (default 10000) */
+  limitEdges?: number;
+  /** Include similarity edges */
+  includeSimilar?: boolean;
+  /** Similarity threshold (0-1) */
+  threshold?: number;
+  /** Include isolated nodes */
+  includeIsolated?: boolean;
+  /** Similar top-K per node */
+  similarTopK?: number;
+  /** Output format: json (default), dot, mermaid */
+  format?: "json" | "dot" | "mermaid";
+}
+
+export type GraphCommandResult =
+  | { success: true; data: GraphResult }
+  | { success: false; error: string; isValidation?: boolean };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Command: graph
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Execute gno graph command.
+ * Returns knowledge graph of document links.
+ */
+export async function graph(
+  options: GraphOptions = {}
+): Promise<GraphCommandResult> {
+  const initResult = await initStore({ configPath: options.configPath });
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+  const { store } = initResult;
+
+  try {
+    const storeOptions: GetGraphOptions = {
+      collection: options.collection,
+      limitNodes: options.limitNodes,
+      limitEdges: options.limitEdges,
+      includeSimilar: options.includeSimilar,
+      threshold: options.threshold,
+      linkedOnly: !options.includeIsolated,
+      similarTopK: options.similarTopK,
+    };
+
+    const result = await store.getGraph(storeOptions);
+    if (!result.ok) {
+      return { success: false, error: result.error.message };
+    }
+
+    return { success: true, data: result.value };
+  } finally {
+    await store.close();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Formatters
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Escape string for DOT format (double quotes, newlines) */
+function escapeDot(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+
+/** Escape string for Mermaid (quotes, brackets, newlines) */
+function escapeMermaid(s: string): string {
+  return s
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, "#quot;")
+    .replace(/\[/g, "#lbrack;")
+    .replace(/\]/g, "#rbrack;")
+    .replace(/\n/g, " ");
+}
+
+/**
+ * Format graph result as DOT (Graphviz).
+ */
+export function formatDot(result: GraphResult): string {
+  const lines: string[] = ["digraph G {"];
+  lines.push("  rankdir=LR;");
+  lines.push(
+    '  node [shape=box, style="rounded,filled", fillcolor="#f0f0f0"];'
+  );
+
+  // Nodes
+  for (const node of result.nodes) {
+    const label = escapeDot(node.title ?? node.id);
+    lines.push(`  "${escapeDot(node.id)}" [label="${label}"];`);
+  }
+
+  // Edges
+  for (const link of result.links) {
+    const style =
+      link.type === "similar"
+        ? ' [style=dashed, color="#888888", dir=none]'
+        : "";
+    lines.push(
+      `  "${escapeDot(link.source)}" -> "${escapeDot(link.target)}"${style};`
+    );
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}
+
+/**
+ * Format graph result as Mermaid.
+ */
+export function formatMermaid(result: GraphResult): string {
+  const lines: string[] = ["graph LR"];
+
+  // Build node ID map (Mermaid needs simple IDs)
+  const nodeIds = new Map<string, string>();
+  result.nodes.forEach((node, i) => {
+    nodeIds.set(node.id, `n${i}`);
+  });
+
+  // Nodes with labels
+  for (const node of result.nodes) {
+    const mermaidId = nodeIds.get(node.id) ?? node.id;
+    const label = escapeMermaid(node.title ?? node.id);
+    lines.push(`  ${mermaidId}["${label}"]`);
+  }
+
+  // Edges
+  for (const link of result.links) {
+    const sourceId = nodeIds.get(link.source) ?? link.source;
+    const targetId = nodeIds.get(link.target) ?? link.target;
+    const arrow = link.type === "similar" ? "---" : "-->";
+    lines.push(`  ${sourceId} ${arrow} ${targetId}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format graph result for output.
+ */
+export function formatGraph(
+  result: GraphCommandResult,
+  options: GraphOptions
+): string {
+  if (!result.success) {
+    if (options.format === "json" || !options.format) {
+      return JSON.stringify({
+        error: { code: "GRAPH_FAILED", message: result.error },
+      });
+    }
+    return `Error: ${result.error}`;
+  }
+
+  const { data } = result;
+
+  switch (options.format) {
+    case "dot":
+      return formatDot(data);
+    case "mermaid":
+      return formatMermaid(data);
+    case "json":
+    default:
+      return JSON.stringify(data, null, 2);
+  }
+}