Skip to content

Configuration

Jump to bottom
Maxim Mironenko edited this page May 19, 2026 · 7 revisions

Configuration

Environment Variables

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

Variable Default Description
KG_MAX_TOKENS 4000 Token limit per graph level before compaction. Two graphs ≈ 32K chars, safe under Claude Code's 50K tool output limit.
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_MAX_TOKENS=5000 kg-memory start

Or set them in your shell profile for persistence:

export KG_MAX_TOKENS=5000
export KG_ORPHAN_GRACE_DAYS=60

What's Tunable vs Hardcoded

Tunable

  • Token limit (KG_MAX_TOKENS) — Higher means more active knowledge, but larger tool output. 4000 per graph is the recommended default — two graphs stay safely under Claude Code's 50K char tool output limit. Not recommended to raise further since nodes in the grace period can temporarily exceed the limit.
  • 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
Compaction target ratio see constants.py After compaction, aim for this fraction of the token limit
Archived budget ratio 0.30 Max fraction of max_tokens that archived IDs may occupy before orphaning
Token estimation: base per node 20 tokens Rough overhead for JSON structure
Token estimation: chars per token 4 Standard approximation
Token estimation: per edge 15 tokens Rough overhead
Scoring formula 0.33×recency + 0.66×connectedness Weighted sum of percentile ranks. Connectedness = in×0.66 + out×0.33, active edges only.

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 3000 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