Run any Skill in Manus with one click

kg-ops

Stars3

Forks1

UpdatedJuly 5, 2026 at 19:53

Operations runbook for the knowledge-graph plugin: install and first run, plugin updates, server lifecycle (start/stop/restart/logs), autostart via systemd, connecting Claude Desktop/Cowork, configuration, backup and restore, and troubleshooting (tools offline, -32000 errors, stale data, Desktop issues). Use when something needs setting up, breaks, or the user asks to manage the memory server or "read the docs and do what's needed".

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

mironmax

mironmax/claudecode-plugins

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Computer Occupations, All OtherComputer and Mathematical Occupations·SOC 15-1299

SKILL.md

readonly

name	kg-ops
user-invocable	true
description	Operations runbook for the knowledge-graph plugin: install and first run, plugin updates, server lifecycle (start/stop/restart/logs), autostart via systemd, connecting Claude Desktop/Cowork, configuration, backup and restore, and troubleshooting (tools offline, -32000 errors, stale data, Desktop issues). Use when something needs setting up, breaks, or the user asks to manage the memory server or "read the docs and do what's needed".

Knowledge-graph operations runbook

Recipes for agents. Each: diagnose → act → verify → undo where it applies.

Orientation — what runs where

One shared HTTP MCP server serves every session: http://127.0.0.1:8765/ (override port with KG_HTTP_PORT). Health: curl -sf http://127.0.0.1:8765/health.
Logs: ~/.local/state/knowledge-graph/mcp_server.log. PID file: server/.mcp_server.pid next to manage_server.sh.
Data: ~/.knowledge-graph/ (plain JSON — user.json, projects/<slug>/graph.json, sessions.json). Survives uninstall.
Plugin cache dirs are versioned (~/.claude/plugins/cache/maxim-plugins/knowledge-graph/<version>/) and change on every update. Anything that must survive updates goes through the stable shims in ~/.local/bin/: kg-memory, kg-visual, kg-desktop-bridge. Never hardcode a versioned cache path into configs.
A SessionStart hook auto-starts the server when it's down. It never stops or restarts a running one.

Install / first run

User installs via /plugin marketplace add mironmax/claudecode-plugins → /plugin install knowledge-graph@maxim-plugins → restart Claude Code.
The start script builds its own Python venv on first run (and rebuilds after updates) — first start can take ~1 min. No manual pip steps.
Optional shell commands:
```
bash "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name install_command.sh | sort -V | tail -1)"
```
Symlinks kg-memory + kg-visual (and refreshes kg-desktop-bridge if present) into ~/.local/bin/ — which must be on PATH.
Verify: health curl above returns JSON; kg_read works in a session.

After a plugin update

Rerun install_command.sh (recipe above) — repoints all ~/.local/bin shims at the new version dir.
The running server still executes the OLD code until restarted: kg-memory restart.
Every open session's MCP connection is now stale — the user must run /mcp → plugin:knowledge-graph:kg → Reconnect (agents cannot do this).

Server lifecycle

kg-memory start|stop|restart|status|logs|commit
kg-visual start|stop|status|logs        # graph editor at http://localhost:8766

