Skip to content

Installation

Jump to bottom
Maxim Mironenko edited this page Mar 17, 2026 · 17 revisions

Installation

Via Plugin Marketplace

# 1. Add the marketplace
/plugin marketplace add mironmax/claudecode-plugins

# 2. Install the plugin
/plugin install knowledge-graph@maxim-plugins

# 3. Set up CLAUDE.md (critical — see below)

# 4. Disable built-in auto-memory (see below)

# 5. Install global command (optional but recommended)
bash ~/.claude/plugins/knowledge-graph/install_command.sh

# 6. Restart Claude Code

The CLAUDE.md Template (Don't Skip This)

The plugin ships a template that tells Claude to auto-load the knowledge graph at session start. Without it, you'll need to manually call tools each session.

If you don't have ~/.claude/CLAUDE.md yet:

cp ~/.claude/plugins/knowledge-graph/templates/CLAUDE.md ~/.claude/CLAUDE.md

If you already have ~/.claude/CLAUDE.md: Manually append the content from ~/.claude/plugins/knowledge-graph/templates/CLAUDE.md to your existing file.

The template includes:

  • Session start hook (kg_register_session() + kg_read())
  • Capture guidelines and compression rules
  • Self-reflection triggers
  • Memory trace instructions
  • Skill routing (/skill scout, /skill extract, /skill memory)

One Global CLAUDE.md Only

Use only ~/.claude/CLAUDE.md — do not add project-level CLAUDE.md files inside individual repos. Multiple CLAUDE.md files cause contradicting instructions and unnecessary context bloat. The knowledge graph is designed to carry project-specific knowledge (decisions, architecture, patterns) so project-level config files are redundant.

Disable Built-in Auto-Memory

Claude Code ships with a built-in auto-memory system that writes to ~/.claude/projects/*/memory/. When running alongside the knowledge graph, it creates duplicate, sometimes contradicting memory entries and wastes context window space.

Disable it:

  1. Open Claude Code: ⚙ Settings → Memory
  2. Toggle Auto-memory off

With auto-memory off, the knowledge graph becomes the single source of persistent memory — cleaner, more intentional, and without conflicts.

Enable Auto-Approval (Optional)

By default, Claude Code will ask permission for each MCP tool call. To skip these prompts, add permissions to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__plugin_knowledge-graph_kg__kg_read",
      "mcp__plugin_knowledge-graph_kg__kg_register_session",
      "mcp__plugin_knowledge-graph_kg__kg_put_node",
      "mcp__plugin_knowledge-graph_kg__kg_put_edge",
      "mcp__plugin_knowledge-graph_kg__kg_sync",
      "mcp__plugin_knowledge-graph_kg__kg_search",
      "mcp__plugin_knowledge-graph_kg__kg_delete_node",
      "mcp__plugin_knowledge-graph_kg__kg_delete_edge",
      "mcp__plugin_knowledge-graph_kg__kg_recall",
      "mcp__plugin_knowledge-graph_kg__kg_progress_get",
      "mcp__plugin_knowledge-graph_kg__kg_progress_set",
      "mcp__plugin_knowledge-graph_kg__kg_session_stats"
    ]
  }
}

If you already have a settings.json, merge these into your existing permissions.allow array. Don't paste the whole block — you'll get duplicate keys.

Verify Installation

# Start the server
kg-memory start

# Check it's running
kg-memory status

# Should return JSON health response
curl http://127.0.0.1:8765/health

Common Issues

"kg-memory: command not found"

  • Run bash ~/.claude/plugins/knowledge-graph/install_command.sh
  • Make sure ~/.local/bin is in your PATH
  • Add export PATH="$HOME/.local/bin:$PATH" to your shell rc file

Server won't start

  • Check if port 8765 is already in use: lsof -i :8765
  • Check Python venv exists: ls ~/.claude/plugins/cache/maxim-plugins/knowledge-graph/latest/server/venv/
  • Check logs: cat /tmp/mcp_server.log

Tools not appearing in Claude Code

  • Verify .mcp.json points to http://127.0.0.1:8765/
  • Restart Claude Code after installation
  • Check server is running: kg-memory status

Claude doesn't auto-load graph

  • Verify ~/.claude/CLAUDE.md exists and contains the template content
  • The template must include kg_register_session() and kg_read() instructions

Claude seems confused about memory or gives inconsistent context

  • Check if built-in auto-memory is still enabled: ⚙ Settings → Memory → Auto-memory (should be off)
  • Check if there are project-level CLAUDE.md files in your repos — they may conflict with the global template

Requirements

  • Python 3.10+
  • Claude Code with MCP plugin support
  • No external services, databases, or API keys needed

Clone this wiki locally