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:

Open Claude Code: ⚙ Settings → Memory
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:

Run /plugin in Claude Code
Select Marketplaces → maxim-plugins
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.

Session Limits and the Status Line (Recommended)

Claude Code pipes a JSON payload to your status-line command on every render, and that payload carries rate_limits — rolling 5-hour and 7-day subscription usage with reset timestamps. It reaches that command's stdin and nowhere else: the model never receives it, and the harness does not persist it. Without a status line that saves it, Claude cannot read its own remaining budget and has to ask you for the number on your screen.

The repo ships a status line that does both jobs — renders session health, and persists the quota so an agent can read it:

recommended-setup/statusline.sh (requires jq)

curl -fsSL https://raw.githubusercontent.com/mironmax/claudecode-plugins/main/recommended-setup/statusline.sh \
  -o ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

Then register it in ~/.claude/settings.json (merge into your existing JSON):

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

It renders two lines:

maxim@Solaris 📁 claudecode-plugins 🕐 21:21 🔗 knowledge-graph,claude-in-chrome [concise-quality-v2]
─────────────────────────────────────────────────────────────────────────────────────────────────────
⚡ Opus 5 │ 📊 5h:41%→02:10 7d:62%→Sun 02 │ 💾 cache:94% │ 📐 ctx:34%

— and writes every render's quota reading atomically to ~/.claude/last-limits.json:

jq . ~/.claude/last-limits.json
# {"five_hour_pct":41.5,"five_hour_resets_at":1785539400,"five_hour_seen_at":1785521950,
#  "seven_day_pct":62.0,"seven_day_resets_at":1785664800,"seven_day_seen_at":1785521950,
#  "context_pct":34.2,"updated_at":1785521950}

Field semantics an agent needs in order to use this correctly:

Field	Scope	How to read it
`five_hour_pct` / `seven_day_pct`	Account-global	Valid for every session, including background and scheduled ones — whichever session rendered last wrote them
`five_hour_resets_at` / `seven_day_resets_at`	Account-global	Unix epoch — directly schedulable. The 5h window is anchored to first use and drifts, so anchor quota-sensitive runs to this value rather than to a wall-clock time
`five_hour_seen_at` / `seven_day_seen_at`	Per window	Unix epoch of when that percentage was actually observed. This is the freshness gate — the two windows can arrive independently, and a carried-over value keeps its original stamp so it can never pass as current
`context_pct`	Last renderer only	Belongs to whichever session rendered last, not necessarily the one reading it — a hint, not your own context figure
`updated_at`	—	Unix epoch of the last write. Answers "is this file being maintained", not "is this number current" — headless and scheduled sessions do not reliably render a frame, so the file can go stale exactly when an unattended run needs it

Availability: Claude Code sends rate_limits only to Claude.ai subscribers (Pro/Max), and only after the session's first API response — early frames carry none, and API-key users get none at all. Each window can be absent independently; the script writes whichever arrived and carries the other's previous value forward with its original *_seen_at. A render with neither leaves the file untouched rather than overwriting good readings with nulls.

Telling Claude the gauge exists

The file changes nothing on its own — Claude has no way to discover it. Point at it once, either as a knowledge-graph node (arrives via session-start preload, costs nothing in the always-loaded budget, and accumulates your calibration numbers over time) or as a short section in ~/.claude/CLAUDE.md:

## Limits
My rolling quota is at ~/.claude/last-limits.json (written by the status line):
five_hour_pct, seven_day_pct, reset epochs, per-window *_seen_at stamps. Read it
at session start and before committing to a large block of work; pace against it
and say plainly when the budget argues for a smaller scope.

Why this pairs with graph memory specifically: quota-aware pacing works by ending sessions on a checkpoint — merge, commit, handover letter, memory writes — rather than mid-edit. That wrap-up costs budget of its own, so it has to be planned for while there's still room (stop near ~90%, not at 100%). A session that ends on a checkpoint hands the next one a complete picture; one that runs out mid-edit loses the session's learning rather than merely pausing it.

Full rationale and the pacing practice: recommended user-level setup.

How It Works (No Setup Needed)

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

Skill	Role	What it carries
`kg-core`	Hidden (auto-load)	The memory doctrine: session protocol, recall, capture, search below the surface
`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-maintain, kg-scout, kg-extract, kg-ops) 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-maintain, 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

Navigation Menu

Installation

Installation

Via Plugin Marketplace

Disable Built-in Auto-Memory

Enable Auto-Updates (Recommended)

Extend Session History Retention (Recommended)

Recommended Companion Practices (CLAUDE.md)

Session Limits and the Status Line (Recommended)

Telling Claude the gauge exists

How It Works (No Setup Needed)

Optional: `kg-memory` and `kg-visual` Shell Commands

Enable Auto-Approval (Optional)

Verify Installation

Common Issues

Requirements

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Installation

Installation

Via Plugin Marketplace

Disable Built-in Auto-Memory

Enable Auto-Updates (Recommended)

Extend Session History Retention (Recommended)

Recommended Companion Practices (CLAUDE.md)

Session Limits and the Status Line (Recommended)

Telling Claude the gauge exists

How It Works (No Setup Needed)

Optional: kg-memory and kg-visual Shell Commands

Enable Auto-Approval (Optional)

Verify Installation

Common Issues

Requirements

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Optional: `kg-memory` and `kg-visual` Shell Commands