Data and Backup

Data and Backup

File Locations

All data is stored centrally in ~/.knowledge-graph/ (git-tracked by default):

Data	Path	Scope
User graph	~/.knowledge-graph/user.json	Global, all projects
Project graphs	~/.knowledge-graph/projects/<slug>/graph.json	Per-project
Sessions	~/.knowledge-graph/sessions.json	Active session tracking
Server logs	/tmp/mcp_server.log	Ephemeral
Server PID	...server/.mcp_server.pid	Runtime

The <slug> is derived from the project directory name (last path component). For example, /home/user/DevProj/my-app → my-app.

Graph File Format

Both user and project graphs use the same JSON structure:

{
  "nodes": {
    "node-id": {
      "id": "node-id",
      "gist": "Short description",
      "notes": ["additional context"],
      "touches": ["related/file.py"],
      "_archived": true,
      "_orphaned_ts": 1706000000.0
    }
  },
  "edges": {
    "source->target:relationship": {
      "from": "source",
      "to": "target",
      "rel": "relationship",
      "notes": ["edge context"]
    }
  },
  "_meta": {
    "versions": {
      "node:node-id": {"v": 3, "ts": 1706000000.0, "session": "abc12345"}
    },
    "progress": {
      "scout": {"last_ts": 1706000000, "sessions_reviewed": ["xyz"]}
    }
  }
}

• _archived and _orphaned_ts are optional flags on nodes
• _meta.versions tracks change history for sync
• _meta.progress stores persistent task state (scout, extract)

Write-Through Persistence

Every mutation (kg_put_node, kg_put_edge, kg_delete_*, kg_read with archived node promotion) saves to disk immediately via atomic write. No data loss on crash or unexpected termination.

Atomic Writes

All saves use atomic writes to prevent corruption:

1. Write to <file>.tmp
2. fsync to ensure data hits disk
3. rename temp to final path (POSIX atomic operation)

If the process crashes mid-write, the temp file is left behind and cleaned up on next save attempt.

Backup Tiers

The system creates tiered backups automatically:

Tier	Files	Retention	Interval
Recent	.json.bak.1, .bak.2, .bak.3	3 copies	Minimum 1 hour apart
Daily	.json.bak.daily.1 through .bak.daily.7	7 days	Once per day
Weekly	.json.bak.weekly.1 through .bak.weekly.4	4 weeks	Once per week

Backups rotate: when a new backup is created at a tier, the oldest at that tier is promoted to the next tier (if eligible).

Recovery

Choose the appropriate backup based on when the issue occurred:

# Recent (last few hours)
cp ~/.knowledge-graph/user.json.bak.1 ~/.knowledge-graph/user.json

# Yesterday
cp ~/.knowledge-graph/user.json.bak.daily.1 ~/.knowledge-graph/user.json

# Last week
cp ~/.knowledge-graph/user.json.bak.weekly.2 ~/.knowledge-graph/user.json

# Same for project graphs
cp ~/.knowledge-graph/projects/<slug>/graph.json.bak.1 ~/.knowledge-graph/projects/<slug>/graph.json

After restoring, restart the MCP server (or start a new Claude Code session) to reload from disk.

Data Recovery from Session History

If graph files are lost entirely, you can reconstruct knowledge from Claude Code conversation history using the kg-scout skill. Scout scans ~/.claude/projects/ JSONL session files for past decisions, preferences, and patterns and rebuilds knowledge graph entries from them.

/skill kg-scout

Scout uses a tension-driven approach — it scans session metadata first and only deep-dives into sessions that show signals of useful knowledge (decisions, corrections, recurring patterns). See Skills Reference for details.

Claude Code Session History Retention

Claude Code stores full conversation transcripts as JSONL files in ~/.claude/projects/. These files are the raw material that kg-scout mines for knowledge recovery — and they're also the archive that lets you trace back any decision or insight from past sessions.

By default, Claude Code deletes session files older than 30 days at startup, controlled by the cleanupPeriodDays setting.

Why this matters: If you rely on kg-scout to recover or fill gaps in your knowledge graph, a 30-day window limits how far back it can reach. Extending this gives you a longer recovery window and richer history for mining.

Recommended: set it to 90 days (or whatever matches your working style):

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 90
}

You can also use /config in Claude Code's interactive REPL to set this via the Settings UI.

Note: Session files can grow large over time. At 90 days with active use, expect a few hundred MB in ~/.claude/projects/. The knowledge graph itself stays compact — scout extracts the signal and discards the noise.

Git Tracking

The ~/.knowledge-graph/ directory is initialized as a git repository. The server auto-commits changes on stop (throttled to once per 10 minutes).

# Manual commit
kg-memory commit

# View history
cd ~/.knowledge-graph && git log --oneline

This provides version history for all graph data across all projects.

Manual Editing

Graph files are plain JSON — you can edit them with any text editor. This is intentional.

Safe edits:

• Delete a node: remove its entry from nodes and any edges referencing it
• Edit a gist or notes: modify the text directly
• Unarchive: delete the _archived key from a node

Note: With write-through persistence, the server saves on every mutation. If you edit files while the server is running, use the visual editor or restart the server after manual edits to reload from disk.

Data Size

Typical graph sizes:

• Small project: 5-20 nodes, 10-30 edges, ~2-5 KB on disk
• Medium project: 20-50 nodes, 30-80 edges, ~10-30 KB on disk
• Active user graph after months: 30-100 nodes, ~15-50 KB on disk

The 3000-token compaction limit keeps the active graph small. Archived nodes stay on disk but don't count toward the limit.