Skip to content

Installation

Jump to bottom
Maxim Mironenko edited this page Apr 11, 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. Disable built-in auto-memory (see below)

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

# 5. Restart Claude Code

That's it. The plugin ships hidden skills that automatically load behavioral rules into every session — no CLAUDE.md setup required.

Extend Session History Retention (Recommended)

Claude Code stores conversation transcripts in ~/.claude/projects/ — the same files that kg-scout mines to recover or build knowledge. By default it deletes sessions older than 30 days.

Add this to ~/.claude/settings.json to extend the window to 90 days:

{
  "cleanupPeriodDays": 90
}

This gives scout a richer history to work with and lets you recover context from older sessions when revisiting dormant projects. See Data and Backup for more detail.

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.

How It Works (No Setup Needed)

The plugin includes 4 hidden skills (user-invocable: false) whose descriptions are automatically loaded into Claude's context every session:

Hidden Skill What it carries
kg-core Session protocol, self-awareness check, API reference
kg-capture Capture triggers, search-before-put, compression rules
kg-recall Proactive recall, memory traces, sync timing
kg-maintain Self-reflection triggers, graph health, update discipline

These use ~8.3K of the 16K skill description budget — well within limits, leaving room for other plugins.

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_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_progress"
    ]
  }
}

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

  • Check /context in Claude Code — hidden skills (kg-core, kg-capture, etc.) should appear
  • If skills are missing, the plugin may not be enabled: check /plugin list

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)

Requirements

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

Clone this wiki locally