Skip to content

Configuration

Jump to bottom
Maxim Mironenko edited this page Jul 3, 2026 · 9 revisions

Configuration

Environment Variables

Set these before starting the server, or in the systemd service file.

Variable Default Description
KG_ORPHAN_GRACE_DAYS see constants.py Days before orphaned archived nodes are permanently deleted
KG_GRACE_PERIOD_DAYS see constants.py Days after node creation before it becomes eligible for archival. Updates and reads do not reset this.
KG_STORAGE_ROOT ~/.knowledge-graph Root directory for all graph data (centralized storage)
KG_HTTP_PORT 8765 Server port
KG_HTTP_HOST 127.0.0.1 Server host binding
KG_LOG_LEVEL INFO Logging level (DEBUG, INFO, WARNING, ERROR)

Note: KG_SAVE_INTERVAL is no longer critical — write-through persistence means every mutation saves to disk immediately. The periodic save thread (30s) handles maintenance tasks only (compaction, orphan pruning).

Example:

KG_ORPHAN_GRACE_DAYS=60 kg-memory start

Or set them in your shell profile for persistence:

export KG_ORPHAN_GRACE_DAYS=60

The Size Budget Is Fixed by Design

The graph's size budget is exact rendered characters, not estimated tokens, and it is deliberately not configurable (the old KG_MAX_TOKENS variable is gone as of 0.9.16): 17,500 characters per graph level for compaction, 40,000 for a whole kg_read result. The estimator measures the very strings kg_read renders — render equals charge — so the budget arithmetic guarantees the output always lands inline in Claude's context instead of spilling to a persisted file. A knob would break that guarantee. If a graph ever exceeds what fits (e.g. one maintained by an older server), the output degrades gracefully: lowest-scored archived anchors are hidden first, then lowest-value edges, never active knowledge — and the output says so.

What's Tunable vs Hardcoded

Tunable

  • Storage root (KG_STORAGE_ROOT) — Override where all graph data is stored. Default is ~/.knowledge-graph/.
  • Grace periods — How long before nodes can be archived or orphans deleted. Longer = more disk usage, shorter = more aggressive cleanup.
  • Log level — Set to DEBUG for troubleshooting, WARNING for quiet operation.

Hardcoded (Not Configurable)

Setting Value Why
Storage layout ~/.knowledge-graph/projects/<slug>/graph.json Centralized, plain JSON
User graph path ~/.knowledge-graph/user.json Single shared file
Sessions path ~/.knowledge-graph/sessions.json Central session tracking
Session TTL 24 hours Sessions expire after inactivity
Session ID length 8 hex chars Short enough for tool args
Char budget per level 17,500 Compaction threshold — exact rendered characters (see above)
Read output ceiling 40,000 chars Hard cap on a kg_read result; degrades gracefully, never overflows
Search output ceiling 10,000 chars Hard cap on a kg_search result
Compaction target ratio 0.8 Archiving compacts down to this fraction of the budget; refill fills back up to the same ceiling
Archived budget ratio 0.30 Max fraction of the budget that archived anchor lines may occupy before orphaning
Archived-edge weight 0.2 Connectedness weight of an edge to an archived neighbour (active = 1.0, orphaned = 0)
Scoring formula 0.25×recency + 0.40×connectedness + 0.35×usefulness Weighted sum of tie-aware percentile ranks. Connectedness = in×0.66 + out×0.33 (archived neighbours at reduced weight). Usefulness = decaying kg_useful endorsements (90-day half-life).
Likes per session 5 kg_useful budget — endorsement, not traffic

These are defined in server/core/constants.py. You can modify them if you clone/fork the code, but they're not exposed as env vars.

Recommended Settings

Default (Most Users)

Leave everything at defaults. The system is designed to work well out of the box with small-to-medium graphs.

Heavy User (Many Projects, Long Sessions)

export KG_ORPHAN_GRACE_DAYS=60   # Keep archived nodes longer
export KG_GRACE_PERIOD_DAYS=7    # Longer protection window

Minimal Footprint

export KG_ORPHAN_GRACE_DAYS=7    # Quick cleanup

Debugging

export KG_LOG_LEVEL=DEBUG        # Verbose logging

MCP Connection Config

The plugin's .mcp.json tells Claude Code where the server is:

{
  "mcpServers": {
    "kg": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

If you change KG_HTTP_PORT, update this file to match.

Visual Editor Config

The visual editor has its own env vars (separate from the MCP server):

Variable Default Description
EDITOR_PORT 8766 Visual editor web server port
EDITOR_HOST 127.0.0.1 Host binding
MCP_SERVER_URL http://127.0.0.1:8765 Where to find the MCP server

Clone this wiki locally