Installation
Users can install the Knowledge Management Graph using a universal installer — a single markdown file that any AI assistant can execute for automated setup.
How It Works
The universal installer detects the platform (Claude Code, Codex CLI, Cursor, Windsurf, Continue.dev, JetBrains, VS Code, Aider, or other AI assistants), configures the appropriate components, and initializes a knowledge graph automatically.
Installation takes approximately 5 minutes.
Get the Installer
This page shows a preview of the installer. To actually install, copy and paste the raw markdown file into an AI assistant. → Get the raw installer file
- Click the link above
- Select all text (Ctrl+A / Cmd+A)
- Copy to clipboard (Ctrl+C / Cmd+C)
- Paste into Claude, ChatGPT, Cursor, or any AI assistant
- Follow the assistant's instructions
For Claude Code Users
Claude Code users can follow a manual setup walkthrough instead: → Quickstart Or paste the universal installer above for the same automated experience.
For Codex CLI Users
codex plugin marketplace add technomensch/knowledge-graph
codex plugin add kmgraph@knowledge-management-graph
Skills and MCP tools activate immediately after install — no further configuration needed.
If you update the plugin source but skills or tools don't reflect the changes, Codex may be using a cached version. Clear the plugin cache:
rm -rf ~/.codex/plugins/cache/knowledge-management-graph/kmgraph/
codex plugin uninstall kmgraph
codex plugin marketplace add technomensch/knowledge-graph
codex plugin add kmgraph@knowledge-management-graph
This resolves issues where tools are out of date or skills don't appear after an update.
kmgraph hook scripts require node to be on the PATH visible to the Codex process. If hooks silently fail after install, confirm node is accessible from the shell that launches Codex — not just your login shell.
- nvm users: source
nvmbefore launching Codex, or add it to your shell'srcfile so it loads for non-login shells - fnm / volta users: these work reliably when their shims are on the system PATH (default install)
- Homebrew / system Node: typically works without changes
Codex skips plugin-bundled hooks until you explicitly trust them. After install, run /hooks inside a Codex session to review and trust the kmgraph hook definitions. New or modified hooks must be re-trusted whenever the hook file changes.
The commands/, skills/, agents/, and hooks/ directories in this repo are loaded exclusively
by the Claude Code plugin system. Do not copy these directories if using Cursor, Windsurf,
Continue.dev, JetBrains, VS Code, or any other tool — they will not work outside the plugin system.
All cross-platform functionality is provided through the MCP server as kg_* tools.
Platform Capabilities
Users can install on multiple platforms with varying automation levels:
| Platform | Automation | How to Install |
|---|---|---|
| Claude Code | Full automation | Paste installer (recommended) or follow Quickstart |
| Codex CLI | Full automation | codex plugin marketplace add technomensch/knowledge-graph then codex plugin add kmgraph@knowledge-management-graph |
| Cursor | Medium (MCP tools) | Paste installer; MCP server handles data layer |
| Windsurf | Medium (MCP tools) | Paste installer; MCP server handles data layer |
| Continue.dev | Medium (MCP tools) | Paste installer; MCP server handles data layer |
| JetBrains IDE | Medium (MCP tools) | Paste installer; configure in Settings → Tools → AI Assistant |
| VS Code | Medium (MCP tools) | Paste installer; MCP server handles data layer |
| Claude Desktop | Medium (MCP tools) | Paste installer; configure in Desktop settings |
| Aider | Low (manual workflows) | Paste installer; follow templates manually |
| GitHub Copilot | Low (manual workflows) | Paste installer; follow templates manually |
What Gets Installed
The installer sets up:
- Configuration file —
~/.claude/kg-config.json(stores knowledge graph locations and metadata) - Directory structure —
knowledge/,lessons-learned/,decisions/,sessions/,chat-history/ - Identity files —
knowledge/me.md(contributor identity, gitignored),knowledge/rules.md(project conventions, committed), andknowledge/triggers.md(rule timing, when each rule applies). See Your AI Profile. - Wiki links — Cross-references throughout the KG are converted to Obsidian
[[wiki link]]format, enabling graph view navigation in Obsidian and compatible editors - MCP server — Provides knowledge graph tools for non-Claude-Code platforms
- Templates — Starter scaffolds for capturing lessons and decisions
Upgrade Checks
When running /kmgraph:init on an existing installation, the wizard inspects your setup and reports what it finds:
| Check | What it looks for |
|---|---|
| a. Directories | Missing subdirectories (knowledge/, decisions/, sessions/, etc.) |
| b. Config fields | Missing fields in ~/.claude/kg-config.json introduced in newer versions |
| c. Templates | Template files that have been updated or added since your install |
| d. Platform split | Claude-specific tool directives in knowledge/rules.md that belong in CLAUDE.md |
| e. Wiki pass | Bare ADR-NNN, ENH-NNN, #NNN, and lesson filename references not yet converted to [[wiki links]] — runs once per KG, skipped on re-run if already complete |
| f. Docs migration | docs/enhancements/ or docs/issues/ subdirectories that should be moved into the knowledge graph structure |
| g. FTS5 cleanup | Stale in-project FTS5 index files (knowledge/fts5/) left behind by older versions |
| h. Identity scaffold | Missing me.md, rules.md, or triggers.md — presents a dry-run preview, scans existing platform files (CLAUDE.md, GEMINI.md, .cursorrules, etc.), README, ADRs, and sessions to pre-populate recommendations, then archives any originals before writing |
/kmgraph:init is safe to re-run at any time. It skips steps already complete and only offers items still pending for your install.
Next Steps
After installation, users can:
- Capture a lesson — Document a problem solved, pattern learned, or decision made
- Create architecture decisions — Record important design choices
- Search knowledge — Find lessons and patterns across sessions
- Sync knowledge — Automatically extract and organize captured content
See Quickstart for detailed walkthroughs.
Breaking Changes
v0.5.10.7 — core/templates/ renamed (Tier 3 manual installers only)
Affected: Tier 3 manual installers (ADR-009) who reference core/templates/ directly in copy instructions or custom scripts.
Change: core/templates/ renamed to core/default-templates/.
Action required: Update any copy instructions: core/templates/<dir>/ → core/default-templates/<dir>/.
Plugin/marketplace users (Tier 1/2): no action required — this path is internal to the plugin distribution; your knowledge/ directory is untouched.
Having Issues?
- Installation failed? Paste the full error message into the installer file's troubleshooting section
- MCP tools not visible? Restart the IDE after configuring the MCP server
- Config file not found? Run the installer again to create it
See FAQ for additional help.