Claude Code: Migrating 15 months of project memory

Symptom: Project memories stored in ~/.claude/projects/ are tied to a specific machine, preventing context sharing across devices.

Cause: Memories rely on absolute path slugs for folder names and contain OS-specific filename encoding (CP949).

Fix: Use a custom Python script to prune secrets, consolidate memories into one file, and decode filenames during extraction.

I've been using Claude Code on my work laptop for 15 months, starting June 17, 2025. Over time, this grew into a massive knowledge base: 46 project folders and 680 automated memory files. These cover everything from internal inventory dashboards and mixing record systems to a desktop PDF editor, alongside my Obsidian second brain. The problem was that all this context lived exclusively in ~/.claude/projects/ on one laptop; my Mac Mini at home was completely clueless about this history.

Claude Code: Migrating 15 months of project memory

To move this "brain," I wrote a 221-line Python script to package the memories into a zip file. Since the code itself is handled via git, I focused only on the memory files: the global CLAUDE.md and settings.json, 46 project-specific memory folders (including their internal CLAUDE.md files), operational docs, scripts, and agent cron lists. To make it efficient for the receiving Claude, I also generated ALL-MEMORIES.md (2.2MB), which concatenates all 680 memory files into one, rather than forcing the AI to open hundreds of small files. The final package was 4.8MB, expanding to 1,594 files (15MB) when extracted.

Scrubbing secrets and handling the "slug" trap

Security was a priority. My script filtered out files like auth.json, google_token.json, .env, and session/chat histories by filename. For secrets embedded within the text, I used regex to replace values following key, token, secret, password, or webhook with *REDACTED*. A final scan flagged four suspicious strings, which turned out to be placeholders (e.g., ghp_xxxx, sk-xxxx) in skill documentation. I listed these specific locations in a HANDOFF.md file so the receiving Claude could verify them immediately.

However, there is a structural trap: Claude Code uses project paths as folder names. For example, C:\X\IRMS becomes C--X-IRMS, and desktop projects become C--Users-username-Desktop-.... If the path on the new machine differs—especially if the username changes—Claude won't find the memories. You must either replicate the exact path or manually rename the folders. I realized this after the migration and marked it in bold under step 2 of the HANDOFF.md instructions.

Solving Mac unzip corruption

The most frustrating part was extracting the Windows-created zip on macOS. Because the filenames were encoded in CP949, the Mac unzip utility failed, producing corrupted names like 0. ۦ+�� �ة�����.md and eventually crashing with a write error.

Instead of searching for a different GUI tool, I used Python's zipfile module to fix the encoding. By iterating through the archive and decoding names that lacked the UTF-8 flag, I could restore them using:

name.encode('cp437').decode('cp949')

This ten-line fix successfully recovered all 1,594 files with their original Korean filenames intact.

Restoring the context on Mac Mini

Once the files were moved, I sent the zip to Claude on my Mac Mini via Discord. After asking if it could use the package as a resource, Claude extracted the files and analyzed HANDOFF.md and the consolidated memory file. It correctly reported:

  • 46 projects total.
  • Memory breakdown: 159 feedback, 261 project, 35 reference, and 21 user memories.
  • Date range: 2025-06-17 to 2026-09-16.

Interestingly, based on a note I left in HANDOFF.md regarding company confidentiality, Claude proactively suggested omitting specific company names and unit prices from any public write-ups of this process.

If you plan to migrate your Claude Code history, remember that memories are strictly bound to file paths and can harbor hidden secrets. Also, be wary of the legacy Windows-to-Mac filename encoding issue. Address these three points, and you can port over years of project context in one go.

Related posts

This post is the English edition of a Korean write-up: 원문 보기

Comments

Post a Comment

Popular posts from this blog

npm command not found on Windows: fix the PATH

Image
I recently hit a wall while configuring my development environment on Windows. It's one of those subtle issues that can waste an afternoon if you don't know what to look for. Here's exactly how I diagnosed and fixed a 'command not found' error after a successful global install. The Problem I decided to add a markdown processing tool to my toolkit by running: npm install -g markdown-it-cli The terminal output confirmed the installation succeeded, displaying a message about added packages. Satisfied, I tried to use it by typing markdown-it-cli in the command line. Windows immediately responded with: 'markdown-it-cli is not recognized as an internal or external command, operable program or batch file.' This error means Windows looked through every folder in its search list and couldn't find an executable with that name. Attempts and Failures My initial reaction was to suspect the package itself might be broken. I tried running it using npx , wh...
Read more

Claude CLI 401 Unauthorized Refresh Token Issue

Symptom: claude commands fail with 401 Unauthorized and the message "refresh token was already used. Please log out and sign in again." Cause: The refresh token expired after being consumed by another session or a background process. Refresh tokens are single-use credentials. Fix: Run claude auth login to refresh authentication without running a logout command first. Why claude login alone did not clear the 401 I was running a pipeline command when every subsequent CLI call failed. The terminal returned this exact output: Error: 401 Unauthorized Message: "Authentication failed: refresh token was already used. Please log out and sign in again." Code: "AUTH_ERROR" The error text explicitly instructs me to log out. I spent roughly ten minutes searching the terminal for a logout function. The prompt only showed AUTH_ERROR . I assumed clearing old sessions was required first. That assumption blocked progress. The instructions in the error message ...
Read more

Tailscale without sudo: what userspace mode actually costs you

At first, I installed Tailscale on macOS knowing I did not have admin rights to write to system directories. The CLI package installed cleanly enough, landing entirely within my user space without triggering any permission errors or requiring elevated prompts. The installation process felt seamless, but the friction appeared immediately during usage. Every single command I typed required appending --socket=$HOME/.tailscale/tailscaled.sock to talk to the daemon. I found myself adding this flag to status checks, key generation, and connection queries across multiple sessions. The repetition was exhausting for a tool I expected to run in the background, turning routine operations into a chore. I eventually wrote a shell function to wrap this flag, allowing me to call tailscale directly without typing the socket path every time. This workaround saved my sanity but highlighted that userspace mode demands extra configuration just to use the CLI, and any automation scripts I maintained had...
Read more