Skip to content

Getting Started with Knowledge Graph

A step-by-step guide for setting up the knowledge graph system and capturing the first lesson.

Version: 0.1.0-beta

Universal Installer (All Platforms)

For Cursor, Windsurf, Continue.dev, JetBrains, VS Code, Aider, and other AI assistants: Paste ./INSTALL.md into the AI assistant for fully automated setup.

The universal installer is a natural language prompt designed to execute shell scripts and manage file system operations within the local project directory. The installer detects the platform, configures the Model Context Protocol (MCP) server, and initializes the knowledge graph automatically.

Access Requirements

Automated setup requires an AI assistant with terminal and file system access. Assistants without these capabilities require manual configuration following the setup within the prompt itself.

For Claude Code users: Follow the setup steps below, or paste ./INSTALL.md for the same automated experience.

Not sure which platform fits? Read ./CONCEPTS.md for a plain-English overview of the system before proceeding.

Using Commands on Non-Claude-Code Platforms

The commands in this guide work across different platforms:

Platform How Commands Work
Claude Code Slash commands: /kmgraph:capture-lesson — full automation
Cursor, Windsurf, Continue.dev, VS Code Paste command content into your LLM. Substitute ${CLAUDE_PLUGIN_ROOT} with your actual path
Claude.ai, ChatGPT, Gemini, etc. Commands serve as reference documentation. Follow steps manually

Note: Commands are designed to work with any LLM. Full automation is Claude Code-exclusive, but the underlying workflows work everywhere.

Claude Code Setup

For: Users with the Claude Code plugin installed.

Time to first lesson: ~5 minutes

Prerequisites

  • Claude Code (latest version)
  • Git (recommended; enables automatic code linking)
  • Node.js 18+ (required for the MCP server)

Step 1: Load the Plugin

Start Claude Code from the plugin directory to load the knowledge graph commands:

claude --plugin-dir /path/to/knowledge-graph

Verify the plugin loaded by typing /knowledge — the autocomplete menu should display available commands.

Step 2: Initialize the Knowledge Graph

/kmgraph:init

The initialization wizard prompts for: - Project name — the name of the current project - Git tracking — enable to automatically capture branch and commit metadata - Optional Backfill (Step 1.10) — "Would you like to backfill the knowledge graph from existing project context? [y/N]" - If yes: automatically extracts from README, CHANGELOG, existing lessons, decisions, and chat history - If no: starts with empty knowledge graph, grows organically as you document lessons

After completion, the command creates the knowledge graph directory structure in the project.

Step 3: Verify Setup

/kmgraph:status

Expected output: Knowledge Graph: [project-name] | 0 lessons | 0 decisions

Step 4: Capture the First Lesson

/kmgraph:capture-lesson

Claude Code guides the session through documenting a problem solved recently. The command auto-fills metadata fields (created, author, git.*) and asks for the manual fields (title, category, tags).

Tip: The best time to document is immediately after solving a problem — details are freshest then.

Step 5: Verify the Lesson Was Saved

/kmgraph:status

Expected output now shows: 1 lesson

The Knowledge Capture Pipeline

The workflow for capturing and synchronizing knowledge follows a four-step pipeline:

%%{init: { 'flowchart': { 'useMaxWidth': true }, 'theme': 'neutral' }}%%
graph LR
    A["📝 Capture<br/>/kmgraph:capture-lesson"] --> B["📊 Extract<br/>/kmgraph:update-graph"]
    B --> C["🔄 Sync<br/>/kmgraph:sync-all"]
    C --> D["💾 Summarize<br/>/kmgraph:session-summary"]

    accTitle: Knowledge Capture Pipeline
    accDescr: Four-step workflow: Capture lessons (step 1) feeds into Extract patterns (step 2), which feeds into Sync across graphs (step 3), which feeds into Summarize session (step 4)

Each step serves a specific purpose:

  1. Capture - Document what you learned immediately after solving a problem
  2. Extract - Transform lessons into searchable patterns and concepts
  3. Sync - Consolidate across multiple knowledge graphs
  4. Summarize - Create session snapshots for future reference

Next Steps for Claude Code Users

  • Essential Commands

    Start with the core commands: init, capture-lesson, status, and recall. These cover 80% of daily use.

  • Real-World Examples

    See completed examples of lessons learned, ADRs, and KG entries from real projects.

  • Set Up Sharing

    Configure sanitization to safely share your knowledge graph with team members and the public.

