Skip to content

Home

Jump to bottom
Maxim Mironenko edited this page May 20, 2026 · 10 revisions

Knowledge Graph Plugin for Claude Code

Gives Claude a persistent memory that survives across sessions — not flat notes, but a graph of distilled insights connected by typed relationships.

Quick Install

/plugin marketplace add mironmax/claudecode-plugins
/plugin install knowledge-graph@maxim-plugins

Restart Claude Code. The plugin's bundled hook auto-loads on session start and keeps the graph in focus across all sessions.

Also do this:

  • Disable built-in auto-memory — ⚙ Settings → Memory → toggle Auto-memory off. Without this, two memory systems run in parallel and write conflicting entries.
  • Enable plugin auto-updates — /plugin → Marketplaces → maxim-plugins → Enable auto-update. Third-party marketplaces are off by default. See Installation#enable-auto-updates-recommended.

Optional: for kg-memory / kg-visual shell commands (manage the server from your terminal), see Installation.

See Installation for full setup, Skills Reference for usage, or browse the full wiki.

Is This For Me?

  • You use Claude Code regularly across sessions
  • You find yourself re-explaining the same context, patterns, or decisions
  • You want Claude to remember your preferences and project quirks over time
  • You're comfortable running a local Python server

The value depends on how well Claude captures useful knowledge vs. noise — this improves as the graph matures.

How It Works (brief)

A local MCP server (Python/FastAPI, port 8765) stores a knowledge graph as JSON files at ~/.knowledge-graph/. Two storage levels: user (cross-project wisdom) and project (codebase-specific). Claude reads and writes nodes and edges representing insights, patterns, and relationships.

Key mechanics: In-memory graph with write-through persistence (every mutation saved immediately to disk). Auto-compaction uses a two-pass system: active nodes are archived when the graph exceeds 4000 tokens; archived nodes are orphaned when they exceed 30% of the token budget — orphaned nodes vanish from the graph view but remain searchable and can be chain-recalled. Multi-session aware — parallel Claude Code instances share the same server.

Stack: Python, FastAPI, MCP over stateless HTTP, JSON file storage. No databases, no cloud, fully local.

How It Compares

Three memory approaches exist for Claude Code — each with a different philosophy:

KG Memory (this plugin) Claude Code Auto-Memory MemPalace
Structure Graph — nodes + typed edges Flat markdown files + index Spatial hierarchy (wings/rooms)
Storage Compressed insights (gist + notes) Short markdown summaries Verbatim transcripts, never summarized
Relationships First-class — explicit labeled edges None Implicit via spatial co-location
Architecture/code patterns Yes — core use case Explicitly excluded Yes
Auto-compaction Yes — scores by recency/connectedness (+ resurrection pass) No — manual curation No — grows unbounded
Multi-session sync Yes — shared server + kg_sync() No No
Infrastructure Local Python server Just files on disk ChromaDB + SQLite
  • Auto-Memory bets on simplicity — flat files, low overhead. Good for preferences. No structural awareness of how knowledge relates.
  • MemPalace bets on fidelity — store everything verbatim, organize spatially, let vector search find it. High recall accuracy, high storage cost.
  • KG Memory bets on compression + connections — distill insights aggressively, compensate with explicit relationships. The only system where "component A depends on service B because of decision C" is a native representation, not text sitting in a file.

See Design Decisions for the full comparison.

Wiki Pages

Page What's In It
Installation Full setup steps, permissions, troubleshooting
How It Works Architecture, data flow, compaction, two-level model
Server Management Start/stop/status, logs, systemd, troubleshooting
Knowledge Graph API All MCP tools with inputs, outputs, examples
Skills Reference Scout, extract, memory skills — when and how to use
Visual Editor Setup, features, limitations
Data and Backup File locations, crash protection, recovery, git/borg setup
Configuration Environment variables, defaults, what's tunable
Design Decisions Why JSON, why stateless HTTP, why compress-on-entry

Clone this wiki locally