claude-code-vault

A drop-in template for backing up the durable parts of Claude Code's configuration so it survives a reformat or new machine.

What it backs up:

• ~/.claude/settings.json — global Claude Code settings
• ~/.claude/skills/ — your user-level skills
• ~/.claude/projects/<encoded>/memory/ — per-project memory (the irreplaceable part: MEMORY.md + feedback/project/reference notes)
• A snapshot of your installed plugins manifest

What it intentionally does not back up:

• Session transcripts (~hundreds of MB of .jsonl, regenerable)
• Caches, runtime state, telemetry
• Per-repo .claude/settings.local.json (lives in each repo)

The mechanism: bootstrap moves your existing ~/.claude/ data into the vault repo and symlinks it back. Future memory writes from Claude land directly in the vault, where git tracks them.

---

First-time setup

1. Create your own private repo from this template

Click the green "Use this template" button at the top of this repo, then choose "Create a new repository". Make it private — your memories include feedback you've given Claude across projects, which is personal-ish and definitely should not be public.

2. Clone your new repo

git clone git@github.com:YOUR-USERNAME/YOUR-REPO.git ~/dotfiles

(~/dotfiles is conventional. Pick a different name if you prefer — e.g. ~/claude-vault. Just be consistent across machines.)

3. Preview what bootstrap will do

~/dotfiles/bootstrap.sh --dry-run

This prints every action it would take without changing anything. Read the output. If it tries to do something concerning (overwrite an unfamiliar file, link a path you don't recognize), stop and inspect.

4. Run bootstrap for real

~/dotfiles/bootstrap.sh

It will:

• Move existing ~/.claude/settings.json into the vault, symlink it back
• Move ~/.claude/skills/ into the vault, symlink it back
• For each ~/.claude/projects/<encoded>/ that has a memory/ dir, move it into the vault and symlink it back
• Snapshot your plugin manifest into the vault (copy, not symlink)
• Run link-worktree-memory.sh to point any existing worktree memory dirs at their parent repo's memory

It is idempotent and safe: it never overwrites a non-symlink file. If it sees something it doesn't expect, it warns and leaves the file alone.

5. Commit and push

cd ~/dotfiles
git add -A
git commit -m "Initial vault setup"
git push

Your Claude Code config is now backed up. Every memory Claude saves from here on lands in your vault automatically.

---

Subsequent machines

Same flow as above, in this order:

git clone git@github.com:YOUR-USERNAME/YOUR-REPO.git ~/dotfiles
~/dotfiles/bootstrap.sh

Bootstrap detects an empty ~/.claude/ and creates symlinks pointing into the vault data you already have. Your previous machine's memories light up immediately.

---

Day-to-day

Memory writes flow into the vault automatically

When Claude saves a new memory in any project, it's writing through the symlink, so the change shows up in git status inside ~/dotfiles/. Commit when you want a checkpoint:

cd ~/dotfiles
git add -A
git commit -m "memory updates"
git push

After installing or removing a Claude plugin

The plugin manifest is a snapshot copy, not a symlink (so plugin churn doesn't dirty the repo). Refresh manually after changes:

cp ~/.claude/plugins/installed_plugins.json  ~/dotfiles/claude/plugins-manifest/
cp ~/.claude/plugins/known_marketplaces.json ~/dotfiles/claude/plugins-manifest/
cd ~/dotfiles && git add -A && git commit -m "plugin manifest update" && git push

After creating a git worktree

If you use git worktree for parallel branches under a <repo>/.claude/worktrees/<name> path, each worktree gets its own Claude project entry with empty memory by default. Run the linker so the worktree inherits parent memory:

~/dotfiles/claude/link-worktree-memory.sh

Idempotent. Safe to re-run anytime. Won't overwrite a worktree that already has its own memory files.

Periodic memory pruning (recommended quarterly)

Memory accumulates stale entries: completed projects, dead worktree references, redundant feedback. Ask Claude to audit your claude/memory/<project>/ directories and propose deletions; you approve, Claude deletes, you commit.

Stale memory is worse than no memory because Claude will confidently apply outdated guidance. Pruning takes ~15 minutes every few months.

---

Memory paths and why they matter

Memory is per-project, scoped by an encoded version of the project's absolute path:

~/Dev/myrepo  →  ~/.claude/projects/-Users-myname-Dev-myrepo/

The encoding rule: replace / and . with -. So the encoded path depends on the absolute filesystem location.

Practical consequences:

• Keep the same username across machines (or accept rename work)
• Keep repos under a consistent root (e.g. ~/Dev/)
• Don't move repos to non-canonical locations

If you must move a repo, rename the matching directory under claude/memory/<encoded-path>/ to match the new path.

---

Instructions for Claude on a fresh machine

Claude: if the user has pointed you at this repo on a new machine, you can execute the steps below directly. The user has authorized you to set up symlinks via bootstrap.sh. Do not commit or push anything during first install.

Pre-flight checks

1. Confirm Claude Code is installed (which claude should resolve).
2. Confirm the user's $HOME is consistent with the encoded paths in claude/memory/. If not, warn the user — memory dirs may need renaming to match the new home path.
3. Confirm ~/.claude/ exists. If not: mkdir -p ~/.claude/projects.

Restore steps

# Already cloned; just bootstrap
~/dotfiles/bootstrap.sh --dry-run    # preview
~/dotfiles/bootstrap.sh              # apply

Post-restore verification

readlink ~/.claude/settings.json    # should print path under ~/dotfiles
readlink ~/.claude/skills           # should print path under ~/dotfiles
ls ~/.claude/projects/              # each existing project's memory subdir should be a symlink

If any verification fails, do not "fix" by deleting files — investigate first. The user may have written new state in this session that needs to be merged.

Plugins

Plugin manifest snapshot is at claude/plugins-manifest/installed_plugins.json. Plugins themselves must be reinstalled via Claude Code's plugin install flow (this repo only stores the list). Tell the user which plugins to reinstall; do not try to install them via shell.

---

What's next?

This template handles the durable parts of ~/.claude/ so a reformat doesn't blow away your config and memory. A few common follow-ons people pair with it:

• Personal Obsidian vault for notes and meetings. Install Obsidian (free), make the vault folder a private GitHub repo, and use the Granola Sync community plugin to pipe meeting notes into markdown that Claude Code can read. Solves the "where does my knowledge live" problem with a flat-file vault that survives any tool change.
• A second-brain vault repo, kept separate from this one. This template is for tool config; vaults are for content. They have very different commit cadences and privacy needs — keep them apart.
• Periodic memory pruning. Memory files accumulate stale entries (completed projects, dead worktrees, redundant feedback). Quarterly review takes ~15 minutes and keeps Claude calibrated against current reality. Just point Claude at claude/memory/ and ask it to propose deletions; you approve.

These are all optional and orthogonal to this repo — pick what fits your stack.

---

Sandbox testing (for contributors)

The bootstrap honors CLAUDE_HOME and VAULT_ROOT environment variables, so you can run it against a fake home in /tmp/ to verify behavior without touching your real ~/.claude/. See test/run-sandbox-test.sh.

---

License

MIT.