Skip to content

Installation

Jump to bottom
Maxim Mironenko edited this page Jul 20, 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 bundled hooks: a SessionStart hook that starts the local memory server automatically when it's down (the very first run also builds its Python environment, ~1 minute) and preloads your memory into context, a UserPromptSubmit hook that surfaces memory matching each prompt, and a PostToolUse hook that nudges a capture when knowledge is being re-derived. No setup script, no ~/.claude/settings.json edits, no version-stamped paths to remember.

First session note: if the server was still warming up when your session connected, the kg_* tools may show as offline. Once the server is up (a few seconds; ~1 min on the very first run), run /mcp, select plugin:knowledge-graph:kg, and hit Reconnect — tools work immediately after. This only happens when a session starts while the server is down.

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.

Recommended Companion Practices (CLAUDE.md)

The plugin handles memory mechanics on its own — preload, full read, capture nudges all arrive via hooks and skills. Two practices sit above the mechanics, and they belong in your global ~/.claude/CLAUDE.md where they shape every session's posture rather than any single tool call.

Add a section like this:

## Memory

The Knowledge Graph holds accumulated context from past sessions. Reading it
means operating with the full picture; capturing learnings while working —
not after — pays off as higher-quality work in every later session.

At the end of a work session, leave a "letter to future self" in devdocs/ops/
(or the project's equivalent doc location). The KG stays lean — gists, edges,
compressed facts. The letter holds the full narrative: what was done, what's
broken, what to verify next, exact commands. A KG node references the file.
A fresh session reads both in under a minute and continues without
re-deriving anything. Once a later session has processed the letter, clean
it up or carry what remains into the next one.

Why the split works: the graph is optimized for scanning — an agent orients across dozens of compressed facts in seconds, and archival scoring keeps that scan affordable as knowledge accumulates. A session handover is the opposite shape: one long, ordered narrative that only the very next session needs in full. Storing the narrative as a file and pointing a graph node at it gives each medium the job it's best at — and the combination gets stronger as models get better at following the pointer chain without being told.

How It Works (No Setup Needed)

The plugin ships seven skills. Their descriptions auto-load into Claude's context every session — three are hidden (auto-load only), four 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 Bounded maintenance pass paying down the graph's DEBT line, reactive triggers
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
kg-ops Auto-load + /skill kg-ops Operations runbook: updates, server lifecycle, Desktop/Cowork, backup, troubleshooting

Each description is under 1,536 chars — the per-skill hard limit enforced by Claude Code. The plugin also ships hooks/hooks.json with three hooks: SessionStart (kg-autostart.sh — server autostart + memory preload), UserPromptSubmit (kg-remind.sh — prompt-matched recall, with staged reminders as the fallback), and PostToolUse (kg-tool-event.sh — capture nudges on proven re-derivation). All skills and hooks 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, shared by all sessions. It starts automatically — a SessionStart hook health-checks it and launches it when down, and the start script builds its Python environment on first run. You don't need to manage it at all for normal use.

If you want manual control from your terminal anyway — stop, restart, status, 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 8766)

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

# Server health check (the server auto-starts with your first session;
# the very first run takes ~1 min to build its Python environment)
curl http://127.0.0.1:8765/health

# (Only if you installed the optional shell commands)
kg-memory status

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.

kg_ tools offline even though the server is up*

  • This happens when a session starts while the server is down (e.g. the very first session, while the environment was still building): Claude Code's MCP connection went stale at startup.
  • Fix: run /mcp, select plugin:knowledge-graph:kg, hit Reconnect. Tools work immediately after.

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 environment is built automatically on first start and rebuilt after plugin updates; if a dependency install failed (e.g. no network), the next start retries it. Running the start script in a terminal shows the full error output.

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