Troubleshooting

Plugin update does not take effect

Known Claude Code Limitation: Plugin Cache Not Refreshed on Update

Claude Code's "Update Now" feature and claude plugin update command update version metadata but do not re-download plugin files. The installed plugin continues running from the old cached version after an update.

This is a known platform issue (#19197, #14061).

Symptoms: - Installed tab still shows the old version number - New commands or skills added in the update are unavailable - MCP server shows a failed status

Fix — clear the cache and reinstall:

# Step 1: Remove the stale cache
rm -rf ~/.claude/plugins/cache/stayinginsync-knowledge-graph/

# Step 2: Reinstall via the Claude Code /plugin UI
# Uninstall kmgraph, then reinstall from the marketplace

Step 3: Reconnect the MCP server

After reinstalling, open /plugin → Installed → kmgraph → MCP Server → Reconnect.

Commands do not appear in Claude Code autocomplete

  • Verify the plugin is loaded: start Claude Code with claude --plugin-dir /path/to/knowledge-graph
  • Commands use the knowledge: prefix with a colon, not a hyphen: /kmgraph:init (correct), /knowledge-init (incorrect)
  • Restart Claude Code completely if commands still do not appear

The MCP server does not start

# Verify Node.js is installed
node --version  # Should show 18.x or higher

# Check the MCP server binary exists
ls mcp-server/dist/index.js

# Test the MCP server directly
./tests/test-mcp-direct.sh

Templates are not found

Verify that core/templates/ exists in the project directory and that templates were copied to docs/templates/ with cp -r core/templates/. docs/templates/.

Which category should this lesson use?

Category Use for
architecture System design decisions, component relationships
process Workflow improvements, tool configurations, procedures
patterns Reusable solutions discovered through experience
debugging Bug investigations, troubleshooting sessions, root cause analysis

When uncertain, choose debugging for problem-solving documentation and process for workflow-related insights.

Is git required?

Git is recommended but not required. With git, the system automatically captures branch name, commit hash, and PR/issue numbers as lesson metadata. Without git, all features remain available — only automatic code linking is unavailable.

Skills and Subagents

As you work, the system provides two types of intelligent assistance:

Skills (Auto-Triggered Context Providers)

Skills activate automatically based on what you're doing. They provide guidance without interrupting:

Skill Triggers On Suggests
lesson-capture "figured it out", bug solved, breakthrough made /kmgraph:capture-lesson with pre-filled context
kg-recall "have we done this before", past decisions, history questions /kmgraph:recall with extracted search terms
session-wrap Session ending, context limit (180K+), major milestone /kmgraph:session-summary before compaction
adr-guide "I'm thinking of using...", architecture decisions /kmgraph:create-adr with decision guidance
gov-execute-plan "execute plan", implementation start, docs/plans/*.md mentioned Zero-deviation 8-step execution protocol

You don't invoke skills directly — they appear as helpful context when relevant.

Subagents (Heavy-Lift Handlers)

Subagents handle resource-intensive tasks in isolation, keeping your main context clean:

Subagent Mode When to Use
knowledge-extractor Read-only (approval-gated writes) Parsing 10+ lessons, 50+ KB extracts, or backfill from existing project context. Never auto-writes without user review.
session-documenter Git archaeology (approval-gated commits/pushes) Complex multi-file sessions, automated session summaries with conventional commit format. Never auto-commits or auto-pushes.

Use --delegate knowledge-extractor or --delegate session-documenter in commands like /kmgraph:extract-chat, /kmgraph:update-graph, or /kmgraph:session-summary to invoke subagents for heavy operations.

Installation & Setup

Automated setup for all platforms (paste into any AI assistant)

Post-install customization: sanitization, team workflows, MCP server

Integration details for Cursor, Windsurf, Continue, VS Code, Aider

Learning & Reference

All commands with examples, learning path, and troubleshooting

One-page guide for common tasks and commands

Plain-English definitions of every term used in documentation

Real-world completed examples: lessons, ADRs, KG entries

Advanced

Step-by-step guides for all 9 workflow types

How to write high-quality knowledge entries

Documentation authoring standards and best practices

Version: 0.1.0-beta Last Updated: 2026-03-03