Skip to content

Configuration

Jump to bottom
Maxim Mironenko edited this page Feb 6, 2026 · 9 revisions

Configuration

Environment Variables

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

Variable Default Description
KG_MAX_TOKENS 5000 Token limit per graph before compaction kicks in
KG_SAVE_INTERVAL 30 Seconds between auto-saves to disk
KG_ORPHAN_GRACE_DAYS 7 Days before orphaned archived nodes are permanently deleted
KG_GRACE_PERIOD_DAYS 7 Days after last update before a node becomes eligible for archival
KG_USER_PATH ~/.claude/knowledge/user.json Path to user-level graph file
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)

Example:

KG_MAX_TOKENS=8000 KG_SAVE_INTERVAL=60 kg-memory start

Or set them in your shell profile for persistence:

export KG_MAX_TOKENS=8000
export KG_ORPHAN_GRACE_DAYS=30

What's Tunable vs Hardcoded

Tunable

  • Token limit (KG_MAX_TOKENS) — Higher means more active knowledge, but larger context window usage. 5000 is roughly 1-2 pages of compressed insights.
  • Save interval (KG_SAVE_INTERVAL) — Lower = more durable but more disk I/O. 30s is a reasonable balance.
  • 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
Project graph path .claude/knowledge/graph.json Consistent location across all projects
User graph path ~/.claude/knowledge/user.json Standard location
Session TTL 24 hours Sessions expire after inactivity
Session ID length 8 hex chars Short enough for tool args
Compaction target 90% of max tokens After compaction, aim for 90% of limit
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: percentile-based recency × connectedness × richness Product of three percentile ranks

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_MAX_TOKENS=8000        # More room before compaction
export KG_ORPHAN_GRACE_DAYS=30   # Keep archived nodes longer
export KG_GRACE_PERIOD_DAYS=14   # Longer protection window

Minimal Footprint

export KG_MAX_TOKENS=3000        # Aggressive compaction
export KG_ORPHAN_GRACE_DAYS=3    # Quick cleanup
export KG_SAVE_INTERVAL=60       # Less disk I/O

Debugging

export KG_LOG_LEVEL=DEBUG        # Verbose logging
export KG_SAVE_INTERVAL=5        # Frequent saves (catch issues faster)

MCP Connection Config

The file ~/.claude/plugins/memory/.mcp.json (or the project-level equivalent) 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