Maintenance

Operations you run when you want. None are part of the agent's tool surface, so an agent never triggers them by itself.

Find duplicates

$ kgl-memory-maintain dedup --root memory/graph

A fast all-pairs similarity scan over same-type entities. Pure vector maths, no LLM. It reports candidate pairs (adjust with --threshold) and never merges anything. Compare candidates in the viewer's entity pages, then merge by hand.

Synthesise reflections

$ kgl-memory-maintain reflect --root memory/graph --since 2026-11-01 --dry-run

Writes a Reflection node, a higher-level insight over recent facts, preferences and messages, which genuinely needs an LLM. Rather than ask for another API key, it shells out to your own authenticated claude CLI (claude -p, with tool access disabled). This uses your Claude usage, so run --dry-run first to inspect the exact prompt. If nothing falls in the window it exits without calling anything. Pick another model with --model (default sonnet). Requires the Claude Code CLI on your PATH.

Rebuild the indexes

After hand-editing .kgl files, or after switching embedders:

from kgl_memory.store import MemoryStore
from kgl_memory import ops

ops.reindex(MemoryStore("memory/graph"))

This rebuilds both the search index and the alias index from the source files.

Check structure

Ask the agent for run_lint, or open the viewer's Lint page, to list unresolved links and schema violations.

Per-project memory

By default kgl-memory-init gives each project its own graph at <project>/memory/graph (change with --graph-dir), so memories never leak between unrelated work. It registers the server in that project's .mcp.json using an absolute path. If the project already has a global kgl-memory registration, you'll end up with two under the same name; remove the one you don't want with claude mcp remove kgl-memory.

Init flags: --no-mcp-config and --no-stop-hook skip those steps, and --server-name changes the registered name.

Git

The server never commits on your behalf. Commit memory/graph/ when you like; consider ignoring memory/graph/.index/, which is derived data. An opt-in ops.CommitBatcher exists if you do want automatic, batched commits.