Restarting disconnects all live sessions → each needs the /mcp Reconnect (ask the user; don't restart casually mid-work).
stop validates the PID actually belongs to the MCP server before killing (stale-PID protection) — trust it over manual kill.

Autostart on boot (Linux, systemd user unit)

Prerequisite: install_command.sh run once (unit invokes the kg-memory shim).

mkdir -p ~/.config/systemd/user
cp "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name memory-mcp.service | sort -V | tail -1)" \
   ~/.config/systemd/user/memory-mcp.service
systemctl --user enable --now memory-mcp.service

Verify: systemctl --user status memory-mcp + health curl. Undo: systemctl --user disable --now memory-mcp.service.

Connect Claude Desktop (and Cowork)

Desktop's "Add custom connector" dialog cannot work for a local server — those connectors are contacted from Anthropic's cloud and require a public https URL. The local route is Desktop's config file, automated here:

python3 "${CLAUDE_PLUGIN_ROOT}/setup_desktop.py"          # add (idempotent, backs up config)
python3 "${CLAUDE_PLUGIN_ROOT}/setup_desktop.py" --remove # undo

The entry points Desktop at the stable ~/.local/bin/kg-desktop-bridge symlink, which auto-starts the server if needed and proxies stdio↔HTTP via mcp-remote (needs Node.js ≥ 18; script fails loudly if npx is missing).

Verify the bridge before involving Desktop (expect "Proxy established"):

timeout 12 npx -y mcp-remote http://127.0.0.1:8765/ --allow-http 2>&1 | head -5

Then have the user fully quit Desktop (not just the window) and reopen. Cowork sessions receive the server through Desktop's own sandbox bridge.
Caveats: Desktop sessions get no SessionStart preload (Claude Code hook) — the first kg_read call orients instead. On Windows the auto-start wrapper is skipped (no bash); a Claude Code session must have started the server.

Configuration

Env vars (shell rc, or the systemd unit), then kg-memory restart: KG_HTTP_PORT (8765) · KG_STORAGE_ROOT (~/.knowledge-graph) · KG_SAVE_INTERVAL (30s) · KG_AUTOCOMMIT_INTERVAL (900s, 0 disables) · KG_GRACE_PERIOD_DAYS / KG_ORPHAN_GRACE_DAYS (see server/core/constants.py). Render budgets are fixed by design — no knob. Don't edit the bundled .mcp.json (overwritten on update).

Backup and restore

Crash protection is built in: atomic writes + one rolling <file>.prev. Restore: cp ~/.knowledge-graph/user.json.prev ~/.knowledge-graph/user.json (same pattern per project graph). Restart not required, but force a reload (below) if the server was up during the copy.
Versioned history: git init inside ~/.knowledge-graph (gitignore *.prev, *.tmp) — the server then auto-commits every 15 min and on shutdown; kg-memory commit forces one.
Off-machine: any file backup tool works on the JSON; borg dedups well.

Troubleshooting

kg tools offline / connection refused → health curl. Down: kg-memory start (first run builds venv, ~1 min), then user runs /mcp → Reconnect.
-32000 / "failed to reconnect" → the server-side process died; the code is generic. Get the real error: kg-memory logs, or run the start command by hand and read the traceback. Most common cause: OS Python upgrade broke the venv → rm -rf the plugin's server/venv, kg-memory start rebuilds it.
Graph looks stale after direct disk edits (scripts writing to ~/.knowledge-graph while the server runs) → the server caches graphs in memory: curl -s 'http://127.0.0.1:8765/api/graph/read?reload=true&project_path=<root>' forces a disk reload.
Desktop shows no knowledge-graph server → run the bridge verify command above. Bridge OK → the config entry: ~/.config/Claude/claude_desktop_config.json (Linux) / ~/Library/Application Support/Claude/ (macOS) — rerun setup_desktop.py, then full quit + reopen.
Log lines that are fine: Healed N corrupt node(s) on load (self-repair did its job) · over budget but all N active nodes within grace — compaction deferred (informational stall notice).

Uninstall

setup_desktop.py --remove first (frees the Desktop config), then /plugin uninstall knowledge-graph@maxim-plugins. Optionally remove the ~/.local/bin shims and the systemd unit. ~/.knowledge-graph/ is preserved.

More from this repository

same repository

kg-core

mironmax/claudecode-plugins

Knowledge Graph — persistent memory, your twin across sessions. Primary context before reaching for any other tool. Session start: memory usually arrives PRELOADED — a "KG MEMORY PRELOADED" block with session_id already in context. It is a compact core: a PARTIAL view, not the graph. REQUIRED before any substantive work: kg_read(session_id) once — it renders everything the preload dropped without repeating it. If no block: kg_read(cwd="<project root>") first. The session_id goes on ALL later kg_* calls. Announce "I have recalled KG Memories" only AFTER that full read. Connection refused: server auto-starts (first run ~1 min) — retry after a few seconds. Still offline: user runs /mcp → plugin:knowledge-graph:kg → Reconnect. Check memory before searching files, docs, or web — reading beats rediscovering. Working currency: gists + edges. Notes are on-demand depth — kg_read(id), or ids=[...] for several related nodes in ONE call. Writes mid-conversation are cheap — capture as things happen. Levels: user = cr

2026-07-043

kg-maintain

mironmax/claudecode-plugins

Knowledge graph maintenance. Tend the garden — regular, light care keeps it healthy. Woven into every session. GARDEN RHYTHM — three modes, applied as needed: Water (routine): after each task, glance at 2–3 recently-touched nodes. Gists still accurate? Notes worth adding? Do touches still point where they claim (files drift)? Prune (when dense): merge duplicate nodes, shorten verbose gists (→ notes), split oversized nodes, remove stale touches, delete edges to removed concepts. Fertilize (on use): when a node proves valuable, connect it to newly-discovered related nodes. One new edge makes a node far more durable. AFTER CAPTURE: when you save a node, immediately ask — - Do any adjacent nodes now need updating? - Is this a duplicate of something existing? Merge if so. - Does this node's gist still fit, or did context shift? REACTIVE TRIGGERS (act immediately, mid-conversation): Uncertainty (spinning wheels,

2026-07-033

kg-capture

mironmax/claudecode-plugins

Knowledge capture rules. Capture mid-conversation, not after — context is cached, so a write costs almost nothing now but saves full re-derivation next session. Good moments to capture (as things happen, not at task end): - Opened files with no component node → a brief node now saves a re-read later - Discovered how two things connect → an edge, while the insight is fresh - Understood why something works a certain way → a note on the existing node - 10+ min debugging resolved → root cause node before moving on - User expressed a preference, style, or constraint → user-level node - User corrected your approach → capture what was missed, not just the fix - Explained something non-obvious → node before it scrolls away - Approach agreed with user → capture the methodology, not just the decision - Architectural decision made → node with rationale in notes - Context window feels deep → a good moment to check for anything unrecorded When reading a file with no component node, consider creating

2026-07-033

kg-extract

mironmax/claudecode-plugins

Map codebase architecture into the knowledge graph

2026-07-033

kg-recall

mironmax/claudecode-plugins

Knowledge recall rules. Active every session, integrated with all task work. After kg_read, scan all node IDs and gists — anything that feels related to the current task is worth reading in full, several at once: kg_read(session_id, ids=[...]). Lean toward reading more rather than less; a wrong guess costs one tool call, missing context costs the whole task. Gists + edges are the working currency (WHAT + how things relate). Notes hold rationale (WHY) — read a node in full when a decision depends on the reasoning. Node reads also return the node's edges: each one is the next crumb. Three tiers — nodes shift as the graph grows: active → id + gist visible in kg_read archived → id only; edges visible as crumb trails orphaned → invisible in kg_read; reachable via kg_search Following crumbs: an edge pointing to an archived id is an invitation — reading it promotes it and surfaces any orphaned neighbors. Batch the whole trail into one ids=[...] call when several nodes look related. No edges? Scan the arc

2026-07-033

kg-scout

mironmax/claudecode-plugins

Mine conversation history for patterns and insights worth preserving

2026-05-223

name	kg-ops
user-invocable	true
description	Operations runbook for the knowledge-graph plugin: install and first run, plugin updates, server lifecycle (start/stop/restart/logs), autostart via systemd, connecting Claude Desktop/Cowork, configuration, backup and restore, and troubleshooting (tools offline, -32000 errors, stale data, Desktop issues). Use when something needs setting up, breaks, or the user asks to manage the memory server or "read the docs and do what's needed".

Knowledge-graph operations runbook

Recipes for agents. Each: diagnose → act → verify → undo where it applies.

Orientation — what runs where

One shared HTTP MCP server serves every session: http://127.0.0.1:8765/ (override port with KG_HTTP_PORT). Health: curl -sf http://127.0.0.1:8765/health.
Logs: ~/.local/state/knowledge-graph/mcp_server.log. PID file: server/.mcp_server.pid next to manage_server.sh.
Data: ~/.knowledge-graph/ (plain JSON — user.json, projects/<slug>/graph.json, sessions.json). Survives uninstall.
Plugin cache dirs are versioned (~/.claude/plugins/cache/maxim-plugins/knowledge-graph/<version>/) and change on every update. Anything that must survive updates goes through the stable shims in ~/.local/bin/: kg-memory, kg-visual, kg-desktop-bridge. Never hardcode a versioned cache path into configs.
A SessionStart hook auto-starts the server when it's down. It never stops or restarts a running one.

Install / first run

User installs via /plugin marketplace add mironmax/claudecode-plugins → /plugin install knowledge-graph@maxim-plugins → restart Claude Code.
The start script builds its own Python venv on first run (and rebuilds after updates) — first start can take ~1 min. No manual pip steps.
Optional shell commands:
```
bash "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name install_command.sh | sort -V | tail -1)"
```
Symlinks kg-memory + kg-visual (and refreshes kg-desktop-bridge if present) into ~/.local/bin/ — which must be on PATH.
Verify: health curl above returns JSON; kg_read works in a session.

After a plugin update

Rerun install_command.sh (recipe above) — repoints all ~/.local/bin shims at the new version dir.
The running server still executes the OLD code until restarted: kg-memory restart.
Every open session's MCP connection is now stale — the user must run /mcp → plugin:knowledge-graph:kg → Reconnect (agents cannot do this).

Server lifecycle

kg-memory start|stop|restart|status|logs|commit
kg-visual start|stop|status|logs        # graph editor at http://localhost:8766

Restarting disconnects all live sessions → each needs the /mcp Reconnect (ask the user; don't restart casually mid-work).
stop validates the PID actually belongs to the MCP server before killing (stale-PID protection) — trust it over manual kill.

Autostart on boot (Linux, systemd user unit)

Prerequisite: install_command.sh run once (unit invokes the kg-memory shim).

mkdir -p ~/.config/systemd/user
cp "$(find ~/.claude/plugins/cache/maxim-plugins/knowledge-graph -name memory-mcp.service | sort -V | tail -1)" \
   ~/.config/systemd/user/memory-mcp.service
systemctl --user enable --now memory-mcp.service

Verify: systemctl --user status memory-mcp + health curl. Undo: systemctl --user disable --now memory-mcp.service.

Connect Claude Desktop (and Cowork)

python3 "${CLAUDE_PLUGIN_ROOT}/setup_desktop.py"          # add (idempotent, backs up config)
python3 "${CLAUDE_PLUGIN_ROOT}/setup_desktop.py" --remove # undo

Verify the bridge before involving Desktop (expect "Proxy established"):

timeout 12 npx -y mcp-remote http://127.0.0.1:8765/ --allow-http 2>&1 | head -5

Then have the user fully quit Desktop (not just the window) and reopen. Cowork sessions receive the server through Desktop's own sandbox bridge.
Caveats: Desktop sessions get no SessionStart preload (Claude Code hook) — the first kg_read call orients instead. On Windows the auto-start wrapper is skipped (no bash); a Claude Code session must have started the server.

Configuration

Backup and restore

Crash protection is built in: atomic writes + one rolling <file>.prev. Restore: cp ~/.knowledge-graph/user.json.prev ~/.knowledge-graph/user.json (same pattern per project graph). Restart not required, but force a reload (below) if the server was up during the copy.
Versioned history: git init inside ~/.knowledge-graph (gitignore *.prev, *.tmp) — the server then auto-commits every 15 min and on shutdown; kg-memory commit forces one.
Off-machine: any file backup tool works on the JSON; borg dedups well.

Troubleshooting

kg tools offline / connection refused → health curl. Down: kg-memory start (first run builds venv, ~1 min), then user runs /mcp → Reconnect.
-32000 / "failed to reconnect" → the server-side process died; the code is generic. Get the real error: kg-memory logs, or run the start command by hand and read the traceback. Most common cause: OS Python upgrade broke the venv → rm -rf the plugin's server/venv, kg-memory start rebuilds it.
Graph looks stale after direct disk edits (scripts writing to ~/.knowledge-graph while the server runs) → the server caches graphs in memory: curl -s 'http://127.0.0.1:8765/api/graph/read?reload=true&project_path=<root>' forces a disk reload.
Desktop shows no knowledge-graph server → run the bridge verify command above. Bridge OK → the config entry: ~/.config/Claude/claude_desktop_config.json (Linux) / ~/Library/Application Support/Claude/ (macOS) — rerun setup_desktop.py, then full quit + reopen.
Log lines that are fine: Healed N corrupt node(s) on load (self-repair did its job) · over budget but all N active nodes within grace — compaction deferred (informational stall notice).