Skip to content

Installation

Jump to bottom
Claude edited this page Oct 9, 2026 · 24 revisions

Installation

uv tool install kg-memory     # needs uv: https://docs.astral.sh/uv/ (it brings its own Python)
kg setup                      # asks before each change, backs up what it edits

No uv yet? curl -LsSf https://raw.githubusercontent.com/mironmax/kg-memory/main/install.sh | sh installs uv and kg-memory, then runs kg setup when there is a terminal to ask in. Running it again upgrades kg. Asking an agent to install it? Point it at INSTALL.md; the agent shows you the plan and applies only what you agree to.

Requirements

  • Linux or macOS. Windows is not supported: the kg command relies on Unix file locking and the hooks are bash scripts.
  • uv, which installs kg into its own environment with Python 3.10 or newer.
  • bash, curl and python3 on your system. The harness hooks run them.
  • At least one harness: Claude Code, Codex CLI, Antigravity CLI (experimental) or Claude Desktop.

What kg setup does

kg setup checks each piece, shows what it would change, and asks about each item separately. Accepting what it offers is the usual start. Every file it edits is first backed up under ~/.local/state/knowledge-graph/backups/. Items for harnesses you don't have are skipped.

Key What it sets up
command The kg command on your PATH. If it is missing, setup says how to fix it (uv tool update-shell, then open a new terminal).
legacy-commands Retires the kg-memory and kg-visual links from 0.11 and earlier. kg-memory stays as a shim that runs kg.
service A systemd user service, kg-memory.service, that starts the server with your login session. Linux only; elsewhere the session hook starts the server on demand.
server One running server, on this version, from this installation.
claude-plugin The knowledge-graph plugin from the maxim-plugins marketplace.
claude-autoupdate Marketplace auto-update in Claude Code, so fixes arrive.
claude-permissions The kg_* tools pre-approved, so they don't ask on every call.
claude-automemory Claude Code's built-in auto-memory turned off. Two memory systems write conflicting entries.
claude-gauge Your status line routed through kg gauge, so the memory can read your quota (see below).
claude-desktop Claude Desktop's config pointed at kg mcp.
codex-plugin The plugin in Codex CLI, from the same marketplace.
codex-hooks A check only: Codex hooks need your approval in /hooks.
agy-plugin, agy-permissions The Antigravity CLI plugin and its tool grants. Deletions still ask.
upkeep Background upkeep, opt-in (see below).
storage A check only: where the memory lives and whether it has git history.

Two items change your existing setup, so read them before you accept: claude-automemory turns off Claude Code's own memory, and claude-gauge wraps your status line. Your status line keeps rendering.

Background upkeep is opt-in. With it on, the server tends the memory in small headless agent runs while your quota has room to spare. Because it spends quota, its question defaults to No, and --yes applies it only when named: kg setup --yes --only upkeep. Without it, the memory is tended when you run /kg-maintain. Its settings are in Configuration#maintenance-chores.

Useful forms:

kg setup --plan                      # show what setup would change, with each item's key
kg setup --yes --only KEY,KEY        # apply just these, without asking
kg doctor                            # check every piece afterwards

Steps only you can take

  • Codex: run /hooks and trust the knowledge-graph hooks. Codex keeps a plugin's hooks off until you approve them; until then the kg_* tools work but nothing arrives on its own. Codex records trust per hook content, so an update that changes the hooks asks again.
  • Claude Desktop: fully quit and reopen it after setup. Desktop chat has no hooks, so memory arrives on the first kg_read; Desktop's Code tab runs the Claude Code hooks.
  • Start a new session in each harness. Once the agent has read its memory, it says "I have recalled KG Memories". The memory is empty at first; that's normal.

Session limits and the status line (recommended)

Claude Code passes your 5-hour and weekly quota only to the status-line command. The claude-gauge item makes that command kg gauge, which records the reading in ~/.claude/last-limits.json and then runs your own status line unchanged (kg gauge --wrap '<your command>'), or prints a minimal quota line if you had none. With that file in place:

  • the server tells the agent when to plan its wrap-up (80% of the five-hour window) and when to wrap up now (90%), and likewise at 90% and 95% of the week;
  • background upkeep, if you switch it on, can check that your quota has room before it runs through Claude Code.

The recommended status line writes the same file and shows more; either one will do. Codex and Antigravity need nothing extra: the server reads their quota from the Codex session log and from Antigravity's /usage. To turn the notices off, see Configuration.

Updates

kg update

This upgrades kg, restarts the shared server on the new version and updates every installed plugin. Open sessions keep their tools: kg mcp waits out the restart. New skills and hooks load in a new session, and in Codex, changed hooks need trusting again in /hooks.

Uninstall

kg uninstall --plan          # what it would reverse
kg uninstall                 # asks before each step
uv tool uninstall kg-memory  # the kg command itself

kg uninstall reverses what setup did, backing up each file it changes: it stops the server, removes the service, the Claude Code, Codex and Antigravity plugins, the tool permissions and the Desktop entry, gives back the status line the gauge wrapped, turns Claude Code's auto-memory back on and switches upkeep off. Marketplace auto-update stays on. Your memory in ~/.knowledge-graph/ is not touched.

Upgrading from 0.11 or earlier

0.12 moved the server out of the plugin into the kg command. Install kg as above and run kg setup: it replaces the old kg-memory/kg-visual links, moves a Claude Desktop entry off the npx bridge, replaces the old memory-mcp.service unit with kg-memory.service, and updates the plugins. Your memory in ~/.knowledge-graph/ is untouched.

Troubleshooting

Start with kg doctor: it names each broken piece and the fix, and kg setup applies the fixes it can. More in Server Management#troubleshooting, and the kg-ops skill has the same recipes for an agent.

See also: Server Management, Configuration, and the plugin guide.

Clone this wiki locally