@graphmemory/server 1.1.0 → 1.3.0

package/dist/ui/assets/help-CEMQqZUR.js

@@ -0,0 +1,891 @@
+var e=[{id:`getting-started`,title:`Getting Started`,summary:`What Graph Memory does, how the six graphs work, and how to get started.`,category:`overview`,relatedTools:[],content:`# Getting Started with Graph Memory
+
+Graph Memory is an MCP server that builds a **semantic graph** from your project directory. It indexes markdown documentation, TypeScript/JavaScript source code, and all project files — then exposes 58 tools for searching, navigating, and enriching that knowledge.
+
+## What does it do?
+
+Imagine having a smart assistant that has read every file in your project and can instantly:
+
+- **Find relevant documentation** by meaning, not just keywords
+- **Look up any code symbol** — functions, classes, interfaces — with full context
+- **Track knowledge and decisions** in a persistent note graph
+- **Manage tasks** with a full kanban workflow
+- **Store reusable skills** — recipes, procedures, and troubleshooting guides
+- **Cross-reference** code definitions with documentation examples
+
+## The Six Graphs
+
+Graph Memory maintains six separate but interconnected graphs:
+
+| Graph | What it indexes | Created from |
+|-------|----------------|--------------|
+| **DocGraph** | Markdown sections, headings, code blocks | Files matching \`graphs.docs.include\` |
+| **CodeGraph** | Functions, classes, methods, imports | Files matching \`graphs.code.include\` |
+| **FileIndexGraph** | All files and directories with metadata | Entire project directory |
+| **KnowledgeGraph** | User-created notes, facts, decisions | Manual creation via tools |
+| **TaskGraph** | Tasks with status, priority, dependencies | Manual creation via tools |
+| **SkillGraph** | Reusable recipes, procedures, triggers | Manual creation via tools |
+
+## How search works
+
+All search tools use **semantic search** — you describe what you're looking for in natural language, and the system finds the most relevant results by meaning.
+
+Under the hood:
+1. Your query is converted to a **vector embedding** (a list of numbers representing meaning)
+2. This vector is compared against all indexed items using **cosine similarity**
+3. Top matches are expanded via **BFS graph walk** — following links to find related content
+4. Results are scored and ranked by relevance
+
+This means \`"how to authenticate users"\` will find documentation about auth even if it never contains that exact phrase.
+
+## Quick start workflow
+
+1. **Start** the server: \`graphmemory serve\` (uses current directory as project, or \`--config graph-memory.yaml\` for custom config)
+3. **Browse** your indexed content in the UI
+4. **Search** across all graphs using natural language
+5. **Create notes** to capture knowledge and decisions
+6. **Link** notes to code, docs, files, and tasks for a connected knowledge base
+`},{id:`how-search-works`,title:`How Semantic Search Works`,summary:`Vector embeddings, cosine similarity, and BFS graph expansion explained.`,category:`concept`,relatedTools:[`search`,`search_code`,`search_notes`,`search_tasks`,`search_skills`,`search_all_files`,`search_topic_files`,`search_files`,`search_snippets`],content:`# How Search Works
+
+Graph Memory uses **hybrid search** — combining BM25 keyword matching with vector similarity, fused via Reciprocal Rank Fusion (RRF). This gives you the best of both worlds: precise keyword matching for exact terms and semantic understanding for natural language queries.
+
+## Vector embeddings
+
+When content is indexed, each chunk (doc section, code symbol, file path, note, task, skill) is converted to a **vector embedding** — a list of ~1024 numbers that represent semantic meaning.
+
+The default model is \`bge-m3\`, a multilingual transformer that runs locally. No API calls, no data leaves your machine.
+
+Similar concepts produce similar vectors:
+- "authentication" and "login" will have high similarity
+- "authentication" and "database schema" will have low similarity
+
+### What gets embedded
+
+| Graph | What's embedded | Embedding input |
+|-------|-----------------|-----------------|
+| DocGraph | Each section/heading | Section title + content text |
+| DocGraph (file-level) | Each file root | File path + h1 title |
+| CodeGraph | Each symbol | Symbol name + signature + docComment |
+| CodeGraph (file-level) | Each file root | File path only |
+| FileIndexGraph | Each file | File path |
+| KnowledgeGraph | Each note | Note title + content |
+| TaskGraph | Each task | Task title + description |
+| SkillGraph | Each skill | Skill title + description |
+
+### Per-graph models
+
+Each graph can use a different embedding model, configured in \`graph-memory.yaml\`:
+
+\`\`\`yaml
+projects:
+  my-app:
+    model:
+      name: Xenova/bge-m3          # default for all graphs
+    graphs:
+      docs:
+        model:
+          name: Xenova/bge-m3      # override for docs (whole object, no merge)
+      code:
+        model:
+          name: Xenova/bge-base-en-v1.5
+      # knowledge, tasks, files, skills inherit project.model
+\`\`\`
+
+Model resolution: \`graph.model → project.model → server.model → defaults\`. Each level is a complete config block — no field-by-field merge. Embedding config (\`batchSize\`, \`maxChars\`, etc.) is separate and merges field-by-field.
+
+## Cosine similarity
+
+To compare a search query against indexed content, both are converted to vectors, then compared using **cosine similarity** (dot product of L2-normalized vectors).
+
+Score ranges from 0 to 1:
+- **> 0.7** — very relevant
+- **0.5 - 0.7** — probably relevant
+- **< 0.5** — weak match
+
+The default \`minScore\` threshold is **0.5** for node search and **0.3** for file-level search.
+
+## BFS graph expansion
+
+After finding the top-K most similar nodes, the search expands outward through the graph using **breadth-first search** (BFS):
+
+1. Start with the top-K seed nodes
+2. Follow edges to neighboring nodes (linked sections, related code symbols, connected notes)
+3. Each hop applies a **decay factor** (default 0.8) — relevance decreases with distance
+4. Continue up to \`bfsDepth\` hops (default 1)
+
+This is powerful because relevant content is often **near** other relevant content in the graph.
+
+### What edges are followed
+
+| Graph | Edge types followed during BFS |
+|-------|-------------------------------|
+| DocGraph | \`sibling\` (next section), \`cross-file link\` (markdown links) |
+| CodeGraph | \`contains\` (file→symbol), \`imports\`, \`extends\`, \`implements\` |
+| KnowledgeGraph | All relation edges between notes |
+| TaskGraph | \`subtask_of\`, \`blocks\`, \`related_to\` |
+| SkillGraph | \`depends_on\`, \`related_to\`, \`variant_of\` |
+
+## Hybrid scoring: BM25 + Vector
+
+Each search combines two ranking methods:
+
+1. **Vector search** — cosine similarity between query embedding and node embedding (finds semantically similar content)
+2. **BM25 keyword search** — classic TF-IDF term matching (finds exact keyword matches)
+
+Results are fused using **Reciprocal Rank Fusion (RRF)**:
+\`\`\`
+score(d) = 1/(k + rank_vector) + 1/(k + rank_bm25)
+\`\`\`
+
+This means a document ranked highly by both methods gets the highest fused score. A document ranked highly by only one method still appears, but lower.
+
+### BM25 tokenizer
+
+The BM25 tokenizer splits text on whitespace, punctuation, and **camelCase boundaries**:
+- \`getUserById\` → \`[get, user, by, id]\`
+- \`AuthService\` → \`[auth, service]\`
+- \`XMLParser\` → \`[xml, parser]\`
+
+This makes it effective for searching code symbols by partial name.
+
+### Search mode
+
+All search tools accept a \`searchMode\` parameter:
+
+| Mode | Description |
+|------|-------------|
+| \`hybrid\` (default) | BM25 + vector, fused with RRF |
+| \`vector\` | Embedding similarity only (original behavior) |
+| \`keyword\` | BM25 keyword matching only |
+
+Use \`vector\` mode when you want pure semantic search. Use \`keyword\` when you know the exact term.
+
+## Two types of search
+
+### Node search (hybrid + BFS)
+
+Used by: \`search\`, \`search_code\`, \`search_notes\`, \`search_tasks\`, \`search_skills\`
+
+Full parameter set:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| \`query\` | (required) | Natural language search query |
+| \`topK\` | 5 | Number of seed nodes from hybrid scoring |
+| \`bfsDepth\` | 1 | Hops to follow in graph expansion (0 = no expansion) |
+| \`maxResults\` | 20 | Maximum results to return |
+| \`minScore\` | 0.5 | Minimum relevance score (0–1) |
+| \`bfsDecay\` | 0.8 | Score multiplier per hop |
+| \`searchMode\` | \`hybrid\` | \`hybrid\`, \`vector\`, or \`keyword\` |
+
+### File-level search (cosine only)
+
+Used by: \`search_topic_files\`, \`search_files\`, \`search_all_files\`, \`search_snippets\`
+
+Simpler — no BFS expansion, just vector similarity:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| \`query\` | (required) | Search query |
+| \`topK\` | 10 | Maximum results |
+| \`minScore\` | 0.3 | Minimum relevance score (0–1) |
+
+Lower \`minScore\` default because file path and code snippet embeddings are less semantically rich than full content.
+
+## All search tools at a glance
+
+| Tool | Graph | Search type | What it searches |
+|------|-------|-------------|-----------------|
+| \`search\` | DocGraph | Node (BFS) | Documentation sections |
+| \`search_topic_files\` | DocGraph | File-level | Documentation files |
+| \`search_snippets\` | DocGraph | File-level | Code blocks in docs (+ language filter) |
+| \`search_code\` | CodeGraph | Node (BFS) | Code symbols |
+| \`search_files\` | CodeGraph | File-level | Source code files |
+| \`search_all_files\` | FileIndexGraph | File-level | All project files |
+| \`search_notes\` | KnowledgeGraph | Node (BFS) | Knowledge notes |
+| \`search_tasks\` | TaskGraph | Node (BFS) | Tasks |
+| \`search_skills\` | SkillGraph | Node (BFS) | Skills |
+
+## Tips
+
+- Lower \`minScore\` (e.g., 0.3) to get more results when you're exploring
+- Increase \`bfsDepth\` to 2 when you want to discover loosely related content
+- Set \`bfsDepth: 0\` for pure vector search without graph expansion
+- Use \`searchMode: 'keyword'\` when searching for exact symbol names like \`AuthService\`
+- Use \`searchMode: 'vector'\` for pure semantic queries like "how does authentication work"
+- File-level searches are faster — use them as a first pass before diving into node-level search
+- The search query is embedded the same way as the content — so descriptive natural language works best
+- All models run locally — first search after startup may be slow while the model loads
+`},{id:`graph-structure`,title:`Graph Structure`,summary:`The six graphs: DocGraph, CodeGraph, FileIndexGraph, KnowledgeGraph, TaskGraph, SkillGraph.`,category:`concept`,relatedTools:[`list_topics`,`get_toc`,`get_node`,`list_files`,`get_file_symbols`,`get_symbol`,`list_all_files`,`get_file_info`,`list_notes`,`get_note`,`list_tasks`,`get_task`,`list_skills`,`get_skill`],content:`# Graph Structure
+
+Graph Memory organizes project knowledge into six interconnected graphs. Each graph is a set of **nodes** (entities) connected by **edges** (relationships).
+
+## DocGraph
+
+Indexes markdown documentation by parsing files into a hierarchy of sections.
+
+**Nodes:**
+- **File root** (level 1) — represents the markdown file itself
+- **Sections** (level 2+) — headings and their content (\`# Title\`, \`## Subtitle\`)
+- **Code blocks** — fenced code snippets extracted as child nodes with \`language\` and \`symbols\` fields
+
+**Edges:**
+- \`sibling\` — links consecutive sections within the same file
+- \`cross-file link\` — when markdown contains \`[text](./other.md)\`, links to the target file
+
+**Node IDs:** \`"guide.md"\` for file root, \`"guide.md::Setup"\` for sections, \`"guide.md::Setup::code-1"\` for code blocks.
+
+## CodeGraph
+
+Indexes TypeScript/JavaScript source code using tree-sitter AST parsing.
+
+**Nodes:**
+- **File** — represents the source file
+- **Symbols** — functions, classes, interfaces, types, variables, enums, methods
+
+**Edges:**
+- \`contains\` — file → symbol, class → method
+- \`imports\` — file → imported file (resolved by import resolver)
+- \`extends\` — class → base class
+- \`implements\` — class → interface
+
+**Node IDs:** \`"auth.ts"\` for file, \`"auth.ts::createUser"\` for top-level symbols, \`"auth.ts::AuthService::login"\` for methods.
+
+## FileIndexGraph
+
+Indexes **every file and directory** in the project, regardless of docs/code patterns.
+
+**Nodes:**
+- **Files** — with size, language, MIME type, modification date
+- **Directories** — with aggregate size and file count
+
+**Edges:**
+- \`contains\` — directory → child file or subdirectory
+
+## KnowledgeGraph
+
+A manually curated graph for notes, facts, and decisions. Not populated by indexing — created through tools or the UI.
+
+**Nodes:**
+- **Notes** — title, content, tags, embedding
+
+**Edges:**
+- Free-form typed relations: \`relates_to\`, \`depends_on\`, \`contradicts\`, etc.
+- **Cross-graph links** — can link to nodes in DocGraph, CodeGraph, FileIndexGraph, or TaskGraph via proxy nodes
+
+## TaskGraph
+
+Task management with kanban workflow. Also manually curated.
+
+**Nodes:**
+- **Tasks** — title, description, status, priority, tags, dueDate, estimate, assignee
+
+**Edges:**
+- \`subtask_of\` — parent-child tasks
+- \`blocks\` — dependency ordering
+- \`related_to\` — loose associations
+- **Cross-graph links** — can link to any other graph
+
+## SkillGraph
+
+Stores reusable recipes and procedures. Also manually curated.
+
+**Nodes:**
+- **Skills** — title, description, steps[], triggers[], source (\`user\`|\`learned\`), tags, usageCount, lastUsedAt, confidence, embedding
+
+**Edges:**
+- \`depends_on\` — skill requires another skill
+- \`related_to\` — loose associations
+- \`variant_of\` — alternative approaches to the same goal
+- **Cross-graph links** — can link to docs, code, files, knowledge, or tasks via proxy nodes
+
+**Node IDs:** slug from title (\`"add-rest-endpoint"\`), dedup with suffix (\`"add-rest-endpoint::2"\`).
+
+**Persistence:** \`skills.json\` in the graphMemory directory, mirrored to \`.skills/{id}/skill.md\`.
+
+## Cross-graph links
+
+KnowledgeGraph, TaskGraph, and SkillGraph can create edges to nodes in other graphs using **proxy nodes**. A proxy is a lightweight placeholder node (e.g., \`@docs::guide.md::Setup\`) that represents an external entity.
+
+This lets you create connections like:
+- Note "Auth architecture" → links to \`auth.ts::AuthService\` in CodeGraph
+- Task "Update auth docs" → links to \`guide.md\` in DocGraph
+- Note "Config format" → links to \`src/config.ts\` in FileIndexGraph
+- Skill "Add REST endpoint" → links to \`auth.ts::AuthService\` in CodeGraph
+`},{id:`cross-graph`,title:`Cross-Graph Links`,summary:`How to link notes and tasks to code, docs, and files via proxy nodes.`,category:`concept`,relatedTools:[`create_relation`,`delete_relation`,`list_relations`,`create_task_link`,`delete_task_link`,`create_skill_link`,`delete_skill_link`,`find_linked_notes`,`find_linked_tasks`,`find_linked_skills`],content:'# Cross-Graph Links\n\nOne of Graph Memory\'s most powerful features is the ability to **link knowledge across different graphs**. A note can reference a code symbol, a task can link to documentation, and everything stays connected.\n\n## How it works\n\nWhen you create a cross-graph link (via `create_relation`, `create_task_link`, or `create_skill_link`), the system creates a **proxy node** — a lightweight placeholder in the source graph that represents a node from another graph.\n\nProxy node IDs follow the format `@{graph}::{nodeId}`:\n- `@docs::guide.md::Setup` — a doc section\n- `@code::auth.ts::AuthService` — a code symbol\n- `@files::src/config.ts` — a file\n- `@tasks::fix-auth-bug` — a task\n- `@knowledge::auth-architecture` — a note\n- `@skills::add-rest-endpoint` — a skill\n\n## Creating cross-graph links\n\n### From Knowledge (notes)\n\nUse `create_relation` with the `targetGraph` parameter:\n\n```\ncreate_relation({\n  fromId: "auth-architecture",\n  toId: "auth.ts::AuthService",\n  kind: "documents",\n  targetGraph: "code"\n})\n```\n\nSupported target graphs: `docs`, `code`, `files`, `tasks`, `skills`\n\n### From Tasks\n\nUse `create_task_link` with the `targetGraph` parameter:\n\n```\ncreate_task_link({\n  taskId: "update-auth-docs",\n  targetId: "guide.md::Authentication",\n  kind: "relates_to",\n  targetGraph: "docs"\n})\n```\n\nSupported target graphs: `docs`, `code`, `files`, `knowledge`, `skills`\n\n### From Skills\n\nUse `create_skill_link` with the `targetGraph` parameter:\n\n```\ncreate_skill_link({\n  skillId: "add-rest-endpoint",\n  targetId: "api-guide.md::REST",\n  kind: "relates_to",\n  targetGraph: "docs"\n})\n```\n\nSupported target graphs: `docs`, `code`, `files`, `knowledge`, `tasks`\n\n## Discovering cross-graph links\n\n- `find_linked_notes` — find all notes linked to a specific external node\n- `find_linked_tasks` — find all tasks linked to a specific external node\n- `find_linked_skills` — find all skills linked to a specific external node\n- `list_relations` — list all relations for a note (including cross-graph)\n- `get_task` — returns enriched task data including all cross-graph links\n- `get_skill` — returns enriched skill data including all cross-graph links\n\n## Proxy cleanup\n\nProxy nodes are automatically cleaned up when:\n- The source note, task, or skill is deleted (orphaned proxies removed)\n- The relation/link is explicitly deleted\n- During indexing, if the target file no longer exists\n\n## Use cases\n\n- **Architecture decisions**: Create notes documenting why code is structured a certain way, link to the actual code symbols\n- **Task context**: Link tasks to the files and docs they affect for quick navigation\n- **Knowledge mapping**: Build a web of connections between concepts, implementations, and documentation\n- **Reusable skills**: Link skills to the code, docs, and tasks they relate to so they can be recalled in context\n'},{id:`mcp-setup`,title:`Connecting MCP Clients`,summary:`How to connect Claude Desktop, Cursor, Windsurf, and other MCP clients via HTTP.`,category:`guide`,relatedTools:[`get_context`],content:`# Connecting MCP Clients
+
+Graph Memory uses HTTP transport for MCP clients. Start the server, then connect your client to the MCP endpoint.
+
+## Setup
+
+Start the server first:
+
+\`\`\`bash
+graphmemory serve --config graph-memory.yaml
+\`\`\`
+
+Each project gets its own MCP endpoint at \`http://localhost:3000/mcp/{projectId}\`.
+
+### Claude Desktop
+
+Add via **Settings > Connectors** in the Claude Desktop app, enter the URL:
+
+\`\`\`
+http://localhost:3000/mcp/my-app
+\`\`\`
+
+### Claude Code
+
+Run in your project directory:
+
+\`\`\`bash
+claude mcp add --transport http --scope project graph-memory http://localhost:3000/mcp/my-app
+\`\`\`
+
+Or add to \`.mcp.json\` manually:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "graph-memory": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp/my-app"
+    }
+  }
+}
+\`\`\`
+
+### Cursor / Windsurf / Other clients
+
+Enter the MCP URL directly in your client's server configuration:
+
+\`\`\`
+http://localhost:3000/mcp/{projectId}
+\`\`\`
+
+## Docker
+
+\`\`\`bash
+docker run -d \\
+  --name graph-memory \\
+  -p 3000:3000 \\
+  -v $(pwd)/graph-memory.yaml:/data/config/graph-memory.yaml:ro \\
+  -v /path/to/my-app:/data/projects/my-app \\
+  -v graph-memory-models:/data/models \\
+  ghcr.io/graph-memory/graphmemory-server
+\`\`\`
+
+Then connect your MCP client to \`http://localhost:3000/mcp/my-app\`.
+
+To index once and exit without starting the server:
+
+\`\`\`bash
+# Docker
+docker run --rm \\
+  -v $(pwd)/graph-memory.yaml:/data/config/graph-memory.yaml:ro \\
+  -v /path/to/my-app:/data/projects/my-app \\
+  -v graph-memory-models:/data/models \\
+  ghcr.io/graph-memory/graphmemory-server index --config /data/config/graph-memory.yaml
+
+# Docker Compose (uses volumes defined in your compose file)
+docker compose run --rm graph-memory index --config /data/config/graph-memory.yaml
+\`\`\`
+
+## Troubleshooting
+
+**Model loading is slow on first start**: The embedding model (\`Xenova/bge-m3\`, ~560MB) is downloaded on first use. Subsequent starts use the cached model from \`~/.graph-memory/models/\` (or the configured \`modelsDir\`).
+
+**Port already in use**: Change the port in \`graph-memory.yaml\` under \`server.port\`, or stop the existing process.
+
+**Tools not showing up**: Make sure \`graphs.docs.include\` and/or \`graphs.code.include\` are set in your config (defaults: \`**/*.md\` and \`**/*.{js,ts,jsx,tsx}\`). If a graph is \`enabled: false\`, its tools won't be registered.
+
+**Config changes not taking effect**: Restart the server process to apply changes to \`graph-memory.yaml\`.
+`},{id:`configuration`,title:`Configuration Guide`,summary:`All graph-memory.yaml settings: server, projects, workspaces, embedding models, and patterns.`,category:`guide`,relatedTools:[],content:`# Configuration Guide
+
+All configuration is done via a single \`graph-memory.yaml\` file. This guide covers every setting and common patterns.
+
+## Basic structure
+
+\`\`\`yaml
+author:
+  name: "Your Name"
+  email: "you@example.com"
+
+server:
+  port: 3000
+
+projects:
+  my-app:
+    projectDir: "/path/to/my-app"
+\`\`\`
+
+The only required field is \`projects.*.projectDir\`. Everything else has sensible defaults (docs indexes \`**/*.md\`, code indexes \`**/*.{js,ts,jsx,tsx}\`).
+
+## Author settings
+
+The \`author\` block sets who is recorded as the creator/updater of notes, tasks, and skills. Written in git-style format (\`"Name <email>"\`) in mirror files.
+
+\`\`\`yaml
+author:
+  name: "Your Name"
+  email: "you@example.com"
+\`\`\`
+
+Can be overridden per project or per workspace.
+
+## Server settings
+
+| Field | Default | Description |
+|---|---|---|
+| \`host\` | \`127.0.0.1\` | Bind address. Use \`0.0.0.0\` for Docker or remote access |
+| \`port\` | \`3000\` | HTTP server port |
+| \`sessionTimeout\` | \`1800\` | Idle MCP session timeout in seconds (30 min) |
+| \`modelsDir\` | \`~/.graph-memory/models\` | Where embedding models are cached locally |
+| \`corsOrigins\` | — | Allowed CORS origins (array of strings) |
+| \`defaultAccess\` | \`rw\` | Default access for unknown users: \`deny\`, \`r\`, \`rw\` |
+| \`embedding.model\` | \`Xenova/bge-m3\` | Default model for all graphs |
+| \`embedding.remote\` | — | Remote embedding API URL (delegates instead of local model) |
+| \`embedding.remoteApiKey\` | — | API key for remote embedding |
+| \`embeddingApi.enabled\` | \`false\` | Expose local model via \`POST /api/embed\` |
+| \`embeddingApi.apiKey\` | — | API key for the embedding endpoint |
+
+## Project settings
+
+Each project needs at least \`projectDir\`:
+
+| Field | Default | Description |
+|---|---|---|
+| \`projectDir\` | **(required)** | Root directory to index |
+| \`graphMemory\` | \`.graph-memory\` | Where graph JSON files are stored (relative to projectDir) |
+| \`exclude\` | — | Additional glob to exclude (merged with server default \`**/node_modules/**,**/dist/**\`) |
+| \`chunkDepth\` | \`4\` | Max heading depth for markdown chunking |
+| \`embedding.maxChars\` | \`8000\` | Max characters fed to the embedding model per node (inherits: graph → project → workspace → server) |
+| \`access\` | — | Per-user access overrides for this project |
+
+> **Legacy fields:** \`docsPattern\` and \`codePattern\` have been removed. Use \`graphs.docs.include\` and \`graphs.code.include\` instead.
+
+### Per-graph configuration
+
+Each graph can be individually configured with \`enabled\`, \`include\`, \`exclude\`, \`embedding\`, and \`access\`:
+
+\`\`\`yaml
+projects:
+  my-app:
+    projectDir: "/path/to/my-app"
+    graphs:
+      docs:
+        enabled: true                      # Set false to disable this graph
+        include: "**/*.md"                 # Default — indexes all markdown files
+        exclude: "**/archive/**"           # Glob to exclude
+        model:                              # Full model config (whole object, no merge with parent)
+          name: "Xenova/bge-m3"
+          pooling: "cls"
+          normalize: true
+        access:                             # Per-graph access control
+          bob: rw
+      code:
+        enabled: true
+        include: "**/*.{js,ts,jsx,tsx}"    # Default — indexes all JS/TS files
+        model:
+          name: "Xenova/bge-base-en-v1.5"
+      knowledge:
+        access:
+          bob: rw                           # bob gets rw on knowledge
+      tasks:
+        enabled: true
+      files:
+        enabled: true
+      skills:
+        enabled: true
+\`\`\`
+
+Graphs without a specific \`embedding\` block use the project-level \`embedding\`, then the server-level \`embedding\`. The same model string is loaded only once, even if used by multiple graphs.
+
+Graph-level \`embedding\` is a complete block (first-defined-wins, no field-by-field merge with parent).
+
+## Workspaces
+
+Workspaces let multiple projects share the same knowledge, task, and skill graphs. Each project keeps its own docs, code, and file index graphs.
+
+\`\`\`yaml
+projects:
+  api-gateway:
+    projectDir: "./api-gateway"
+
+  catalog-service:
+    projectDir: "./catalog-service"
+
+workspaces:
+  backend:
+    projects: [api-gateway, catalog-service]
+    graphMemory: "./.workspace-backend"
+    mirrorDir: "./.workspace-backend"
+    author:
+      name: "Backend Team"
+      email: "backend@example.com"
+\`\`\`
+
+| Field | Description |
+|---|---|
+| \`projects\` | List of project IDs that share this workspace |
+| \`graphMemory\` | Where shared graph JSON files are stored |
+| \`mirrorDir\` | Where shared \`.notes/\`, \`.tasks/\`, \`.skills/\` mirror files are written |
+| \`author\` | Author for shared notes/tasks/skills (overrides root author) |
+| \`access\` | Per-user access for shared graphs (overrides \`server.access\`) |
+| \`embedding\` | Embedding config for shared graphs (overrides \`server.embedding\`) |
+
+## Users & authentication
+
+Define users for REST API and UI authentication.
+
+\`\`\`yaml
+users:
+  alice:
+    name: "Alice"
+    email: "alice@example.com"
+    apiKey: "mgm-key-abc123"
+    passwordHash: "$scrypt$16384$8$1$salt$hash"   # generated by: graphmemory users add
+
+server:
+  jwtSecret: "your-secret-key-here"    # required when users are defined
+  accessTokenTtl: "15m"                # JWT access token lifetime (default: 15m)
+  refreshTokenTtl: "7d"                # JWT refresh token lifetime (default: 7d)
+\`\`\`
+
+| Field | Description |
+|---|---|
+| \`name\` | Display name (used as createdBy/updatedBy in notes/tasks/skills) |
+| \`email\` | Email address (for UI login and mirror files) |
+| \`apiKey\` | Bearer token for programmatic API/MCP access |
+| \`passwordHash\` | Scrypt hash for UI password login (generate with \`graphmemory users add\`) |
+
+Two authentication methods:
+- **UI login**: email + password → JWT cookies (httpOnly, SameSite=Strict)
+- **API access**: \`Authorization: Bearer <apiKey>\` header
+
+When a user authenticates, their \`name\` and \`email\` are used as the author for mutations, overriding the root \`author\` config.
+
+## Access control
+
+Access control restricts who can read or write to projects, workspaces, and individual graphs. Access levels are \`deny\`, \`r\` (read-only), or \`rw\` (read-write).
+
+### Server-level defaults
+
+\`\`\`yaml
+server:
+  defaultAccess: rw            # Access for users not listed in access maps
+  access:                       # Server-level per-user access
+    alice: rw
+    bob: r
+\`\`\`
+
+\`defaultAccess\` applies to any authenticated user not explicitly listed. Default is \`rw\`.
+
+### Per-project access
+
+\`\`\`yaml
+projects:
+  my-app:
+    projectDir: "/path/to/my-app"
+    access:
+      bob: rw                   # bob gets rw on this project (overrides server.access)
+\`\`\`
+
+### Per-workspace access
+
+\`\`\`yaml
+workspaces:
+  backend:
+    projects: [api-gateway, catalog-service]
+    access:
+      alice: rw
+      bob: r                    # bob gets read-only on shared graphs
+\`\`\`
+
+### Per-graph access
+
+\`\`\`yaml
+projects:
+  my-app:
+    projectDir: "/path/to/my-app"
+    access:
+      bob: r                    # bob is read-only on this project...
+    graphs:
+      knowledge:
+        access:
+          bob: rw               # ...but gets rw on knowledge specifically
+\`\`\`
+
+### Resolution order
+
+Access is resolved from most specific to least specific:
+
+1. **Graph-level** \`access\` (e.g., \`graphs.knowledge.access.bob\`)
+2. **Project-level** \`access\` (e.g., \`projects.my-app.access.bob\`)
+3. **Workspace-level** \`access\` (for shared graphs)
+4. **Server-level** \`access\` (e.g., \`server.access.bob\`)
+5. **\`server.defaultAccess\`** (fallback, default \`rw\`)
+
+## Team directory setup
+
+For team environments, combine \`users\` with access control to give each team member appropriate permissions:
+
+\`\`\`yaml
+users:
+  alice:
+    name: "Alice (Tech Lead)"
+    email: "alice@company.com"
+    apiKey: "mgm-key-alice-secret"
+  bob:
+    name: "Bob (Developer)"
+    email: "bob@company.com"
+    apiKey: "mgm-key-bob-secret"
+  ci:
+    name: "CI Bot"
+    email: "ci@company.com"
+    apiKey: "mgm-key-ci-secret"
+
+server:
+  defaultAccess: deny            # Deny unknown users
+  access:
+    alice: rw
+    bob: rw
+    ci: r                        # CI can only read
+
+projects:
+  production-app:
+    projectDir: "/path/to/app"
+    access:
+      ci: r                      # CI can read project data
+\`\`\`
+
+## Embedding API configuration
+
+Expose the server's local embedding model as an HTTP API for other services or Graph Memory instances to use:
+
+\`\`\`yaml
+server:
+  embeddingApi:
+    enabled: true                # Enable POST /api/embed endpoint
+    apiKey: "emb-secret-key"     # API key for embedding requests (separate from user apiKeys)
+\`\`\`
+
+When enabled, \`POST /api/embed\` accepts \`{ text: "..." }\` or \`{ texts: ["..."] }\` and returns embeddings from the server's configured model. Authenticate with \`Authorization: Bearer <apiKey>\` using the \`embeddingApi.apiKey\`.
+
+## Remote embedding setup
+
+Instead of running the embedding model locally, delegate to a remote embedding API (e.g., another Graph Memory instance with \`embeddingApi\` enabled, or any compatible service):
+
+\`\`\`yaml
+server:
+  model:
+    name: "Xenova/bge-m3"
+  embedding:
+    remote: "http://gpu-server:3000/api/embed"
+    remoteApiKey: "emb-secret-key"
+\`\`\`
+
+When \`remote\` is set, the server sends embedding requests to the remote URL instead of loading the model locally. This is useful for:
+- Running on machines without GPU/enough RAM for the model
+- Sharing a single model instance across multiple Graph Memory servers
+- Using a dedicated embedding service
+
+The \`remote\` and \`remoteApiKey\` fields can be set at server, project, or graph level following the same embedding resolution order.
+
+## CORS origins
+
+Configure allowed origins for Cross-Origin Resource Sharing when the UI or API is accessed from a different domain:
+
+\`\`\`yaml
+server:
+  corsOrigins:
+    - "http://localhost:5173"       # Vite dev server
+    - "https://my-app.example.com"  # Production frontend
+\`\`\`
+
+When \`corsOrigins\` is not set, CORS headers are not added. Set this when the web UI or REST API is accessed from a different origin than the server.
+
+## Common patterns
+
+### Docs-only project (no code indexing)
+
+\`\`\`yaml
+projects:
+  wiki:
+    projectDir: "/path/to/wiki"
+    graphs:
+      docs:
+        include: "**/*.md"
+      code:
+        enabled: false
+\`\`\`
+
+### Code-only project (no docs)
+
+\`\`\`yaml
+projects:
+  library:
+    projectDir: "/path/to/library"
+    graphs:
+      docs:
+        enabled: false
+      code:
+        include: "src/**/*.ts"
+\`\`\`
+
+### Multiple exclude patterns
+
+\`\`\`yaml
+projects:
+  my-app:
+    projectDir: "/path/to/my-app"
+    exclude: "**/coverage/**,**/.git/**"
+\`\`\`
+
+### Docker deployment
+
+\`\`\`yaml
+server:
+  host: "0.0.0.0"
+  port: 3000
+  modelsDir: "/data/models"
+
+projects:
+  my-app:
+    projectDir: "/data/projects/my-app"
+\`\`\`
+
+## Applying config changes
+
+Restart the server process to apply changes to \`graph-memory.yaml\`.
+
+## Automatic re-indexing
+
+Each graph stores which embedding model was used. If you change the model in config, the graph is automatically discarded and re-indexed on next startup — no \`--reindex\` flag needed.
+`},{id:`docs-tools`,title:`Documentation Tools`,summary:`Search, browse, and navigate indexed markdown documentation.`,category:`guide`,relatedTools:[`list_topics`,`get_toc`,`search`,`get_node`,`search_topic_files`,`find_examples`,`search_snippets`,`list_snippets`,`explain_symbol`],content:'# Documentation Tools\n\nThe docs tools let you search, browse, and navigate your indexed markdown documentation. They\'re available when `graphs.docs.include` is configured in your project (default: `**/*.md`).\n\n## Tool overview\n\n| Tool | Purpose | When to use |\n|------|---------|-------------|\n| `list_topics` | List all indexed files | Get an overview of available documentation |\n| `get_toc` | Get table of contents for a file | Understand the structure of a specific document |\n| `search` | Semantic search across all docs | Find information without knowing which file has it |\n| `get_node` | Get full content of a section | Read the actual content after finding it via search |\n| `search_topic_files` | Search at file level | Find which files are most relevant to a topic |\n| `find_examples` | Find code blocks containing a specific symbol | Look up usage examples of a known function/class |\n| `search_snippets` | Semantic search across code blocks | Find code examples by description |\n| `list_snippets` | List code blocks in a file | Discover what code examples exist in docs |\n| `explain_symbol` | Get symbol\'s code block + surrounding docs context | Understand what a symbol does via documentation |\n| `cross_references` | Find symbol across code AND docs | Most comprehensive symbol lookup (see dedicated guide) |\n\n## Typical workflow\n\n### 1. Discover what\'s documented\n\nStart with `list_topics` to see all indexed markdown files. This gives you file IDs and titles.\n\n### 2. Search by meaning\n\nUse `search` with a natural language query. For example:\n- `"how to set up authentication"` — finds auth-related sections\n- `"database migration process"` — finds migration docs\n\nThe search returns scored results with `id`, `title`, `content` preview, and `score`.\n\n### 3. Read full content\n\nTake the `id` from search results and pass it to `get_node` to read the full section content, including any code blocks.\n\n### 4. Navigate structure\n\nUse `get_toc` with a file ID to see the full heading hierarchy. This helps when you want to explore a specific document top-to-bottom.\n\n## Code block tools\n\nWhen markdown is indexed, fenced code blocks (` ```lang ... ``` `) are extracted as child nodes. TypeScript/JavaScript blocks are additionally parsed with tree-sitter to extract top-level symbol names into the `symbols` field. This enables powerful code example discovery.\n\n### find_examples\n\nSearches the `symbols` array of code blocks for an exact symbol name match. Use this when you know the function/class name and want to find documentation examples.\n\nReturns: `{ id, fileId, language, symbols, content, parentId, parentTitle }`\n\n### search_snippets\n\nSemantic search across code block nodes only. Unlike `find_examples` (exact name), this works with natural language descriptions like "authentication example" or "database query".\n\nSupports a `language` filter to narrow results (e.g., `"typescript"`, `"python"`).\n\nReturns: `{ id, fileId, language, symbols, content, score }`\n\n### list_snippets\n\nLists code blocks with optional filters. Useful for exploring what examples exist in a specific file.\n\nFilters: `fileId` (specific file), `language` (e.g., "typescript"), `filter` (substring match on content).\n\nReturns: `{ id, fileId, language, symbols, preview }`\n\n### explain_symbol\n\nThe most context-rich symbol lookup in docs. For each match, returns both the **code block** and the **parent text section** that provides narrative context/explanation around the example.\n\nReturns: `{ codeBlock: { id, language, symbols, content }, explanation: { id, title, content } | null, fileId }`\n\n## Tool reference\n\n### list_topics\n\nList indexed documentation files with optional filtering.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `filter` | string | No | — | Case-insensitive substring to match against file paths |\n| `limit` | number | No | 20 | Maximum number of results |\n\n**Returns:** `[{ fileId, title, chunks }]`\n\n### get_toc\n\nReturn the table of contents (heading hierarchy) for a specific file.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fileId` | string | Yes | File path relative to docs dir, e.g. `"docs/auth.md"` |\n\n**Returns:** `[{ id, title, level }]` — `id` can be passed to `get_node`\n\n### search\n\nSemantic search over all indexed documentation sections.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language search query |\n| `topK` | number | No | 5 | Number of seed nodes (1–500) |\n| `bfsDepth` | number | No | 1 | Hops to follow cross-document links (0–10) |\n| `maxResults` | number | No | 20 | Maximum results (1–500) |\n| `minScore` | number | No | 0.5 | Minimum relevance score (0–1) |\n| `bfsDecay` | number | No | 0.8 | Score multiplier per graph hop (0–1) |\n| `searchMode` | string | No | `hybrid` | `hybrid`, `vector`, or `keyword` |\n\n**Returns:** `[{ id, fileId, title, content, level, score }]`\n\n### get_node\n\nReturn the full content of a specific doc node (file root or section).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `nodeId` | string | Yes | Node ID, e.g. `"docs/auth.md"` or `"docs/auth.md::Overview"` |\n\n**Returns:** `{ id, fileId, title, content, level, links, mtime }`\n\nNode IDs have two forms:\n- `"docs/auth.md"` — file root (intro text before first heading)\n- `"docs/auth.md::Overview"` — named section\n- `"docs/auth.md::Overview::code-1"` — code block within a section\n\n### search_topic_files\n\nSemantic search at file level (not section level). Faster than `search` when you just need to identify relevant files.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language search query |\n| `topK` | number | No | 10 | Maximum results |\n| `minScore` | number | No | 0.3 | Minimum relevance score (0–1) |\n\n**Returns:** `[{ fileId, title, chunks, score }]`\n\n### find_examples\n\nFind code blocks containing a specific symbol by exact name match.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbol` | string | Yes | — | Symbol name, e.g. `"createUser"`, `"UserService"` |\n| `limit` | number | No | 20 | Max results |\n\n**Returns:** `[{ id, fileId, language, symbols, content, parentId, parentTitle }]`\n\n### search_snippets\n\nSemantic search over code block nodes only.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language search query |\n| `topK` | number | No | 10 | Max results |\n| `minScore` | number | No | 0.3 | Minimum relevance score (0–1) |\n| `language` | string | No | — | Filter by language (e.g., `"typescript"`, `"python"`) |\n\n**Returns:** `[{ id, fileId, language, symbols, content, score }]`\n\n### list_snippets\n\nList code blocks with optional filters.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `fileId` | string | No | — | Filter by file |\n| `filter` | string | No | — | Substring match on content (case-insensitive) |\n| `language` | string | No | — | Filter by language |\n| `limit` | number | No | 20 | Max results |\n\n**Returns:** `[{ id, fileId, language, symbols, preview }]`\n\n### explain_symbol\n\nFind documentation that explains a symbol — returns both code example and surrounding text.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `symbol` | string | Yes | — | Symbol name, e.g. `"createUser"` |\n| `limit` | number | No | 10 | Max results |\n\n**Returns:** `[{ codeBlock: { id, language, symbols, content }, explanation: { id, title, content } | null, fileId }]`\n\n## Tips\n\n- Use `search` for broad exploration, `get_node` for targeted reading\n- `search_topic_files` is faster than `search` when you just need to know which file covers a topic\n- `find_examples` is for exact symbol name lookup; `search_snippets` is for natural language queries\n- `explain_symbol` gives the richest context — both the code example and the documentation around it\n- Lower `minScore` to 0.3 when exploring unfamiliar codebases\n- Set `bfsDepth: 0` in `search` for pure vector search without graph expansion\n- Set `bfsDepth: 2` to discover more loosely related content\n'},{id:`code-tools`,title:`Code Tools`,summary:`Search and navigate TypeScript/JavaScript source code symbols.`,category:`guide`,relatedTools:[`list_files`,`get_file_symbols`,`search_code`,`get_symbol`,`search_files`],content:'# Code Tools\n\nThe code tools let you search and navigate your indexed TypeScript/JavaScript source code. They\'re available when `graphs.code.include` is configured in your project (default: `**/*.{js,ts,jsx,tsx}`).\n\n## Tool overview\n\n| Tool | Purpose | When to use |\n|------|---------|-------------|\n| `list_files` | List all indexed source files | Get an overview of the codebase |\n| `get_file_symbols` | List symbols in a file | Explore a file\'s exports and structure |\n| `search_code` | Semantic search across code symbols | Find functions/classes by what they do |\n| `get_symbol` | Get full details of a symbol | Read signature, JSDoc, body, line numbers |\n| `search_files` | Search at file level | Find which files are relevant to a topic |\n\n## What gets indexed\n\nThe code parser uses tree-sitter to extract:\n- **Functions** — declarations, arrow functions, function expressions, ambient (`declare function`)\n- **Classes** — concrete and abstract, with constructors, methods, and fields as children\n- **Interfaces** — with method signatures and property signatures as children\n- **Types** and **Enums** — name, signature\n- **Variables** — exported and non-exported (`const`, `let`)\n- **Constructors** — extracted as `kind: \'constructor\'` (distinct from methods)\n- **Nested functions** — named functions inside function bodies (1 level deep)\n- **Generic types** — `Foo<T>` extracts base name `"Foo"` for extends/implements edges\n\nEdges capture structural relationships:\n- `contains` — file → symbol, class → method\n- `imports` — file → imported file (resolved by import resolver)\n- `extends` — class → base class\n- `implements` — class → interface\n\n## Node ID format\n\nCode graph node IDs follow a hierarchical pattern:\n- `"src/auth.ts"` — file node\n- `"src/auth.ts::createUser"` — top-level symbol in file\n- `"src/auth.ts::AuthService::login"` — method within a class\n\n## Typical workflow\n\n### 1. Find code by meaning\n\nUse `search_code` with a description of what you\'re looking for:\n- `"user authentication"` — finds auth-related functions and classes\n- `"parse markdown into sections"` — finds parsing logic\n\nUnlike grep, this finds code by **what it does**, not by exact text matches.\n\n### 2. Explore a symbol\n\nUse `get_symbol` with the symbol ID from search results. This returns the full picture: signature, JSDoc comment, body text, file location, line numbers, export status.\n\n### 3. Understand file structure\n\nUse `get_file_symbols` to see all symbols in a file — helpful for understanding module organization. The result includes `isExported` flag to distinguish public API from internal helpers.\n\n### 4. Discover relevant files\n\nUse `search_files` for a quick file-level search before diving into symbols. Lighter than `search_code` when you just need to identify which files to explore.\n\n### 5. Cross-reference with docs\n\nUse `cross_references` (requires both `graphs.docs.include` and `graphs.code.include`) to find everywhere a symbol appears — in both code definitions and documentation examples. See the dedicated guide for details.\n\n## Tool reference\n\n### list_files\n\nList indexed source files with optional filtering.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `filter` | string | No | — | Case-insensitive substring to match against file paths, e.g. `"graph"` or `"src/lib"` |\n| `limit` | number | No | 20 | Maximum number of results |\n\n**Returns:** `[{ fileId, symbolCount }]`\n\n### get_file_symbols\n\nReturn all symbols declared in a specific file.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fileId` | string | Yes | File path, e.g. `"src/lib/graph.ts"` |\n\n**Returns:** `[{ id, kind, name, signature, startLine, endLine, isExported }]`\n\nSymbol kinds: `function`, `class`, `interface`, `type`, `enum`, `variable`, `method`, `constructor`.\n\n### search_code\n\nSemantic search over code symbols. Matches against signatures and doc comments using vector similarity, then expands through graph edges.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language or code search query |\n| `topK` | number | No | 5 | Number of seed nodes (1–500) |\n| `bfsDepth` | number | No | 1 | Hops to follow graph edges (0–10). 0 = no expansion |\n| `maxResults` | number | No | 20 | Maximum results to return (1–500) |\n| `minScore` | number | No | 0.3 | Minimum relevance score (0–1) |\n| `bfsDecay` | number | No | 0.8 | Score multiplier per graph hop (0–1) |\n| `searchMode` | string | No | `hybrid` | `hybrid`, `vector`, or `keyword` |\n| `includeBody` | boolean | No | `false` | Include full body text in results |\n\n**Returns:** `[{ id, fileId, kind, name, signature, docComment, startLine, endLine, score, body? }]`\n\n### get_symbol\n\nReturn full details of a specific code symbol.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `nodeId` | string | Yes | Symbol ID, e.g. `"src/lib/graph.ts::updateFile"` or `"src/auth.ts::AuthService::login"` |\n\n**Returns:** `{ id, fileId, kind, name, signature, docComment, body, startLine, endLine, isExported }`\n\nThe `body` field contains the full implementation text. `docComment` contains the JSDoc comment if present.\n\n### search_files\n\nSemantic search at file level using file path embeddings.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language or path search query |\n| `topK` | number | No | 10 | Maximum results |\n| `minScore` | number | No | 0.3 | Minimum relevance score (0–1) |\n\n**Returns:** `[{ fileId, symbolCount, score }]`\n\n## Tips\n\n- `search_code` works best with descriptive queries about **what the code does**, not exact symbol names\n- For exact name lookup, use `get_symbol` directly with the node ID\n- `get_file_symbols` shows `isExported` — useful for distinguishing public API from internals\n- `search_files` is useful as a first step when exploring unfamiliar codebases\n- The `cross_references` tool (see dedicated guide) is the most comprehensive way to understand a symbol\n- BFS expansion in `search_code` follows `imports`, `contains`, and `extends` edges — set `bfsDepth: 2` to discover related modules\n- Code graph edges track `imports` for relative imports and tsconfig path aliases (`@/lib/foo`); external packages are skipped\n- BFS in `search_code` excludes reverse `imports` edges — popular utility files won\'t flood results\n'},{id:`knowledge-tools`,title:`Knowledge Tools`,summary:`Create and manage notes, facts, and decisions in a persistent knowledge graph.`,category:`guide`,relatedTools:[`create_note`,`update_note`,`delete_note`,`get_note`,`list_notes`,`search_notes`,`create_relation`,`delete_relation`,`list_relations`,`find_linked_notes`,`add_note_attachment`,`remove_note_attachment`],content:'# Knowledge Tools\n\nThe knowledge tools manage a persistent graph of **notes, facts, and decisions**. Unlike docs and code tools that index existing files, the knowledge graph is built manually — capturing information that lives in people\'s heads.\n\n## Why use a knowledge graph?\n\nCode and docs tell you **what** exists. The knowledge graph captures **why** — architectural decisions, domain knowledge, gotchas, context that doesn\'t belong in code comments.\n\nExamples:\n- "We use JWT instead of sessions because the mobile app needs stateless auth"\n- "The billing service has a 30-second timeout — don\'t chain more than 3 API calls"\n- "Users in the \'legacy\' tier have different rate limits, check `isLegacy` flag"\n\n## Tool overview\n\n| Tool | Purpose | Type |\n|------|---------|------|\n| `create_note` | Create a new note with title, content, tags | Mutation |\n| `update_note` | Update an existing note | Mutation |\n| `delete_note` | Remove a note and all its relations | Mutation |\n| `get_note` | Read a single note by ID | Read |\n| `list_notes` | List notes with optional filters | Read |\n| `search_notes` | Semantic search across notes | Read |\n| `create_relation` | Link a note to another note or external node | Mutation |\n| `delete_relation` | Remove a link | Mutation |\n| `list_relations` | List all relations for a note | Read |\n| `find_linked_notes` | Reverse lookup: find notes that link to an external node | Read |\n| `add_note_attachment` | Attach a file to a note | Mutation |\n| `remove_note_attachment` | Remove an attachment from a note | Mutation |\n\n> **Mutation tools** are serialized through a queue to prevent concurrent graph modifications.\n\n## Note ID generation\n\nNote IDs are slugified from the title:\n- "Auth Architecture" → `auth-architecture`\n- "JWT Token Format" → `jwt-token-format`\n\nDuplicate titles get a suffix: `auth-architecture::2`, `auth-architecture::3`.\n\n## Tool reference\n\n### create_note\n\nCreate a new note. Automatically embedded for semantic search.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `title` | string | Yes | Short title, e.g. `"Auth uses JWT tokens"` |\n| `content` | string | Yes | Full text content |\n| `tags` | string[] | No | Tags for filtering, e.g. `["architecture", "decision"]` |\n\n**Returns:** `{ noteId }` — the generated slug ID\n\n### update_note\n\nUpdate an existing note. Only provided fields change. Re-embeds automatically if title or content changes.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `noteId` | string | Yes | ID of the note to update |\n| `title` | string | No | New title |\n| `content` | string | No | New content |\n| `tags` | string[] | No | New tags (replaces existing array entirely) |\n\n**Returns:** `{ noteId, updated: true }`\n\n### delete_note\n\nDelete a note and all its connected edges (relations, cross-graph links). Orphaned proxy nodes are cleaned up automatically.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `noteId` | string | Yes | ID of the note to delete |\n\n**Returns:** `{ noteId, deleted: true }`\n\n### get_note\n\nReturn the full content of a note.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `noteId` | string | Yes | Note ID, e.g. `"auth-uses-jwt-tokens"` |\n\n**Returns:** `{ id, title, content, tags, createdAt, updatedAt }`\n\n### list_notes\n\nList notes with optional filtering. Sorted by most recently updated.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `filter` | string | No | — | Case-insensitive substring match on title or ID |\n| `tag` | string | No | — | Filter by tag (exact match, case-insensitive) |\n| `limit` | number | No | 20 | Maximum results |\n\n**Returns:** `[{ id, title, tags, updatedAt }]`\n\n### search_notes\n\nSemantic search over the knowledge graph with BFS expansion through note relations.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language search query |\n| `topK` | number | No | 5 | Number of seed nodes (1–500) |\n| `bfsDepth` | number | No | 1 | Hops to follow relations (0–10) |\n| `maxResults` | number | No | 20 | Maximum results (1–500) |\n| `minScore` | number | No | 0.5 | Minimum relevance score (0–1) |\n| `bfsDecay` | number | No | 0.8 | Score multiplier per hop (0–1) |\n| `searchMode` | string | No | `hybrid` | `hybrid`, `vector`, or `keyword` |\n\n**Returns:** `[{ id, title, content, tags, score }]`\n\n### create_relation\n\nCreate a directed edge from a note to another note or to an external graph node.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fromId` | string | Yes | Source note ID |\n| `toId` | string | Yes | Target note ID, or target node ID in external graph |\n| `kind` | string | Yes | Relation type: `"relates_to"`, `"depends_on"`, `"contradicts"`, `"supports"`, `"part_of"`, `"references"`, etc. |\n| `targetGraph` | `"docs"` \\| `"code"` \\| `"files"` \\| `"tasks"` \\| `"skills"` | No | Set to create a cross-graph link instead of note-to-note |\n\n**Returns:** `{ fromId, toId, kind, targetGraph, created: true }`\n\n**Cross-graph examples:**\n```\ncreate_relation({ fromId: "auth-arch", toId: "auth.ts::AuthService", kind: "documents", targetGraph: "code" })\ncreate_relation({ fromId: "config-note", toId: "src/config.ts", kind: "references", targetGraph: "files" })\ncreate_relation({ fromId: "api-decision", toId: "api-guide.md::Endpoints", kind: "explains", targetGraph: "docs" })\ncreate_relation({ fromId: "my-note", toId: "fix-auth-bug", kind: "tracks", targetGraph: "tasks" })\n```\n\n### delete_relation\n\nRemove a directed edge.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fromId` | string | Yes | Source note ID |\n| `toId` | string | Yes | Target note ID or external node ID |\n| `targetGraph` | `"docs"` \\| `"code"` \\| `"files"` \\| `"tasks"` \\| `"skills"` | No | Set when deleting a cross-graph link |\n\n**Returns:** `{ fromId, toId, targetGraph, deleted: true }`\n\n### list_relations\n\nList all relations (both incoming and outgoing) for a note. Cross-graph links include `targetGraph` field and resolve the real node ID (not the proxy ID).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `noteId` | string | Yes | Note ID to list relations for |\n\n**Returns:** `[{ fromId, toId, kind, targetGraph? }]`\n\n### find_linked_notes\n\nReverse lookup: given a node in an external graph, find all notes that link to it.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `targetId` | string | Yes | Target node ID in the external graph, e.g. `"src/config.ts"`, `"auth.ts::login"`, `"api.md::Setup"` |\n| `targetGraph` | `"docs"` \\| `"code"` \\| `"files"` \\| `"tasks"` \\| `"skills"` | Yes | Which graph the target belongs to |\n| `kind` | string | No | Filter by relation kind. If omitted, returns all relations |\n\n**Returns:** `[{ noteId, title, kind, tags }]`\n\n**Use case:** When working on a code file, call `find_linked_notes({ targetId: "src/auth.ts", targetGraph: "code" })` to discover what knowledge notes reference that file.\n\n### add_note_attachment\n\nAttach a file to a note. The file is copied into the note\'s directory (`.notes/{noteId}/`).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `noteId` | string | Yes | Note ID to attach the file to |\n| `filePath` | string | Yes | Absolute path to the file on disk |\n\n**Returns:** `{ noteId, attachment: { filename, mimeType, size } }`\n\n### remove_note_attachment\n\nRemove an attachment from a note. Deletes the file from disk.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `noteId` | string | Yes | Note ID |\n| `filename` | string | Yes | Filename of the attachment to remove |\n\n**Returns:** `{ noteId, filename, deleted: true }`\n\n## Tips\n\n- Use tags consistently for easy filtering (e.g., `decision`, `gotcha`, `todo`, `architecture`)\n- Link notes to the code they describe — this creates a navigable knowledge web\n- `find_linked_notes` is useful to discover what knowledge exists about a specific code symbol or file\n- Notes persist across server restarts (saved as `knowledge.json`)\n- The `kind` field on relations is free-form — use whatever makes sense for your domain\n- `update_note` with `tags` replaces the entire array — include all tags you want to keep\n- `search_notes` with `bfsDepth: 2` will traverse through related notes to find loosely connected knowledge\n- Notes support file attachments — attach images, logs, or any file via `add_note_attachment`\n- Attachments are stored in `.notes/{noteId}/` alongside the note\'s markdown file\n- When the knowledge graph is configured as `readonly: true`, mutation tools (create, update, delete) are hidden from MCP clients and REST mutation endpoints return 403. The UI hides write buttons accordingly.\n'},{id:`task-tools`,title:`Task Tools`,summary:`Kanban task management with priorities, dependencies, and cross-graph links.`,category:`guide`,relatedTools:[`create_task`,`update_task`,`delete_task`,`get_task`,`list_tasks`,`search_tasks`,`move_task`,`link_task`,`create_task_link`,`delete_task_link`,`find_linked_tasks`,`add_task_attachment`,`remove_task_attachment`],content:'# Task Tools\n\nThe task tools provide a full **kanban-style task management** system within Graph Memory. Tasks have status, priority, due dates, estimates, and can link to any other graph.\n\n## Why tasks in Graph Memory?\n\nTasks here are tightly integrated with your project\'s knowledge graph:\n- Link a task to the code files it affects\n- Link a task to documentation that needs updating\n- Link a task to knowledge notes for context\n- Track dependencies between tasks (subtasks, blockers)\n\n## Tool overview\n\n| Tool | Purpose | Type |\n|------|---------|------|\n| `create_task` | Create a task | Mutation |\n| `update_task` | Modify task fields | Mutation |\n| `delete_task` | Remove a task and all its edges | Mutation |\n| `get_task` | Read a task with all relations | Read |\n| `list_tasks` | List tasks with filters | Read |\n| `search_tasks` | Semantic search across tasks | Read |\n| `move_task` | Change task status (kanban move) | Mutation |\n| `link_task` | Create task-to-task relation | Mutation |\n| `create_task_link` | Link task to external graph node | Mutation |\n| `delete_task_link` | Remove cross-graph link | Mutation |\n| `find_linked_tasks` | Reverse lookup: find tasks linked to an external node | Read |\n| `add_task_attachment` | Attach a file to a task | Mutation |\n| `remove_task_attachment` | Remove an attachment from a task | Mutation |\n\n> **Mutation tools** are serialized through a queue to prevent concurrent graph modifications.\n\n## Task properties\n\n| Property | Type | Values / Format | Notes |\n|----------|------|-----------------|-------|\n| `title` | string | Free text | Becomes slug ID |\n| `description` | string | Markdown | Full task description |\n| `status` | enum | `backlog`, `todo`, `in_progress`, `review`, `done`, `cancelled` | Use `move_task` to change |\n| `priority` | enum | `critical`, `high`, `medium`, `low` | Affects sort order |\n| `tags` | string[] | Free-form | For filtering |\n| `dueDate` | number | Unix timestamp in milliseconds | Optional deadline |\n| `estimate` | number | Hours | Optional effort estimate |\n| `assignee` | string \\| null | Team member ID | Optional assignee from `users:` config |\n| `completedAt` | number | Unix timestamp (auto-managed) | Set on done/cancelled, cleared on reopen |\n| `createdAt` | number | Unix timestamp (auto) | Set at creation |\n| `updatedAt` | number | Unix timestamp (auto) | Updated on every change |\n\n## Task ID generation\n\nLike notes, task IDs are slugified from the title:\n- "Fix auth redirect loop" → `fix-auth-redirect-loop`\n- Duplicates get suffixes: `fix-auth-redirect-loop::2`\n\n## Tool reference\n\n### create_task\n\nCreate a new task. Automatically embedded for semantic search.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `title` | string | Yes | — | Short title, e.g. `"Fix auth redirect loop"` |\n| `description` | string | Yes | — | Full description (markdown) |\n| `priority` | enum | Yes | — | `"critical"`, `"high"`, `"medium"`, `"low"` |\n| `status` | enum | No | `"backlog"` | `"backlog"`, `"todo"`, `"in_progress"`, `"review"`, `"done"`, `"cancelled"` |\n| `tags` | string[] | No | `[]` | Tags for filtering |\n| `dueDate` | number | No | — | Due date as Unix timestamp in milliseconds |\n| `estimate` | number | No | — | Estimated effort in hours |\n| `assignee` | string | No | — | Team member ID to assign the task to |\n\n**Returns:** `{ taskId }`\n\n### update_task\n\nUpdate an existing task. Only provided fields change. Re-embeds if title or description changes. Status changes auto-manage `completedAt`.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Task ID to update |\n| `title` | string | No | New title |\n| `description` | string | No | New description |\n| `status` | enum | No | New status |\n| `priority` | enum | No | New priority |\n| `tags` | string[] | No | Replace tags array (include all you want to keep) |\n| `dueDate` | number \\| null | No | New due date (ms timestamp), or `null` to clear |\n| `estimate` | number \\| null | No | New estimate (hours), or `null` to clear |\n| `assignee` | string \\| null | No | Team member ID to assign, or `null` to unassign |\n\n**Returns:** `{ taskId, updated: true }`\n\n> Use `move_task` for a simpler status-only change — it\'s more explicit about `completedAt` management.\n\n### delete_task\n\nDelete a task and all its edges (relations + cross-graph links). Orphaned proxy nodes cleaned up automatically. **Irreversible.**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Task ID to delete |\n\n**Returns:** `{ taskId, deleted: true }`\n\n### get_task\n\nReturn full task details including all relations. This is the most complete view of a task.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Task ID to retrieve |\n\n**Returns:**\n```\n{\n  id, title, description, status, priority, tags, assignee,\n  dueDate, estimate, completedAt, createdAt, updatedAt,\n  subtasks: [{ id, title, status }],\n  blockedBy: [{ id, title, status }],\n  blocks: [{ id, title, status }],\n  related: [{ id, title, status }]\n}\n```\n\nThe `subtasks`, `blockedBy`, `blocks`, and `related` arrays are automatically populated from task-to-task edges.\n\n### list_tasks\n\nList tasks with optional filters. Sorted by priority (critical → low) then due date (earliest first, nulls last).\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `status` | enum | No | — | Filter by status |\n| `priority` | enum | No | — | Filter by priority |\n| `tag` | string | No | — | Filter by tag (exact match, case-insensitive) |\n| `filter` | string | No | — | Substring match on title or ID |\n| `assignee` | string | No | — | Filter by assignee (team member ID) |\n| `limit` | number | No | 50 | Maximum results |\n\n**Returns:** `[{ id, title, description, status, priority, tags, dueDate, estimate, assignee, completedAt, createdAt, updatedAt }]`\n\n### search_tasks\n\nSemantic search over the task graph with BFS expansion.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Natural language search query |\n| `topK` | number | No | 5 | Seed nodes (1–500) |\n| `bfsDepth` | number | No | 1 | Hops to follow relations (0–10) |\n| `maxResults` | number | No | 20 | Maximum results (1–500) |\n| `minScore` | number | No | 0.5 | Minimum relevance score (0–1) |\n| `bfsDecay` | number | No | 0.8 | Score multiplier per hop (0–1) |\n| `searchMode` | string | No | `hybrid` | `hybrid`, `vector`, or `keyword` |\n\n**Returns:** `[{ id, title, description, status, priority, tags, score }]`\n\n### move_task\n\nChange task status. The preferred way to move tasks through the kanban workflow.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Task ID to move |\n| `status` | enum | Yes | New status: `"backlog"`, `"todo"`, `"in_progress"`, `"review"`, `"done"`, `"cancelled"` |\n\n**Returns:** `{ taskId, status, completedAt }`\n\n**Automatic behavior:**\n- Moving to `done` or `cancelled` → sets `completedAt` to current time\n- Moving from `done`/`cancelled` to any other status → clears `completedAt`\n\n### link_task\n\nCreate a directed relation between two tasks.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fromId` | string | Yes | Source task ID |\n| `toId` | string | Yes | Target task ID |\n| `kind` | enum | Yes | `"subtask_of"`, `"blocks"`, `"related_to"` |\n\n**Returns:** `{ fromId, toId, kind, created: true }`\n\n**Semantics:**\n- `subtask_of` — `fromId` is a subtask of `toId` (child → parent)\n- `blocks` — `fromId` blocks `toId` (blocker → blocked task)\n- `related_to` — free association between tasks\n\n### create_task_link\n\nLink a task to a node in another graph (docs, code, files, or knowledge).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Source task ID |\n| `targetId` | string | Yes | Target node ID in the external graph |\n| `targetGraph` | enum | Yes | `"docs"`, `"code"`, `"files"`, `"knowledge"`, `"skills"` |\n| `kind` | string | Yes | Relation type: `"references"`, `"fixes"`, `"implements"`, `"documents"`, etc. |\n\n**Returns:** `{ taskId, targetId, targetGraph, kind, created: true }`\n\n**Examples:**\n```\ncreate_task_link({ taskId: "fix-auth", targetId: "src/auth.ts::login", targetGraph: "code", kind: "fixes" })\ncreate_task_link({ taskId: "update-docs", targetId: "guide.md::Authentication", targetGraph: "docs", kind: "updates" })\ncreate_task_link({ taskId: "review-config", targetId: "src/config.ts", targetGraph: "files", kind: "references" })\ncreate_task_link({ taskId: "implement-arch", targetId: "auth-architecture", targetGraph: "knowledge", kind: "implements" })\n```\n\n### delete_task_link\n\nRemove a cross-graph link from a task. Orphaned proxy nodes cleaned up automatically.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Source task ID |\n| `targetId` | string | Yes | Target node ID in the external graph |\n| `targetGraph` | enum | Yes | `"docs"`, `"code"`, `"files"`, `"knowledge"`, `"skills"` |\n\n**Returns:** `{ taskId, targetId, targetGraph, deleted: true }`\n\n### find_linked_tasks\n\nReverse lookup: given a node in an external graph, find all tasks that link to it.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `targetId` | string | Yes | Target node ID, e.g. `"src/auth.ts"`, `"guide.md::Setup"`, `"my-note"` |\n| `targetGraph` | enum | Yes | `"docs"`, `"code"`, `"files"`, `"knowledge"`, `"skills"` |\n| `kind` | string | No | Filter by relation kind. Omit for all relations |\n\n**Returns:** `[{ taskId, title, kind, status, priority, tags }]`\n\n**Use case:** When working on a file, call `find_linked_tasks({ targetId: "src/auth.ts", targetGraph: "code" })` to see all tasks related to that file.\n\n### add_task_attachment\n\nAttach a file to a task. The file is copied into the task\'s directory (`.tasks/{taskId}/`).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Task ID to attach the file to |\n| `filePath` | string | Yes | Absolute path to the file on disk |\n\n**Returns:** `{ taskId, attachment: { filename, mimeType, size } }`\n\n### remove_task_attachment\n\nRemove an attachment from a task. Deletes the file from disk.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `taskId` | string | Yes | Task ID |\n| `filename` | string | Yes | Filename of the attachment to remove |\n\n**Returns:** `{ taskId, filename, deleted: true }`\n\n## Kanban board UI\n\nThe Tasks page provides a visual kanban board with these features:\n\n- **Column visibility** — toggle which status columns are shown via the column icon in the top bar; saved in localStorage\n- **Drag-and-drop** — drag task cards between columns to change status; drop-zone highlights on hover\n- **Inline task creation** — click "+" in a column header to quickly create a task in that status\n- **Filter bar** — search tasks by text, filter by priority or tag\n- **Due date indicators** — overdue tasks show a red badge, approaching deadlines (≤3 days) show yellow\n- **Estimate badges** — tasks with estimates show hours on the card\n- **Quick actions** — hover a card to see edit and delete buttons\n- **Scrollable columns** — columns scroll independently when content overflows\n\n## Tips\n\n- Use `move_task` instead of `update_task` for status changes — it explicitly handles `completedAt`\n- `get_task` returns the richest data — includes subtasks, blockers, and related tasks\n- `list_tasks` is sorted by priority then due date — critical overdue tasks appear first\n- Link tasks to code files they affect — makes it easy to find related tasks when working on code\n- Use `search_tasks` to find tasks by meaning, not just title keywords\n- `update_task` with `dueDate: null` or `estimate: null` clears those fields\n- `update_task` with `tags` replaces the entire array — include all tags you want to keep\n- Task-to-task `kind` values are a fixed enum (`subtask_of`, `blocks`, `related_to`), unlike knowledge relations which are free-form\n- Tasks support file attachments — attach screenshots, logs, or any file via `add_task_attachment`\n- Attachments are stored in `.tasks/{taskId}/` alongside the task\'s markdown file\n- When the task graph is configured as `readonly: true`, mutation tools (create, update, delete, move) are hidden from MCP clients and REST mutation endpoints return 403. The UI hides write buttons and disables drag-and-drop on the kanban board.\n'},{id:`skill-tools`,title:`Skill Tools`,summary:`Create and manage reusable skills, recipes, and procedures with triggers and usage tracking.`,category:`guide`,relatedTools:[`create_skill`,`update_skill`,`delete_skill`,`get_skill`,`list_skills`,`search_skills`,`link_skill`,`create_skill_link`,`delete_skill_link`,`find_linked_skills`,`add_skill_attachment`,`remove_skill_attachment`,`recall_skills`,`bump_skill_usage`],content:'# Skill Tools\n\nThe skill tools provide a **recipe/procedure management** system within Graph Memory. Skills capture reusable knowledge — step-by-step procedures, patterns, and best practices — with triggers, usage tracking, and cross-graph links.\n\n## Why skills in Graph Memory?\n\nSkills here are tightly integrated with your project\'s knowledge graph:\n- Link a skill to the code files it applies to\n- Link a skill to documentation that describes the pattern\n- Link a skill to knowledge notes for context\n- Link a skill to tasks that use the procedure\n- Track dependencies and variants between skills\n\n## Tool overview\n\n| Tool | Purpose | Type |\n|------|---------|------|\n| `create_skill` | Create a skill with steps, triggers, and metadata | Mutation |\n| `update_skill` | Modify skill fields (partial update) | Mutation |\n| `delete_skill` | Remove a skill and all its edges | Mutation |\n| `get_skill` | Read a skill with all relations | Read |\n| `list_skills` | List skills with filters | Read |\n| `search_skills` | Semantic search across skills | Read |\n| `link_skill` | Create skill-to-skill relation | Mutation |\n| `create_skill_link` | Link skill to external graph node | Mutation |\n| `delete_skill_link` | Remove cross-graph link | Mutation |\n| `find_linked_skills` | Reverse lookup: find skills linked to an external node | Read |\n| `add_skill_attachment` | Attach a file to a skill | Mutation |\n| `remove_skill_attachment` | Remove an attachment from a skill | Mutation |\n| `recall_skills` | Recall relevant skills for a task context | Read |\n| `bump_skill_usage` | Increment usage counter + set lastUsedAt | Mutation |\n\n> **Mutation tools** are serialized through a queue to prevent concurrent graph modifications.\n\n## Skill properties\n\n| Property | Type | Values / Format | Notes |\n|----------|------|-----------------|-------|\n| `title` | string | Free text | Becomes slug ID |\n| `description` | string | Markdown | Full skill description |\n| `steps` | string[] | Ordered list | Step-by-step procedure |\n| `triggers` | string[] | Free-form | When to apply this skill |\n| `source` | enum | `user`, `learned` | How the skill was created |\n| `tags` | string[] | Free-form | For filtering |\n| `usageCount` | number | Auto-managed | Incremented by `bump_skill_usage` |\n| `lastUsedAt` | number | Unix timestamp (auto) | Set by `bump_skill_usage` |\n| `createdAt` | number | Unix timestamp (auto) | Set at creation |\n| `updatedAt` | number | Unix timestamp (auto) | Updated on every change |\n\n## Skill ID generation\n\nLike notes and tasks, skill IDs are slugified from the title:\n- "Add REST Endpoint" -> `add-rest-endpoint`\n- Duplicates get suffixes: `add-rest-endpoint::2`\n\n## Tool reference\n\n### create_skill\n\nCreate a new skill. Automatically embedded for semantic search.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `title` | string | Yes | -- | Short title, e.g. `"Add REST Endpoint"` |\n| `description` | string | Yes | -- | Full description (markdown) |\n| `steps` | string[] | No | `[]` | Ordered steps of the procedure |\n| `triggers` | string[] | No | `[]` | When this skill should be applied |\n| `source` | enum | No | `"user"` | `"user"`, `"learned"` |\n| `tags` | string[] | No | `[]` | Tags for filtering |\n\n**Returns:** `{ skillId }`\n\n### update_skill\n\nUpdate an existing skill. Only provided fields change. Re-embeds if title, description, or triggers change.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Skill ID to update |\n| `title` | string | No | New title |\n| `description` | string | No | New description |\n| `steps` | string[] | No | Replace steps array |\n| `triggers` | string[] | No | Replace triggers array |\n| `source` | enum | No | New source |\n| `tags` | string[] | No | Replace tags array (include all you want to keep) |\n\n**Returns:** `{ skillId, updated: true }`\n\n### delete_skill\n\nDelete a skill and all its edges (relations + cross-graph links). Orphaned proxy nodes cleaned up automatically. **Irreversible.**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Skill ID to delete |\n\n**Returns:** `{ skillId, deleted: true }`\n\n### get_skill\n\nReturn full skill details including all relations. This is the most complete view of a skill.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Skill ID to retrieve |\n\n**Returns:**\n```\n{\n  id, title, description, steps, triggers, source, tags,\n  usageCount, lastUsedAt, createdAt, updatedAt,\n  dependsOn: [{ id, title }],\n  dependedBy: [{ id, title }],\n  related: [{ id, title }],\n  variants: [{ id, title }]\n}\n```\n\nThe `dependsOn`, `dependedBy`, `related`, and `variants` arrays are automatically populated from skill-to-skill edges.\n\n### list_skills\n\nList skills with optional filters. Sorted by usage count (most used first).\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `source` | enum | No | -- | Filter by source (`user`, `learned`) |\n| `tag` | string | No | -- | Filter by tag (exact match, case-insensitive) |\n| `filter` | string | No | -- | Substring match on title or ID |\n| `limit` | number | No | 50 | Maximum results |\n\n**Returns:** `[{ id, title, description, steps, triggers, source, tags, usageCount, lastUsedAt, createdAt, updatedAt }]`\n\n### search_skills\n\nSemantic search over the skill graph with BFS expansion.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | -- | Natural language search query |\n| `topK` | number | No | 5 | Seed nodes (1–500) |\n| `bfsDepth` | number | No | 1 | Hops to follow relations (0–10) |\n| `maxResults` | number | No | 20 | Maximum results (1–500) |\n| `minScore` | number | No | 0.5 | Minimum relevance score (0–1) |\n| `bfsDecay` | number | No | 0.8 | Score multiplier per hop (0–1) |\n| `searchMode` | string | No | `hybrid` | `hybrid`, `vector`, or `keyword` |\n\n**Returns:** `[{ id, title, description, steps, triggers, source, tags, score }]`\n\n### recall_skills\n\nRecall relevant skills for a task context. Uses a lower default `minScore` (0.3) for higher recall.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `context` | string | Yes | -- | Description of the current task or context to match skills against |\n| `topK` | number | No | 5 | How many top similar skills to use as seeds |\n| `minScore` | number | No | 0.3 | Minimum relevance score (0-1) |\n\n**Returns:** `[{ id, title, description, steps, triggers, source, tags, score, usageCount }]`\n\n### bump_skill_usage\n\nRecord that a skill was used. Increments `usageCount` and sets `lastUsedAt` to the current time.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Skill ID to bump |\n\n**Returns:** `{ skillId, usageCount, lastUsedAt }`\n\n### link_skill\n\nCreate a directed relation between two skills.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fromId` | string | Yes | Source skill ID |\n| `toId` | string | Yes | Target skill ID |\n| `kind` | enum | Yes | `"depends_on"`, `"related_to"`, `"variant_of"` |\n\n**Returns:** `{ fromId, toId, kind, created: true }`\n\n**Semantics:**\n- `depends_on` -- `fromId` depends on `toId` (prerequisite)\n- `related_to` -- free association between skills\n- `variant_of` -- `fromId` is a variation of `toId`\n\n### create_skill_link\n\nLink a skill to a node in another graph (docs, code, files, knowledge, or tasks).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Source skill ID |\n| `targetId` | string | Yes | Target node ID in the external graph |\n| `targetGraph` | enum | Yes | `"docs"`, `"code"`, `"files"`, `"knowledge"`, `"tasks"` |\n| `kind` | string | Yes | Relation type: `"applies_to"`, `"documented_in"`, `"used_by"`, etc. |\n\n**Returns:** `{ skillId, targetId, targetGraph, kind, created: true }`\n\n**Examples:**\n```\ncreate_skill_link({ skillId: "add-rest-endpoint", targetId: "src/routes/index.ts", targetGraph: "code", kind: "applies_to" })\ncreate_skill_link({ skillId: "add-rest-endpoint", targetId: "guide.md::REST API", targetGraph: "docs", kind: "documented_in" })\ncreate_skill_link({ skillId: "add-rest-endpoint", targetId: "implement-api", targetGraph: "tasks", kind: "used_by" })\n```\n\n### delete_skill_link\n\nRemove a cross-graph link from a skill. Orphaned proxy nodes cleaned up automatically.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Source skill ID |\n| `targetId` | string | Yes | Target node ID in the external graph |\n| `targetGraph` | enum | Yes | `"docs"`, `"code"`, `"files"`, `"knowledge"`, `"tasks"` |\n\n**Returns:** `{ skillId, targetId, targetGraph, deleted: true }`\n\n### find_linked_skills\n\nReverse lookup: given a node in an external graph, find all skills that link to it.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `targetId` | string | Yes | Target node ID, e.g. `"src/auth.ts"`, `"guide.md::Setup"`, `"my-task"` |\n| `targetGraph` | enum | Yes | `"docs"`, `"code"`, `"files"`, `"knowledge"`, `"tasks"` |\n| `kind` | string | No | Filter by relation kind. Omit for all relations |\n\n**Returns:** `[{ skillId, title, kind, source, tags }]`\n\n**Use case:** When working on a file, call `find_linked_skills({ targetId: "src/routes/index.ts", targetGraph: "code" })` to see all skills related to that file.\n\n### add_skill_attachment\n\nAttach a file to a skill. The file is copied into the skill\'s directory (`.skills/{skillId}/`).\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Skill ID to attach the file to |\n| `filePath` | string | Yes | Absolute path to the file on disk |\n\n**Returns:** `{ skillId, attachment: { filename, mimeType, size } }`\n\n### remove_skill_attachment\n\nRemove an attachment from a skill. Deletes the file from disk.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `skillId` | string | Yes | Skill ID |\n| `filename` | string | Yes | Filename of the attachment to remove |\n\n**Returns:** `{ skillId, filename, deleted: true }`\n\n## Tips\n\n- Use `recall_skills` when starting a task to find relevant procedures -- it uses a lower threshold for better recall\n- Call `bump_skill_usage` after applying a skill to track which skills are most useful\n- Skills with `source: "learned"` are typically created by AI agents that discover patterns\n- Skills with `source: "user"` are created by humans documenting their procedures\n- Link skills to code files they apply to -- makes it easy to find relevant skills when working on code\n- Use `search_skills` to find skills by meaning, not just title keywords\n- `update_skill` with `tags` replaces the entire array -- include all tags you want to keep\n- Skill-to-skill `kind` values are a fixed enum (`depends_on`, `related_to`, `variant_of`)\n- Skills support file attachments -- attach templates, examples, or reference files via `add_skill_attachment`\n- Attachments are stored in `.skills/{skillId}/` alongside the skill\'s markdown file\n- When the skill graph is configured as `readonly: true`, mutation tools (create, update, delete) are hidden from MCP clients and REST mutation endpoints return 403. The UI hides write buttons accordingly.\n'},{id:`files-tools`,title:`File Index Tools`,summary:`Browse and search metadata for every file and directory in your project.`,category:`guide`,relatedTools:[`list_all_files`,`search_all_files`,`get_file_info`],content:'# File Index Tools\n\nThe file index tools provide access to metadata about **every file and directory** in your project. Unlike docs and code tools which only index pattern-matched files, the file index covers the entire project tree.\n\n## Tool overview\n\n| Tool | Purpose | When to use |\n|------|---------|-------------|\n| `list_all_files` | List files/directories with filters | Browse project structure, filter by extension/language |\n| `search_all_files` | Semantic search by file path | Find files by what they might contain |\n| `get_file_info` | Get metadata for a specific path | Check size, language, modification date |\n\n## What gets indexed\n\nFor every file in the project directory:\n- **Path** (relative to project root)\n- **File name** and **extension**\n- **Size** in bytes\n- **Language** (detected from extension: `.ts` → TypeScript, `.md` → Markdown, `.json` → JSON, etc.)\n- **MIME type** (e.g., `application/json`, `text/markdown`, `image/png`)\n- **Modification time** (`mtime`)\n\nFor directories:\n- **Aggregate size** (sum of all contained files)\n- **File count** (total files in subtree)\n- Directory → child edges (`contains`)\n\n## Browsing vs searching\n\n### Directory browsing\n\n`list_all_files` with the `directory` parameter returns **immediate children** (files + subdirectories) of that directory. This is how you browse the project tree:\n\n```\nlist_all_files({ directory: "." })           → root contents\nlist_all_files({ directory: "src" })         → src/ contents\nlist_all_files({ directory: "src/api" })     → src/api/ contents\n```\n\nWithout `directory`, it returns all files matching filters (flat list, no directories).\n\n### File search\n\n`search_all_files` embeds file paths for semantic search. You can search by:\n- Partial paths: `"config"` finds configuration files\n- Concepts: `"authentication"` finds files in auth-related directories\n- File types: `"typescript source"` finds `.ts` files\n\nThe `minScore` default is **0.3** (lower than node search) because file path embeddings are less semantically rich than content embeddings.\n\n## Tool reference\n\n### list_all_files\n\nList project files and directories with optional filters.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `directory` | string | No | — | List immediate children of this directory (e.g. `"."`, `"src/lib"`). Without this, returns all files matching filters |\n| `extension` | string | No | — | Filter by extension (e.g. `".ts"`, `".md"`, `".png"`) |\n| `language` | string | No | — | Filter by detected language (e.g. `"typescript"`, `"markdown"`, `"json"`) |\n| `filter` | string | No | — | Substring match on file path (case-insensitive) |\n| `limit` | number | No | 50 | Maximum results |\n\n**Returns:** `[{ filePath, kind, fileName, extension, language, mimeType, size, fileCount }]`\n\n- `kind` is `"file"` or `"directory"`\n- `fileCount` is present for directories (number of files in subtree)\n- `language` and `mimeType` are present for files\n\n**Behavior differences:**\n- With `directory` set: returns both files and subdirectories (immediate children only)\n- Without `directory`: returns only files (no directories), across the entire project\n\n### search_all_files\n\nSemantic search over file nodes by path embedding. Searches files only (not directories).\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Search query (natural language or path fragment) |\n| `topK` | number | No | 10 | Maximum results |\n| `minScore` | number | No | 0.3 | Minimum cosine similarity score (0–1) |\n\n**Returns:** `[{ filePath, fileName, extension, language, size, score }]`\n\n### get_file_info\n\nGet full metadata for a specific file or directory. Use `"."` for the project root.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `filePath` | string | Yes | Relative file or directory path (e.g. `"src/lib/config.ts"`, `"src/lib"`, `"."`) |\n\n**Returns for files:**\n```\n{ filePath, kind: "file", fileName, directory, extension, language, mimeType, size, mtime }\n```\n\n**Returns for directories:**\n```\n{ filePath, kind: "directory", fileName, directory, fileCount, size }\n```\n\n- `size` for directories is the total size of all direct children\n- `fileCount` for directories is the total number of files in the subtree\n- `mtime` is the last modification timestamp (files only)\n\n## Cross-graph links\n\nFiles can be linked from notes and tasks:\n\n```\n// From a knowledge note\ncreate_relation({ fromId: "config-format", toId: "src/config.ts", kind: "documents", targetGraph: "files" })\n\n// From a task\ncreate_task_link({ taskId: "refactor-config", targetId: "src/config.ts", targetGraph: "files", kind: "affects" })\n```\n\nUse `find_linked_notes` or `find_linked_tasks` with `targetGraph: "files"` to discover what knowledge or tasks reference a specific file:\n\n```\nfind_linked_notes({ targetId: "src/auth.ts", targetGraph: "files" })\nfind_linked_tasks({ targetId: "src/auth.ts", targetGraph: "files" })\n```\n\n## Tips\n\n- Use `list_all_files` with `directory` to browse top-down through the project tree\n- Use `list_all_files` with `extension: ".ts"` or `language: "typescript"` to find all files of a type\n- `get_file_info` on `"."` gives project-level stats (total size, file count)\n- `search_all_files` works better with path-like queries than abstract concepts\n- File index is always active — no `graphs.docs.include` or `graphs.code.include` configuration needed\n- The `language` filter in `list_all_files` uses detected language names like `"typescript"`, `"javascript"`, `"markdown"`, `"json"`, `"yaml"`, `"css"`, `"html"`, `"python"`, etc.\n'},{id:`cross-references`,title:`Cross References Tool`,summary:`Bridge code definitions and documentation examples for any symbol.`,category:`guide`,relatedTools:[`cross_references`],content:`# Cross References Tool
+
+\`cross_references\` is the only tool that works across **both** the CodeGraph and DocGraph simultaneously. It's the most comprehensive way to understand a symbol — combining source code definitions, documentation context, and usage examples.
+
+## When to use it
+
+Use \`cross_references\` when you want to fully understand a symbol:
+- "Where is \`createUser\` defined, and where is it documented?"
+- "Show me all examples of \`AuthService\` in the docs"
+- "What does \`parseConfig\` do, and how is it used?"
+
+## Requirements
+
+This tool is **only available** when both \`graphs.docs.include\` and \`graphs.code.include\` are configured in the project. It needs both graphs to bridge definitions and documentation.
+
+## Tool reference
+
+### cross_references
+
+Find all references to a symbol across both code and documentation graphs.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| \`symbol\` | string | Yes | Symbol name to look up, e.g. \`"createUser"\`, \`"AuthService"\` |
+
+**Returns:**
+\`\`\`
+{
+  definitions: [{
+    id,              // CodeGraph node ID, e.g. "src/auth.ts::createUser"
+    fileId,          // Source file path
+    kind,            // Symbol kind: function, class, method, interface, etc.
+    name,            // Symbol name
+    signature,       // Full type signature
+    docComment,      // JSDoc comment text
+    startLine,       // First line number
+    endLine          // Last line number
+  }],
+  documentation: [{
+    id,              // DocGraph node ID of parent text section
+    fileId,          // Documentation file path
+    title,           // Section heading
+    content          // Full section text (narrative context)
+  }],
+  examples: [{
+    id,              // DocGraph node ID of code block
+    fileId,          // Documentation file path
+    language,        // Code block language (e.g. "typescript")
+    symbols,         // All symbols found in this code block
+    content          // Full code block text
+  }]
+}
+\`\`\`
+
+## How it works in detail
+
+### Step 1: Find definitions in CodeGraph
+
+The tool iterates over all nodes in the CodeGraph, looking for exact \`name\` matches. This finds where the symbol is **defined** — the source code declarations.
+
+A single symbol name can have multiple definitions (e.g., overloaded functions, or the same name in different files).
+
+### Step 2: Find examples in DocGraph
+
+The tool iterates over all nodes in the DocGraph, checking the \`symbols\` array of code block nodes. When markdown is indexed, fenced code blocks are parsed:
+
+1. The code block's language is detected from the fence tag (\` \`\`\`ts \`, \` \`\`\`javascript \`, etc.)
+2. TypeScript/JavaScript blocks are parsed with \`tree-sitter\` using a virtual in-memory file
+3. Top-level symbol names are extracted: function declarations, class declarations, variable declarations
+4. These are stored in the \`symbols\` field
+
+So \`cross_references\` can find a code block like:
+
+\`\`\`typescript
+const user = createUser({ name: 'Alice', role: 'admin' });
+await sendWelcomeEmail(user);
+\`\`\`
+
+This block would have \`symbols: ["user"]\` (the top-level variable declaration), but **not** \`symbols: ["createUser"]\` — because \`createUser\` is a function **call**, not a declaration. Only top-level declarations are extracted.
+
+> **Important:** Symbol extraction captures **declarations**, not **usages**. A code block that calls \`createUser()\` won't match unless it also declares something named \`createUser\`.
+
+For the symbol to match, the code block must contain a **declaration** of that name. For example:
+
+\`\`\`typescript
+function createUser(data: UserInput): User {
+  return db.insert(data);
+}
+\`\`\`
+
+This block **would** match because \`createUser\` is declared as a top-level function.
+
+### Step 3: Find documentation context
+
+For each matching code block example, the tool looks at its **parent text section** — the in-neighbors in the doc graph that are in the same file with a lower heading level and no language tag (i.e., text content, not another code block).
+
+This gives you the narrative context around the example: the explanation, the motivation, the caveats.
+
+## Example scenario
+
+Project structure:
+- \`src/auth.ts\` contains \`export function createUser(data: UserInput): User { ... }\`
+- \`docs/guide.md\` has a section "## Creating Users" with an example code block that declares/uses \`createUser\`
+
+Calling \`cross_references({ symbol: "createUser" })\` returns:
+- **definitions**: \`[{ id: "src/auth.ts::createUser", kind: "function", signature: "function createUser(data: UserInput): User", ... }]\`
+- **examples**: \`[{ id: "docs/guide.md::Creating Users::code-1", language: "typescript", symbols: ["createUser"], content: "..." }]\`
+- **documentation**: \`[{ id: "docs/guide.md::Creating Users", title: "Creating Users", content: "To create a new user, call..." }]\`
+
+## Comparison with other symbol tools
+
+| Tool | Graph | Finds | Best for |
+|------|-------|-------|----------|
+| \`get_symbol\` | CodeGraph only | One specific symbol by ID | Reading full implementation |
+| \`search_code\` | CodeGraph only | Symbols by semantic similarity | Finding code by description |
+| \`find_examples\` | DocGraph only | Code blocks by symbol name | Finding doc examples |
+| \`explain_symbol\` | DocGraph only | Code blocks + parent text | Understanding via docs |
+| \`cross_references\` | Both graphs | Definitions + examples + docs | Complete understanding |
+
+## Tips
+
+- Use exact symbol names (case-sensitive match)
+- If you get no results, check that both \`graphs.docs.include\` and \`graphs.code.include\` are configured
+- Empty \`definitions\` + non-empty \`examples\` means the symbol is documented but not in your indexed code
+- Empty \`examples\` + non-empty \`definitions\` means the symbol exists in code but isn't documented with examples
+- Combine with \`get_symbol\` to read the full implementation body (which \`cross_references\` doesn't include)
+`}];function t(t){return e.find(e=>e.id===t)}function n(t){return e.filter(e=>e.relatedTools.includes(t))}export{n,e as r,t};