Two files and a directory
Claude Code doesn't pretend the amnesia isn't there. It ships with two mechanisms for pushing back on it.
The first is CLAUDE.md, a markdown file of standing instructions that gets prepended to context. Mine holds coding principles, a rule about where documentation is allowed to live, and a section describing the memory system itself.
The second is file-based memory: a directory of markdown files where each file holds one fact, with a little YAML frontmatter naming it and describing what it's for.
---
name: vpn-gated-servers
description: hostinger & sigHunt need Surfshark dedicated IP before SSH
metadata:
type: project
---
Both boxes filter SSH by source IP. Connect the Surfshark dedicated
endpoint before any ssh/scp/rsync, or the connection times out with
no useful error. See [[workstation-setup]] for the key layout.
Alongside them sits MEMORY.md, a flat index of one-line pointers that gets loaded into context at the start of every session, so Claude knows what exists without reading all of it.
On this laptop that directory currently holds 25 files and about 6,900 words. The contents are exactly the kind of thing a repository can't tell you: that two of my servers drop SSH unless the VPN's dedicated IP is up, that a branch with a real fix on it exists on one machine and nowhere else, that a set of files in ~/Documents are zero-filled and recoverable from a specific OneDrive folder. None of that is derivable from code or Git history. All of it is expensive to rediscover.
For a single project on a single machine, this is a good system, and I want to be clear about that before I take it apart. It's plain markdown. It opens in your editor. It diffs in Git. There is no server to keep alive and nothing to debug at two in the morning.
Then I started working across three machines.
The path is the address
File memory lives at ~/.claude/projects/<encoded-cwd>/memory/. That middle path segment is your working directory with the slashes flattened. Sessions I start from my home directory read and write here:
/home/michael/.claude/projects/-home-michael/memory/
The working directory is part of the address. Start Claude one folder over, in a specific repository, and you're pointed at a different directory that is usually empty. My laptop has four of these project directories and only three contain any memory at all, which is a fair description of how it goes: you accumulate context wherever you happened to be standing, and then you stand somewhere else.
You can work around it by always starting from the same place. I did that for a while. It means your memory about a repository lives at an address that has nothing to do with the repository, and the moment you forget the convention you start a session with nothing.
Two homes, no shared path
The harder version of the same problem is the one that has no workaround.
My laptop runs as /home/michael. My VPS runs as /home/rdpuser. When a session on the server learned something worth keeping, it wrote to /home/rdpuser/.claude/projects/-home-rdpuser/memory/, a path that does not exist on my laptop and never will.
I could have synced the directories. I tried a version of that, and it fails on the same rock the encoded path already established: the directory names don't match, so a sync either flattens two different memory stores into one or maintains two stores that disagree. Neither is memory. Both are a merge conflict waiting for a moment when you're busy.
This one mattered more than it sounds, because the split ran along the most useful line. The server does the deploys and holds production. The laptop does the planning and most of the writing. The context each one accumulates is precisely the context the other one needs.
Retrieval by guessing the title
The index Claude reads at session start is a list like this:
- [VPN-gated servers](vpn-gated-servers.md) — hostinger & sigHunt need
Surfshark dedicated IP before SSH
- [pkexec sudo prompt](pkexec-sudo-prompt.md) — use pkexec GUI dialog for
root on MPx-Bit instead of sudo paste-blocks
Retrieval means scanning those hooks and picking one. At 25 entries that works. It works because I wrote them and I remember roughly what's in there.
The failure is quieter than a missing file. Ask "how do I get root on this machine without pasting a password into a terminal" and the pkexec memory surfaces only if the hook line happens to share vocabulary with the question. Write the hook as "GUI auth for privileged commands" and the same question sails straight past it. There's no ranking, no notion of similarity, nothing that gets you from the words you used to the words you used six weeks ago.
It also grows in one direction. Nothing expires. Nothing gets superseded. Every session pays the token cost of the full index whether or not any of it is relevant, and the index only ever gets longer.
The instruction that doesn't always fire
The fourth failure is the one I'd argue about with anyone who hasn't hit it.
My CLAUDE.md is 846 words. It contains this, in capitals, near the top of the memory section: when you receive the first user message in a session, always search memory before responding.
Claude reads it. Claude will tell you it read it. And then, some fraction of the time, it answers the question directly without searching, because nothing in the machinery makes the instruction fire. It's text in the context window competing with all the other text in the context window, and on a turn where the user's question looks self-contained it loses.
I want to be careful about how strong a claim I make here, because I never instrumented it and I can't give you a percentage. What I can say is that the failure rate was high enough that I stopped trusting it and started typing an explicit /start command at the beginning of every session instead. An invoked command runs. A described rule is a hope with good formatting.
This is the failure that generalises furthest beyond memory. Anything you need to happen every time belongs in something that executes, whether that's a command, a hook, or a script. Prose in a config file is documentation of an intention.
The stopgap: handing off through the repo
What I actually did, before building anything, was write handoff documents.
At the end of a session I'd have Claude write down where things stood, what was half-finished, and what the next step was, then commit it to the repository. The next session, possibly on the other machine, pulled and read it. Git was already installed on both boxes, already authenticated, already the thing I moved code with. Using it to move context cost nothing extra.
It worked. It worked well enough that I ran it for weeks, and well enough that when a remote MCP server broke and the two machines that needed to fix it had no shared terminal between them, a handoff document in a repository was the only channel they had. That episode is the next chapter, and it's the point where the workaround stopped being a workaround and turned into a genuine coordination protocol.
It also had an obvious ceiling. Somebody has to write the handoff, every time, and the somebody is you at the end of a session when you want to stop. What gets captured is whatever you thought to mention. Six weeks later the document is buried in the log of a repository you may not be in, and there's still no way to ask a question and get the three relevant paragraphs back.
What the failures specified
Taken together the four failures wrote most of the spec.
Storage could not be keyed to a local path, because the two machines that needed to share it disagreed about every path. Retrieval had to work on meaning rather than on filenames, because the whole point is recalling something you've forgotten the title of. Whatever loaded the context had to be invoked rather than described, because described rules don't reliably run. And it needed a notion of relevance and age, so the store could grow past a few dozen entries without every session paying for all of it.
Read back now, that's a small remote service with embeddings and a slash command in front of it. At the time it was four separate annoyances that took a few weeks to recognise as one problem.
The memory files are still on my laptop, incidentally. I never deleted them. They hold 25 facts about this specific machine, which is the one job the design does well, and the index line that used to say "remember to check memory" now says which system is the real one.