Skip to content

Installation

Jump to bottom
Maxim Mironenko edited this page Jun 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. Restart Claude Code

That's it. The plugin ships hidden skills that auto-load behavioral rules into every session, plus a bundled hooks/hooks.json that registers a UserPromptSubmit hook on session start. No setup script, no ~/.claude/settings.json edits, no version-stamped paths to remember.

Already in a session and don't want to restart? Run /reload-plugins to activate everything immediately.

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-Updates (Recommended)

Third-party marketplaces have auto-update off by default — without opting in, you'll stay on whichever version you first installed. This plugin ships frequently, so enabling auto-update is the painless way to stay current.

Enable it:

  1. Run /plugin in Claude Code
  2. Select Marketplaces → maxim-plugins
  3. Choose Enable auto-update

After that, Claude Code refreshes the marketplace catalog and updates installed plugins at session start. If anything was updated, you'll see a prompt to run /reload-plugins (or just restart Claude Code) to activate the new version.

Manual refresh on demand:

/plugin marketplace update maxim-plugins

This pulls the latest marketplace data and updates installed plugins from it without waiting for the next session start.

Upgrade note for older installs: if you used an earlier version of this plugin and saw the reminder hook get written into ~/.claude/settings.json, run the optional install_command.sh once after the next update. It cleans up the legacy entry so you don't get double reminders. See Optional shell commands.

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.

How It Works (No Setup Needed)

The plugin ships six skills. Their descriptions auto-load into Claude's context every session — three are hidden (auto-load only), three are also user-invocable via /skill <name>:

Skill Role What it carries
kg-core Hidden (auto-load) Session start protocol, memory-first principle, API reference
kg-capture Hidden (auto-load) Capture triggers, telegraphic encoding rules, edge-first thinking
kg-recall Hidden (auto-load) Proactive recall, three-tier state model, crumb-following
kg-maintain Auto-load + /skill kg-maintain Garden rhythm (water/prune/fertilize), reactive triggers, focused maintenance pass
kg-scout Auto-load + /skill kg-scout Tension-driven history mining from past sessions
kg-extract Auto-load + /skill kg-extract Codebase architecture mapping into the project graph

Each description is under 1,536 chars — the per-skill hard limit enforced by Claude Code. The plugin also ships a hooks/hooks.json with a UserPromptSubmit hook (hooks/kg-remind.sh) that injects a random KG-related reminder before each user turn. All skills and the hook activate automatically when the plugin is enabled — no manual configuration required.

Optional: kg-memory and kg-visual Shell Commands

The plugin's MCP server is a shared HTTP service on port 8765 that should be started once and left running across sessions. Claude Code connects to it on each session start but does not launch it for you. If you want to manage the server from your terminal — start, stop, check status, view logs — install the helper commands:

bash "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name install_command.sh | sort -V | tail -1)"

This symlinks two commands into ~/.local/bin/:

  • kg-memory {start,stop,status,restart,logs} — manage the MCP server
  • kg-visual {start,stop,status,restart,logs} — manage the visual editor (browser UI on port 3000)

Make sure ~/.local/bin is in your PATH. The script also cleans up the legacy UserPromptSubmit hook entry that older versions of the plugin wrote into ~/.claude/settings.json, so it's safe to run on upgrades.

Upgrading from an older install? Running install_command.sh once is the recommended cleanup step — it removes the legacy hook entry from ~/.claude/settings.json so you don't get double reminders.

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

# (Only if you installed the optional shell commands)
kg-memory status
kg-memory start   # if not already running

# Server health check
curl http://127.0.0.1:8765/health

In Claude Code, run /context and confirm the plugin's skills (kg-core, kg-capture, kg-recall, kg-maintain, kg-scout, kg-extract) appear under the plugin.

Common Issues

"kg-memory: command not found"

  • The shell commands are optional and installed by install_command.sh. See the Optional shell commands section.
  • After running it, make sure ~/.local/bin is in your PATH: export PATH="$HOME/.local/bin:$PATH" in your shell rc file.

Server won't start

  • Check if port 8765 is already in use: lsof -i :8765
  • Check logs: cat ~/.local/state/knowledge-graph/mcp_server.log
  • The Python venv lives inside the plugin's cache dir; if it's broken, reinstall the plugin: /plugin uninstall knowledge-graph@maxim-plugins then /plugin install knowledge-graph@maxim-plugins.

Tools not appearing in Claude Code

  • Restart Claude Code (or run /reload-plugins) — plugins activate at session start.
  • Verify the plugin is enabled: /plugin list
  • Confirm the server is running: curl http://127.0.0.1:8765/health

Claude doesn't auto-load graph

  • Check /context — the plugin's skills (kg-core, kg-capture, etc.) should appear.
  • If skills are missing, the plugin may not be enabled: check /plugin list.
  • If the reminder hook isn't firing, run /reload-plugins once to pick up the bundled hooks/hooks.json.

Two reminders firing per prompt (upgrade artifact)

  • Older versions of this plugin wrote the reminder hook into ~/.claude/settings.json. The current version ships it inside the plugin instead. Run the optional install_command.sh once — it cleans up the legacy entry idempotently.

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