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 them from Claude Code session transcripts:

# Dry run (preview what would be recovered)
cd <plugin-dir>/server
./venv/bin/python tools/replay_sessions.py

# Apply recovery
./venv/bin/python tools/replay_sessions.py --apply

This scans ~/.claude/projects/ JSONL session files for kg_put_node and kg_put_edge calls and reconstructs the graph data.

Legacy Data Migration

If you're upgrading from a version that stored data in .claude/knowledge/:

cd <plugin-dir>/server
./venv/bin/python tools/migrate_storage.py        # Dry run
./venv/bin/python tools/migrate_storage.py --apply # Apply migration

Migration runs automatically on first server start if centralized storage is empty but legacy data exists.

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.